ts::UString Class Reference

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

#include <tsUString.h>

Inheritance diagram for ts::UString:

Collaboration diagram for ts::UString:

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

Public Types
enum	HexaFlags {   HEXA = 0x0001 ,   ASCII = 0x0002 ,   OFFSET = 0x0004 ,   WIDE_OFFSET = 0x0008 ,   SINGLE_LINE = 0x0010 ,   BPL = 0x0020 ,   C_STYLE = 0x0040 ,   BINARY = 0x0080 ,   BIN_NIBBLE = 0x0100 ,   COMPACT = 0x0200 }
	Flags for the Hexa() family of methods. More...
using	SuperClass = std::u16string
	Explicit reference to superclass.

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

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

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

Detailed Description

An implementation of UTF-16 strings.

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

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

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

ts::UString s1(u"abcd");
ts::UString s2 = s1 + u"efgh";

Some interesting features in class UString are:

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

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

ts::UString us;
 
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

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

enum ts::UString::HexaFlags

Flags for the Hexa() family of methods.

Enumerator
HEXA	Dump hexa values.
ASCII	Dump ascii values.
OFFSET	Display address offsets.
WIDE_OFFSET	Always wide offset.
SINGLE_LINE	Hexa on one single line, no line feed, ignore other flags.
BPL	Interpret max_line_width as number of displayed Bytes Per Line (BPL).
C_STYLE	C-style hexa value(u"0xXX," instead of "XX").
BINARY	Dump binary values ("XXXXXXXX" binary digits).
BIN_NIBBLE	Binary values are grouped by nibble ("XXXX XXXX").
COMPACT	Same as SINGLE_LINE but use a compact display without space.

Constructor & Destructor Documentation

UString() [1/19]

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

inlineexplicitnoexcept

Constructor using an allocator.

Parameters

[in]

alloc

Allocator.

UString() [2/19]

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

inline

Copy constructor.

Parameters

[in]

other

Other instance to copy.

UString() [3/19]

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

inlinenoexcept

Move constructor.

Parameters

[in,out]

other

Other instance to move. Upon return, other is left in valid, but unspecified state.

UString() [4/19]

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

inline

Constructor using a repetition of the same character.

Parameters

[in]	count	Initial size of the string.
[in]	ch	Character to repeat count times.
[in]	alloc	Allocator.

UString() [5/19]

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

inline

Constructor using a substring.

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

Parameters

[in]	other	Other instance to partially copy.
[in]	pos	Initial position to copy in other.
[in]	count	Number of character to copy.
[in]	alloc	Allocator.

UString() [6/19]

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

inline

Constructor using a Unicode string.

Parameters

[in]	s	Address of a string. Can be a null pointer if count is zero, in which case the string is empty.
[in]	count	Number of characters to copy from s. That number of characters is always copied, including null characters.
[in]	alloc	Allocator.

UString() [7/19]

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

inline

Constructor using a null-terminated Unicode string.

Parameters

[in]	s	Address of a null-terminated string. Can be a null pointer, in which case the string is empty.
[in]	alloc	Allocator.

UString() [8/19]

template<typename CHARTYPE , typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>

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

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

Template Parameters

CHARTYPE	A 16-bit character or integer type.
INT	An integer type.

Parameters

[in]	vec	The vector of characters.
[in]	count	Maximum 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]	alloc	Allocator.

UString() [9/19]

template<typename CHARTYPE >

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

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

Template Parameters

CHARTYPE

A 16-bit character or integer type.

Parameters

[in]	vec	The vector of characters. Nul-terminated string.
[in]	alloc	Allocator.

UString() [10/19]

template<typename CHARTYPE , std::size_t SIZE, typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>

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

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

Template Parameters

CHARTYPE	A 16-bit character or integer type.
SIZE	The size of the array.
INT	An integer type.

Parameters

[in]	arr	The array of characters.
[in]	count	Maximum 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]	alloc	Allocator.

UString() [11/19]

template<typename CHARTYPE , std::size_t SIZE>

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

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

Template Parameters

CHARTYPE	A 16-bit character or integer type.
SIZE	The size of the array.

Parameters

[in]	arr	The array of characters. Nul-terminated string.
[in]	alloc	Allocator.

UString() [12/19]

template<class InputIt >

ts::UString::UString ( InputIt  first, InputIt  last, const allocator_type &  alloc = allocator_type()  )

inline

Constructor from iterators.

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

Template Parameters

InputIt

An 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]	first	Iterator to the first position to copy.
[in]	last	Iterator after the last position to copy.
[in]	alloc	Allocator.

UString() [13/19]

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

inline

Constructor from an initializer list.

Parameters

[in]	init	Initializer list of Char.
[in]	alloc	Allocator.

UString() [14/19]

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

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

Parameters

[in]	s	Address of a string. Can be a null pointer if count is zero, in which case the string is empty.
[in]	count	Number of characters to copy from s. That number of characters is always copied, including null characters.
[in]	alloc	Allocator.

UString() [15/19]

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

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

Parameters

[in]	s	Address of a null-terminated string. Can be a null pointer, in which case the string is empty.
[in]	alloc	Allocator.

UString() [16/19]

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

inline

Constructor from an UTF-8 string.

Available only when the macro TS_ALLOW_IMPLICIT_UTF8_CONVERSION is externally defined.

Parameters

[in]

utf8

A string in UTF-8 representation.

UString() [17/19]

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

inline

Constructor from an UTF-8 string.

Available only when the macro TS_ALLOW_IMPLICIT_UTF8_CONVERSION is externally defined.

Parameters

[in]

utf8

Address of a nul-terminated string in UTF-8 representation.

UString() [18/19]

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

