1
/***************************************************************************
2
copyright : (C) 2002 - 2008 by Scott Wheeler
3
email : wheeler@kde.org
4
***************************************************************************/
6
/***************************************************************************
7
* This library is free software; you can redistribute it and/or modify *
8
* it under the terms of the GNU Lesser General Public License version *
9
* 2.1 as published by the Free Software Foundation. *
11
* This library is distributed in the hope that it will be useful, but *
12
* WITHOUT ANY WARRANTY; without even the implied warranty of *
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
14
* Lesser General Public License for more details. *
16
* You should have received a copy of the GNU Lesser General Public *
17
* License along with this library; if not, write to the Free Software *
18
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 *
21
* Alternatively, this file is available under the Mozilla Public *
22
* License Version 1.1. You may obtain a copy of the License at *
23
* http://www.mozilla.org/MPL/ *
24
***************************************************************************/
26
#ifndef TAGLIB_STRING_H
27
#define TAGLIB_STRING_H
29
#include "taglib_export.h"
31
#include "tbytevector.h"
37
* \relates TagLib::String
39
* Converts a TagLib::String to a QString without a requirement to link to Qt.
41
#define QStringToTString(s) TagLib::String(s.utf8().data(), TagLib::String::UTF8)
44
* \relates TagLib::String
46
* Converts a TagLib::String to a QString without a requirement to link to Qt.
48
#define TStringToQString(s) QString::fromUtf8(s.toCString(true))
52
//! A \e wide string class suitable for unicode.
55
* This is an implicitly shared \e wide string. For storage it uses
56
* TagLib::wstring, but as this is an <i>implementation detail</i> this of
57
* course could change. Strings are stored internally as UTF-16BE. (Without
58
* the BOM (Byte Order Mark)
60
* The use of implicit sharing means that copying a string is cheap, the only
61
* \e cost comes into play when the copy is modified. Prior to that the string
62
* just has a pointer to the data of the \e parent String. This also makes
63
* this class suitable as a function return type.
65
* In addition to adding implicit sharing, this class keeps track of four
66
* possible encodings, which are the four supported by the ID3v2 standard.
69
class TAGLIB_EXPORT String
73
#ifndef DO_NOT_DOCUMENT
74
typedef std::basic_string<wchar>::iterator Iterator;
75
typedef std::basic_string<wchar>::const_iterator ConstIterator;
79
* The four types of string encodings supported by the ID3v2 specification.
80
* ID3v1 is assumed to be Latin1 and Ogg Vorbis comments use UTF8.
84
* IS08859-1, or <i>Latin1</i> encoding. 8 bit characters.
88
* UTF16 with a <i>byte order mark</i>. 16 bit characters.
92
* UTF16 <i>big endian</i>. 16 bit characters. This is the encoding used
93
* internally by TagLib.
97
* UTF8 encoding. Characters are usually 8 bits but can be up to 32.
101
* UTF16 <i>little endian</i>. 16 bit characters.
107
* Constructs an empty String.
112
* Make a shallow, implicitly shared, copy of \a s. Because this is
113
* implicitly shared, this method is lightweight and suitable for
114
* pass-by-value usage.
116
String(const String &s);
119
* Makes a deep copy of the data in \a s.
121
* \note This should only be used with the 8-bit codecs Latin1 and UTF8, when
122
* used with other codecs it will simply print a warning and exit.
124
String(const std::string &s, Type t = Latin1);
127
* Makes a deep copy of the data in \a s.
129
String(const wstring &s, Type t = UTF16BE);
132
* Makes a deep copy of the data in \a s.
134
String(const wchar_t *s, Type t = UTF16BE);
137
* Makes a deep copy of the data in \a c.
139
* \note This should only be used with the 8-bit codecs Latin1 and UTF8, when
140
* used with other codecs it will simply print a warning and exit.
142
String(char c, Type t = Latin1);
145
* Makes a deep copy of the data in \a c.
147
String(wchar_t c, Type t = Latin1);
151
* Makes a deep copy of the data in \a s.
153
* \note This should only be used with the 8-bit codecs Latin1 and UTF8, when
154
* used with other codecs it will simply print a warning and exit.
156
String(const char *s, Type t = Latin1);
159
* Makes a deep copy of the data in \a s.
161
* \note This should only be used with the 8-bit codecs Latin1 and UTF8, when
162
* used with other codecs it will simply print a warning and exit.
164
String(const ByteVector &v, Type t = Latin1);
167
* Destroys this String instance.
172
* If \a unicode if false (the default) this will return a \e Latin1 encoded
173
* std::string. If it is true the returned std::wstring will be UTF-8
176
std::string to8Bit(bool unicode = false) const;
179
* Returns a wstring version of the TagLib string as a wide string.
181
wstring toWString() const;
184
* Creates and returns a C-String based on the data. This string is still
185
* owned by the String (class) and as such should not be deleted by the user.
187
* If \a unicode if false (the default) this string will be encoded in
188
* \e Latin1. If it is true the returned C-String will be UTF-8 encoded.
190
* This string remains valid until the String instance is destroyed or
191
* another export method is called.
193
* \warning This however has the side effect that this C-String will remain
194
* in memory <b>in addition to</b> other memory that is consumed by the
195
* String instance. So, this method should not be used on large strings or
196
* where memory is critical.
198
const char *toCString(bool unicode = false) const;
201
* Returns an iterator pointing to the beginning of the string.
206
* Returns a const iterator pointing to the beginning of the string.
208
ConstIterator begin() const;
211
* Returns an iterator pointing to the end of the string (the position
212
* after the last character).
217
* Returns a const iterator pointing to the end of the string (the position
218
* after the last character).
220
ConstIterator end() const;
223
* Finds the first occurrence of pattern \a s in this string starting from
224
* \a offset. If the pattern is not found, -1 is returned.
226
int find(const String &s, int offset = 0) const;
229
* Returns true if the strings starts with the substring \a s.
231
bool startsWith(const String &s) const;
234
* Extract a substring from this string starting at \a position and
235
* continuing for \a n characters.
237
String substr(uint position, uint n = 0xffffffff) const;
240
* Append \a s to the current string and return a reference to the current
243
String &append(const String &s);
246
* Returns an upper case version of the string.
248
* \warning This only works for the characters in US-ASCII, i.e. A-Z.
250
String upper() const;
253
* Returns the size of the string.
258
* Returns the length of the string. Equivalent to size().
263
* Returns true if the string is empty.
267
bool isEmpty() const;
270
* Returns true if this string is null -- i.e. it is a copy of the
271
* String::null string.
273
* \note A string can be empty and not null.
279
* Returns a ByteVector containing the string's data. If \a t is Latin1 or
280
* UTF8, this will return a vector of 8 bit characters, otherwise it will use
283
ByteVector data(Type t) const;
286
* Convert the string to an integer.
291
* Returns a string with the leading and trailing whitespace stripped.
293
String stripWhiteSpace() const;
296
* Returns true if the file only uses characters required by Latin1.
298
bool isLatin1() const;
301
* Returns true if the file only uses characters required by (7-bit) ASCII.
303
bool isAscii() const;
306
* Converts the base-10 integer \a n to a string.
308
static String number(int n);
311
* Returns a reference to the character at position \a i.
313
wchar &operator[](int i);
316
* Returns a const reference to the character at position \a i.
318
const wchar &operator[](int i) const;
321
* Compares each character of the String with each character of \a s and
322
* returns true if the strings match.
324
bool operator==(const String &s) const;
327
* Appends \a s to the end of the String.
329
String &operator+=(const String &s);
332
* Appends \a s to the end of the String.
334
String &operator+=(const wchar_t* s);
337
* Appends \a s to the end of the String.
339
String &operator+=(const char* s);
342
* Appends \a s to the end of the String.
344
String &operator+=(wchar_t c);
347
* Appends \a c to the end of the String.
349
String &operator+=(char c);
352
* Performs a shallow, implicitly shared, copy of \a s, overwriting the
353
* String's current data.
355
String &operator=(const String &s);
358
* Performs a deep copy of the data in \a s.
360
String &operator=(const std::string &s);
363
* Performs a deep copy of the data in \a s.
365
String &operator=(const wstring &s);
368
* Performs a deep copy of the data in \a s.
370
String &operator=(const wchar_t *s);
373
* Performs a deep copy of the data in \a s.
375
String &operator=(char c);
378
* Performs a deep copy of the data in \a s.
380
String &operator=(wchar_t c);
383
* Performs a deep copy of the data in \a s.
385
String &operator=(const char *s);
388
* Performs a deep copy of the data in \a v.
390
String &operator=(const ByteVector &v);
393
* To be able to use this class in a Map, this operator needed to be
394
* implemented. Returns true if \a s is less than this string in a bytewise
397
bool operator<(const String &s) const;
400
* A null string provided for convenience.
406
* If this String is being shared via implicit sharing, do a deep copy of the
407
* data and separate from the shared members. This should be called by all
408
* non-const subclass members.
414
* This checks to see if the string is in \e UTF-16 (with BOM) or \e UTF-8
415
* format and if so converts it to \e UTF-16BE for internal use. \e Latin1
416
* does not require conversion since it is a subset of \e UTF-16BE and
417
* \e UTF16-BE requires no conversion since it is used internally.
419
void prepare(Type t);
428
* \relates TagLib::String
430
* Concatenates \a s1 and \a s2 and returns the result as a string.
432
TAGLIB_EXPORT const TagLib::String operator+(const TagLib::String &s1, const TagLib::String &s2);
435
* \relates TagLib::String
437
* Concatenates \a s1 and \a s2 and returns the result as a string.
439
TAGLIB_EXPORT const TagLib::String operator+(const char *s1, const TagLib::String &s2);
442
* \relates TagLib::String
444
* Concatenates \a s1 and \a s2 and returns the result as a string.
446
TAGLIB_EXPORT const TagLib::String operator+(const TagLib::String &s1, const char *s2);
450
* \relates TagLib::String
452
* Send the string to an output stream.
454
TAGLIB_EXPORT std::ostream &operator<<(std::ostream &s, const TagLib::String &str);
added
removed
Frameworks/taglib/taglib/taglib/toolkit/tstring.h
