TSDuck v3.38-3675
MPEG Transport Stream Toolkit
Loading...
Searching...
No Matches
ts::UString Class Reference

An implementation of UTF-16 strings. More...

#include <tsUString.h>

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

Classes

class  RegisterChronoUnit
 A class to register new std::chrono::duration units. More...
 

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
}
 Flags for the Hexa() family of methods. More...
 
using SuperClass = std::u16string
 Explicit reference to superclass.
 

Public Member Functions

 UString () noexcept(noexcept(allocator_type()))
 Default constructor.
 
 UString (const ::WCHAR *s, const allocator_type &alloc=allocator_type())
 Constructor using a null-terminated Windows Unicode string (Windows-specific).
 
 UString (const ::WCHAR *s, size_type count, const allocator_type &alloc=allocator_type())
 Constructor using a Windows Unicode string (Windows-specific).
 
 UString (const allocator_type &alloc) noexcept
 Constructor using an allocator.
 
 UString (const char *utf8)
 Constructor from an UTF-8 string.
 
 UString (const char *utf8, size_type count)
 Constructor from an UTF-8 string.
 
 UString (const fs::path &p)
 Constructor from a std::filesystem::path.
 
template<typename CHARTYPE , std::size_t SIZE>
 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<typename CHARTYPE , std::size_t SIZE, typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
 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.
 
 UString (const std::string &utf8)
 Constructor from an UTF-8 string.
 
template<typename CHARTYPE >
 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<typename CHARTYPE , typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
 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.
 
 UString (const SuperClass &other)
 Copy constructor.
 
 UString (const SuperClass &other, size_type pos, size_type count, const allocator_type &alloc=allocator_type())
 Constructor using a substring.
 
 UString (const UChar *s, const allocator_type &alloc=allocator_type())
 Constructor using a null-terminated Unicode string.
 
 UString (const UChar *s, size_type count, const allocator_type &alloc=allocator_type())
 Constructor using a Unicode string.
 
template<class InputIt >
 UString (InputIt first, InputIt last, const allocator_type &alloc=allocator_type())
 Constructor from iterators.
 
 UString (size_type count, UChar ch, const allocator_type &alloc=allocator_type())
 Constructor using a repetition of the same character.
 
 UString (std::initializer_list< UChar > init, const allocator_type &alloc=allocator_type())
 Constructor from an initializer list.
 
 UString (SuperClass &&other) noexcept
 Move constructor.
 
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)
 Append a multi-line string containing the hexadecimal dump of a memory area.
 
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)
 Append a multi-line string containing the hexadecimal dump of a memory area.
 
template<typename CHARTYPE , std::size_t SIZE>
UStringassign (const std::array< CHARTYPE, SIZE > &arr)
 Assign from a std::array of 16-bit characters of any type.
 
template<typename CHARTYPE , std::size_t SIZE, typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
UStringassign (const std::array< CHARTYPE, SIZE > &arr, INT count)
 Assign from a std::array of 16-bit characters of any type.
 
template<typename CHARTYPE >
UStringassign (const std::vector< CHARTYPE > &vec)
 Assign from a std::vector of 16-bit characters of any type.
 
template<typename CHARTYPE , typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
UStringassign (const std::vector< CHARTYPE > &vec, INT count)
 Assign from a std::vector of 16-bit characters of any type.
 
UStringassignFromUTF8 (const char *utf8)
 Convert an UTF-8 string into this object.
 
UStringassignFromUTF8 (const char *utf8, size_type count)
 Convert an UTF-8 string into this object.
 
UStringassignFromUTF8 (const std::string &utf8)
 Convert an UTF-8 string into this object.
 
UStringassignFromWChar (const std::wstring &wstr)
 Convert a C++ "wide string" into this object.
 
UStringassignFromWChar (const wchar_t *wstr)
 Convert a C++ "wide string" into this object.
 
UStringassignFromWChar (const wchar_t *wstr, size_type count)
 Convert a C++ "wide string" into this object.
 
void combineDiacritical ()
 Combine all possible diacritical marks.
 
size_t commonPrefixSize (const UString &str, CaseSensitivity cs=CASE_SENSITIVE) const
 Compute the number of similar leading characters in two strings.
 
size_t commonSuffixSize (const UString &str, CaseSensitivity cs=CASE_SENSITIVE) const
 Compute the number of similar trailing characters in two strings.
 
bool contain (const UString &substring, CaseSensitivity cs=CASE_SENSITIVE) const
 Check if a string contains a specified substring.
 
bool contain (UChar c) const
 Check if a string contains a specified character.
 
void convertFromHTML ()
 Convert all HTML entities in the string into plain characters.
 
void convertFromJSON ()
 Convert all JSON backslash sequences in the string into plain characters.
 
void convertToHTML (const UString &convert=UString())
 Convert the string into a suitable HTML representation.
 
void convertToJSON ()
 Convert the string into a suitable JSON representation.
 
void convertToLower ()
 Convert the string to lower-case.
 
void convertToUpper ()
 Convert the string to uper-case.
 
void decomposeDiacritical ()
 Decompose all precombined characters.
 
size_type displayPosition (size_type count, size_type from=0, StringDirection direction=LEFT_TO_RIGHT) const
 Count displayed positions inside a string.
 
bool endWith (const UString &suffix, CaseSensitivity cs=CASE_SENSITIVE, bool skip_space=false) const
 Check if a string ends with a specified suffix.
 
template<class CONTAINER >
CONTAINER::const_iterator findSimilar (const CONTAINER &container) const
 Locate into a map or multimap an element with a similar string.
 