inline

Constructor from an UTF-8 string.

Available only when the macro TS_ALLOW_IMPLICIT_UTF8_CONVERSION is externally defined.

Parameters

[in]	utf8	Address of a string in UTF-8 representation.
[in]	count	Size in bytes of the UTF-8 string (not necessarily a number of characters).

UString() [19/19]

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

inline

Constructor from a std::filesystem::path.

Parameters

[in]

p

A standard path instance.

Member Function Documentation

wc_str() [1/2]

const ::WCHAR * ts::UString::wc_str

(

)

const

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

Returns

The address of the underlying null-terminated Unicode string .

wc_str() [2/2]

::WCHAR * ts::UString::wc_str

(

)

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

Returns

The address of the underlying null-terminated Unicode string .

FromUTF8() [1/3]

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

static

Convert an UTF-8 string into UTF-16.

Parameters

[in]

utf8

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

utf8

Address 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]	utf8	Address of a string in UTF-8 representation.
[in]	count	Size 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]

utf8

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

utf8

Address 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]	utf8	Address of a string in UTF-8 representation. Can be null.
[in]	count	Size 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]

utf8

The 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]	inStart	Address of the input UTF-16 buffer to convert. Updated upon return to point after the last converted character.
[in]	inEnd	Address after the end of the input UTF-16 buffer.
[in,out]	outStart	Address of the output UTF-8 buffer to fill. Updated upon return to point after the last converted character.
[in]	outEnd	Address 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]	inStart	Address of the input UTF-8 buffer to convert. Updated upon return to point after the last converted character.
[in]	inEnd	Address after the end of the input UTF-8 buffer.
[in,out]	outStart	Address of the output UTF-16 buffer to fill. Updated upon return to point after the last converted character.
[in]	outEnd	Address after the end of the output UTF-16 buffer to fill.

assign() [1/4]

template<typename CHARTYPE , typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>

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

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

Template Parameters

CHARTYPE	A 16-bit character or integer type.
INT	An integer type.

Parameters

[in]	vec	The vector of characters.
[in]	count	Maximum 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

CHARTYPE

A 16-bit character or integer type.

Parameters

[in]

vec

The 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

CHARTYPE	A 16-bit character or integer type.
SIZE	The size of the array.
INT	An integer type.

Parameters

[in]	arr	The array of characters.
[in]	count	Maximum 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

CHARTYPE	A 16-bit character or integer type.
SIZE	The size of the array.

Parameters

[in]

arr

The array of characters. Nul-terminated string.

Returns

A reference to this object.

FromWChar() [1/3]

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

static

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

Parameters

[in]

wstr

A C++ "wide string".

Returns

The equivalent UTF-16 string.

FromWChar() [2/3]

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

static

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

Parameters

[in]

wstr

Address of a nul-terminated "wide string". Can be null.

Returns

The equivalent UTF-16 string. Empty string if wstr is a null pointer.

FromWChar() [3/3]

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

static

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

Parameters

[in]	wstr	Address of a "wide string". Can be null.
[in]	count	Number of characters in wstr.

Returns

The equivalent UTF-16 string. Empty string if utf8 is a null pointer.

assignFromWChar() [1/3]

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

inline

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

Parameters

[in]

wstr

A C++ "wide string".

Returns

A reference to this object.

assignFromWChar() [2/3]

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

inline

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

Parameters

[in]

wstr

Address of a nul-terminated "wide string". Can be null.

Returns

A reference to this object.

assignFromWChar() [3/3]

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

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

Parameters

[in]	wstr	Address of a "wide string". Can be null.
[in]	count	Number of characters in wstr.

Returns

A reference to this object.

operator fs::path()

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

inline

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

Returns

A path value.

operator==()

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

inline

Comparison operator with std::filesystem::path.

Parameters

[in]

other

A path to compare.

Returns

True if this string object is equal to the path string, false otherwise.

last() [1/2]

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

inline

Get the address after the last character in the string.

Returns

The address after the last character in the string.

last() [2/2]

UChar * ts::UString::last ( )

inline

Get the address after the last character in the string.

Returns

The address after the last character in the string.

width()

size_type ts::UString::width

(

)

const

Get the display width in characters.

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

Returns

The display width in characters.

displayPosition()

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

Count displayed positions inside a string.

Any combining diacritical character is not counted in display position. Similarly, any surrogate pair is considered as one single character.

Parameters

[in]	count	Number of display positions to move.
[in]	from	Starting index in the string. This is an index, not a display position.
[in]	direction	Direction 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]	maxWidth	Maximum display width, after which the string is truncated.
[in]	direction	Direction 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]	maxWidth	Maximum display width, after which the string is truncated.
[in]	direction	Direction to move when counting width. When RIGHT_TO_LEFT, the width is counted from the end of the string and the beginning of the string is truncated.

Returns

A copy of the string, truncated to the given display width.

trimLength()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>

void ts::UString::trimLength	(	INT	length,
		bool	trimTrailingSpaces = true
	)

Reduce the size of the string to a given length from an alien integer type.

This method is useful when the string has been used as an input buffer.

Template Parameters

INT	An integer type.

Parameters

[in]	length	New size of the string. Ignored if negative or greater than the current string length.
[in]	trimTrailingSpaces	If true, also remove any trailing space.

toReversed()

UString ts::UString::toReversed

(

)

const

Return a copy of the string where characters are reversed.

Returns

A copy of the string where characters are reversed.

trim()

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

Trim leading and / or trailing space characters.

Parameters

[in]	leading	If true (the default), remove all space characters at the beginning of the string.
[in]	trailing	If true (the default), remove all space characters at the end of the string.
[in]	sequences	If true (disabled by default), replace all space characters sequences in the middle of the string by one single space character.

