TSDuck v3.46-4964
MPEG Transport Stream Toolkit
Loading...
Searching...
No Matches

#include <tsUString.h>

Inheritance diagram for ts::UString:
Collaboration diagram for ts::UString:

Classes

class  RegisterChronoUnit

Public Types

enum  HexaFlags {
  HEXA = 0x0001 ,
  ASCII = 0x0002 ,
  OFFSET = 0x0004 ,
  WIDE_OFFSET = 0x0008 ,
  SINGLE_LINE = 0x0010 ,
  BPL = 0x0020 ,
  C_STYLE = 0x0040 ,
  BINARY = 0x0080 ,
  BIN_NIBBLE = 0x0100 ,
  COMPACT = 0x0200
}
using SuperClass = std::u16string

Public Member Functions

 UString () noexcept(noexcept(allocator_type()))
 UString (const ::WCHAR *s, const allocator_type &alloc=allocator_type())
 UString (const ::WCHAR *s, size_type count, const allocator_type &alloc=allocator_type())
 UString (const allocator_type &alloc) noexcept
 UString (const char *utf8)
 UString (const char *utf8, size_type count)
 UString (const fs::path &p)
template<typename CHARTYPE, std::size_t SIZE>
 UString (const std::array< CHARTYPE, SIZE > &arr, const allocator_type &alloc=allocator_type())
template<typename CHARTYPE, std::size_t SIZE, typename INT>
requires std::integral<INT>
 UString (const std::array< CHARTYPE, SIZE > &arr, INT count, const allocator_type &alloc=allocator_type())
 UString (const std::string &utf8)
template<typename CHARTYPE>
 UString (const std::vector< CHARTYPE > &vec, const allocator_type &alloc=allocator_type())
template<typename CHARTYPE, typename INT>
requires std::integral<INT>
 UString (const std::vector< CHARTYPE > &vec, INT count, const allocator_type &alloc=allocator_type())
 UString (const SuperClass &other)
 UString (const SuperClass &other, size_type pos, size_type count, const allocator_type &alloc=allocator_type())
 UString (const UChar *s, const allocator_type &alloc=allocator_type())
 UString (const UChar *s, size_type count, const allocator_type &alloc=allocator_type())
template<class InputIt>
 UString (InputIt first, InputIt last, const allocator_type &alloc=allocator_type())
 UString (size_type count, UChar ch, const allocator_type &alloc=allocator_type())
 UString (std::initializer_list< UChar > init, const allocator_type &alloc=allocator_type())
 UString (SuperClass &&other) noexcept
void appendDump (const ByteBlock &bb, uint32_t flags=HEXA, size_type indent=0, size_type line_width=DEFAULT_HEXA_LINE_WIDTH, size_type init_offset=0, size_type inner_indent=0)
void appendDump (const void *data, size_type size, uint32_t flags=HEXA, size_type indent=0, size_type line_width=DEFAULT_HEXA_LINE_WIDTH, size_type init_offset=0, size_type inner_indent=0)
void appendUTF8 (ByteBlock &utf8) const
void appendUTF8 (std::string &utf8) const
template<typename CHARTYPE, std::size_t SIZE>
UString & assign (const std::array< CHARTYPE, SIZE > &arr)
template<typename CHARTYPE, std::size_t SIZE, typename INT>
requires std::integral<INT>
UString & assign (const std::array< CHARTYPE, SIZE > &arr, INT count)
template<typename CHARTYPE>
UString & assign (const std::vector< CHARTYPE > &vec)
template<typename CHARTYPE, typename INT>
requires std::integral<INT>
UString & assign (const std::vector< CHARTYPE > &vec, INT count)
UString & assignFromUTF8 (const char *utf8)
UString & assignFromUTF8 (const char *utf8, size_type count)
UString & assignFromUTF8 (const std::string &utf8)
UString & assignFromWChar (const std::wstring &wstr)
UString & assignFromWChar (const wchar_t *wstr)
UString & assignFromWChar (const wchar_t *wstr, size_type count)
void combineDiacritical ()
size_t commonPrefixSize (const UString &str, CaseSensitivity cs=CASE_SENSITIVE) const
size_t commonSuffixSize (const UString &str, CaseSensitivity cs=CASE_SENSITIVE) const
int constantTimeCompare (const UString &secret) const
bool contains (const UString &substring, CaseSensitivity cs=CASE_SENSITIVE) const
bool contains (UChar c) const
void convertFromHTML ()
void convertFromJSON ()
void convertToHTML (const UString &convert=UString())
void convertToJSON ()
void convertToLower ()
void convertToUpper ()
void decomposeDiacritical ()
size_type displayPosition (size_type count, size_type from=0, StringDirection direction=LEFT_TO_RIGHT) const
bool ends_with (const std::u16string_view &suffix, CaseSensitivity cs=CASE_SENSITIVE, bool skip_spaces=false, size_type end=NPOS) const
bool ends_with (const UChar *suffix, CaseSensitivity cs=CASE_SENSITIVE, bool skip_spaces=false, size_type end=NPOS) const
bool ends_with (const UString &suffix, CaseSensitivity cs=CASE_SENSITIVE, bool skip_spaces=false, size_type end=NPOS) const
bool ends_with (UChar suffix, CaseSensitivity cs=CASE_SENSITIVE, bool skip_spaces=false, size_type end=NPOS) const
template<class CONTAINER>
CONTAINER::const_iterator findSimilar (const CONTAINER &container, size_t this_pos=0) const
template<class... Args>
void format (const UChar *fmt, Args &&... args)
template<class... Args>
void format (const UString &fmt, Args &&... args)
UString fromHTML () const
UString fromJSON () const
template<class CONTAINER>
void fromQuotedLine (CONTAINER &container, const UString &quote_characters=DEFAULT_QUOTE_CHARACTERS, const UString &special_characters=DEFAULT_SPECIAL_CHARACTERS) const
bool getLine (std::istream &strm)
bool hexaDecode (ByteBlock &result, bool c_style=false) const
bool hexaDecodeAppend (ByteBlock &result, bool c_style=false) const
void indent (size_t size)
template<class CONTAINER>
bool isContainedSimilarIn (const CONTAINER &container, size_t this_pos=0) const
bool isInteger (const UString &thousand_separators=UString()) const
template<class CONTAINER>
UString join (const CONTAINER &container, bool remove_empty=false) const
template<class ITERATOR>
UString join (ITERATOR begin, ITERATOR end, bool remove_empty=false) const
void justify (const UString &right, size_type width, UChar pad=SPACE, size_t spaces_around_pad=0)
void justifyCentered (size_type width, UChar pad=SPACE, bool truncate=false, size_t spaces_around_pad=0)
void justifyLeft (size_type width, UChar pad=SPACE, bool truncate=false, size_t spaces_before_pad=0)
void justifyRight (size_type width, UChar pad=SPACE, bool truncate=false, size_t spaces_after_pad=0)
UChar * last ()
const UChar * last () const
 operator fs::path () const
bool operator== (const fs::path &other) const
void quoted (UChar quote_character=u'\'', const UString &special_characters=DEFAULT_SPECIAL_CHARACTERS, bool force_quote=false, UChar non_print=u'?')
template<class CONTAINER>
void quotedLine (const CONTAINER &container, UChar quote_character=u'\'', const UString &special_characters=DEFAULT_SPECIAL_CHARACTERS)
void remove (const UString &substr)
void remove (UChar c)
void removePrefix (const UString &prefix, CaseSensitivity cs=CASE_SENSITIVE)
void removeSuffix (const UString &suffix, CaseSensitivity cs=CASE_SENSITIVE)
void reverse ()
bool save (const fs::path &file_name, bool append=false, bool enforce_last_line_feed=false) const
template<class... Args>
bool scan (const UChar *fmt, Args &&... args) const
template<class... Args>
bool scan (const UString &fmt, Args &&... args) const
template<class... Args>
bool scan (size_t &extracted_count, size_type &end_index, const UChar *fmt, Args &&... args) const
template<class... Args>
bool scan (size_t &extracted_count, size_type &end_index, const UString &fmt, Args &&... args) const
bool similar (const UChar *other, size_t this_pos=0, size_t other_pos=0) const
bool similar (const UString &other, size_t this_pos=0, size_t other_pos=0) const
bool similar (const void *addr, size_type size, size_t this_pos=0, size_t other_pos=0) const
bool similarAfterLast (const UChar *other, UChar separator) const
bool similarAfterLast (const UString &other, UChar separator) const
bool similarAfterLast (const void *addr, size_type size, UChar separator) const
template<class CONTAINER>
void split (CONTAINER &container, UChar separator=COMMA, bool trim_spaces=true, bool remove_empty=false) const
template<class CONTAINER>
void splitAppend (CONTAINER &container, UChar separator=COMMA, bool trim_spaces=true, bool remove_empty=false) const
template<class CONTAINER>
void splitBlocks (CONTAINER &container, UChar starts_with=u'[', UChar ends_with=u']', bool trim_spaces=true) const
template<class CONTAINER>
void splitBlocksAppend (CONTAINER &container, UChar starts_with=u'[', UChar ends_with=u']', bool trim_spaces=true) const
template<class CONTAINER>
void splitLines (CONTAINER &container, size_type max_width, const UString &other_separators=UString(), const UString &next_margin=UString(), bool force_split=false) const
template<class CONTAINER>
void splitLinesAppend (CONTAINER &container, size_type max_width, const UString &other_separators=UString(), const UString &next_margin=UString(), bool force_split=false) const
template<class CONTAINER>
void splitShellStyle (CONTAINER &container) const
template<class CONTAINER>
void splitShellStyleAppend (CONTAINER &container) const
bool starts_with (const std::u16string_view &prefix, CaseSensitivity cs=CASE_SENSITIVE, bool skip_spaces=false, size_type start=0) const
bool starts_with (const UChar *prefix, CaseSensitivity cs=CASE_SENSITIVE, bool skip_spaces=false, size_type start=0) const
bool starts_with (const UString &prefix, CaseSensitivity cs=CASE_SENSITIVE, bool skip_spaces=false, size_type start=0) const
bool starts_with (UChar prefix, CaseSensitivity cs=CASE_SENSITIVE, bool skip_spaces=false, size_type start=0) const
void substitute (const UString &value, const UString &replacement)
void substitute (UChar value, UChar replacement)
int superCompare (const UChar *other, uint32_t flags=SCOMP_DEFAULT, size_t this_pos=0, size_t other_pos=0) const
int superCompare (const UString &other, uint32_t flags=SCOMP_DEFAULT, size_t this_pos=0, size_t other_pos=0) const
bool toBool (bool &value) const
template<class Rep, class Period>
bool toChrono (cn::duration< Rep, Period > &value, const UString &thousand_separators=UString(), const cn::duration< Rep, Period > &min_value=cn::duration< Rep, Period >::min(), const cn::duration< Rep, Period > &max_value=cn::duration< Rep, Period >::max()) const
UString toCombinedDiacritical () const
UString toDecomposedDiacritical () const
template<typename FLT>
requires std::floating_point<FLT>
bool toFloat (FLT &value, FLT min_value=std::numeric_limits< FLT >::lowest(), FLT max_value=std::numeric_limits< FLT >::max()) const
UString toHTML (const UString &convert=UString()) const
UString toIndented (size_t size) const
template<typename INT>
requires std::integral<INT>
bool toInteger (INT &value, const UString &thousand_separators=UString(), size_type decimals=0, const UString &decimal_separators=u".", INT min_value=std::numeric_limits< INT >::min(), INT max_value=std::numeric_limits< INT >::max()) const
template<class CONTAINER>
requires std::integral<typename CONTAINER::value_type>
bool toIntegers (CONTAINER &container, const UString &thousand_separators=UString(), const UString &list_separators=UString(u",; "), size_type decimals=0, const UString &decimal_separators=UString(u"."), typename CONTAINER::value_type min_value=std::numeric_limits< typename CONTAINER::value_type >::min(), typename CONTAINER::value_type max_value=std::numeric_limits< typename CONTAINER::value_type >::max()) const
UString toJSON () const
UString toJustified (const UString &right, size_type width, UChar pad=SPACE, size_t spaces_around_pad=0) const
UString toJustifiedCentered (size_type width, UChar pad=SPACE, bool truncate=false, size_t spaces_around_pad=0) const
UString toJustifiedLeft (size_type width, UChar pad=SPACE, bool truncate=false, size_t spaces_before_pad=0) const
UString toJustifiedRight (size_type width, UChar pad=SPACE, bool truncate=false, size_t spaces_after_pad=0) const
UString toLower () const
UString toQuoted (UChar quote_character=u'\'', const UString &special_characters=DEFAULT_SPECIAL_CHARACTERS, bool force_quote=false, UChar non_print=u'?') const
UString toRemoved (const UString &substr) const
UString toRemoved (UChar c) const
UString toRemovedPrefix (const UString &prefix, CaseSensitivity cs=CASE_SENSITIVE) const
UString toRemovedSuffix (const UString &suffix, CaseSensitivity cs=CASE_SENSITIVE) const
UString toReversed () const
UString toSplitLines (size_type max_width, const UString &other_separators=UString(), const UString &next_margin=UString(), bool force_split=false, const UString &line_separator=UString(1, LINE_FEED)) const
UString toSubstituted (const UString &value, const UString &replacement) const
UString toSubstituted (UChar value, UChar replacement) const
UString toTrimmed (bool leading=true, bool trailing=true, bool sequences=false) const
bool toTristate (Tristate &value) const
UString toTruncatedWidth (size_type max_width, StringDirection direction=LEFT_TO_RIGHT) const
UString toUnquoted (const UString &quote_characters=DEFAULT_QUOTE_CHARACTERS) const
UString toUpper () const
std::string toUTF8 () const
void toUTF8 (ByteBlock &utf8) const
void toUTF8 (std::string &utf8) const
void trim (bool leading=true, bool trailing=true, bool sequences=false)
template<typename INT>
requires std::integral<INT>
void trimLength (INT length, bool trim_trailing_spaces=true)
void truncateWidth (size_type max_width, StringDirection direction=LEFT_TO_RIGHT)
void unquoted (const UString &quote_characters=DEFAULT_QUOTE_CHARACTERS)
::WCHAR * wc_str ()
const ::WCHAR * wc_str () const
size_type width () const

Static Public Member Functions

