From ee49f54091935330ffbd942794748986faac8215 Mon Sep 17 00:00:00 2001 From: Francesco Montorsi Date: Thu, 19 Mar 2009 14:51:46 +0000 Subject: [PATCH] revised wxString docs: don't use old style grouping of functions at the beginning of the file; rather use doxygen-style member groups; to be able to reference member groups, introduce the new @member_group_name and @ref_member_group ALIASES; fix some typos in the process git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@59623 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/doxygen/Doxyfile_inc | 11 + interface/wx/string.h | 1808 +++++++++++++++++++------------------ 2 files changed, 951 insertions(+), 868 deletions(-) diff --git a/docs/doxygen/Doxyfile_inc b/docs/doxygen/Doxyfile_inc index 6acb0074f8..b37821874e 100644 --- a/docs/doxygen/Doxyfile_inc +++ b/docs/doxygen/Doxyfile_inc @@ -85,6 +85,17 @@ ALIASES += endFlagTable="\n" # creates appearance section: this should be used for all main GUI controls ALIASES += appearance{1}="\htmlonly
Appearance:
wxMSW appearancewxGTK appearancewxMac appearance
wxMSW appearancewxGTK appearancewxMac appearance
\endhtmlonly" +# aliases for the creation of "named member groups" +# USAGE: the first argument must not contain spaces and be a unique identifier +# of the member group for the class being documented; +# the second argument is the member group name and can contain spaces +# See wxString as an usage example. +# NOTE: no warnings are given for wrong member group names so be careful and check +# the doxygen output to verify that there are no typos +ALIASES += member_group_name{2}=" \name \2" +ALIASES += ref_member_group{2}="\2" + + #--------------------------------------------------------------------------- # Aliases - for use when documenting any C++ entity #--------------------------------------------------------------------------- diff --git a/interface/wx/string.h b/interface/wx/string.h index b937a5267b..fe98211313 100644 --- a/interface/wx/string.h +++ b/interface/wx/string.h @@ -40,204 +40,24 @@ be sure to read also @ref overview_unicode. - @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() - - - @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() + @section string_index Index of the member groups + + 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,67 @@ 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); /** - 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). */ wxString(const std::string& str); /** - Constructs a string from @e str. + Constructs a string from @a str. */ wxString(const std::wstring& str); - - + /** String destructor. @@ -347,560 +177,722 @@ 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. - - 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 + wxString operator =(wxUniChar c); - 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. - */ - bool Alloc(size_t nLen); /** - Appends the string literal @e psz. - */ - wxString& Append(const char* psz); + @member_group_name{length, String length} - /** - Appends the wide string literal @e pwz. + These functions return the string length and/or check whether the string + is empty. + + See also the length(), size() or empty() STL-like functions. */ - wxString& Append(const wchar_t* pwz); + //@{ + /** - Appends the string literal @e psz with max length @e nLen. + Returns the length of the string. */ - wxString& Append(const char* psz, size_t nLen); + size_t Len() const; /** - Appends the wide string literal @e psz with max length @e nLen. + 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 wchar_t* pwz, size_t nLen); + size_t Length() const; /** - Appends the string @e s. + Returns @true if the string is empty. */ - wxString& Append(const wxString& s); + bool IsEmpty() const; /** - Appends the character @e ch @e count times. + 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(wxUniChar ch, size_t count = 1u); + bool IsNull() const; /** - Gets all characters before the first occurrence of @e ch. - Returns the whole string if @a ch is not found. - */ - wxString BeforeFirst(wxUniChar ch) const; + Empty string is @false, so !string will only return @true if the + string is empty. - /** - Gets all characters before the last occurrence of @e ch. - Returns the empty string if @a ch is not found. + @see IsEmpty(). */ - wxString BeforeLast(wxUniChar ch) const; + bool operator!() 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. - See also: Empty() + @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. */ - void Clear(); + //@{ /** - Returns a deep copy of the string. - - That is, the returned string is guaranteed to not share data with this - string when using reference-counted wxString implementation. - - This method is primarily useful for passing strings between threads - (because wxString is not thread-safe). Unlike creating a copy using - @c wxString(c_str()), Clone() handles embedded NULs correctly. - - @since 2.9.0 - */ - wxString Clone() const; + Returns the character at position @a n (read-only). + */ + wxUniChar GetChar(size_t n) const; /** - Case-sensitive comparison. - Returns a positive value if the string is greater than the argument, - zero if it is equal to it or a negative value if it is less than the - argument (same semantics as the standard @c strcmp() function). - - See also CmpNoCase(), IsSameAs(). + wxWidgets compatibility conversion. Same as c_str(). */ - int Cmp(const wxString& s) const; + const wxCStrData GetData() const; /** - Case-insensitive comparison. - Returns a positive value if the string is greater than the argument, - zero if it is equal to it or a negative value if it is less than the - argument (same semantics as the standard @c strcmp() function). - - See also Cmp(), IsSameAs(). + Returns a reference to the character at position @a n. */ - int CmpNoCase(const wxString& s) const; + wxUniCharRef GetWritableChar(size_t n); /** - 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. + 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. */ - bool Contains(const wxString& str) const; - + wxStringCharType* GetWriteBuf(size_t len); /** - Makes the string empty, but doesn't free memory occupied by the string. - See also: Clear(). - */ - void Empty(); + 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(); + /** - 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. + @overload */ - bool EndsWith(const wxString& suffix, wxString *rest = NULL) const; - + void UngetWriteBuf(size_t len); + /** - Searches for the given character @e ch. Returns the position or - @c wxNOT_FOUND if not found. + Sets the character at position @e n. */ - int Find(wxUniChar ch, bool fromEnd = false) const; + void SetChar(size_t n, wxUniChar ch); /** - Searches for the given string @e sub. Returns the starting position or - @c wxNOT_FOUND if not found. + Returns a the last character. + + This is a wxWidgets 1.xx compatibility function; + you should not use it in new code. */ - int Find(const wxString& sub) const; - - //@{ + wxUniChar Last() const; + /** - Same as Find(). + 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 First(wxUniChar ch) const; - int First(const wxString& str) const; - //@} + wxUniCharRef Last(); /** - This static function returns the string containing the result of calling - Printf() with the passed parameters on it. - - @see FormatV(), Printf() + Returns the @a i-th character of the string. */ - static wxString Format(const wxString& format, ...); + wxUniChar operator [](size_t i) const; /** - This static function returns the string containing the result of calling - PrintfV() with the passed parameters on it. - - @see Format(), PrintfV() + Returns a writable reference to the @a i-th character of the string. */ - static wxString FormatV(const wxString& format, va_list argptr); + wxUniCharRef operator [](size_t i); + + //@} + /** - 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. + @member_group_name{conv, Conversions} + + 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. */ - int Freq(wxUniChar ch) const; - //@{ + /** - Converts given buffer of binary data from 8-bit string to wxString. In - Unicode build, the string is interpreted as being in ISO-8859-1 - encoding. The version without @e len parameter takes NUL-terminated - data. + 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. - 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. + Please see the @ref overview_unicode for more information about it. - @since 2.8.4 + 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 wxString::To8BitData() + @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str() */ - static wxString From8BitData(const char* buf, size_t len); - static wxString From8BitData(const char* buf); - //@} + wxCStrData c_str() const; - //@{ /** - Converts the string or character from an ASCII, 7-bit form - to the native wxString representation. + 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() */ - 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); - //@} + wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) 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. - - 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. + Returns buffer of the specified type containing the string data. - @since 2.8.4 - */ - static wxString FromUTF8(const char* s); - static wxString FromUTF8(const char* s, size_t len); - //@} + 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. - //@{ - /** - Converts C string encoded in UTF-8 to wxString without checking its - validity. + 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). - 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. + @param len + If non-@NULL, filled with the length of the returned buffer. - @since 2.8.9 - */ - static wxString FromUTF8Unchecked(const char* s); - static wxString FromUTF8Unchecked(const char* s, size_t len); - //@} + @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 the character at position @a n (read-only). + Returns a string representation suitable for passing to OS' functions + for file handling. */ - wxUniChar GetChar(size_t n) const; - + const wchar_t* fn_str() const; + /** - wxWidgets compatibility conversion. Same as c_str(). + @overload */ - const wxCStrData GetData() const; + const char* fn_str() const; /** - Returns a reference to the character at position @e n. + @overload */ - wxUniCharRef GetWritableChar(size_t n); + const wxCharBuffer fn_str() 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. + 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 */ - wxStringCharType* GetWriteBuf(size_t len); + const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const; /** - Returns @true if the string contains only ASCII characters. - See wxUniChar::IsAscii for more details. + 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. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + @see wc_str(), c_str(), mb_str() */ - bool IsAscii() const; - + const char* utf8_str() const; + /** - Returns @true if the string is empty. + @overload */ - bool IsEmpty() const; + const wxCharBuffer utf8_str() const; /** - Returns @true if the string is empty (same as wxString::IsEmpty). - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. - */ - bool IsNull() const; + 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). - /** - Returns @true if the string is an integer (with possible sign). - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + The macro wxWX2WCbuf is defined as the correct return type (without const). + + @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str() */ - bool IsNumber() const; + const wchar_t* wc_str() 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() + @overload */ - bool IsSameAs(const wxString &s, bool caseSensitive = true) const; - bool IsSameAs(wxUniChar ch, bool caseSensitive = true) const; - //@} + const wxWCharBuffer wc_str() 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. + 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() */ - bool IsWord() const; + wxWritableWCharBuffer wchar_str() const; - //@{ /** - Returns a reference to the last character (writable). - This is a wxWidgets 1.xx compatibility function; - you should not use it in new code. + Explicit conversion to C string in the internal representation (either + wchar_t* or UTF-8-encoded char*, depending on the build). */ - wxUniCharRef Last(); - const wxUniChar Last(); - //@} - + const wxStringCharType *wx_str() const; + /** - Returns the first @a count characters of the string. + Converts the string to an 8-bit string in ISO-8859-1 encoding in the + form of a wxCharBuffer (Unicode builds only). + + This is a convenience method useful when storing binary data in + wxString. It should be used @em only for this purpose. It is only valid + to call this method on strings created using From8BitData(). + + @since 2.8.4 + + @see wxString::From8BitData() */ - wxString Left(size_t count) const; + const char* To8BitData() const; /** - Returns the length of the string. + @overload */ - size_t Len() const; + const wxCharBuffer To8BitData() const; /** - Returns the length of the string (same as Len). - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + 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. */ - size_t Length() const; + const char* ToAscii() const; /** - Returns this string converted to the lower case. - - @see MakeLower() + @overload */ - wxString Lower() const; + const wxCharBuffer ToAscii() const; /** - Same as MakeLower. - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + Same as utf8_str(). */ - void LowerCase(); + const char* ToUTF8() 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. - - @since 2.9.0 - - @see Capitalize() + @overload */ - wxString& MakeCapitalized(); + const wxCharBuffer ToUTF8() const; - /** - 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. + @member_group_name{concat, Concatenation} - @see Upper() - */ - wxString& MakeUpper(); + 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. - /** - Returns @true if the string contents matches a mask containing '*' and '?'. + See also the insert() and append() STL-like functions. */ - bool Matches(const wxString& mask) const; + //@{ /** - Returns a substring starting at @e first, with length @e count, or the rest of - the string if @a count is the default value. + Appends the string literal @a psz. */ - wxString Mid(size_t first, size_t nCount = wxString::npos) const; - + wxString& Append(const char* psz); /** - 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). + Appends the wide string literal @a pwz. */ - wxString& Pad(size_t count, wxUniChar chPad = ' ', bool fromRight = true); + wxString& Append(const wchar_t* pwz); /** - Prepends @a str to this string, returning a reference to this string. + Appends the string literal @a psz with max length @a nLen. */ - wxString& Prepend(const wxString& str); + wxString& Append(const char* psz, size_t nLen); /** - Similar to the standard function @e sprintf(). Returns the number of - characters written, or an integer less than zero on error. - Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports - Unix98-style positional parameters: - - @note This function will use a safe version of @e vsprintf() (usually called - @e vsnprintf()) whenever available to always allocate the buffer of correct - size. Unfortunately, this function is not available on all platforms and the - dangerous @e vsprintf() will be used then which may lead to buffer overflows. + Appends the wide string literal @a psz with max length @a nLen. */ - int Printf(const wxString& pszFormat, ...); + wxString& Append(const wchar_t* pwz, size_t nLen); /** - Similar to vprintf. Returns the number of characters written, or an integer - less than zero - on error. + Appends the string @a s. */ - int PrintfV(const wxString& pszFormat, va_list argPtr); + wxString& Append(const wxString& s); - //@{ /** - 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. + Appends the character @a ch @a count times. */ - wxString Remove(size_t pos); - wxString Remove(size_t pos, size_t len); - //@} + wxString &Append(wxUniChar ch, size_t count = 1u); /** - Removes the last character. + Prepends @a str to this string, returning a reference to this string. */ - wxString& RemoveLast(size_t n = 1); + wxString& Prepend(const wxString& str); /** - 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. + Concatenation: returns a new string equal to the concatenation of the operands. */ - size_t Replace(const wxString& strOld, const wxString& strNew, - bool replaceAll = true); - + wxString operator +(const wxString& x, const wxString& y); + /** - Returns the last @a count characters. + @overload */ - wxString Right(size_t count) const; + wxString operator +(const wxString& x, wxUniChar y); - /** - Sets the character at position @e n. + 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); + + /** + Concatenation in place: the argument is appended to the string. */ - void SetChar(size_t n, wxUniChar ch); + void operator +=(const wxString& str); + + /** + @overload + */ + void operator +=(wxUniChar c); + + //@} + /** - Minimizes the string's memory. This can be useful after a call to - Alloc() if too much memory were preallocated. + @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. */ - bool Shrink(); + //@{ + + /** + 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). + + @see CmpNoCase(), IsSameAs(). + */ + int Cmp(const wxString& s) const; + + /** + Case-insensitive comparison. + Returns a positive value if the string is greater than the argument, + zero if it is equal to it or a negative value if it is less than the + argument (same semantics as the standard @c strcmp() function). + + @see Cmp(), IsSameAs(). + */ + int CmpNoCase(const wxString& s) const; + + /** + Test whether the string is equal to the single character @a c. + + The test is case-sensitive if @a caseSensitive is @true (default) or not if it is + @false. + + Returns @true if the string is equal to the character, @false otherwise. + + @see Cmp(), CmpNoCase() + */ + bool IsSameAs(const wxString &s, bool caseSensitive = true) const; + + /** + @overload + */ + 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 - @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. + @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; /** - 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. + 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. */ - wxString Strip(stripType s = trailing) const; + bool EndsWith(const wxString& suffix, wxString *rest = NULL) const; + + //@} + + + /** + @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. + */ + + /** + 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 nCount = wxString::npos) const; /** - Returns the part of the string between the indices @a from and @e to + 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). */ wxString SubString(size_t from, size_t to) const; + + /** + Same as Mid() (substring extraction). + */ + wxString operator()(size_t start, size_t len) const; + + /** + Returns the first @a count characters of the string. + */ + wxString Left(size_t count) const; + + /** + Returns the last @a count characters. + */ + wxString Right(size_t count) const; + + /** + Gets all the characters after the first occurrence of @e ch. + Returns the empty string if @e ch is not found. + */ + wxString AfterFirst(wxUniChar ch) const; + + /** + 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. + */ + wxString BeforeFirst(wxUniChar ch) const; + + /** + Gets all characters before the last occurrence of @e ch. + Returns the empty string if @a ch is not found. + */ + wxString BeforeLast(wxUniChar ch) const; + + //@} + + + /** + @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. + */ //@{ + /** - Converts the string to an 8-bit string in ISO-8859-1 encoding in the - form of a wxCharBuffer (Unicode builds only). + Return the copy of the string with the first string character in the + upper case and the subsequent ones in the lower case. - 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(). + @since 2.9.0 - @since 2.8.4 + @see MakeCapitalized() + */ + wxString Capitalize() const; - @see wxString::From8BitData() + /** + Returns this string converted to the lower case. + + @see MakeLower() */ - const char* To8BitData() const; - const wxCharBuffer To8BitData() const; + wxString Lower() const; + + /** + Same as MakeLower. + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + void LowerCase(); + + /** + 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. + */ + 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. + */ //@{ + /** - 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. + Searches for the given character @a ch. + Returns the position or @c wxNOT_FOUND if not found. */ - const char* ToAscii() const; - const wxCharBuffer ToAscii() const; + int Find(wxUniChar ch, bool fromEnd = false) const; + + /** + Searches for the given string @a sub. + Returns the starting position or @c wxNOT_FOUND if not found. + */ + int Find(const wxString& sub) const; + + /** + Same as Find(). + + This is a wxWidgets 1.xx compatibility function; + you should not use it in new code. + */ + int First(wxUniChar ch) const; + + /** + Same as Find(). + + This is a wxWidgets 1.xx compatibility function; + you should not use it in new code. + */ + int First(const wxString& str) const; + + /** + 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. + */ + size_t Replace(const wxString& strOld, const wxString& strNew, + bool replaceAll = true); + //@} + + + /** + @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. + */ + //@{ + /** 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 @@ -964,388 +956,468 @@ public: */ bool ToULongLong(wxULongLong_t* val, int base = 10) const; - //@{ - /** - Same as utf8_str(). - */ - const char* ToUTF8() const; - const wxCharBuffer ToUTF8() const; //@} - /** - Removes white-space (space, tabs, form feed, newline and carriage return) from - the left or from the right end of the string (right is default). - */ - wxString& Trim(bool fromRight = true); /** - Truncate the string to the given length. - */ - wxString& Truncate(size_t len); + @member_group_name{fmt, Formatting and printing} + Both formatted versions (Printf/() and stream-like insertion operators + exist (for basic types only). + + See also the static Format() and FormatV() functions. + */ //@{ - /** - 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). + /** + Similar to the standard function @e sprintf(). Returns the number of + characters written, or an integer less than zero on error. + Note that if @c wxUSE_PRINTF_POS_PARAMS is set to 1, then this function supports + Unix98-style positional parameters: - This method is deprecated, please use wxStringBuffer or - wxStringBufferLength instead. + @note This function will use a safe version of @e vsprintf() (usually called + @e vsnprintf()) whenever available to always allocate the buffer of correct + size. Unfortunately, this function is not available on all platforms and the + dangerous @e vsprintf() will be used then which may lead to buffer overflows. */ - void UngetWriteBuf(); - void UngetWriteBuf(size_t len); + 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 wxString& pszFormat, va_list argPtr); + //@} + + + /** + @member_group_name{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. + + See also the reserve() and resize() STL-like functions. + */ + //@{ + /** - Returns this string converted to upper case. + Preallocate enough space for wxString to store @a nLen characters. - @see MakeUpper() + 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. */ - wxString Upper() const; + bool Alloc(size_t nLen); /** - The same as MakeUpper(). - - This is a wxWidgets 1.xx compatibility function; you should not use it in new - code. + Minimizes the string's memory. This can be useful after a call to + Alloc() if too much memory were preallocated. */ - void UpperCase(); + bool Shrink(); /** - 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. + Returns a deep copy of the string. - Please see the @ref overview_unicode for more information about it. + That is, the returned string is guaranteed to not share data with this + string when using reference-counted wxString implementation. - 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. + 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. - @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str() + @since 2.9.0 + */ + wxString Clone() const; + + /** + Empties the string and frees memory occupied by it. + + @see Empty() */ - wxCStrData c_str() const; + void Clear(); + + //@} + + /** - 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{misc, Miscellaneous} - @see c_str() + Miscellaneous other string functions. */ - wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const; + //@{ /** - Returns buffer of the specified type containing the string data. + Returns @true if target appears anywhere in wxString; else @false. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. + */ + bool Contains(const wxString& str) const; - 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. + /** + Makes the string empty, but doesn't free memory occupied by the string. + + @see Clear(). + */ + void Empty(); - 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). + /** + Returns the number of occurrences of @e ch in the string. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. + */ + int Freq(wxUniChar ch) const; - @param len - If non-@NULL, filled with the length of the returned buffer. + /** + Returns @true if the string contains only ASCII characters. + See wxUniChar::IsAscii for more details. - @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; + This is a wxWidgets 1.xx compatibility function; you should not use it in new + code. + */ + bool IsAscii() const; - //@{ /** - Returns string representation suitable for passing to OS' functions - for file handling. + Returns @true if the string is an integer (with possible sign). + + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ - const wchar_t* fn_str() const; - const char* fn_str() const; - const wxCharBuffer fn_str() const; - //@} + bool IsNumber() const; /** - Returns the multibyte (C string) representation of the string - using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer. + Returns @true if the string is a word. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. + */ + bool IsWord() const; - @see wc_str(), utf8_str(), c_str(), wxMBConv + /** + Adds @a count copies of @a chPad to the beginning, or to the end of the + string (the default). + + Removes spaces from the left or from the right (default). */ - const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const; + wxString& Pad(size_t count, wxUniChar chPad = ' ', bool fromRight = true); + + /** + Removes all characters from the string starting at @a pos. + Use Truncate() as a more readable alternative. + + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. + */ + wxString& Remove(size_t pos); + + /** + 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. + */ + wxString& Remove(size_t pos, size_t len); /** - Extraction from a stream. + Removes the last character. */ - friend istream operator>>(istream& is, wxString& str); + wxString& RemoveLast(size_t n = 1); - //@{ /** - 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. + 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& 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); - //@} + wxString Strip(stripType s = trailing) const; /** - Same as Mid() (substring extraction). + Removes white-space (space, tabs, form feed, newline and carriage return) from + the left or from the right end of the string (right is default). */ - wxString operator()(size_t start, size_t len) const; + wxString& Trim(bool fromRight = true); - //@{ /** - Concatenation: these operators return a new string equal to the - concatenation of the operands. + Truncate the string to the given length. */ - wxString operator +(const wxString& x, const wxString& y); - wxString operator +(const wxString& x, wxUniChar y); + wxString& Truncate(size_t len); + //@} - //@{ + + + /** - Concatenation in place: the argument is appended to the string. + @member_group_name{iter, Iterator interface} + + These methods return iterators to the beginnnig or end of the string. + + Please see any STL reference (e.g. http://www.cppreference.com/wiki/string/start) + for their documentation. */ - void operator +=(const wxString& str); - void operator +=(wxUniChar c); + //@{ + + 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(); + //@} - //@{ + + /** - Assignment: the effect of each operation is the same as for the corresponding - constructor (see wxString constructors). + @member_group_name{stl, STL interface} + + The supported STL functions are listed here. + + Please see any STL reference (e.g. http://www.cppreference.com/wiki/string/start) + for their documentation. */ - wxString operator =(const wxString& str); - wxString operator =(wxUniChar c); + //@{ + + 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 FUNCTIONS + // Keep these functions separed from the other groups or Doxygen gets confused + // ----------------------------------------------------------------------------- - //@{ /** - Element extraction. + An 'invalid' value for string index */ - wxUniChar operator [](size_t i) const; - wxUniCharRef operator [](size_t i); - //@} + static const size_t npos; /** - Empty string is @false, so !string will only return @true if the - string is empty. + This static function returns the string containing the result of calling + Printf() with the passed parameters on it. - See also IsEmpty(). + @see FormatV(), Printf() */ - bool operator!() const; - + static wxString Format(const wxString& format, ...); - //@{ /** - 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. + This static function returns the string containing the result of calling + PrintfV() with the passed parameters on it. - @see wc_str(), c_str(), mb_str() + @see Format(), PrintfV() */ - const char* utf8_str() const; - const wxCharBuffer utf8_str() const; - //@} + static wxString FormatV(const wxString& format, va_list argptr); //@{ /** - 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). + 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. - The macro wxWX2WCbuf is defined as the correct return - type (without 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. - @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str() + @since 2.8.4 + + @see wxString::To8BitData() */ - const wchar_t* wc_str() const; - const wxWCharBuffer wc_str() const; + static wxString From8BitData(const char* buf, size_t len); + static wxString From8BitData(const char* buf); //@} + //@{ /** - 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() + Converts the string or character from an ASCII, 7-bit form + to the native wxString representation. */ - wxWritableWCharBuffer wchar_str() const; + 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); + //@} + //@{ /** - 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. - The supported STL functions are listed here. Please see any - STL reference for their documentation. + 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 */ - //@{ - 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); //@} }; -- 2.45.2