toTrimmed()

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

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

Parameters

[in]	leading	If true (the default), remove all space characters at the beginning of the string.
[in]	trailing	If true (the default), remove all space characters at the end of the string.
[in]	sequences	If true (disabled by default), replace all space characters sequences in the middle of the string by one single space character.

Returns

A copy of this object after trimming.

toLower()

UString ts::UString::toLower

(

)

const

Return a lower-case version of the string.

Returns

Lower-case version of the string.

toUpper()

UString ts::UString::toUpper

(

)

const

Return an upper-case version of the string.

Returns

Upper-case version of the string.

combineDiacritical()

void ts::UString::combineDiacritical

(

)

Combine all possible diacritical marks.

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

toCombinedDiacritical()

UString ts::UString::toCombinedDiacritical

(

)

const

Return a string with all possible diacritical marks combined.

Returns

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

decomposeDiacritical()

void ts::UString::decomposeDiacritical

(

)

Decompose all precombined characters.

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

toDecomposedDiacritical()

UString ts::UString::toDecomposedDiacritical

(

)

const

Return a string with all precombined characters decomposed.

Returns

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

remove() [1/2]

void ts::UString::remove

(

const UString &

substr

)

Remove all occurences of a substring.

Parameters

[in]

substr

Substring to remove.

remove() [2/2]

void ts::UString::remove

(

UChar

c

)

Remove all occurences of a character.

Parameters

[in]

c

Character to remove.

toRemoved() [1/2]

UString ts::UString::toRemoved

(

const UString &

substr

)

const

Remove all occurences of a substring.

Parameters

[in]

substr

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

c

Character to remove.

Returns

This string with all occurences of substr removed.

substitute() [1/2]

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

Substitute all occurences of a string with another one.

Parameters

[in]	value	Value to search.
[in]	replacement	Replacement string for value.

substitute() [2/2]

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

Substitute all occurences of a character with another one.

Parameters

[in]	value	Value to search.
[in]	replacement	Replacement for value.

toSubstituted() [1/2]

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

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

Parameters

[in]	value	Value to search.
[in]	replacement	Replacement string for value.

Returns

A copy to this string where all occurences of value have been replaced by replace.

toSubstituted() [2/2]

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

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

Parameters

[in]	value	Value to search.
[in]	replacement	Replacement 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]	prefix	A prefix to remove, if present at the beginning of the string.
[in]	cs	Indicate 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]	suffix	A suffix to remove, if present at the end of the string.
[in]	cs	Indicate 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]	prefix	A prefix to remove, if present at the beginning of the string.
[in]	cs	Indicate 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]	suffix	A suffix to remove, if present at the end of the string.
[in]	cs	Indicate if the comparison is case-sensitive.

Returns

A copy of this string with suffix removed.

indent()

void ts::UString::indent

(

size_t

size

)

Indent all lines in the string.

Parameters

[in]

size

Number of spaces to add at the beginning of each line.

toIndented()

UString ts::UString::toIndented

(

size_t

size

)

const

Indent all lines in the string.

Parameters

[in]

size

Number of spaces to add at the beginning of each line.

Returns

A copy of this string with indented lines.

startWith()

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

Check if the string starts with a specified prefix.

Parameters

[in]	prefix	A string prefix to check.
[in]	cs	Indicate if the comparison is case-sensitive.
[in]	skip_space	If true, ignore initial spaces in this string.
[in]	start	Start index where to match the prefix.

Returns

True if this string starts with prefix, false otherwise.

contain() [1/2]

bool ts::UString::contain

(

UChar

c

)

const

Check if a string contains a specified character.

Parameters

[in]

c

A character to check.

Returns

True if this string contains c, false otherwise.

contain() [2/2]

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

Check if a string contains a specified substring.

Parameters

[in]	substring	A substring to check.
[in]	cs	Indicate if the comparison is case-sensitive.

Returns

True if this string contains substring, false otherwise.

endWith()

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

Check if a string ends with a specified suffix.

Parameters

[in]	suffix	A string suffix to check.
[in]	cs	Indicate if the comparison is case-sensitive.
[in]	skip_space	If true, ignore trailing spaces in this string.
[in]	end	Last logical character to check in the string. By default, use the end of string.

Returns

True if this string ends with suffix, false otherwise.

commonPrefixSize()

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

Compute the number of similar leading characters in two strings.

Parameters

[in]	str	A string to compare with this string.
[in]	cs	Indicate if the comparison is case-sensitive.

Returns

The number of identical leading characters in str and this string.

commonSuffixSize()

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

Compute the number of similar trailing characters in two strings.

Parameters

[in]	str	A string to compare with this string.
[in]	cs	Indicate if the comparison is case-sensitive.

Returns

The number of identical trailing characters in str and this string.

split()

template<class CONTAINER >

void ts::UString::split ( CONTAINER &  container, UChar  separator = COMMA, bool  trimSpaces = true, bool  removeEmpty = false  ) const

inline

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

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[out]	container	A container of UString which receives the segments of the splitted string.
[in]	separator	The character which is used to separate the segments.
[in]	trimSpaces	If true (the default), each segment is trimmed, i.e. all leading and trailing space characters are removed.
[in]	removeEmpty	If true, empty segments are ignored

splitAppend()

template<class CONTAINER >

void ts::UString::splitAppend	(	CONTAINER &	container,
		UChar	separator = COMMA,
		bool	trimSpaces = true,
		bool	removeEmpty = false
	)		const

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

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in,out]	container	A container of UString which receives the segments of the splitted string. The strings are appended to the container without erasing previous content.
[in]	separator	The character which is used to separate the segments.
[in]	trimSpaces	If true (the default), each segment is trimmed, i.e. all leading and trailing space characters are removed.
[in]	removeEmpty	If true, empty segments are ignored