static UString AfterBytes (const std::streampos &position)
template<class CONTAINER>
static CONTAINER & Append (CONTAINER &container, int argc, char *const argv[])
template<class CONTAINER>
static CONTAINER & Append (CONTAINER &container, int argc, const char *const argv[])
template<class CONTAINER>
static CONTAINER & Assign (CONTAINER &container, int argc, char *const argv[])
template<class CONTAINER>
static CONTAINER & Assign (CONTAINER &container, int argc, const char *const argv[])
static UString BoolNamesList ()
template<class Rep, class Period>
static UString Chrono (const cn::duration< Rep, Period > &value, bool short_format=false, const UString &separator=DEFAULT_THOUSANDS_SEPARATOR, bool force_sign=false)
template<class DURATION>
requires std::integral<typename DURATION::rep>
static UString ChronoUnit (bool short_format=false, bool plural=false)
static UString ChronoUnit (std::intmax_t num, std::intmax_t den, bool short_format=false, bool plural=false)
static void ConvertUTF16ToUTF8 (const UChar *&in_start, const UChar *in_end, char *&out_start, char *out_end)
static void ConvertUTF8ToUTF16 (const char *&in_start, const char *in_end, UChar *&out_start, UChar *out_end)
template<class CONTAINER>
requires ts::int_enum<typename CONTAINER::value_type>
static UString Decimal (const CONTAINER &values, const UString &separator=UString(u", "), bool force_sign=false)
template<typename INT>
requires ts::int_enum<INT>
static UString Decimal (INT value, size_type min_width=0, bool right_justified=true, const UString &separator=DEFAULT_THOUSANDS_SEPARATOR, bool force_sign=false, UChar pad=SPACE)
static UString Dump (const ByteBlock &bb, uint32_t flags=HEXA, size_type indent=0, size_type line_width=DEFAULT_HEXA_LINE_WIDTH, size_type init_offset=0, size_type inner_indent=0)
static UString Dump (const void *data, size_type size, uint32_t flags=HEXA, size_type indent=0, size_type line_width=DEFAULT_HEXA_LINE_WIDTH, size_type init_offset=0, size_type inner_indent=0)
template<class Rep, class Period>
static UString Duration (const cn::duration< Rep, Period > &value, bool with_days=false)
static const UString & EMPTY ()
static const std::string & EMPTY8 ()
static UString Float (double value, size_type width=0, size_type precision=0, bool force_sign=false)
template<class... Args>
static UString Format (const UChar *fmt, Args &&... args)
template<class... Args>
static UString Format (const UString &fmt, Args &&... args)
static UString FromUTF8 (const char *utf8)
static UString FromUTF8 (const char *utf8, size_type count)
static UString FromUTF8 (const std::string &utf8)
static UString FromWChar (const std::wstring &wstr)
static UString FromWChar (const wchar_t *wstr)
static UString FromWChar (const wchar_t *wstr, size_type count)
template<typename INT>
requires std::integral<INT>
static UString Hexa (INT value, size_type width=0, const UString &separator=UString(), bool use_prefix=true, bool use_upper=true)
template<typename INT>
requires std::integral<INT>
static UString HexaMin (INT value, size_type min_width=0, const UString &separator=UString(), bool use_prefix=true, bool use_upper=true)
static UString HumanSize (int64_t value, const UString &units=u"B", bool force_sign=false)
template<class CONTAINER>
static UString Join (const CONTAINER &container, const UString &separator=UString(u", "), bool remove_empty=false)
template<class CONTAINER>
static UString Join (const CONTAINER &container, UChar separator, bool remove_empty=false)
template<class ITERATOR>
static UString Join (ITERATOR begin, ITERATOR end, const UString &separator=UString(u", "), bool remove_empty=false)
template<class ITERATOR>
static UString Join (ITERATOR begin, ITERATOR end, UChar separator, bool remove_empty=false)
template<class CONTAINER>
static bool Load (CONTAINER &container, const fs::path &file_name, size_t max_lines=NPOS)
template<class CONTAINER>
static bool Load (CONTAINER &container, std::istream &strm, size_t max_lines=NPOS)
template<class CONTAINER>
static bool LoadAppend (CONTAINER &container, const fs::path &file_name, size_t max_lines=NPOS)
template<class CONTAINER>
static bool LoadAppend (CONTAINER &container, std::istream &strm, size_t max_lines=NPOS)
static UString OnOff (bool b)
template<class Rep1, class Period1, class Rep2, class Period2>
static UString Percentage (const cn::duration< Rep1, Period1 > &value, const cn::duration< Rep2, Period2 > &total)
template<typename Int1, typename Int2>
requires std::integral<Int1> && std::integral<Int2>
static UString Percentage (Int1 value, Int2 total)
static UString Range (UChar first, UChar last)
template<class CONTAINER>
static bool Save (const CONTAINER &container, const fs::path &file_name, bool append=false)
template<class CONTAINER>
static bool Save (const CONTAINER &container, std::ostream &strm)
template<class ITERATOR>
static bool Save (ITERATOR begin, ITERATOR end, const fs::path &file_name, bool append=false)
template<class ITERATOR>
static bool Save (ITERATOR begin, ITERATOR end, std::ostream &strm)
static int SuperCompare (const UChar *s1, const UChar *s2, uint32_t flags=SCOMP_DEFAULT, size_t s1_pos=0, size_t s2_pos=0)
template<class CONTAINER>
static UString ToQuotedLine (const CONTAINER &container, UChar quote_character=u'\'', const UString &special_characters=DEFAULT_SPECIAL_CHARACTERS)
static UString TristateNamesList ()
static UString TristateOnOff (Tristate b)
static UString TristateTrueFalse (Tristate b)
static UString TristateYesNo (Tristate b)
static UString TrueFalse (bool b)
static UString YesNo (bool b)

Static Public Attributes

static constexpr size_type DEFAULT_HEXA_LINE_WIDTH = 78
static constexpr const UChar * DEFAULT_QUOTE_CHARACTERS = u"\"'"
static constexpr const UChar * DEFAULT_SPECIAL_CHARACTERS = u"\"'`;$*?&(){}[]"
static constexpr const UChar * DEFAULT_THOUSANDS_SEPARATOR = u","
static constexpr const UChar * EOL
static constexpr size_t MAX_FIELD_WIDTH = 4096
static constexpr const char * UTF8_BOM = "\xEF\xBB\xBF"
static constexpr size_type UTF8_BOM_SIZE = 3
static constexpr size_type UTF8_CHAR_MAX_SIZE = 4

Detailed Description

An implementation of UTF-16 strings.

This class is an extension of std::u16string with additional services.

The class UString implements Java-like Unicode strings. Each character uses 16 bits of storage. Formally, UString uses UTF-16 representation. This means that all characters from all modern languages can be represented as one single character. Characters from archaic languages may need two UTF-16 values, called a "surrogate pair".

The element of a UString is a UChar (or char16_t). Nul-terminated strings of UChar are implicitly converted to UString when necessary. Be aware that strings literals of char16_t are prefixed by a letter u as illustrated below:

ts::UString s1(u"abcd");
ts::UString s2 = s1 + u"efgh";
Definition tsUString.h:153

Some interesting features in class UString are:

  • Explicit and implicit(*) conversions between UTF-8 and UTF-16.
  • Including automatic conversion to UTF-8 when writing to text streams.
  • Conversions with HTML encoding.
  • Conversions with JSON encoding.
  • Management of "display width", that is to say the amount of space which is used when the string is displayed. This can be different from the string length in the presence of combining diacritical characters or surrogate pairs.
  • String padding, trimming, truncation, justification, case conversions.
  • Substring, prefix or suffix detection, removal or substitution.
  • Splitting and joining strings based on separators or line widths.
  • Reading or writing text lines from or to a text file.
  • Data formatting using Format(), Decimal(), Hexa() or Dump().
  • Data scanning using scan().

(*) Implicit conversions from UTF-8 C-strings (const char*) and std::string are disabled by default. You may enabled implicit conversions by defining TS_ALLOW_IMPLICIT_UTF8_CONVERSION before including tsUString.h. Thus, there is no need to explicitly invoke FromUTF8() all the time. However, leaving the implicit conversions disabled has some advantages like flagging useless and costly UTF-8 conversions, for instance when string literals are incorrectly spelled as illustrated below:

us = "efgh"; // only if implicit conversions are enabled
us = u"efgh"; // always ok and much faster
std::string s;
us = UString::FromUTF8(s); // always ok
us.assignFromUTF8(s); // always ok, probably faster
us = s; // only if implicit conversions are enabled
UString & assignFromUTF8(const std::string &utf8)
Definition tsUString.h:473
static UString FromUTF8(const std::string &utf8)

Warning for maintainers: The standard classes std::u16string and std::basic_string do not have virtual destructors. The means that if a UString is destroyed through, for instance, a std::u16string*, the destructor for the class UString will not be invoked. This is not a problem as long as the UString subclass does not have any field to destroy, which is the case for the current implementation. When modifying the UString class, make sure to avoid any issue with the absence of virtual destructor in the parent class.

Member Typedef Documentation

◆ SuperClass

using ts::UString::SuperClass = std::u16string

Explicit reference to superclass.

Member Enumeration Documentation

◆ HexaFlags

Flags for the Hexa() family of methods.

Enumerator
HEXA 

Dump hexa values.

ASCII 

Dump ascii values.

OFFSET 

Display address offsets.

WIDE_OFFSET 

Always wide offset.

SINGLE_LINE 

Hexa on one single line, no line feed, ignore other flags.

BPL 

Interpret max_line_width as number of displayed Bytes Per Line (BPL).

C_STYLE 

C-style hexa value(u"0xXX," instead of "XX").

BINARY 

Dump binary values ("XXXXXXXX" binary digits).

BIN_NIBBLE 

Binary values are grouped by nibble ("XXXX XXXX").

COMPACT 

Same as SINGLE_LINE but use a compact display without space.

Constructor & Destructor Documentation

◆ UString() [1/20]

ts::UString::UString ( )
inlinenoexcept

Default constructor.

◆ UString() [2/20]

ts::UString::UString ( const allocator_type & alloc)
inlineexplicitnoexcept

Constructor using an allocator.

Parameters
[in]allocAllocator.

◆ UString() [3/20]

ts::UString::UString ( const SuperClass & other)
inline

Copy constructor.

Parameters
[in]otherOther instance to copy.

◆ UString() [4/20]

ts::UString::UString ( SuperClass && other)
inlinenoexcept

Move constructor.

Parameters
[in,out]otherOther instance to move. Upon return, other is left in valid, but unspecified state.

◆ UString() [5/20]

ts::UString::UString ( size_type count,
UChar ch,
const allocator_type & alloc = allocator_type() )
inline

Constructor using a repetition of the same character.

Parameters
[in]countInitial size of the string.
[in]chCharacter to repeat count times.
[in]allocAllocator.

◆ UString() [6/20]

ts::UString::UString ( const SuperClass & other,
size_type pos,
size_type count,
const allocator_type & alloc = allocator_type() )
inline

Constructor using a substring. The object receives the substring other [pos, pos + count). If count == npos or if the requested substring lasts past the end of the string, the resulting substring is [pos, size()).

Parameters
[in]otherOther instance to partially copy.
[in]posInitial position to copy in other.
[in]countNumber of character to copy.
[in]allocAllocator.

◆ UString() [7/20]

ts::UString::UString ( const UChar * s,
size_type count,
const allocator_type & alloc = allocator_type() )
inline

Constructor using a Unicode string.

Parameters
[in]sAddress of a string. Can be a null pointer if count is zero, in which case the string is empty.
[in]countNumber of characters to copy from s. That number of characters is always copied, including null characters.
[in]allocAllocator.

◆ UString() [8/20]

ts::UString::UString ( const UChar * s,
const allocator_type & alloc = allocator_type() )
inline

Constructor using a null-terminated Unicode string.

Parameters
[in]sAddress of a null-terminated string. Can be a null pointer, in which case the string is empty.
[in]allocAllocator.

◆ UString() [9/20]

template<typename CHARTYPE, typename INT>
requires std::integral<INT>
ts::UString::UString ( const std::vector< CHARTYPE > & vec,
INT count,
const allocator_type & alloc = allocator_type() )

Constructor using a std::vector of 16-bit characters of any type.

Template Parameters
CHARTYPEA 16-bit character or integer type.
INTAn integer type.
Parameters
[in]vecThe vector of characters.
[in]countMaximum number of characters to include in the string. Stop before the first nul character before max. Can be of any integer type, including a signed type.
[in]allocAllocator.

◆ UString() [10/20]

template<typename CHARTYPE>
ts::UString::UString ( const std::vector< CHARTYPE > & vec,
const allocator_type & alloc = allocator_type() )

Constructor using a std::vector of 16-bit characters of any type.

Template Parameters
CHARTYPEA 16-bit character or integer type.
Parameters
[in]vecThe vector of characters. Nul-terminated string.
[in]allocAllocator.

◆ UString() [11/20]

template<typename CHARTYPE, std::size_t SIZE, typename INT>
requires std::integral<INT>
ts::UString::UString ( const std::array< CHARTYPE, SIZE > & arr,
INT count,
const allocator_type & alloc = allocator_type() )

Constructor using a std::array of 16-bit characters of any type.

Template Parameters
CHARTYPEA 16-bit character or integer type.
SIZEThe size of the array.
INTAn integer type.
Parameters
[in]arrThe array of characters.
[in]countMaximum number of characters to include in the string. Stop before the first nul character before max. Can be of any integer type, including a signed type.
[in]allocAllocator.

◆ UString() [12/20]

template<typename CHARTYPE, std::size_t SIZE>
ts::UString::UString ( const std::array< CHARTYPE, SIZE > & arr,
const allocator_type & alloc = allocator_type() )

Constructor using a std::array of 16-bit characters of any type.

Template Parameters
CHARTYPEA 16-bit character or integer type.
SIZEThe size of the array.
Parameters
[in]arrThe array of characters. Nul-terminated string.
[in]allocAllocator.

◆ UString() [13/20]

template<class InputIt>
ts::UString::UString ( InputIt first,
InputIt last,
const allocator_type & alloc = allocator_type() )
inline

Constructor from iterators. Constructs the string with the contents of the range [first, @ last).

Template Parameters
InputItAn iterator type to containers of Char. If InputIt is an integral type, equivalent to String(static_cast<size_type>(first), static_cast<Char>(last), alloc).
Parameters
[in]firstIterator to the first position to copy.
[in]lastIterator after the last position to copy.
[in]allocAllocator.

◆ UString() [14/20]

ts::UString::UString ( std::initializer_list< UChar > init,
const allocator_type & alloc = allocator_type() )
inline

Constructor from an initializer list.

Parameters
[in]initInitializer list of Char.
[in]allocAllocator.

◆ UString() [15/20]

ts::UString::UString ( const ::WCHAR * s,
size_type count,
const allocator_type & alloc = allocator_type() )

Constructor using a Windows Unicode string (Windows-specific).

