TSDuck Version 3.15-964 (TSDuck - The MPEG Transport Stream Toolkit)
ts::UString Class Reference

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

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

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...
 
typedef std::u16string SuperClass
 Explicit reference to superclass.
 

Public Member Functions

 UString () noexcept(noexcept(allocator_type()))
 Default constructor.
 
 UString (const allocator_type &alloc) noexcept
 Constructor using an allocator. More...
 
 UString (const SuperClass &other)
 Copy constructor. More...
 
 UString (SuperClass &&other) noexcept
 Move constructor. More...
 
 UString (size_type count, UChar ch, const allocator_type &alloc=allocator_type())
 Constructor using a repetition of the same character. More...
 
 UString (const SuperClass &other, size_type pos, size_type count, const allocator_type &alloc=allocator_type())
 Constructor using a substring. More...
 
 UString (const UChar *s, size_type count, const allocator_type &alloc=allocator_type())
 Constructor using a Unicode string. More...
 
 UString (const UChar *s, const allocator_type &alloc=allocator_type())
 Constructor using a null-terminated Unicode string. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
template<class InputIt >
 UString (InputIt first, InputIt last, const allocator_type &alloc=allocator_type())
 Constructor from iterators. More...
 
 UString (const std::initializer_list< UChar > &init, const allocator_type &alloc=allocator_type())
 Constructor from an initializer list. More...
 
 UString (const ::WCHAR *s, size_type count, const allocator_type &alloc=allocator_type())
 Constructor using a Windows Unicode string (Windows-specific). More...
 
 UString (const ::WCHAR *s, const allocator_type &alloc=allocator_type())
 Constructor using a null-terminated Windows Unicode string (Windows-specific). More...
 
 UString (const std::string &utf8)
 Constructor from an UTF-8 string. More...
 
 UString (const char *utf8)
 Constructor from an UTF-8 string. More...
 
 UString (const char *utf8, size_type count)
 Constructor from an UTF-8 string. More...
 
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. More...
 
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. More...
 
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. More...
 
template<typename CHARTYPE >
UStringassign (const std::vector< CHARTYPE > &vec)
 Assign from a std::vector of 16-bit characters of any type. More...
 
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. More...
 
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. More...
 
UStringassignFromUTF8 (const std::string &utf8)
 Convert an UTF-8 string into this object. More...
 
UStringassignFromUTF8 (const char *utf8)
 Convert an UTF-8 string into this object. More...
 
UStringassignFromUTF8 (const char *utf8, size_type count)
 Convert an UTF-8 string into this object. More...
 
bool contain (const UString &substring, CaseSensitivity cs=CASE_SENSITIVE) const
 Check if a string contains a specified substring. More...
 
template<class CONTAINER >
bool containSimilar (const CONTAINER &container) const
 Check if a container of strings contains something similar to this string. More...
 
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. More...
 
void convertToJSON ()
 Convert the string into a suitable JSON representation. More...
 
void convertToLower ()
 Convert the string to lower-case.
 
void convertToUpper ()
 Convert the string to uper-case.
 
size_type displayPosition (size_type count, size_type from=0, StringDirection direction=LEFT_TO_RIGHT) const
 Count displayed positions inside a string. More...
 
bool endWith (const UString &suffix, CaseSensitivity cs=CASE_SENSITIVE) const
 Check if a string ends with a specified suffix. More...
 
template<class CONTAINER >
CONTAINER::const_iterator findSimilar (const CONTAINER &container) const
 Locate into a map or multimap an element with a similar string. More...
 