splitShellStyle()

template<class CONTAINER >

void ts::UString::splitShellStyle ( CONTAINER &  container ) const

inline

Split the string into shell-style arguments.

Spaces are used as argument delimiters. Arguments can be quoted using single or double quotes. Any character can be escaped using a backslash.

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[out]

container

A container of UString which receives the segments of the splitted string.

splitShellStyleAppend()

template<class CONTAINER >

void ts::UString::splitShellStyleAppend

(

CONTAINER &

container

)

const

Split the string into shell-style arguments.

Spaces are used as argument delimiters. Arguments can be quoted using single or double quotes. Any character can be escaped using a backslash.

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in,out]

container

A container of UString which receives the segments of the splitted string. The strings are appended to the container without erasing previous content.

splitBlocks()

template<class CONTAINER >

void ts::UString::splitBlocks ( CONTAINER &  container, UChar  startWith = u'[', UChar  endWith = u']', bool  trimSpaces = true  ) const

inline

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

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[out]	container	A container of UString which receives the segments of the splitted string.
[in]	startWith	The character which is used to identify the start of a segment of input.
[in]	endWith	The character which is used to identify the end of a segment of input.
[in]	trimSpaces	If true (the default), each segment is trimmed, i.e. all leading and trailing space characters are removed.

splitBlocksAppend()

template<class CONTAINER >

void ts::UString::splitBlocksAppend	(	CONTAINER &	container,
		UChar	startWith = u'[',
		UChar	endWith = u']',
		bool	trimSpaces = true
	)		const

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

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in,out]	container	A container of UString which receives the segments of the splitted string. The strings are appended to the container without erasing previous content.
[in]	startWith	The character which is used to identify the start of a segment of input.
[in]	endWith	The character which is used to identify the end of a segment of input.
[in]	trimSpaces	If true (the default), each segment is trimmed, i.e. all leading and trailing space characters are removed.

splitLines()

template<class CONTAINER >

void ts::UString::splitLines ( CONTAINER &  container, size_type  maxWidth, const UString &  otherSeparators = UString(), const UString &  nextMargin = UString(), bool  forceSplit = false  ) const

inline

Split a string into multiple lines which are not longer than a specified maximum width.

The splits occur on spaces or after any character in otherSeparators.

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[out]	container	A container of UString which receives the lines of the splitted string.
[in]	maxWidth	Maximum width of each resulting line.
[in]	otherSeparators	A string containing all characters which are acceptable as line break points (in addition to space characters which are always potential line break points).
[in]	nextMargin	A string which is prepended to all lines after the first one.
[in]	forceSplit	If true, longer lines without separators are split at the maximum width (by default, longer lines without separators are not split, resulting in lines longer than maxWidth).

splitLinesAppend()

template<class CONTAINER >

void ts::UString::splitLinesAppend	(	CONTAINER &	container,
		size_type	maxWidth,
		const UString &	otherSeparators = UString(),
		const UString &	nextMargin = UString(),
		bool	forceSplit = false
	)		const

Split a string into multiple lines which are not longer than a specified maximum width.

The splits occur on spaces or after any character in otherSeparators.

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in,out]	container	A container of UString which receives the lines of the splitted string. The strings are appended to the container without erasing previous content.
[in]	maxWidth	Maximum width of each resulting line.
[in]	otherSeparators	A string containing all characters which are acceptable as line break points (in addition to space characters which are always potential line break points).
[in]	nextMargin	A string which is prepended to all lines after the first one.
[in]	forceSplit	If 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]	maxWidth	Maximum width of each resulting line.
[in]	otherSeparators	A string containing all characters which are acceptable as line break points (in addition to space characters which are always potential line break points).
[in]	nextMargin	A string which is prepended to all lines after the first one.
[in]	forceSplit	If 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]	lineSeparator	The sequence of characters for line feed.

Returns

The splitted string with embedded line separators.

Join() [1/2]

template<class ITERATOR >

static UString ts::UString::Join ( ITERATOR  begin, ITERATOR  end, const UString &  separator = UString(u", "), bool  removeEmpty = false  )

static

Join a part of a container of strings into one big string.

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

Template Parameters

ITERATOR

An iterator class over UString as defined by the C++ Standard Template Library (STL).

Parameters

[in]	begin	An iterator pointing to the first string.
[in]	end	An iterator pointing after the last string.
[in]	separator	A string to insert between all segments.
[in]	removeEmpty	If true, empty segments are ignored

Returns

The big string containing all segments and separators.

Join() [2/2]

template<class CONTAINER >

static UString ts::UString::Join ( const CONTAINER &  container, const UString &  separator = UString(u", "), bool  removeEmpty = false  )

inlinestatic

Join a container of strings into one big string.

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

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in]	container	A container of UString containing all strings to concatenate.
[in]	separator	A string to insert between all segments.
[in]	removeEmpty	If true, empty segments are ignored

Returns

The big string containing all segments and separators.

justifyLeft()

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

Left-justify (pad and optionally truncate) string.

If this string is shorter than the specified width, pad characters are appended to the string up to the specified width.

Parameters