Parameters
[in]sAddress of a string. Can be a null pointer if count is zero, in which case the string is empty.
[in]countNumber of characters to copy from s. That number of characters is always copied, including null characters.
[in]allocAllocator.

◆ UString() [16/20]

ts::UString::UString ( const ::WCHAR * s,
const allocator_type & alloc = allocator_type() )

Constructor using a null-terminated Windows Unicode string (Windows-specific).

Parameters
[in]sAddress of a null-terminated string. Can be a null pointer, in which case the string is empty.
[in]allocAllocator.

◆ UString() [17/20]

ts::UString::UString ( const std::string & utf8)
inline

Constructor from an UTF-8 string. Available only when the macro TS_ALLOW_IMPLICIT_UTF8_CONVERSION is externally defined.

Parameters
[in]utf8A string in UTF-8 representation.

◆ UString() [18/20]

ts::UString::UString ( const char * utf8)
inline

Constructor from an UTF-8 string. Available only when the macro TS_ALLOW_IMPLICIT_UTF8_CONVERSION is externally defined.

Parameters
[in]utf8Address of a nul-terminated string in UTF-8 representation.

◆ UString() [19/20]

ts::UString::UString ( const char * utf8,
size_type count )
inline

Constructor from an UTF-8 string. Available only when the macro TS_ALLOW_IMPLICIT_UTF8_CONVERSION is externally defined.

Parameters
[in]utf8Address of a string in UTF-8 representation.
[in]countSize in bytes of the UTF-8 string (not necessarily a number of characters).

◆ UString() [20/20]

ts::UString::UString ( const fs::path & p)
inline

Constructor from a std::filesystem::path.

Parameters
[in]pA standard path instance.

Member Function Documentation

◆ EMPTY()

const UString & ts::UString::EMPTY ( )
static

A static empty string. Can be used when a reference to a static empty string is required.

Returns
A constant reference to the empty string.

◆ EMPTY8()

const std::string & ts::UString::EMPTY8 ( )
static

A static empty 8-bit string. Can be used when a reference to a static empty string is required.

Returns
A constant reference to the empty string.

◆ Range()

UString ts::UString::Range ( UChar first,
UChar last )
static

Build a string containing a range of characters.

Parameters
[in]firstFirst character in range.
[in]lastLast character in range.
Returns
A string containing all characters from first to last.

◆ wc_str() [1/2]

const ::WCHAR * ts::UString::wc_str ( ) const

Get the address of the underlying null-terminated Unicode string (Windows-specific).

Returns
The address of the underlying null-terminated Unicode string .

◆ wc_str() [2/2]

::WCHAR * ts::UString::wc_str ( )

Get the address of the underlying null-terminated Unicode string (Windows-specific).

Returns
The address of the underlying null-terminated Unicode string .

◆ FromUTF8() [1/3]

UString ts::UString::FromUTF8 ( const std::string & utf8)
static

Convert an UTF-8 string into UTF-16.

Parameters
[in]utf8A string in UTF-8 representation.
Returns
The equivalent UTF-16 string.

◆ FromUTF8() [2/3]

UString ts::UString::FromUTF8 ( const char * utf8)
static

Convert an UTF-8 string into UTF-16.

Parameters
[in]utf8Address of a nul-terminated string in UTF-8 representation.
Returns
The equivalent UTF-16 string. Empty string if utf8 is a null pointer.

◆ FromUTF8() [3/3]

UString ts::UString::FromUTF8 ( const char * utf8,
size_type count )
static

Convert an UTF-8 string into UTF-16.

Parameters
[in]utf8Address of a string in UTF-8 representation.
[in]countSize in bytes of the UTF-8 string (not necessarily a number of characters).
Returns
The equivalent UTF-16 string. Empty string if utf8 is a null pointer.

◆ assignFromUTF8() [1/3]

UString & ts::UString::assignFromUTF8 ( const std::string & utf8)
inline

Convert an UTF-8 string into this object.

Parameters
[in]utf8A string in UTF-8 representation.
Returns
A reference to this object.

◆ assignFromUTF8() [2/3]

UString & ts::UString::assignFromUTF8 ( const char * utf8)

Convert an UTF-8 string into this object.

Parameters
[in]utf8Address of a nul-terminated string in UTF-8 representation.
Returns
A reference to this object.

◆ assignFromUTF8() [3/3]

UString & ts::UString::assignFromUTF8 ( const char * utf8,
size_type count )

Convert an UTF-8 string into this object.

Parameters
[in]utf8Address of a string in UTF-8 representation. Can be null.
[in]countSize in bytes of the UTF-8 string (not necessarily a number of characters).
Returns
A reference to this object.

◆ toUTF8() [1/3]

std::string ts::UString::toUTF8 ( ) const

Convert this UTF-16 string into UTF-8.

Returns
The equivalent UTF-8 string.

◆ toUTF8() [2/3]

void ts::UString::toUTF8 ( std::string & utf8) const

Convert this UTF-16 string into UTF-8.

Parameters
[out]utf8The equivalent UTF-8 string.

◆ toUTF8() [3/3]

void ts::UString::toUTF8 ( ByteBlock & utf8) const

Convert this UTF-16 string into UTF-8 data.

Parameters
[out]utf8The equivalent UTF-8 data.

◆ appendUTF8() [1/2]

void ts::UString::appendUTF8 ( std::string & utf8) const

Convert this UTF-16 string into UTF-8 and append in a 8-bit string.

Parameters
[in,out]utf8Where to append the equivalent UTF-8 string.

◆ appendUTF8() [2/2]

void ts::UString::appendUTF8 ( ByteBlock & utf8) const

Convert this UTF-16 string into UTF-8 data and append in a byte block.

Parameters
[in,out]utf8Where to append the equivalent UTF-8 data.

◆ ConvertUTF16ToUTF8()

void ts::UString::ConvertUTF16ToUTF8 ( const UChar *& in_start,
const UChar * in_end,
char *& out_start,
char * out_end )
static

General routine to convert from UTF-16 to UTF-8. Stop when the input buffer is empty or the output buffer is full, whichever comes first. Invalid input values are silently ignored and skipped.

Parameters
[in,out]in_startAddress of the input UTF-16 buffer to convert. Updated upon return to point after the last converted character.
[in]in_endAddress after the end of the input UTF-16 buffer.
[in,out]out_startAddress of the output UTF-8 buffer to fill. Updated upon return to point after the last converted character.
[in]out_endAddress after the end of the output UTF-8 buffer to fill.

◆ ConvertUTF8ToUTF16()

void ts::UString::ConvertUTF8ToUTF16 ( const char *& in_start,
const char * in_end,
UChar *& out_start,
UChar * out_end )
static

General routine to convert from UTF-8 to UTF-16. Stop when the input buffer is empty or the output buffer is full, whichever comes first. Invalid input values are silently ignored and skipped.

Parameters
[in,out]in_startAddress of the input UTF-8 buffer to convert. Updated upon return to point after the last converted character.
[in]in_endAddress after the end of the input UTF-8 buffer.
[in,out]out_startAddress of the output UTF-16 buffer to fill. Updated upon return to point after the last converted character.
[in]out_endAddress after the end of the output UTF-16 buffer to fill.

◆ assign() [1/4]

template<typename CHARTYPE, typename INT>
requires std::integral<INT>
UString & ts::UString::assign ( const std::vector< CHARTYPE > & vec,
INT count )

Assign from a std::vector of 16-bit characters of any type.

Template Parameters
CHARTYPEA 16-bit character or integer type.
INTAn integer type.
Parameters
[in]vecThe vector of characters.
[in]countMaximum number of characters to include in the string. Stop before the first nul character before max. Can be of any integer type, including a signed type.
Returns
A reference to this object.

◆ assign() [2/4]

template<typename CHARTYPE>
UString & ts::UString::assign ( const std::vector< CHARTYPE > & vec)

Assign from a std::vector of 16-bit characters of any type.

Template Parameters
CHARTYPEA 16-bit character or integer type.
Parameters
[in]vecThe vector of characters. Nul-terminated string.
Returns
A reference to this object.

◆ assign() [3/4]

template<typename CHARTYPE, std::size_t SIZE, typename INT>
requires std::integral<INT>
UString & ts::UString::assign ( const std::array< CHARTYPE, SIZE > & arr,
INT count )

Assign from a std::array of 16-bit characters of any type.

Template Parameters
CHARTYPEA 16-bit character or integer type.
SIZEThe size of the array.
INTAn integer type.
Parameters
[in]arrThe array of characters.
[in]countMaximum number of characters to include in the string. Stop before the first nul character before max. Can be of any integer type, including a signed type.
Returns
A reference to this object.

◆ assign() [4/4]

template<typename CHARTYPE, std::size_t SIZE>
UString & ts::UString::assign ( const std::array< CHARTYPE, SIZE > & arr)

Assign from a std::array of 16-bit characters of any type.

Template Parameters
CHARTYPEA 16-bit character or integer type.
SIZEThe size of the array.
Parameters
[in]arrThe array of characters. Nul-terminated string.
Returns
A reference to this object.

◆ FromWChar() [1/3]

UString ts::UString::FromWChar ( const std::wstring & wstr)
static

Convert a C++ "wide string" into UTF-16.

Parameters
[in]wstrA C++ "wide string".
Returns
The equivalent UTF-16 string.

◆ FromWChar() [2/3]

UString ts::UString::FromWChar ( const wchar_t * wstr)
static

Convert a C++ "wide string" into UTF-16.

Parameters
[in]wstrAddress of a nul-terminated "wide string". Can be null.
Returns
The equivalent UTF-16 string. Empty string if wstr is a null pointer.

◆ FromWChar() [3/3]

UString ts::UString::FromWChar ( const wchar_t * wstr,
size_type count )
static

Convert a C++ "wide string" into UTF-16.

Parameters
[in]wstrAddress of a "wide string". Can be null.
[in]countNumber of characters in wstr.
Returns
The equivalent UTF-16 string. Empty string if utf8 is a null pointer.

◆ assignFromWChar() [1/3]

UString & ts::UString::assignFromWChar ( const std::wstring & wstr)
inline

Convert a C++ "wide string" into this object.

Parameters
[in]wstrA C++ "wide string".
Returns
A reference to this object.

◆ assignFromWChar() [2/3]

UString & ts::UString::assignFromWChar ( const wchar_t * wstr)
inline

Convert a C++ "wide string" into this object.

Parameters
[in]wstrAddress of a nul-terminated "wide string". Can be null.
Returns
A reference to this object.

◆ assignFromWChar() [3/3]

UString & ts::UString::assignFromWChar ( const wchar_t * wstr,
size_type count )

Convert a C++ "wide string" into this object.

Parameters
[in]wstrAddress of a "wide string". Can be null.
[in]countNumber of characters in wstr.
Returns
A reference to this object.

◆ operator fs::path()

ts::UString::operator fs::path ( ) const
inline

Conversion operator from ts::UString to std::filesystem::path

Returns
A path value.

◆ operator==()

bool ts::UString::operator== ( const fs::path & other) const
inline

Comparison operator with std::filesystem::path.

Parameters
[in]otherA path to compare.
Returns
True if this string object is equal to the path string, false otherwise.

◆ last() [1/2]

const UChar * ts::UString::last ( ) const
inline

Get the address after the last character in the string.

Returns
The address after the last character in the string.

◆ last() [2/2]

UChar * ts::UString::last ( )
inline

Get the address after the last character in the string.

Returns
The address after the last character in the string.

◆ width()

size_type ts::UString::width ( ) const

Get the display width in characters. Any combining diacritical character is not counted in the width since it is combined with the preceding character. Similarly, any surrogate pair is considered as one single character. As a general rule, width() is always lower than or equal to length(), the number of characters in the string.

Returns
The display width in characters.

◆ displayPosition()

size_type ts::UString::displayPosition ( size_type count,
size_type from = 0,
StringDirection direction = LEFT_TO_RIGHT ) const

Count displayed positions inside a string. Any combining diacritical character is not counted in display position. Similarly, any surrogate pair is considered as one single character.

Parameters
[in]countNumber of display positions to move.
[in]fromStarting index in the string. This is an index, not a display position.
[in]directionDirection to move when counting display positions. When counting RIGHT_TO_LEFT, from is the position after the right-most character.
Returns
The index in the string after moving. When the display position is outside the string, return length() when moving LEFT_TO_RIGHT and return zero when moving RIGHT_TO_LEFT. The returned index is never in the middle of a combining diacritical sequence or of a surrogate pair, always at the start of this sequence.

◆ truncateWidth()

void ts::UString::truncateWidth ( size_type max_width,
StringDirection direction = LEFT_TO_RIGHT )

Truncate this string to a given display width. Any combining diacritical character is not counted in display position. Similarly, any surrogate pair is considered as one single character.

Parameters
[in]max_widthMaximum display width, after which the string is truncated.
[in]directionDirection to move when counting width. When RIGHT_TO_LEFT, the width is counted from the end of the string and the beginning of the string is truncated.

◆ toTruncatedWidth()

UString ts::UString::toTruncatedWidth ( size_type max_width,
StringDirection direction = LEFT_TO_RIGHT ) const

Return a copy of this string, truncated to a given display width. Any combining diacritical character is not counted in display position. Similarly, any surrogate pair is considered as one single character.

Parameters
[in]max_widthMaximum display width, after which the string is truncated.
[in]directionDirection to move when counting width. When RIGHT_TO_LEFT, the width is counted from the end of the string and the beginning of the string is truncated.
Returns
A copy of the string, truncated to the given display width.

◆ reverse()

void ts::UString::reverse ( )

Reverse the order of characters in the string.

◆ trimLength()

template<typename INT>
requires std::integral<INT>
void ts::UString::trimLength ( INT length,
bool trim_trailing_spaces = true )

Reduce the size of the string to a given length from an alien integer type. This method is useful when the string has been used as an input buffer.

Template Parameters
INTAn integer type.
Parameters
[in]lengthNew size of the string. Ignored if negative or greater than the current string length.
[in]trim_trailing_spacesIf true, also remove any trailing space.

◆ toReversed()

UString ts::UString::toReversed ( ) const

Return a copy of the string where characters are reversed.

Returns
A copy of the string where characters are reversed.

◆ trim()

void ts::UString::trim ( bool leading = true,
bool trailing = true,
bool sequences = false )

Trim leading and / or trailing space characters.

Parameters
[in]leadingIf true (the default), remove all space characters at the beginning of the string.
[in]trailingIf true (the default), remove all space characters at the end of the string.
[in]sequencesIf true (disabled by default), replace all space characters sequences in the middle of the string by one single space character.

◆ toTrimmed()

UString ts::UString::toTrimmed ( bool leading = true,
bool trailing = true,
bool sequences = false ) const