void format (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Format a string using a template and arguments. More...
 
void format (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Format a string using a template and arguments. More...
 
UString fromHTML () const
 Return the string with all HTML entities converted into plain characters. More...
 
UString fromJSON () const
 Return the string with all JSON backslash sequences converted into plain characters. More...
 
bool getLine (std::istream &strm)
 Read one UTF-8 line from a text file and load it into this object. More...
 
bool hexaDecode (ByteBlock &result) const
 Interpret this string as a sequence of hexadecimal digits (ignore blanks). More...
 
bool hexaDecodeAppend (ByteBlock &result) const
 Interpret this string as a sequence of hexadecimal digits (ignore blanks). More...
 
void justify (const UString &right, size_type width, UChar pad=SPACE, size_t spacesAroundPad=0)
 Justify string, pad in the middle. More...
 
void justifyCentered (size_type width, UChar pad=SPACE, bool truncate=false, size_t spacesAroundPad=0)
 Centered-justified (pad and optionally truncate) string. More...
 
void justifyLeft (size_type width, UChar pad=SPACE, bool truncate=false, size_t spacesBeforePad=0)
 Left-justify (pad and optionally truncate) string. More...
 
void justifyRight (size_type width, UChar pad=SPACE, bool truncate=false, size_t spacesAfterPad=0)
 Right-justified (pad and optionally truncate) string. More...
 
const UCharlast () const
 Get the address after the last character in the string. More...
 
UCharlast ()
 Get the address after the last character in the string (C++17). More...
 
void remove (const UString &substr)
 Remove all occurences of a substring. More...
 
void remove (UChar c)
 Remove all occurences of a character. More...
 
void removePrefix (const UString &prefix, CaseSensitivity cs=CASE_SENSITIVE)
 Remove a prefix in string. More...
 
void removeSuffix (const UString &suffix, CaseSensitivity cs=CASE_SENSITIVE)
 Remove a suffix in string. More...
 
void reverse ()
 Reverse the order of characters in the string.
 
bool scan (size_t &extractedCount, size_type &endIndex, const UChar *fmt, const std::initializer_list< ArgMixOut > &args) const
 Scan this string for integer or character values using a template and arguments. More...
 
bool scan (size_t &extractedCount, size_type &endIndex, const UString &fmt, const std::initializer_list< ArgMixOut > &args) const
 Scan this string for integer or character values using a template and arguments. More...
 
bool scan (const UChar *fmt, const std::initializer_list< ArgMixOut > &args) const
 Scan this string for integer or character values using a template and arguments. More...
 
bool scan (const UString &fmt, const std::initializer_list< ArgMixOut > &args) const
 Scan this string for integer or character values using a template and arguments. More...
 
bool similar (const UString &other) const
 Check if two strings are identical, case-insensitive and ignoring blanks. More...
 
bool similar (const void *addr, size_type size) const
 Check if two strings are identical, case-insensitive and ignoring blanks. More...
 
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). More...
 
template<class CONTAINER >
void splitBlocks (CONTAINER &container, UChar startWith=UChar('['), UChar endWith=UChar(']'), bool trimSpaces=true) const
 Split a string into segments which are identified by their starting / ending characters (respectively "[" and "]" by default). More...
 
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. More...
 
bool startWith (const UString &prefix, CaseSensitivity cs=CASE_SENSITIVE) const
 Check if the string starts with a specified prefix. More...
 
void substitute (const UString &value, const UString &replacement)
 Substitute all occurences of a string with another one. More...
 
size_type toDVB (uint8_t *&buffer, size_t &size, size_type start=0, size_type count=NPOS, const DVBCharset *charset=0) const
 Encode this UTF-16 string into a DVB string. More...
 
ByteBlock toDVB (size_type start=0, size_type count=NPOS, const DVBCharset *charset=0) const
 Encode this UTF-16 string into a DVB string. More...
 
size_type toDVBWithByteLength (uint8_t *&buffer, size_t &size, size_type start=0, size_type count=NPOS, const DVBCharset *charset=0) const
 Encode this UTF-16 string into a DVB string (preceded by its one-byte length). More...
 
ByteBlock toDVBWithByteLength (size_type start=0, size_type count=NPOS, const DVBCharset *charset=0) const
 Encode this UTF-16 string into a DVB string (preceded by its one-byte length). More...
 
UString toHTML (const UString &convert=UString()) const
 Return the string in a suitable HTML representation. More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
bool toInteger (INT &value, const UString &thousandSeparators=UString()) const
 Convert a string into an integer. More...
 
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",; ")) const
 Convert a string containing a list of integers into a container of integers. More...
 
UString toJSON () const
 Return the string in a suitable JSON representation. More...
 
UString toJustified (const UString &right, size_type width, UChar pad=SPACE, size_t spacesAroundPad=0) const
 Return a justified string, pad in the middle. More...
 
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. More...
 
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. More...
 
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. More...
 
UString toLower () const
 Return a lower-case version of the string. More...
 
UString toRemoved (const UString &substr) const
 Remove all occurences of a substring. More...
 
UString toRemoved (UChar c) const
 Remove all occurences of a character. More...
 
UString toRemovedPrefix (const UString &prefix, CaseSensitivity cs=CASE_SENSITIVE) const
 Remove a prefix in string. More...
 
UString toRemovedSuffix (const UString &suffix, CaseSensitivity cs=CASE_SENSITIVE) const
 Remove a suffix in string. More...
 
UString toReversed () const
 Return a copy of the string where characters are reversed. More...
 
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. More...
 
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. More...
 
UString toTrimmed (bool leading=true, bool trailing=true) const
 Return a copy of the string where leading and / or trailing spaces are trimmed. More...
 