[in]	width	The required width of the result string.
[in]	pad	The character to append to the string.
[in]	truncate	If 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]	spacesBeforePad	Number 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]	width	The required width of the result string.
[in]	pad	The character to append to the string.
[in]	truncate	If 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]	spacesBeforePad	Number 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]	width	The required width of the result string.
[in]	pad	The character to prepend to the string.
[in]	truncate	If 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]	spacesAfterPad	Number 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]	width	The required width of the result string.
[in]	pad	The character to prepend to the string.
[in]	truncate	If 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]	spacesAfterPad	Number 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]	width	The required width of the result string.
[in]	pad	The pad character for the string.
[in]	truncate	If 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]	spacesAroundPad	Number 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]	width	The required width of the result string.
[in]	pad	The pad character for the string.
[in]	truncate	If 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]	spacesAroundPad	Number 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]	right	The right part of the string to justify. This string is used as left part.
[in]	width	The required width of the result string.
[in]	pad	The character to insert between the two parts.
[in]	spacesAroundPad	Number 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]	right	The right part of the string to justify. This string is used as left part.
[in]	width	The required width of the result string.
[in]	pad	The character to insert between the two parts.
[in]	spacesAroundPad	Number of spaces around padding.

Returns

The justified string.

quoted()

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

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

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

Parameters

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

toQuoted()

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

Return a "quoted" version of this string.

Parameters

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

Returns

A "quoted" version of this string.

See also

quoted()

quotedLine()

template<class CONTAINER >

void ts::UString::quotedLine	(	const CONTAINER &	container,
		UChar	quoteCharacter = u'\'',
		const UString &	specialCharacters = DEFAULT_SPECIAL_CHARACTERS
	)

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

This string object receives the final line with quoted elements.

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in]	container	A container of UString containing all elements.
[in]	quoteCharacter	The character to be used as quote.
[in]	specialCharacters	The list of special characters. The quoteCharacter is implicitly part of specialCharacters.

ToQuotedLine()

template<class CONTAINER >

static UString ts::UString::ToQuotedLine ( const CONTAINER &  container, UChar  quoteCharacter = u'\'', const UString &  specialCharacters = DEFAULT_SPECIAL_CHARACTERS  )

static

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

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in]	container	A container of UString containing all elements.
[in]	quoteCharacter	The character to be used as quote.
[in]	specialCharacters	The list of special characters. The quoteCharacter is implicitly part of specialCharacters.

Returns

The final line with quoted elements.

fromQuotedLine()

template<class CONTAINER >

void ts::UString::fromQuotedLine	(	CONTAINER &	container,
		const UString &	quoteCharacters = DEFAULT_QUOTE_CHARACTERS,
		const UString &	specialCharacters = DEFAULT_SPECIAL_CHARACTERS
	)		const

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

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[out]	container	A container of UString receiving all unquoted elements.
[in]	quoteCharacters	All characters which are recognized as quote at the beginning of an element.
[in]	specialCharacters	The list of special characters. The quoteCharacter is implicitly part of specialCharacters.

See also

quoted()

convertToHTML()

void ts::UString::convertToHTML

(

const UString &

convert = UString()

)

Convert the string into a suitable HTML representation.

Parameters

[in]

convert

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

convert

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

b

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

b

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

b

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

b

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

b

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

b

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

position

A 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]	value	A size value in basic units. This is a signed value.
[in]	units	A string for the units. The default is "B" (for bytes).
[in]	forceSign	If true, use a '+' sign for positive value.

Returns

A human-readable representation of the size value.

Percentage() [1/2]

template<typename Int1 , typename Int2 , typename std::enable_if< std::is_integral< Int1 >::value &&std::is_integral< Int2 >::value >::type * = nullptr>

static UString ts::UString::Percentage ( Int1  value, Int2  total  )

static

Format a percentage string.

Parameters

[in]	value	An integer value, a portion of total.
[in]	total	The total value.

Returns

A string representing the percentage of value in total.

Percentage() [2/2]

template<class Rep1 , class Period1 , class Rep2 , class Period2 >

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

static

Format a percentage string between duration values.

Parameters

[in]	value	A duration value, a portion of total.
[in]	total	The total duration value.

Returns

A string representing the percentage of value in total.

superCompare() [1/2]

int ts::UString::superCompare ( const UString &  other, uint32_t  flags = SCOMP_DEFAULT  ) const

inline

Compare two strings using various comparison options.

Parameters

[in]	other	Other string to compare.
[in]	flags	A bitmask of StringComparison values. By default, use a strict comparison.

Returns

-1, 0, or 1, if this string is respectively before, equal to, or after other according to flags.

superCompare() [2/2]

int ts::UString::superCompare ( const UChar *  other, uint32_t  flags = SCOMP_DEFAULT  ) const

inline

Compare two strings using various comparison options.

Parameters

[in]	other	Address of a nul-terminated UTF-16 string..
[in]	flags	A bitmask of StringComparison values. By default, use a strict comparison.

Returns

-1, 0, or 1, if this string is respectively before, equal to, or after other according to flags.

SuperCompare()

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

static

Compare two strings using various comparison options.

Parameters

[in]	s1	Address of a nul-terminated UTF-16 string..
[in]	s2	Address of a nul-terminated UTF-16 string..
[in]	flags	A bitmask of StringComparison values. By default, use a strict comparison.

Returns

-1, 0, or 1, if s1 is respectively before, equal to, or after s2 according to flags.

similar() [1/3]

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

inline

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

Parameters

[in]

other

Other string to compare.

Returns

True if this string and other are "similar", ie. identical, case-insensitive and ignoring blanks.

similar() [2/3]

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

inline

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

Parameters

[in]

other

Other string to compare.

Returns

True if this string and other are "similar", ie. identical, case-insensitive and ignoring blanks.

similar() [3/3]

bool ts::UString::similar	(	const void *	addr,
		size_type	size
	)		const

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

Parameters

[in]	addr	Address of second string in UTF-8 representation.
[in]	size	Size in bytes of second string.

Returns