Return a copy of the string where leading and / or trailing spaces are trimmed.

Parameters
[in]leadingIf true (the default), remove all space characters at the beginning of the string.
[in]trailingIf true (the default), remove all space characters at the end of the string.
[in]sequencesIf true (disabled by default), replace all space characters sequences in the middle of the string by one single space character.
Returns
A copy of this object after trimming.

◆ convertToLower()

void ts::UString::convertToLower ( )

Convert the string to lower-case.

◆ convertToUpper()

void ts::UString::convertToUpper ( )

Convert the string to uper-case.

◆ toLower()

UString ts::UString::toLower ( ) const

Return a lower-case version of the string.

Returns
Lower-case version of the string.

◆ toUpper()

UString ts::UString::toUpper ( ) const

Return an upper-case version of the string.

Returns
Upper-case version of the string.

◆ combineDiacritical()

void ts::UString::combineDiacritical ( )

Combine all possible diacritical marks. All sequences of two characters, letter and non-spacing diacritical marks, which can be grouped into once single precombined character are substituted with this precombined character.

◆ toCombinedDiacritical()

UString ts::UString::toCombinedDiacritical ( ) const

Return a string with all possible diacritical marks combined.

Returns
A string where all sequences of two characters, letter and non-spacing diacritical marks, which can be grouped into once single precombined character have been substituted with this precombined character.

◆ decomposeDiacritical()

void ts::UString::decomposeDiacritical ( )

Decompose all precombined characters. All precombined characters are replaced by two characters, the base letter and the non-spacing diacritical mark.

◆ toDecomposedDiacritical()

UString ts::UString::toDecomposedDiacritical ( ) const

Return a string with all precombined characters decomposed.

Returns
A string where all precombined characters are replaced by two characters, the base letter and the non-spacing diacritical mark.

◆ remove() [1/2]

void ts::UString::remove ( const UString & substr)

Remove all occurrences of a substring.

Parameters
[in]substrSubstring to remove.

◆ remove() [2/2]

void ts::UString::remove ( UChar c)

Remove all occurrences of a character.

Parameters
[in]cCharacter to remove.

◆ toRemoved() [1/2]

UString ts::UString::toRemoved ( const UString & substr) const

Remove all occurrences of a substring.

Parameters
[in]substrSubstring to remove.
Returns
This string with all occurrences of substr removed.

◆ toRemoved() [2/2]

UString ts::UString::toRemoved ( UChar c) const

Remove all occurrences of a character.

Parameters
[in]cCharacter to remove.
Returns
This string with all occurrences of substr removed.

◆ substitute() [1/2]

void ts::UString::substitute ( const UString & value,
const UString & replacement )

Substitute all occurrences of a string with another one.

Parameters
[in]valueValue to search.
[in]replacementReplacement string for value.

◆ substitute() [2/2]

void ts::UString::substitute ( UChar value,
UChar replacement )

Substitute all occurrences of a character with another one.

Parameters
[in]valueValue to search.
[in]replacementReplacement for value.

◆ toSubstituted() [1/2]

UString ts::UString::toSubstituted ( const UString & value,
const UString & replacement ) const

Return a copy of the string where all occurrences of a string are substituted with another one.

Parameters
[in]valueValue to search.
[in]replacementReplacement string for value.
Returns
A copy to this string where all occurrences of value have been replaced by replace.

◆ toSubstituted() [2/2]

UString ts::UString::toSubstituted ( UChar value,
UChar replacement ) const

Return a copy of the string where all occurrences of a character are substituted with another one.

Parameters
[in]valueValue to search.
[in]replacementReplacement for value.
Returns
A copy to this string where all occurrences of value have been replaced by replace.

◆ removePrefix()

void ts::UString::removePrefix ( const UString & prefix,
CaseSensitivity cs = CASE_SENSITIVE )

Remove a prefix in string.

Parameters
[in]prefixA prefix to remove, if present at the beginning of the string.
[in]csIndicate if the comparison is case-sensitive.

◆ removeSuffix()

void ts::UString::removeSuffix ( const UString & suffix,
CaseSensitivity cs = CASE_SENSITIVE )

Remove a suffix in string.

Parameters
[in]suffixA suffix to remove, if present at the end of the string.
[in]csIndicate if the comparison is case-sensitive.

◆ toRemovedPrefix()

UString ts::UString::toRemovedPrefix ( const UString & prefix,
CaseSensitivity cs = CASE_SENSITIVE ) const

Remove a prefix in string.

Parameters
[in]prefixA prefix to remove, if present at the beginning of the string.
[in]csIndicate if the comparison is case-sensitive.
Returns
A copy of this string with prefix removed.

◆ toRemovedSuffix()

UString ts::UString::toRemovedSuffix ( const UString & suffix,
CaseSensitivity cs = CASE_SENSITIVE ) const

Remove a suffix in string.

Parameters
[in]suffixA suffix to remove, if present at the end of the string.
[in]csIndicate if the comparison is case-sensitive.
Returns
A copy of this string with suffix removed.

◆ indent()

void ts::UString::indent ( size_t size)

Indent all lines in the string.

Parameters
[in]sizeNumber of spaces to add at the beginning of each line.

◆ toIndented()

UString ts::UString::toIndented ( size_t size) const

Indent all lines in the string.

Parameters
[in]sizeNumber of spaces to add at the beginning of each line.
Returns
A copy of this string with indented lines.

◆ starts_with() [1/4]

bool ts::UString::starts_with ( const UString & prefix,
CaseSensitivity cs = CASE_SENSITIVE,
bool skip_spaces = false,
size_type start = 0 ) const

Check if the string starts with a specified prefix.

Parameters
[in]prefixA string prefix to check.
[in]csIndicate if the comparison is case-sensitive.
[in]skip_spacesIf true, ignore initial spaces in this string.
[in]startStart index where to match the prefix.
Returns
True if this string starts with prefix, false otherwise.

◆ starts_with() [2/4]

bool ts::UString::starts_with ( const std::u16string_view & prefix,
CaseSensitivity cs = CASE_SENSITIVE,
bool skip_spaces = false,
size_type start = 0 ) const
inline

Check if the string starts with a specified prefix.

Parameters
[in]prefixA string prefix to check.
[in]csIndicate if the comparison is case-sensitive.
[in]skip_spacesIf true, ignore initial spaces in this string.
[in]startStart index where to match the prefix.
Returns
True if this string starts with prefix, false otherwise.

◆ starts_with() [3/4]

bool ts::UString::starts_with ( UChar prefix,
CaseSensitivity cs = CASE_SENSITIVE,
bool skip_spaces = false,
size_type start = 0 ) const
inline

Check if the string starts with a specified prefix.

Parameters
[in]prefixA string prefix to check.
[in]csIndicate if the comparison is case-sensitive.
[in]skip_spacesIf true, ignore initial spaces in this string.
[in]startStart index where to match the prefix.
Returns
True if this string starts with prefix, false otherwise.

◆ starts_with() [4/4]

bool ts::UString::starts_with ( const UChar * prefix,
CaseSensitivity cs = CASE_SENSITIVE,
bool skip_spaces = false,
size_type start = 0 ) const
inline

Check if the string starts with a specified prefix.

Parameters
[in]prefixA string prefix to check.
[in]csIndicate if the comparison is case-sensitive.
[in]skip_spacesIf true, ignore initial spaces in this string.
[in]startStart index where to match the prefix.
Returns
True if this string starts with prefix, false otherwise.

◆ contains() [1/2]

bool ts::UString::contains ( UChar c) const

Check if a string contains a specified character.

Parameters
[in]cA character to check.
Returns
True if this string contains c, false otherwise.

◆ contains() [2/2]

bool ts::UString::contains ( const UString & substring,
CaseSensitivity cs = CASE_SENSITIVE ) const

Check if a string contains a specified substring.

Parameters
[in]substringA substring to check.
[in]csIndicate if the comparison is case-sensitive.
Returns
True if this string contains substring, false otherwise.

◆ ends_with() [1/4]

bool ts::UString::ends_with ( const UString & suffix,
CaseSensitivity cs = CASE_SENSITIVE,
bool skip_spaces = false,
size_type end = NPOS ) const

Check if a string ends with a specified suffix.

Parameters
[in]suffixA string suffix to check.
[in]csIndicate if the comparison is case-sensitive.
[in]skip_spacesIf true, ignore trailing spaces in this string.
[in]endLast logical character to check in the string. By default, use the end of string.
Returns
True if this string ends with suffix, false otherwise.

◆ ends_with() [2/4]

bool ts::UString::ends_with ( const std::u16string_view & suffix,
CaseSensitivity cs = CASE_SENSITIVE,
bool skip_spaces = false,
size_type end = NPOS ) const
inline

Check if a string ends with a specified suffix.

Parameters
[in]suffixA string suffix to check.
[in]csIndicate if the comparison is case-sensitive.
[in]skip_spacesIf true, ignore trailing spaces in this string.
[in]endLast logical character to check in the string. By default, use the end of string.
Returns
True if this string ends with suffix, false otherwise.

◆ ends_with() [3/4]

bool ts::UString::ends_with ( UChar suffix,
CaseSensitivity cs = CASE_SENSITIVE,
bool skip_spaces = false,
size_type end = NPOS ) const
inline

Check if a string ends with a specified suffix.

Parameters
[in]suffixA string suffix to check.
[in]csIndicate if the comparison is case-sensitive.
[in]skip_spacesIf true, ignore trailing spaces in this string.
[in]endLast logical character to check in the string. By default, use the end of string.
Returns
True if this string ends with suffix, false otherwise.

◆ ends_with() [4/4]

bool ts::UString::ends_with ( const UChar * suffix,
CaseSensitivity cs = CASE_SENSITIVE,
bool skip_spaces = false,
size_type end = NPOS ) const
inline

Check if a string ends with a specified suffix.

Parameters
[in]suffixA string suffix to check.
[in]csIndicate if the comparison is case-sensitive.
[in]skip_spacesIf true, ignore trailing spaces in this string.
[in]endLast logical character to check in the string. By default, use the end of string.
Returns
True if this string ends with suffix, false otherwise.

◆ commonPrefixSize()

size_t ts::UString::commonPrefixSize ( const UString & str,
CaseSensitivity cs = CASE_SENSITIVE ) const

Compute the number of similar leading characters in two strings.

Parameters
[in]strA string to compare with this string.
[in]csIndicate if the comparison is case-sensitive.
Returns
The number of identical leading characters in str and this string.

◆ commonSuffixSize()

size_t ts::UString::commonSuffixSize ( const UString & str,
CaseSensitivity cs = CASE_SENSITIVE ) const

Compute the number of similar trailing characters in two strings.

Parameters
[in]strA string to compare with this string.
[in]csIndicate if the comparison is case-sensitive.
Returns
The number of identical trailing characters in str and this string.

◆ split()

template<class CONTAINER>
void ts::UString::split ( CONTAINER & container,
UChar separator = COMMA,
bool trim_spaces = true,
bool remove_empty = false ) const
inline

Split the string into segments based on a separator character (comma by default).

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[out]containerA container of UString which receives the segments of the splitted string.
[in]separatorThe character which is used to separate the segments.
[in]trim_spacesIf true (the default), each segment is trimmed, i.e. all leading and trailing space characters are removed.
[in]remove_emptyIf true, empty segments are ignored

◆ splitAppend()

template<class CONTAINER>
void ts::UString::splitAppend ( CONTAINER & container,
UChar separator = COMMA,
bool trim_spaces = true,
bool remove_empty = false ) const

Split the string into segments based on a separator character (comma by default).

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in,out]containerA container of UString which receives the segments of the splitted string. The strings are appended to the container without erasing previous content.
[in]separatorThe character which is used to separate the segments.
[in]trim_spacesIf true (the default), each segment is trimmed, i.e. all leading and trailing space characters are removed.
[in]remove_emptyIf true, empty segments are ignored

◆ splitShellStyle()

template<class CONTAINER>
void ts::UString::splitShellStyle ( CONTAINER & container) const
inline

Split the string into shell-style arguments. Spaces are used as argument delimiters. Arguments can be quoted using single or double quotes. Any character can be escaped using a backslash.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[out]containerA container of UString which receives the segments of the splitted string.

◆ splitShellStyleAppend()

template<class CONTAINER>
void ts::UString::splitShellStyleAppend ( CONTAINER & container) const

Split the string into shell-style arguments. Spaces are used as argument delimiters. Arguments can be quoted using single or double quotes. Any character can be escaped using a backslash.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in,out]containerA container of UString which receives the segments of the splitted string. The strings are appended to the container without erasing previous content.

◆ splitBlocks()

template<class CONTAINER>
void ts::UString::splitBlocks ( CONTAINER & container,
UChar starts_with = u'[',
UChar ends_with = u']',
bool trim_spaces = true ) const
inline

Split a string into segments which are identified by their starting / ending characters (respectively "[" and "]" by default).

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[out]containerA container of UString which receives the segments of the splitted string.
[in]starts_withThe character which is used to identify the start of a segment of input.
[in]ends_withThe character which is used to identify the end of a segment of input.
[in]trim_spacesIf true (the default), each segment is trimmed, i.e. all leading and trailing space characters are removed.

◆ splitBlocksAppend()

template<class CONTAINER>
void ts::UString::splitBlocksAppend ( CONTAINER & container,
UChar starts_with = u'[',
UChar ends_with = u']',
bool trim_spaces = true ) const

Split a string into segments which are identified by their starting / ending characters (respectively "[" and "]" by default).

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in,out]containerA container of UString which receives the segments of the splitted string. The strings are appended to the container without erasing previous content.
[in]starts_withThe character which is used to identify the start of a segment of input.
[in]ends_withThe character which is used to identify the end of a segment of input.
[in]trim_spacesIf true (the default), each segment is trimmed, i.e. all leading and trailing space characters are removed.

◆ splitLines()

template<class CONTAINER>
void ts::UString::splitLines ( CONTAINER & container,
size_type max_width,
const UString & other_separators = UString(),
const UString & next_margin = UString(),
bool force_split = false ) const
inline

Split a string into multiple lines which are not longer than a specified maximum width. The splits occur on spaces or after any character in other_separators.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[out]containerA container of UString which receives the lines of the splitted string.
[in]max_widthMaximum width of each resulting line.
[in]other_separatorsA string containing all characters which are acceptable as line break points (in addition to space characters which are always potential line break points).
[in]next_marginA string which is prepended to all lines after the first one.
[in]force_splitIf true, longer lines without separators are split at the maximum width (by default, longer lines without separators are not split, resulting in lines longer than max_width).

◆ splitLinesAppend()

template<class CONTAINER>
void ts::UString::splitLinesAppend ( CONTAINER & container,
size_type max_width,
const UString & other_separators = UString(),
const UString & next_margin = UString(),
bool force_split = false ) const

Split a string into multiple lines which are not longer than a specified maximum width. The splits occur on spaces or after any character in other_separators.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in,out]containerA container of UString which receives the lines of the splitted string. The strings are appended to the container without erasing previous content.
[in]max_widthMaximum width of each resulting line.
[in]other_separatorsA string containing all characters which are acceptable as line break points (in addition to space characters which are always potential line break points).
[in]next_marginA string which is prepended to all lines after the first one.
[in]force_splitIf true, longer lines without separators are split at the maximum width (by default, longer lines without separators are not split, resulting in lines longer than max_width).

◆ toSplitLines()

UString ts::UString::toSplitLines ( size_type max_width,
const UString & other_separators = UString(),
const UString & next_margin = UString(),
bool force_split = false,
const UString & line_separator = UString(1, LINE_FEED) ) const

Split a string into multiple lines which are not longer than a specified maximum width. The splits occur on spaces or after any character in other_separators.

Parameters
[in]max_widthMaximum width of each resulting line.
[in]other_separatorsA string containing all characters which are acceptable as line break points (in addition to space characters which are always potential line break points).
[in]next_marginA string which is prepended to all lines after the first one.
[in]force_splitIf true, longer lines without separators are split at the maximum width (by default, longer lines without separators are not split, resulting in lines longer than max_width).
[in]line_separatorThe sequence of characters for line feed.
Returns
The splitted string with embedded line separators.

◆ join() [1/2]

template<class ITERATOR>
UString ts::UString::join ( ITERATOR begin,
ITERATOR end,
bool remove_empty = false ) const

Join a part of a container of strings into one big string. This string is used as separator between the strings to join. The strings are accessed through iterators in the container. All strings are concatenated into one big string.

Template Parameters
ITERATORAn iterator class over UString as defined by the C++ Standard Template Library (STL).
Parameters
[in]beginAn iterator pointing to the first string.
[in]endAn iterator pointing after the last string.
[in]remove_emptyIf true, empty segments are ignored
Returns
The big string containing all segments and separators.

◆ join() [2/2]

template<class CONTAINER>
UString ts::UString::join ( const CONTAINER & container,
bool remove_empty = false ) const
inline

Join a container of strings into one big string. This string is used as separator between the strings to join. All strings from the container are concatenated into one big string.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in]containerA container of UString containing all strings to concatenate.
[in]remove_emptyIf true, empty segments are ignored
Returns
The big string containing all segments and separators.

◆ Join() [1/4]

template<class ITERATOR>
UString ts::UString::Join ( ITERATOR begin,
ITERATOR end,
const UString & separator = UString(u", "),
bool remove_empty = false )
inlinestatic

Join a part of a container of strings into one big string. The strings are accessed through iterators in the container. All strings are concatenated into one big string.

Template Parameters
ITERATORAn iterator class over UString as defined by the C++ Standard Template Library (STL).
Parameters
[in]beginAn iterator pointing to the first string.
[in]endAn iterator pointing after the last string.
[in]separatorA string to insert between all segments.
[in]remove_emptyIf true, empty segments are ignored
Returns
The big string containing all segments and separators.

◆ Join() [2/4]

template<class ITERATOR>
UString ts::UString::Join ( ITERATOR begin,
ITERATOR end,
UChar separator,
bool remove_empty = false )
inlinestatic

Join a part of a container of strings into one big string. The strings are accessed through iterators in the container. All strings are concatenated into one big string.

Template Parameters
ITERATORAn iterator class over UString as defined by the C++ Standard Template Library (STL).
Parameters
[in]beginAn iterator pointing to the first string.
[in]endAn iterator pointing after the last string.
[in]separatorA character to insert between all segments.
[in]remove_emptyIf true, empty segments are ignored
Returns
The big string containing all segments and separators.

◆ Join() [3/4]

template<class CONTAINER>
UString ts::UString::Join ( const CONTAINER & container,
const UString & separator = UString(u", "),
bool remove_empty = false )
inlinestatic

Join a container of strings into one big string. All strings from the container are concatenated into one big string.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in]containerA container of UString containing all strings to concatenate.
[in]separatorA string to insert between all segments.
[in]remove_emptyIf true, empty segments are ignored
Returns
The big string containing all segments and separators.

◆ Join() [4/4]

template<class CONTAINER>
UString ts::UString::Join ( const CONTAINER & container,
UChar separator,
bool remove_empty = false )
inlinestatic

Join a container of strings into one big string. All strings from the container are concatenated into one big string.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in]containerA container of UString containing all strings to concatenate.
[in]separatorA character to insert between all segments.
[in]remove_emptyIf true, empty segments are ignored
Returns
The big string containing all segments and separators.

◆ justifyLeft()

void ts::UString::justifyLeft ( size_type width,
UChar pad = SPACE,
bool truncate = false,
size_t spaces_before_pad = 0 )

Left-justify (pad and optionally truncate) string. If this string is shorter than the specified width, pad characters are appended to the string up to the specified width.

Parameters
[in]widthThe required width of the result string.
[in]padThe character to append to the string.
[in]truncateIf true and this string is longer than width, it is truncated to width character. If false, this string is never truncated, possibly resulting in a string longer than width.
[in]spaces_before_padNumber of spaces before padding.

◆ toJustifiedLeft()

UString ts::UString::toJustifiedLeft ( size_type width,
UChar pad = SPACE,
bool truncate = false,
size_t spaces_before_pad = 0 ) const

Return a left-justified (padded and optionally truncated) string. If this string is shorter than the specified width, pad characters are appended to the string up to the specified width.

Parameters
[in]widthThe required width of the result string.
[in]padThe character to append to the string.
[in]truncateIf true and this string is longer than width, it is truncated to width character. If false, this string is never truncated, possibly resulting in a string longer than width.
[in]spaces_before_padNumber of spaces before padding.
Returns
The justified string.

◆ justifyRight()

void ts::UString::justifyRight ( size_type width,
UChar pad = SPACE,
bool truncate = false,
size_t spaces_after_pad = 0 )

Right-justified (pad and optionally truncate) string. If this string is shorter than the specified width, pad characters are prepended to the string up to the specified width.

Parameters
[in]widthThe required width of the result string.
[in]padThe character to prepend to the string.
[in]truncateIf true and this string is longer than width, the beginning of str is truncated. If false, this string is never truncated, possibly resulting in a string longer than width.
[in]spaces_after_padNumber of spaces after padding.

◆ toJustifiedRight()

UString ts::UString::toJustifiedRight ( size_type width,
UChar pad = SPACE,
bool truncate = false,
size_t spaces_after_pad = 0 ) const

Return a right-justified (padded and optionally truncated) string. If this string is shorter than the specified width, pad characters are prepended to the string up to the specified width.

Parameters
[in]widthThe required width of the result string.
[in]padThe character to prepend to the string.
[in]truncateIf true and this string is longer than width, the beginning of str is truncated. If false, this string is never truncated, possibly resulting in a string longer than width.
[in]spaces_after_padNumber of spaces after padding.
Returns
The justified string.

◆ justifyCentered()

void ts::UString::justifyCentered ( size_type width,
UChar pad = SPACE,
bool truncate = false,
size_t spaces_around_pad = 0 )

Centered-justified (pad and optionally truncate) string. If this string is shorter than the specified width, pad characters are prepended and appended to the string up to the specified width.

Parameters
[in]widthThe required width of the result string.
[in]padThe pad character for the string.
[in]truncateIf true and this string is longer than width, this string is truncated to width character. If false, this string is never truncated, possibly resulting in a string longer than width.
[in]spaces_around_padNumber of spaces around padding.

◆ toJustifiedCentered()

UString ts::UString::toJustifiedCentered ( size_type width,
UChar pad = SPACE,
bool truncate = false,
size_t spaces_around_pad = 0 ) const

Return a centered-justified (padded and optionally truncated) string. If this string is shorter than the specified width, pad characters are prepended and appended to the string up to the specified width.

Parameters
[in]widthThe required width of the result string.
[in]padThe pad character for the string.
[in]truncateIf true and this string is longer than width, this string is truncated to width character. If false, this string is never truncated, possibly resulting in a string longer than width.
[in]spaces_around_padNumber of spaces around padding.
Returns
The justified string.

◆ justify()

void ts::UString::justify ( const UString & right,
size_type width,
UChar pad = SPACE,
size_t spaces_around_pad = 0 )

Justify string, pad in the middle. If the this string and right components are collectively shorter than the specified width, pad characters are inserted between left and right, up to the specified width.

Parameters
[in]rightThe right part of the string to justify. This string is used as left part.
[in]widthThe required width of the result string.
[in]padThe character to insert between the two parts.
[in]spaces_around_padNumber of spaces around padding.

◆ toJustified()

UString ts::UString::toJustified ( const UString & right,
size_type width,
UChar pad = SPACE,
size_t spaces_around_pad = 0 ) const

Return a justified string, pad in the middle. If the this string and right components are collectively shorter than the specified width, pad characters are inserted between left and right, up to the specified width.

Parameters
[in]rightThe right part of the string to justify. This string is used as left part.
[in]widthThe required width of the result string.
[in]padThe character to insert between the two parts.
[in]spaces_around_padNumber of spaces around padding.
Returns
The justified string.

◆ quoted()

void ts::UString::quoted ( UChar quote_character = u'\'',
const UString & special_characters = DEFAULT_SPECIAL_CHARACTERS,
bool force_quote = false,
UChar non_print = u'?' )

Replace the string with a "quoted" version of it. If this string contains any space character or any character from special_characters, then the string is replaced with a value surrounded by the quote_character and all special characters are properly escaped using a backslash.

Parameters
[in]quote_characterThe character to be used as quote.
[in]special_charactersThe list of special characters. The quote_character is implicitly part of special_characters.
[in]force_quoteIf true, force quote, even if the content does not require it.
[in]non_printReplacement character for all non-printable characters.

◆ toQuoted()

UString ts::UString::toQuoted ( UChar quote_character = u'\'',
const UString & special_characters = DEFAULT_SPECIAL_CHARACTERS,
bool force_quote = false,
UChar non_print = u'?' ) const

Return a "quoted" version of this string.

Parameters
[in]quote_characterThe character to be used as quote.
[in]special_charactersThe list of special characters. The quote_character is implicitly part of special_characters.
[in]force_quoteIf true, force quote, even if the content does not require it.
[in]non_printReplacement character for all non-printable characters.
Returns
A "quoted" version of this string.
See also
quoted()

◆ quotedLine()

template<class CONTAINER>
void ts::UString::quotedLine ( const CONTAINER & container,
UChar quote_character = u'\'',
const UString & special_characters = DEFAULT_SPECIAL_CHARACTERS )

Convert a container of strings into one big string where all elements are properly quoted when necessary. This string object receives the final line with quoted elements.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in]containerA container of UString containing all elements.
[in]quote_characterThe character to be used as quote.
[in]special_charactersThe list of special characters. The quote_character is implicitly part of special_characters.

◆ ToQuotedLine()

template<class CONTAINER>
UString ts::UString::ToQuotedLine ( const CONTAINER & container,
UChar quote_character = u'\'',
const UString & special_characters = DEFAULT_SPECIAL_CHARACTERS )
static

Convert a container of strings into one big string where all elements are properly quoted when necessary.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in]containerA container of UString containing all elements.
[in]quote_characterThe character to be used as quote.
[in]special_charactersThe list of special characters. The quote_character is implicitly part of special_characters.
Returns
The final line with quoted elements.

◆ fromQuotedLine()

template<class CONTAINER>
void ts::UString::fromQuotedLine ( CONTAINER & container,
const UString & quote_characters = DEFAULT_QUOTE_CHARACTERS,
const UString & special_characters = DEFAULT_SPECIAL_CHARACTERS ) const

Split this string in space-separated possibly-quoted elements.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[out]containerA container of UString receiving all unquoted elements.
[in]quote_charactersAll characters which are recognized as quote at the beginning of an element.
[in]special_charactersThe list of special characters. The quote_character is implicitly part of special_characters.
See also
quoted()

◆ unquoted()

void ts::UString::unquoted ( const UString & quote_characters = DEFAULT_QUOTE_CHARACTERS)

Remove matching pairs of quotes at beginning and end of string. This is done recursively (e.g. "'"abcd"'" -> abcd).

Parameters
[in]quote_charactersAll characters which are recognized as quote.

◆ toUnquoted()

UString ts::UString::toUnquoted ( const UString & quote_characters = DEFAULT_QUOTE_CHARACTERS) const

Return a version of the string with matching pairs of quotes at beginning and end removed.

Parameters
[in]quote_charactersAll characters which are recognized as quote.
Returns
A version of the string with matching pairs of quotes at beginning and end removed.

◆ convertToHTML()

void ts::UString::convertToHTML ( const UString & convert = UString())

Convert the string into a suitable HTML representation.

Parameters
[in]convertA string containing all characters to convert into their corresponding HTML entities. If empty, all characters are converted.

◆ toHTML()

UString ts::UString::toHTML ( const UString & convert = UString()) const

Return the string in a suitable HTML representation.

Parameters
[in]convertA string containing all characters to convert into their corresponding HTML entities. If empty, all characters are converted.
Returns
The string with HTML entities replacing special characters.

◆ convertFromHTML()

void ts::UString::convertFromHTML ( )

Convert all HTML entities in the string into plain characters.

◆ fromHTML()

UString ts::UString::fromHTML ( ) const

Return the string with all HTML entities converted into plain characters.

Returns
The string with HTML entities translated.

◆ convertToJSON()

void ts::UString::convertToJSON ( )

Convert the string into a suitable JSON representation. The characters to escape are converted with backslashes.

◆ toJSON()

UString ts::UString::toJSON ( ) const

Return the string in a suitable JSON representation.

Returns
The string with backslash sequences replacing special characters.

◆ convertFromJSON()

void ts::UString::convertFromJSON ( )

Convert all JSON backslash sequences in the string into plain characters.

◆ fromJSON()

UString ts::UString::fromJSON ( ) const

Return the string with all JSON backslash sequences converted into plain characters.

Returns
The string with JSON backslash sequences translated.

◆ YesNo()

UString ts::UString::YesNo ( bool b)
static

Format a boolean value as "yes" or "no".

Parameters
[in]bA boolean value.
Returns
"yes" is b is true, "no" otherwise.

◆ TrueFalse()

UString ts::UString::TrueFalse ( bool b)
static

Format a boolean value as "true" or "false".

Parameters
[in]bA boolean value.
Returns
"true" is b is true, "false" otherwise.