bool toTristate (Tristate &value) const
 Convert a string into a Tristate value. More...
 
UString toTruncatedWidth (size_type maxWidth, StringDirection direction=LEFT_TO_RIGHT) const
 Return a copy of this string, truncated to a given display width. More...
 
UString toUpper () const
 Return an upper-case version of the string. More...
 
std::string toUTF8 () const
 Convert this UTF-16 string into UTF-8. More...
 
void toUTF8 (std::string &utf8) const
 Convert this UTF-16 string into UTF-8. More...
 
void trim (bool leading=true, bool trailing=true)
 Trim leading and / or trailing space characters. More...
 
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. More...
 
void truncateWidth (size_type maxWidth, StringDirection direction=LEFT_TO_RIGHT)
 Truncate this string to a given display width. More...
 
const ::WCHAR * wc_str () const
 Get the address of the underlying null-terminated Unicode string (Windows-specific). More...
 
::WCHAR * wc_str ()
 Get the address of the underlying null-terminated Unicode string (Windows-specific). More...
 
size_type width () const
 Get the display width in characters. More...
 

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. More...
 
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. More...
 
template<class CONTAINER >
static CONTAINER & Append (CONTAINER &container, int argc, char *const argv[])
 Append an array of C-strings to a container of strings. More...
 
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. More...
 
template<class CONTAINER >
static CONTAINER & Assign (CONTAINER &container, int argc, char *const argv[])
 Assign an array of C-strings to a container of strings. More...
 
static void ConvertUTF16ToUTF8 (const UChar *&inStart, const UChar *inEnd, char *&outStart, char *outEnd)
 General routine to convert from UTF-16 to UTF-8. More...
 
static void ConvertUTF8ToUTF16 (const char *&inStart, const char *inEnd, UChar *&outStart, UChar *outEnd)
 General routine to convert from UTF-8 to UTF-16. More...
 
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. More...
 
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. More...
 
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. More...
 
static UString Format (const UChar *fmt, const std::initializer_list< ArgMixIn > &args)
 Format a string using a template and arguments. More...
 
static UString Format (const UString &fmt, const std::initializer_list< ArgMixIn > &args)
 Format a string using a template and arguments. More...
 
static UString FromDVB (const std::string &dvb, const DVBCharset *charset=0)
 Convert a DVB string into UTF-16. More...
 
static UString FromDVB (const uint8_t *dvb, size_type dvbSize, const DVBCharset *charset=0)
 Convert a DVB string into UTF-16. More...
 
static UString FromDVBWithByteLength (const uint8_t *&buffer, size_t &size, const DVBCharset *charset=0)
 Convert a DVB string into UTF-16 (preceded by its one-byte length). More...
 
static UString FromUTF8 (const std::string &utf8)
 Convert an UTF-8 string into UTF-16. More...
 
static UString FromUTF8 (const char *utf8)
 Convert an UTF-8 string into UTF-16. More...
 
static UString FromUTF8 (const char *utf8, size_type count)
 Convert an UTF-8 string into UTF-16. More...
 
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. More...
 
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. More...
 
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. More...
 
template<class ITERATOR >
static UString Join (ITERATOR begin, ITERATOR end, const UString &separator=UString(u", "))
 Join a part of a container of strings into one big string. More...
 
template<class CONTAINER >
static UString Join (const CONTAINER &container, const UString &separator=UString(u", "))
 Join a container of strings into one big string. More...
 
template<class CONTAINER >
static bool Load (CONTAINER &container, const UString &fileName)
 Load all lines of a text file in UTF-8 format as UString's into a container. More...
 
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. More...
 
template<class CONTAINER >
static bool LoadAppend (CONTAINER &container, const UString &fileName)
 Load all lines of a text file in UTF-8 format as UString's and append them in a container. More...
 
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. More...
 
static UString OnOff (bool b)
 Format a boolean value as "on" or "off". More...
 
template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
static UString Percentage (INT value, INT total)
 Format a percentage string. More...
 
template<class ITERATOR >
static bool Save (ITERATOR begin, ITERATOR end, const UString &fileName, bool append=false)
 Save strings from a container into a file, in UTF-8 format, one per line. More...
 
template<class CONTAINER >
static bool Save (const CONTAINER &container, const UString &fileName, bool append=false)
 Save strings from a container into a file, in UTF-8 format, one per line. More...
 
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. More...
 
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. More...
 
static UString TristateNamesList ()
 Get the list of valid strings for Tristate values. More...
 
static UString TristateOnOff (Tristate b)
 Format a tristate value as "on", "off", "unknown". More...
 
