// 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
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
original string is not modified and the function returns the extracted
substring.
+ @li at()
@li substr()
@li Mid()
@li operator()()
@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}
@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
{
/**
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.
*/
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
@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
@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.
/**
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.
/**
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.
*/
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.
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);
//@{
/**
/**
Removes the last character.
*/
- wxString RemoveLast();
+ wxString& RemoveLast(size_t n = 1);
/**
Replace first (or all) occurrences of substring with another one.
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
@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
@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
@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.
@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;
//@{
/**
@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
*/
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);
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;
//@{
/**
//@{
/**
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);
STL reference for their documentation.
*/
//@{
- size_t length() const;
- size_type size() const;
- size_type max_size() const;
- size_type capacity() const;
- void reserve(size_t sz);
-
- void resize(size_t nSize, wxUniChar ch = '\0');
-
wxString& append(const wxString& str, size_t pos, size_t n);
wxString& append(const wxString& str);
wxString& append(const char *sz, size_t n);
wxString& 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,
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);
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);
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.
-
/**
@class wxStringBufferLength
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<wxIsdigit>(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<bool (T)(const wxUniChar& c)>
+ inline bool wxStringCheck(const wxString& val);
+
+//@}
projects / wxWidgets.git / blobdiff