◆ OnOff()

UString ts::UString::OnOff ( bool b)
static

Format a boolean value as "on" or "off".

Parameters
[in]bA boolean value.
Returns
"on" is b is true, "off" otherwise.

◆ TristateYesNo()

UString ts::UString::TristateYesNo ( Tristate b)
static

Format a tristate value as "yes", "no", "maybe".

Parameters
[in]bA tristate value.
Returns
One of "yes", "no", "maybe".

◆ TristateTrueFalse()

UString ts::UString::TristateTrueFalse ( Tristate b)
static

Format a tristate value as "true", "false", "unknown".

Parameters
[in]bA tristate value.
Returns
One of "true", "false", "unknown".

◆ TristateOnOff()

UString ts::UString::TristateOnOff ( Tristate b)
static

Format a tristate value as "on", "off", "unknown".

Parameters
[in]bA tristate value.
Returns
One of "on", "off", "unknown".

◆ AfterBytes()

UString ts::UString::AfterBytes ( const std::streampos & position)
static

Build an error message fragment indicating the number of bytes previously read in a binary file.

Parameters
[in]positionA stream position.
Returns
A string like " after XX bytes" if position is greater than zero, an empty string otherwise.

◆ HumanSize()

UString ts::UString::HumanSize ( int64_t value,
const UString & units = u"B",
bool force_sign = false )
static

Format a human-readable size using MB, kB or B as appropriate.

Parameters
[in]valueA size value in basic units. This is a signed value.
[in]unitsA string for the units. The default is "B" (for bytes).
[in]force_signIf true, use a '+' sign for positive value.
Returns
A human-readable representation of the size value.

◆ Percentage() [1/2]

template<typename Int1, typename Int2>
requires std::integral<Int1> && std::integral<Int2>
UString ts::UString::Percentage ( Int1 value,
Int2 total )
static

Format a percentage string.

Parameters
[in]valueAn integer value, a portion of total.
[in]totalThe total value.
Returns
A string representing the percentage of value in total.

◆ Percentage() [2/2]

template<class Rep1, class Period1, class Rep2, class Period2>
UString ts::UString::Percentage ( const cn::duration< Rep1, Period1 > & value,
const cn::duration< Rep2, Period2 > & total )
static

Format a percentage string between duration values.

Parameters
[in]valueA duration value, a portion of total.
[in]totalThe total duration value.
Returns
A string representing the percentage of value in total.

◆ superCompare() [1/2]

int ts::UString::superCompare ( const UString & other,
uint32_t flags = SCOMP_DEFAULT,
size_t this_pos = 0,
size_t other_pos = 0 ) const
inline

Compare two strings using various comparison options.

Parameters
[in]otherOther string to compare.
[in]flagsA bitmask of StringComparison values. By default, use a strict comparison.
[in]this_posStarting position in this string. If it points beyond the end of string, consider the string as empty.
[in]other_posStarting position in string other. If it points beyond the end of string, consider the string as empty.
Returns
-1, 0, or 1, if this string is respectively before, equal to, or after other according to flags.

◆ superCompare() [2/2]

int ts::UString::superCompare ( const UChar * other,
uint32_t flags = SCOMP_DEFAULT,
size_t this_pos = 0,
size_t other_pos = 0 ) const
inline

Compare two strings using various comparison options.

Parameters
[in]otherAddress of a nul-terminated UTF-16 string.
[in]flagsA bitmask of StringComparison values. By default, use a strict comparison.
[in]this_posStarting position in this string. If it points beyond the end of string, consider the string as empty.
[in]other_posStarting position in string other. If it points beyond the end of string, consider the string as empty.
Returns
-1, 0, or 1, if this string is respectively before, equal to, or after other according to flags.

◆ SuperCompare()

int ts::UString::SuperCompare ( const UChar * s1,
const UChar * s2,
uint32_t flags = SCOMP_DEFAULT,
size_t s1_pos = 0,
size_t s2_pos = 0 )
static

Compare two strings using various comparison options.

Parameters
[in]s1Address of a nul-terminated UTF-16 string.
[in]s2Address of a nul-terminated UTF-16 string.
[in]flagsA bitmask of StringComparison values. By default, use a strict comparison.
[in]s1_posStarting position in string s1. If it points beyond the end of s1, consider s1 as an empty string.
[in]s2_posStarting position in string s2. If it points beyond the end of s2, consider s2 as an empty string.
Returns
-1, 0, or 1, if s1 is respectively before, equal to, or after s2 according to flags.

◆ similar() [1/3]

bool ts::UString::similar ( const UString & other,
size_t this_pos = 0,
size_t other_pos = 0 ) const
inline

Check if two strings are identical, case-insensitive and ignoring blanks.

Parameters
[in]otherOther string to compare.
[in]this_posStarting position in this string. If it points beyond the end of string, consider the string as empty.
[in]other_posStarting position in string other. If it points beyond the end of string, consider the string as empty.
Returns
True if this string and other are "similar", ie. identical, case-insensitive and ignoring blanks.

◆ similar() [2/3]

bool ts::UString::similar ( const UChar * other,
size_t this_pos = 0,
size_t other_pos = 0 ) const
inline

Check if two strings are identical, case-insensitive and ignoring blanks.

Parameters
[in]otherOther string to compare.
[in]this_posStarting position in this string. If it points beyond the end of string, consider the string as empty.
[in]other_posStarting position in string other. If it points beyond the end of string, consider the string as empty.
Returns
True if this string and other are "similar", ie. identical, case-insensitive and ignoring blanks.

◆ similar() [3/3]

bool ts::UString::similar ( const void * addr,
size_type size,
size_t this_pos = 0,
size_t other_pos = 0 ) const

Check if two strings are identical, case-insensitive and ignoring blanks.

Parameters
[in]addrAddress of second string in UTF-8 representation.
[in]sizeSize in bytes of second string.
[in]this_posStarting position in this string. If it points beyond the end of string, consider the string as empty.
[in]other_posStarting position in string other. If it points beyond the end of string, consider the string as empty.
Returns
True if the strings are "similar", ie. identical, case-insensitive and ignoring blanks

◆ similarAfterLast() [1/3]

bool ts::UString::similarAfterLast ( const UString & other,
UChar separator ) const
inline

Check if two strings are identical, case-insensitive and ignoring blanks, after a delimiter character.

Parameters
[in]otherOther string to compare.
[in]separatorCompare the part of the strings after the last occurrence of that character. If separator is not found in a string, use the complete string.
Returns
True if this string and other are "similar", ie. identical, case-insensitive and ignoring blanks.

◆ similarAfterLast() [2/3]

bool ts::UString::similarAfterLast ( const UChar * other,
UChar separator ) const

Check if two strings are identical, case-insensitive and ignoring blanks, after a delimiter character.

Parameters
[in]otherOther string to compare.
[in]separatorCompare the part of the strings after the last occurrence of that character. If separator is not found in a string, use the complete string.
Returns
True if this string and other are "similar", ie. identical, case-insensitive and ignoring blanks.

◆ similarAfterLast() [3/3]

bool ts::UString::similarAfterLast ( const void * addr,
size_type size,
UChar separator ) const

Check if two strings are identical, case-insensitive and ignoring blanks, after a delimiter character.

Parameters
[in]addrAddress of second string in UTF-8 representation.
[in]sizeSize in bytes of second string.
[in]separatorCompare the part of the strings after the last occurrence of that character. If separator is not found in a string, use the complete string.
Returns
True if the strings are "similar", ie. identical, case-insensitive and ignoring blanks

◆ isContainedSimilarIn()

template<class CONTAINER>
bool ts::UString::isContainedSimilarIn ( const CONTAINER & container,
size_t this_pos = 0 ) const

Check if a container of strings contains something similar to this string.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in]containerA container of UString.
[in]this_posStarting position in this string. If it points beyond the end of string, consider the string as empty.
Returns
True if container contains a string similar to this string.
See also
similar()

◆ findSimilar()

template<class CONTAINER>
CONTAINER::const_iterator ts::UString::findSimilar ( const CONTAINER & container,
size_t this_pos = 0 ) const

Locate into a map or multimap an element with a similar string.

Template Parameters
CONTAINERA map container class using UString as key.
Parameters
[in]containerA map container with UString keys.
[in]this_posStarting position in this string. If it points beyond the end of string, consider the string as empty.
Returns
An iterator to the first element of container with a key value which is similar to this string according to similar(). Return container.end() if not found.
See also
similar()

◆ constantTimeCompare()

int ts::UString::constantTimeCompare ( const UString & secret) const

Compare two strings in constant time. This method is useful to compare a public string (this string, typically an entered password or authentication token) to a secret string (typically the secret password or token). The execution time of this method only depends on the content of this object, not the content of secret. This method is slower than a direct comparison but it executes in constant time.

Parameters
[in]secretA secret string to compare.
Returns
-1, 0, or 1, if this string is respectively before, equal to, or after secret.

◆ save()

bool ts::UString::save ( const fs::path & file_name,
bool append = false,
bool enforce_last_line_feed = false ) const

Save this string into a file, in UTF-8 format.

Parameters
[in]file_nameThe name of the text file where to save this string. If the file path is empty or "-", write to the standard output.
[in]appendIf true, append this string at the end of the file. If false (the default), overwrite the file if it already existed.
[in]enforce_last_line_feedIf true and this string does not end with a line feed, force a final line feed.
Returns
True on success, false on error (mostly file errors).

◆ Save() [1/4]

template<class ITERATOR>
bool ts::UString::Save ( ITERATOR begin,
ITERATOR end,
const fs::path & file_name,
bool append = false )
static

Save strings from a container into a file, in UTF-8 format, one per line. The strings must be located in a container and are accessed through iterators.

Template Parameters
ITERATORAn iterator class over UString as defined by the C++ Standard Template Library (STL).
Parameters
[in]beginAn iterator pointing to the first string.
[in]endAn iterator pointing after the last string.
[in]file_nameThe name of the text file where to save the strings. If the file path is empty or "-", write to the standard output.
[in]appendIf true, append the strings at the end of the file. If false (the default), overwrite the file if it already existed.
Returns
True on success, false on error (mostly file errors).

◆ Save() [2/4]

template<class CONTAINER>
bool ts::UString::Save ( const CONTAINER & container,
const fs::path & file_name,
bool append = false )
static

Save strings from a container into a file, in UTF-8 format, one per line.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in]containerA container of UString containing all strings to save.
[in]file_nameThe name of the text file where to save the strings. If the file path is empty or "-", write to the standard output.
[in]appendIf true, append the strings at the end of the file. If false (the default), overwrite the file if it already existed.
Returns
True on success, false on error (mostly file errors).

◆ Save() [3/4]

template<class ITERATOR>
bool ts::UString::Save ( ITERATOR begin,
ITERATOR end,
std::ostream & strm )
static

Save strings from a container into a stream, in UTF-8 format, one per line. The strings must be located in a container and are accessed through iterators.

Template Parameters
ITERATORAn iterator class over UString as defined by the C++ Standard Template Library (STL).
Parameters
[in]beginAn iterator pointing to the first string.
[in]endAn iterator pointing after the last string.
[in]strmOutput stream.
Returns
True on success, false on error (mostly file errors).

◆ Save() [4/4]

template<class CONTAINER>
bool ts::UString::Save ( const CONTAINER & container,
std::ostream & strm )
static

Save strings from a container into a file, in UTF-8 format, one per line.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in]containerA container of UString containing all strings to save.
[in]strmOutput stream.
Returns
True on success, false on error (mostly file errors).

◆ Load() [1/2]

template<class CONTAINER>
bool ts::UString::Load ( CONTAINER & container,
const fs::path & file_name,
size_t max_lines = NPOS )
static

Load all lines of a text file in UTF-8 format as UString's into a container.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[out]containerA container of UString receiving all lines of the file. Each line of the text file is a separate string.
[in]file_nameThe name of the text file from where to load the strings.
[in]max_linesMaximum number of lines to read. Unlimited by default.
Returns
True on success, false on error (mostly file errors).

◆ LoadAppend() [1/2]

template<class CONTAINER>
bool ts::UString::LoadAppend ( CONTAINER & container,
const fs::path & file_name,
size_t max_lines = NPOS )
static

Load all lines of a text file in UTF-8 format as UString's and append them in a container.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in,out]containerA container of UString receiving all lines of the file. Each line of the text file is a separate string.
[in]file_nameThe name of the text file from where to load the strings. Each line of the text file is inserted as a separate string.
[in]max_linesMaximum number of lines to read. Unlimited by default.
Returns
True on success, false on error (mostly file errors).

◆ Load() [2/2]

template<class CONTAINER>
bool ts::UString::Load ( CONTAINER & container,
std::istream & strm,
size_t max_lines = NPOS )
static

Load all lines of a text file in UTF-8 format as UString's into a container.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[out]containerA container of UString receiving all lines of the file. Each line of the text file is a separate string.
[in,out]strmA standard text stream in input mode. Each line of the text file is inserted as a separate string.
[in]max_linesMaximum number of lines to read. Unlimited by default.
Returns
True on success, false on error (mostly file errors).

◆ LoadAppend() [2/2]

template<class CONTAINER>
bool ts::UString::LoadAppend ( CONTAINER & container,
std::istream & strm,
size_t max_lines = NPOS )
static

Load all lines of a text file in UTF-8 format as UString's and append them in a container.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in,out]containerA container of UString receiving all lines of the file. Each line of the text file is a separate string.
[in,out]strmA standard text stream in input mode. Each line of the text file is inserted as a separate string.
[in]max_linesMaximum number of lines to read. Unlimited by default.
Returns
True on success, false on error (mostly file errors).

◆ getLine()

bool ts::UString::getLine ( std::istream & strm)

Read one UTF-8 line from a text file and load it into this object.

Parameters
[in,out]strmA standard stream in input mode.
Returns
True on success, false on error (mostly file errors).

◆ toBool()

bool ts::UString::toBool ( bool & value) const

Convert a string into a bool value.

This string must contain the representation of an integer value in decimal or hexadecimal (prefix 0x) or one of "false", "true", "yes", "no", "on", "off" (not case sensitive).

Parameters
[out]valueThe returned decoded value. On error value contains false.
Returns
True on success, false on error (invalid string).

◆ BoolNamesList()

UString ts::UString::BoolNamesList ( )
static

Get the list of valid strings for bool values.

Returns
The list of valid strings for bool values.

◆ toTristate()

bool ts::UString::toTristate ( Tristate & value) const

Convert a string into a Tristate value.

This string must contain the representation of an integer value in decimal or hexadecimal (prefix 0x) or one of "false", "true", "yes", "no", "on", "off", "maybe", "unknown" (not case sensitive).

