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

#include <tstring.h>

Collaboration diagram for TagLib::String:

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 wstring &s, Type t=WCharByteOrder)
 String (const wchar_t *s, Type t=WCharByteOrder)
 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)
virtual ~String ()
std::string to8Bit (bool unicode=false) const
wstring toWString () const
const char * toCString (bool unicode=false) const
const wchar_t * toCWString () const
Iterator begin ()
ConstIterator begin () const
Iterator end ()
ConstIterator end () 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 (uint position, uint n=0xffffffff) const
Stringappend (const String &s)
String upper () const
uint size () const
uint length () const
bool isEmpty () const
bool isNull () const
ByteVector data (Type t) const
int toInt () const
int toInt (bool *ok) const
String stripWhiteSpace () const
bool isLatin1 () const
bool isAscii () const
wcharoperator[] (int i)
const wcharoperator[] (int i) const
bool operator== (const String &s) const
bool operator!= (const String &s) const
Stringoperator+= (const String &s)
Stringoperator+= (const wchar_t *s)
Stringoperator+= (const char *s)
Stringoperator+= (wchar_t c)
Stringoperator+= (char c)
Stringoperator= (const String &s)
Stringoperator= (const std::string &s)
Stringoperator= (const wstring &s)
Stringoperator= (const wchar_t *s)
Stringoperator= (char c)
Stringoperator= (wchar_t c)
Stringoperator= (const char *s)
Stringoperator= (const ByteVector &v)
bool operator< (const String &s) const

Static Public Member Functions

static String number (int n)

Static Public Attributes

static String null

Protected Member Functions

void detach ()

Related Functions

(Note that these are not member functions.)

#define QStringToTString(s)   TagLib::String(s.utf8().data(), TagLib::String::UTF8)
#define TStringToQString(s)   QString::fromUtf8(s.toCString(true))
TAGLIB_EXPORT const TagLib::String operator+ (const TagLib::String &s1, const TagLib::String &s2)
TAGLIB_EXPORT const TagLib::String operator+ (const char *s1, const TagLib::String &s2)
TAGLIB_EXPORT const 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 TagLib::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 four possible encodings, which are the four supported by the ID3v2 standard.

Member Enumeration Documentation

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

Enumerator:
Latin1 

IS08859-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

TagLib::String::String ( )

Constructs an empty String.

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.

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.
TagLib::String::String ( const wstring s,
Type  t = WCharByteOrder 
)

Makes a deep copy of the data in s.

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

Makes a deep copy of the data in s.

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.
TagLib::String::String ( wchar_t  c,
Type  t = Latin1 
)

Makes a deep copy of the data in c.

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.
TagLib::String::String ( const ByteVector v,
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.
virtual TagLib::String::~String ( )
virtual

Destroys this String instance.

Member Function Documentation

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

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

Iterator TagLib::String::begin ( )

Returns an iterator pointing to the beginning of the string.

ConstIterator TagLib::String::begin ( ) const

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

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.

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.

Iterator TagLib::String::end ( )

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

ConstIterator TagLib::String::end ( ) const

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

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.

bool TagLib::String::isAscii ( ) const

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

bool TagLib::String::isEmpty ( ) const

Returns true if the string is empty.

See Also
isNull()
bool TagLib::String::isLatin1 ( ) const

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

bool TagLib::String::isNull ( ) const

Returns true if this string is null – i.e. it is a copy of the String::null string.

Note
A string can be empty and not null.
See Also
isEmpty()
uint TagLib::String::length ( ) const

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

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

Converts the base-10 integer n to a string.

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.

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

Appends s to the end of the String.

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

Appends s to the end of the String.

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

Appends s to the end of the String.

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

Appends s to the end of the String.

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

Appends c to the end of the String.

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 bytewise comparison.

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

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

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

Performs a deep copy of the data in s.

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

Performs a deep copy of the data in s.

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

Performs a deep copy of the data in s.

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

Performs a deep copy of the data in s.

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

Performs a deep copy of the data in s.

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

Performs a deep copy of the data in s.

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

Performs a deep copy of the data in v.

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.

wchar& TagLib::String::operator[] ( int  i)

Returns a reference to the character at position i.

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

Returns a const reference to the character at position i.

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.

uint TagLib::String::size ( ) const

Returns the size of the string.

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

Splits the string on each occurrence of separator.

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

Returns true if the strings starts with the substring s.

String TagLib::String::stripWhiteSpace ( ) const

Returns a string with the leading and trailing whitespace stripped.

String TagLib::String::substr ( uint  position,
uint  n = 0xffffffff 
) const

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

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

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()
int TagLib::String::toInt ( ) const

Convert the string to an integer.

Returns the integer if the conversion was successful or 0 if the string does not represent a number.

int TagLib::String::toInt ( bool *  ok) const

Convert the string to an integer.

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

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

See Also
toCWString()
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.

Friends And Related Function Documentation

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

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

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

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

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

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

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

Send the string to an output stream.

#define QStringToTString (   s)    TagLib::String(s.utf8().data(), TagLib::String::UTF8)
related

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
#define TStringToQString (   s)    QString::fromUtf8(s.toCString(true))
related

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

Member Data Documentation

String TagLib::String::null
static

A null string provided for convenience.


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