X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4701dc09838c3da46a8bc2836265a7dffee541ee..b5fe7ca67bf3121959a0b5a59afd00c1708f2f03:/interface/wx/string.h?ds=sidebyside diff --git a/interface/wx/string.h b/interface/wx/string.h index 7cf640a51f..b937a5267b 100644 --- a/interface/wx/string.h +++ b/interface/wx/string.h @@ -6,59 +6,6 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/** - @class wxStringBuffer - - This tiny class allows you to conveniently access the wxString internal buffer - as a writable pointer without any risk of forgetting to restore the string - to the usable state later. - - For example, assuming you have a low-level OS function called - @c "GetMeaningOfLifeAsString(char *)" returning the value in the provided - buffer (which must be writable, of course) you might call it like this: - - @code - wxString theAnswer; - GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024)); - if ( theAnswer != "42" ) - wxLogError("Something is very wrong!"); - @endcode - - Note that the exact usage of this depends on whether or not wxUSE_STL is - enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty - character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from - wxString, keeping the same buffer wxString uses intact. In other words, - relying on wxStringBuffer containing the old wxString data is not a good - idea if you want to build your program both with and without wxUSE_STL. - - @library{wxbase} - @category{data} -*/ -class wxStringBuffer -{ -public: - /** - Constructs a writable string buffer object associated with the given string - and containing enough space for at least @a len characters. - Basically, this is equivalent to calling wxString::GetWriteBuf() and - saving the result. - */ - wxStringBuffer(const wxString& str, size_t len); - - /** - Restores the string passed to the constructor to the usable state by calling - wxString::UngetWriteBuf() on it. - */ - ~wxStringBuffer(); - - /** - Returns the writable pointer to a buffer of the size at least equal to the - length specified in the constructor. - */ - wxStringCharType* operator wxStringCharType *(); -}; - - /** @class wxString @@ -68,66 +15,29 @@ public: version wxWidgets 3.0. wxString is a class representing a Unicode character string. - wxString uses @c std::string internally to store its content - unless this is not supported by the compiler or disabled - specifically when building wxWidgets and it therefore inherits - many features from @c std::string. Most implementations of - @c std::string are thread-safe and don't use reference counting. - By default, wxString uses @c std::string internally even if - wxUSE_STL is not defined. - - wxString now internally uses UTF-16 under Windows and UTF-8 under - Unix, Linux and OS X to store its content. Note that when iterating - over a UTF-16 string under Windows, the user code has to take care - of surrogate pair handling whereas Windows itself has built-in - support pairs in UTF-16, such as for drawing strings on screen. - - Much work has been done to make existing code using ANSI string literals - work as before. If you nonetheless need to have a wxString that uses wchar_t - on Unix and Linux, too, you can specify this on the command line with the - @c configure @c --disable-utf8 switch or you can consider using wxUString - or std::wstring instead. - - Accessing a UTF-8 string by index can be very inefficient because - a single character is represented by a variable number of bytes so that - the entire string has to be parsed in order to find the character. - Since iterating over a string by index is a common programming technique and - was also possible and encouraged by wxString using the access operator[]() - wxString implements caching of the last used index so that iterating over - a string is a linear operation even in UTF-8 mode. - - It is nonetheless recommended to use iterators (instead of index based - access) like this: - - @code - wxString s = "hello"; - wxString::const_iterator i; - for (i = s.begin(); i != s.end(); ++i) - { - wxUniChar uni_ch = *i; - // do something with it - } - @endcode - - Please see the @ref overview_string and the @ref overview_unicode for more - information about it. - - wxString uses the current locale encoding to convert any C string - literal to Unicode. The same is done for converting to and from - @c std::string and for the return value of c_str(). - For this conversion, the @a wxConvLibc class instance is used. - See wxCSConv and wxMBConv. - - wxString implements most of the methods of the @c std::string class. - These standard functions are only listed here, but they are not - fully documented in this manual. Please see the STL documentation. + wxString uses @c std::basic_string internally (even if @c wxUSE_STL is not defined) + to store its content (unless this is not supported by the compiler or disabled + specifically when building wxWidgets) and it therefore inherits + many features from @c std::basic_string. (Note that most implementations of + @c std::basic_string are thread-safe and don't use reference counting.) + + These @c std::basic_string standard functions are only listed here, but + they are not fully documented in this manual; see the STL documentation + (http://www.cppreference.com/wiki/string/start) for more info. The behaviour of all these functions is identical to the behaviour described there. You may notice that wxString sometimes has several functions which do - the same thing like Length(), Len() and length() which - all return the string length. In all cases of such duplication the - @c std::string compatible method should be used. + the same thing like Length(), Len() and length() which all return the + string length. In all cases of such duplication the @c std::string + compatible methods should be used. + + For informations about the internal encoding used by wxString and + for important warnings and advices for using it, please read + the @ref overview_string. + + Since wxWidgets 3.0 wxString always stores Unicode strings, so you should + be sure to read also @ref overview_unicode. @section string_construct Constructors and assignment operators @@ -229,6 +139,7 @@ public: original string is not modified and the function returns the extracted substring. + @li at() @li substr() @li Mid() @li operator()() @@ -320,14 +231,13 @@ public: @li Pad() - @section string_misc wxWidgets 1.xx compatibility functions + @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() + Contains(), First(), Freq(), IsAscii(), IsNull(), IsNumber(), IsWord(), + Last(), Length(), LowerCase(), Remove(), Strip(), SubString(), UpperCase() @library{wxbase} @@ -336,7 +246,8 @@ public: @stdobjects ::wxEmptyString - @see @ref overview_string, @ref overview_unicode, wxUString + @see @ref overview_string, @ref overview_unicode, wxUString, + wxCharBuffer, wxUniChar, wxStringTokenizer, @ref group_funcmacro_string */ class wxString { @@ -494,22 +405,22 @@ public: /** Appends the wide string literal @e pwz. */ - wxString& Append(const wchar_t* pwz) + wxString& Append(const wchar_t* pwz); /** Appends the string literal @e psz with max length @e nLen. */ - wxString& Append(const wchar_t* pwz); + wxString& Append(const char* psz, size_t nLen); /** Appends the wide string literal @e psz with max length @e nLen. */ - wxString& Append(const wchar_t* pwz, size_t nLen) + wxString& Append(const wchar_t* pwz, size_t nLen); /** Appends the string @e s. */ - wxString& Append(const wchar_t* pwz, size_t nLen); + wxString& Append(const wxString& s); /** Appends the character @e ch @e count times. @@ -578,26 +489,6 @@ public: */ int CmpNoCase(const wxString& s) const; - - //@{ - /** - Comparison operators - */ - bool operator ==(const wxString& x, const wxString& y); - bool operator ==(const wxString& x, wxUniChar ch); - bool operator !=(const wxString& x, const wxString& y); - bool operator !=(const wxString& x, wxUniChar ch); - bool operator(const wxString& x, const wxString& y); - bool operator(const wxString& x, wxUniChar ch); - bool operator =(const wxString& x, const wxString& y); - bool operator =(const wxString& x, wxUniChar ch); - bool operator(const wxString& x, const wxString& y); - bool operator(const wxString& x, wxUniChar ch); - bool operator =(const wxString& x, const wxString& y); - bool operator =(const wxString& x, wxUniChar ch); - //@} - - /** Returns @true if target appears anywhere in wxString; else @false. This is a wxWidgets 1.xx compatibility function; you should not use it in new @@ -649,7 +540,7 @@ public: @see FormatV(), Printf() */ - static wxString Format(const wxChar format, ...); + static wxString Format(const wxString& format, ...); /** This static function returns the string containing the result of calling @@ -657,7 +548,7 @@ public: @see Format(), PrintfV() */ - static wxString FormatV(const wxChar format, va_list argptr); + static wxString FormatV(const wxString& format, va_list argptr); /** Returns the number of occurrences of @e ch in the string. @@ -742,7 +633,7 @@ public: /** wxWidgets compatibility conversion. Same as c_str(). */ - const wxCStrData* GetData() const; + const wxCStrData GetData() const; /** Returns a reference to the character at position @e n. @@ -762,6 +653,8 @@ public: /** Returns @true if the string contains only ASCII characters. + See wxUniChar::IsAscii for more details. + This is a wxWidgets 1.xx compatibility function; you should not use it in new code. */ @@ -881,15 +774,14 @@ public: Returns a substring starting at @e first, with length @e count, or the rest of the string if @a count is the default value. */ - wxString Mid(size_t first, size_t count = wxSTRING_MAXLEN) const; + wxString Mid(size_t first, size_t nCount = wxString::npos) const; /** Adds @a count copies of @a pad to the beginning, or to the end of the string (the default). Removes spaces from the left or from the right (default). */ - wxString& Pad(size_t count, wxUniChar pad = ' ', - bool fromRight = true); + wxString& Pad(size_t count, wxUniChar chPad = ' ', bool fromRight = true); /** Prepends @a str to this string, returning a reference to this string. @@ -907,14 +799,14 @@ public: size. Unfortunately, this function is not available on all platforms and the dangerous @e vsprintf() will be used then which may lead to buffer overflows. */ - int Printf(const wxChar* pszFormat, ...); + int Printf(const wxString& pszFormat, ...); /** Similar to vprintf. Returns the number of characters written, or an integer less than zero on error. */ - int PrintfV(const wxChar* pszFormat, va_list argPtr); + int PrintfV(const wxString& pszFormat, va_list argPtr); //@{ /** @@ -929,7 +821,7 @@ public: /** Removes the last character. */ - wxString RemoveLast(); + wxString& RemoveLast(size_t n = 1); /** Replace first (or all) occurrences of substring with another one. @@ -953,7 +845,7 @@ public: Minimizes the string's memory. This can be useful after a call to Alloc() if too much memory were preallocated. */ - void Shrink(); + bool Shrink(); /** This function can be used to test if the string starts with the specified @@ -1017,7 +909,7 @@ public: @see ToLong(), ToULong() */ - bool ToDouble(double val) const; + bool ToDouble(double* val) const; /** Attempts to convert the string to a signed integer in base @e base. Returns @@ -1035,7 +927,7 @@ public: @see ToDouble(), ToULong() */ - bool ToLong(long val, int base = 10) const; + bool ToLong(long* val, int base = 10) const; /** This is exactly the same as ToLong() but works with 64 @@ -1046,7 +938,7 @@ public: @see ToLong(), ToULongLong() */ - bool ToLongLong(wxLongLong_t val, int base = 10) const; + bool ToLongLong(wxLongLong_t* val, int base = 10) const; /** Attempts to convert the string to an unsigned integer in base @e base. @@ -1063,14 +955,14 @@ public: @see ToDouble(), ToLong() */ - bool ToULong(unsigned long val, int base = 10) const; + bool ToULong(unsigned long* val, int base = 10) const; /** This is exactly the same as ToULong() but works with 64 bit integer numbers. Please see ToLongLong() for additional remarks. */ - bool ToULongLong(wxULongLong_t val, int base = 10) const; + bool ToULongLong(wxULongLong_t* val, int base = 10) const; //@{ /** @@ -1139,7 +1031,7 @@ public: @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str() */ - const wxCStrData c_str() const; + wxCStrData c_str() const; /** Returns an object with string data that is implicitly convertible to @@ -1200,22 +1092,21 @@ public: */ friend istream operator>>(istream& is, wxString& str); + //@{ /** 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<<(const char* psz); - wxString& operator<<(wxUniCharRef ch) - 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<<(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); @@ -1224,11 +1115,12 @@ public: wxString& operator<<(wxULongLong_t ul); wxString& operator<<(float f); wxString& operator<<(double d); + //@} /** Same as Mid() (substring extraction). */ - wxString operator ()(size_t start, size_t len); + wxString operator()(size_t start, size_t len) const; //@{ /** @@ -1250,7 +1142,7 @@ public: //@{ /** Assignment: the effect of each operation is the same as for the corresponding - constructor (see @ref wxString() "wxString constructors"). + constructor (see wxString constructors). */ wxString operator =(const wxString& str); wxString operator =(wxUniChar c); @@ -1344,14 +1236,6 @@ public: STL reference for their documentation. */ //@{ - size_t length() const; - size_type size() const; - size_type max_size() const; - size_type capacity() const; - void reserve(size_t sz); - - void resize(size_t nSize, wxUniChar ch = '\0'); - wxString& append(const wxString& str, size_t pos, size_t n); wxString& append(const wxString& str); wxString& append(const char *sz, size_t n); @@ -1366,8 +1250,13 @@ public: wxString& assign(size_t n, wxUniChar ch); wxString& assign(const_iterator first, const_iterator last); + wxUniChar at(size_t n) const; + wxUniCharRef at(size_t n); + void clear(); + size_type capacity() const; + int compare(const wxString& str) const; int compare(size_t nStart, size_t nLen, const wxString& str) const; int compare(size_t nStart, size_t nLen, @@ -1377,6 +1266,8 @@ public: int compare(size_t nStart, size_t nLen, const wchar_t* sz, size_t nCount = npos) const; + wxCStrData data() const; + bool empty() const; wxString& erase(size_type pos = 0, size_type n = npos); @@ -1387,6 +1278,28 @@ public: size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const; size_t find(const wchar_t* sz, size_t nStart = 0, size_t n = npos) const; size_t find(wxUniChar ch, size_t nStart = 0) const; + size_t find_first_of(const char* sz, size_t nStart = 0) const; + size_t find_first_of(const wchar_t* sz, size_t nStart = 0) const; + size_t find_first_of(const char* sz, size_t nStart, size_t n) const; + size_t find_first_of(const wchar_t* sz, size_t nStart, size_t n) const; + size_t find_first_of(wxUniChar c, size_t nStart = 0) const; + size_t find_last_of (const wxString& str, size_t nStart = npos) const; + size_t find_last_of (const char* sz, size_t nStart = npos) const; + size_t find_last_of (const wchar_t* sz, size_t nStart = npos) const; + size_t find_last_of(const char* sz, size_t nStart, size_t n) const; + size_t find_last_of(const wchar_t* sz, size_t nStart, size_t n) const; + size_t find_last_of(wxUniChar c, size_t nStart = npos) const; + size_t find_first_not_of(const wxString& str, size_t nStart = 0) const; + size_t find_first_not_of(const char* sz, size_t nStart = 0) const; + size_t find_first_not_of(const wchar_t* sz, size_t nStart = 0) const; + size_t find_first_not_of(const char* sz, size_t nStart, size_t n) const; + size_t find_first_not_of(const wchar_t* sz, size_t nStart, size_t n) const; + size_t find_first_not_of(wxUniChar ch, size_t nStart = 0) const; + size_t find_last_not_of(const wxString& str, size_t nStart = npos) const; + size_t find_last_not_of(const char* sz, size_t nStart = npos) const; + size_t find_last_not_of(const wchar_t* sz, size_t nStart = npos) const; + size_t find_last_not_of(const char* sz, size_t nStart, size_t n) const; + size_t find_last_not_of(const wchar_t* sz, size_t nStart, size_t n) const; wxString& insert(size_t nPos, const wxString& str); wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n); @@ -1397,40 +1310,95 @@ public: void insert(iterator it, const_iterator first, const_iterator last); void insert(iterator it, size_type n, wxUniChar ch); + size_t length() const; + + size_type max_size() const; + + void reserve(size_t sz); + void resize(size_t nSize, wxUniChar ch = '\0'); + wxString& replace(size_t nStart, size_t nLen, const wxString& str); wxString& replace(size_t nStart, size_t nLen, size_t nCount, wxUniChar ch); wxString& replace(size_t nStart, size_t nLen, - const wxString& str, size_t nStart2, size_t nLen2); + const wxString& str, size_t nStart2, size_t nLen2); wxString& replace(size_t nStart, size_t nLen, - const char* sz, size_t nCount); + const char* sz, size_t nCount); wxString& replace(size_t nStart, size_t nLen, - const wchar_t* sz, size_t nCount); + const wchar_t* sz, size_t nCount); wxString& replace(size_t nStart, size_t nLen, - const wxString& s, size_t nCount); + const wxString& s, size_t nCount); wxString& replace(iterator first, iterator last, const wxString& s); wxString& replace(iterator first, iterator last, const char* s, size_type n); wxString& replace(iterator first, iterator last, const wchar_t* s, size_type n); wxString& replace(iterator first, iterator last, size_type n, wxUniChar ch); wxString& replace(iterator first, iterator last, - const_iterator first1, const_iterator last1); + const_iterator first1, const_iterator last1); wxString& replace(iterator first, iterator last, - const char *first1, const char *last1); + const char *first1, const char *last1); wxString& replace(iterator first, iterator last, - const wchar_t *first1, const wchar_t *last1); + const wchar_t *first1, const wchar_t *last1); size_t rfind(const wxString& str, size_t nStart = npos) const; size_t rfind(const char* sz, size_t nStart = npos, size_t n = npos) const; size_t rfind(const wchar_t* sz, size_t nStart = npos, size_t n = npos) const; size_t rfind(wxUniChar ch, size_t nStart = npos) const; + size_type size() const; wxString substr(size_t nStart = 0, size_t nLen = npos) const; - void swap(wxString& str); - //@} - }; + + +//@{ +/** + Comparison operator for string types. +*/ +inline bool operator==(const wxString& s1, const wxString& s2); +inline bool operator!=(const wxString& s1, const wxString& s2); +inline bool operator< (const wxString& s1, const wxString& s2); +inline bool operator> (const wxString& s1, const wxString& s2); +inline bool operator<=(const wxString& s1, const wxString& s2); +inline bool operator>=(const wxString& s1, const wxString& s2); +inline bool operator==(const wxString& s1, const wxCStrData& s2); +inline bool operator==(const wxCStrData& s1, const wxString& s2); +inline bool operator!=(const wxString& s1, const wxCStrData& s2); +inline bool operator!=(const wxCStrData& s1, const wxString& s2); +inline bool operator==(const wxString& s1, const wxWCharBuffer& s2); +inline bool operator==(const wxWCharBuffer& s1, const wxString& s2); +inline bool operator!=(const wxString& s1, const wxWCharBuffer& s2); +inline bool operator!=(const wxWCharBuffer& s1, const wxString& s2); +inline bool operator==(const wxString& s1, const wxCharBuffer& s2); +inline bool operator==(const wxCharBuffer& s1, const wxString& s2); +inline bool operator!=(const wxString& s1, const wxCharBuffer& s2); +inline bool operator!=(const wxCharBuffer& s1, const wxString& s2); +//@} + +//@{ +/** + Comparison operators char types. +*/ +inline bool operator==(const wxUniChar& c, const wxString& s); +inline bool operator==(const wxUniCharRef& c, const wxString& s); +inline bool operator==(char c, const wxString& s); +inline bool operator==(wchar_t c, const wxString& s); +inline bool operator==(int c, const wxString& s); +inline bool operator==(const wxString& s, const wxUniChar& c); +inline bool operator==(const wxString& s, const wxUniCharRef& c); +inline bool operator==(const wxString& s, char c); +inline bool operator==(const wxString& s, wchar_t c); +inline bool operator!=(const wxUniChar& c, const wxString& s); +inline bool operator!=(const wxUniCharRef& c, const wxString& s); +inline bool operator!=(char c, const wxString& s); +inline bool operator!=(wchar_t c, const wxString& s); +inline bool operator!=(int c, const wxString& s); +inline bool operator!=(const wxString& s, const wxUniChar& c); +inline bool operator!=(const wxString& s, const wxUniCharRef& c); +inline bool operator!=(const wxString& s, char c); +inline bool operator!=(const wxString& s, wchar_t c); +//@} + /** The global wxString instance of an empty string. Used extensively in the entire wxWidgets API. @@ -1439,7 +1407,6 @@ wxString wxEmptyString; - /** @class wxStringBufferLength @@ -1510,3 +1477,81 @@ public: wxChar* operator wxChar *(); }; + +/** + @class wxStringBuffer + + This tiny class allows you to conveniently access the wxString internal buffer + as a writable pointer without any risk of forgetting to restore the string + to the usable state later. + + For example, assuming you have a low-level OS function called + @c "GetMeaningOfLifeAsString(char *)" returning the value in the provided + buffer (which must be writable, of course) you might call it like this: + + @code + wxString theAnswer; + GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024)); + if ( theAnswer != "42" ) + wxLogError("Something is very wrong!"); + @endcode + + Note that the exact usage of this depends on whether or not @c wxUSE_STL is + enabled. If @c wxUSE_STL is enabled, wxStringBuffer creates a separate empty + character buffer, and if @c wxUSE_STL is disabled, it uses GetWriteBuf() from + wxString, keeping the same buffer wxString uses intact. In other words, + relying on wxStringBuffer containing the old wxString data is not a good + idea if you want to build your program both with and without @c wxUSE_STL. + + @library{wxbase} + @category{data} +*/ +class wxStringBuffer +{ +public: + /** + Constructs a writable string buffer object associated with the given string + and containing enough space for at least @a len characters. + Basically, this is equivalent to calling wxString::GetWriteBuf() and + saving the result. + */ + wxStringBuffer(const wxString& str, size_t len); + + /** + Restores the string passed to the constructor to the usable state by calling + wxString::UngetWriteBuf() on it. + */ + ~wxStringBuffer(); + + /** + Returns the writable pointer to a buffer of the size at least equal to the + length specified in the constructor. + */ + wxStringCharType* operator wxStringCharType *(); +}; + + +/** @addtogroup group_funcmacro_string */ +//@{ + +/** + Allows to extend a function with the signature: + @code bool SomeFunc(const wxUniChar& c) @endcode + which operates on a single character, to an entire wxString. + + E.g. if you want to check if an entire string contains only digits, + you can do: + @code + if (wxStringCheck(myString)) + ... // the entire string contains oly digits! + else + ... // at least one character of myString is not a digit + @endcode + + @return @true if the given function returns a non-zero value for all + characters of the @a val string. +*/ +template + inline bool wxStringCheck(const wxString& val); + +//@}