True if the strings are "similar", ie. identical, case-insensitive and ignoring blanks

isContainedSimilarIn()

template<class CONTAINER >

bool ts::UString::isContainedSimilarIn

(

const CONTAINER &

container

)

const

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

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in]

container

A 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

CONTAINER

A map container class using UString as key.

Parameters

[in]

container

A map container with UString keys.

Returns

An iterator to the first element of container with a key value which is similar to this string according to similar(). Return container.end() if not found.

See also

similar()

save()

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

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

Parameters

[in]	fileName	The name of the text file where to save this string.
[in]	append	If true, append this string at the end of the file. If false (the default), overwrite the file if it already existed.
[in]	enforceLastLineFeed	If true and this string does not end with a line feed, force a final line feed.

Returns

True on success, false on error (mostly file errors).

Save() [1/4]

template<class ITERATOR >

static bool ts::UString::Save ( ITERATOR  begin, ITERATOR  end, const fs::path &  fileName, bool  append = false  )

static

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

The strings must be located in a container and are accessed through iterators.

Template Parameters

ITERATOR

An iterator class over UString as defined by the C++ Standard Template Library (STL).

Parameters

[in]	begin	An iterator pointing to the first string.
[in]	end	An iterator pointing after the last string.
[in]	fileName	The name of the text file where to save the strings.
[in]	append	If true, append the strings at the end of the file. If false (the default), overwrite the file if it already existed.

Returns

True on success, false on error (mostly file errors).

Save() [2/4]

template<class CONTAINER >

static bool ts::UString::Save ( const CONTAINER &  container, const fs::path &  fileName, bool  append = false  )

static

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

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in]	container	A container of UString containing all strings to save.
[in]	fileName	The name of the text file where to save the strings.
[in]	append	If 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

ITERATOR

An iterator class over UString as defined by the C++ Standard Template Library (STL).

Parameters

[in]	begin	An iterator pointing to the first string.
[in]	end	An iterator pointing after the last string.
[in]	strm	Output 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

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in]	container	A container of UString containing all strings to save.
[in]	strm	Output stream.

Returns

True on success, false on error (mostly file errors).

Load() [1/2]

template<class CONTAINER >

static bool ts::UString::Load ( CONTAINER &  container, const fs::path &  fileName  )

static

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

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[out]	container	A container of UString receiving all lines of the file. Each line of the text file is a separate string.
[in]	fileName	The name of the text file from where to load the strings.

Returns

True on success, false on error (mostly file errors).

LoadAppend() [1/2]

template<class CONTAINER >

static bool ts::UString::LoadAppend ( CONTAINER &  container, const fs::path &  fileName  )

static

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

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in,out]	container	A container of UString receiving all lines of the file. Each line of the text file is a separate string.
[in]	fileName	The 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

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[out]	container	A container of UString receiving all lines of the file. Each line of the text file is a separate string.
[in,out]	strm	A 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

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in,out]	container	A container of UString receiving all lines of the file. Each line of the text file is a separate string.
[in,out]	strm	A 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]

strm

A standard stream in input mode.

Returns

True on success, false on error (mostly file errors).

toBool()

bool ts::UString::toBool

(

bool &

value

)

const

Convert a string into a bool value.

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

Parameters

[out]

value

The returned decoded value. On error value contains false.

Returns

True on success, false on error (invalid string).

toTristate()

bool ts::UString::toTristate

(

Tristate &

value

)

const

Convert a string into a Tristate value.

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

Parameters

[out]

value

The returned decoded value. On error value contains MAYBE.

Returns

True on success, false on error (invalid string).

TristateNamesList()

static UString ts::UString::TristateNamesList ( )

static

Get the list of valid strings for Tristate values.

Returns

The list of valid strings for Tristate values.

toInteger()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>

bool ts::UString::toInteger	(	INT &	value,
		const UString &	thousandSeparators = UString(),
		size_type	decimals = 0,
		const UString &	decimalSeparators = u".",
		INT	minValue = std::numeric_limits< INT >::min(),
		INT	maxValue = std::numeric_limits< INT >::max()
	)		const

Convert a string into an integer.

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

Template Parameters

INT	An integer type, any size, signed or unsigned. The toInteger function decodes integer values of this type.

Parameters

[out]	value	The returned decoded value. On error (invalid string), value contains what could be decoded up to the first invalid character.
[in]	thousandSeparators	A 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]	decimals	Reference number of decimal digits. When decimals is greater than zero, the result is automatically adjusted by the corresponding power of ten. For instance, when decimals is 3, u"12" returns 12000, u"12.34" returns 12340 and "12.345678" returns 12345. All extra decimals are accepted but ignored.
[in]	decimalSeparators	A string of characters which are interpreted as decimal point. A decimal point is allowed only in base 10.
[in]	minValue	minimum allowed value for the decoded integer.
[in]	maxValue	maximum allowed value for the decoded integer.

Returns

True on success, false on error (invalid string).

toIntegers()

template<class CONTAINER , typename std::enable_if< std::is_integral< typename CONTAINER::value_type >::value >::type * = nullptr>

bool ts::UString::toIntegers	(	CONTAINER &	container,
		const UString &	thousandSeparators = UString(),
		const UString &	listSeparators = UString(u",; "),
		size_type	decimals = 0,
		const UString &	decimalSeparators = UString(u"."),
		typename CONTAINER::value_type	minValue = std::numeric_limits< typename CONTAINER::value_type >::min(),
		typename CONTAINER::value_type	maxValue = std::numeric_limits< typename CONTAINER::value_type >::max()
	)		const

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

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

Template Parameters

CONTAINER

A container class of any integer type as defined by the C++ Standard Template Library (STL).