void format (const UChar *fmt, std::initializer_list< ArgMixIn > args)
 Format a string using a template and arguments.
 
void format (const UString &fmt, std::initializer_list< ArgMixIn > args)
 Format a string using a template and arguments.
 
UString fromHTML () const
 Return the string with all HTML entities converted into plain characters.
 
UString fromJSON () const
 Return the string with all JSON backslash sequences converted into plain characters.
 
template<class CONTAINER >
void fromQuotedLine (CONTAINER &container, const UString &quoteCharacters=DEFAULT_QUOTE_CHARACTERS, const UString &specialCharacters=DEFAULT_SPECIAL_CHARACTERS) const
 Split this string in space-separated possibly-quoted elements.
 
bool getLine (std::istream &strm)
 Read one UTF-8 line from a text file and load it into this object.
 
bool hexaDecode (ByteBlock &result, bool c_style=false) const
 Interpret this string as a sequence of hexadecimal digits (ignore blanks).
 
bool hexaDecodeAppend (ByteBlock &result, bool c_style=false) const
 Interpret this string as a sequence of hexadecimal digits (ignore blanks).
 
void indent (size_t size)
 Indent all lines in the string.
 
template<class CONTAINER >
bool isContainedSimilarIn (const CONTAINER &container) const
 Check if a container of strings contains something similar to this string.
 
void justify (const UString &right, size_type width, UChar pad=SPACE, size_t spacesAroundPad=0)
 Justify string, pad in the middle.
 
void justifyCentered (size_type width, UChar pad=SPACE, bool truncate=false, size_t spacesAroundPad=0)
 Centered-justified (pad and optionally truncate) string.
 
void justifyLeft (size_type width, UChar pad=SPACE, bool truncate=false, size_t spacesBeforePad=0)
 Left-justify (pad and optionally truncate) string.
 
void justifyRight (size_type width, UChar pad=SPACE, bool truncate=false, size_t spacesAfterPad=0)
 Right-justified (pad and optionally truncate) string.
 
UCharlast ()
 Get the address after the last character in the string.
 
const UCharlast () const
 Get the address after the last character in the string.
 
 operator fs::path () const
 Conversion operator from ts::UString to std::filesystem::path.
 
bool operator== (const fs::path &other) const
 Comparison operator with std::filesystem::path.
 
void quoted (UChar quoteCharacter=u'\'', const UString &specialCharacters=DEFAULT_SPECIAL_CHARACTERS, bool forceQuote=false)
 Replace the string with a "quoted" version of it.
 
template<class CONTAINER >
void quotedLine (const CONTAINER &container, UChar quoteCharacter=u'\'', const UString &specialCharacters=DEFAULT_SPECIAL_CHARACTERS)
 Convert a container of strings into one big string where all elements are properly quoted when necessary.
 
void remove (const UString &substr)
 Remove all occurences of a substring.
 
void remove (UChar c)
 Remove all occurences of a character.
 
void removePrefix (const UString &prefix, CaseSensitivity cs=CASE_SENSITIVE)
 Remove a prefix in string.
 
void removeSuffix (const UString &suffix, CaseSensitivity cs=CASE_SENSITIVE)
 Remove a suffix in string.
 
void reverse ()
 Reverse the order of characters in the string.
 
bool save (const fs::path &fileName, bool append=false, bool enforceLastLineFeed=false) const
 Save this string into a file, in UTF-8 format.
 
bool scan (const UChar *fmt, std::initializer_list< ArgMixOut > args) const
 Scan this string for integer or character values using a template and arguments.
 
bool scan (const UString &fmt, std::initializer_list< ArgMixOut > args) const
 Scan this string for integer or character values using a template and arguments.
 
bool scan (size_t &extractedCount, size_type &endIndex, const UChar *fmt, std::initializer_list< ArgMixOut > args) const
 Scan this string for integer or character values using a template and arguments.
 
bool scan (size_t &extractedCount, size_type &endIndex, const UString &fmt, std::initializer_list< ArgMixOut > args) const
 Scan this string for integer or character values using a template and arguments.
 
bool similar (const UChar *other) const
 Check if two strings are identical, case-insensitive and ignoring blanks.
 
bool similar (const UString &other) const
 Check if two strings are identical, case-insensitive and ignoring blanks.
 
bool similar (const void *addr, size_type size) const
 Check if two strings are identical, case-insensitive and ignoring blanks.
 
template<class CONTAINER >
void split (CONTAINER &container, UChar separator=COMMA, bool trimSpaces=true, bool removeEmpty=false) const
 Split the string into segments based on a separator character (comma by default).
 
template<class CONTAINER >
void splitAppend (CONTAINER &container, UChar separator=COMMA, bool trimSpaces=true, bool removeEmpty=false) const
 Split the string into segments based on a separator character (comma by default).
 
template<class CONTAINER >
void splitBlocks (CONTAINER &container, UChar startWith=u'[', UChar endWith=u']', bool trimSpaces=true) const
 Split a string into segments which are identified by their starting / ending characters (respectively "[" and "]" by default).
 
template<class CONTAINER >
void splitBlocksAppend (CONTAINER &container, UChar startWith=u'[', UChar endWith=u']', bool trimSpaces=true) const
 Split a string into segments which are identified by their starting / ending characters (respectively "[" and "]" by default).
 
template<class CONTAINER >
void splitLines (CONTAINER &container, size_type maxWidth, const UString &otherSeparators=UString(), const UString &nextMargin=UString(), bool forceSplit=false) const
 Split a string into multiple lines which are not longer than a specified maximum width.
 
template<class CONTAINER >
void splitLinesAppend (CONTAINER &container, size_type maxWidth, const UString &otherSeparators=UString(), const UString &nextMargin=UString(), bool forceSplit=false) const
 Split a string into multiple lines which are not longer than a specified maximum width.
 
template<class CONTAINER >
void splitShellStyle (CONTAINER &container) const
 Split the string into shell-style arguments.
 
template<class CONTAINER >
void splitShellStyleAppend (CONTAINER &container) const
 Split the string into shell-style arguments.
 
bool startWith (const UString &prefix, CaseSensitivity cs=CASE_SENSITIVE, bool skip_space=false) const
 Check if the string starts with a specified prefix.
 
void substitute (const UString &value, const UString &replacement)
 Substitute all occurences of a string with another one.
 
void substitute (UChar value, UChar replacement)
 Substitute all occurences of a character with another one.
 
int superCompare (const UChar *other, uint32_t flags=SCOMP_DEFAULT) const
 Compare two strings using various comparison options.
 
int superCompare (const UString &other, uint32_t flags=SCOMP_DEFAULT) const
 Compare two strings using various comparison options.
 
bool toBool (bool &value) const
 Convert a string into a bool value.
 
template<class Rep , class Period >
bool toChrono (cn::duration< Rep, Period > &value, const UString &thousandSeparators=UString(), const cn::duration< Rep, Period > &minValue=cn::duration< Rep, Period >::min(), const cn::duration< Rep, Period > &maxValue=cn::duration< Rep, Period >::max()) const
 Convert a string into a std::chrono::duration value.
 
UString toCombinedDiacritical () const
 Return a string with all possible diacritical marks combined.
 
UString toDecomposedDiacritical () const
 Return a string with all precombined characters decomposed.
 
template<typename FLT , typename std::enable_if< std::is_floating_point< FLT >::value >::type * = nullptr>
bool toFloat (FLT &value, FLT minValue=std::numeric_limits< FLT >::lowest(), FLT maxValue=std::numeric_limits< FLT >::max()) const
 Convert a string into a floating-point.
 
UString toHTML (const UString &convert=UString()) const
 Return the string in a suitable HTML representation.
 
UString toIndented (size_t size) const
 Indent all lines in the string.
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
bool toInteger (INT &value, const UString &thousandSeparators=UString(), size_type decimals=0, const UString &decimalSeparators=u".", INT minValue=std::numeric_limits< INT >::min(), INT maxValue=std::numeric_limits< INT >::max()) const
 Convert a string into an integer.
 
template<class CONTAINER , typename std::enable_if< std::is_integral< typename CONTAINER::value_type >::value >::type * = nullptr>
bool toIntegers (CONTAINER &container, const UString &thousandSeparators=UString(), const UString &listSeparators=UString(u",; "), size_type decimals=0, const UString &decimalSeparators=UString(u"."), typename CONTAINER::value_type minValue=std::numeric_limits< typename CONTAINER::value_type >::min(), typename CONTAINER::value_type maxValue=std::numeric_limits< typename CONTAINER::value_type >::max()) const
 Convert a string containing a list of integers into a container of integers.
 
UString toJSON () const
 Return the string in a suitable JSON representation.
 
UString toJustified (const UString &right, size_type width, UChar pad=SPACE, size_t spacesAroundPad=0) const
 Return a justified string, pad in the middle.
 
UString toJustifiedCentered (size_type width, UChar pad=SPACE, bool truncate=false, size_t spacesAroundPad=0) const
 Return a centered-justified (padded and optionally truncated) string.
 
UString toJustifiedLeft (size_type width, UChar pad=SPACE, bool truncate=false, size_t spacesBeforePad=0) const
 Return a left-justified (padded and optionally truncated) string.
 
UString toJustifiedRight (size_type width, UChar pad=SPACE, bool truncate=false, size_t spacesAfterPad=0) const
 Return a right-justified (padded and optionally truncated) string.
 
UString toLower () const
 Return a lower-case version of the string.
 
UString toQuoted (UChar quoteCharacter=u'\'', const UString &specialCharacters=DEFAULT_SPECIAL_CHARACTERS, bool forceQuote=false) const
 Return a "quoted" version of this string.
 
UString toRemoved (const UString &substr) const
 Remove all occurences of a substring.
 
UString toRemoved (UChar c) const
 Remove all occurences of a character.
 
UString toRemovedPrefix (const UString &prefix, CaseSensitivity cs=CASE_SENSITIVE) const
 Remove a prefix in string.
 
UString toRemovedSuffix (const UString &suffix, CaseSensitivity cs=CASE_SENSITIVE) const
 Remove a suffix in string.
 
UString toReversed () const
 Return a copy of the string where characters are reversed.
 
UString toSplitLines (size_type maxWidth, const UString &otherSeparators=UString(), const UString &nextMargin=UString(), bool forceSplit=false, const UString lineSeparator=UString(1, LINE_FEED)) const
 Split a string into multiple lines which are not longer than a specified maximum width.
 
UString toSubstituted (const UString &value, const UString &replacement) const
 Return a copy of the string where all occurences of a string are substituted with another one.
 
UString toSubstituted (UChar value, UChar replacement) const
 Return a copy of the string where all occurences of a character are substituted with another one.
 
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.
 
bool toTristate (Tristate &value) const
 Convert a string into a Tristate value.
 