static UString TristateTrueFalse (Tristate b)
 Format a tristate value as "true", "false", "unknown". More...
 
static UString TristateYesNo (Tristate b)
 Format a tristate value as "yes", "no", "maybe". More...
 
static UString TrueFalse (bool b)
 Format a boolean value as "true" or "false". More...
 
static UString YesNo (bool b)
 Format a boolean value as "yes" or "no". More...
 

Static Public Attributes

static const size_type DEFAULT_HEXA_LINE_WIDTH = 78
 Default line width for the Hexa() family of methods.
 
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 char *const UTF8_BOM
 The 3-byte so-called "UTF-8 Byte Order Mark".
 
static const size_type UTF8_BOM_SIZE = 3
 Size in bytes of the so-called "UTF-8 Byte Order Mark".
 
static const 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";

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 DVB character sets.
  • 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

Unicode strings can be converted to and from DVB strings. Most DVB-defined character sets are implemented (see the class DVBCharset) and recognized when a string is read from a descriptor.

When a string is serialized into a binary DVB descriptor, the most appropriate DVB character set is used. In practice, a few known DVB character sets are used and when the string cannot be encoded in any of them UTF-8 is used (UTF-8 is a valid DVB character set).

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

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

Constructor using an allocator.

Parameters
[in]allocAllocator.

◆ UString() [2/18]

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

Copy constructor.

Parameters
[in]otherOther instance to copy.

◆ UString() [3/18]

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

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

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

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

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

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

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

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

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

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

ts::UString::UString ( const 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/18]

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

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

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

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

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

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

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

Member Function Documentation

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

◆ FromDVB() [1/2]

static UString ts::UString::FromDVB ( const std::string &  dvb,
const DVBCharset charset = 0 
)
inlinestatic

Convert a DVB string into UTF-16.

Parameters
[in]dvbA string in DVB representation. The first bytes of the string indicate the DVB character set to use.
[in]charsetIf not zero, use this character set if no explicit table code is present, instead of the standard default ISO-6937.
Returns
The equivalent UTF-16 string. Stop on untranslatable character, if any.
See also
ETSI EN 300 468, Annex A.

◆ FromDVB() [2/2]

static UString ts::UString::FromDVB ( const uint8_t *  dvb,
size_type  dvbSize,
const DVBCharset charset = 0 
)
static

Convert a DVB string into UTF-16.

Parameters
[in]dvbAddress of a string in DVB representation. The first bytes of the string indicate the DVB character set to use.
[in]dvbSizeSize in bytes of the DVB string.
[in]charsetIf not zero, use this character set if no explicit table code is present, instead of the standard default ISO-6937.
Returns
The equivalent UTF-16 string. Stop on untranslatable character, if any.
See also
ETSI EN 300 468, Annex A.

◆ FromDVBWithByteLength()

static UString ts::UString::FromDVBWithByteLength ( const uint8_t *&  buffer,
size_t &  size,
const DVBCharset charset = 0 
)
static

Convert a DVB string into UTF-16 (preceded by its one-byte length).

Parameters
[in,out]bufferAddress of a buffer containing a DVB string to read. The first byte in the buffer is the length in bytes of the string. Upon return, buffer is updated to point after the end of the string.
[in,out]sizeSize in bytes of the buffer, which may be larger than the DVB string. Upon return, size is updated, decremented by the same amount buffer was incremented.
[in]charsetIf not zero, use this character set if no explicit table code is present, instead of the standard default ISO-6937.
Returns
The equivalent UTF-16 string. Stop on untranslatable character, if any.
See also
ETSI EN 300 468, Annex A.

◆ toDVB() [1/2]

size_type ts::UString::toDVB ( uint8_t *&  buffer,
size_t &  size,
size_type  start = 0,
size_type  count = NPOS,
const DVBCharset charset = 0 
) const

Encode this UTF-16 string into a DVB string.

Stop either when this string is serialized or when the buffer is full, whichever comes first.

Parameters
[in,out]bufferAddress of the buffer where the DVB string is written. The address is updated to point after the encoded value.
[in,out]sizeSize of the buffer. Updated to remaining size.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
[in]charsetPreferred character set for DVB encoding. If omitted or if the string cannot be represented in the specified character set, an alternative one will be automatically selected.
Returns
The number of serialized characters (which is usually not the same as the number of written bytes).

◆ toDVB() [2/2]

ByteBlock ts::UString::toDVB ( size_type  start = 0,
size_type  count = NPOS,
const DVBCharset charset = 0 
) const

Encode this UTF-16 string into a DVB string.

Parameters
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
[in]charsetPreferred character set for DVB encoding. If omitted or if the string cannot be represented in the specified character set, an alternative one will be automatically selected.
Returns
The DVB string.

◆ toDVBWithByteLength() [1/2]

size_type ts::UString::toDVBWithByteLength ( uint8_t *&  buffer,
size_t &  size,
size_type  start = 0,
size_type  count = NPOS,
const DVBCharset charset = 0 
) const

Encode this UTF-16 string into a DVB string (preceded by its one-byte length).

Stop either when this string is serialized or when the buffer is full or when 255 bytes are written, whichever comes first.

Parameters
[in,out]bufferAddress of the buffer where the DVB string is written. The first byte will receive the size in bytes of the DVB string. The address is updated to point after the encoded value.
[in,out]sizeSize of the buffer. Updated to remaining size.
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
[in]charsetPreferred character set for DVB encoding. If omitted or if the string cannot be represented in the specified character set, an alternative one will be automatically selected.
Returns
The number of serialized characters (which is usually not the same as the number of written bytes).

◆ toDVBWithByteLength() [2/2]

ByteBlock ts::UString::toDVBWithByteLength ( size_type  start = 0,
size_type  count = NPOS,
const DVBCharset charset = 0 
) const

Encode this UTF-16 string into a DVB string (preceded by its one-byte length).

Parameters
[in]startStarting offset to convert in this UTF-16 string.
[in]countMaximum number of characters to convert.
[in]charsetPreferred character set for DVB encoding. If omitted or if the string cannot be represented in the specified character set, an alternative one will be automatically selected.
Returns
The DVB string with the initial length byte.

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

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

◆ wc_str() [1/2]

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

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

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

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

◆ 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 (C++17).

Returns
The address after the last character in the string.

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

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.

◆ toTrimmed()

UString ts::UString::toTrimmed ( bool  leading = true,
bool  trailing = true 
) 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.
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.

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

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.

◆ toSubstituted()

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.

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

◆ startWith()

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

◆ contain()

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 sunstring, false otherwise.

◆ endWith()

bool ts::UString::endWith ( const UString suffix,
CaseSensitivity  cs = CASE_SENSITIVE 
) 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.
Returns
True if this string ends with suffix, false otherwise.

◆ split()

template<class CONTAINER >
void ts::UString::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 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,
[in]removeEmptyIf true, empty segments are ignored i.e. all leading and trailing space characters are removed.

◆ splitBlocks()

template<class CONTAINER >
void ts::UString::splitBlocks ( CONTAINER &  container,
UChar  startWith = UChar('['),
UChar  endWith = UChar(']'),
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
[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.

◆ 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

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

◆ 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", ") 
)
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.
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", ") 
)
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.
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.

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

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>
static UString ts::UString::Percentage ( INT  value,
INT  total 
)
static

Format a percentage string.

Template Parameters
INTAn integer type.
Parameters
[in]valueAn integer value, a portion of total.
[in]totalThe total value.
Returns
A string reprenting the percentage of value in total.

◆ similar() [1/2]

bool ts::UString::similar ( const UString other) const

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

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

◆ containSimilar()

template<class CONTAINER >
bool ts::UString::containSimilar ( 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() [1/4]

template<class ITERATOR >
static bool ts::UString::Save ( ITERATOR  begin,
ITERATOR  end,
const UString 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 UString 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 UString 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 UString 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).

◆ 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() 
) 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.
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",; ") 
) 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.
Returns
True on success, false on error (invalid string).

◆ Decimal()

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.

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

◆ format() [1/2]

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

Format a string using a template and arguments.

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.
  • %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.
  • %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.
  • %% : Insert a literal %.

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

  • - : Left-justified (right-justified by default).
  • + : Force a '+' sign with positive decimal integers (%d 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. Ignored for integers.
  • ' : For integer conversions, use a separator for groups of thousands.
  • * : 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"});

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"
$
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,
const std::initializer_list< ArgMixIn > &  args 
)
inline

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.
See also
format()

◆ Format() [1/2]

static UString ts::UString::Format ( const UChar fmt,
const 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,
const 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,
const 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 %.
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*, const std::initializer_list<ArgMixIn>&)
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.

◆ scan() [2/4]

bool ts::UString::scan ( size_t &  extractedCount,
size_type &  endIndex,
const UString fmt,
const 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,
const 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*, const std::initializer_list<ArgMixOut>&)

◆ scan() [4/4]

bool ts::UString::scan ( const UString fmt,
const 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) const

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

Parameters
[out]resultDecoded bytes.
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) 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.
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: