/////////////////////////////////////////////////////////////////////////////
// Name: string.h
-// Purpose: interface of wxStringBuffer
+// Purpose: interface of wxStringBuffer, wxString
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+
/**
- @class wxStringBuffer
- @wxheader{string.h}
+ @class wxString
- This tiny class allows to conveniently access the wxString
- internal buffer as a writable pointer without any risk of forgetting to restore
- the string to the usable state later.
+ The wxString class has been completely rewritten for wxWidgets 3.0
+ and this change was actually the main reason for the calling that
+ version wxWidgets 3.0.
- For example, assuming you have a low-level OS function called
- @c GetMeaningOfLifeAsString(char *) returning the value in the provided
- buffer (which must be writable, of course) you might call it like this:
+ wxString is a class representing a Unicode character string.
+ wxString uses @c std::basic_string internally (even if @c wxUSE_STL is not defined)
+ to store its content (unless this is not supported by the compiler or disabled
+ specifically when building wxWidgets) and it therefore inherits
+ many features from @c std::basic_string. (Note that most implementations of
+ @c std::basic_string are thread-safe and don't use reference counting.)
+
+ These @c std::basic_string standard functions are only listed here, but
+ they are not fully documented in this manual; see the STL documentation
+ (http://www.cppreference.com/wiki/string/start) for more info.
+ The behaviour of all these functions is identical to the behaviour
+ described there.
- @code
- wxString theAnswer;
- GetMeaningOfLifeAsString(wxStringBuffer(theAnswer, 1024));
- if ( theAnswer != "42" )
- {
- wxLogError("Something is very wrong!");
- }
- @endcode
+ You may notice that wxString sometimes has several functions which do
+ the same thing like Length(), Len() and length() which all return the
+ string length. In all cases of such duplication the @c std::string
+ compatible methods should be used.
- Note that the exact usage of this depends on whether on not wxUSE_STL is
- enabled. If
- wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer,
- and
- if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same
- buffer
- wxString uses intact. In other words, relying on wxStringBuffer containing the
- old
- wxString data is probably not a good idea if you want to build your program in
- both
- with and without wxUSE_STL.
+ For informations about the internal encoding used by wxString and
+ for important warnings and advices for using it, please read
+ the @ref overview_string.
- @library{wxbase}
- @category{FIXME}
-*/
-class wxStringBuffer
-{
-public:
- /**
- Constructs a writable string buffer object associated with the given string
- and containing enough space for at least @a len characters. Basically, this
- is equivalent to calling wxString::GetWriteBuf and
- saving the result.
- */
- wxStringBuffer(const wxString& str, size_t len);
+ In wxWidgets 3.0 wxString always stores Unicode strings, so you should
+ be sure to read also @ref overview_unicode.
- /**
- Restores the string passed to the constructor to the usable state by calling
- wxString::UngetWriteBuf on it.
- */
- ~wxStringBuffer();
- /**
- Returns the writable pointer to a buffer of the size at least equal to the
- length specified in the constructor.
- */
- wxStringCharType* operator wxStringCharType *();
-};
+ @section string_construct Constructors and assignment operators
+ A string may be constructed either from a C string, (some number of copies of)
+ a single character or a wide (Unicode) string. For all constructors (except the
+ default which creates an empty string) there is also a corresponding assignment
+ operator.
+
+ @li wxString()
+ @li operator=()
+ @li ~wxString()
+ @li assign()
-/**
- @class wxString
- @wxheader{string.h}
+ @section string_len String length
- wxString is a class representing a Unicode character string.
- wxString uses @c std::string internally to store its content
- unless this is not supported by the compiler or disabled
- specifically when building wxWidgets. Therefore wxString
- inherits many features from @c std::string's. Most
- implementations of @std::string are thread-safe and don't
- use reference counting. By default, wxString uses @c std::string
- internally even if wxUSE_STL is not defined.
-
- Since wxWidgets 3.0 wxString internally uses UCS-2 (basically 2-byte per
- character wchar_t) under Windows and UTF-8 under Unix, Linux and
- OS X to store its content. Much work has been done to make existing
- code using ANSI string literals work as before. If you need to have a
- wxString that uses wchar_t on Unix and Linux, too, you can specify
- this on the command line with the @c configure @c --disable-utf8 switch.
-
- As a consequence of this change, iterating over a wxString by index
- can become inefficient in UTF8 mode and iterators should be used instead:
+ These functions return the string length and check whether the string
+ is empty or they empty it.
- @code
- wxString s = "hello";
- wxString::const_iterator i;
- for (i = s.begin(); i != s.end(); ++i)
- {
- wxUniChar uni_ch = *i;
- // do something with it
- }
- @endcode
+ @li length()
+ @li size()
+ @li Len()
+ @li IsEmpty()
+ @li operator!()
+ @li Empty()
+ @li Clear()
- Please see the
- @ref overview_string "wxString overview" and the
- @ref overview_unicode "Unicode overview" for more information
- about it.
- wxString uses the current locale encoding to convert any C string
- literal to Unicode. The same is done for converting to and from
- @c std::string and for the return value of c_str(). For this
- conversion, the @a wxConvLibc class instance is used. See wxCSConv and wxMBConv.
+ @section string_access Character access
- wxString implements most of the methods of the @c std::string class.
- These standard functions are only listed here, but they are not
- fully documented in this manual. Please see the STL documentation.
- The behaviour of all these functions is identical to the behaviour
- described there.
+ Many functions below take a character index in the string. As with C
+ strings and arrays, the indices start from 0, so the first character of a
+ string is string[0]. An attempt to access a character beyond the end of the
+ string (which may even be 0 if the string is empty) will provoke an assert
+ failure in @ref overview_debugging "debug builds", but no checks are
+ done in release builds.
+
+ This section also contains both implicit and explicit conversions to C style
+ strings. Although implicit conversion is quite convenient, you are advised
+ to use wc_str() for the sake of clarity.
+
+ @li GetChar()
+ @li GetWritableChar()
+ @li SetChar()
+ @li Last()
+ @li operator[]()
+ @li wc_str()
+ @li utf8_str()
+ @li c_str()
+ @li wx_str()
+ @li mb_str()
+ @li fn_str()
+
+
+ @section string_concat Concatenation
+
+ Anything may be concatenated (appended to) with a string. However, you can't
+ append something to a C string (including literal constants), so to do this it
+ should be converted to a wxString first.
+
+ @li insert()
+ @li append()
+ @li operator<<()
+ @li operator+=()
+ @li operator+()
+ @li Append()
+ @li Prepend()
+
+
+ @section string_comp Comparison
+
+ The default comparison function Cmp() is case-sensitive and so is the default
+ version of IsSameAs(). For case insensitive comparisons you should use CmpNoCase()
+ or give a second parameter to IsSameAs(). This last function is maybe more
+ convenient if only equality of the strings matters because it returns a boolean
+ @true value if the strings are the same and not 0 (which is usually @false
+ in C) as Cmp() does.
+
+ Matches() is a poor man's regular expression matcher: it only understands
+ '*' and '?' metacharacters in the sense of DOS command line interpreter.
+
+ StartsWith() is helpful when parsing a line of text which should start
+ with some predefined prefix and is more efficient than doing direct string
+ comparison as you would also have to precalculate the length of the prefix.
+
+ @li compare()
+ @li Cmp()
+ @li CmpNoCase()
+ @li IsSameAs()
+ @li Matches()
+ @li StartsWith()
+ @li EndsWith()
+
+
+ @section string_substring Substring extraction
+
+ These functions allow you to extract a substring from the string. The
+ original string is not modified and the function returns the extracted
+ substring.
+
+ @li at()
+ @li substr()
+ @li Mid()
+ @li operator()()
+ @li Left()
+ @li Right()
+ @li BeforeFirst()
+ @li BeforeLast()
+ @li AfterFirst()
+ @li AfterLast()
+ @li StartsWith()
+ @li EndsWith()
+
+
+ @section string_case Case conversion
+
+ The MakeXXX() variants modify the string in place, while the other functions
+ return a new string which contains the original text converted to the upper or
+ lower case and leave the original string unchanged.
+
+ @li MakeUpper()
+ @li Upper()
+ @li MakeLower()
+ @li Lower()
+ @li MakeCapitalized()
+ @li Capitalize()
+
+
+ @section string_search Searching and replacing
+
+ These functions replace the standard @e strchr() and @e strstr()
+ functions.
+
+ @li find()
+ @li rfind()
+ @li replace()
+ @li Find()
+ @li Replace()
+
+
+ @section string_conv Conversion to numbers
+
+ The string provides functions for conversion to signed and unsigned integer and
+ floating point numbers. All functions take a pointer to the variable to
+ put the numeric value in and return @true if the @b entire string could be
+ converted to a number.
+
+ @li ToLong()
+ @li ToLongLong()
+ @li ToULong()
+ @li ToULongLong()
+ @li ToDouble()
+
+
+ @section string_fmt Writing values into the string
+
+ Both formatted versions (Printf/() and stream-like insertion operators
+ exist (for basic types only). Additionally, the Format() function allows
+ you to simply append a formatted value to a string:
+
+ @li Format()
+ @li FormatV()
+ @li Printf()
+ @li PrintfV()
+ @li operator>>()
+
+
+ @section string_mem Memory management
+
+ The following are "advanced" functions and they will be needed rarely.
+ Alloc() and Shrink() are only interesting for optimization purposes.
+ wxStringBuffer and wxStringBufferLength classes may be very useful
+ when working with some external API which requires the caller to provide
+ a writable buffer.
+
+ @li reserve()
+ @li resize()
+ @li Alloc()
+ @li Shrink()
+ @li wxStringBuffer
+ @li wxStringBufferLength
+
+
+ @section string_misc Miscellaneous
+
+ Miscellaneous other string functions.
+
+ @li Trim()
+ @li Truncate()
+ @li Pad()
+
+
+ @section string_compat wxWidgets 1.xx compatibility functions
+
+ The following functions are deprecated.
+ Please consider using @c std::string compatible variants.
+
+ Contains(), First(), Freq(), IsAscii(), IsNull(), IsNumber(), IsWord(),
+ Last(), Length(), LowerCase(), Remove(), Strip(), SubString(), UpperCase()
- You may notice that wxString sometimes has several functions which do
- the same thing like, for example, Length(), Len() and length() which
- all return the string length. In all cases of such duplication the
- @c std::string compatible method should be used.
-
- Anything may be concatenated (appended to) with a string. However, you can't
- append something to a C string (including literal constants), so to do this it
- should be converted to a wxString first.
-
- @li operator<<()
- @li operator+=()
- @li operator+()
- @li Append()
- @li Prepend()
-
- A string may be constructed either from a C string, (some number of copies of)
- a single character or a wide (UNICODE) string. For all constructors (except the
- default which creates an empty string) there is also a corresponding assignment
- operator.
-
- @li wxString()
- @li operator=()
- @li ~wxString()
-
- The MakeXXX() variants modify the string in place, while the other functions
- return a new string which contains the original text converted to the upper or
- lower case and leave the original string unchanged.
-
- @li MakeUpper()
- @li Upper()
- @li MakeLower()
- @li Lower()
-
- Many functions in this section take a character index in the string. As with C
- strings and/or arrays, the indices start from 0, so the first character of a
- string is string[0]. Attempt to access a character beyond the end of the
- string (which may be even 0 if the string is empty) will provoke an assert
- failure in @ref overview_debugging "debug build", but no checks are
- done in release builds.
- This section also contains both implicit and explicit conversions to C style
- strings. Although implicit conversion is quite convenient, it is advised to use
- explicit c_str() method for the sake of clarity.
-
- @li GetChar()
- @li GetWritableChar()
- @li SetChar()
- @li Last()
- @li operator[]()
- @li c_str()
- @li mb_str()
- @li wc_str()
- @li fn_str()
-
- The default comparison function Cmp() is case-sensitive and
- so is the default version of IsSameAs(). For case
- insensitive comparisons you should use CmpNoCase() or
- give a second parameter to IsSameAs. This last function is may be more
- convenient if only equality of the strings matters because it returns a boolean
- @true value if the strings are the same and not 0 (which is usually @false
- in C)as Cmp() does.
- Matches() is a poor man's regular expression matcher: it only understands
- '*' and '?' metacharacters in the sense of DOS command line interpreter.
- StartsWith() is helpful when parsing a line of text which should start
- with some predefined prefix and is more efficient than doing direct string
- comparison as you would also have to precalculate the length of the prefix then.
-
- @li Cmp()
- @li CmpNoCase()
- @li IsSameAs()
- @li Matches()
- @li StartsWith()
- @li EndsWith()
-
- The string provides functions for conversion to signed and unsigned integer and
- floating point numbers. All three functions take a pointer to the variable to
- put the numeric value in and return @true if the @b entire string could be
- converted to a number.
-
- @li ToLong()
- @li ToLongLong()
- @li ToULong()
- @li ToULongLong()
- @li ToDouble()
-
- These are "advanced" functions and they will be needed quite rarely.
- Alloc() and Shrink() are only interesting for optimization purposes.
- wxStringBuffer and wxStringBufferLength classes may be very useful
- when working with some external API which requires the caller to provide
- a writable buffer.
-
- @li Alloc()
- @li Shrink()
- @li wxStringBuffer
- @li wxStringBufferLength
-
- Misc. other string functions.
-
- @li Trim()
- @li Truncate()
- @li Pad()
-
- These functions return the string length and check whether the string
- is empty or empty it.
-
- @li Len()
- @li IsEmpty()
- @li operator!()
- @li Empty()
- @li Clear()
-
-
- These functions allow to extract substring from this string. All of them don't
- modify the original string and return a new string containing the extracted
- substring.
-
- @li Mid()
- @li operator()()
- @li Left()
- @li Right()
- @li BeforeFirst()
- @li BeforeLast()
- @li AfterFirst()
- @li AfterLast()
- @li StartsWith()
- @li EndsWith()
-
- These functions replace the standard @e strchr() and @e strstr()
- functions.
-
- @li Find()
- @li Replace()
-
- Both formatted versions (Printf/() and stream-like insertion operators
- exist (for basic types only). Additionally, the Format() function allows
- to use simply append formatted value to a string:
-
- @li Format()
- @li FormatV()
- @li Printf()
- @li PrintfV()
- @li operator>>()
-
- These functions are deprecated, please consider using new wxWidgets 2.0
- functions instead of them (or, even better, std::string compatible variants).
-
- Contains(), First(), Freq(), IsAscii(), IsNull(),
- IsNumber(), IsWord(), Last(), Length(), LowerCase(), Remove(), Strip(),
- SubString(), UpperCase()
@library{wxbase}
@category{data}
@stdobjects
- ::Objects:, ::wxEmptyString,
+ ::wxEmptyString
- @see @ref overview_string "wxString overview", @ref overview_unicode
- "Unicode overview"
+ @see @ref overview_string, @ref overview_unicode, wxUString
*/
class wxString
{
wxString();
/**
- Creates a string from another string. Just increases the ref
- count by 1.
+ Creates a string from another string.
+ Just increases the ref count by 1.
*/
wxString(const wxString& stringSrc);
wxString(const wchar_t *pwz, size_t nLength);
/**
- Constructs a string from @e buf using the using
- the current locale encoding to convert it to Unicode.
+ Constructs a string from @e buf using the using the current locale
+ encoding to convert it to Unicode.
*/
wxString(const wxCharBuffer& buf);
/**
- String destructor. Note that this is not virtual, so wxString must not be
- inherited from.
+ String destructor.
+
+ Note that this is not virtual, so wxString must not be inherited from.
*/
~wxString();
/**
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.
/**
Appends the wide string literal @e psz with max length @e nLen.
*/
- wxString& Append(const wchar_t* pwz, size_t nLen)
+ wxString& Append(const wchar_t* pwz, size_t nLen);
/**
Appends the string @e s.
*/
- wxString &Append(const wxString &s);
+ wxString& Append(const wxString& s);
/**
Appends the character @e ch @e count times.
*/
wxString BeforeLast(wxUniChar ch) const;
+ /**
+ Return the copy of the string with the first string character in the
+ upper case and the subsequent ones in the lower case.
+
+ @since 2.9.0
+
+ @see MakeCapitalized()
+ */
+ wxString Capitalize() const;
/**
Empties the string and frees memory occupied by it.
*/
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.
//@{
/**
Converts C string encoded in UTF-8 to wxString.
- Note that this method assumes that @a s is a valid UTF-8 sequence and
- doesn't do any validation in release builds, it's validity is only checked in
- debug builds.
+
+ If @a s is not a valid UTF-8 string, an empty string is returned.
+
+ Notice that when using UTF-8 wxWidgets build there is a more efficient
+ alternative to this function called FromUTF8Unchecked() which, unlike
+ this one, doesn't check that the input string is valid.
+
+ @since 2.8.4
*/
static wxString FromUTF8(const char* s);
static wxString FromUTF8(const char* s, size_t len);
//@}
+ //@{
+ /**
+ Converts C string encoded in UTF-8 to wxString without checking its
+ validity.
+
+ This method assumes that @a s is a valid UTF-8 sequence and doesn't do
+ any validation (although an assert failure is triggered in debug builds
+ if the string is invalid). Only use it if you are absolutely sure that
+ @a s is a correct UTF-8 string (e.g. because it comes from another
+ library using UTF-8) and if the performance matters, otherwise use
+ slower (in UTF-8 build) but safer FromUTF8(). Passing a bad UTF-8
+ string to this function will result in creating a corrupted wxString
+ and all the subsequent operations on it will be undefined.
+
+ @since 2.8.9
+ */
+ static wxString FromUTF8Unchecked(const char* s);
+ static wxString FromUTF8Unchecked(const char* s, size_t len);
+ //@}
+
/**
Returns the character at position @a n (read-only).
*/
/**
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 this string converted to the lower case.
+
+ @see MakeLower()
*/
wxString Lower() const;
void LowerCase();
/**
- Converts all characters to lower case and returns the result.
+ Converts the first characters of the string to the upper case and all
+ the subsequent ones to the lower case and returns the result.
+
+ @since 2.9.0
+
+ @see Capitalize()
+ */
+ wxString& MakeCapitalized();
+
+ /**
+ Converts all characters to lower case and returns the reference to the
+ modified string.
+
+ @see Lower()
*/
wxString& MakeLower();
/**
- Converts all characters to upper case and returns the result.
+ Converts all characters to upper case and returns the reference to the
+ modified string.
+
+ @see Upper()
*/
wxString& MakeUpper();
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
Converts the string to an ASCII, 7-bit string in the form of
a wxCharBuffer (Unicode builds only) or a C string (ANSI builds).
Note that this conversion only works if the string contains only ASCII
- characters. The @ref mbstr() mb_str method provides more
+ characters. The @ref mb_str() "mb_str" method provides more
powerful means of converting wxString to C string.
*/
const char* ToAscii() const;
@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.
Returns @true on success in which case the number is stored in the
location pointed to by @a val or @false if the string does not
represent a valid number in the given base (the value of @a val is not
- modified in this case). Please notice that this function
- behaves in the same way as the standard @c strtoul() and so it simply
- converts negative numbers to unsigned representation instead of rejecting them
- (e.g. -1 is returned as @c ULONG_MAX).
- See ToLong() for the more detailed
- description of the @a base parameter.
+ modified in this case).
+
+ Please notice that this function behaves in the same way as the standard
+ @c strtoul() and so it simply converts negative numbers to unsigned
+ representation instead of rejecting them (e.g. -1 is returned as @c ULONG_MAX).
+
+ See ToLong() for the more detailed description of the @a base parameter.
@see ToDouble(), ToLong()
*/
- bool ToULong(unsigned long val, int base = 10) const;
+ bool ToULong(unsigned long* val, int base = 10) const;
/**
This is exactly the same as ToULong() but works with 64
bit integer numbers.
Please see ToLongLong() for additional remarks.
*/
- bool ToULongLong(wxULongLong_t val, int base = 10) const;
+ bool ToULongLong(wxULongLong_t* val, int base = 10) const;
//@{
/**
Same as utf8_str().
*/
const char* ToUTF8() const;
- const wxCharBuffer ToUF8() const;
+ const wxCharBuffer ToUTF8() const;
//@}
/**
//@{
/**
Puts the string back into a reasonable state (in which it can be used
- normally), after
- GetWriteBuf() was called.
+ normally), after GetWriteBuf() was called.
+
The version of the function without the @a len parameter will calculate the
new string length itself assuming that the string is terminated by the first
@c NUL character in it while the second one will use the specified length
and thus is the only version which should be used with the strings with
embedded @c NULs (it is also slightly more efficient as @c strlen()
doesn't have to be called).
- This method is deprecated, please use
- wxStringBuffer or
+
+ This method is deprecated, please use wxStringBuffer or
wxStringBufferLength instead.
*/
void UngetWriteBuf();
/**
Returns this string converted to upper case.
+
+ @see MakeUpper()
*/
wxString Upper() const;
/**
- The same as MakeUpper.
+ The same as MakeUpper().
+
This is a wxWidgets 1.xx compatibility function; you should not use it in new
code.
*/
void UpperCase();
/**
- Returns a pointer to the string data (@c const char* when using UTF-8
- internally, @c const wchar_t* when using UCS-2 internally).
+ 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.
+
+ Please see the @ref overview_unicode for more information about it.
Note that the returned value is not convertible to @c char* or
@c wchar_t*, use char_str() or wchar_str() if you need to pass
string value to a function expecting non-const pointer.
+
+ @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str()
*/
- const wxCStrData c_str() const;
+ wxCStrData c_str() const;
/**
Returns an object with string data that is implicitly convertible to
buffer will contain the conversion of the string to the encoding of the
current locale (and so can fail).
- @param len If non-@NULL, filled with the length of the returned buffer.
+ @param len
+ If non-@NULL, filled with the length of the returned buffer.
+
@return
buffer containing the string contents in the specified type,
notice that it may be @NULL if the conversion failed (e.g. Unicode
const wxCharBuffer fn_str() const;
//@}
- //@{
/**
- Returns multibyte (C string) representation of the string.
- In Unicode build, converts using @e conv's wxMBConv::cWC2MB
- method and returns wxCharBuffer. In ANSI build, this function
- is same as c_str().
- The macro wxWX2MBbuf is defined as the correct return type (without const).
+ Returns the multibyte (C string) representation of the string
+ using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer.
- @see wxMBConv, c_str(), wc_str(), fn_str(), char_str()
+ @see wc_str(), utf8_str(), c_str(), wxMBConv
*/
- const char* mb_str(const wxMBConv& conv = wxConvLibc) const;
const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const;
- //@}
/**
Extraction from a stream.
*/
- friend istream operator(istream& is, wxString& str);
+ friend istream operator>>(istream& is, wxString& str);
//@{
/**
- These functions work as C++ stream insertion operators: they insert the given
- value into the string. Precision or format cannot be set using them, you can
- use Printf() for this.
- */
- wxString operator(const wxString& str);
- wxString operator(wxUniChar ch);
- wxString operator(int i);
- wxString operator(float f);
- wxString operator(double d);
+ These functions work as C++ stream insertion operators. They insert the
+ given value into the string. Precision and format cannot be set using them.
+ Use Printf() instead.
+ */
+ wxString& operator<<(const wxString& s);
+ wxString& operator<<(const char* psz);
+ wxString& operator<<(const wchar_t* pwz);
+ wxString& operator<<(const wxCStrData& psz);
+ wxString& operator<<(char ch);
+ wxString& operator<<(unsigned char ch);
+ wxString& operator<<(wchar_t ch);
+ wxString& operator<<(const wxCharBuffer& s);
+ wxString& operator<<(const wxWCharBuffer& s);
+ wxString& operator<<(wxUniCharRef ch);
+ wxString& operator<<(unsigned int ui);
+ wxString& operator<<(long l);
+ wxString& operator<<(unsigned long ul);
+ wxString& operator<<(wxLongLong_t ll);
+ wxString& operator<<(wxULongLong_t ul);
+ wxString& operator<<(float f);
+ wxString& operator<<(double d);
//@}
/**
- Same as Mid (substring extraction).
+ Same as Mid() (substring extraction).
*/
- wxString operator ()(size_t start, size_t len);
+ wxString operator()(size_t start, size_t len) const;
//@{
/**
//@{
/**
Assignment: the effect of each operation is the same as for the corresponding
- constructor (see @ref construct() "wxString constructors").
+ constructor (see wxString constructors).
*/
wxString operator =(const wxString& str);
wxString operator =(wxUniChar c);
Converts the strings contents to UTF-8 and returns it either as a
temporary wxCharBuffer object or as a pointer to the internal
string contents in UTF-8 build.
+
+ @see wc_str(), c_str(), mb_str()
*/
const char* utf8_str() const;
const wxCharBuffer utf8_str() const;
//@{
/**
Converts the strings contents to the wide character represention
- and returns it as a temporary wxWCharBuffer object or returns a
- pointer to the internal string contents in wide character mode.
+ and returns it as a temporary wxWCharBuffer object (Unix and OS X)
+ or returns a pointer to the internal string contents in wide character
+ mode (Windows).
The macro wxWX2WCbuf is defined as the correct return
type (without const).
- @see wxMBConv, c_str(), mb_str(), fn_str(), wchar_str()
+ @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str()
*/
const wchar_t* wc_str() const;
const wxWCharBuffer wc_str() const;
*/
wxWritableWCharBuffer wchar_str() const;
+ /**
+ Explicit conversion to C string in the internal representation (either
+ wchar_t* or UTF-8-encoded char*, depending on the build).
+ */
+ const wxStringCharType *wx_str() const;
+
+
/**
@name Iterator interface
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);
-
//@}
-
};
+/** @addtogroup group_string_operators */
+//@{
+/**
+ Comparison operators for wxString.
+*/
+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);
/**
- FIXME
+ Comparison operators with wxUniChar or wxUniCharRef.
*/
-wxString Objects:
-;
+inline bool operator==(const wxUniChar& c, const wxString& s);
+inline bool operator==(const wxUniCharRef& c, const wxString& s);
+inline bool operator==(char c, const wxString& s);
+inline bool operator==(wchar_t c, const wxString& s);
+inline bool operator==(int c, const wxString& s);
+inline bool operator==(const wxString& s, const wxUniChar& c);
+inline bool operator==(const wxString& s, const wxUniCharRef& c);
+inline bool operator==(const wxString& s, char c);
+inline bool operator==(const wxString& s, wchar_t c);
+inline bool operator!=(const wxUniChar& c, const wxString& s);
+inline bool operator!=(const wxUniCharRef& c, const wxString& s);
+inline bool operator!=(char c, const wxString& s);
+inline bool operator!=(wchar_t c, const wxString& s);
+inline bool operator!=(int c, const wxString& s);
+inline bool operator!=(const wxString& s, const wxUniChar& c);
+inline bool operator!=(const wxString& s, const wxUniCharRef& c);
+inline bool operator!=(const wxString& s, char c);
+inline bool operator!=(const wxString& s, wchar_t c);
+//@}
/**
- FIXME
+ The global wxString instance of an empty string.
+ Used extensively in the entire wxWidgets API.
*/
wxString wxEmptyString;
/**
@class wxStringBufferLength
- @wxheader{string.h}
- This tiny class allows to conveniently access the wxString
- internal buffer as a writable pointer without any risk of forgetting to restore
- the string to the usable state later, and allows the user to set the internal
- length of the string.
+ This tiny class allows you to conveniently access the wxString internal buffer
+ as a writable pointer without any risk of forgetting to restore the string to
+ the usable state later, and allows the user to set the internal length of the string.
For example, assuming you have a low-level OS function called
- @c int GetMeaningOfLifeAsString(char *) copying the value in the provided
+ @c "int GetMeaningOfLifeAsString(char *)" copying the value in the provided
buffer (which must be writable, of course), and returning the actual length
of the string, you might call it like this:
@code
- wxString theAnswer;
+ wxString theAnswer;
wxStringBuffer theAnswerBuffer(theAnswer, 1024);
int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
theAnswerBuffer.SetLength(nLength);
if ( theAnswer != "42" )
- {
wxLogError("Something is very wrong!");
- }
@endcode
- Note that the exact usage of this depends on whether on not wxUSE_STL is
- enabled. If
- wxUSE_STL is enabled, wxStringBuffer creates a separate empty character buffer,
- and
- if wxUSE_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same
- buffer
- wxString uses intact. In other words, relying on wxStringBuffer containing the
- old
- wxString data is probably not a good idea if you want to build your program in
- both
- with and without wxUSE_STL.
+ @todo
+ the example above does not make use of wxStringBufferLength??
+
+ Note that the exact usage of this depends on whether or not wxUSE_STL is
+ enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty
+ character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from
+ wxString, keeping the same buffer wxString uses intact. In other words,
+ relying on wxStringBuffer containing the old wxString data is not a good
+ idea if you want to build your program both with and without wxUSE_STL.
- Note that SetLength @c must be called before wxStringBufferLength destructs.
+ Note that wxStringBuffer::SetLength @b must be called before
+ wxStringBufferLength destructs.
@library{wxbase}
- @category{FIXME}
+ @category{data}
*/
class wxStringBufferLength
{
public:
/**
Constructs a writable string buffer object associated with the given string
- and containing enough space for at least @a len characters. Basically, this
- is equivalent to calling wxString::GetWriteBuf and
+ and containing enough space for at least @a len characters.
+
+ Basically, this is equivalent to calling wxString::GetWriteBuf and
saving the result.
*/
wxStringBufferLength(const wxString& str, size_t len);
/**
Sets the internal length of the string referred to by wxStringBufferLength to
@a nLength characters.
+
Must be called before wxStringBufferLength destructs.
*/
void SetLength(size_t nLength);
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 *();
+};
projects / wxWidgets.git / blobdiff