UString toTruncatedWidth (size_type maxWidth, StringDirection direction=LEFT_TO_RIGHT) const
 Return a copy of this string, truncated to a given display width.
 
UString toUpper () const
 Return an upper-case version of the string.
 
std::string toUTF8 () const
 Convert this UTF-16 string into UTF-8.
 
void toUTF8 (std::string &utf8) const
 Convert this UTF-16 string into UTF-8.
 
void trim (bool leading=true, bool trailing=true, bool sequences=false)
 Trim leading and / or trailing space characters.
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void trimLength (INT length, bool trimTrailingSpaces=true)
 Reduce the size of the string to a given length from an alien integer type.
 
void truncateWidth (size_type maxWidth, StringDirection direction=LEFT_TO_RIGHT)
 Truncate this string to a given display width.
 
::WCHAR * wc_str ()
 Get the address of the underlying null-terminated Unicode string (Windows-specific).
 
const ::WCHAR * wc_str () const
 Get the address of the underlying null-terminated Unicode string (Windows-specific).
 
size_type width () const
 Get the display width in characters.
 

Static Public Member Functions

static UString AfterBytes (const std::streampos &position)
 Build an error message fragment indicating the number of bytes previously read in a binary file.
 
template<class CONTAINER >
static CONTAINER & Append (CONTAINER &container, int argc, char *const argv[])
 Append an array of C-strings to a container of strings.
 
template<class CONTAINER >
static CONTAINER & Append (CONTAINER &container, int argc, const char *const argv[])
 Append an array of C-strings to a container of strings.
 
template<class CONTAINER >
static CONTAINER & Assign (CONTAINER &container, int argc, char *const argv[])
 Assign an array of C-strings to a container of strings.
 
template<class CONTAINER >
static CONTAINER & Assign (CONTAINER &container, int argc, const char *const argv[])
 Assign an array of C-strings to a container of strings.
 
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)
 Format a string containing a std::chrono::duration value, with units.
 
template<class DURATION , typename std::enable_if< std::is_integral< typename DURATION::rep >::value, int >::type = 0>
static UString ChronoUnit (bool short_format=false, bool plural=false)
 Format the name of an instance of std::chrono::duration.
 
static UString ChronoUnit (std::intmax_t num, std::intmax_t den, bool short_format=false, bool plural=false)
 Format the name of an instance of std::chrono::duration based on its ratio values.
 
static void ConvertUTF16ToUTF8 (const UChar *&inStart, const UChar *inEnd, char *&outStart, char *outEnd)
 General routine to convert from UTF-16 to UTF-8.
 
static void ConvertUTF8ToUTF16 (const char *&inStart, const char *inEnd, UChar *&outStart, UChar *outEnd)
 General routine to convert from UTF-8 to UTF-16.
 
template<class CONTAINER , typename std::enable_if< std::is_integral< typename CONTAINER::value_type >::value >::type * = nullptr>
static UString Decimal (const CONTAINER &values, const UString &separator=UString(u", "), bool force_sign=false)
 Format a string containing a list of decimal values.
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
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)
 Format a string containing a decimal value.
 
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)
 Build a multi-line string containing the hexadecimal dump of a memory area.
 
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)
 Build a multi-line string containing the hexadecimal dump of a memory area.
 
static UString Float (double value, size_type width=0, size_type precision=0, bool force_sign=false)
 Format a string containing a floating point value.
 
static UString Format (const UChar *fmt, std::initializer_list< ArgMixIn > args)
 Format a string using a template and arguments.
 
static UString Format (const UString &fmt, std::initializer_list< ArgMixIn > args)
 Format a string using a template and arguments.
 
static UString FromUTF8 (const char *utf8)
 Convert an UTF-8 string into UTF-16.
 
static UString FromUTF8 (const char *utf8, size_type count)
 Convert an UTF-8 string into UTF-16.
 
static UString FromUTF8 (const std::string &utf8)
 Convert an UTF-8 string into UTF-16.
 
static UString FromWChar (const std::wstring &wstr)
 Convert a C++ "wide string" into UTF-16.
 
static UString FromWChar (const wchar_t *wstr)
 Convert a C++ "wide string" into UTF-16.
 
static UString FromWChar (const wchar_t *wstr, size_type count)
 Convert a C++ "wide string" into UTF-16.
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
static UString Hexa (INT value, size_type width=0, const UString &separator=UString(), bool use_prefix=true, bool use_upper=true)
 Format a string containing an hexadecimal value.
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
static UString HexaMin (INT value, size_type min_width=0, const UString &separator=UString(), bool use_prefix=true, bool use_upper=true)
 Format a string containing an hexadecimal value.
 
static UString HumanSize (int64_t value, const UString &units=u"B", bool forceSign=false)
 Format a human-readable size using MB, kB or B as appropriate.
 
template<class CONTAINER >
static UString Join (const CONTAINER &container, const UString &separator=UString(u", "), bool removeEmpty=false)
 Join a container of strings into one big string.
 
template<class ITERATOR >
static UString Join (ITERATOR begin, ITERATOR end, const UString &separator=UString(u", "), bool removeEmpty=false)
 Join a part of a container of strings into one big string.
 
template<class CONTAINER >
static bool Load (CONTAINER &container, const fs::path &fileName)
 Load all lines of a text file in UTF-8 format as UString's into a container.
 
template<class CONTAINER >
static bool Load (CONTAINER &container, std::istream &strm)
 Load all lines of a text file in UTF-8 format as UString's into a container.
 
template<class CONTAINER >
static bool LoadAppend (CONTAINER &container, const fs::path &fileName)
 Load all lines of a text file in UTF-8 format as UString's and append them in a container.
 
template<class CONTAINER >
static bool LoadAppend (CONTAINER &container, std::istream &strm)
 Load all lines of a text file in UTF-8 format as UString's and append them in a container.
 
static UString OnOff (bool b)
 Format a boolean value as "on" or "off".
 
template<class Rep1 , class Period1 , class Rep2 , class Period2 >
static UString Percentage (const cn::duration< Rep1, Period1 > &value, const cn::duration< Rep2, Period2 > &total)
 Format a percentage string between duration values.
 
template<typename Int1 , typename Int2 , typename std::enable_if< std::is_integral< Int1 >::value &&std::is_integral< Int2 >::value >::type * = nullptr>
static UString Percentage (Int1 value, Int2 total)
 Format a percentage string.
 
template<class CONTAINER >
static bool Save (const CONTAINER &container, const fs::path &fileName, bool append=false)
 Save strings from a container into a file, in UTF-8 format, one per line.
 
template<class CONTAINER >
static bool Save (const CONTAINER &container, std::ostream &strm)
 Save strings from a container into a file, in UTF-8 format, one per line.
 
template<class ITERATOR >
static bool Save (ITERATOR begin, ITERATOR end, const fs::path &fileName, bool append=false)
 Save strings from a container into a file, in UTF-8 format, one per line.
 
template<class ITERATOR >
static bool Save (ITERATOR begin, ITERATOR end, std::ostream &strm)
 Save strings from a container into a stream, in UTF-8 format, one per line.
 
static int SuperCompare (const UChar *s1, const UChar *s2, uint32_t flags=SCOMP_DEFAULT)
 Compare two strings using various comparison options.
 
template<class CONTAINER >
static UString ToQuotedLine (const CONTAINER &container, UChar quoteCharacter=u'\'', const UString &specialCharacters=DEFAULT_SPECIAL_CHARACTERS)
 Convert a container of strings into one big string where all elements are properly quoted when necessary.
 
static UString TristateNamesList ()
 Get the list of valid strings for Tristate values.
 
static UString TristateOnOff (Tristate b)
 Format a tristate value as "on", "off", "unknown".
 
static UString TristateTrueFalse (Tristate b)
 Format a tristate value as "true", "false", "unknown".
 
static UString TristateYesNo (Tristate b)
 Format a tristate value as "yes", "no", "maybe".
 
static UString TrueFalse (bool b)
 Format a boolean value as "true" or "false".
 
static UString YesNo (bool b)
 Format a boolean value as "yes" or "no".
 

Static Public Attributes

static constexpr size_type DEFAULT_HEXA_LINE_WIDTH = 78
 Default line width for the Hexa() family of methods.
 
static const UString DEFAULT_QUOTE_CHARACTERS
 The default list of acceptable quote characters.
 
static const UString DEFAULT_SPECIAL_CHARACTERS
 The default list of characters to be protected by quoted().
 
static const UString DEFAULT_THOUSANDS_SEPARATOR
 Default separator string for groups of thousands, a comma.
 
static const UString EMPTY
 A reference empty string.
 
static const UString EOL
 End-of-line sequence for the operating system.
 
static const char *const UTF8_BOM
 The 3-byte so-called "UTF-8 Byte Order Mark".
 
static constexpr size_type UTF8_BOM_SIZE = 3
 Size in bytes of the so-called "UTF-8 Byte Order Mark".
 
static constexpr size_type UTF8_CHAR_MAX_SIZE = 4
 Maximum size in bytes of an UTF-8 encoded character.
 

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";
An implementation of UTF-16 strings.
Definition tsUString.h:122

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)
Convert an UTF-8 string into this object.
Definition tsUString.h:416
static UString FromUTF8(const std::string &utf8)
Convert an UTF-8 string into UTF-16.

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 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/19]

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

Constructor using an allocator.

Parameters
[in]allocAllocator.

◆ UString() [2/19]

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

Copy constructor.

Parameters
[in]otherOther instance to copy.

◆ UString() [3/19]

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() [4/19]

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() [5/19]

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() [6/19]

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() [7/19]

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() [8/19]

template<typename CHARTYPE , typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
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() [9/19]

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() [10/19]

template<typename CHARTYPE , std::size_t SIZE, typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
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() [11/19]

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() [12/19]

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() [13/19]

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() [14/19]

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() [15/19]

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() [16/19]

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() [17/19]

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() [18/19]

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() [19/19]

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

Constructor from a std::filesystem::path.

Parameters
[in]pA standard path instance.

Member Function Documentation

◆ 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]

static 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]

static 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]

static 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/2]

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

Convert this UTF-16 string into UTF-8.

Returns
The equivalent UTF-8 string.

◆ toUTF8() [2/2]

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

Convert this UTF-16 string into UTF-8.

Parameters
[out]utf8The equivalent UTF-8 string.

◆ ConvertUTF16ToUTF8()

static void ts::UString::ConvertUTF16ToUTF8 ( const UChar *&  inStart,
const UChar inEnd,
char *&  outStart,
char *  outEnd 
)
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]inStartAddress of the input UTF-16 buffer to convert. Updated upon return to point after the last converted character.
[in]inEndAddress after the end of the input UTF-16 buffer.
[in,out]outStartAddress of the output UTF-8 buffer to fill. Updated upon return to point after the last converted character.
[in]outEndAddress after the end of the output UTF-8 buffer to fill.

◆ ConvertUTF8ToUTF16()

static void ts::UString::ConvertUTF8ToUTF16 ( const char *&  inStart,
const char *  inEnd,
UChar *&  outStart,
UChar outEnd 
)
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]inStartAddress of the input UTF-8 buffer to convert. Updated upon return to point after the last converted character.
[in]inEndAddress after the end of the input UTF-8 buffer.
[in,out]outStartAddress of the output UTF-16 buffer to fill. Updated upon return to point after the last converted character.
[in]outEndAddress after the end of the output UTF-16 buffer to fill.

◆ assign() [1/4]

template<typename CHARTYPE , typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
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 , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
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]

static 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]

static 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]

static 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  maxWidth,
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]maxWidthMaximum 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  maxWidth,
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]maxWidthMaximum 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.

◆ trimLength()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
void ts::UString::trimLength ( INT  length,
bool  trimTrailingSpaces = 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]trimTrailingSpacesIf 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.

◆ 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 occurences of a substring.

Parameters
[in]substrSubstring to remove.

◆ remove() [2/2]

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

Remove all occurences of a character.

Parameters
[in]cCharacter to remove.

◆ toRemoved() [1/2]

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

Remove all occurences of a substring.

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

◆ toRemoved() [2/2]

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

Remove all occurences of a character.

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

◆ substitute() [1/2]

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

Substitute all occurences 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 occurences 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 occurences 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 occurences 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 occurences 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 occurences 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.

◆ startWith()

bool ts::UString::startWith ( const UString prefix,
CaseSensitivity  cs = CASE_SENSITIVE,
bool  skip_space = false 
) 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_spaceIf true, ignore initial spaces in this string.
Returns
True if this string starts with prefix, false otherwise.

◆ contain() [1/2]

bool ts::UString::contain ( 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.

◆ contain() [2/2]

bool ts::UString::contain ( 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.

◆ endWith()

bool ts::UString::endWith ( const UString suffix,
CaseSensitivity  cs = CASE_SENSITIVE,
bool  skip_space = false 
) 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_spaceIf true, ignore trailing spaces in this 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  trimSpaces = true,
bool  removeEmpty = 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]trimSpacesIf true (the default), each segment is trimmed, i.e. all leading and trailing space characters are removed.
[in]removeEmptyIf true, empty segments are ignored

◆ splitAppend()

template<class CONTAINER >
void ts::UString::splitAppend ( CONTAINER &  container,
UChar  separator = COMMA,
bool  trimSpaces = true,
bool  removeEmpty = 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]trimSpacesIf true (the default), each segment is trimmed, i.e. all leading and trailing space characters are removed.
[in]removeEmptyIf 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  startWith = u'[',
UChar  endWith = u']',
bool  trimSpaces = 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]startWithThe character which is used to identify the start of a segment of input.
[in]endWithThe character which is used to identify the end of a segment of input.
[in]trimSpacesIf 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  startWith = u'[',
UChar  endWith = u']',
bool  trimSpaces = 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]startWithThe character which is used to identify the start of a segment of input.
[in]endWithThe character which is used to identify the end of a segment of input.
[in]trimSpacesIf 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  maxWidth,
const UString otherSeparators = UString(),
const UString nextMargin = UString(),
bool  forceSplit = 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 otherSeparators.

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]maxWidthMaximum width of each resulting line.
[in]otherSeparatorsA string containing all characters which are acceptable as line break points (in addition to space characters which are always potential line break points).
[in]nextMarginA string which is prepended to all lines after the first one.
[in]forceSplitIf 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 maxWidth).

◆ splitLinesAppend()

template<class CONTAINER >
void ts::UString::splitLinesAppend ( CONTAINER &  container,
size_type  maxWidth,
const UString otherSeparators = UString(),
const UString nextMargin = UString(),
bool  forceSplit = 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 otherSeparators.

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]maxWidthMaximum width of each resulting line.
[in]otherSeparatorsA string containing all characters which are acceptable as line break points (in addition to space characters which are always potential line break points).
[in]nextMarginA string which is prepended to all lines after the first one.
[in]forceSplitIf 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 maxWidth).

◆ toSplitLines()

UString ts::UString::toSplitLines ( size_type  maxWidth,
const UString otherSeparators = UString(),
const UString nextMargin = UString(),
bool  forceSplit = false,
const UString  lineSeparator = 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 otherSeparators.

Parameters
[in]maxWidthMaximum width of each resulting line.
[in]otherSeparatorsA string containing all characters which are acceptable as line break points (in addition to space characters which are always potential line break points).
[in]nextMarginA string which is prepended to all lines after the first one.
[in]forceSplitIf 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 maxWidth).
[in]lineSeparatorThe sequence of characters for line feed.
Returns
The splitted string with embedded line separators.

◆ Join() [1/2]

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

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]removeEmptyIf true, empty segments are ignored
Returns
The big string containing all segments and separators.

◆ Join() [2/2]

template<class CONTAINER >
static UString ts::UString::Join ( const CONTAINER &  container,
const UString separator = UString(u", "),
bool  removeEmpty = 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]removeEmptyIf 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  spacesBeforePad = 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]spacesBeforePadNumber of spaces before padding.

◆ toJustifiedLeft()

UString ts::UString::toJustifiedLeft ( size_type  width,
UChar  pad = SPACE,
bool  truncate = false,
size_t  spacesBeforePad = 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]spacesBeforePadNumber of spaces before padding.
Returns
The justified string.

◆ justifyRight()

void ts::UString::justifyRight ( size_type  width,
UChar  pad = SPACE,
bool  truncate = false,
size_t  spacesAfterPad = 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]spacesAfterPadNumber of spaces after padding.

◆ toJustifiedRight()

UString ts::UString::toJustifiedRight ( size_type  width,
UChar  pad = SPACE,
bool  truncate = false,
size_t  spacesAfterPad = 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]spacesAfterPadNumber of spaces after padding.
Returns
The justified string.

◆ justifyCentered()

void ts::UString::justifyCentered ( size_type  width,
UChar  pad = SPACE,
bool  truncate = false,
size_t  spacesAroundPad = 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]spacesAroundPadNumber of spaces around padding.

◆ toJustifiedCentered()

UString ts::UString::toJustifiedCentered ( size_type  width,
UChar  pad = SPACE,
bool  truncate = false,
size_t  spacesAroundPad = 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]spacesAroundPadNumber of spaces around padding.
Returns
The justified string.

◆ justify()

void ts::UString::justify ( const UString right,
size_type  width,
UChar  pad = SPACE,
size_t  spacesAroundPad = 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]spacesAroundPadNumber of spaces around padding.

◆ toJustified()

UString ts::UString::toJustified ( const UString right,
size_type  width,
UChar  pad = SPACE,
size_t  spacesAroundPad = 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]spacesAroundPadNumber of spaces around padding.
Returns
The justified string.

◆ quoted()

void ts::UString::quoted ( UChar  quoteCharacter = u'\'',
const UString specialCharacters = DEFAULT_SPECIAL_CHARACTERS,
bool  forceQuote = false 
)

Replace the string with a "quoted" version of it.

If this string contains any space character or any character from specialCharacters, then the string is replaced with a value surrounded by the quoteCharacter and all special characters are properly escaped using a backslash.

Parameters
[in]quoteCharacterThe character to be used as quote.
[in]specialCharactersThe list of special characters. The quoteCharacter is implicitly part of specialCharacters.
[in]forceQuoteIf true, force quote, even if the content does not require it.

◆ toQuoted()

UString ts::UString::toQuoted ( UChar  quoteCharacter = u'\'',
const UString specialCharacters = DEFAULT_SPECIAL_CHARACTERS,
bool  forceQuote = false 
) const

Return a "quoted" version of this string.

Parameters
[in]quoteCharacterThe character to be used as quote.
[in]specialCharactersThe list of special characters. The quoteCharacter is implicitly part of specialCharacters.
[in]forceQuoteIf true, force quote, even if the content does not require it.
Returns
A "quoted" version of this string.
See also
quoted()

◆ quotedLine()

template<class CONTAINER >
void ts::UString::quotedLine ( const CONTAINER &  container,
UChar  quoteCharacter = u'\'',
const UString specialCharacters = 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]quoteCharacterThe character to be used as quote.
[in]specialCharactersThe list of special characters. The quoteCharacter is implicitly part of specialCharacters.

◆ ToQuotedLine()

template<class CONTAINER >
static UString ts::UString::ToQuotedLine ( const CONTAINER &  container,
UChar  quoteCharacter = u'\'',
const UString specialCharacters = 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]quoteCharacterThe character to be used as quote.
[in]specialCharactersThe list of special characters. The quoteCharacter is implicitly part of specialCharacters.
Returns
The final line with quoted elements.

◆ fromQuotedLine()

template<class CONTAINER >
void ts::UString::fromQuotedLine ( CONTAINER &  container,
const UString quoteCharacters = DEFAULT_QUOTE_CHARACTERS,
const UString specialCharacters = 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]quoteCharactersAll characters which are recognized as quote at the beginning of an element.
[in]specialCharactersThe list of special characters. The quoteCharacter is implicitly part of specialCharacters.
See also
quoted()

◆ 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.

◆ 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.

◆ 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static UString ts::UString::HumanSize ( int64_t  value,
const UString units = u"B",
bool  forceSign = 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]forceSignIf true, use a '+' sign for positive value.
Returns
A human-readable representation of the size value.

◆ Percentage() [1/2]

template<typename Int1 , typename Int2 , typename std::enable_if< std::is_integral< Int1 >::value &&std::is_integral< Int2 >::value >::type * = nullptr>
static 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 >
static 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 
) 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.
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 
) 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.
Returns
-1, 0, or 1, if this string is respectively before, equal to, or after other according to flags.

◆ SuperCompare()

static int ts::UString::SuperCompare ( const UChar s1,
const UChar s2,
uint32_t  flags = SCOMP_DEFAULT 
)
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.
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) const
inline

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

Parameters
[in]otherOther string to compare.
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) const
inline

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

Parameters
[in]otherOther string to compare.
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 
) 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.
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) 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.
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) 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.
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()

◆ save()

bool ts::UString::save ( const fs::path &  fileName,
bool  append = false,
bool  enforceLastLineFeed = false 
) const

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

Parameters
[in]fileNameThe name of the text file where to save this string.
[in]appendIf true, append this string at the end of the file. If false (the default), overwrite the file if it already existed.
[in]enforceLastLineFeedIf 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 >
static bool ts::UString::Save ( ITERATOR  begin,
ITERATOR  end,
const fs::path &  fileName,
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]fileNameThe name of the text file where to save the strings.
[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 >
static bool ts::UString::Save ( const CONTAINER &  container,
const fs::path &  fileName,
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]fileNameThe name of the text file where to save the strings.
[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 >
static 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 >
static 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 >
static bool ts::UString::Load ( CONTAINER &  container,
const fs::path &  fileName 
)
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]fileNameThe name of the text file from where to load the strings.
Returns
True on success, false on error (mostly file errors).

◆ LoadAppend() [1/2]

template<class CONTAINER >
static bool ts::UString::LoadAppend ( CONTAINER &  container,
const fs::path &  fileName 
)
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]fileNameThe name of the text file from where to load the strings. Each line of the text file is inserted as a separate string.
Returns
True on success, false on error (mostly file errors).

◆ Load() [2/2]

template<class CONTAINER >
static bool ts::UString::Load ( CONTAINER &  container,
std::istream &  strm 
)
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.
Returns
True on success, false on error (mostly file errors).

◆ LoadAppend() [2/2]

template<class CONTAINER >
static bool ts::UString::LoadAppend ( CONTAINER &  container,
std::istream &  strm 
)
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.
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).

◆ 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()

static UString ts::UString::TristateNamesList ( )
static

Get the list of valid strings for Tristate values.

Returns
The list of valid strings for Tristate values.

◆ toInteger()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
bool ts::UString::toInteger ( INT value,
const UString thousandSeparators = UString(),
size_type  decimals = 0,
const UString decimalSeparators = u".",
INT  minValue = std::numeric_limits< INT >::min(),
INT  maxValue = 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]thousandSeparatorsA string of characters which are interpreted as thousands separators and are ignored. Any character from the thousandSeparators 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]decimalSeparatorsA string of characters which are interpreted as decimal point. A decimal point is allowed only in base 10.
[in]minValueminimum allowed value for the decoded integer.
[in]maxValuemaximum allowed value for the decoded integer.
Returns
True on success, false on error (invalid string).

◆ toIntegers()

template<class CONTAINER , typename std::enable_if< std::is_integral< typename CONTAINER::value_type >::value >::type * = nullptr>
bool ts::UString::toIntegers ( CONTAINER &  container,
const UString thousandSeparators = UString(),
const UString listSeparators = UString(u",; "),
size_type  decimals = 0,
const UString decimalSeparators = UString(u"."),
typename CONTAINER::value_type  minValue = std::numeric_limits< typename CONTAINER::value_type >::min(),
typename CONTAINER::value_type  maxValue = 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]thousandSeparatorsA string of characters which are interpreted as thousands separators and are ignored. Any character from the thousandSeparators string is interpreted as a separator. Note that this implies that the optional thousands separators may have one character only.
[in]listSeparatorsA 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]decimalSeparatorsA string of characters which are interpreted as decimal point. A decimal point is allowed only in base 10.
[in]minValueminimum allowed value for the decoded integers.
[in]maxValuemaximum allowed value for the decoded integers.
Returns
True on success, false on error (invalid string).

◆ toFloat()

template<typename FLT , typename std::enable_if< std::is_floating_point< FLT >::value >::type * = nullptr>
bool ts::UString::toFloat ( FLT &  value,
FLT  minValue = std::numeric_limits< FLT >::lowest(),
FLT  maxValue = 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]minValueMinimum allowed value for the decoded value.
[in]maxValueMaximum allowed value for the decoded value.
Returns
True on success, false on error (invalid string).

◆ Decimal() [1/2]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
static 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 , typename std::enable_if< std::is_integral< typename CONTAINER::value_type >::value >::type * = nullptr>
static 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 , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
static 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 , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
static 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()

static 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 thousandSeparators = UString(),
const cn::duration< Rep, Period > &  minValue = cn::duration< Rep, Period >::min(),
const cn::duration< Rep, Period > &  maxValue = 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]thousandSeparatorsA string of characters which are interpreted as thousands separators and are ignored. Any character from the thousandSeparators string is interpreted as a separator. Note that this implies that the optional thousands separators may have one character only.
[in]minValueminimum allowed value for the decoded value.
[in]maxValuemaximum allowed value for the decoded value.
Returns
True on success, false on error (invalid string).

◆ Chrono()

template<class Rep , class Period >
static 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.

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.

◆ ChronoUnit() [1/2]

template<class DURATION , typename std::enable_if< std::is_integral< typename DURATION::rep >::value, int >::type = 0>
static 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]

static 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]

void ts::UString::format ( const UChar fmt,
std::initializer_list< ArgMixIn args 
)

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.
  • %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.

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, std::initializer_list< ArgMixIn > args)
Format a string using a template and arguments.

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, std::initializer_list< ArgMixIn > args)
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.

◆ format() [2/2]

void ts::UString::format ( const UString fmt,
std::initializer_list< ArgMixIn 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]

static UString ts::UString::Format ( const UChar fmt,
std::initializer_list< ArgMixIn args 
)
static

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]

static UString ts::UString::Format ( const UString fmt,
std::initializer_list< ArgMixIn 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]

bool ts::UString::scan ( size_t &  extractedCount,
size_type &  endIndex,
const UChar fmt,
std::initializer_list< ArgMixOut args 
) const

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.
  • %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]extractedCountThe number of successfully extracted values.
[out]endIndexThe 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]

bool ts::UString::scan ( size_t &  extractedCount,
size_type &  endIndex,
const UString fmt,
std::initializer_list< ArgMixOut args 
) const
inline

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

Parameters
[out]extractedCountThe number of successfully extracted values.
[out]endIndexThe 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]

bool ts::UString::scan ( const UChar fmt,
std::initializer_list< ArgMixOut 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]

bool ts::UString::scan ( const UString fmt,
std::initializer_list< ArgMixOut 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]

static 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]

static 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 >
static 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 >
static 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 >
static 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 >
static 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.

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