X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4cc4bfafe5a31cb96f35b3ec9b19fa2b0b3a4eef..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/string.h?ds=inline diff --git a/interface/string.h b/interface/string.h index 11639efeca..25c36a1d8d 100644 --- a/interface/string.h +++ b/interface/string.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: string.h -// Purpose: documentation for wxStringBuffer class +// Purpose: interface of wxStringBuffer // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -63,70 +63,307 @@ public: Returns the writable pointer to a buffer of the size at least equal to the length specified in the constructor. */ - wxChar* operator wxChar *(); + wxStringCharType* operator wxStringCharType *(); }; + /** @class wxString @wxheader{string.h} - wxString is a class representing a character string. Please see the - @ref overview_wxstringoverview "wxString overview" for more information about - it. - - As explained there, wxString implements most of the methods of the std::string - class. - These standard functions are not documented in this manual, please see the - STL documentation). - The behaviour of all these functions is identical to the behaviour described - there. - - You may notice that wxString sometimes has many functions which do the same - thing like, for example, wxString::Length, - wxString::Len and @c length() which all return the string - length. In all cases of such duplication the @c std::string-compatible - method (@c length() in this case, always the lowercase version) should be - used as it will ensure smoother transition to @c std::string when wxWidgets - starts using it instead of wxString. + wxString is a class representing a Unicode character string. + wxString uses @c std::string internally to store its content + unless this is not supported by the compiler or disabled + specifically when building wxWidgets. Therefore wxString + inherits many features from @c std::string's. Most + implementations of @std::string are thread-safe and don't + use reference counting. By default, wxString uses @c std::string + internally even if wxUSE_STL is not defined. + + Since wxWidgets 3.0 wxString internally uses UCS-2 (basically 2-byte per + character wchar_t) under Windows and UTF-8 under Unix, Linux and + OS X to store its content. Much work has been done to make existing + code using ANSI string literals work as before. If you need to have a + wxString that uses wchar_t on Unix and Linux, too, you can specify + this on the command line with the @c configure @c --disable-utf8 switch. + + As a consequence of this change, iterating over a wxString by index + can become inefficient in UTF8 mode and iterators should be used instead: + + @code + wxString s = "hello"; + wxString::const_iterator i; + for (i = s.begin(); i != s.end(); ++i) + { + wxUniChar uni_ch = *i; + // do something with it + } + @endcode + + Please see the + @ref overview_string "wxString overview" and the + @ref overview_unicode "Unicode overview" for more information + about it. + + wxString uses the current locale encoding to convert any C string + literal to Unicode. The same is done for converting to and from + @c std::string and for the return value of c_str(). For this + conversion, the @a wxConvLibc class instance is used. See wxCSConv and wxMBConv. + + wxString implements most of the methods of the @c std::string class. + These standard functions are only listed here, but they are not + fully documented in this manual. Please see the STL documentation. + The behaviour of all these functions is identical to the behaviour + described there. + + You may notice that wxString sometimes has several functions which do + the same thing like, for example, Length(), Len() and length() which + all return the string length. In all cases of such duplication the + @c std::string compatible method should be used. + + Anything may be concatenated (appended to) with a string. However, you can't + append something to a C string (including literal constants), so to do this it + should be converted to a wxString first. + + @li operator<<() + @li operator+=() + @li operator+() + @li Append() + @li Prepend() + + A string may be constructed either from a C string, (some number of copies of) + a single character or a wide (UNICODE) string. For all constructors (except the + default which creates an empty string) there is also a corresponding assignment + operator. + + @li wxString() + @li operator=() + @li ~wxString() + + The MakeXXX() variants modify the string in place, while the other functions + return a new string which contains the original text converted to the upper or + lower case and leave the original string unchanged. + + @li MakeUpper() + @li Upper() + @li MakeLower() + @li Lower() + + Many functions in this section take a character index in the string. As with C + strings and/or arrays, the indices start from 0, so the first character of a + string is string[0]. Attempt to access a character beyond the end of the + string (which may be even 0 if the string is empty) will provoke an assert + failure in @ref overview_debugging "debug build", but no checks are + done in release builds. + This section also contains both implicit and explicit conversions to C style + strings. Although implicit conversion is quite convenient, it is advised to use + explicit c_str() method for the sake of clarity. + + @li GetChar() + @li GetWritableChar() + @li SetChar() + @li Last() + @li operator[]() + @li c_str() + @li mb_str() + @li wc_str() + @li fn_str() + + The default comparison function Cmp() is case-sensitive and + so is the default version of IsSameAs(). For case + insensitive comparisons you should use CmpNoCase() or + give a second parameter to IsSameAs. This last function is may be more + convenient if only equality of the strings matters because it returns a boolean + @true value if the strings are the same and not 0 (which is usually @false + in C)as Cmp() does. + Matches() is a poor man's regular expression matcher: it only understands + '*' and '?' metacharacters in the sense of DOS command line interpreter. + StartsWith() is helpful when parsing a line of text which should start + with some predefined prefix and is more efficient than doing direct string + comparison as you would also have to precalculate the length of the prefix then. + + @li Cmp() + @li CmpNoCase() + @li IsSameAs() + @li Matches() + @li StartsWith() + @li EndsWith() + + The string provides functions for conversion to signed and unsigned integer and + floating point numbers. All three functions take a pointer to the variable to + put the numeric value in and return @true if the @b entire string could be + converted to a number. + + @li ToLong() + @li ToLongLong() + @li ToULong() + @li ToULongLong() + @li ToDouble() + + These are "advanced" functions and they will be needed quite rarely. + Alloc() and Shrink() are only interesting for optimization purposes. + wxStringBuffer and wxStringBufferLength classes may be very useful + when working with some external API which requires the caller to provide + a writable buffer. + + @li Alloc() + @li Shrink() + @li wxStringBuffer + @li wxStringBufferLength + + Misc. other string functions. + + @li Trim() + @li Truncate() + @li Pad() + + These functions return the string length and check whether the string + is empty or empty it. + + @li Len() + @li IsEmpty() + @li operator!() + @li Empty() + @li Clear() + + + These functions allow to extract substring from this string. All of them don't + modify the original string and return a new string containing the extracted + substring. + + @li Mid() + @li operator()() + @li Left() + @li Right() + @li BeforeFirst() + @li BeforeLast() + @li AfterFirst() + @li AfterLast() + @li StartsWith() + @li EndsWith() + + These functions replace the standard @e strchr() and @e strstr() + functions. + + @li Find() + @li Replace() + + Both formatted versions (Printf/() and stream-like insertion operators + exist (for basic types only). Additionally, the Format() function allows + to use simply append formatted value to a string: + + @li Format() + @li FormatV() + @li Printf() + @li PrintfV() + @li operator>>() + + These functions are deprecated, please consider using new wxWidgets 2.0 + functions instead of them (or, even better, std::string compatible variants). + + Contains(), First(), Freq(), IsAscii(), IsNull(), + IsNumber(), IsWord(), Last(), Length(), LowerCase(), Remove(), Strip(), + SubString(), UpperCase() @library{wxbase} @category{data} @stdobjects - Objects: - wxEmptyString + ::Objects:, ::wxEmptyString, - @seealso - @ref overview_wxstringoverview "wxString overview", @ref overview_unicode + @see @ref overview_string "wxString overview", @ref overview_unicode "Unicode overview" */ class wxString { public: + /** + An 'invalid' value for string index + */ + static const size_t npos; + + /** + @name Standard types + */ //@{ + typedef wxUniChar value_type; + typedef wxUniChar char_type; + typedef wxUniCharRef reference; + typedef wxChar* pointer; + typedef const wxChar* const_pointer; + typedef size_t size_type; + typedef wxUniChar const_reference; + //@} + /** - Initializes the string from first @a nLength characters of C string. - The default value of @c wxSTRING_MAXLEN means take all the string. - In Unicode build, @e conv's - wxMBConv::MB2WC method is called to - convert @a psz to wide string (the default converter uses current locale's - charset). It is ignored in ANSI build. - - @see @ref overview_mbconvclasses "wxMBConv classes", @ref mbstr() - mb_str, @ref wcstr() wc_str + Default constructor */ wxString(); - wxString(const wxString& x); - wxString(wxChar ch, size_t n = 1); - wxString(const wxChar* psz, size_t nLength = wxSTRING_MAXLEN); - wxString(const unsigned char* psz, - size_t nLength = wxSTRING_MAXLEN); - wxString(const wchar_t* psz, const wxMBConv& conv, - size_t nLength = wxSTRING_MAXLEN); - wxString(const char* psz, const wxMBConv& conv = wxConvLibc, - size_t nLength = wxSTRING_MAXLEN); - //@} + + /** + Creates a string from another string. Just increases the ref + count by 1. + */ + wxString(const wxString& stringSrc); + + + /** + Constructs a string from the string literal @e psz using + the current locale encoding to convert it to Unicode (wxConvLibc). + */ + wxString(const char *psz); + + /** + Constructs a string from the string literal @e psz using + @e conv to convert it Unicode. + */ + wxString(const char *psz, const wxMBConv& conv); + + /** + Constructs a string from the first @e nLength character of the string literal @e psz using + the current locale encoding to convert it to Unicode (wxConvLibc). + */ + wxString(const char *psz, size_t nLength); + + /** + Constructs a string from the first @e nLength character of the string literal @e psz using + @e conv to convert it Unicode. + */ + wxString(const char *psz, const wxMBConv& conv, size_t nLength); + + /** + Constructs a string from the string literal @e pwz. + */ + wxString(const wchar_t *pwz); + + /** + Constructs a string from the first @e nLength characters of the string literal @e pwz. + */ + wxString(const wchar_t *pwz, size_t nLength); + + /** + Constructs a string from @e buf using the using + the current locale encoding to convert it to Unicode. + */ + wxString(const wxCharBuffer& buf); + + /** + Constructs a string from @e buf. + */ + wxString(const wxWCharBuffer& buf); + + /** + Constructs a string from @e str using the using the current locale encoding + to convert it to Unicode (wxConvLibc). + */ + wxString(const std::string& str); + + /** + Constructs a string from @e str. + */ + wxString(const std::wstring& str); + /** String destructor. Note that this is not virtual, so wxString must not be @@ -136,99 +373,96 @@ public: /** Gets all the characters after the first occurrence of @e ch. - Returns the empty string if @a ch is not found. + Returns the empty string if @e ch is not found. */ - wxString AfterFirst(wxChar ch); + wxString AfterFirst(wxUniChar ch) const; /** Gets all the characters after the last occurrence of @e ch. - Returns the whole string if @a ch is not found. + Returns the whole string if @e ch is not found. */ - wxString AfterLast(wxChar ch); + wxString AfterLast(wxUniChar ch) const; /** - Preallocate enough space for wxString to store @a nLen characters. This function - may be used to increase speed when the string is constructed by repeated - concatenation as in - - because it will avoid the need to reallocate string memory many times (in case - of long strings). Note that it does not set the maximal length of a string - it - will still expand if more than @a nLen characters are stored in it. Also, it - does not truncate the existing string (use - Truncate() for this) even if its current length is - greater than @e nLen + Preallocate enough space for wxString to store @a nLen characters. + + Please note that this method does the same thing as the standard + reserve() one and shouldn't be used in new code. + + This function may be used to increase speed when the string is + constructed by repeated concatenation as in + + @code + // delete all vowels from the string + wxString DeleteAllVowels(const wxString& original) + { + wxString result; + + size_t len = original.length(); + + result.Alloc(len); + + for ( size_t n = 0; n < len; n++ ) + { + if ( strchr("aeuio", tolower(original[n])) == NULL ) + result += original[n]; + } + + return result; + } + @endcode + + because it will avoid the need to reallocate string memory many times + (in case of long strings). Note that it does not set the maximal length + of a string -- it will still expand if more than @a nLen characters are + stored in it. Also, it does not truncate the existing string (use + Truncate() for this) even if its current length is greater than @a nLen. + + @return @true if memory was successfully allocated, @false otherwise. */ - void Alloc(size_t nLen); + bool Alloc(size_t nLen); - //@{ /** - Concatenates character @a ch to this string, @a count times, returning a - reference - to it. + Appends the string literal @e psz. */ - wxString Append(const wxChar* psz); - wxString Append(wxChar ch, int count = 1); - //@} + wxString& Append(const char* psz); /** - Gets all characters before the first occurrence of @e ch. - Returns the whole string if @a ch is not found. + Appends the wide string literal @e pwz. */ - wxString BeforeFirst(wxChar ch); + wxString& Append(const wchar_t* pwz) /** - Gets all characters before the last occurrence of @e ch. - Returns the empty string if @a ch is not found. + Appends the string literal @e psz with max length @e nLen. */ - wxString BeforeLast(wxChar ch); + wxString& Append(const char* psz, size_t nLen); /** - The MakeXXX() variants modify the string in place, while the other functions - return a new string which contains the original text converted to the upper or - lower case and leave the original string unchanged. - MakeUpper() - - Upper() - - MakeLower() - - Lower() + Appends the wide string literal @e psz with max length @e nLen. */ + wxString& Append(const wchar_t* pwz, size_t nLen) + /** + Appends the string @e s. + */ + wxString &Append(const wxString &s); /** - Many functions in this section take a character index in the string. As with C - strings and/or arrays, the indices start from 0, so the first character of a - string is string[0]. Attempt to access a character beyond the end of the - string (which may be even 0 if the string is empty) will provoke an assert - failure in @ref overview_debuggingoverview "debug build", but no checks are - done in - release builds. - This section also contains both implicit and explicit conversions to C style - strings. Although implicit conversion is quite convenient, it is advised to use - explicit @ref cstr() c_str method for the sake of clarity. Also - see overview for the cases where it is necessary to - use it. - GetChar() - - GetWritableChar() - - SetChar() - - Last() - - @ref operatorbracket() "operator []" - - @ref cstr() c_str - - @ref mbstr() mb_str - - @ref wcstr() wc_str - - @ref fnstr() fn_str - - @ref operatorconstcharpt() "operator const char*" + Appends the character @e ch @e count times. + */ + wxString &Append(wxUniChar ch, size_t count = 1u); + + /** + Gets all characters before the first occurrence of @e ch. + Returns the whole string if @a ch is not found. */ + wxString BeforeFirst(wxUniChar ch) const; + + /** + Gets all characters before the last occurrence of @e ch. + Returns the empty string if @a ch is not found. + */ + wxString BeforeLast(wxUniChar ch) const; /** @@ -237,137 +471,66 @@ public: */ void Clear(); - //@{ + /** + Returns a deep copy of the string. + + That is, the returned string is guaranteed to not share data with this + string when using reference-counted wxString implementation. + + This method is primarily useful for passing strings between threads + (because wxString is not thread-safe). Unlike creating a copy using + @c wxString(c_str()), Clone() handles embedded NULs correctly. + + @since 2.9.0 + */ + wxString Clone() const; + /** Case-sensitive comparison. - Returns a positive value if the string is greater than the argument, zero if - it is equal to it or a negative value if it is less than the argument (same - semantics - as the standard @e strcmp() function). + Returns a positive value if the string is greater than the argument, + zero if it is equal to it or a negative value if it is less than the + argument (same semantics as the standard @c strcmp() function). + See also CmpNoCase(), IsSameAs(). */ - int Cmp(const wxString& s); - int Cmp(const wxChar* psz); - //@} + int Cmp(const wxString& s) const; - //@{ /** Case-insensitive comparison. - Returns a positive value if the string is greater than the argument, zero if - it is equal to it or a negative value if it is less than the argument (same - semantics - as the standard @e strcmp() function). - See also Cmp(), IsSameAs(). - */ - int CmpNoCase(const wxString& s); - int CmpNoCase(const wxChar* psz); - //@} + Returns a positive value if the string is greater than the argument, + zero if it is equal to it or a negative value if it is less than the + argument (same semantics as the standard @c strcmp() function). - /** - Case-sensitive comparison. Returns 0 if equal, 1 if greater or -1 if less. - This is a wxWidgets 1.xx compatibility function; use Cmp() instead. - */ - int CompareTo(const wxChar* psz, caseCompare cmp = exact); - - /** - The default comparison function Cmp() is case-sensitive and - so is the default version of IsSameAs(). For case - insensitive comparisons you should use CmpNoCase() or - give a second parameter to IsSameAs. This last function is may be more - convenient if only equality of the strings matters because it returns a boolean - @true value if the strings are the same and not 0 (which is usually @false in - C) - as @c Cmp() does. - Matches() is a poor man's regular expression matcher: - it only understands '*' and '?' metacharacters in the sense of DOS command line - interpreter. - StartsWith() is helpful when parsing a line of - text which should start with some predefined prefix and is more efficient than - doing direct string comparison as you would also have to precalculate the - length of the prefix then. - Cmp() - - CmpNoCase() - - IsSameAs() - - Matches() - - StartsWith() - - EndsWith() + See also Cmp(), IsSameAs(). */ + int CmpNoCase(const wxString& s) const; //@{ /** - + Comparison operators */ bool operator ==(const wxString& x, const wxString& y); - bool operator ==(const wxString& x, const wxChar* t); + bool operator ==(const wxString& x, wxUniChar ch); bool operator !=(const wxString& x, const wxString& y); - bool operator !=(const wxString& x, const wxChar* t); + bool operator !=(const wxString& x, wxUniChar ch); bool operator(const wxString& x, const wxString& y); - bool operator(const wxString& x, const wxChar* t); + bool operator(const wxString& x, wxUniChar ch); bool operator =(const wxString& x, const wxString& y); - bool operator =(const wxString& x, const wxChar* t); + bool operator =(const wxString& x, wxUniChar ch); bool operator(const wxString& x, const wxString& y); - bool operator(const wxString& x, const wxChar* t); + bool operator(const wxString& x, wxUniChar ch); bool operator =(const wxString& x, const wxString& y); - bool operator =(const wxString& x, const wxChar* t); + bool operator =(const wxString& x, wxUniChar ch); //@} - /** - Anything may be concatenated (appended to) with a string. However, you can't - append something to a C string (including literal constants), so to do this it - should be converted to a wxString first. - @ref operatorout() "operator " - - @ref plusequal() "operator +=" - - @ref operatorplus() "operator +" - - Append() - - Prepend() - */ - - - /** - A string may be constructed either from a C string, (some number of copies of) - a single character or a wide (UNICODE) string. For all constructors (except the - default which creates an empty string) there is also a corresponding assignment - operator. - @ref construct() wxString - - @ref operatorassign() "operator =" - - @ref destruct() ~wxString - */ - /** Returns @true if target appears anywhere in wxString; else @false. This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool Contains(const wxString& str); - - /** - The string provides functions for conversion to signed and unsigned integer and - floating point numbers. All three functions take a pointer to the variable to - put the numeric value in and return @true if the @b entire string could be - converted to a number. - ToLong() - - ToLongLong() - - ToULong() - - ToULongLong() - - ToDouble() - */ + bool Contains(const wxString& str) const; /** @@ -379,36 +542,38 @@ public: /** This function can be used to test if the string ends with the specified @e suffix. If it does, the function will return @true and put the - beginning of the string before the suffix into @a rest string if it is not + beginning of the string before the suffix into @e rest string if it is not @NULL. Otherwise, the function returns @false and doesn't modify the @e rest. */ - bool EndsWith(const wxString& suffix, wxString rest = NULL); + bool EndsWith(const wxString& suffix, wxString *rest = NULL) const; - //@{ /** - Searches for the given string. Returns the starting index, or @c wxNOT_FOUND if - not found. + Searches for the given character @e ch. Returns the position or + @c wxNOT_FOUND if not found. */ - int Find(wxUniChar ch, bool fromEnd = false); - int Find(const wxString& sub); - //@} + int Find(wxUniChar ch, bool fromEnd = false) const; + + /** + Searches for the given string @e sub. Returns the starting position or + @c wxNOT_FOUND if not found. + */ + int Find(const wxString& sub) const; //@{ /** Same as Find(). - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + This is a wxWidgets 1.xx compatibility function; + you should not use it in new code. */ - int First(wxChar c); - int First(const wxChar* psz); - int First(const wxString& str); + int First(wxUniChar ch) const; + int First(const wxString& str) const; //@} /** This static function returns the string containing the result of calling Printf() with the passed parameters on it. - + @see FormatV(), Printf() */ static wxString Format(const wxChar format, ...); @@ -416,27 +581,33 @@ public: /** This static function returns the string containing the result of calling PrintfV() with the passed parameters on it. - + @see Format(), PrintfV() */ static wxString FormatV(const wxChar format, va_list argptr); /** - Returns the number of occurrences of @a ch in the string. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + Returns the number of occurrences of @e ch in the string. + This is a wxWidgets 1.xx compatibility function; you should not + use it in new code. */ - int Freq(wxChar ch); + int Freq(wxUniChar ch) const; //@{ /** - Converts given buffer of binary data from 8-bit string to wxString. In Unicode - build, the string is interpreted as being in ISO-8859-1 encoding. The version - without @a len parameter takes NUL-terminated data. - This is a convenience method useful when storing binary data in wxString. - This function is new since wxWidgets version 2.8.4 - - @see wxString::To8BitData + Converts given buffer of binary data from 8-bit string to wxString. In + Unicode build, the string is interpreted as being in ISO-8859-1 + encoding. The version without @e len parameter takes NUL-terminated + data. + + This is a convenience method useful when storing binary data in + wxString. It should be used @em only for that purpose and only in + conjunction with To8BitData(). Use mb_str() for conversion of character + data to known encoding. + + @since 2.8.4 + + @see wxString::To8BitData() */ static wxString From8BitData(const char* buf, size_t len); static wxString From8BitData(const char* buf); @@ -445,10 +616,7 @@ public: //@{ /** Converts the string or character from an ASCII, 7-bit form - to the native wxString representation. Most useful when using - a Unicode build of wxWidgets (note the use of @c char instead of @c wxChar). - Use @ref construct() "wxString constructors" if you - need to convert from another charset. + to the native wxString representation. */ static wxString FromAscii(const char* s); static wxString FromAscii(const unsigned char* s); @@ -471,66 +639,54 @@ public: /** Returns the character at position @a n (read-only). */ - wxChar GetChar(size_t n); + wxUniChar GetChar(size_t n) const; /** - wxWidgets compatibility conversion. Returns a constant pointer to the data in - the string. + wxWidgets compatibility conversion. Same as c_str(). */ - const wxChar* GetData(); + const wxCStrData* GetData() const; /** Returns a reference to the character at position @e n. */ - wxChar GetWritableChar(size_t n); + wxUniCharRef GetWritableChar(size_t n); /** Returns a writable buffer of at least @a len bytes. It returns a pointer to a new memory block, and the existing data will not be copied. - Call UngetWriteBuf() as soon as - possible to put the string back into a reasonable state. - This method is deprecated, please use - wxStringBuffer or + Call UngetWriteBuf() as soon as possible to put the + string back into a reasonable state. + This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead. */ - wxChar* GetWriteBuf(size_t len); - - //@{ - /** - Same as Find(). - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. - */ - size_t Index(wxChar ch); - size_t Index(const wxChar* sz); - //@} + wxStringCharType* GetWriteBuf(size_t len); /** Returns @true if the string contains only ASCII characters. This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool IsAscii(); + bool IsAscii() const; /** Returns @true if the string is empty. */ - bool IsEmpty(); + bool IsEmpty() const; /** Returns @true if the string is empty (same as wxString::IsEmpty). This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool IsNull(); + bool IsNull() const; /** Returns @true if the string is an integer (with possible sign). This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool IsNumber(); + bool IsNumber() const; //@{ /** @@ -540,8 +696,8 @@ public: Returns @true if the string is equal to the character, @false otherwise. See also Cmp(), CmpNoCase() */ - bool IsSameAs(const wxChar* psz, bool caseSensitive = true); - bool IsSameAs(wxChar c, bool caseSensitive = true); + bool IsSameAs(const wxString &s, bool caseSensitive = true) const; + bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const; //@} /** @@ -549,39 +705,39 @@ public: This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool IsWord(); + bool IsWord() const; //@{ /** Returns a reference to the last character (writable). - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + This is a wxWidgets 1.xx compatibility function; + you should not use it in new code. */ - wxChar Last(); - wxChar Last(); + wxUniCharRef Last(); + const wxUniChar Last(); //@} /** Returns the first @a count characters of the string. */ - wxString Left(size_t count); + wxString Left(size_t count) const; /** Returns the length of the string. */ - size_t Len(); + size_t Len() const; /** Returns the length of the string (same as Len). This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - size_t Length(); + size_t Length() const; /** Returns this string converted to the lower case. */ - wxString Lower(); + wxString Lower() const; /** Same as MakeLower. @@ -593,72 +749,44 @@ public: /** Converts all characters to lower case and returns the result. */ - wxString MakeLower(); + wxString& MakeLower(); /** Converts all characters to upper case and returns the result. */ - wxString MakeUpper(); + wxString& MakeUpper(); /** Returns @true if the string contents matches a mask containing '*' and '?'. */ - bool Matches(const wxString& mask); - - /** - These are "advanced" functions and they will be needed quite rarely. - Alloc() and Shrink() are only - interesting for optimization purposes. - wxStringBuffer - and wxStringBufferLength classes may be very - useful when working with some external API which requires the caller to provide - a writable buffer. - Alloc() - - Shrink() - - wxStringBuffer - - wxStringBufferLength - */ - + bool Matches(const wxString& mask) const; /** Returns a substring starting at @e first, with length @e count, or the rest of the string if @a count is the default value. */ - wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN); - - /** - Other string functions. - Trim() - - Truncate() - - Pad() - */ + wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN) const; /** - Adds @a count copies of @a pad to the beginning, or to the end of the string - (the default). - Removes spaces from the left or from the right (default). + Adds @a count copies of @a pad to the beginning, or to the end of the + string (the default). Removes spaces from the left or from the right (default). */ - wxString Pad(size_t count, wxChar pad = ' ', + wxString& Pad(size_t count, wxUniChar pad = ' ', bool fromRight = true); /** Prepends @a str to this string, returning a reference to this string. */ - wxString Prepend(const wxString& str); + wxString& Prepend(const wxString& str); /** Similar to the standard function @e sprintf(). Returns the number of characters written, or an integer less than zero on error. Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports Unix98-style positional parameters: - - @b NB: This function will use a safe version of @e vsprintf() (usually called + + @note This function will use a safe version of @e vsprintf() (usually called @e vsnprintf()) whenever available to always allocate the buffer of correct size. Unfortunately, this function is not available on all platforms and the dangerous @e vsprintf() will be used then which may lead to buffer overflows. @@ -698,21 +826,12 @@ public: /** Returns the last @a count characters. */ - wxString Right(size_t count); - - /** - These functions replace the standard @e strchr() and @e strstr() - functions. - Find() - - Replace() - */ - + wxString Right(size_t count) const; /** Sets the character at position @e n. */ - void SetChar(size_t n, wxChar ch); + void SetChar(size_t n, wxUniChar ch); /** Minimizes the string's memory. This can be useful after a call to @@ -727,22 +846,7 @@ public: @NULL. Otherwise, the function returns @false and doesn't modify the @e rest. */ - bool StartsWith(const wxString& prefix, wxString rest = NULL); - - /** - These functions return the string length and check whether the string is empty - or empty it. - Len() - - IsEmpty() - - @ref operatornot() operator! - - Empty() - - Clear() - */ - + bool StartsWith(const wxString& prefix, wxString *rest = NULL) const; /** Strip characters at the front and/or end. The same as Trim except that it @@ -750,7 +854,7 @@ public: This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - wxString Strip(stripType s = trailing); + wxString Strip(stripType s = trailing) const; /** Returns the part of the string between the indices @a from and @e to @@ -758,45 +862,23 @@ public: This is a wxWidgets 1.xx compatibility function, use Mid() instead (but note that parameters have different meaning). */ - wxString SubString(size_t from, size_t to); + wxString SubString(size_t from, size_t to) const; + //@{ /** - These functions allow to extract substring from this string. All of them don't - modify the original string and return a new string containing the extracted - substring. - Mid() - - @ref operatorparenth() operator - - Left() - - Right() - - BeforeFirst() - - BeforeLast() - - AfterFirst() - - AfterLast() - - StartsWith() - - EndsWith() - */ + Converts the string to an 8-bit string in ISO-8859-1 encoding in the + form of a wxCharBuffer (Unicode builds only). + This is a convenience method useful when storing binary data in + wxString. It should be used @em only for this purpose. It is only valid + to call this method on strings created using From8BitData(). - //@{ - /** - Converts the string to an 8-bit string in ISO-8859-1 encoding in the form of - a wxCharBuffer (Unicode builds only). - This is a convenience method useful when storing binary data in wxString. - This function is new since wxWidgets version 2.8.4 - - @see wxString::From8BitData + @since 2.8.4 + + @see wxString::From8BitData() */ - const char* To8BitData(); - const wxCharBuffer To8BitData(); + const char* To8BitData() const; + const wxCharBuffer To8BitData() const; //@} //@{ @@ -807,8 +889,8 @@ public: characters. The @ref mbstr() mb_str method provides more powerful means of converting wxString to C string. */ - const char* ToAscii(); - const wxCharBuffer ToAscii(); + const char* ToAscii() const; + const wxCharBuffer ToAscii() const; //@} /** @@ -816,10 +898,10 @@ public: success (the number is stored in the location pointed to by @e val) or @false if the string does not represent such number (the value of @a val is not modified in this case). - + @see ToLong(), ToULong() */ - bool ToDouble(double val); + bool ToDouble(double val) const; /** Attempts to convert the string to a signed integer in base @e base. Returns @@ -834,10 +916,10 @@ public: that you may not want to specify the base 0 if you are parsing the numbers which may have leading zeroes as they can yield unexpected (to the user not familiar with C) results. - + @see ToDouble(), ToULong() */ - bool ToLong(long val, int base = 10); + bool ToLong(long val, int base = 10) const; /** This is exactly the same as ToLong() but works with 64 @@ -845,10 +927,10 @@ public: Notice that currently it doesn't work (always returns @false) if parsing of 64 bit numbers is not supported by the underlying C run-time library. Compilers with C99 support and Microsoft Visual C++ version 7 and higher do support this. - + @see ToLong(), ToULongLong() */ - bool ToLongLong(wxLongLong_t val, int base = 10); + bool ToLongLong(wxLongLong_t val, int base = 10) const; /** Attempts to convert the string to an unsigned integer in base @e base. @@ -861,36 +943,36 @@ public: (e.g. -1 is returned as @c ULONG_MAX). See ToLong() for the more detailed description of the @a base parameter. - + @see ToDouble(), ToLong() */ - bool ToULong(unsigned long val, int base = 10); + bool ToULong(unsigned long val, int base = 10) const; /** This is exactly the same as ToULong() but works with 64 bit integer numbers. Please see ToLongLong() for additional remarks. */ - bool ToULongLong(wxULongLong_t val, int base = 10); + bool ToULongLong(wxULongLong_t val, int base = 10) const; //@{ /** - Same as @ref wxString::utf8str utf8_str. + Same as utf8_str(). */ - const char* ToUTF8(); - const wxCharBuffer ToUF8(); + const char* ToUTF8() const; + const wxCharBuffer ToUF8() const; //@} /** Removes white-space (space, tabs, form feed, newline and carriage return) from the left or from the right end of the string (right is default). */ - wxString Trim(bool fromRight = true); + wxString& Trim(bool fromRight = true); /** Truncate the string to the given length. */ - wxString Truncate(size_t len); + wxString& Truncate(size_t len); //@{ /** @@ -914,7 +996,7 @@ public: /** Returns this string converted to upper case. */ - wxString Upper(); + wxString Upper() const; /** The same as MakeUpper. @@ -924,78 +1006,71 @@ public: void UpperCase(); /** - Both formatted versions (wxString::Printf) and stream-like - insertion operators exist (for basic types only). Additionally, the - Format() function allows to use simply append - formatted value to a string: - - Format() - - FormatV() - - Printf() - - PrintfV() - - @ref operatorout() "operator " - */ - + Returns a pointer to the string data (@c const char* when using UTF-8 + internally, @c const wchar_t* when using UCS-2 internally). - /** - Returns a pointer to the string data (@c const char* in ANSI build, - @c const wchar_t* in Unicode build). Note that the returned value is not convertible to @c char* or - @c wchar_t*, use @ref charstr() char_str or - @ref wcharstr() wchar_string if you need to pass string value - to a function expecting non-const pointer. - - @see @ref mbstr() mb_str, @ref wcstr() wc_str, @ref - fnstr() fn_str, @ref charstr() char_str, @ref - wcharstr() wchar_string + @c wchar_t*, use char_str() or wchar_str() if you need to pass + string value to a function expecting non-const pointer. */ - const wxChar* c_str(); + const wxCStrData c_str() const; /** Returns an object with string data that is implicitly convertible to @c char* pointer. Note that any change to the returned buffer is lost and so this function is only usable for passing strings to legacy libraries that - don't have const-correct API. Use wxStringBuffer if - you want to modify the string. - - @see @ref mbstr() mb_str, @ref wcstr() wc_str, @ref - fnstr() fn_str, @ref cstr() c_str, @ref - wcharstr() wchar_str + don't have const-correct API. Use wxStringBuffer if you want to modify + the string. + + @see c_str() */ - wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc); + wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const; + + /** + Returns buffer of the specified type containing the string data. + + This method is only useful in template code, otherwise you should + directly call mb_str() or wc_str() if you need to retrieve a narrow or + wide string from this wxString. The template parameter @a t should be + either @c char or @c wchar_t. + + Notice that retrieving a char buffer in UTF-8 build will return the + internal string representation in UTF-8 while in wchar_t build the char + buffer will contain the conversion of the string to the encoding of the + current locale (and so can fail). + + @param len If non-@NULL, filled with the length of the returned buffer. + @return + buffer containing the string contents in the specified type, + notice that it may be @NULL if the conversion failed (e.g. Unicode + string couldn't be converted to the current encoding when @a T is + @c char). + */ + template + wxCharTypeBuffer tchar_str(size_t *len = NULL) const; //@{ /** - Returns string representation suitable for passing to OS' functions for - file handling. In ANSI build, this is same as @ref cstr() c_str. - In Unicode build, returned value can be either wide character string - or C string in charset matching the @c wxConvFileName object, depending on - the OS. - - @see wxMBConv, @ref wcstr() wc_str, @ref wcstr() mb_str - */ - const wchar_t* fn_str(); - const char* fn_str(); - const wxCharBuffer fn_str(); + Returns string representation suitable for passing to OS' functions + for file handling. + */ + const wchar_t* fn_str() const; + const char* fn_str() const; + const wxCharBuffer fn_str() const; //@} //@{ /** Returns multibyte (C string) representation of the string. In Unicode build, converts using @e conv's wxMBConv::cWC2MB - method and returns wxCharBuffer. In ANSI build, this function is same - as @ref cstr() c_str. + method and returns wxCharBuffer. In ANSI build, this function + is same as c_str(). The macro wxWX2MBbuf is defined as the correct return type (without const). - - @see wxMBConv, @ref cstr() c_str, @ref wcstr() wc_str, @ref - fnstr() fn_str, @ref charstr() char_str + + @see wxMBConv, c_str(), wc_str(), fn_str(), char_str() */ - const char* mb_str(const wxMBConv& conv = wxConvLibc); - const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc); + const char* mb_str(const wxMBConv& conv = wxConvLibc) const; + const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const; //@} /** @@ -1007,12 +1082,10 @@ public: /** These functions work as C++ stream insertion operators: they insert the given value into the string. Precision or format cannot be set using them, you can - use - Printf() for this. + use Printf() for this. */ wxString operator(const wxString& str); - wxString operator(const wxChar* psz); - wxString operator(wxChar ch); + wxString operator(wxUniChar ch); wxString operator(int i); wxString operator(float f); wxString operator(double d); @@ -1025,13 +1098,11 @@ public: //@{ /** - Concatenation: all these operators return a new string equal to the + Concatenation: these operators return a new string equal to the concatenation of the operands. */ wxString operator +(const wxString& x, const wxString& y); - wxString operator +(const wxString& x, const wxChar* y); - wxString operator +(const wxString& x, wxChar y); - wxString operator +(const wxChar* x, const wxString& y); + wxString operator +(const wxString& x, wxUniChar y); //@} //@{ @@ -1039,8 +1110,7 @@ public: Concatenation in place: the argument is appended to the string. */ void operator +=(const wxString& str); - void operator +=(const wxChar* psz); - void operator +=(wxChar c); + void operator +=(wxUniChar c); //@} //@{ @@ -1049,64 +1119,49 @@ public: constructor (see @ref construct() "wxString constructors"). */ wxString operator =(const wxString& str); - wxString operator =(const wxChar* psz); - wxString operator =(wxChar c); + wxString operator =(wxUniChar c); //@} //@{ /** Element extraction. */ - wxChar operator [](size_t i); - wxChar operator [](size_t i); - wxChar operator [](int i); - wxChar operator [](int i); + wxUniChar operator [](size_t i) const; + wxUniCharRef operator [](size_t i); //@} /** - Implicit conversion to a C string. - */ - operator const wxChar*(); + Empty string is @false, so !string will only return @true if the + string is empty. - /** - Empty string is @false, so !string will only return @true if the string is - empty. - This allows the tests for @NULLness of a @e const wxChar * pointer and emptiness - of the string to look the same in the code and makes it easier to port old code - to wxString. See also IsEmpty(). */ - bool operator!(); - - /** - The supported functions are only listed here, please see any STL reference for - their documentation. - */ + bool operator!() const; //@{ /** - Converts the strings contents to UTF-8 and returns it either as a temporary - wxCharBuffer object or as a pointer to the internal string contents in - UTF-8 build. + Converts the strings contents to UTF-8 and returns it either as a + temporary wxCharBuffer object or as a pointer to the internal + string contents in UTF-8 build. */ - const char* utf8_str(); - const wxCharBuffer utf8_str(); + const char* utf8_str() const; + const wxCharBuffer utf8_str() const; //@} //@{ /** - Returns wide character representation of the string. - In ANSI build, converts using @e conv's wxMBConv::cMB2WC - method and returns wxWCharBuffer. In Unicode build, this function is same - as @ref cstr() c_str. - The macro wxWX2WCbuf is defined as the correct return type (without const). - - @see wxMBConv, @ref cstr() c_str, @ref wcstr() mb_str, @ref - fnstr() fn_str, @ref wcharstr() wchar_str - */ - const wchar_t* wc_str(const wxMBConv& conv); - const wxWCharBuffer wc_str(const wxMBConv& conv); + Converts the strings contents to the wide character represention + and returns it as a temporary wxWCharBuffer object or returns a + pointer to the internal string contents in wide character mode. + + The macro wxWX2WCbuf is defined as the correct return + type (without const). + + @see wxMBConv, c_str(), mb_str(), fn_str(), wchar_str() + */ + const wchar_t* wc_str() const; + const wxWCharBuffer wc_str() const; //@} /** @@ -1115,51 +1170,138 @@ public: not be lost (depending on the build) and so this function is only usable for passing strings to legacy libraries that don't have const-correct API. Use wxStringBuffer if you want to modify the string. - - @see @ref mbstr() mb_str, @ref wcstr() wc_str, @ref - fnstr() fn_str, @ref cstr() c_str, @ref - charstr() char_str + + @see mb_str(), wc_str(), fn_str(), c_str(), char_str() */ - wxWritableWCharBuffer wchar_str(); + wxWritableWCharBuffer wchar_str() const; /** - These functions are deprecated, please consider using new wxWidgets 2.0 - functions instead of them (or, even better, std::string compatible variants). - CompareTo() - - Contains() - - First() - - Freq() - - Index() - - IsAscii() - - IsNull() - - IsNumber() - - IsWord() - - Last() - - Length() - - LowerCase() - - Remove() - - Strip() - - SubString() - - UpperCase() + @name Iterator interface + + These methods return iterators to the beginnnig or + end of the string. */ + //@{ + const_iterator begin() const; + iterator begin(); + const_iterator end() const; + iterator end(); + + const_reverse_iterator rbegin() const; + reverse_iterator rbegin(); + const_reverse_iterator rend() const; + reverse_iterator rend(); + //@} + + /** + @name STL interface + + The supported STL functions are listed here. Please see any + STL reference for their documentation. + */ + //@{ + size_t length() const; + size_type size() const; + size_type max_size() const; + size_type capacity() const; + void reserve(size_t sz); + + void resize(size_t nSize, wxUniChar ch = '\0'); + + wxString& append(const wxString& str, size_t pos, size_t n); + wxString& append(const wxString& str); + wxString& append(const char *sz, size_t n); + wxString& append(const wchar_t *sz, size_t n); + wxString& append(size_t n, wxUniChar ch); + wxString& append(const_iterator first, const_iterator last); + + wxString& assign(const wxString& str, size_t pos, size_t n); + wxString& assign(const wxString& str); + wxString& assign(const char *sz, size_t n); + wxString& assign(const wchar_t *sz, size_t n); + wxString& assign(size_t n, wxUniChar ch); + wxString& assign(const_iterator first, const_iterator last); + + void clear(); + + int compare(const wxString& str) const; + int compare(size_t nStart, size_t nLen, const wxString& str) const; + int compare(size_t nStart, size_t nLen, + const wxString& str, size_t nStart2, size_t nLen2) const; + int compare(size_t nStart, size_t nLen, + const char* sz, size_t nCount = npos) const; + int compare(size_t nStart, size_t nLen, + const wchar_t* sz, size_t nCount = npos) const; + + bool empty() const; + + wxString& erase(size_type pos = 0, size_type n = npos); + iterator erase(iterator first, iterator last); + iterator erase(iterator first); + + size_t find(const wxString& str, size_t nStart = 0) const; + size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const; + size_t find(const wchar_t* sz, size_t nStart = 0, size_t n = npos) const; + size_t find(wxUniChar ch, size_t nStart = 0) const; + + wxString& insert(size_t nPos, const wxString& str); + wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n); + wxString& insert(size_t nPos, const char *sz, size_t n); + wxString& insert(size_t nPos, const wchar_t *sz, size_t n); + wxString& insert(size_t nPos, size_t n, wxUniChar ch); + iterator insert(iterator it, wxUniChar ch); + void insert(iterator it, const_iterator first, const_iterator last); + void insert(iterator it, size_type n, wxUniChar ch); + + wxString& replace(size_t nStart, size_t nLen, const wxString& str); + wxString& replace(size_t nStart, size_t nLen, size_t nCount, wxUniChar ch); + wxString& replace(size_t nStart, size_t nLen, + const wxString& str, size_t nStart2, size_t nLen2); + wxString& replace(size_t nStart, size_t nLen, + const char* sz, size_t nCount); + wxString& replace(size_t nStart, size_t nLen, + const wchar_t* sz, size_t nCount); + wxString& replace(size_t nStart, size_t nLen, + const wxString& s, size_t nCount); + wxString& replace(iterator first, iterator last, const wxString& s); + wxString& replace(iterator first, iterator last, const char* s, size_type n); + wxString& replace(iterator first, iterator last, const wchar_t* s, size_type n); + wxString& replace(iterator first, iterator last, size_type n, wxUniChar ch); + wxString& replace(iterator first, iterator last, + const_iterator first1, const_iterator last1); + wxString& replace(iterator first, iterator last, + const char *first1, const char *last1); + wxString& replace(iterator first, iterator last, + const wchar_t *first1, const wchar_t *last1); + + size_t rfind(const wxString& str, size_t nStart = npos) const; + size_t rfind(const char* sz, size_t nStart = npos, size_t n = npos) const; + size_t rfind(const wchar_t* sz, size_t nStart = npos, size_t n = npos) const; + size_t rfind(wxUniChar ch, size_t nStart = npos) const; + + wxString substr(size_t nStart = 0, size_t nLen = npos) const; + + void swap(wxString& str); + + //@} + }; +/** + FIXME +*/ +wxString Objects: +; + +/** + FIXME +*/ +wxString wxEmptyString; + + + + /** @class wxStringBufferLength @wxheader{string.h} @@ -1233,26 +1375,3 @@ public: wxChar* operator wxChar *(); }; - -// ============================================================================ -// Global functions/macros -// ============================================================================ - -//@{ -/** - Converts its argument to string. - See also: wxFromString. -*/ -wxString wxToString(const wxColour& col); -wxString wxToString(const wxFont& col); -//@} - -//@{ -/** - Converts string to the type of the second argument. Returns @true on success. - See also: wxToString. -*/ -bool wxFromString(const wxString& str, wxColour* col); -bool wxFromString(const wxString& str, wxFont* col); -//@} -