TagLib::String Class Reference

A wide string class suitable for unicode. More...

`#include <tstring.h>`

## Public Types

enum | Type { Latin1 = 0 , UTF16 = 1 , UTF16BE = 2 , UTF8 = 3 , UTF16LE = 4 }

## Public Member Functions

| String ()
| String (const String &s)
| String (const std::string &s, Type t=Latin1)
| String (const std::wstring &s)
| String (const std::wstring &s, Type t)
| String (const wchar_t *s)
| String (const wchar_t *s, Type t)
| String (char c, Type t=Latin1)
| String (wchar_t c, Type t=Latin1)
| String (const char *s, Type t=Latin1)
| String (const ByteVector &v, Type t=Latin1)
| ~String ()
std::string | to8Bit (bool unicode=false) const
std::wstring | toWString () const
const char * | toCString (bool unicode=false) const
const wchar_t * | toCWString () const
Iterator | begin ()
ConstIterator | begin () const
ConstIterator | cbegin () const
Iterator | end ()
ConstIterator | end () const
ConstIterator | cend () const
int | find (const String &s, int offset=0) const
int | rfind (const String &s, int offset=-1) const
StringList | split (const String &separator=" ") const
bool | startsWith (const String &s) const
String | substr (unsigned int position, unsigned int n=0xffffffff) const
String & | append (const String &s)
String & | clear ()
String | upper () const
unsigned int | size () const
unsigned int | length () const
bool | isEmpty () const
ByteVector | data (Type t) const
int | toInt (bool *ok=nullptr) const
long long | toLongLong (bool *ok=nullptr, int base=10) const
unsigned long long | toULongLong (bool *ok=nullptr, int base=10) const
String | stripWhiteSpace () const
bool | isLatin1 () const
bool | isAscii () const
wchar_t & | operator[] (int i)
const wchar_t & | operator[] (int i) const
bool | operator== (const String &s) const
bool | operator!= (const String &s) const
bool | operator== (const char *s) const
bool | operator!= (const char *s) const
bool | operator== (const wchar_t *s) const
bool | operator!= (const wchar_t *s) const
String & | operator+= (const String &s)
String & | operator+= (const wchar_t *s)
String & | operator+= (const char *s)
String & | operator+= (wchar_t c)
String & | operator+= (char c)
String & | operator= (const String &s)
String & | operator= (const std::string &s)
String & | operator= (const std::wstring &s)
String & | operator= (const wchar_t *s)
String & | operator= (char c)
String & | operator= (wchar_t c)
String & | operator= (const char *s)
String & | operator= (const ByteVector &v)
void | swap (String &s) noexcept
bool | operator< (const String &s) const

## Static Public Member Functions

static String | number (int n)
static String | fromLongLong (long long n)
static String | fromULongLong (unsigned long long n)

## Protected Member Functions

void | detach ()

## Related Symbols

(Note that these are not member symbols.)
#define | QStringToTString(s)
#define | TStringToQString(s)
TAGLIB_EXPORT TagLib::String | operator+ (const TagLib::String &s1, const TagLib::String &s2)
TAGLIB_EXPORT TagLib::String | operator+ (const char *s1, const TagLib::String &s2)
TAGLIB_EXPORT TagLib::String | operator+ (const TagLib::String &s1, const char *s2)
TAGLIB_EXPORT std::ostream & | operator<< (std::ostream &s, const TagLib::String &str)

## Detailed Description

A wide string class suitable for unicode.

This is an implicitly shared wide string. For storage it uses std::wstring, but as this is an implementation detail this of course could change. Strings are stored internally as UTF-16 (without BOM/CPU byte order)

The use of implicit sharing means that copying a string is cheap, the only cost comes into play when the copy is modified. Prior to that the string just has a pointer to the data of the parent String. This also makes this class suitable as a function return type.

In addition to adding implicit sharing, this class keeps track of possible encodings, which are those supported by the ID3v2 standard.

## Member Enumeration Documentation

## Type

enum TagLib::String::Type

The four types of string encodings supported by the ID3v2 specification. (plus UTF16LE). ID3v1 is assumed to be Latin1 and Ogg Vorbis comments use UTF8.

Enumerator
Latin1 | ISO-8859-1, or Latin1 encoding. 8 bit characters.
UTF16 | UTF16 with a byte order mark. 16 bit characters.
UTF16BE | UTF16 big endian. 16 bit characters. This is the encoding used internally by TagLib.
UTF8 | UTF8 encoding. Characters are usually 8 bits but can be up to 32.
UTF16LE | UTF16 little endian. 16 bit characters.

## Constructor & Destructor Documentation

## String() [1/11]

TagLib::String::String | ( |  | ) |

Constructs an empty String.

Referenced by append(), clear(), find(), fromLongLong(), fromULongLong(), number(), operator!=(), operator+=(), operator+=(), operator+=(), operator+=(), operator+=(), operator<(), operator=(), operator=(), operator=(), operator=(), operator=(), operator=(), operator=(), operator=(), operator==(), rfind(), split(), startsWith(), String(), stripWhiteSpace(), substr(), swap(), and upper().

## String() [2/11]

TagLib::String::String | ( | const String & | s | ) |

Make a shallow, implicitly shared, copy of s. Because this is implicitly shared, this method is lightweight and suitable for pass-by-value usage.

References String().

## String() [3/11]

TagLib::String::String | ( | const std::string & | s,
|  | Type | t = Latin1 )

Makes a deep copy of the data in s.

Note
  This should only be used with the 8-bit codecs Latin1 and UTF8, when used with other codecs it will simply print a warning and exit.

References Latin1.

## String() [4/11]

TagLib::String::String | ( | const std::wstring & | s | ) |

Makes a deep copy of the data in s, which are in CPU byte order.

## String() [5/11]

TagLib::String::String | ( | const std::wstring & | s,
|  | Type | t )

Makes a deep copy of the data in s, which are in byte order t.

## String() [6/11]

TagLib::String::String | ( | const wchar_t * | s | ) |

Makes a deep copy of the data in s, which are in CPU byte order.

## String() [7/11]

TagLib::String::String | ( | const wchar_t * | s,
|  | Type | t )

Makes a deep copy of the data in s, which are in byte order t.

## String() [8/11]

TagLib::String::String | ( | char | c,
|  | Type | t = Latin1 )

Makes a deep copy of the data in c.

Note
  This should only be used with the 8-bit codecs Latin1 and UTF8, when used with other codecs it will simply print a warning and exit.

References Latin1.

## String() [9/11]

TagLib::String::String | ( | wchar_t | c,
|  | Type | t = Latin1 )

Makes a deep copy of the data in c.

References Latin1.

## String() [10/11]

TagLib::String::String | ( | const char * | s,
|  | Type | t = Latin1 )

Makes a deep copy of the data in s.

Note
  This should only be used with the 8-bit codecs Latin1 and UTF8, when used with other codecs it will simply print a warning and exit.

References Latin1.

## String() [11/11]

TagLib::String::String | ( | const ByteVector & | v,
|  | Type | t = Latin1 )

Makes a deep copy of the data in v.

References Latin1.

## ~String()

TagLib::String::~String | ( |  | ) |

Destroys this String instance.

## Member Function Documentation

## append()

String & TagLib::String::append | ( | const String & | s | ) |

Append s to the current string and return a reference to the current string.

References String().

## begin() [1/2]

Iterator TagLib::String::begin | ( |  | ) |

Returns an iterator pointing to the beginning of the string.

## begin() [2/2]

ConstIterator TagLib::String::begin | ( |  | ) | const

Returns a const iterator pointing to the beginning of the string.

## cbegin()

ConstIterator TagLib::String::cbegin | ( |  | ) | const

Returns a const iterator pointing to the beginning of the string.

## cend()

ConstIterator TagLib::String::cend | ( |  | ) | const

Returns a const iterator pointing to the end of the string (the position after the last character).

## clear()

String & TagLib::String::clear | ( |  | ) |

Clears the string.

References String().

## data()

ByteVector TagLib::String::data | ( | Type | t | ) | const

Returns a ByteVector containing the string's data. If t is Latin1 or UTF8, this will return a vector of 8 bit characters, otherwise it will use 16 bit characters.

Note
  If t is UTF16, the returned data is encoded in little-endian format and has a BOM.
  The returned data is not null terminated.

## detach()

void TagLib::String::detach | ( |  | ) |

protected

If this String is being shared via implicit sharing, do a deep copy of the data and separate from the shared members. This should be called by all non-const subclass members.

References TAGLIB_MSVC_SUPPRESS_WARNING_NEEDS_TO_HAVE_DLL_INTERFACE.

## end() [1/2]

Iterator TagLib::String::end | ( |  | ) |

Returns an iterator pointing to the end of the string (the position after the last character).

## end() [2/2]

ConstIterator TagLib::String::end | ( |  | ) | const

Returns a const iterator pointing to the end of the string (the position after the last character).

## find()

int TagLib::String::find | ( | const String & | s,
|  | int | offset = 0 ) const

Finds the first occurrence of pattern s in this string starting from offset. If the pattern is not found, -1 is returned.

References String().

## fromLongLong()

String TagLib::String::fromLongLong | ( | long long | n | ) |

static

Converts the base-10 integer n to a string.

References String().

## fromULongLong()

String TagLib::String::fromULongLong | ( | unsigned long long | n | ) |

static

Converts the base-10 integer n to a string.

References String().

## isAscii()

bool TagLib::String::isAscii | ( |  | ) | const

Returns `true` if the file only uses characters required by (7-bit) ASCII.

## isEmpty()

bool TagLib::String::isEmpty | ( |  | ) | const

Returns `true` if the string is empty.

## isLatin1()

bool TagLib::String::isLatin1 | ( |  | ) | const

Returns `true` if the file only uses characters required by Latin1.

## length()

unsigned int TagLib::String::length | ( |  | ) | const

Returns the length of the string. Equivalent to size().

## number()

String TagLib::String::number | ( | int | n | ) |

static

Converts the base-10 integer n to a string.

References String().

## operator!=() [1/3]

bool TagLib::String::operator!= | ( | const char * | s | ) | const

Compares each character of the String with each character of s and returns `false` if the strings match.

## operator!=() [2/3]

bool TagLib::String::operator!= | ( | const String & | s | ) | const

Compares each character of the String with each character of s and returns `false` if the strings match.

References String().

## operator!=() [3/3]

bool TagLib::String::operator!= | ( | const wchar_t * | s | ) | const

Compares each character of the String with each character of s and returns `false` if the strings match.

## operator+=() [1/5]

String & TagLib::String::operator+= | ( | char | c | ) |

Appends c to the end of the String.

References String().

## operator+=() [2/5]

String & TagLib::String::operator+= | ( | const char * | s | ) |

Appends s to the end of the String.

References String().

## operator+=() [3/5]

String & TagLib::String::operator+= | ( | const String & | s | ) |

Appends s to the end of the String.

References String().

## operator+=() [4/5]

String & TagLib::String::operator+= | ( | const wchar_t * | s | ) |

Appends s to the end of the String.

References String().

## operator+=() [5/5]

String & TagLib::String::operator+= | ( | wchar_t | c | ) |

Appends s to the end of the String.

References String().

## operator<()

bool TagLib::String::operator< | ( | const String & | s | ) | const

To be able to use this class in a Map, this operator needed to be implemented. Returns `true` if s is less than this string in a byte-wise comparison.

References String().

## operator=() [1/8]

String & TagLib::String::operator= | ( | char | c | ) |

Performs a deep copy of the data in s.

References String().

## operator=() [2/8]

String & TagLib::String::operator= | ( | const ByteVector & | v | ) |

Performs a deep copy of the data in v.

References String().

## operator=() [3/8]

String & TagLib::String::operator= | ( | const char * | s | ) |

Performs a deep copy of the data in s.

References String().

## operator=() [4/8]

String & TagLib::String::operator= | ( | const std::string & | s | ) |

Performs a deep copy of the data in s.

References String().

## operator=() [5/8]

String & TagLib::String::operator= | ( | const std::wstring & | s | ) |

Performs a deep copy of the data in s.

References String().

## operator=() [6/8]

String & TagLib::String::operator= | ( | const String & | s | ) |

Performs a shallow, implicitly shared, copy of s, overwriting the String's current data.

References String().

## operator=() [7/8]

String & TagLib::String::operator= | ( | const wchar_t * | s | ) |

Performs a deep copy of the data in s.

References String().

## operator=() [8/8]

String & TagLib::String::operator= | ( | wchar_t | c | ) |

Performs a deep copy of the data in s.

References String().

## operator==() [1/3]

bool TagLib::String::operator== | ( | const char * | s | ) | const

Compares each character of the String with each character of s and returns `true` if the strings match.

## operator==() [2/3]

bool TagLib::String::operator== | ( | const String & | s | ) | const

Compares each character of the String with each character of s and returns `true` if the strings match.

References String().

## operator==() [3/3]

bool TagLib::String::operator== | ( | const wchar_t * | s | ) | const

Compares each character of the String with each character of s and returns `true` if the strings match.

## operator[]() [1/2]

wchar_t & TagLib::String::operator[] | ( | int | i | ) |

Returns a reference to the character at position i.

## operator[]() [2/2]

const wchar_t & TagLib::String::operator[] | ( | int | i | ) | const

Returns a const reference to the character at position i.

## rfind()

int TagLib::String::rfind | ( | const String & | s,
|  | int | offset = -1 ) const

Finds the last occurrence of pattern s in this string, searched backwards, either from the end of the string or starting from offset. If the pattern is not found, -1 is returned.

References String().

## size()

unsigned int TagLib::String::size | ( |  | ) | const

Returns the size of the string.

## split()

StringList TagLib::String::split | ( | const String & | separator = " " | ) | const

Splits the string on each occurrence of separator.

References String().

## startsWith()

bool TagLib::String::startsWith | ( | const String & | s | ) | const

Returns `true` if the string starts with the substring s.

References String().

## stripWhiteSpace()

String TagLib::String::stripWhiteSpace | ( |  | ) | const

Returns a string with the leading and trailing whitespace stripped.

References String().

## substr()

String TagLib::String::substr | ( | unsigned int | position,
|  | unsigned int | n = 0xffffffff ) const

Extract a substring from this string starting at position and continuing for n characters.

References String().

## swap()

void TagLib::String::swap | ( | String & | s | ) |

noexcept

Exchanges the content of the String with the content of s.

References String().

## to8Bit()

std::string TagLib::String::to8Bit | ( | bool | unicode = false | ) | const

Returns a deep copy of this String as an `std::string`. The returned string is encoded in UTF8 if unicode is `true`, otherwise Latin1.

See also
  toCString()

## toCString()

const char * TagLib::String::toCString | ( | bool | unicode = false | ) | const

Creates and returns a standard C-style (null-terminated) version of this String. The returned string is encoded in UTF8 if unicode is `true`, otherwise Latin1.

The returned string is still owned by this String and should not be deleted by the user.

The returned pointer remains valid until this String instance is destroyed or toCString() is called again.

Warning
  This however has the side effect that the returned string will remain in memory in addition to other memory that is consumed by this String instance. So, this method should not be used on large strings or where memory is critical. Consider using to8Bit() instead to avoid it.

See also
  to8Bit()

## toCWString()

const wchar_t * TagLib::String::toCWString | ( |  | ) | const

Returns a standard C-style (null-terminated) wide character version of this String. The returned string is encoded in UTF-16 (without BOM/CPU byte order), not UTF-32 even if `wchar_t` is 32-bit wide.

The returned string is still owned by this String and should not be deleted by the user.

The returned pointer remains valid until this String instance is destroyed or any other method of this String is called.

Note
  This returns a pointer to the String's internal data without any conversions.

See also
  toWString()

## toInt()

int TagLib::String::toInt | ( | bool * | ok = nullptr | ) | const

Convert the string to an integer.

If the conversion was successful, it sets the value of *ok to `true` and returns the integer. Otherwise it sets *ok to `false` and the result is undefined.

## toLongLong()

long long TagLib::String::toLongLong | ( | bool * | ok = nullptr,
|  | int | base = 10 ) const

Convert the string to an integer.

If the conversion was successful, it sets the value of *ok to `true` and returns the integer. Otherwise it sets *ok to `false` and the result is undefined.

## toULongLong()

unsigned long long TagLib::String::toULongLong | ( | bool * | ok = nullptr,
|  | int | base = 10 ) const

Convert the string to an integer.

If the conversion was successful, it sets the value of *ok to `true` and returns the integer. Otherwise it sets *ok to `false` and the result is undefined.

## toWString()

std::wstring TagLib::String::toWString | ( |  | ) | const

Returns a deep copy of this String as a `wstring`. The returned string is encoded in UTF-16 (without BOM/CPU byte order), not UTF-32 even if `wchar_t` is 32-bit wide.

See also
  toCWString()

## upper()

String TagLib::String::upper | ( |  | ) | const

Returns an upper case version of the string.

Warning
  This only works for the characters in US-ASCII, i.e. A-Z.

References String().

## Friends And Related Symbol Documentation

## operator+() [1/3]

TAGLIB_EXPORT TagLib::String operator+ | ( | const char * | s1,
|  | const TagLib::String & | s2 )

related

Concatenates s1 and s2 and returns the result as a string.

References TAGLIB_EXPORT.

## operator+() [2/3]

TAGLIB_EXPORT TagLib::String operator+ | ( | const TagLib::String & | s1,
|  | const char * | s2 )

related

Concatenates s1 and s2 and returns the result as a string.

References TAGLIB_EXPORT.

## operator+() [3/3]

TAGLIB_EXPORT TagLib::String operator+ | ( | const TagLib::String & | s1,
|  | const TagLib::String & | s2 )

related

Concatenates s1 and s2 and returns the result as a string.

References TAGLIB_EXPORT.

## operator<<()

TAGLIB_EXPORT std::ostream & operator<< | ( | std::ostream & | s,
|  | const TagLib::String & | str )

related

Send the string to an output stream.

References TAGLIB_EXPORT.

## QStringToTString

#define QStringToTString | ( |  | s | ) |

related

Value:
TagLib::String((s).utf8().data(), TagLib::String::UTF8)
TagLib::String
A wide string class suitable for unicode.
Definition tstring.h:83
TagLib::String::data
ByteVector data(Type t) const
TagLib::String::UTF8
@ UTF8
Definition tstring.h:113

Converts a QString to a TagLib::String without a requirement to link to Qt.

Note
  consider conversion via usual char-by-char for loop to avoid UTF16->UTF8->UTF16 conversion happening in the background

## TStringToQString

#define TStringToQString | ( |  | s | ) |

related

Value:
QString::fromUtf8((s).toCString(true))
TagLib::String::toCString
const char * toCString(bool unicode=false) const

Converts a TagLib::String to a QString without a requirement to link to Qt.

Note
  consider conversion via usual char-by-char for loop to avoid UTF16->UTF8->UTF16 conversion happening in the background

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

- tstring.h