Parameters

[out]	container	The 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]	thousandSeparators	A 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]	listSeparators	A string of characters which are interpreted as list separators. Distinct integer values must be separated by one or more of these separators. Any character from the listSeparators string is interpreted as a separator. Note that this implies that the list separators may have one character only.
[in]	decimals	Reference number of decimal digits. When decimals is greater than zero, the result is automatically adjusted by the corresponding power of ten. For instance, when decimals is 3, u"12" returns 12000, u"12.34" returns 12340 and "12.345678" returns 12345. All extra decimals are accepted but ignored.
[in]	decimalSeparators	A string of characters which are interpreted as decimal point. A decimal point is allowed only in base 10.
[in]	minValue	minimum allowed value for the decoded integers.
[in]	maxValue	maximum allowed value for the decoded integers.

Returns

True on success, false on error (invalid string).

toFloat()

template<typename FLT , typename std::enable_if< std::is_floating_point< FLT >::value >::type * = nullptr>

bool ts::UString::toFloat	(	FLT &	value,
		FLT	minValue = std::numeric_limits< FLT >::lowest(),
		FLT	maxValue = std::numeric_limits< FLT >::max()
	)		const

Convert a string into a floating-point.

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

Template Parameters

FLT	A floating-point type. The toFloat() function decodes floating-point values of this type.

Parameters

[out]	value	The returned decoded value.
[in]	minValue	Minimum allowed value for the decoded value.
[in]	maxValue	Maximum allowed value for the decoded value.

Returns

True on success, false on error (invalid string).

Decimal() [1/2]

template<typename INT , typename std::enable_if< std::is_integral< INT >::value||std::is_enum< 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

INT	An integer type.

Parameters

[in]	value	The integer value to format.
[in]	min_width	Minimum width of the returned string. Padded with spaces if larger than the number of characters in the formatted number.
[in]	right_justified	If 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]	separator	Separator string for groups of thousands, a comma by default.
[in]	force_sign	If true, force a '+' sign for positive values.
[in]	pad	The padding character to adjust the width.

Returns

The formatted string.

Decimal() [2/2]

template<class CONTAINER , typename std::enable_if< std::is_integral< typename CONTAINER::value_type >::value||std::is_enum< typename CONTAINER::value_type >::value >::type * = nullptr>

static UString ts::UString::Decimal ( const CONTAINER &  values, const UString &  separator = UString(u", "), bool  force_sign = false  )

static

Format a string containing a list of decimal values.

Template Parameters

CONTAINER

A container class of any integer type as defined by the C++ Standard Template Library (STL).

Parameters

[in]	values	The integer values to format.
[in]	separator	Separator string between values, a comma by default.
[in]	force_sign	If true, force a '+' sign for positive values.

Returns

The formatted string.

Hexa()

template<typename INT , typename std::enable_if< std::is_integral< INT >::value >::type * = nullptr>

static UString ts::UString::Hexa ( INT  value, size_type  width = 0, const UString &  separator = UString(), bool  use_prefix = true, bool  use_upper = true  )

static

Format a string containing an hexadecimal value.

Template Parameters

INT	An integer type.

Parameters

[in]	value	The integer value to format.
[in]	width	Width 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]	separator	Separator string for groups of 4 digits, empty by default.
[in]	use_prefix	If true, prepend the standard hexa prefix "0x".
[in]	use_upper	If 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

INT	An integer type.

Parameters

[in]	value	The integer value to format.
[in]	min_width	Minimum 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]	separator	Separator string for groups of 4 digits, empty by default.
[in]	use_prefix	If true, prepend the standard hexa prefix "0x".
[in]	use_upper	If true, use upper-case hexadecimal digits.

Returns

The formatted string.

Float()

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

static

Format a string containing a floating point value.

Parameters

[in]	value	The floating point value to format.
[in]	width	Width of the formatted number, not including the optional prefix and separator.
[in]	precision	Precision to use after the decimal point. Default is 6 digits when set to zero.
[in]	force_sign	If true, force a '+' sign for positive values.

Returns

The formatted string.

toChrono()

template<class Rep , class Period >

bool ts::UString::toChrono	(	cn::duration< Rep, Period > &	value,
		const UString &	thousandSeparators = UString(),
		const cn::duration< Rep, Period > &	minValue = cn::duration< Rep, Period >::min(),
		const cn::duration< Rep, Period > &	maxValue = cn::duration< Rep, Period >::max()
	)		const

Convert a string into a std::chrono::duration value.

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

Parameters

[out]	value	The returned decoded value. On error (invalid string), value contains what could be decoded up to the first invalid character.
[in]	thousandSeparators	A 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]	minValue	minimum allowed value for the decoded value.
[in]	maxValue	maximum allowed value for the decoded value.

Returns

True on success, false on error (invalid string).

Chrono()

template<class Rep , class Period >

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

inlinestatic

Format a string containing a std::chrono::duration value, with units.

Parameters

[in]	value	The chrono value to format.
[in]	short_format	When true, use short unit format (e.g. "ms"). By default, use a full unit name (e.g. "millisecond").
[in]	separator	Separator string for groups of thousands, a comma by default.
[in]	force_sign	If true, force a '+' sign for positive values.

Returns

The formatted string.

ChronoUnit() [1/2]

template<class DURATION , typename std::enable_if< std::is_integral< typename DURATION::rep >::value, int >::type = 0>

static UString ts::UString::ChronoUnit ( bool  short_format = false, bool  plural = false  )

inlinestatic

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

Template Parameters

DURATION

An instance of std::chrono::duration.

Parameters

[in]	short_format	When true, use short unit format (e.g. "ms"). By default, use a full unit name (e.g. "millisecond").
[in]	plural	When true, use the plural form (full unit name only, e.g. "milliseconds").

Returns

A string representing the unit of the DURATION.

ChronoUnit() [2/2]

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

static

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

Parameters

[in]	num	Ratio numerator.
[in]	den	Ratio denominator.
[in]	short_format	When true, use short unit format (e.g. "ms"). By default, use a full unit name (e.g. "millisecond").
[in]	plural	When true, use the plural form (full unit name only, e.g. "milliseconds").

Returns

A string representing the unit of the DURATION.

format() [1/2]

template<class... Args>

void ts::UString::format ( const UChar *  fmt, Args &&...  args  )

inline

Format a string using a template and arguments.

The formatted string is appended to this string object.

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

The available '%' sequences are:

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

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

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

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]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

format() [2/2]

template<class... Args>

void ts::UString::format ( const UString &  fmt, Args &&...  args  )

inline

Format a string using a template and arguments.

The formatted string is appended to this string object.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also

format()

Format() [1/2]

template<class... Args>

static UString ts::UString::Format ( const UChar *  fmt, Args &&...  args  )

inlinestatic

Format a string using a template and arguments.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

Returns

The formatted string.

See also

format()

Format() [2/2]

template<class... Args>

static UString ts::UString::Format ( const UString &  fmt, Args &&...  args  )

inlinestatic

Format a string using a template and arguments.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

Returns

The formatted string.

See also

format()

scan() [1/4]

template<class... Args>

bool ts::UString::scan ( size_t &  extractedCount, size_type &  endIndex, const UChar *  fmt, Args &&...  args  ) const

inline

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

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

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

The available '%' sequences are:

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

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

• ' : For decimal integer conversions, ignore separator for groups of thousands.

Parameters

[out]	extractedCount	The number of successfully extracted values.
[out]	endIndex	The index in this string after the last extracted value.
[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of output arguments to receive extracted values. The args list is built from pointers to integer data of any size, signed or unsigned.

Returns

True if the entire string is consumed and the entire format is parsed. False otherwise. In other words, the method returns true when this object string exactly matches the format in fmt.

See also

Format(const UChar*, std::initializer_list<ArgMixIn>)

scan() [2/4]

template<class... Args>

bool ts::UString::scan ( size_t &  extractedCount, size_type &  endIndex, const UString &  fmt, Args &&...  args  ) const

inline

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

Parameters

[out]	extractedCount	The number of successfully extracted values.
[out]	endIndex	The index in this string after the last extracted value.
[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of output arguments to receive extracted values. The args list is built from pointers to integer data of any size, signed or unsigned.

Returns

True if the entire string is consumed and the entire format is parsed. False otherwise. In other words, the method returns true when this object string exactly matches the format in fmt.

See also

scan()

scan() [3/4]

template<class... Args>

bool ts::UString::scan ( const UChar *  fmt, Args &&...  args  ) const

inline

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

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of output arguments to receive extracted values. The args list is built from pointers to integer data of any size, signed or unsigned.

Returns

True if the entire string is consumed and the entire format is parsed. False otherwise. In other words, the method returns true when this object string exactly matches the format in fmt.

See also

scan(size_t&, size_type&, const UChar*, std::initializer_list<ArgMixOut>)

scan() [4/4]

template<class... Args>

bool ts::UString::scan ( const UString &  fmt, Args &&...  args  ) const

inline

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

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List 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]	data	Starting address of the memory area to dump.
[in]	size	Size in bytes of the memory area to dump.
[in]	flags	A 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]	indent	Each line is indented by this number of characters.
[in]	line_width	Maximum 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_offset	If 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_indent	Add 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]	bb	Byte block to dump.
[in]	flags	A 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]	indent	Each line is indented by this number of characters.
[in]	line_width	Maximum 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_offset	If 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_indent	Add 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]	data	Starting address of the memory area to dump.
[in]	size	Size in bytes of the memory area to dump.
[in]	flags	A 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]	indent	Each line is indented by this number of characters.
[in]	line_width	Maximum 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_offset	If 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_indent	Add 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]	bb	Byte block to dump.
[in]	flags	A 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]	indent	Each line is indented by this number of characters.
[in]	line_width	Maximum 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_offset	If 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_indent	Add this indentation before hexa/ascii dump, after offset.

See also

HexaFlags

hexaDecode()

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

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

Parameters

[out]	result	Decoded bytes.
[in]	c_style	If true, allow "C-style" aggregate (ignore commas, braces and "0x").

Returns

True on success, false on error (invalid hexa format). When returning false, the result contains everything that could be decoded before getting the error.

hexaDecodeAppend()

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

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

Parameters

[in,out]	result	The decoded bytes are added at the end of the previous content.
[in]	c_style	If true, allow "C-style" aggregate (ignore commas, braces and "0x").

Returns

True on success, false on error (invalid hexa format). When returning false, the result contains everything that could be decoded before getting the error.

Append() [1/2]

template<class CONTAINER >

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

static

Append an array of C-strings to a container of strings.

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

Template Parameters

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in,out]	container	A container of UString.
[in]	argc	The number of C-strings in argv.
[in]	argv	An 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

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[in,out]	container	A container of UString.
[in]	argc	The number of C-strings in argv.
[in]	argv	An 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

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[out]	container	A container of UString.
[in]	argc	The number of C-strings in argv.
[in]	argv	An 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

CONTAINER

A container class of UString as defined by the C++ Standard Template Library (STL).

Parameters

[out]	container	A container of UString.
[in]	argc	The number of C-strings in argv.
[in]	argv	An array of C-strings.

Returns

A reference to container.

---

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

• tsUString.h