X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b2ceedadb12d5141966209ab4b5e096c064135c5..b5fe7ca67bf3121959a0b5a59afd00c1708f2f03:/interface/wx/string.h diff --git a/interface/wx/string.h b/interface/wx/string.h index f8d8d715b3..b937a5267b 100644 --- a/interface/wx/string.h +++ b/interface/wx/string.h @@ -1,277 +1,253 @@ ///////////////////////////////////////////////////////////////////////////// // Name: string.h -// Purpose: interface of wxStringBuffer +// Purpose: interface of wxStringBuffer, wxString // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// + /** - @class wxStringBuffer + @class wxString - This tiny class allows to conveniently access the wxString - internal buffer as a writable pointer without any risk of forgetting to restore - the string to the usable state later. + The wxString class has been completely rewritten for wxWidgets 3.0 + and this change was actually the main reason for the calling that + version wxWidgets 3.0. - For example, assuming you have a low-level OS function called - @c GetMeaningOfLifeAsString(char *) returning the value in the provided - buffer (which must be writable, of course) you might call it like this: + wxString is a class representing a Unicode character string. + wxString uses @c std::basic_string internally (even if @c wxUSE_STL is not defined) + to store its content (unless this is not supported by the compiler or disabled + specifically when building wxWidgets) and it therefore inherits + many features from @c std::basic_string. (Note that most implementations of + @c std::basic_string are thread-safe and don't use reference counting.) + + These @c std::basic_string standard functions are only listed here, but + they are not fully documented in this manual; see the STL documentation + (http://www.cppreference.com/wiki/string/start) for more info. + The behaviour of all these functions is identical to the behaviour + described there. - @code - wxString theAnswer; - GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024)); - if ( theAnswer != "42" ) - { - wxLogError("Something is very wrong!"); - } - @endcode + You may notice that wxString sometimes has several functions which do + the same thing like Length(), Len() and length() which all return the + string length. In all cases of such duplication the @c std::string + compatible methods should be used. - Note that the exact usage of this depends on whether on not wxUSE_STL is - enabled. If - wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer, - and - if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same - buffer - wxString uses intact. In other words, relying on wxStringBuffer containing the - old - wxString data is probably not a good idea if you want to build your program in - both - with and without wxUSE_STL. + For informations about the internal encoding used by wxString and + for important warnings and advices for using it, please read + the @ref overview_string. - @library{wxbase} - @category{FIXME} -*/ -class wxStringBuffer -{ -public: - /** - Constructs a writable string buffer object associated with the given string - and containing enough space for at least @a len characters. Basically, this - is equivalent to calling wxString::GetWriteBuf and - saving the result. - */ - wxStringBuffer(const wxString& str, size_t len); + Since wxWidgets 3.0 wxString always stores Unicode strings, so you should + be sure to read also @ref overview_unicode. - /** - Restores the string passed to the constructor to the usable state by calling - wxString::UngetWriteBuf on it. - */ - ~wxStringBuffer(); - /** - Returns the writable pointer to a buffer of the size at least equal to the - length specified in the constructor. - */ - wxStringCharType* operator wxStringCharType *(); -}; + @section string_construct Constructors and assignment operators + 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() + @li assign() -/** - @class wxString + @section string_len String length - 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: + These functions return the string length and check whether the string + is empty or they empty it. - @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 + @li length() + @li size() + @li Len() + @li IsEmpty() + @li operator!() + @li Empty() + @li Clear() - 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. + @section string_access Character access - 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. + Many functions below take a character index in the string. As with C + strings and arrays, the indices start from 0, so the first character of a + string is string[0]. An attempt to access a character beyond the end of the + string (which may even be 0 if the string is empty) will provoke an assert + failure in @ref overview_debugging "debug builds", 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, you are advised + to use wc_str() for the sake of clarity. + + @li GetChar() + @li GetWritableChar() + @li SetChar() + @li Last() + @li operator[]() + @li wc_str() + @li utf8_str() + @li c_str() + @li wx_str() + @li mb_str() + @li fn_str() + + + @section string_concat Concatenation + + 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 insert() + @li append() + @li operator<<() + @li operator+=() + @li operator+() + @li Append() + @li Prepend() + + + @section string_comp Comparison + + 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 maybe 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. + + @li compare() + @li Cmp() + @li CmpNoCase() + @li IsSameAs() + @li Matches() + @li StartsWith() + @li EndsWith() + + + @section string_substring Substring extraction + + These functions allow you to extract a substring from the string. The + original string is not modified and the function returns the extracted + substring. + + @li at() + @li substr() + @li Mid() + @li operator()() + @li Left() + @li Right() + @li BeforeFirst() + @li BeforeLast() + @li AfterFirst() + @li AfterLast() + @li StartsWith() + @li EndsWith() + + + @section string_case Case conversion + + 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() + @li MakeCapitalized() + @li Capitalize() + + + @section string_search Searching and replacing + + These functions replace the standard @e strchr() and @e strstr() + functions. + + @li find() + @li rfind() + @li replace() + @li Find() + @li Replace() + + + @section string_conv Conversion to numbers + + The string provides functions for conversion to signed and unsigned integer and + floating point numbers. All 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() + + + @section string_fmt Writing values into the string + + Both formatted versions (Printf/() and stream-like insertion operators + exist (for basic types only). Additionally, the Format() function allows + you to simply append a formatted value to a string: + + @li Format() + @li FormatV() + @li Printf() + @li PrintfV() + @li operator>>() + + + @section string_mem Memory management + + The following are "advanced" functions and they will be needed 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 reserve() + @li resize() + @li Alloc() + @li Shrink() + @li wxStringBuffer + @li wxStringBufferLength + + + @section string_misc Miscellaneous + + Miscellaneous other string functions. + + @li Trim() + @li Truncate() + @li Pad() + + + @section string_compat wxWidgets 1.xx compatibility functions + + The following functions are deprecated. + Please consider using @c std::string compatible variants. + + Contains(), First(), Freq(), IsAscii(), IsNull(), IsNumber(), IsWord(), + Last(), Length(), LowerCase(), Remove(), Strip(), SubString(), UpperCase() - 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, + ::wxEmptyString - @see @ref overview_string "wxString overview", @ref overview_unicode - "Unicode overview" + @see @ref overview_string, @ref overview_unicode, wxUString, + wxCharBuffer, wxUniChar, wxStringTokenizer, @ref group_funcmacro_string */ class wxString { @@ -300,8 +276,8 @@ public: wxString(); /** - Creates a string from another string. Just increases the ref - count by 1. + Creates a string from another string. + Just increases the ref count by 1. */ wxString(const wxString& stringSrc); @@ -341,8 +317,8 @@ public: 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. + Constructs a string from @e buf using the using the current locale + encoding to convert it to Unicode. */ wxString(const wxCharBuffer& buf); @@ -364,8 +340,9 @@ public: /** - String destructor. Note that this is not virtual, so wxString must not be - inherited from. + String destructor. + + Note that this is not virtual, so wxString must not be inherited from. */ ~wxString(); @@ -428,7 +405,7 @@ public: /** Appends the wide string literal @e pwz. */ - wxString& Append(const wchar_t* pwz) + wxString& Append(const wchar_t* pwz); /** Appends the string literal @e psz with max length @e nLen. @@ -438,12 +415,12 @@ public: /** Appends the wide string literal @e psz with max length @e nLen. */ - wxString& Append(const wchar_t* pwz, size_t nLen) + wxString& Append(const wchar_t* pwz, size_t nLen); /** Appends the string @e s. */ - wxString &Append(const wxString &s); + wxString& Append(const wxString& s); /** Appends the character @e ch @e count times. @@ -462,6 +439,15 @@ public: */ wxString BeforeLast(wxUniChar ch) const; + /** + Return the copy of the string with the first string character in the + upper case and the subsequent ones in the lower case. + + @since 2.9.0 + + @see MakeCapitalized() + */ + wxString Capitalize() const; /** Empties the string and frees memory occupied by it. @@ -503,26 +489,6 @@ public: */ int CmpNoCase(const wxString& s) const; - - //@{ - /** - Comparison operators - */ - bool operator ==(const wxString& x, const wxString& y); - bool operator ==(const wxString& x, wxUniChar ch); - bool operator !=(const wxString& x, const wxString& y); - bool operator !=(const wxString& x, wxUniChar ch); - bool operator(const wxString& x, const wxString& y); - bool operator(const wxString& x, wxUniChar ch); - bool operator =(const wxString& x, const wxString& y); - bool operator =(const wxString& x, wxUniChar ch); - bool operator(const wxString& x, const wxString& y); - bool operator(const wxString& x, wxUniChar ch); - bool operator =(const wxString& x, const wxString& y); - bool operator =(const wxString& x, wxUniChar ch); - //@} - - /** 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 @@ -574,7 +540,7 @@ public: @see FormatV(), Printf() */ - static wxString Format(const wxChar format, ...); + static wxString Format(const wxString& format, ...); /** This static function returns the string containing the result of calling @@ -582,7 +548,7 @@ public: @see Format(), PrintfV() */ - static wxString FormatV(const wxChar format, va_list argptr); + static wxString FormatV(const wxString& format, va_list argptr); /** Returns the number of occurrences of @e ch in the string. @@ -626,14 +592,39 @@ public: //@{ /** Converts C string encoded in UTF-8 to wxString. - Note that this method assumes that @a s is a valid UTF-8 sequence and - doesn't do any validation in release builds, it's validity is only checked in - debug builds. + + If @a s is not a valid UTF-8 string, an empty string is returned. + + Notice that when using UTF-8 wxWidgets build there is a more efficient + alternative to this function called FromUTF8Unchecked() which, unlike + this one, doesn't check that the input string is valid. + + @since 2.8.4 */ static wxString FromUTF8(const char* s); static wxString FromUTF8(const char* s, size_t len); //@} + //@{ + /** + Converts C string encoded in UTF-8 to wxString without checking its + validity. + + This method assumes that @a s is a valid UTF-8 sequence and doesn't do + any validation (although an assert failure is triggered in debug builds + if the string is invalid). Only use it if you are absolutely sure that + @a s is a correct UTF-8 string (e.g. because it comes from another + library using UTF-8) and if the performance matters, otherwise use + slower (in UTF-8 build) but safer FromUTF8(). Passing a bad UTF-8 + string to this function will result in creating a corrupted wxString + and all the subsequent operations on it will be undefined. + + @since 2.8.9 + */ + static wxString FromUTF8Unchecked(const char* s); + static wxString FromUTF8Unchecked(const char* s, size_t len); + //@} + /** Returns the character at position @a n (read-only). */ @@ -642,7 +633,7 @@ public: /** wxWidgets compatibility conversion. Same as c_str(). */ - const wxCStrData* GetData() const; + const wxCStrData GetData() const; /** Returns a reference to the character at position @e n. @@ -662,6 +653,8 @@ public: /** Returns @true if the string contains only ASCII characters. + See wxUniChar::IsAscii for more details. + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -734,6 +727,8 @@ public: /** Returns this string converted to the lower case. + + @see MakeLower() */ wxString Lower() const; @@ -745,12 +740,28 @@ public: void LowerCase(); /** - Converts all characters to lower case and returns the result. + Converts the first characters of the string to the upper case and all + the subsequent ones to the lower case and returns the result. + + @since 2.9.0 + + @see Capitalize() + */ + wxString& MakeCapitalized(); + + /** + Converts all characters to lower case and returns the reference to the + modified string. + + @see Lower() */ wxString& MakeLower(); /** - Converts all characters to upper case and returns the result. + Converts all characters to upper case and returns the reference to the + modified string. + + @see Upper() */ wxString& MakeUpper(); @@ -763,15 +774,14 @@ public: 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) const; + wxString Mid(size_t first, size_t nCount = wxString::npos) 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). */ - wxString& Pad(size_t count, wxUniChar pad = ' ', - bool fromRight = true); + wxString& Pad(size_t count, wxUniChar chPad = ' ', bool fromRight = true); /** Prepends @a str to this string, returning a reference to this string. @@ -789,14 +799,14 @@ public: 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. */ - int Printf(const wxChar* pszFormat, ...); + int Printf(const wxString& pszFormat, ...); /** Similar to vprintf. Returns the number of characters written, or an integer less than zero on error. */ - int PrintfV(const wxChar* pszFormat, va_list argPtr); + int PrintfV(const wxString& pszFormat, va_list argPtr); //@{ /** @@ -811,7 +821,7 @@ public: /** Removes the last character. */ - wxString RemoveLast(); + wxString& RemoveLast(size_t n = 1); /** Replace first (or all) occurrences of substring with another one. @@ -835,7 +845,7 @@ public: Minimizes the string's memory. This can be useful after a call to Alloc() if too much memory were preallocated. */ - void Shrink(); + bool Shrink(); /** This function can be used to test if the string starts with the specified @@ -884,7 +894,7 @@ public: Converts the string to an ASCII, 7-bit string in the form of a wxCharBuffer (Unicode builds only) or a C string (ANSI builds). Note that this conversion only works if the string contains only ASCII - characters. The @ref mbstr() mb_str method provides more + characters. The @ref mb_str() "mb_str" method provides more powerful means of converting wxString to C string. */ const char* ToAscii() const; @@ -899,7 +909,7 @@ public: @see ToLong(), ToULong() */ - bool ToDouble(double val) const; + bool ToDouble(double* val) const; /** Attempts to convert the string to a signed integer in base @e base. Returns @@ -917,7 +927,7 @@ public: @see ToDouble(), ToULong() */ - bool ToLong(long val, int base = 10) const; + bool ToLong(long* val, int base = 10) const; /** This is exactly the same as ToLong() but works with 64 @@ -928,37 +938,38 @@ public: @see ToLong(), ToULongLong() */ - bool ToLongLong(wxLongLong_t val, int base = 10) const; + bool ToLongLong(wxLongLong_t* val, int base = 10) const; /** Attempts to convert the string to an unsigned integer in base @e base. Returns @true on success in which case the number is stored in the location pointed to by @a val or @false if the string does not represent a valid number in the given base (the value of @a val is not - modified in this case). Please notice that this function - behaves in the same way as the standard @c strtoul() and so it simply - converts negative numbers to unsigned representation instead of rejecting them - (e.g. -1 is returned as @c ULONG_MAX). - See ToLong() for the more detailed - description of the @a base parameter. + modified in this case). + + Please notice that this function behaves in the same way as the standard + @c strtoul() and so it simply converts negative numbers to unsigned + representation instead of rejecting them (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) const; + 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) const; + bool ToULongLong(wxULongLong_t* val, int base = 10) const; //@{ /** Same as utf8_str(). */ const char* ToUTF8() const; - const wxCharBuffer ToUF8() const; + const wxCharBuffer ToUTF8() const; //@} /** @@ -975,16 +986,16 @@ public: //@{ /** Puts the string back into a reasonable state (in which it can be used - normally), after - GetWriteBuf() was called. + normally), after GetWriteBuf() was called. + The version of the function without the @a len parameter will calculate the new string length itself assuming that the string is terminated by the first @c NUL character in it while the second one will use the specified length and thus is the only version which should be used with the strings with embedded @c NULs (it is also slightly more efficient as @c strlen() doesn't have to be called). - This method is deprecated, please use - wxStringBuffer or + + This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead. */ void UngetWriteBuf(); @@ -993,11 +1004,14 @@ public: /** Returns this string converted to upper case. + + @see MakeUpper() */ wxString Upper() const; /** - The same as MakeUpper. + The same as MakeUpper(). + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -1006,16 +1020,18 @@ public: /** Returns a lightweight intermediate class which is in turn implicitly convertible to both @c const @c char* and to @c const @c wchar_t*. - - Please see the @ref overview_unicode "Unicode overview" for more - information about it. - + Given this ambiguity it is mostly better to use wc_str(), mb_str() or + utf8_str() instead. + + Please see the @ref overview_unicode for more information about it. + Note that the returned value is not convertible to @c char* or @c wchar_t*, use char_str() or wchar_str() if you need to pass string value to a function expecting non-const pointer. - + + @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str() */ - const wxCStrData c_str() const; + wxCStrData c_str() const; /** Returns an object with string data that is implicitly convertible to @@ -1041,7 +1057,9 @@ public: 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. + @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 @@ -1061,42 +1079,48 @@ public: 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 c_str(). - The macro wxWX2MBbuf is defined as the correct return type (without const). + Returns the multibyte (C string) representation of the string + using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer. - @see wxMBConv, c_str(), wc_str(), fn_str(), char_str() + @see wc_str(), utf8_str(), c_str(), wxMBConv */ - const char* mb_str(const wxMBConv& conv = wxConvLibc) const; const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const; - //@} /** Extraction from a stream. */ - friend istream operator(istream& is, wxString& str); + friend istream operator>>(istream& is, wxString& str); //@{ /** - 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. - */ - wxString operator(const wxString& str); - wxString operator(wxUniChar ch); - wxString operator(int i); - wxString operator(float f); - wxString operator(double d); + These functions work as C++ stream insertion operators. They insert the + given value into the string. Precision and format cannot be set using them. + Use Printf() instead. + */ + wxString& operator<<(const wxString& s); + wxString& operator<<(const char* psz); + wxString& operator<<(const wchar_t* pwz); + wxString& operator<<(const wxCStrData& psz); + wxString& operator<<(char ch); + wxString& operator<<(unsigned char ch); + wxString& operator<<(wchar_t ch); + wxString& operator<<(const wxCharBuffer& s); + wxString& operator<<(const wxWCharBuffer& s); + wxString& operator<<(wxUniCharRef ch); + wxString& operator<<(unsigned int ui); + wxString& operator<<(long l); + wxString& operator<<(unsigned long ul); + wxString& operator<<(wxLongLong_t ll); + wxString& operator<<(wxULongLong_t ul); + wxString& operator<<(float f); + wxString& operator<<(double d); //@} /** - Same as Mid (substring extraction). + Same as Mid() (substring extraction). */ - wxString operator ()(size_t start, size_t len); + wxString operator()(size_t start, size_t len) const; //@{ /** @@ -1118,7 +1142,7 @@ public: //@{ /** Assignment: the effect of each operation is the same as for the corresponding - constructor (see @ref construct() "wxString constructors"). + constructor (see wxString constructors). */ wxString operator =(const wxString& str); wxString operator =(wxUniChar c); @@ -1146,6 +1170,8 @@ public: 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. + + @see wc_str(), c_str(), mb_str() */ const char* utf8_str() const; const wxCharBuffer utf8_str() const; @@ -1154,13 +1180,14 @@ public: //@{ /** 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. + and returns it as a temporary wxWCharBuffer object (Unix and OS X) + or returns a pointer to the internal string contents in wide character + mode (Windows). The macro wxWX2WCbuf is defined as the correct return type (without const). - @see wxMBConv, c_str(), mb_str(), fn_str(), wchar_str() + @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str() */ const wchar_t* wc_str() const; const wxWCharBuffer wc_str() const; @@ -1177,6 +1204,13 @@ public: */ wxWritableWCharBuffer wchar_str() const; + /** + Explicit conversion to C string in the internal representation (either + wchar_t* or UTF-8-encoded char*, depending on the build). + */ + const wxStringCharType *wx_str() const; + + /** @name Iterator interface @@ -1202,14 +1236,6 @@ public: 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); @@ -1224,8 +1250,13 @@ public: wxString& assign(size_t n, wxUniChar ch); wxString& assign(const_iterator first, const_iterator last); + wxUniChar at(size_t n) const; + wxUniCharRef at(size_t n); + void clear(); + size_type capacity() const; + 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, @@ -1235,6 +1266,8 @@ public: int compare(size_t nStart, size_t nLen, const wchar_t* sz, size_t nCount = npos) const; + wxCStrData data() const; + bool empty() const; wxString& erase(size_type pos = 0, size_type n = npos); @@ -1245,6 +1278,28 @@ public: 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; + size_t find_first_of(const char* sz, size_t nStart = 0) const; + size_t find_first_of(const wchar_t* sz, size_t nStart = 0) const; + size_t find_first_of(const char* sz, size_t nStart, size_t n) const; + size_t find_first_of(const wchar_t* sz, size_t nStart, size_t n) const; + size_t find_first_of(wxUniChar c, size_t nStart = 0) const; + size_t find_last_of (const wxString& str, size_t nStart = npos) const; + size_t find_last_of (const char* sz, size_t nStart = npos) const; + size_t find_last_of (const wchar_t* sz, size_t nStart = npos) const; + size_t find_last_of(const char* sz, size_t nStart, size_t n) const; + size_t find_last_of(const wchar_t* sz, size_t nStart, size_t n) const; + size_t find_last_of(wxUniChar c, size_t nStart = npos) const; + size_t find_first_not_of(const wxString& str, size_t nStart = 0) const; + size_t find_first_not_of(const char* sz, size_t nStart = 0) const; + size_t find_first_not_of(const wchar_t* sz, size_t nStart = 0) const; + size_t find_first_not_of(const char* sz, size_t nStart, size_t n) const; + size_t find_first_not_of(const wchar_t* sz, size_t nStart, size_t n) const; + size_t find_first_not_of(wxUniChar ch, size_t nStart = 0) const; + size_t find_last_not_of(const wxString& str, size_t nStart = npos) const; + size_t find_last_not_of(const char* sz, size_t nStart = npos) const; + size_t find_last_not_of(const wchar_t* sz, size_t nStart = npos) const; + size_t find_last_not_of(const char* sz, size_t nStart, size_t n) const; + size_t find_last_not_of(const wchar_t* sz, size_t nStart, size_t n) const; wxString& insert(size_t nPos, const wxString& str); wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n); @@ -1255,103 +1310,148 @@ public: void insert(iterator it, const_iterator first, const_iterator last); void insert(iterator it, size_type n, wxUniChar ch); + size_t length() const; + + size_type max_size() const; + + void reserve(size_t sz); + void resize(size_t nSize, wxUniChar ch = '\0'); + 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); + const wxString& str, size_t nStart2, size_t nLen2); wxString& replace(size_t nStart, size_t nLen, - const char* sz, size_t nCount); + const char* sz, size_t nCount); wxString& replace(size_t nStart, size_t nLen, - const wchar_t* sz, size_t nCount); + const wchar_t* sz, size_t nCount); wxString& replace(size_t nStart, size_t nLen, - const wxString& s, size_t nCount); + 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); + const_iterator first1, const_iterator last1); wxString& replace(iterator first, iterator last, - const char *first1, const char *last1); + const char *first1, const char *last1); wxString& replace(iterator first, iterator last, - const wchar_t *first1, const wchar_t *last1); + 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; + size_type size() const; wxString substr(size_t nStart = 0, size_t nLen = npos) const; - void swap(wxString& str); - //@} - }; + +//@{ /** - FIXME + Comparison operator for string types. */ -wxString Objects: -; +inline bool operator==(const wxString& s1, const wxString& s2); +inline bool operator!=(const wxString& s1, const wxString& s2); +inline bool operator< (const wxString& s1, const wxString& s2); +inline bool operator> (const wxString& s1, const wxString& s2); +inline bool operator<=(const wxString& s1, const wxString& s2); +inline bool operator>=(const wxString& s1, const wxString& s2); +inline bool operator==(const wxString& s1, const wxCStrData& s2); +inline bool operator==(const wxCStrData& s1, const wxString& s2); +inline bool operator!=(const wxString& s1, const wxCStrData& s2); +inline bool operator!=(const wxCStrData& s1, const wxString& s2); +inline bool operator==(const wxString& s1, const wxWCharBuffer& s2); +inline bool operator==(const wxWCharBuffer& s1, const wxString& s2); +inline bool operator!=(const wxString& s1, const wxWCharBuffer& s2); +inline bool operator!=(const wxWCharBuffer& s1, const wxString& s2); +inline bool operator==(const wxString& s1, const wxCharBuffer& s2); +inline bool operator==(const wxCharBuffer& s1, const wxString& s2); +inline bool operator!=(const wxString& s1, const wxCharBuffer& s2); +inline bool operator!=(const wxCharBuffer& s1, const wxString& s2); +//@} + +//@{ +/** + Comparison operators char types. +*/ +inline bool operator==(const wxUniChar& c, const wxString& s); +inline bool operator==(const wxUniCharRef& c, const wxString& s); +inline bool operator==(char c, const wxString& s); +inline bool operator==(wchar_t c, const wxString& s); +inline bool operator==(int c, const wxString& s); +inline bool operator==(const wxString& s, const wxUniChar& c); +inline bool operator==(const wxString& s, const wxUniCharRef& c); +inline bool operator==(const wxString& s, char c); +inline bool operator==(const wxString& s, wchar_t c); +inline bool operator!=(const wxUniChar& c, const wxString& s); +inline bool operator!=(const wxUniCharRef& c, const wxString& s); +inline bool operator!=(char c, const wxString& s); +inline bool operator!=(wchar_t c, const wxString& s); +inline bool operator!=(int c, const wxString& s); +inline bool operator!=(const wxString& s, const wxUniChar& c); +inline bool operator!=(const wxString& s, const wxUniCharRef& c); +inline bool operator!=(const wxString& s, char c); +inline bool operator!=(const wxString& s, wchar_t c); +//@} /** - FIXME + The global wxString instance of an empty string. + Used extensively in the entire wxWidgets API. */ wxString wxEmptyString; - /** @class wxStringBufferLength - This tiny class allows to conveniently access the wxString - internal buffer as a writable pointer without any risk of forgetting to restore - the string to the usable state later, and allows the user to set the internal - length of the string. + This tiny class allows you to conveniently access the wxString internal buffer + as a writable pointer without any risk of forgetting to restore the string to + the usable state later, and allows the user to set the internal length of the string. For example, assuming you have a low-level OS function called - @c int GetMeaningOfLifeAsString(char *) copying the value in the provided + @c "int GetMeaningOfLifeAsString(char *)" copying the value in the provided buffer (which must be writable, of course), and returning the actual length of the string, you might call it like this: @code - wxString theAnswer; + wxString theAnswer; wxStringBuffer theAnswerBuffer(theAnswer, 1024); int nLength = GetMeaningOfLifeAsString(theAnswerBuffer); theAnswerBuffer.SetLength(nLength); if ( theAnswer != "42" ) - { wxLogError("Something is very wrong!"); - } @endcode - Note that the exact usage of this depends on whether on not wxUSE_STL is - enabled. If - wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer, - and - if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same - buffer - wxString uses intact. In other words, relying on wxStringBuffer containing the - old - wxString data is probably not a good idea if you want to build your program in - both - with and without wxUSE_STL. + @todo + the example above does not make use of wxStringBufferLength?? - Note that SetLength @c must be called before wxStringBufferLength destructs. + Note that the exact usage of this depends on whether or not wxUSE_STL is + enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty + character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from + wxString, keeping the same buffer wxString uses intact. In other words, + relying on wxStringBuffer containing the old wxString data is not a good + idea if you want to build your program both with and without wxUSE_STL. + + Note that wxStringBuffer::SetLength @b must be called before + wxStringBufferLength destructs. @library{wxbase} - @category{FIXME} + @category{data} */ class wxStringBufferLength { public: /** Constructs a writable string buffer object associated with the given string - and containing enough space for at least @a len characters. Basically, this - is equivalent to calling wxString::GetWriteBuf and + and containing enough space for at least @a len characters. + + Basically, this is equivalent to calling wxString::GetWriteBuf and saving the result. */ wxStringBufferLength(const wxString& str, size_t len); @@ -1365,6 +1465,7 @@ public: /** Sets the internal length of the string referred to by wxStringBufferLength to @a nLength characters. + Must be called before wxStringBufferLength destructs. */ void SetLength(size_t nLength); @@ -1376,3 +1477,81 @@ public: wxChar* operator wxChar *(); }; + +/** + @class wxStringBuffer + + This tiny class allows you to conveniently access the wxString internal buffer + as a writable pointer without any risk of forgetting to restore the string + to the usable state later. + + For example, assuming you have a low-level OS function called + @c "GetMeaningOfLifeAsString(char *)" returning the value in the provided + buffer (which must be writable, of course) you might call it like this: + + @code + wxString theAnswer; + GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024)); + if ( theAnswer != "42" ) + wxLogError("Something is very wrong!"); + @endcode + + Note that the exact usage of this depends on whether or not @c wxUSE_STL is + enabled. If @c wxUSE_STL is enabled, wxStringBuffer creates a separate empty + character buffer, and if @c wxUSE_STL is disabled, it uses GetWriteBuf() from + wxString, keeping the same buffer wxString uses intact. In other words, + relying on wxStringBuffer containing the old wxString data is not a good + idea if you want to build your program both with and without @c wxUSE_STL. + + @library{wxbase} + @category{data} +*/ +class wxStringBuffer +{ +public: + /** + Constructs a writable string buffer object associated with the given string + and containing enough space for at least @a len characters. + Basically, this is equivalent to calling wxString::GetWriteBuf() and + saving the result. + */ + wxStringBuffer(const wxString& str, size_t len); + + /** + Restores the string passed to the constructor to the usable state by calling + wxString::UngetWriteBuf() on it. + */ + ~wxStringBuffer(); + + /** + Returns the writable pointer to a buffer of the size at least equal to the + length specified in the constructor. + */ + wxStringCharType* operator wxStringCharType *(); +}; + + +/** @addtogroup group_funcmacro_string */ +//@{ + +/** + Allows to extend a function with the signature: + @code bool SomeFunc(const wxUniChar& c) @endcode + which operates on a single character, to an entire wxString. + + E.g. if you want to check if an entire string contains only digits, + you can do: + @code + if (wxStringCheck(myString)) + ... // the entire string contains oly digits! + else + ... // at least one character of myString is not a digit + @endcode + + @return @true if the given function returns a non-zero value for all + characters of the @a val string. +*/ +template + inline bool wxStringCheck(const wxString& val); + +//@}