Parameters
[out]valueThe returned decoded value. On error value contains MAYBE.
Returns
True on success, false on error (invalid string).

◆ TristateNamesList()

UString ts::UString::TristateNamesList ( )
static

Get the list of valid strings for Tristate values.

Returns
The list of valid strings for Tristate values.

◆ isInteger()

bool ts::UString::isInteger ( const UString & thousand_separators = UString()) const

Check if the string is a syntactically valid integer.

Parameters
[in]thousand_separatorsA string of characters which are interpreted as thousands separators and are ignored. Any character from the thousand_separators string is interpreted as a separator. Note that this implies that the optional thousands separators may have one character only.
Returns
True if the string is a syntactically valid integer, false otherwise. Note that a string can be a valid integer and may not be convertible into a given integer type, if the corresponding integer value is outside the valid range for the integer type.

◆ toInteger()

template<typename INT>
requires std::integral<INT>
bool ts::UString::toInteger ( INT & value,
const UString & thousand_separators = UString(),
size_type decimals = 0,
const UString & decimal_separators = u".",
INT min_value = std::numeric_limits< INT >::min(),
INT max_value = std::numeric_limits< INT >::max() ) const

Convert a string into an integer.

This string must contain the representation of an integer value in decimal or hexadecimal (prefix 0x). Hexadecimal values are case-insensitive, including the 0x prefix. Leading and trailing spaces are ignored. Optional thousands separators are ignored.

Template Parameters
INTAn integer type, any size, signed or unsigned. The toInteger function decodes integer values of this type.
Parameters
[out]valueThe returned decoded value. On error (invalid string), value contains what could be decoded up to the first invalid character.
[in]thousand_separatorsA string of characters which are interpreted as thousands separators and are ignored. Any character from the thousand_separators string is interpreted as a separator. Note that this implies that the optional thousands separators may have one character only.
[in]decimalsReference number of decimal digits. When decimals is greater than zero, the result is automatically adjusted by the corresponding power of ten. For instance, when decimals is 3, u"12" returns 12000, u"12.34" returns 12340 and "12.345678" returns 12345. All extra decimals are accepted but ignored.
[in]decimal_separatorsA string of characters which are interpreted as decimal point. A decimal point is allowed only in base 10.
[in]min_valueminimum allowed value for the decoded integer.
[in]max_valuemaximum allowed value for the decoded integer.
Returns
True on success, false on error (invalid string).

◆ toIntegers()

template<class CONTAINER>
requires std::integral<typename CONTAINER::value_type>
bool ts::UString::toIntegers ( CONTAINER & container,
const UString & thousand_separators = UString(),
const UString & list_separators = UString(u",; "),
size_type decimals = 0,
const UString & decimal_separators = UString(u"."),
typename CONTAINER::value_type min_value = std::numeric_limits< typename CONTAINER::value_type >::min(),
typename CONTAINER::value_type max_value = std::numeric_limits< typename CONTAINER::value_type >::max() ) const

Convert a string containing a list of integers into a container of integers.

This string must contain the representation of integer values in decimal or hexadecimal (prefix 0x). Hexadecimal values are case-insensitive, including the 0x prefix. Leading and trailing spaces are ignored. Optional thousands separators are ignored. The various integer values in the string are separated using list delimiters.

Template Parameters
CONTAINERA container class of any integer type as defined by the C++ Standard Template Library (STL).
Parameters
[out]containerThe returned decoded values. The previous content of the container is discarded. The integer values are added in the container in the order of the decoded string. On error (invalid string), container contains what could be decoded up to the first invalid character.
[in]thousand_separatorsA string of characters which are interpreted as thousands separators and are ignored. Any character from the thousand_separators string is interpreted as a separator. Note that this implies that the optional thousands separators may have one character only.
[in]list_separatorsA string of characters which are interpreted as list separators. Distinct integer values must be separated by one or more of these separators. Any character from the listSeparators string is interpreted as a separator. Note that this implies that the list separators may have one character only.
[in]decimalsReference number of decimal digits. When decimals is greater than zero, the result is automatically adjusted by the corresponding power of ten. For instance, when decimals is 3, u"12" returns 12000, u"12.34" returns 12340 and "12.345678" returns 12345. All extra decimals are accepted but ignored.
[in]decimal_separatorsA string of characters which are interpreted as decimal point. A decimal point is allowed only in base 10.
[in]min_valueminimum allowed value for the decoded integers.
[in]max_valuemaximum allowed value for the decoded integers.
Returns
True on success, false on error (invalid string).

◆ toFloat()

template<typename FLT>
requires std::floating_point<FLT>
bool ts::UString::toFloat ( FLT & value,
FLT min_value = std::numeric_limits< FLT >::lowest(),
FLT max_value = std::numeric_limits< FLT >::max() ) const

Convert a string into a floating-point.

This string must contain the representation of a floating-point value.

Template Parameters
FLTA floating-point type. The toFloat() function decodes floating-point values of this type.
Parameters
[out]valueThe returned decoded value.
[in]min_valueMinimum allowed value for the decoded value.
[in]max_valueMaximum allowed value for the decoded value.
Returns
True on success, false on error (invalid string).

◆ Decimal() [1/2]

template<typename INT>
requires ts::int_enum<INT>
UString ts::UString::Decimal ( INT value,
size_type min_width = 0,
bool right_justified = true,
const UString & separator = DEFAULT_THOUSANDS_SEPARATOR,
bool force_sign = false,
UChar pad = SPACE )
static

Format a string containing a decimal value.

Template Parameters
INTAn integer type.
Parameters
[in]valueThe integer value to format.
[in]min_widthMinimum width of the returned string. Padded with spaces if larger than the number of characters in the formatted number.
[in]right_justifiedIf true (the default), return a right-justified string. When false, return a left-justified string. Ignored if min_width is lower than the number of characters in the formatted number.
[in]separatorSeparator string for groups of thousands, a comma by default.
[in]force_signIf true, force a '+' sign for positive values.
[in]padThe padding character to adjust the width.
Returns
The formatted string.

◆ Decimal() [2/2]

template<class CONTAINER>
requires ts::int_enum<typename CONTAINER::value_type>
UString ts::UString::Decimal ( const CONTAINER & values,
const UString & separator = UString(u", "),
bool force_sign = false )
static

Format a string containing a list of decimal values.

Template Parameters
CONTAINERA container class of any integer type as defined by the C++ Standard Template Library (STL).
Parameters
[in]valuesThe integer values to format.
[in]separatorSeparator string between values, a comma by default.
[in]force_signIf true, force a '+' sign for positive values.
Returns
The formatted string.

◆ Hexa()

template<typename INT>
requires std::integral<INT>
UString ts::UString::Hexa ( INT value,
size_type width = 0,
const UString & separator = UString(),
bool use_prefix = true,
bool use_upper = true )
static

Format a string containing an hexadecimal value.

Template Parameters
INTAn integer type.
Parameters
[in]valueThe integer value to format.
[in]widthWidth of the formatted number, not including the optional prefix and separator. By default, use the "natural" size of INT (e.g. 8 for 32-bit integer).
[in]separatorSeparator string for groups of 4 digits, empty by default.
[in]use_prefixIf true, prepend the standard hexa prefix "0x".
[in]use_upperIf true, use upper-case hexadecimal digits.
Returns
The formatted string.

◆ HexaMin()

template<typename INT>
requires std::integral<INT>
UString ts::UString::HexaMin ( INT value,
size_type min_width = 0,
const UString & separator = UString(),
bool use_prefix = true,
bool use_upper = true )
static

Format a string containing an hexadecimal value. This version differ from Hexa() in the interpretation of the @ min_width argument.

Template Parameters
INTAn integer type.
Parameters
[in]valueThe integer value to format.
[in]min_widthMinimum width of the returned string, including the optional prefix and separator. By default, use the "natural" size of INT (e.g. 8 for 32-bit integer) plus prefix and separator.
[in]separatorSeparator string for groups of 4 digits, empty by default.
[in]use_prefixIf true, prepend the standard hexa prefix "0x".
[in]use_upperIf true, use upper-case hexadecimal digits.
Returns
The formatted string.

◆ Float()

UString ts::UString::Float ( double value,
size_type width = 0,
size_type precision = 0,
bool force_sign = false )
static

Format a string containing a floating point value.

Parameters
[in]valueThe floating point value to format.
[in]widthWidth of the formatted number, not including the optional prefix and separator.
[in]precisionPrecision to use after the decimal point. Default is 6 digits when set to zero.
[in]force_signIf true, force a '+' sign for positive values.
Returns
The formatted string.

◆ toChrono()

template<class Rep, class Period>
bool ts::UString::toChrono ( cn::duration< Rep, Period > & value,
const UString & thousand_separators = UString(),
const cn::duration< Rep, Period > & min_value = cn::duration< Rep, Period >::min(),
const cn::duration< Rep, Period > & max_value = cn::duration< Rep, Period >::max() ) const

Convert a string into a std::chrono::duration value. No suffix is decoded. The string shall contain an integer value which is interpreted in units of the temaplte std::chrono::duration type.

Parameters
[out]valueThe returned decoded value. On error (invalid string), value contains what could be decoded up to the first invalid character.
[in]thousand_separatorsA string of characters which are interpreted as thousands separators and are ignored. Any character from the thousand_separators string is interpreted as a separator. Note that this implies that the optional thousands separators may have one character only.
[in]min_valueminimum allowed value for the decoded value.
[in]max_valuemaximum allowed value for the decoded value.
Returns
True on success, false on error (invalid string).

◆ Chrono()

template<class Rep, class Period>
UString ts::UString::Chrono ( const cn::duration< Rep, Period > & value,
bool short_format = false,
const UString & separator = DEFAULT_THOUSANDS_SEPARATOR,
bool force_sign = false )
inlinestatic

Format a string containing a std::chrono::duration value, with units. This function returns one single value, e.g. "12345 ms". Use Duration() for a string with hours, minutes, seconds, milliseconds.

Parameters
[in]valueThe chrono value to format.
[in]short_formatWhen true, use short unit format (e.g. "ms"). By default, use a full unit name (e.g. "millisecond").
[in]separatorSeparator string for groups of thousands, a comma by default.
[in]force_signIf true, force a '+' sign for positive values.
Returns
The formatted string.
See also
Duration()

◆ Duration()

template<class Rep, class Period>
UString ts::UString::Duration ( const cn::duration< Rep, Period > & value,
bool with_days = false )
inlinestatic

Format a string representing a std::chrono::duration value, with hours, minutes, seconds, milliseconds.

Parameters
[in]valueThe chrono value to format.
[in]with_daysWhen true, add a number of days when necessary. By default, use number of hours above 24.
Returns
The formatted string.
See also
Chrono()

◆ ChronoUnit() [1/2]

template<class DURATION>
requires std::integral<typename DURATION::rep>
UString ts::UString::ChronoUnit ( bool short_format = false,
bool plural = false )
inlinestatic

Format the name of an instance of std::chrono::duration.

Template Parameters
DURATIONAn instance of std::chrono::duration.
Parameters
[in]short_formatWhen true, use short unit format (e.g. "ms"). By default, use a full unit name (e.g. "millisecond").
[in]pluralWhen true, use the plural form (full unit name only, e.g. "milliseconds").
Returns
A string representing the unit of the DURATION.

◆ ChronoUnit() [2/2]

UString ts::UString::ChronoUnit ( std::intmax_t num,
std::intmax_t den,
bool short_format = false,
bool plural = false )
static

Format the name of an instance of std::chrono::duration based on its ratio values.

Parameters
[in]numRatio numerator.
[in]denRatio denominator.
[in]short_formatWhen true, use short unit format (e.g. "ms"). By default, use a full unit name (e.g. "millisecond").
[in]pluralWhen true, use the plural form (full unit name only, e.g. "milliseconds").
Returns
A string representing the unit of the DURATION.

◆ format() [1/2]

template<class... Args>
void ts::UString::format ( const UChar * fmt,
Args &&... args )
inline

Format a string using a template and arguments.

The formatted string is appended to this string object.

This method is similar in principle to printf(). The fmt paramter is used as a format or template where sequences starting with '%' are place-holders for arguments. The main different with printf() is that the argument list is typed, thanks to C++ features. Thus, the risk of mismatch or crash is eliminated. When a '%' sequence is formatted, the presence and type of the corresponding argument is known. For this reason, the syntax of the '%' sequences is simplified.

The available '%' sequences are:

  • %s : String. Treated as %d if the argument is an integer. Print true or false if the argument is a bool. With std::chrono::duration value, add the unit (e.g. "seconds", "milliseconds", etc.)
  • %c : Character. Use integer argument as Unicode code point. Treated as %s if the argument is a string.
  • %d : Integer in decimal. Treated as %s if the argument is a string. If argument os a fixed point value, print its integral part.
  • %x : Integer in lowercase hexadecimal. Treated as %s if the argument is a string.
  • %X : Integer in uppercase hexadecimal. Treated as %s if the argument is a string.
  • %n : Integer in "normalized" hexadecimal and decimal format. Equivalent to 0xX (%<d). Treated as %s if the argument is a string.
  • %f : Floating or fixed point value. Treated as %s if the argument is a string.
  • %% : Insert a literal %.

The allowed options, between the '%' and the letter are, in this order:

  • < : Reuse previous argument value, do not advance in argument list.
  • - : Left-justified (right-justified by default).
  • + : Force a '+' sign with positive decimal integers or floating point values (%d or %f only).
  • 0 : Zero padding for integers. This is the default with %x and %X.
  • digits : Minimum field width. This is a display width, not a number of characters for strings. With %x or %X, the default width is the "natural" width of the parameter (e.g. 8 digits for a uint32_t value without thousands separator).
  • . digits : Starting with a dot. Maximum field width for strings or precision for floating point values. Ignored for integers.
  • ' : For integer conversions, use a separator for groups of thousands.
  • ! : Short format. With std::chrono::duration value, use "ms" instead of "milliseconds", etc.
  • * : Can be used instead of digits. The integer value is taken from the argument list.

The field width is limited to MAX_FIELD_WIDTH characters.

Since the argument list is typed, it is possible to mix integers and strings of various types and sizes. Example:

int i = -1234;
uint16_t u16 = 128;
ts::UString us(u"abc");
std::string s("def");
std::cout << ts::UString::Format(u"i = %'d, u16 = 0x%X, %d %s %s %s %s", i, u16, 27, us, s, u"ghi", "jkl");
static UString Format(const UChar *fmt, Args &&... args)
Definition tsUString.h:2381

displays:

i = -1,234, u16 = 0x0080, 27 abc def ghi jkl

Incorrect format specifiers are silently ignored. Extraneous or missing parameters are also silently ignored. Incorrect types are fixed when possible. To report all these discrepancies, define the environment variable TSDUCK_FORMAT_DEBUG and error messages will be reported on standard error.

Sample incorrect formats or combination of arguments:

ts::UString::Format(u"a) %d %d", 1, 2, 3, 4); // return "a) 1 2"
ts::UString::Format(u"b) %d %d", 1); // return "b) 1 "
ts::UString::Format(u"c) %d %d", 1, u"abc"); // return "c) 1 abc"
ts::UString::Format(u"d) %d %s", 1, 2); // return "d) 1 2"
ts::UString::Format(u"e) ab%scd%sef", u"X"); // return "e) abXcdef"
ts::UString::Format(u"f) %d %01", 1, 2, 3); // return "f) 1 "

To report errors which are otherwise silently fixed:

$ utests
$
$ export TSDUCK_FORMAT_DEBUG=true
$ utests
[FORMATDBG] extraneous 2 arguments at position 8 in format string: "a) %d %d"
[FORMATDBG] missing argument for sequence %d at position 8 in format string: "b) %d %d"
[FORMATDBG] type mismatch, got a string for sequence %d at position 8 in format string: "c) %d %d"
[FORMATDBG] type mismatch, got an integer for sequence %s at position 8 in format string: "d) %d %s"
[FORMATDBG] missing argument for sequence %s at position 11 in format string: "e) ab%scd%sef"
[FORMATDBG] invalid '%' sequence at position 9 in format string: "f) %d %01"
[FORMATDBG] extraneous 2 arguments at position 9 in format string: "f) %d %01"
$
void format(const UChar *fmt, Args &&... args)
Definition tsUString.h:2355
Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.

◆ format() [2/2]

template<class... Args>
void ts::UString::format ( const UString & fmt,
Args &&... args )
inline

Format a string using a template and arguments. The formatted string is appended to this string object.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
See also
format()

◆ Format() [1/2]

template<class... Args>
UString ts::UString::Format ( const UChar * fmt,
Args &&... args )
inlinestatic

Format a string using a template and arguments.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
Returns
The formatted string.
See also
format()

◆ Format() [2/2]

template<class... Args>
UString ts::UString::Format ( const UString & fmt,
Args &&... args )
inlinestatic

Format a string using a template and arguments.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of arguments to substitute in the format string.
Returns
The formatted string.
See also
format()

◆ scan() [1/4]

template<class... Args>
bool ts::UString::scan ( size_t & extracted_count,
size_type & end_index,
const UChar * fmt,
Args &&... args ) const
inline

Scan this string for integer or character values using a template and arguments.

This method is similar in principle to scanf(). The fmt paramter is used as a format or template where sequences starting with '%' are place-holders for arguments. The main different with scanf() is that the argument list is typed, thanks to C++ features. Thus, the risk of mismatch or crash is eliminated. When a '%' sequence is matched, the presence and type of the corresponding argument is known. For this reason, the syntax of the '%' sequences is simplified.

All spaces in the input string are ignored. A sequence of space characters only forces a separation between two fields. Other characters in fmt, outside '' sequences, must match the corresponding character in the input string. Scanning the input string stops when a match fails.

The available '%' sequences are:

  • %d : Matches an integer in decimal or hexadecimal. If the field starts with 0x or 0X, the value is interpreted as hexadecimal. Decimal otherwise.
  • %i : Same as %d.
  • %x : Matches an integer in hexadecimal, case-insensitive, without 0x or 0X prefix.
  • %X : Same as %x.
  • %f : Matches a floating point value.
  • %c : Matches the next non-space character. The Unicode code point is returned.
  • %% : Matches a literal %.

The allowed options, between the '%' and the letter are, in this order:

  • ' : For decimal integer conversions, ignore separator for groups of thousands.
Parameters
[out]extracted_countThe number of successfully extracted values.
[out]end_indexThe index in this string after the last extracted value.
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of output arguments to receive extracted values. The args list is built from pointers to integer data of any size, signed or unsigned.
Returns
True if the entire string is consumed and the entire format is parsed. False otherwise. In other words, the method returns true when this object string exactly matches the format in fmt.
See also
Format(const UChar*, std::initializer_list<ArgMixIn>)

◆ scan() [2/4]

template<class... Args>
bool ts::UString::scan ( size_t & extracted_count,
size_type & end_index,
const UString & fmt,
Args &&... args ) const
inline

Scan this string for integer or character values using a template and arguments.

Parameters
[out]extracted_countThe number of successfully extracted values.
[out]end_indexThe index in this string after the last extracted value.
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of output arguments to receive extracted values. The args list is built from pointers to integer data of any size, signed or unsigned.
Returns
True if the entire string is consumed and the entire format is parsed. False otherwise. In other words, the method returns true when this object string exactly matches the format in fmt.
See also
scan()

◆ scan() [3/4]

template<class... Args>
bool ts::UString::scan ( const UChar * fmt,
Args &&... args ) const
inline

Scan this string for integer or character values using a template and arguments.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of output arguments to receive extracted values. The args list is built from pointers to integer data of any size, signed or unsigned.
Returns
True if the entire string is consumed and the entire format is parsed. False otherwise. In other words, the method returns true when this object string exactly matches the format in fmt.
See also
scan(size_t&, size_type&, const UChar*, std::initializer_list<ArgMixOut>)

◆ scan() [4/4]

template<class... Args>
bool ts::UString::scan ( const UString & fmt,
Args &&... args ) const
inline

Scan this string for integer or character values using a template and arguments.

Parameters
[in]fmtFormat string with embedded '%' sequences.
[in]argsList of output arguments to receive extracted values. The args list is built from pointers to integer data of any size, signed or unsigned.
Returns
True if the entire string is consumed and the entire format is parsed. False otherwise. In other words, the method returns true when this object string exactly matches the format in fmt.
See also
scan(size_t&, size_type&, const UChar*, std::initializer_list<ArgMixOut>)

◆ Dump() [1/2]

UString ts::UString::Dump ( const void * data,
size_type size,
uint32_t flags = HEXA,
size_type indent = 0,
size_type line_width = DEFAULT_HEXA_LINE_WIDTH,
size_type init_offset = 0,
size_type inner_indent = 0 )
static

Build a multi-line string containing the hexadecimal dump of a memory area.

Parameters
[in]dataStarting address of the memory area to dump.
[in]sizeSize in bytes of the memory area to dump.
[in]flagsA combination of option flags indicating how to format the data. This is typically the result of or'ed values from the enum type HexaFlags.
[in]indentEach line is indented by this number of characters.
[in]line_widthMaximum number of characters per line. If the flag BPL is specified, line_width is interpreted as the number of displayed byte values per line.
[in]init_offsetIf the flag OFFSET is specified, an offset in the memory area is displayed at the beginning of each line. In this case, init_offset specified the offset value for the first byte.
[in]inner_indentAdd this indentation before hexa/ascii dump, after offset.
Returns
A string containing the formatted hexadecimal dump. Lines are separated with embedded new-line characters.
See also
HexaFlags

◆ Dump() [2/2]

UString ts::UString::Dump ( const ByteBlock & bb,
uint32_t flags = HEXA,
size_type indent = 0,
size_type line_width = DEFAULT_HEXA_LINE_WIDTH,
size_type init_offset = 0,
size_type inner_indent = 0 )
static

Build a multi-line string containing the hexadecimal dump of a memory area.

Parameters
[in]bbByte block to dump.
[in]flagsA combination of option flags indicating how to format the data. This is typically the result of or'ed values from the enum type HexaFlags.
[in]indentEach line is indented by this number of characters.
[in]line_widthMaximum number of characters per line. If the flag BPL is specified, line_width is interpreted as the number of displayed byte values per line.
[in]init_offsetIf the flag OFFSET is specified, an offset in the memory area is displayed at the beginning of each line. In this case, init_offset specified the offset value for the first byte.
[in]inner_indentAdd this indentation before hexa/ascii dump, after offset.
Returns
A string containing the formatted hexadecimal dump. Lines are separated with embedded new-line characters.
See also
HexaFlags

◆ appendDump() [1/2]

void ts::UString::appendDump ( const void * data,
size_type size,
uint32_t flags = HEXA,
size_type indent = 0,
size_type line_width = DEFAULT_HEXA_LINE_WIDTH,
size_type init_offset = 0,
size_type inner_indent = 0 )

Append a multi-line string containing the hexadecimal dump of a memory area.

Parameters
[in]dataStarting address of the memory area to dump.
[in]sizeSize in bytes of the memory area to dump.
[in]flagsA combination of option flags indicating how to format the data. This is typically the result of or'ed values from the enum type HexaFlags.
[in]indentEach line is indented by this number of characters.
[in]line_widthMaximum number of characters per line. If the flag BPL is specified, line_width is interpreted as the number of displayed byte values per line.
[in]init_offsetIf the flag OFFSET is specified, an offset in the memory area is displayed at the beginning of each line. In this case, init_offset specified the offset value for the first byte.
[in]inner_indentAdd this indentation before hexa/ascii dump, after offset.
See also
HexaFlags

◆ appendDump() [2/2]

void ts::UString::appendDump ( const ByteBlock & bb,
uint32_t flags = HEXA,
size_type indent = 0,
size_type line_width = DEFAULT_HEXA_LINE_WIDTH,
size_type init_offset = 0,
size_type inner_indent = 0 )

Append a multi-line string containing the hexadecimal dump of a memory area.

Parameters
[in]bbByte block to dump.
[in]flagsA combination of option flags indicating how to format the data. This is typically the result of or'ed values from the enum type HexaFlags.
[in]indentEach line is indented by this number of characters.
[in]line_widthMaximum number of characters per line. If the flag BPL is specified, line_width is interpreted as the number of displayed byte values per line.
[in]init_offsetIf the flag OFFSET is specified, an offset in the memory area is displayed at the beginning of each line. In this case, init_offset specified the offset value for the first byte.
[in]inner_indentAdd this indentation before hexa/ascii dump, after offset.
See also
HexaFlags

◆ hexaDecode()

bool ts::UString::hexaDecode ( ByteBlock & result,
bool c_style = false ) const

Interpret this string as a sequence of hexadecimal digits (ignore blanks).

Parameters
[out]resultDecoded bytes.
[in]c_styleIf true, allow "C-style" aggregate (ignore commas, braces and "0x").
Returns
True on success, false on error (invalid hexa format). When returning false, the result contains everything that could be decoded before getting the error.

◆ hexaDecodeAppend()

bool ts::UString::hexaDecodeAppend ( ByteBlock & result,
bool c_style = false ) const

Interpret this string as a sequence of hexadecimal digits (ignore blanks).

Parameters
[in,out]resultThe decoded bytes are added at the end of the previous content.
[in]c_styleIf true, allow "C-style" aggregate (ignore commas, braces and "0x").
Returns
True on success, false on error (invalid hexa format). When returning false, the result contains everything that could be decoded before getting the error.

◆ Append() [1/2]

template<class CONTAINER>
CONTAINER & ts::UString::Append ( CONTAINER & container,
int argc,
const char *const argv[] )
static

Append an array of C-strings to a container of strings. All C-strings from an array are appended at the end of a container. The argc / argv pair is typically received by a main program from a command line.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in,out]containerA container of UString.
[in]argcThe number of C-strings in argv.
[in]argvAn array of C-strings.
Returns
A reference to container.

◆ Append() [2/2]

template<class CONTAINER>
CONTAINER & ts::UString::Append ( CONTAINER & container,
int argc,
char *const argv[] )
inlinestatic

Append an array of C-strings to a container of strings. All C-strings from an array are appended at the end of a container. The argc / argv pair is typically received by a main program from a command line.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[in,out]containerA container of UString.
[in]argcThe number of C-strings in argv.
[in]argvAn array of C-strings.
Returns
A reference to container.

◆ Assign() [1/2]

template<class CONTAINER>
CONTAINER & ts::UString::Assign ( CONTAINER & container,
int argc,
const char *const argv[] )
inlinestatic

Assign an array of C-strings to a container of strings. The container is assigned using all C-strings from an array. The argc / argv pair is typically received by a main program from a command line.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[out]containerA container of UString.
[in]argcThe number of C-strings in argv.
[in]argvAn array of C-strings.
Returns
A reference to container.

◆ Assign() [2/2]

template<class CONTAINER>
CONTAINER & ts::UString::Assign ( CONTAINER & container,
int argc,
char *const argv[] )
inlinestatic

Assign an array of C-strings to a container of strings. The container is assigned using all C-strings from an array. The argc / argv pair is typically received by a main program from a command line.

Template Parameters
CONTAINERA container class of UString as defined by the C++ Standard Template Library (STL).
Parameters
[out]containerA container of UString.
[in]argcThe number of C-strings in argv.
[in]argvAn array of C-strings.
Returns
A reference to container.

Member Data Documentation

◆ UTF8_BOM

const char* ts::UString::UTF8_BOM = "\xEF\xBB\xBF"
staticconstexpr

The 3-byte so-called "UTF-8 Byte Order Mark".

◆ UTF8_BOM_SIZE

size_type ts::UString::UTF8_BOM_SIZE = 3
staticconstexpr

Size in bytes of the so-called "UTF-8 Byte Order Mark".

◆ UTF8_CHAR_MAX_SIZE

size_type ts::UString::UTF8_CHAR_MAX_SIZE = 4
staticconstexpr

Maximum size in bytes of an UTF-8 encoded character.

◆ EOL

const UChar* ts::UString::EOL
staticconstexpr
Initial value:
=
u"\r\n"

End-of-line sequence for the operating system.

◆ DEFAULT_THOUSANDS_SEPARATOR

const UChar* ts::UString::DEFAULT_THOUSANDS_SEPARATOR = u","
staticconstexpr

Default separator string for groups of thousands, a comma.

◆ DEFAULT_HEXA_LINE_WIDTH

size_type ts::UString::DEFAULT_HEXA_LINE_WIDTH = 78
staticconstexpr

Default line width for the Hexa() family of methods.

◆ DEFAULT_SPECIAL_CHARACTERS

const UChar* ts::UString::DEFAULT_SPECIAL_CHARACTERS = u"\"'`;$*?&(){}[]"
staticconstexpr

The default list of characters to be protected by quoted().

◆ DEFAULT_QUOTE_CHARACTERS

const UChar* ts::UString::DEFAULT_QUOTE_CHARACTERS = u"\"'"
staticconstexpr

The default list of acceptable quote characters.

◆ MAX_FIELD_WIDTH

size_t ts::UString::MAX_FIELD_WIDTH = 4096
staticconstexpr

Maximum allowed field width in format strings.

See also
format()

The documentation for this class was generated from the following file: