X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/413eac73fd4e207a46f94821dd47feac3da7c287..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/string.h?ds=sidebyside diff --git a/interface/wx/string.h b/interface/wx/string.h index e04c1f7b51..93ff1cbee8 100644 --- a/interface/wx/string.h +++ b/interface/wx/string.h @@ -3,7 +3,7 @@ // Purpose: interface of wxStringBuffer, wxString // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -40,204 +40,24 @@ be sure to read also @ref overview_unicode. - @section string_construct Constructors and assignment operators + @section string_index Index of the member groups - 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() - - - @section string_len String length - - These functions return the string length and check whether the string - is empty or they empty it. - - @li length() - @li size() - @li Len() - @li IsEmpty() - @li operator!() - @li Empty() - @li Clear() - - - @section string_access Character access - - 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() + Links for quick access to the various categories of wxString functions: + - @ref_member_group{ctor, Constructors and assignment operators} + - @ref_member_group{length, Length functions} + - @ref_member_group{ch_access, Character access functions} + - @ref_member_group{conv, Conversions functions} + - @ref_member_group{concat, Concatenation functions} + - @ref_member_group{cmp, Comparison functions} + - @ref_member_group{substring, Substring extraction functions} + - @ref_member_group{caseconv, Case conversion functions} + - @ref_member_group{search, Searching and replacing functions} + - @ref_member_group{numconv, Conversion to numbers functions} + - @ref_member_group{fmt, Formatting and printing functions} + - @ref_member_group{mem, Memory management functions} + - @ref_member_group{misc, Miscellaneous functions} + - @ref_member_group{iter, Iterator interface functions} + - @ref_member_group{stl, STL interface functions} @library{wxbase} @@ -246,19 +66,17 @@ @stdobjects ::wxEmptyString - @see @ref overview_string, @ref overview_unicode, wxUString, - wxCharBuffer, wxUniChar, wxStringTokenizer, @ref group_funcmacro_string + @see @ref overview_string, @ref overview_unicode, + @ref group_funcmacro_string "String-related functions", wxUString, + wxCharBuffer, wxUniChar, wxStringTokenizer, wxStringBuffer, wxStringBufferLength */ class wxString { public: - /** - An 'invalid' value for string index - */ - static const size_t npos; - /** @name Standard types + + Types used with wxString. */ //@{ typedef wxUniChar value_type; @@ -270,6 +88,19 @@ public: typedef wxUniChar const_reference; //@} + + /** + @member_group_name{ctor, 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. + + See also the assign() STL-like function. + */ + //@{ + /** Default constructor */ @@ -277,68 +108,91 @@ public: /** Creates a string from another string. - Just increases the ref count by 1. + Just increases the ref count by 1. */ wxString(const wxString& stringSrc); + /** + Construct a string consisting of @a nRepeat copies of ch. + */ + wxString(wxUniChar ch, size_t nRepeat = 1); + + /** + Construct a string consisting of @a nRepeat copies of ch. + */ + wxString(wxUniCharRef ch, size_t nRepeat = 1); + + /** + Construct a string consisting of @a nRepeat copies of ch + converted to Unicode using the current locale encoding. + */ + wxString(char ch, size_t nRepeat = 1); + + /** + Construct a string consisting of @a nRepeat copies of ch. + */ + wxString(wchar_t ch, size_t nRepeat = 1); /** - Constructs a string from the string literal @e psz using + Constructs a string from the string literal @a 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. + Constructs a string from the string literal @a psz using + @a 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 + Constructs a string from the first @a nLength character of the string literal @a 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. + Constructs a string from the first @a nLength character of the string literal @a psz using + @a conv to convert it Unicode. */ wxString(const char *psz, const wxMBConv& conv, size_t nLength); /** - Constructs a string from the string literal @e pwz. + Constructs a string from the string literal @a pwz. */ wxString(const wchar_t *pwz); /** - Constructs a string from the first @e nLength characters of the string literal @e pwz. + Constructs a string from the first @a nLength characters of the string literal @a pwz. */ wxString(const wchar_t *pwz, size_t nLength); /** - Constructs a string from @e buf using the using the current locale + Constructs a string from @a buf using the using the current locale encoding to convert it to Unicode. */ wxString(const wxCharBuffer& buf); /** - Constructs a string from @e buf. + Constructs a string from @a buf. */ wxString(const wxWCharBuffer& buf); /** - Constructs a string from @e str using the using the current locale encoding + Constructs a string from @a str using the using the current locale encoding to convert it to Unicode (wxConvLibc). + + @see ToStdString() */ wxString(const std::string& str); /** - Constructs a string from @e str. + Constructs a string from @a str. + + @see ToStdWstring() */ wxString(const std::wstring& str); - /** String destructor. @@ -347,446 +201,908 @@ public: ~wxString(); /** - Gets all the characters after the first occurrence of @e ch. - Returns the empty string if @e ch is not found. + Assignment: see the relative wxString constructor. */ - wxString AfterFirst(wxUniChar ch) const; + wxString operator =(const wxString& str); /** - Gets all the characters after the last occurrence of @e ch. - Returns the whole string if @e ch is not found. + Assignment: see the relative wxString constructor. */ - wxString AfterLast(wxUniChar ch) const; - - /** - 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. + wxString operator =(wxUniChar c); - 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); + /** + @member_group_name{length, String length} - for ( size_t n = 0; n < len; n++ ) - { - if ( strchr("aeuio", tolower(original[n])) == NULL ) - result += original[n]; - } + These functions return the string length and/or check whether the string + is empty. - return result; - } - @endcode + See also the length(), size() or empty() STL-like functions. + */ + //@{ - 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. + /** + Returns the length of the string. */ - bool Alloc(size_t nLen); + size_t Len() const; /** - Appends the string literal @e psz. + 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. */ - wxString& Append(const char* psz); + size_t Length() const; /** - Appends the wide string literal @e pwz. + Returns @true if the string is empty. */ - wxString& Append(const wchar_t* pwz); + bool IsEmpty() const; /** - Appends the string literal @e psz with max length @e nLen. + 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. */ - wxString& Append(const char* psz, size_t nLen); + bool IsNull() const; /** - Appends the wide string literal @e psz with max length @e nLen. + Empty string is @false, so !string will only return @true if the + string is empty. + + @see IsEmpty(). */ - wxString& Append(const wchar_t* pwz, size_t nLen); + bool operator!() const; + + //@} + + /** - Appends the string @e s. + @member_group_name{ch_access, Character access} + + 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. */ - wxString& Append(const wxString& s); + //@{ /** - Appends the character @e ch @e count times. + Returns the character at position @a n (read-only). */ - wxString &Append(wxUniChar ch, size_t count = 1u); + wxUniChar GetChar(size_t n) const; /** - Gets all characters before the first occurrence of @e ch. - Returns the whole string if @a ch is not found. + wxWidgets compatibility conversion. Same as c_str(). */ - wxString BeforeFirst(wxUniChar ch) const; + const wxCStrData GetData() const; /** - Gets all characters before the last occurrence of @e ch. - Returns the empty string if @a ch is not found. + Returns a reference to the character at position @a n. */ - wxString BeforeLast(wxUniChar ch) const; + wxUniCharRef GetWritableChar(size_t n); /** - 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 + Returns a writable buffer of at least @a len bytes. - @see MakeCapitalized() - */ - wxString Capitalize() const; + 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. - /** - Empties the string and frees memory occupied by it. - See also: Empty() + This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead. */ - void Clear(); + wxStringCharType* GetWriteBuf(size_t len); /** - 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; + Puts the string back into a reasonable state (in which it can be used + normally), after GetWriteBuf() was called. - /** - 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 @c strcmp() function). + 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). - See also CmpNoCase(), IsSameAs(). + This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead. */ - int Cmp(const wxString& s) const; + void UngetWriteBuf(); /** - 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 @c strcmp() function). - - See also Cmp(), IsSameAs(). + @overload */ - int CmpNoCase(const wxString& s) const; + void UngetWriteBuf(size_t len); /** - 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. + Sets the character at position @e n. */ - bool Contains(const wxString& str) const; - + void SetChar(size_t n, wxUniChar ch); /** - Makes the string empty, but doesn't free memory occupied by the string. - See also: Clear(). - */ - void Empty(); + Returns the last character. - /** - 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 @e rest string if it is not - @NULL. Otherwise, the function returns @false and doesn't - modify the @e rest. + This is a wxWidgets 1.xx compatibility function; + you should not use it in new code. */ - bool EndsWith(const wxString& suffix, wxString *rest = NULL) const; + wxUniChar Last() const; /** - Searches for the given character @e ch. Returns the position or - @c wxNOT_FOUND if not found. + Returns a reference to the last character (writable). + + This is a wxWidgets 1.xx compatibility function; + you should not use it in new code. */ - int Find(wxUniChar ch, bool fromEnd = false) const; + wxUniCharRef Last(); /** - Searches for the given string @e sub. Returns the starting position or - @c wxNOT_FOUND if not found. + Returns the @a i-th character of the string. */ - int Find(const wxString& sub) const; + wxUniChar operator [](size_t i) const; - //@{ /** - Same as Find(). - This is a wxWidgets 1.xx compatibility function; - you should not use it in new code. + Returns a writable reference to the @a i-th character of the string. */ - int First(wxUniChar ch) const; - int First(const wxString& str) const; + wxUniCharRef operator [](size_t i); + //@} + /** - This static function returns the string containing the result of calling - Printf() with the passed parameters on it. + @member_group_name{conv, Conversions} - @see FormatV(), Printf() + This section 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. */ - static wxString Format(const wxString& format, ...); + //@{ /** - This static function returns the string containing the result of calling - PrintfV() with the passed parameters on it. + Returns a lightweight intermediate class which is in turn implicitly + convertible to both @c const @c char* and to @c const @c wchar_t*. + Given this ambiguity it is mostly better to use wc_str(), mb_str() or + utf8_str() instead. - @see Format(), PrintfV() - */ - static wxString FormatV(const wxString& format, va_list argptr); + 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() + */ + wxCStrData c_str() const; /** - 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. + 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 c_str() */ - int Freq(wxUniChar ch) const; + wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) 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 @e len parameter takes NUL-terminated - data. + 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 a string representation suitable for passing to OS' functions + for file handling. + */ + const wchar_t* fn_str() const; + + /** + @overload + */ + const char* fn_str() const; + + /** + @overload + */ + const wxCharBuffer fn_str() const; + + /** + Returns the multibyte (C string) representation of the string + using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer. + + @see wc_str(), utf8_str(), c_str(), wxMBConv + */ + const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) 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. + + @see wc_str(), c_str(), mb_str() + */ + const wxScopedCharBuffer utf8_str() const; + + /** + Converts the strings contents to the wide character representation + 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 utf8_str(), c_str(), mb_str(), fn_str(), wchar_str() + */ + const wchar_t* wc_str() const; + + /** + @overload + */ + const wxWCharBuffer wc_str() const; + + /** + Returns an object with string data that is implicitly convertible to + @c char* pointer. Note that changes to the returned buffer may or may + 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 mb_str(), wc_str(), fn_str(), c_str(), char_str() + */ + 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; + + /** + 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 that purpose and only in - conjunction with To8BitData(). Use mb_str() for conversion of character - data to known encoding. + wxString. It should be used @em only for this purpose. It is only valid + to call this method on strings created using From8BitData(). @since 2.8.4 - @see wxString::To8BitData() + @see wxString::From8BitData() */ - static wxString From8BitData(const char* buf, size_t len); - static wxString From8BitData(const char* buf); - //@} + const wxScopedCharBuffer To8BitData() const; - //@{ /** - Converts the string or character from an ASCII, 7-bit form - to the native wxString representation. + 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 mb_str() "mb_str" method provides more + powerful means of converting wxString to C string. */ - static wxString FromAscii(const char* s); - static wxString FromAscii(const unsigned char* s); - static wxString FromAscii(const char* s, size_t len); - static wxString FromAscii(const unsigned char* s, size_t len); - static wxString FromAscii(char c); + const char* ToAscii() const; + + /** + @overload + */ + const wxCharBuffer ToAscii() const; + + /** + Return the string as an std::string in current locale encoding. + + Note that if the conversion of (Unicode) string contents to the current + locale fails, the return string will be empty. Be sure to check for + this to avoid silent data loss. + + Instead of using this function it's also possible to write + @code + std::string s; + wxString wxs; + ... + s = std::string(wxs); + @endcode + but using ToStdString() may make the code more clear. + + @since 2.9.1 + */ + std::string ToStdString() const; + + /** + Return the string as an std::wstring. + + Unlike ToStdString(), there is no danger of data loss when using this + function. + + @since 2.9.1 + */ + std::wstring ToStdWstring() const; + + /** + Same as utf8_str(). + */ + const wxScopedCharBuffer ToUTF8() const; + //@} + + /** + @member_group_name{concat, Concatenation} + + Almost anything may be concatenated (appended to) with a string! + + Note that the various operator<<() overloads 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. + + See also the insert() and append() STL-like functions. + */ //@{ + /** - Converts C string encoded in UTF-8 to wxString. + Appends the string literal @a psz. + */ + wxString& Append(const char* psz); - If @a s is not a valid UTF-8 string, an empty string is returned. + /** + Appends the wide string literal @a pwz. + */ + wxString& Append(const wchar_t* pwz); - 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. + /** + Appends the string literal @a psz with max length @a nLen. + */ + wxString& Append(const char* psz, size_t nLen); - @since 2.8.4 + /** + Appends the wide string literal @a psz with max length @a nLen. */ - static wxString FromUTF8(const char* s); - static wxString FromUTF8(const char* s, size_t len); + wxString& Append(const wchar_t* pwz, size_t nLen); + + /** + Appends the string @a s. + */ + wxString& Append(const wxString& s); + + /** + Appends the character @a ch @a count times. + */ + wxString &Append(wxUniChar ch, size_t count = 1u); + + /** + Prepends @a str to this string, returning a reference to this string. + */ + wxString& Prepend(const wxString& str); + + /** + Concatenation: returns a new string equal to the concatenation of the operands. + */ + wxString operator +(const wxString& x, const wxString& y); + + /** + @overload + */ + wxString operator +(const wxString& x, wxUniChar y); + + 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<<(wxUniChar ch); + 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); + + /** + Concatenation in place: the argument is appended to the string. + */ + void operator +=(const wxString& str); + + /** + @overload + */ + void operator +=(wxUniChar c); + //@} + + /** + @member_group_name{cmp, 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. + + See also the compare() STL-like function. + */ //@{ + /** - Converts C string encoded in UTF-8 to wxString without checking its - validity. + 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 @c strcmp() function). - 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. + @see CmpNoCase(), IsSameAs(). + */ + int Cmp(const wxString& s) const; - @since 2.8.9 + /** + 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 @c strcmp() function). + + @see Cmp(), IsSameAs(). */ - static wxString FromUTF8Unchecked(const char* s); - static wxString FromUTF8Unchecked(const char* s, size_t len); + int CmpNoCase(const wxString& s) const; + + /** + Test whether the string is equal to another string @a s. + + The test is case-sensitive if @a caseSensitive is @true (default) or not if it is + @false. + + @return @true if the string is equal to the other one, @false otherwise. + + @see Cmp(), CmpNoCase() + */ + bool IsSameAs(const wxString& s, bool caseSensitive = true) const; + + /** + Test whether the string is equal to the single character @a ch. + + The test is case-sensitive if @a caseSensitive is @true (default) or not if it is + @false. + + @return @true if the string is equal to this character, @false otherwise. + + @see Cmp(), CmpNoCase() + */ + bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const; + + /** + Returns @true if the string contents matches a mask containing '*' and '?'. + */ + bool Matches(const wxString& mask) const; + + /** + This function can be used to test if the string starts with the specified + @a prefix. + + If it does, the function will return @true and put the rest of the string + (i.e. after the prefix) into @a rest string if it is not @NULL. + Otherwise, the function returns @false and doesn't modify the @a rest. + */ + bool StartsWith(const wxString& prefix, wxString *rest = NULL) const; + + /** + 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 @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) const; + //@} + /** - Returns the character at position @a n (read-only). + @member_group_name{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. + + See also the at() and the substr() STL-like functions. */ - wxUniChar GetChar(size_t n) const; /** - wxWidgets compatibility conversion. Same as c_str(). + Returns a substring starting at @e first, with length @e count, or the rest of + the string if @a count is the default value. */ - const wxCStrData GetData() const; + wxString Mid(size_t first, size_t nCount = wxString::npos) const; /** - Returns a reference to the character at position @e n. + Returns the part of the string between the indices @a from and @a to + inclusive. + + This is a wxWidgets 1.xx compatibility function, use Mid() + instead (but note that parameters have different meaning). */ - wxUniCharRef GetWritableChar(size_t n); + wxString SubString(size_t from, size_t to) const; /** - 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 - wxStringBufferLength instead. + Same as Mid() (substring extraction). */ - wxStringCharType* GetWriteBuf(size_t len); + wxString operator()(size_t start, size_t len) const; /** - Returns @true if the string contains only ASCII characters. - See wxUniChar::IsAscii for more details. + Returns the first @a count characters of the string. + */ + wxString Left(size_t count) const; - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + /** + Returns the last @a count characters. */ - bool IsAscii() const; + wxString Right(size_t count) const; /** - Returns @true if the string is empty. + Gets all the characters after the first occurrence of @e ch. + Returns the empty string if @e ch is not found. */ - bool IsEmpty() const; + wxString AfterFirst(wxUniChar ch) const; /** - Returns @true if the string is empty (same as wxString::IsEmpty). + Gets all the characters after the last occurrence of @e ch. + Returns the whole string if @e ch is not found. + */ + wxString AfterLast(wxUniChar ch) const; + + /** + Gets all characters before the first occurrence of @e ch. + Returns the whole string if @a ch is not found. + + @param ch The character to look for. + @param rest Filled with the part of the string following the first + occurrence of @a ch or cleared if it was not found. The same string + is returned by AfterFirst() but it is more efficient to use this + output parameter if both the "before" and "after" parts are needed + than calling both functions one after the other. This parameter is + available in wxWidgets version 2.9.2 and later only. + @return Part of the string before the first occurrence of @a ch. + */ + wxString BeforeFirst(wxUniChar ch, wxString *rest = NULL) const; + + /** + Gets all characters before the last occurrence of @e ch. + Returns the empty string if @a ch is not found. + + @param ch The character to look for. + @param rest Filled with the part of the string following the last + occurrence of @a ch or the copy of this string if it was not found. + The same string is returned by AfterLast() but it is more efficient + to use this output parameter if both the "before" and "after" parts + are needed than calling both functions one after the other. This + parameter is available in wxWidgets version 2.9.2 and later only. + @return Part of the string before the last occurrence of @a ch. + */ + wxString BeforeLast(wxUniChar ch, wxString *rest = NULL) const; + + //@} + + + /** + @member_group_name{caseconv, 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. + */ + //@{ + + /** + 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; + + /** + Returns this string converted to the lower case. + + @see MakeLower() + */ + wxString Lower() const; + + /** + Same as MakeLower. This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool IsNull() const; + void LowerCase(); /** - Returns @true if the string is an integer (with possible sign). + 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 reference to the + modified string. + + @see Upper() + */ + wxString& MakeUpper(); + + /** + Returns this string converted to upper case. + + @see MakeUpper() + */ + wxString Upper() const; + + /** + The same as MakeUpper(). + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool IsNumber() const; + void UpperCase(); + + //@} + + + /** + @member_group_name{search, Searching and replacing} + + These functions replace the standard @c strchr() and @c strstr() + functions. + See also the find(), rfind(), replace() STL-like functions. + */ //@{ + + /** + Searches for the given character @a ch. + Returns the position or @c wxNOT_FOUND if not found. + */ + int Find(wxUniChar ch, bool fromEnd = false) const; + /** - Test whether the string is equal to the single character @e c. The test is - case-sensitive if @a caseSensitive is @true (default) or not if it is @c - @false. - Returns @true if the string is equal to the character, @false otherwise. - See also Cmp(), CmpNoCase() + Searches for the given string @a sub. + Returns the starting position or @c wxNOT_FOUND if not found. */ - bool IsSameAs(const wxString &s, bool caseSensitive = true) const; - bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const; - //@} + int Find(const wxString& sub) const; /** - Returns @true if the string is a word. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + Same as Find(). + + This is a wxWidgets 1.xx compatibility function; + you should not use it in new code. */ - bool IsWord() const; + int First(wxUniChar ch) const; - //@{ /** - Returns a reference to the last character (writable). + Same as Find(). + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - wxUniCharRef Last(); - const wxUniChar Last(); - //@} + int First(const wxString& str) const; /** - Returns the first @a count characters of the string. + Replace first (or all) occurrences of substring with another one. + + @param strOld + The string to search for replacing. + @param strNew + The substitution string. + @param replaceAll + If @true a global replace will be done (default), otherwise only the + first occurrence will be replaced. + + Returns the number of replacements made. */ - wxString Left(size_t count) const; + size_t Replace(const wxString& strOld, const wxString& strNew, + bool replaceAll = true); + + //@} + + /** - Returns the length of the string. - */ - size_t Len() const; + @member_group_name{numconv, 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. Notice if there is a valid number in the beginning of the + string, it is returned in the output parameter even if the function + returns @false because there is more text following it. + */ + //@{ /** - 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. + Attempts to convert the string to a floating point number. + + Returns @true on success (the number is stored in the location pointed to by + @a val) or @false if the string does not represent such number (the value of + @a val may still be modified in this case). + + Note that unlike ToCDouble() this function uses a localized version of + @c wxStrtod() and thus needs as decimal point (and thousands separator) the + locale-specific decimal point. Thus you should use this function only when + you are sure that this string contains a floating point number formatted with + the rules of the locale currently in use (see wxLocale). + + Also notice that even this function is locale-specific it does not + support strings with thousands separators in them, even if the current + locale uses digits grouping. You may use wxNumberFormatter::FromString() + to parse such strings. + + Please refer to the documentation of the standard function @c strtod() + for more details about the supported syntax. + + @see ToCDouble(), ToLong(), ToULong() */ - size_t Length() const; + bool ToDouble(double* val) const; /** - Returns this string converted to the lower case. + Variant of ToDouble() always working in "C" locale. - @see MakeLower() + Works like ToDouble() but unlike it this function expects the floating point + number to be formatted always with the rules dictated by the "C" locale + (in particular, the decimal point must be a dot), independently from the + current application-wide locale (see wxLocale). + + @see ToDouble(), ToLong(), ToULong() */ - wxString Lower() const; + bool ToCDouble(double* val) const; /** - Same as MakeLower. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + Attempts to convert the string to a signed integer in base @a 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 may still be + modified in this case). + + The value of @a base must be comprised between 2 and 36, inclusive, or + be a special value 0 which means that the usual rules of @c C numbers are + applied: if the number starts with @c 0x it is considered to be in base + 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note + 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. + + Note that unlike ToCLong() this function uses a localized version of + @c wxStrtol(). Thus you should use this function only when you are sure + that this string contains an integer number formatted with + the rules of the locale currently in use (see wxLocale). + + As with ToDouble(), this function does not support strings containing + thousands separators even if the current locale uses digits grouping. + You may use wxNumberFormatter::FromString() to parse such strings. + + Please refer to the documentation of the standard function @c strtol() + for more details about the supported syntax. + + @see ToCDouble(), ToDouble(), ToULong() */ - void LowerCase(); + bool ToLong(long* val, int base = 10) const; /** - Converts the first characters of the string to the upper case and all - the subsequent ones to the lower case and returns the result. + Variant of ToLong() always working in "C" locale. - @since 2.9.0 + Works like ToLong() but unlike it this function expects the integer + number to be formatted always with the rules dictated by the "C" locale, + independently from the current application-wide locale (see wxLocale). - @see Capitalize() + @see ToDouble(), ToLong(), ToULong() */ - wxString& MakeCapitalized(); + bool ToCLong(long* val, int base = 10) const; /** - Converts all characters to lower case and returns the reference to the - modified string. + This is exactly the same as ToLong() but works with 64 bit integer numbers. - @see Lower() + 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() */ - wxString& MakeLower(); + bool ToLongLong(wxLongLong_t* val, int base = 10) const; /** - Converts all characters to upper case and returns the reference to the - modified string. + Attempts to convert the string to an unsigned integer in base @a base. - @see Upper() + 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 may + still be 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 + (and of the locale-specific behaviour of this function). + + @see ToCULong(), ToDouble(), ToLong() */ - wxString& MakeUpper(); + bool ToULong(unsigned long* val, int base = 10) const; /** - Returns @true if the string contents matches a mask containing '*' and '?'. + Variant of ToULong() always working in "C" locale. + + Works like ToULong() but unlike it this function expects the integer + number to be formatted always with the rules dictated by the "C" locale, + independently from the current application-wide locale (see wxLocale). + + @see ToDouble(), ToLong(), ToULong() */ - bool Matches(const wxString& mask) const; + bool ToCULong(unsigned long* val, int base = 10) 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. + This is exactly the same as ToULong() but works with 64 bit integer + numbers. + + Please see ToLongLong() for additional remarks. */ - wxString Mid(size_t first, size_t nCount = wxString::npos) const; + bool ToULongLong(wxULongLong_t* val, int base = 10) 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 chPad = ' ', bool fromRight = true); + @member_group_name{fmt, Formatting and printing} - /** - Prepends @a str to this string, returning a reference to this string. + Both formatted versions (Printf/() and stream-like insertion operators + exist (for basic types only). + + See also the static Format() and FormatV() functions. */ - wxString& Prepend(const wxString& str); + //@{ /** Similar to the standard function @e sprintf(). Returns the number of @@ -794,6 +1110,16 @@ public: Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports Unix98-style positional parameters: + @code + wxString str; + + str.Printf(wxT("%d %d %d"), 1, 2, 3); + // str now contains "1 2 3" + + str.Printf(wxT("%2$d %3$d %1$d"), 1, 2, 3); + // str now contains "2 3 1" + @endcode + @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 @@ -808,38 +1134,59 @@ public: */ int PrintfV(const wxString& pszFormat, va_list argPtr); - //@{ - /** - Removes @a len characters from the string, starting at @e pos. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. - */ - wxString Remove(size_t pos); - wxString Remove(size_t pos, size_t len); //@} - /** - Removes the last character. - */ - wxString& RemoveLast(size_t n = 1); /** - Replace first (or all) occurrences of substring with another one. - @e replaceAll: global replace (default), or only the first occurrence. - Returns the number of replacements made. - */ - size_t Replace(const wxString& strOld, const wxString& strNew, - bool replaceAll = true); + @member_group_name{mem, Memory management} - /** - Returns the last @a count characters. + 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. + + See also the reserve() and resize() STL-like functions. */ - wxString Right(size_t count) const; + //@{ /** - Sets the character at position @e n. + 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 SetChar(size_t n, wxUniChar ch); + bool Alloc(size_t nLen); /** Minimizes the string's memory. This can be useful after a call to @@ -848,129 +1195,117 @@ public: bool Shrink(); /** - This function can be used to test if the string starts with the specified - @e prefix. If it does, the function will return @true and put the rest - of the string (i.e. after the prefix) into @a rest string if it is not - @NULL. Otherwise, the function returns @false and doesn't modify the - @e rest. - */ - bool StartsWith(const wxString& prefix, wxString *rest = NULL) const; + 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; /** - Strip characters at the front and/or end. The same as Trim except that it - doesn't change this string. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + Empties the string and frees memory occupied by it. + + @see Empty() */ - wxString Strip(stripType s = trailing) const; + void Clear(); + + //@} + + /** - Returns the part of the string between the indices @a from and @e to - inclusive. - 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) const; + @member_group_name{misc, Miscellaneous} + Miscellaneous other string functions. + */ //@{ + /** - Converts the string to an 8-bit string in ISO-8859-1 encoding in the - form of a wxCharBuffer (Unicode builds only). + Returns @true if target appears anywhere in wxString; else @false. - 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(). + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. + */ + bool Contains(const wxString& str) const; - @since 2.8.4 + /** + Makes the string empty, but doesn't free memory occupied by the string. - @see wxString::From8BitData() + @see Clear(). */ - const char* To8BitData() const; - const wxCharBuffer To8BitData() const; - //@} + void Empty(); - //@{ /** - 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 mb_str() "mb_str" method provides more - powerful means of converting wxString to C string. + 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. */ - const char* ToAscii() const; - const wxCharBuffer ToAscii() const; - //@} + int Freq(wxUniChar ch) const; /** - Attempts to convert the string to a floating point number. Returns @true on - 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). + Returns @true if the string contains only ASCII characters. + See wxUniChar::IsAscii for more details. - @see ToLong(), ToULong() + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. */ - bool ToDouble(double* val) const; + bool IsAscii() const; /** - Attempts to convert the string to a signed 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). - The value of @a base must be comprised between 2 and 36, inclusive, or - be a special value 0 which means that the usual rules of @c C numbers are - applied: if the number starts with @c 0x it is considered to be in base - 16, if it starts with @c 0 - in base 8 and in base 10 otherwise. Note - 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. + Returns @true if the string is an integer (with possible sign). - @see ToDouble(), ToULong() + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool ToLong(long* val, int base = 10) const; + bool IsNumber() const; /** - This is exactly the same as ToLong() but works with 64 - bit integer numbers. - 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. + Returns @true if the string is a word. - @see ToLong(), ToULongLong() + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool ToLongLong(wxLongLong_t* val, int base = 10) const; + bool IsWord() 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). + Adds @a count copies of @a chPad to the beginning, or to the end of the + string (the default). - 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). + Removes spaces from the left or from the right (default). + */ + wxString& Pad(size_t count, wxUniChar chPad = ' ', bool fromRight = true); - See ToLong() for the more detailed description of the @a base parameter. + /** + Removes all characters from the string starting at @a pos. + Use Truncate() as a more readable alternative. - @see ToDouble(), ToLong() + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool ToULong(unsigned long* val, int base = 10) const; + wxString& Remove(size_t pos); /** - This is exactly the same as ToULong() but works with 64 - bit integer numbers. - Please see ToLongLong() for additional remarks. + Removes @a len characters from the string, starting at @a pos. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - bool ToULongLong(wxULongLong_t* val, int base = 10) const; + wxString& Remove(size_t pos, size_t len); - //@{ /** - Same as utf8_str(). + Removes the last character. */ - const char* ToUTF8() const; - const wxCharBuffer ToUTF8() const; - //@} + wxString& RemoveLast(size_t n = 1); + + /** + Strip characters at the front and/or end. + + This is the same as Trim() except that it doesn't change this string. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. + */ + wxString Strip(stripType s = trailing) const; /** Removes white-space (space, tabs, form feed, newline and carriage return) from @@ -983,376 +1318,297 @@ public: */ wxString& Truncate(size_t len); - //@{ - /** - Puts the string back into a reasonable state (in which it can be used - 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 - wxStringBufferLength instead. - */ - void UngetWriteBuf(); - void UngetWriteBuf(size_t len); //@} - /** - Returns this string converted to upper case. - @see MakeUpper() - */ - wxString Upper() const; + /** - The same as MakeUpper(). + @member_group_name{iter, Iterator interface} - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + These methods return iterators to the beginning or end of the string. + + Please see any STL reference (e.g. http://www.cppreference.com/wiki/string/start) + for their documentation. */ - void UpperCase(); + //@{ - /** - Returns a lightweight intermediate class which is in turn implicitly - convertible to both @c const @c char* and to @c const @c wchar_t*. - Given this ambiguity it is mostly better to use wc_str(), mb_str() or - utf8_str() instead. + const_iterator begin() const; + iterator begin(); + const_iterator end() const; + iterator end(); - Please see the @ref overview_unicode for more information about it. + const_reverse_iterator rbegin() const; + reverse_iterator rbegin(); + const_reverse_iterator rend() const; + reverse_iterator rend(); + + //@} - 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() - */ - 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. + @member_group_name{stl, STL interface} - @see c_str() + The supported STL functions are listed here. + + Please see any STL reference (e.g. http://www.cppreference.com/wiki/string/start) + for their documentation. */ - wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const; + //@{ - /** - Returns buffer of the specified type containing the string data. + 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); + + 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, + 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; + + wxCStrData data() 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; + 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); + 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); + + 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); + 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; + + size_type size() const; + wxString substr(size_t nStart = 0, size_t nLen = npos) const; + void swap(wxString& str); - 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; + // STATIC FUNCTIONS + // Keep these functions separated from the other groups or Doxygen gets confused + // ----------------------------------------------------------------------------- - //@{ /** - Returns string representation suitable for passing to OS' functions - for file handling. + An 'invalid' value for string index */ - const wchar_t* fn_str() const; - const char* fn_str() const; - const wxCharBuffer fn_str() const; - //@} + static const size_t npos; /** - Returns the multibyte (C string) representation of the string - using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer. + This static function returns the string containing the result of calling + Printf() with the passed parameters on it. - @see wc_str(), utf8_str(), c_str(), wxMBConv + @see FormatV(), Printf() */ - const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const; + static wxString Format(const wxString& format, ...); /** - Extraction from a stream. + This static function returns the string containing the result of calling + PrintfV() with the passed parameters on it. + + @see Format(), PrintfV() */ - friend istream operator>>(istream& is, wxString& str); + static wxString FormatV(const wxString& format, va_list argptr); //@{ /** - 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); - //@} + 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. - /** - Same as Mid() (substring extraction). - */ - wxString operator()(size_t start, size_t len) const; + 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. - //@{ - /** - 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, wxUniChar y); - //@} + @since 2.8.4 - //@{ - /** - Concatenation in place: the argument is appended to the string. + @see wxString::To8BitData() */ - void operator +=(const wxString& str); - void operator +=(wxUniChar c); + static wxString From8BitData(const char* buf, size_t len); + static wxString From8BitData(const char* buf); //@} //@{ /** - Assignment: the effect of each operation is the same as for the corresponding - constructor (see wxString constructors). + Converts the string or character from an ASCII, 7-bit form + to the native wxString representation. */ - wxString operator =(const wxString& str); - wxString operator =(wxUniChar c); + static wxString FromAscii(const char* s); + static wxString FromAscii(const unsigned char* s); + static wxString FromAscii(const char* s, size_t len); + static wxString FromAscii(const unsigned char* s, size_t len); + static wxString FromAscii(char c); //@} - //@{ /** - Element extraction. - */ - wxUniChar operator [](size_t i) const; - wxUniCharRef operator [](size_t i); - //@} + Returns a string with the textual representation of the number in C + locale. - /** - Empty string is @false, so !string will only return @true if the - string is empty. + Unlike FromDouble() the string returned by this function always uses + the period character as decimal separator, independently of the current + locale. Otherwise its behaviour is identical to the other function. - See also IsEmpty(). - */ - bool operator!() const; + @since 2.9.1 + @see ToCDouble() + */ + static wxString FromCDouble(double val, int precision = -1); - //@{ /** - 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; - //@} + Returns a string with the textual representation of the number. - //@{ - /** - Converts the strings contents to the wide character represention - 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). + For the default value of @a precision, this function behaves as a + simple wrapper for @code wxString::Format("%g", val) @endcode. If @a + precision is positive (or zero), the @c %.Nf format is used with the + given precision value. - The macro wxWX2WCbuf is defined as the correct return - type (without const). + Notice that the string returned by this function uses the decimal + separator appropriate for the current locale, e.g. @c "," and not a + period in French locale. Use FromCDouble() if this is unwanted. - @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str() - */ - const wchar_t* wc_str() const; - const wxWCharBuffer wc_str() const; - //@} + @param val + The value to format. + @param precision + The number of fractional digits to use in or -1 to use the most + appropriate format. This parameter is new in wxWidgets 2.9.2. - /** - Returns an object with string data that is implicitly convertible to - @c char* pointer. Note that changes to the returned buffer may or may - 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. + @since 2.9.1 - @see mb_str(), wc_str(), fn_str(), c_str(), char_str() - */ - wxWritableWCharBuffer wchar_str() const; + @see ToDouble() + */ + static wxString FromDouble(double val, int precision = -1); + //@{ /** - 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; + Converts C string encoded in UTF-8 to wxString. + If @a s is not a valid UTF-8 string, an empty string is returned. - /** - @name Iterator interface + 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. - These methods return iterators to the beginnnig or - end of the string. + @since 2.8.4 */ - //@{ - 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(); + static wxString FromUTF8(const char* s); + static wxString FromUTF8(const char* s, size_t len); //@} + //@{ /** - @name STL interface + 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. - The supported STL functions are listed here. Please see any - STL reference for their documentation. + @since 2.8.9 */ - //@{ - 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); - - 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, - 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; - - wxCStrData data() 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; - 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); - 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); - - 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); - 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; - - size_type size() const; - wxString substr(size_t nStart = 0, size_t nLen = npos) const; - void swap(wxString& str); + static wxString FromUTF8Unchecked(const char* s); + static wxString FromUTF8Unchecked(const char* s, size_t len); //@} }; -/** @addtogroup group_string_operators */ + + //@{ /** - Comparison operators for wxString. + Comparison operator for string types. */ inline bool operator==(const wxString& s1, const wxString& s2); inline bool operator!=(const wxString& s1, const wxString& s2); @@ -1372,9 +1628,11 @@ 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 with wxUniChar or wxUniCharRef. + Comparison operators char types. */ inline bool operator==(const wxUniChar& c, const wxString& s); inline bool operator==(const wxUniCharRef& c, const wxString& s); @@ -1404,7 +1662,6 @@ wxString wxEmptyString; - /** @class wxStringBufferLength @@ -1419,16 +1676,13 @@ wxString wxEmptyString; @code wxString theAnswer; - wxStringBuffer theAnswerBuffer(theAnswer, 1024); + wxStringBufferLength theAnswerBuffer(theAnswer, 1024); int nLength = GetMeaningOfLifeAsString(theAnswerBuffer); theAnswerBuffer.SetLength(nLength); if ( theAnswer != "42" ) wxLogError("Something is very wrong!"); @endcode - @todo - the example above does not make use of wxStringBufferLength?? - 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