Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

TagLib::String Class Reference

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

#include <tstring.h>

Collaboration diagram for TagLib::String:

Collaboration graph
[legend]
List of all members.

Public Types

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

Public Member Functions

 String ()
 String (const String &s)
 String (const std::string &s, Type t=Latin1)
 String (const wstring &s, Type t=UTF16BE)
 String (const wchar_t *s, Type t=UTF16BE)
 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
const char * toCString (bool unicode=false) const
int find (const String &s, int offset=0) const
String substr (uint position, uint n=0xffffffff) const
Stringappend (const String &s)
String upper () const
uint size () const
bool isEmpty () const
bool isNull () const
ByteVector data (Type t) const
int toInt () const
String stripWhiteSpace () 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

String number (int n)

Static Public Attributes

String null

Protected Member Functions

void detach ()

Related Functions

(Note that these are not member functions.)

const TagLib::String operator+ (const TagLib::String &s1, const TagLib::String &s2)
const TagLib::String operator+ (const char *s1, const TagLib::String &s2)
const TagLib::String operator+ (const TagLib::String &s1, const char *s2)
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-16BE. (Without the BOM (Byte Order Mark)

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

enum TagLib::String::Type
 

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

Enumeration values:
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.


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 = UTF16BE
 

Makes a deep copy of the data in s.

TagLib::String::String const wchar_t *  s,
Type  t = UTF16BE
 

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.

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]
 

int TagLib::String::find const String s,
int  offset = 0
const
 

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

bool TagLib::String::isEmpty  )  const
 

Returns true if the string is empty.

See also:
isNull()

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

String TagLib::String::number int  n  )  [static]
 

Converts the base-10 integer n to a string.

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

Appends c 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+= const char *  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 String s  ) 
 

Appends s 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 ByteVector v  ) 
 

Performs a deep copy of the data in v.

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

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= char  c  ) 
 

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= const wstring s  ) 
 

Performs a deep copy of the data in s.

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

Performs a deep copy of the data in s.

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

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

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.

uint TagLib::String::size  )  const
 

Returns the size of the string.

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
 

If unicode if false (the default) this will return a Latin1 encoded std::string. If it is true the returned std::wstring will be UTF-8 encoded.

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

Creates and returns a C-String based on the data. This string is still owned by the String (class) and as such should not be deleted by the user.

If unicode if false (the default) this string will be encoded in Latin1. If it is true the returned C-String will be UTF-8 encoded.

This string remains valid until the String instance is destroyed or another export method is called.

Warning:
This however has the side effect that this C-String will remain in memory in addition to other memory that is consumed by the String instance. So, this method should not be used on large strings or where memory is critical.

int TagLib::String::toInt  )  const
 

Convert the string to an integer.

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

const TagLib::String operator+ const TagLib::String s1,
const char *  s2
[related]
 

const TagLib::String operator+ const char *  s1,
const TagLib::String s2
[related]
 

const TagLib::String operator+ const TagLib::String s1,
const TagLib::String s2
[related]
 

std::ostream & operator<< std::ostream &  s,
const TagLib::String str
[related]
 

Send the string to an output stream.


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:
Generated on Mon Jun 7 12:51:53 2004 for TagLib by doxygen 1.3.4