// Name: string.h
// Purpose: interface of wxStringBuffer, wxString
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
-/**
- @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
- 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.
-
- 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.
- 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.
-
-
- @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 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.
+ String class for passing textual data to or receiving it from wxWidgets.
+
+ @note
+ While the use of wxString is unavoidable in wxWidgets program, you are
+ encouraged to use the standard string classes @c std::string or @c
+ std::wstring in your applications and convert them to and from wxString
+ only when interacting with wxWidgets.
+
+
+ wxString is a class representing a Unicode character string but with
+ methods taking or returning both @c wchar_t wide characters and @c wchar_t*
+ wide strings and traditional @c char characters and @c char* strings. The
+ dual nature of wxString API makes it simple to use in all cases and,
+ importantly, allows the code written for either ANSI or Unicode builds of
+ the previous wxWidgets versions to compile and work correctly with the
+ single unified Unicode build of wxWidgets 3.0. It is also mostly
+ transparent when using wxString with the few exceptions described below.
+
+
+ @section string_api API overview
+
+ wxString tries to be similar to both @c std::string and @c std::wstring and
+ can mostly be used as either class. It provides practically all of the
+ methods of these classes, which behave exactly the same as in the standard
+ C++, and so are not documented here (please see any standard library
+ documentation, for example http://en.cppreference.com/w/cpp/string for more
+ details).
+
+ In addition to these standard methods, wxString adds functions dealing with
+ the conversions between different string encodings, described below, as
+ well as many extra helpers such as functions for formatted output
+ (Printf(), Format(), ...), case conversion (MakeUpper(), Capitalize(), ...)
+ and various others (Trim(), StartsWith(), Matches(), ...). All of the
+ non-standard methods follow wxWidgets "CamelCase" naming convention and are
+ documented here.
+
+ Notice that some wxString methods exist in several versions for
+ compatibility reasons. For example all of length(), Length() and Len() are
+ provided. In such cases it is recommended to use the standard string-like
+ method, i.e. length() in this case.
+
+
+ @section string_conv Converting to and from wxString
+
+ wxString can be created from:
+ - ASCII string guaranteed to contain only 7 bit characters using
+ wxString::FromAscii().
+ - Narrow @c char* string in the current locale encoding using implicit
+ wxString::wxString(const char*) constructor.
+ - Narrow @c char* string in UTF-8 encoding using wxString::FromUTF8().
+ - Narrow @c char* string in the given encoding using
+ wxString::wxString(const char*, const wxMBConv&) constructor passing a
+ wxCSConv corresponding to the encoding as the second argument.
+ - Standard @c std::string using implicit wxString::wxString(const
+ std::string&) constructor. Notice that this constructor supposes that
+ the string contains data in the current locale encoding, use FromUTF8()
+ or the constructor taking wxMBConv if this is not the case.
+ - Wide @c wchar_t* string using implicit wxString::wxString(const
+ wchar_t*) constructor.
+ - Standard @c std::wstring using implicit wxString::wxString(const
+ std::wstring&) constructor.
+
+ Notice that many of the constructors are implicit, meaning that you don't
+ even need to write them at all to pass the existing string to some
+ wxWidgets function taking a wxString.
+
+ Similarly, wxString can be converted to:
+ - ASCII string using wxString::ToAscii(). This is a potentially
+ destructive operation as all non-ASCII string characters are replaced
+ with a placeholder character.
+ - String in the current locale encoding implicitly or using c_str() or
+ mb_str() methods. This is a potentially destructive operation as an @e
+ empty string is returned if the conversion fails.
+ - String in UTF-8 encoding using wxString::utf8_str().
+ - String in any given encoding using mb_str() with the appropriate
+ wxMBConv object. This is also a potentially destructive operation.
+ - Standard @c std::string using wxString::ToStdString(). The contents
+ of the returned string use the current locale encoding, so this
+ conversion is potentially destructive as well.
+ - Wide C string using wxString::wc_str().
+ - Standard @c std::wstring using wxString::ToStdWstring().
+
+ @note If you built wxWidgets with @c wxUSE_STL set to 1, the implicit
+ conversions to both narrow and wide C strings are disabled and replaced
+ with implicit conversions to @c std::string and @c std::wstring.
+
+ Please notice that the conversions marked as "potentially destructive"
+ above can result in loss of data if their result is not checked, so you
+ need to verify that converting the contents of a non-empty Unicode string
+ to a non-UTF-8 multibyte encoding results in non-empty string. The simplest
+ and best way to ensure that the conversion never fails is to always use
+ UTF-8.
+
+
+ @section string_gotchas Traps for the unwary
+
+ As mentioned above, wxString tries to be compatible with both narrow and
+ wide standard string classes and mostly does it transparently, but there
+ are some exceptions.
+
+ @subsection string_gotchas_element String element access
+
+ Some problems are caused by wxString::operator[]() which returns an object
+ of a special proxy class allowing to assign either a simple @c char or a @c
+ wchar_t to the given index. Because of this, the return type of this
+ operator is neither @c char nor @c wchar_t nor a reference to one of these
+ types but wxUniCharRef which is not a primitive type and hence can't be
+ used in the @c switch statement. So the following code does @e not compile
+ @code
+ wxString s(...);
+ switch ( s[n] ) {
+ case 'A':
+ ...
+ break;
+ }
+ @endcode
+ and you need to use
+ @code
+ switch ( s[n].GetValue() ) {
+ ...
+ }
+ @endcode
+ instead. Alternatively, you can use an explicit cast:
+ @code
+ switch ( static_cast<char>(s[n]) ) {
+ ...
+ }
+ @endcode
+ but notice that this will result in an assert failure if the character at
+ the given position is not representable as a single @c char in the current
+ encoding, so you may want to cast to @c int instead if non-ASCII values can
+ be used.
+
+ Another consequence of this unusual return type arises when it is used with
+ template deduction or C++11 @c auto keyword. Unlike with the normal
+ references which are deduced to be of the referenced type, the deduced type
+ for wxUniCharRef is wxUniCharRef itself. This results in potentially
+ unexpected behaviour, for example:
+ @code
+ wxString s("abc");
+ auto c = s[0];
+ c = 'x'; // Modifies the string!
+ wxASSERT( s == "xbc" );
+ @endcode
+ Due to this, either explicitly specify the variable type:
+ @code
+ int c = s[0];
+ c = 'x'; // Doesn't modify the string any more.
+ wxASSERT( s == "abc" );
+ @endcode
+ or explicitly convert the return value:
+ @code
+ auto c = s[0].GetValue();
+ c = 'x'; // Doesn't modify the string neither.
+ wxASSERT( s == "abc" );
+ @endcode
- @li Trim()
- @li Truncate()
- @li Pad()
+ @subsection string_gotchas_conv Conversion to C string
- @section string_compat wxWidgets 1.xx compatibility functions
+ A different class of problems happens due to the dual nature of the return
+ value of wxString::c_str() method, which is also used for implicit
+ conversions. The result of calls to this method is convertible to either
+ narrow @c char* string or wide @c wchar_t* string and so, again, has
+ neither the former nor the latter type. Usually, the correct type will be
+ chosen depending on how you use the result but sometimes the compiler can't
+ choose it because of an ambiguity, e.g.:
+ @code
+ // Some non-wxWidgets functions existing for both narrow and wide
+ // strings:
+ void dump_text(const char* text); // Version (1)
+ void dump_text(const wchar_t* text); // Version (2)
+
+ wxString s(...);
+ dump_text(s); // ERROR: ambiguity.
+ dump_text(s.c_str()); // ERROR: still ambiguous.
+ @endcode
+ In this case you need to explicitly convert to the type that you need to
+ use or use a different, non-ambiguous, conversion function (which is
+ usually the best choice):
+ @code
+ dump_text(static_cast<const char*>(s)); // OK, calls (1)
+ dump_text(static_cast<const wchar_t*>(s.c_str())); // OK, calls (2)
+ dump_text(s.mb_str()); // OK, calls (1)
+ dump_text(s.wc_str()); // OK, calls (2)
+ dump_text(s.wx_str()); // OK, calls ???
+ @endcode
- The following functions are deprecated.
- Please consider using @c std::string compatible variants.
+ @subsection string_vararg Using wxString with vararg functions
- Contains(), First(), Freq(), IsAscii(), IsNull(), IsNumber(), IsWord(),
- Last(), Length(), LowerCase(), Remove(), Strip(), SubString(), UpperCase()
+ A special subclass of the problems arising due to the polymorphic nature of
+ wxString::c_str() result type happens when using functions taking an
+ arbitrary number of arguments, such as the standard @c printf(). Due to the
+ rules of the C++ language, the types for the "variable" arguments of such
+ functions are not specified and hence the compiler cannot convert wxString
+ objects, or the objects returned by wxString::c_str(), to these unknown
+ types automatically. Hence neither wxString objects nor the results of most
+ of the conversion functions can be passed as vararg arguments:
+ @code
+ // ALL EXAMPLES HERE DO NOT WORK, DO NOT USE THEM!
+ printf("Don't do this: %s", s);
+ printf("Don't do that: %s", s.c_str());
+ printf("Nor even this: %s", s.mb_str());
+ wprintf("And even not always this: %s", s.wc_str());
+ @endcode
+ Instead you need to either explicitly cast to the needed type:
+ @code
+ // These examples work but are not the best solution, see below.
+ printf("You can do this: %s", static_cast<const char*>(s));
+ printf("Or this: %s", static_cast<const char*>(s.c_str()));
+ printf("And this: %s", static_cast<const char*>(s.mb_str()));
+ wprintf("Or this: %s", static_cast<const wchar_t*>(s.wc_str()));
+ @endcode
+ But a better solution is to use wxWidgets-provided functions, if possible,
+ as is the case for @c printf family of functions:
+ @code
+ // This is the recommended way.
+ wxPrintf("You can do just this: %s", s);
+ wxPrintf("And this (but it is redundant): %s", s.c_str());
+ wxPrintf("And this (not using Unicode): %s", s.mb_str());
+ wxPrintf("And this (always Unicode): %s", s.wc_str());
+ @endcode
+ Notice that wxPrintf() replaces both @c printf() and @c wprintf() and
+ accepts wxString objects, results of c_str() calls but also @c char* and
+ @c wchar_t* strings directly.
+
+ wxWidgets provides wx-prefixed equivalents to all the standard vararg
+ functions and a few more, notably wxString::Format(), wxLogMessage(),
+ wxLogError() and other log functions. But if you can't use one of those
+ functions and need to pass wxString objects to non-wx vararg functions, you
+ need to use the explicit casts as explained above.
+
+
+ @section string_performance Performance characteristics
+
+ wxString uses @c std::basic_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::basic_string. In particular, most modern implementations of @c
+ std::basic_string are thread-safe and don't use reference counting (making
+ copying large strings potentially expensive) and so wxString has the same
+ characteristics.
+
+ By default, wxString uses @c std::basic_string specialized for the
+ platform-dependent @c wchar_t type, meaning that it is not memory-efficient
+ for ASCII strings, especially under Unix platforms where every ASCII
+ character, normally fitting in a byte, is represented by a 4 byte @c
+ wchar_t.
+
+ It is possible to build wxWidgets with @c wxUSE_UNICODE_UTF8 set to 1 in
+ which case an UTF-8-encoded string representation is stored in @c
+ std::basic_string specialized for @c char, i.e. the usual @c std::string.
+ In this case the memory efficiency problem mentioned above doesn't arise
+ but run-time performance of many wxString methods changes dramatically, in
+ particular accessing the N-th character of the string becomes an operation
+ taking O(N) time instead of O(1), i.e. constant, time by default. Thus, if
+ you do use this so called UTF-8 build, you should avoid using indices to
+ access the strings whenever possible and use the iterators instead. As an
+ example, traversing the string using iterators is an O(N), where N is the
+ string length, operation in both the normal ("wchar_t") and UTF-8 builds
+ but doing it using indices becomes O(N^2) in UTF-8 case meaning that simply
+ checking every character of a reasonably long (e.g. a couple of millions
+ elements) string can take an unreasonably long time.
+
+ However, if you do use iterators, UTF-8 build can be a better choice than
+ the default build, especially for the memory-constrained embedded systems.
+ Notice also that GTK+ and DirectFB use UTF-8 internally, so using this
+ build not only saves memory for ASCII strings but also avoids conversions
+ between wxWidgets and the underlying toolkit.
+
+
+ @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}
@stdobjects
::wxEmptyString
- @see @ref overview_string, @ref overview_unicode, wxUString
+ @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;
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
*/
/**
Creates a string from another string.
- Just increases the ref count by 1.
+ Just increases the ref count by 1.
*/
wxString(const wxString& stringSrc);
+ /**
+ Construct a string consisting of @a nRepeat copies of ch.
+ */
+ wxString(wxUniChar ch, size_t nRepeat = 1);
+
+ /**
+ Construct a string consisting of @a nRepeat copies of ch.
+ */
+ wxString(wxUniCharRef ch, size_t nRepeat = 1);
+
+ /**
+ Construct a string consisting of @a nRepeat copies of ch
+ converted to Unicode using the current locale encoding.
+ */
+ wxString(char ch, size_t nRepeat = 1);
+
+ /**
+ Construct a string consisting of @a nRepeat copies of ch.
+ */
+ wxString(wchar_t ch, size_t nRepeat = 1);
/**
- Constructs a string from the string literal @e psz using
+ Constructs a string from the string literal @a psz using
the current locale encoding to convert it to Unicode (wxConvLibc).
*/
wxString(const char *psz);
/**
- Constructs a string from the string literal @e psz using
- @e conv to convert it Unicode.
+ Constructs a string from the string literal @a psz using
+ @a conv to convert it Unicode.
*/
wxString(const char *psz, const wxMBConv& conv);
/**
- Constructs a string from the first @e nLength character of the string literal @e psz using
+ Constructs a string from the first @a nLength character of the string literal @a psz using
the current locale encoding to convert it to Unicode (wxConvLibc).
*/
wxString(const char *psz, size_t nLength);
/**
- Constructs a string from the first @e nLength character of the string literal @e psz using
- @e conv to convert it Unicode.
+ Constructs a string from the first @a nLength character of the string literal @a psz using
+ @a conv to convert it Unicode.
*/
wxString(const char *psz, const wxMBConv& conv, size_t nLength);
/**
- Constructs a string from the string literal @e pwz.
+ Constructs a string from the string literal @a pwz.
*/
wxString(const wchar_t *pwz);
/**
- Constructs a string from the first @e nLength characters of the string literal @e pwz.
+ Constructs a string from the first @a nLength characters of the string literal @a pwz.
*/
wxString(const wchar_t *pwz, size_t nLength);
/**
- Constructs a string from @e buf using the using the current locale
+ Constructs a string from @a buf using the using the current locale
encoding to convert it to Unicode.
*/
wxString(const wxCharBuffer& buf);
/**
- Constructs a string from @e buf.
+ Constructs a string from @a buf.
*/
wxString(const wxWCharBuffer& buf);
/**
- Constructs a string from @e str using the using the current locale encoding
+ Constructs a string from @a str using the using the current locale encoding
to convert it to Unicode (wxConvLibc).
+
+ @see ToStdString()
*/
wxString(const std::string& str);
/**
- Constructs a string from @e str.
+ Constructs a string from @a str.
+
+ @see ToStdWstring()
*/
wxString(const std::wstring& str);
-
/**
String destructor.
~wxString();
/**
- Gets all the characters after the first occurrence of @e ch.
- Returns the empty string if @e ch is not found.
+ Assignment: see the relative wxString constructor.
*/
- wxString AfterFirst(wxUniChar ch) const;
+ wxString operator =(const wxString& str);
/**
- Gets all the characters after the last occurrence of @e ch.
- Returns the whole string if @e ch is not found.
+ Assignment: see the relative wxString constructor.
*/
- wxString AfterLast(wxUniChar ch) const;
-
- /**
- Preallocate enough space for wxString to store @a nLen characters.
-
- Please note that this method does the same thing as the standard
- reserve() one and shouldn't be used in new code.
+ wxString operator =(wxUniChar c);
- This function may be used to increase speed when the string is
- constructed by repeated concatenation as in
+ //@}
- @code
- // delete all vowels from the string
- wxString DeleteAllVowels(const wxString& original)
- {
- wxString result;
- size_t len = original.length();
- result.Alloc(len);
+ /**
+ @member_group_name{length, String length}
- for ( size_t n = 0; n < len; n++ )
- {
- if ( strchr("aeuio", tolower(original[n])) == NULL )
- result += original[n];
- }
+ These functions return the string length and/or check whether the string
+ is empty.
- return result;
- }
- @endcode
+ See also the length(), size() or empty() STL-like functions.
+ */
+ //@{
- because it will avoid the need to reallocate string memory many times
- (in case of long strings). Note that it does not set the maximal length
- of a string -- it will still expand if more than @a nLen characters are
- stored in it. Also, it does not truncate the existing string (use
- Truncate() for this) even if its current length is greater than @a nLen.
- @return @true if memory was successfully allocated, @false otherwise.
+ /**
+ Returns the length of the string.
*/
- bool Alloc(size_t nLen);
+ size_t Len() const;
/**
- Appends the string literal @e psz.
+ Returns the length of the string (same as Len).
+ This is a wxWidgets 1.xx compatibility function; you should not use it in new
+ code.
*/
- wxString& Append(const char* psz);
+ size_t Length() const;
/**
- Appends the wide string literal @e pwz.
+ Returns @true if the string is empty.
*/
- wxString& Append(const wchar_t* pwz)
+ bool IsEmpty() const;
/**
- Appends the string literal @e psz with max length @e nLen.
+ Returns @true if the string is empty (same as wxString::IsEmpty).
+ This is a wxWidgets 1.xx compatibility function; you should not use it in new
+ code.
*/
- wxString& Append(const wchar_t* pwz);
+ bool IsNull() const;
/**
- Appends the wide string literal @e psz with max length @e nLen.
+ Empty string is @false, so !string will only return @true if the
+ string is empty.
+
+ @see IsEmpty().
*/
- wxString& Append(const wchar_t* pwz, size_t nLen)
+ bool operator!() const;
+
+ //@}
+
+
/**
- Appends the string @e s.
+ @member_group_name{ch_access, Character access}
+
+ Many functions below take a character index in the string.
+ As with C strings and arrays, the indices start from 0, so the first character
+ of a string is string[0]. An attempt to access a character beyond the end of the
+ string (which may even be 0 if the string is empty) will provoke an assert
+ failure in @ref overview_debugging "debug builds", but no checks are
+ done in release builds.
*/
- wxString& Append(const wchar_t* pwz, size_t nLen);
+ //@{
/**
- Appends the character @e ch @e count times.
+ Returns the character at position @a n (read-only).
*/
- wxString &Append(wxUniChar ch, size_t count = 1u);
+ wxUniChar GetChar(size_t n) const;
/**
- Gets all characters before the first occurrence of @e ch.
- Returns the whole string if @a ch is not found.
+ wxWidgets compatibility conversion. Same as c_str().
*/
- wxString BeforeFirst(wxUniChar ch) const;
+ const wxCStrData GetData() const;
/**
- Gets all characters before the last occurrence of @e ch.
- Returns the empty string if @a ch is not found.
+ Returns a reference to the character at position @a n.
*/
- wxString BeforeLast(wxUniChar ch) const;
+ wxUniCharRef GetWritableChar(size_t n);
/**
- Return the copy of the string with the first string character in the
- upper case and the subsequent ones in the lower case.
-
- @since 2.9.0
+ Returns a writable buffer of at least @a len bytes.
- @see MakeCapitalized()
- */
- wxString Capitalize() const;
+ It returns a pointer to a new memory block, and the existing data will not be copied.
+ Call UngetWriteBuf() as soon as possible to put the string back into a reasonable state.
- /**
- Empties the string and frees memory occupied by it.
- See also: Empty()
+ This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead.
*/
- void Clear();
+ wxStringCharType* GetWriteBuf(size_t len);
/**
- Returns a deep copy of the string.
+ Puts the string back into a reasonable state (in which it can be used
+ normally), after GetWriteBuf() was called.
- That is, the returned string is guaranteed to not share data with this
- string when using reference-counted wxString implementation.
+ 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 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.
+ This method is deprecated, please use wxStringBuffer or wxStringBufferLength instead.
+ */
+ void UngetWriteBuf();
- @since 2.9.0
- */
- wxString Clone() const;
+ /**
+ @overload
+ */
+ void UngetWriteBuf(size_t len);
/**
- 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).
+ Sets the character at position @e n.
+ */
+ void SetChar(size_t n, wxUniChar ch);
+
+ /**
+ Returns the last character.
- See also CmpNoCase(), IsSameAs().
+ This is a wxWidgets 1.xx compatibility function;
+ you should not use it in new code.
*/
- int Cmp(const wxString& s) const;
+ wxUniChar Last() 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).
+ Returns a reference to the last character (writable).
- See also Cmp(), IsSameAs().
+ This is a wxWidgets 1.xx compatibility function;
+ you should not use it in new code.
*/
- int CmpNoCase(const wxString& s) const;
+ wxUniCharRef Last();
+ /**
+ Returns the @a i-th character of the string.
+ */
+ wxUniChar operator [](size_t i) 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 a writable reference to the @a i-th character of the string.
+ */
+ wxUniCharRef operator [](size_t i);
+
//@}
/**
- 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.
+ @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.
*/
- bool Contains(const wxString& str) const;
+ //@{
+ /**
+ 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()
+ */
+ wxCStrData c_str() const;
/**
- Makes the string empty, but doesn't free memory occupied by the string.
- See also: 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.
+
+ @see c_str()
*/
- void Empty();
+ wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const;
/**
- This function can be used to test if the string ends with the specified
- @e suffix. If it does, the function will return @true and put the
- beginning of the string before the suffix into @e rest string if it is not
- @NULL. Otherwise, the function returns @false and doesn't
- modify the @e rest.
+ Returns buffer of the specified type containing the string data.
+
+ This method is only useful in template code, otherwise you should
+ directly call mb_str() or wc_str() if you need to retrieve a narrow or
+ wide string from this wxString. The template parameter @a t should be
+ either @c char or @c wchar_t.
+
+ Notice that retrieving a char buffer in UTF-8 build will return the
+ internal string representation in UTF-8 while in wchar_t build the char
+ buffer will contain the conversion of the string to the encoding of the
+ current locale (and so can fail).
+
+ @param len
+ If non-@NULL, filled with the length of the returned buffer.
+
+ @return
+ buffer containing the string contents in the specified type,
+ notice that it may be @NULL if the conversion failed (e.g. Unicode
+ string couldn't be converted to the current encoding when @a T is
+ @c char).
+ */
+ template <typename T>
+ wxCharTypeBuffer<T> tchar_str(size_t *len = NULL) const;
+
+ /**
+ Returns a string representation suitable for passing to OS' functions
+ for file handling.
*/
- bool EndsWith(const wxString& suffix, wxString *rest = NULL) const;
+ const wchar_t* fn_str() const;
/**
- Searches for the given character @e ch. Returns the position or
- @c wxNOT_FOUND if not found.
+ @overload
*/
- int Find(wxUniChar ch, bool fromEnd = false) const;
+ const char* fn_str() const;
/**
- Searches for the given string @e sub. Returns the starting position or
- @c wxNOT_FOUND if not found.
+ @overload
*/
- int Find(const wxString& sub) const;
+ const wxCharBuffer fn_str() const;
- //@{
/**
- Same as Find().
- This is a wxWidgets 1.xx compatibility function;
- you should not use it in new code.
+ 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
*/
- int First(wxUniChar ch) const;
- int First(const wxString& str) const;
- //@}
+ const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const;
/**
- This static function returns the string containing the result of calling
- Printf() with the passed parameters on it.
+ 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 FormatV(), Printf()
+ @see wc_str(), c_str(), mb_str()
*/
- static wxString Format(const wxChar format, ...);
+ const wxScopedCharBuffer utf8_str() const;
/**
- This static function returns the string containing the result of calling
- PrintfV() with the passed parameters on it.
+ Converts the strings contents to the wide character representation
+ and returns it as a temporary wxWCharBuffer object (Unix and OS X)
+ or returns a pointer to the internal string contents in wide character
+ mode (Windows).
- @see Format(), PrintfV()
+ The macro wxWX2WCbuf is defined as the correct return type (without const).
+
+ @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str()
*/
- static wxString FormatV(const wxChar format, va_list argptr);
+ const wchar_t* wc_str() const;
/**
- Returns the number of occurrences of @e ch in the string.
- This is a wxWidgets 1.xx compatibility function; you should not
- use it in new code.
+ @overload
*/
- int Freq(wxUniChar ch) const;
+ const wxWCharBuffer wc_str() 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 an object with string data that is implicitly convertible to
+ @c char* pointer. Note that changes to the returned buffer may or may
+ not be lost (depending on the build) and so this function is only usable for
+ passing strings to legacy libraries that don't have const-correct API. Use
+ wxStringBuffer if you want to modify the string.
+
+ @see mb_str(), wc_str(), fn_str(), c_str(), char_str()
+ */
+ wxWritableWCharBuffer wchar_str() const;
+
+ /**
+ Explicit conversion to C string in the internal representation (either
+ wchar_t* or UTF-8-encoded char*, depending on the build).
+ */
+ const wxStringCharType *wx_str() const;
+
+ /**
+ Converts the string to an 8-bit string in ISO-8859-1 encoding in the
+ form of a wxCharBuffer (Unicode builds only).
This is a convenience method useful when storing binary data in
- wxString. It should be used @em only for that purpose and only in
- conjunction with To8BitData(). Use mb_str() for conversion of character
- data to known encoding.
+ wxString. It should be used @em only for this purpose. It is only valid
+ to call this method on strings created using From8BitData().
@since 2.8.4
- @see wxString::To8BitData()
+ @see wxString::From8BitData()
*/
- static wxString From8BitData(const char* buf, size_t len);
- static wxString From8BitData(const char* buf);
- //@}
+ const wxScopedCharBuffer To8BitData() const;
- //@{
/**
- Converts the string or character from an ASCII, 7-bit form
- to the native wxString representation.
+ Converts the string to an ASCII, 7-bit string in the form of
+ a wxCharBuffer (Unicode builds only) or a C string (ANSI builds).
+
+ Note that this conversion is only lossless if the string contains only
+ ASCII characters as all the non-ASCII ones are replaced with the @c '_'
+ (underscore) character.
+
+ Use mb_str() or utf8_str() to convert to other encodings.
*/
- static wxString FromAscii(const char* s);
- static wxString FromAscii(const unsigned char* s);
- static wxString FromAscii(const char* s, size_t len);
- static wxString FromAscii(const unsigned char* s, size_t len);
- static wxString FromAscii(char c);
- //@}
+ const char* ToAscii() const;
- //@{
/**
- Converts C string encoded in UTF-8 to wxString.
+ @overload
+ */
+ const wxCharBuffer ToAscii() const;
- If @a s is not a valid UTF-8 string, an empty string is returned.
+ /**
+ Return the string as an std::string in current locale encoding.
- 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.
+ Note that if the conversion of (Unicode) string contents to the current
+ locale fails, the return string will be empty. Be sure to check for
+ this to avoid silent data loss.
- @since 2.8.4
+ Instead of using this function it's also possible to write
+ @code
+ std::string s;
+ wxString wxs;
+ ...
+ s = std::string(wxs);
+ @endcode
+ but using ToStdString() may make the code more clear.
+
+ @since 2.9.1
*/
- static wxString FromUTF8(const char* s);
- static wxString FromUTF8(const char* s, size_t len);
+ std::string ToStdString() const;
+
+ /**
+ Return the string as an std::wstring.
+
+ Unlike ToStdString(), there is no danger of data loss when using this
+ function.
+
+ @since 2.9.1
+ */
+ std::wstring ToStdWstring() const;
+
+ /**
+ Same as utf8_str().
+ */
+ const wxScopedCharBuffer ToUTF8() const;
+
//@}
+
+ /**
+ @member_group_name{concat, Concatenation}
+
+ Almost anything may be concatenated (appended to) with a string!
+
+ Note that the various operator<<() overloads work as C++ stream insertion
+ operators. They insert the given value into the string.
+ Precision and format cannot be set using them. Use Printf() instead.
+
+ See also the insert() and append() STL-like functions.
+ */
//@{
+
/**
- Converts C string encoded in UTF-8 to wxString without checking its
- validity.
+ Appends the string literal @a psz.
+ */
+ wxString& Append(const char* psz);
- 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.
+ /**
+ Appends the wide string literal @a pwz.
+ */
+ wxString& Append(const wchar_t* pwz);
- @since 2.8.9
+ /**
+ Appends the string literal @a psz with max length @a nLen.
*/
- static wxString FromUTF8Unchecked(const char* s);
- static wxString FromUTF8Unchecked(const char* s, size_t len);
- //@}
+ wxString& Append(const char* psz, size_t nLen);
/**
- Returns the character at position @a n (read-only).
+ Appends the wide string literal @a psz with max length @a nLen.
*/
- wxUniChar GetChar(size_t n) const;
+ wxString& Append(const wchar_t* pwz, size_t nLen);
/**
- wxWidgets compatibility conversion. Same as c_str().
+ Appends the string @a s.
*/
- const wxCStrData GetData() const;
+ wxString& Append(const wxString& s);
/**
- Returns a reference to the character at position @e n.
+ Appends the character @a ch @a count times.
*/
- wxUniCharRef GetWritableChar(size_t n);
+ wxString &Append(wxUniChar ch, size_t count = 1u);
/**
- 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.
+ Prepends @a str to this string, returning a reference to this string.
*/
- wxStringCharType* GetWriteBuf(size_t len);
+ wxString& Prepend(const wxString& str);
/**
- Returns @true if the string contains only ASCII characters.
- This is a wxWidgets 1.xx compatibility function; you should not use it in new
- code.
+ Concatenation: returns a new string equal to the concatenation of the operands.
*/
- bool IsAscii() const;
+ wxString operator +(const wxString& x, const wxString& y);
/**
- Returns @true if the string is empty.
+ @overload
*/
- bool IsEmpty() const;
+ wxString operator +(const wxString& x, wxUniChar y);
+
+ wxString& operator<<(const wxString& s);
+ wxString& operator<<(const char* psz);
+ wxString& operator<<(const wchar_t* pwz);
+ wxString& operator<<(const wxCStrData& psz);
+ wxString& operator<<(char ch);
+ wxString& operator<<(unsigned char ch);
+ wxString& operator<<(wchar_t ch);
+ wxString& operator<<(const wxCharBuffer& s);
+ wxString& operator<<(const wxWCharBuffer& s);
+ wxString& operator<<(wxUniChar ch);
+ wxString& operator<<(wxUniCharRef ch);
+ wxString& operator<<(unsigned int ui);
+ wxString& operator<<(long l);
+ wxString& operator<<(unsigned long ul);
+ wxString& operator<<(wxLongLong_t ll);
+ wxString& operator<<(wxULongLong_t ul);
+ wxString& operator<<(float f);
+ wxString& operator<<(double d);
/**
- 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.
+ Concatenation in place: the argument is appended to the string.
*/
- bool IsNull() const;
+ void operator +=(const wxString& str);
/**
- 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.
+ @overload
*/
- bool IsNumber() const;
+ void operator +=(wxUniChar c);
+
+ //@}
+
+
+ /**
+ @member_group_name{cmp, Comparison}
+ The default comparison function Cmp() is case-sensitive and so is the default
+ version of IsSameAs(). For case insensitive comparisons you should use CmpNoCase()
+ or give a second parameter to IsSameAs(). This last function is maybe more
+ convenient if only equality of the strings matters because it returns a boolean
+ @true value if the strings are the same and not 0 (which is usually @false
+ in C) as Cmp() does.
+
+ Matches() is a poor man's regular expression matcher: it only understands
+ '*' and '?' metacharacters in the sense of DOS command line interpreter.
+
+ StartsWith() is helpful when parsing a line of text which should start
+ with some predefined prefix and is more efficient than doing direct string
+ comparison as you would also have to precalculate the length of the prefix.
+
+ See also the compare() STL-like function.
+ */
//@{
+
/**
- 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
+ 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 another string @a s.
+
+ 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 also Cmp(), CmpNoCase()
+
+ @return @true if the string is equal to the other one, @false otherwise.
+
+ @see Cmp(), CmpNoCase()
+ */
+ bool IsSameAs(const wxString& s, bool caseSensitive = true) const;
+
+ /**
+ Test whether the string is equal to the single character @a ch.
+
+ The test is case-sensitive if @a caseSensitive is @true (default) or not if it is
+ @false.
+
+ @return @true if the string is equal to this character, @false otherwise.
+
+ @see Cmp(), CmpNoCase()
*/
- bool IsSameAs(const wxString &s, bool caseSensitive = true) const;
bool IsSameAs(wxUniChar ch, bool caseSensitive = true) 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 @true if the string contents matches a mask containing '*' and '?'.
*/
- bool IsWord() const;
+ bool Matches(const wxString& mask) 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.
+ This function can be used to test if the string starts with the specified
+ @a prefix.
+
+ If it does, the function will return @true and put the rest of the string
+ (i.e. after the prefix) into @a rest string if it is not @NULL.
+ Otherwise, the function returns @false and doesn't modify the @a rest.
*/
- wxUniCharRef Last();
- const wxUniChar Last();
+ bool StartsWith(const wxString& prefix, wxString *rest = NULL) const;
+
+ /**
+ This function can be used to test if the string ends with the specified
+ @e suffix. If it does, the function will return @true and put the
+ beginning of the string before the suffix into @e rest string if it is not
+ @NULL. Otherwise, the function returns @false and doesn't
+ modify the @e rest.
+ */
+ bool EndsWith(const wxString& suffix, wxString *rest = NULL) const;
+
//@}
+
+ /**
+ @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 @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 length of the string.
+ Returns the last @a count characters.
*/
- size_t Len() const;
+ wxString Right(size_t count) 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.
+ Gets all the characters after the first occurrence of @e ch.
+ Returns the empty string if @e ch is not found.
*/
- size_t Length() const;
+ 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.
+
+ @param ch The character to look for.
+ @param rest Filled with the part of the string following the first
+ occurrence of @a ch or cleared if it was not found. The same string
+ is returned by AfterFirst() but it is more efficient to use this
+ output parameter if both the "before" and "after" parts are needed
+ than calling both functions one after the other. This parameter is
+ available in wxWidgets version 2.9.2 and later only.
+ @return Part of the string before the first occurrence of @a ch.
+ */
+ wxString BeforeFirst(wxUniChar ch, wxString *rest = NULL) const;
+
+ /**
+ Gets all characters before the last occurrence of @e ch.
+ Returns the empty string if @a ch is not found.
+
+ @param ch The character to look for.
+ @param rest Filled with the part of the string following the last
+ occurrence of @a ch or the copy of this string if it was not found.
+ The same string is returned by AfterLast() but it is more efficient
+ to use this output parameter if both the "before" and "after" parts
+ are needed than calling both functions one after the other. This
+ parameter is available in wxWidgets version 2.9.2 and later only.
+ @return Part of the string before the last occurrence of @a ch.
+ */
+ wxString BeforeLast(wxUniChar ch, wxString *rest = NULL) const;
+
+ //@}
+
+
+ /**
+ @member_group_name{caseconv, Case conversion}
+
+ The MakeXXX() variants modify the string in place, while the other functions
+ return a new string which contains the original text converted to the upper or
+ lower case and leave the original string unchanged.
+ */
+ //@{
+
+ /**
+ Return the copy of the string with the first string character in the
+ upper case and the subsequent ones in the lower case.
+
+ @since 2.9.0
+
+ @see MakeCapitalized()
+ */
+ wxString Capitalize() const;
/**
Returns this string converted to the lower case.
wxString& MakeUpper();
/**
- Returns @true if the string contents matches a mask containing '*' and '?'.
- */
- 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.
- */
- 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 chPad = ' ', bool fromRight = true);
-
- /**
- Prepends @a str to this string, returning a reference to this string.
- */
- wxString& Prepend(const wxString& str);
-
- /**
- 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.
- */
- int Printf(const wxString& pszFormat, ...);
+ Returns this string converted to upper case.
- /**
- Similar to vprintf. Returns the number of characters written, or an integer
- less than zero
- on error.
+ @see MakeUpper()
*/
- int PrintfV(const wxString& pszFormat, va_list argPtr);
+ wxString Upper() const;
- //@{
/**
- Removes @a len characters from the string, starting at @e pos.
+ The same as MakeUpper().
+
This is a wxWidgets 1.xx compatibility function; you should not use it in new
code.
*/
- wxString Remove(size_t pos);
- wxString Remove(size_t pos, size_t len);
+ void UpperCase();
+
//@}
- /**
- Removes the last character.
- */
- wxString& RemoveLast(size_t n = 1);
/**
- Replace first (or all) occurrences of substring with another one.
- @e replaceAll: global replace (default), or only the first occurrence.
- Returns the number of replacements made.
+ @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.
*/
- size_t Replace(const wxString& strOld, const wxString& strNew,
- bool replaceAll = true);
+ //@{
/**
- Returns the last @a count characters.
+ Searches for the given character @a ch.
+ Returns the position or @c wxNOT_FOUND if not found.
*/
- wxString Right(size_t count) const;
+ int Find(wxUniChar ch, bool fromEnd = false) const;
/**
- Sets the character at position @e n.
+ Searches for the given string @a sub.
+ Returns the starting position or @c wxNOT_FOUND if not found.
*/
- void SetChar(size_t n, wxUniChar ch);
+ int Find(const wxString& sub) const;
/**
- Minimizes the string's memory. This can be useful after a call to
- Alloc() if too much memory were preallocated.
+ Same as Find().
+
+ This is a wxWidgets 1.xx compatibility function;
+ you should not use it in new code.
*/
- bool Shrink();
+ int First(wxUniChar ch) 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.
+ Same as Find().
+
+ This is a wxWidgets 1.xx compatibility function;
+ you should not use it in new code.
*/
- bool StartsWith(const wxString& prefix, wxString *rest = NULL) const;
+ int First(const wxString& str) 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.
+ Replace first (or all) occurrences of substring with another one.
+
+ @param strOld
+ The string to search for replacing.
+ @param strNew
+ The substitution string.
+ @param replaceAll
+ If @true a global replace will be done (default), otherwise only the
+ first occurrence will be replaced.
+
+ Returns the number of replacements made.
*/
- wxString Strip(stripType s = trailing) const;
+ size_t Replace(const wxString& strOld, const wxString& strNew,
+ bool replaceAll = true);
+
+ //@}
+
+
/**
- Returns the part of the string between the indices @a from and @e to
- inclusive.
- This is a wxWidgets 1.xx compatibility function, use Mid()
- instead (but note that parameters have different meaning).
- */
- wxString SubString(size_t from, size_t to) const;
+ @member_group_name{numconv, Conversion to numbers}
+ The string provides functions for conversion to signed and unsigned integer and
+ floating point numbers.
+
+ All functions take a pointer to the variable to put the numeric value
+ in and return @true if the @b entire string could be converted to a
+ number. Notice if there is a valid number in the beginning of the
+ string, it is returned in the output parameter even if the function
+ returns @false because there is more text following it.
+ */
//@{
+
/**
- Converts the string to an 8-bit string in ISO-8859-1 encoding in the
- form of a wxCharBuffer (Unicode builds only).
+ Attempts to convert the string to a floating point number.
- 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().
+ Returns @true on success (the number is stored in the location pointed to by
+ @a val) or @false if the string does not represent such number (the value of
+ @a val may still be modified in this case).
- @since 2.8.4
+ Note that unlike ToCDouble() this function uses a localized version of
+ @c wxStrtod() and thus needs as decimal point (and thousands separator) the
+ locale-specific decimal point. Thus you should use this function only when
+ you are sure that this string contains a floating point number formatted with
+ the rules of the locale currently in use (see wxLocale).
- @see wxString::From8BitData()
- */
- const char* To8BitData() const;
- const wxCharBuffer To8BitData() const;
- //@}
+ Also notice that even this function is locale-specific it does not
+ support strings with thousands separators in them, even if the current
+ locale uses digits grouping. You may use wxNumberFormatter::FromString()
+ to parse such strings.
- //@{
- /**
- 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.
+ Please refer to the documentation of the standard function @c strtod()
+ for more details about the supported syntax.
+
+ @see ToCDouble(), ToLong(), ToULong()
*/
- const char* ToAscii() const;
- const wxCharBuffer ToAscii() const;
- //@}
+ bool ToDouble(double* val) const;
/**
- Attempts to convert the string to a floating point number. Returns @true on
- success (the number is stored in the location pointed to by @e val) or @false
- if the string does not represent such number (the value of @a val is not
- modified in this case).
+ Variant of ToDouble() always working in "C" locale.
- @see ToLong(), ToULong()
+ Works like ToDouble() but unlike it this function expects the floating point
+ number to be formatted always with the rules dictated by the "C" locale
+ (in particular, the decimal point must be a dot), independently from the
+ current application-wide locale (see wxLocale).
+
+ @see ToDouble(), ToLong(), ToULong()
*/
- bool ToDouble(double* val) const;
+ bool ToCDouble(double* val) const;
/**
- Attempts to convert the string to a signed integer in base @e base. Returns
- @true on success in which case the number is stored in the location
+ Attempts to convert the string to a signed integer in base @a base.
+
+ Returns @true on success in which case the number is stored in the location
pointed to by @a val or @false if the string does not represent a
- valid number in the given base (the value of @a val is not modified
- in this case).
+ valid number in the given base (the value of @a val may still be
+ modified in this case).
+
The value of @a base must be comprised between 2 and 36, inclusive, or
be a special value 0 which means that the usual rules of @c C numbers are
applied: if the number starts with @c 0x it is considered to be in base
which may have leading zeroes as they can yield unexpected (to the user not
familiar with C) results.
- @see ToDouble(), ToULong()
+ Note that unlike ToCLong() this function uses a localized version of
+ @c wxStrtol(). Thus you should use this function only when you are sure
+ that this string contains an integer number formatted with
+ the rules of the locale currently in use (see wxLocale).
+
+ As with ToDouble(), this function does not support strings containing
+ thousands separators even if the current locale uses digits grouping.
+ You may use wxNumberFormatter::FromString() to parse such strings.
+
+ Please refer to the documentation of the standard function @c strtol()
+ for more details about the supported syntax.
+
+ @see ToCDouble(), ToDouble(), ToULong()
*/
bool ToLong(long* val, int base = 10) const;
/**
- This is exactly the same as ToLong() but works with 64
- bit integer numbers.
+ Variant of ToLong() always working in "C" locale.
+
+ Works like ToLong() but unlike it this function expects the integer
+ number to be formatted always with the rules dictated by the "C" locale,
+ independently from the current application-wide locale (see wxLocale).
+
+ @see ToDouble(), ToLong(), ToULong()
+ */
+ bool ToCLong(long* val, int base = 10) const;
+
+ /**
+ This is exactly the same as ToLong() but works with 64 bit integer numbers.
+
Notice that currently it doesn't work (always returns @false) if parsing of 64
bit numbers is not supported by the underlying C run-time library. Compilers
with C99 support and Microsoft Visual C++ version 7 and higher do support this.
bool ToLongLong(wxLongLong_t* val, int base = 10) const;
/**
- Attempts to convert the string to an unsigned integer in base @e base.
+ Attempts to convert the string to an unsigned integer in base @a base.
+
Returns @true on success in which case the number is stored in the
location pointed to by @a val or @false if the string does not
- represent a valid number in the given base (the value of @a val is not
- modified in this case).
+ represent a valid number in the given base (the value of @a val may
+ still be modified in this case).
Please notice that this function behaves in the same way as the standard
@c strtoul() and so it simply converts negative numbers to unsigned
representation instead of rejecting them (e.g. -1 is returned as @c ULONG_MAX).
- See ToLong() for the more detailed description of the @a base parameter.
+ See ToLong() for the more detailed description of the @a base parameter
+ (and of the locale-specific behaviour of this function).
- @see ToDouble(), ToLong()
+ @see ToCULong(), ToDouble(), ToLong()
*/
bool ToULong(unsigned long* val, int base = 10) const;
/**
- This is exactly the same as ToULong() but works with 64
- bit integer numbers.
+ Variant of ToULong() always working in "C" locale.
+
+ Works like ToULong() but unlike it this function expects the integer
+ number to be formatted always with the rules dictated by the "C" locale,
+ independently from the current application-wide locale (see wxLocale).
+
+ @see ToDouble(), ToLong(), ToULong()
+ */
+ bool ToCULong(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;
+ //@}
+
+
+ /**
+ @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.
+ */
//@{
+
/**
- Same as utf8_str().
+ 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:
+
+ @code
+ wxString str;
+
+ str.Printf(wxT("%d %d %d"), 1, 2, 3);
+ // str now contains "1 2 3"
+
+ str.Printf(wxT("%2$d %3$d %1$d"), 1, 2, 3);
+ // str now contains "2 3 1"
+ @endcode
+
+ @note This function will use a safe version of @e vsprintf() (usually called
+ @e vsnprintf()) whenever available to always allocate the buffer of correct
+ size. Unfortunately, this function is not available on all platforms and the
+ dangerous @e vsprintf() will be used then which may lead to buffer overflows.
+ */
+ int Printf(const wxString& pszFormat, ...);
+
+ /**
+ Similar to vprintf. Returns the number of characters written, or an integer
+ less than zero
+ on error.
*/
- const char* ToUTF8() const;
- const wxCharBuffer ToUTF8() const;
+ int PrintfV(const wxString& pszFormat, va_list argPtr);
+
//@}
+
/**
- 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).
+ @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.
*/
- wxString& Trim(bool fromRight = true);
+ //@{
/**
- Truncate the string to the given length.
+ Preallocate enough space for wxString to store @a nLen characters.
+
+ Please note that this method does the same thing as the standard
+ reserve() one and shouldn't be used in new code.
+
+ This function may be used to increase speed when the string is
+ constructed by repeated concatenation as in
+
+ @code
+ // delete all vowels from the string
+ wxString DeleteAllVowels(const wxString& original)
+ {
+ wxString result;
+
+ size_t len = original.length();
+
+ result.Alloc(len);
+
+ for ( size_t n = 0; n < len; n++ )
+ {
+ if ( strchr("aeuio", tolower(original[n])) == NULL )
+ result += original[n];
+ }
+
+ return result;
+ }
+ @endcode
+
+ because it will avoid the need to reallocate string memory many times
+ (in case of long strings). Note that it does not set the maximal length
+ of a string -- it will still expand if more than @a nLen characters are
+ stored in it. Also, it does not truncate the existing string (use
+ Truncate() for this) even if its current length is greater than @a nLen.
+
+ @return @true if memory was successfully allocated, @false otherwise.
*/
- wxString& Truncate(size_t len);
+ bool Alloc(size_t nLen);
- //@{
/**
- Puts the string back into a reasonable state (in which it can be used
- normally), after GetWriteBuf() was called.
+ Minimizes the string's memory. This can be useful after a call to
+ Alloc() if too much memory were preallocated.
+ */
+ bool Shrink();
- 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).
+ /**
+ 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;
+
+ /**
+ Empties the string and frees memory occupied by it.
- This method is deprecated, please use wxStringBuffer or
- wxStringBufferLength instead.
+ @see Empty()
*/
- void UngetWriteBuf();
- void UngetWriteBuf(size_t len);
+ void Clear();
+
//@}
+
+
/**
- Returns this string converted to upper case.
+ @member_group_name{misc, Miscellaneous}
- @see MakeUpper()
+ Miscellaneous other string functions.
*/
- wxString Upper() const;
+ //@{
/**
- The same as MakeUpper().
+ 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.
+ This is a wxWidgets 1.xx compatibility function; you should not use it in new code.
*/
- void UpperCase();
+ bool Contains(const wxString& str) const;
/**
- 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.
+ Makes the string empty, but doesn't free memory occupied by the string.
- Please see the @ref overview_unicode for more information about it.
+ @see Clear().
+ */
+ void Empty();
- 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.
+ /**
+ Returns the number of occurrences of @e ch in the string.
- @see wc_str(), utf8_str(), c_str(), mb_str(), fn_str()
+ This is a wxWidgets 1.xx compatibility function; you should not use it in new code.
*/
- wxCStrData c_str() const;
+ int Freq(wxUniChar ch) const;
/**
- Returns an object with string data that is implicitly convertible to
- @c char* pointer. Note that any change to the returned buffer is lost and so
- this function is only usable for passing strings to legacy libraries that
- don't have const-correct API. Use wxStringBuffer if you want to modify
- the string.
+ Returns @true if the string contains only ASCII characters.
+ See wxUniChar::IsAscii for more details.
- @see c_str()
+ This is a wxWidgets 1.xx compatibility function; you should not use it in new
+ code.
*/
- wxWritableCharBuffer char_str(const wxMBConv& conv = wxConvLibc) const;
+ bool IsAscii() const;
/**
- Returns buffer of the specified type containing the string data.
+ 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.
+ */
+ bool IsNumber() 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.
+ /**
+ Returns @true if the string is a word.
- 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 is a wxWidgets 1.xx compatibility function; you should not use it in new code.
+ */
+ bool IsWord() const;
- @param len
- If non-@NULL, filled with the length of the returned buffer.
+ /**
+ Adds @a count copies of @a chPad to the beginning, or to the end of the
+ string (the default).
- @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 <typename T>
- wxCharTypeBuffer<T> tchar_str(size_t *len = NULL) const;
+ Removes spaces from the left or from the right (default).
+ */
+ wxString& Pad(size_t count, wxUniChar chPad = ' ', bool fromRight = true);
- //@{
/**
- Returns string representation suitable for passing to OS' functions
- for file handling.
+ 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.
*/
- const wchar_t* fn_str() const;
- const char* fn_str() const;
- const wxCharBuffer fn_str() const;
- //@}
+ wxString& Remove(size_t pos);
/**
- Returns the multibyte (C string) representation of the string
- using @e conv's wxMBConv::cWC2MB method and returns wxCharBuffer.
+ Removes @a len characters from the string, starting at @a pos.
- @see wc_str(), utf8_str(), c_str(), wxMBConv
+ This is a wxWidgets 1.xx compatibility function; you should not use it in new code.
*/
- const wxCharBuffer mb_str(const wxMBConv& conv = wxConvLibc) const;
+ 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<<(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<<(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 beginning 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 @ref wxString() "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 separated 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, ...);
+
+ /**
+ This static function returns the string containing the result of calling
+ PrintfV() with the passed parameters on it.
+ @see Format(), PrintfV()
+ */
+ static wxString FormatV(const wxString& format, va_list argptr);
//@{
/**
- 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.
+ 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.
- @see wc_str(), c_str(), mb_str()
+ 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.
+
+ @since 2.8.4
+
+ @see wxString::To8BitData()
*/
- const char* utf8_str() const;
- const wxCharBuffer utf8_str() const;
+ static wxString From8BitData(const char* buf, size_t len);
+ static wxString From8BitData(const char* buf);
//@}
//@{
/**
- 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).
-
- The macro wxWX2WCbuf is defined as the correct return
- type (without const).
-
- @see utf8_str(), c_str(), mb_str(), fn_str(), wchar_str()
+ Converts the string or character from an ASCII, 7-bit form
+ to the native wxString representation.
*/
- const wchar_t* wc_str() const;
- const wxWCharBuffer wc_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);
//@}
/**
- 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.
+ Returns a string with the textual representation of the number in C
+ locale.
- @see mb_str(), wc_str(), fn_str(), c_str(), char_str()
- */
- wxWritableWCharBuffer wchar_str() const;
+ Unlike FromDouble() the string returned by this function always uses
+ the period character as decimal separator, independently of the current
+ locale. Otherwise its behaviour is identical to the other function.
+
+ @since 2.9.1
+
+ @see ToCDouble()
+ */
+ static wxString FromCDouble(double val, int precision = -1);
/**
- Explicit conversion to C string in the internal representation (either
- wchar_t* or UTF-8-encoded char*, depending on the build).
- */
- const wxStringCharType *wx_str() const;
+ Returns a string with the textual representation of the number.
+
+ For the default value of @a precision, this function behaves as a
+ simple wrapper for @code wxString::Format("%g", val) @endcode. If @a
+ precision is positive (or zero), the @c %.Nf format is used with the
+ given precision value.
+
+ Notice that the string returned by this function uses the decimal
+ separator appropriate for the current locale, e.g. @c "," and not a
+ period in French locale. Use FromCDouble() if this is unwanted.
+ @param val
+ The value to format.
+ @param precision
+ The number of fractional digits to use in or -1 to use the most
+ appropriate format. This parameter is new in wxWidgets 2.9.2.
+ @since 2.9.1
+
+ @see ToDouble()
+ */
+ static wxString FromDouble(double val, int precision = -1);
+
+ //@{
/**
- @name Iterator interface
+ 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.
- 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.
- */
- //@{
- 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& 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);
-
- void clear();
-
- 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;
-
- 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;
-
- 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);
-
- 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;
-
- wxString substr(size_t nStart = 0, size_t nLen = npos) const;
-
- void swap(wxString& str);
+ 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);
//@}
-
};
+
+
+//@{
+/**
+ 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
@code
wxString theAnswer;
- wxStringBuffer theAnswerBuffer(theAnswer, 1024);
+ wxStringBufferLength theAnswerBuffer(theAnswer, 1024);
int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
theAnswerBuffer.SetLength(nLength);
if ( theAnswer != "42" )
wxLogError("Something is very wrong!");
@endcode
- @todo
- the example above does not make use of wxStringBufferLength??
-
Note that the exact usage of this depends on whether or not wxUSE_STL is
enabled. If wxUSE_STL is enabled, wxStringBuffer creates a separate empty
character buffer, and if wxUSE_STL is disabled, it uses GetWriteBuf() from
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 only 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