b59893f3ef
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@10641 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
1107 lines
36 KiB
TeX
1107 lines
36 KiB
TeX
\section{\class{wxString}}\label{wxstring}
|
|
|
|
wxString is a class representing a character string. Please see the
|
|
\helpref{wxString overview}{wxstringoverview} for more information about it. As explained
|
|
there, wxString implements about 90\% of methods of the std::string class (iterators
|
|
are not supported, nor all methods which use them).
|
|
These standard functions are not documented in this manual so please see the STL documentation.
|
|
The behaviour of all these functions is identical to the behaviour described
|
|
there.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
None
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/string.h>
|
|
|
|
\wxheading{Predefined objects}
|
|
|
|
Objects:
|
|
|
|
{\bf wxEmptyString}
|
|
|
|
\wxheading{See also}
|
|
|
|
\overview{Overview}{wxstringoverview}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Function groups}}}
|
|
|
|
\membersection{Constructors and assignment operators}
|
|
|
|
A strign 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.
|
|
|
|
\helpref{wxString}{wxstringconstruct}\\
|
|
\helpref{operator $=$}{wxstringoperatorassign}\\
|
|
\helpref{\destruct{wxString}}{wxstringdestruct}
|
|
|
|
\membersection{String length}
|
|
|
|
These functions return the string length and check whether the string is empty
|
|
or empty it.
|
|
|
|
\helpref{Len}{wxstringlen}\\
|
|
\helpref{IsEmpty}{wxstringisempty}\\
|
|
\helpref{operator!}{wxstringoperatornot}\\
|
|
\helpref{Empty}{wxstringempty}\\
|
|
\helpref{Clear}{wxstringclear}
|
|
|
|
\membersection{Character access}
|
|
|
|
Many functions in this section take a character index in the string. As with C
|
|
strings and/or arrays, the indices start from $0$, so the first character of a
|
|
string is string[$0$]. Attempt to access a character beyond the end of the
|
|
string (which may be even $0$ if the string is empty) will provocate an assert
|
|
failure in \helpref{debug build}{debuggingoverview}, but no checks are done in
|
|
release builds.
|
|
|
|
This section also contains both implicit and explicit conversions to C style
|
|
strings. Although implicit conversion is quite convenient, it is advised to use
|
|
explicit \helpref{c\_str()}{wxstringcstr} method for the sake of clarity. Also
|
|
see \helpref{overview}{wxstringadvices} for the cases where it is necessary to
|
|
use it.
|
|
|
|
\helpref{GetChar}{wxstringgetchar}\\
|
|
\helpref{GetWritableChar}{wxstringgetwritablechar}\\
|
|
\helpref{SetChar}{wxstringsetchar}\\
|
|
\helpref{Last}{wxstringlast}\\
|
|
\helpref{operator []}{wxstringoperatorbracket}\\
|
|
\helpref{c\_str}{wxstringcstr}\\
|
|
\helpref{operator const char*}{wxstringoperatorconstcharpt}
|
|
|
|
\membersection{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.
|
|
|
|
\helpref{operator \cinsert}{wxstringoperatorout}\\
|
|
\helpref{operator $+=$}{wxstringplusequal}\\
|
|
\helpref{operator $+$}{wxstringoperatorplus}\\
|
|
\helpref{Append}{wxstringappend}\\
|
|
\helpref{Prepend}{wxstringprepend}
|
|
|
|
\membersection{Comparison}
|
|
|
|
The default comparison function \helpref{Cmp}{wxstringcmp} is case-sensitive and
|
|
so is the default version of \helpref{IsSameAs}{wxstringissameas}. For case
|
|
insensitive comparisons you should use \helpref{CmpNoCase}{wxstringcmpnocase} or
|
|
give a second parameter to IsSameAs. This last function is may be more
|
|
convenient if only equality of the strings matters because it returns a boolean
|
|
true value if the strings are the same and not 0 (which is usually FALSE in C)
|
|
as {\tt Cmp()} does.
|
|
|
|
\helpref{Matches}{wxstringmatches} is a poor man's regular expression matcher:
|
|
it only understands '*' and '?' metacharacters in the sense of DOS command line
|
|
interpreter.
|
|
|
|
\helpref{StartsWith}{wxstringstartswith} is helpful when parsing a line of
|
|
text which should start with some predefined prefix and is more efficient than
|
|
doing direct string comparaison as you would also have to precalculate the
|
|
length of the prefix then.
|
|
|
|
\helpref{Cmp}{wxstringcmp}\\
|
|
\helpref{CmpNoCase}{wxstringcmpnocase}\\
|
|
\helpref{IsSameAs}{wxstringissameas}\\
|
|
\helpref{Matches}{wxstringmatches}\\
|
|
\helpref{StartsWith}{wxstringstartswith}
|
|
|
|
\membersection{Substring extraction}
|
|
|
|
These functions allow to extract substring from this string. All of them don't
|
|
modify the original string and return a new string containing the extracted
|
|
substring.
|
|
|
|
\helpref{Mid}{wxstringmid}\\
|
|
\helpref{operator()}{wxstringoperatorparenth}\\
|
|
\helpref{Left}{wxstringleft}\\
|
|
\helpref{Right}{wxstringright}\\
|
|
\helpref{BeforeFirst}{wxstringbeforefirst}\\
|
|
\helpref{BeforeLast}{wxstringbeforelast}\\
|
|
\helpref{AfterFirst}{wxstringafterfirst}\\
|
|
\helpref{AfterLast}{wxstringafterlast}\\
|
|
\helpref{StartsWith}{wxstringstartswith}
|
|
|
|
\membersection{Case conversion}
|
|
|
|
The MakeXXX() variants modify the string in place, while the other functions
|
|
return a new string which containts the original text converted to the upper or
|
|
lower case and leave the original string unchanged.
|
|
|
|
\helpref{MakeUpper}{wxstringmakeupper}\\
|
|
\helpref{Upper}{wxstringupper}\\
|
|
\helpref{MakeLower}{wxstringmakelower}\\
|
|
\helpref{Lower}{wxstringlower}
|
|
|
|
\membersection{Searching and replacing}
|
|
|
|
These functions replace the standard {\it strchr()} and {\it strstr()}
|
|
functions.
|
|
|
|
\helpref{Find}{wxstringfind}\\
|
|
\helpref{Replace}{wxstringreplace}
|
|
|
|
\membersection{Conversion to numbers}
|
|
|
|
The string provides functions for conversion to signed and unsigned integer and
|
|
floating point numbers. All three functions take a pointer to the variable to
|
|
put the numeric value in and return TRUE if the {\bf entire} string could be
|
|
converted to a number.
|
|
|
|
\helpref{ToLong}{wxstringtolong}\\
|
|
\helpref{ToULong}{wxstringtoulong}\\
|
|
\helpref{ToDouble}{wxstringtodouble}
|
|
|
|
\membersection{Writing values into the string}
|
|
|
|
Both formatted versions (\helpref{Printf}{wxstringprintf}) and stream-like
|
|
insertion operators exist (for basic types only). Additionally, the
|
|
\helpref{Format}{wxstringformat} function allows to use simply append
|
|
formatted value to a string:
|
|
|
|
\begin{verbatim}
|
|
// the following 2 snippets are equivalent
|
|
|
|
wxString s = "...";
|
|
s += wxString::Format("%d", n);
|
|
|
|
wxString s;
|
|
s.Printf("...%d", n);
|
|
\end{verbatim}
|
|
|
|
\helpref{Format}{wxstringformat}\\
|
|
\helpref{FormatV}{wxstringformatv}\\
|
|
\helpref{Printf}{wxstringprintf}\\
|
|
\helpref{PrintfV}{wxstringprintfv}\\
|
|
\helpref{operator \cinsert}{wxstringoperatorout}
|
|
|
|
\membersection{Memory management}
|
|
|
|
These are "advanced" functions and they will be needed quite rarily.
|
|
\helpref{Alloc}{wxstringalloc} and \helpref{Shrink}{wxstringshrink} are only
|
|
interesting for optimization purposes.
|
|
\helpref{GetWriteBuf}{wxstringgetwritebuf} may be very useful when working with
|
|
some external API which requires the caller to provide a writable buffer, but
|
|
extreme care should be taken when using it: before performing any other
|
|
operation on the string \helpref{UngetWriteBuf}{wxstringungetwritebuf} {\bf
|
|
must} be called!
|
|
|
|
\helpref{Alloc}{wxstringalloc}\\
|
|
\helpref{Shrink}{wxstringshrink}\\
|
|
\helpref{GetWriteBuf}{wxstringgetwritebuf}\\
|
|
\helpref{UngetWriteBuf}{wxstringungetwritebuf}
|
|
|
|
\membersection{Miscellaneous}
|
|
|
|
Other string functions.
|
|
|
|
\helpref{Trim}{wxstringtrim}\\
|
|
\helpref{Pad}{wxstringpad}\\
|
|
\helpref{Truncate}{wxstringtruncate}
|
|
|
|
\membersection{wxWindows 1.xx compatibility functions}
|
|
|
|
These functions are deprecated, please consider using new wxWindows 2.0
|
|
functions instead of them (or, even better, std::string compatible variants).
|
|
|
|
\helpref{SubString}{wxstringsubstring}\\
|
|
\helpref{sprintf}{wxstringsprintf}\\
|
|
\helpref{CompareTo}{wxstringcompareto}\\
|
|
\helpref{Length}{wxstringlength}\\
|
|
\helpref{Freq}{wxstringfreq}\\
|
|
\helpref{LowerCase}{wxstringlowercase}\\
|
|
\helpref{UpperCase}{wxstringuppercase}\\
|
|
\helpref{Strip}{wxstringstrip}\\
|
|
\helpref{Index}{wxstringindex}\\
|
|
\helpref{Remove}{wxstringremove}\\
|
|
\helpref{First}{wxstringfirst}\\
|
|
\helpref{Last}{wxstringlast}\\
|
|
\helpref{Contains}{wxstringcontains}\\
|
|
\helpref{IsNull}{wxstringisnull}\\
|
|
\helpref{IsAscii}{wxstringisascii}\\
|
|
\helpref{IsNumber}{wxstringisnumber}\\
|
|
\helpref{IsWord}{wxstringisword}
|
|
|
|
\membersection{std::string compatibility functions}\label{wxstringat}
|
|
|
|
The supported functions are only listed here, please see any STL reference for
|
|
their documentation.
|
|
|
|
\begin{verbatim}
|
|
// take nLen chars starting at nPos
|
|
wxString(const wxString& str, size_t nPos, size_t nLen);
|
|
// take all characters from pStart to pEnd (poor man's iterators)
|
|
wxString(const void *pStart, const void *pEnd);
|
|
|
|
// lib.string.capacity
|
|
// return the length of the string
|
|
size_t size() const;
|
|
// return the length of the string
|
|
size_t length() const;
|
|
// return the maximum size of the string
|
|
size_t max_size() const;
|
|
// resize the string, filling the space with c if c != 0
|
|
void resize(size_t nSize, char ch = '\0');
|
|
// delete the contents of the string
|
|
void clear();
|
|
// returns true if the string is empty
|
|
bool empty() const;
|
|
|
|
// lib.string.access
|
|
// return the character at position n
|
|
char at(size_t n) const;
|
|
// returns the writable character at position n
|
|
char& at(size_t n);
|
|
|
|
// lib.string.modifiers
|
|
// append a string
|
|
wxString& append(const wxString& str);
|
|
// append elements str[pos], ..., str[pos+n]
|
|
wxString& append(const wxString& str, size_t pos, size_t n);
|
|
// append first n (or all if n == npos) characters of sz
|
|
wxString& append(const char *sz, size_t n = npos);
|
|
|
|
// append n copies of ch
|
|
wxString& append(size_t n, char ch);
|
|
|
|
// same as `this_string = str'
|
|
wxString& assign(const wxString& str);
|
|
// same as ` = str[pos..pos + n]
|
|
wxString& assign(const wxString& str, size_t pos, size_t n);
|
|
// same as `= first n (or all if n == npos) characters of sz'
|
|
wxString& assign(const char *sz, size_t n = npos);
|
|
// same as `= n copies of ch'
|
|
wxString& assign(size_t n, char ch);
|
|
|
|
// insert another string
|
|
wxString& insert(size_t nPos, const wxString& str);
|
|
// insert n chars of str starting at nStart (in str)
|
|
wxString& insert(size_t nPos, const wxString& str, size_t nStart, size_t n);
|
|
|
|
// insert first n (or all if n == npos) characters of sz
|
|
wxString& insert(size_t nPos, const char *sz, size_t n = npos);
|
|
// insert n copies of ch
|
|
wxString& insert(size_t nPos, size_t n, char ch);
|
|
|
|
// delete characters from nStart to nStart + nLen
|
|
wxString& erase(size_t nStart = 0, size_t nLen = npos);
|
|
|
|
// replaces the substring of length nLen starting at nStart
|
|
wxString& replace(size_t nStart, size_t nLen, const char* sz);
|
|
// replaces the substring with nCount copies of ch
|
|
wxString& replace(size_t nStart, size_t nLen, size_t nCount, char ch);
|
|
// replaces a substring with another substring
|
|
wxString& replace(size_t nStart, size_t nLen,
|
|
const wxString& str, size_t nStart2, size_t nLen2);
|
|
// replaces the substring with first nCount chars of sz
|
|
wxString& replace(size_t nStart, size_t nLen,
|
|
const char* sz, size_t nCount);
|
|
|
|
// swap two strings
|
|
void swap(wxString& str);
|
|
|
|
// All find() functions take the nStart argument which specifies the
|
|
// position to start the search on, the default value is 0. All functions
|
|
// return npos if there were no match.
|
|
|
|
// find a substring
|
|
size_t find(const wxString& str, size_t nStart = 0) const;
|
|
|
|
// find first n characters of sz
|
|
size_t find(const char* sz, size_t nStart = 0, size_t n = npos) const;
|
|
|
|
// find the first occurrence of character ch after nStart
|
|
size_t find(char ch, size_t nStart = 0) const;
|
|
|
|
// rfind() family is exactly like find() but works right to left
|
|
|
|
// as find, but from the end
|
|
size_t rfind(const wxString& str, size_t nStart = npos) const;
|
|
|
|
// as find, but from the end
|
|
size_t rfind(const char* sz, size_t nStart = npos,
|
|
size_t n = npos) const;
|
|
// as find, but from the end
|
|
size_t rfind(char ch, size_t nStart = npos) const;
|
|
|
|
// find first/last occurrence of any character in the set
|
|
|
|
//
|
|
size_t find_first_of(const wxString& str, size_t nStart = 0) const;
|
|
//
|
|
size_t find_first_of(const char* sz, size_t nStart = 0) const;
|
|
// same as find(char, size_t)
|
|
size_t find_first_of(char 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* s, size_t nStart = npos) const;
|
|
// same as rfind(char, size_t)
|
|
size_t find_last_of (char c, size_t nStart = npos) const;
|
|
|
|
// find first/last occurrence of any character not in the set
|
|
|
|
//
|
|
size_t find_first_not_of(const wxString& str, size_t nStart = 0) const;
|
|
//
|
|
size_t find_first_not_of(const char* s, size_t nStart = 0) const;
|
|
//
|
|
size_t find_first_not_of(char 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* s, size_t nStart = npos) const;
|
|
//
|
|
size_t find_last_not_of(char ch, size_t nStart = npos) const;
|
|
|
|
// All compare functions return a negative, zero or positive value
|
|
// if the [sub]string is less, equal or greater than the compare() argument.
|
|
|
|
// just like strcmp()
|
|
int compare(const wxString& str) const;
|
|
// comparison with a substring
|
|
int compare(size_t nStart, size_t nLen, const wxString& str) const;
|
|
// comparison of 2 substrings
|
|
int compare(size_t nStart, size_t nLen,
|
|
const wxString& str, size_t nStart2, size_t nLen2) const;
|
|
// just like strcmp()
|
|
int compare(const char* sz) const;
|
|
// substring comparison with first nCount characters of sz
|
|
int compare(size_t nStart, size_t nLen,
|
|
const char* sz, size_t nCount = npos) const;
|
|
|
|
// substring extraction
|
|
wxString substr(size_t nStart = 0, size_t nLen = npos) const;
|
|
\end{verbatim}
|
|
|
|
%%%%% MEMBERS HERE %%%%%
|
|
\helponly{\insertatlevel{2}{
|
|
|
|
\wxheading{Members}
|
|
|
|
}}
|
|
|
|
\membersection{wxString::wxString}\label{wxstringconstruct}
|
|
|
|
\func{}{wxString}{\void}
|
|
|
|
Default constructor.
|
|
|
|
\func{}{wxString}{\param{const wxString\&}{ x}}
|
|
|
|
Copy constructor.
|
|
|
|
\func{}{wxString}{\param{char}{ ch}, \param{size\_t}{ n = 1}}
|
|
|
|
Constructs a string of {\it n} copies of character {\it ch}.
|
|
|
|
\func{}{wxString}{\param{const char*}{ psz}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}
|
|
|
|
Takes first {\it nLength} characters from the C string {\it psz}.
|
|
The default value of wxSTRING\_MAXLEN means to take all the string.
|
|
|
|
Note that this constructor may be used even if {\it psz} points to a buffer
|
|
with binary data (i.e. containing {\tt NUL} characters) as long as you provide
|
|
the correct value for {\it nLength}. However, the default form of it works
|
|
only with strings without intermediate {\tt NUL}s because it uses
|
|
{\tt strlen()} to calculate the effective length and it would not give correct
|
|
results otherwise.
|
|
|
|
\func{}{wxString}{\param{const unsigned char*}{ psz}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}
|
|
|
|
For compilers using unsigned char: takes first {\it nLength} characters from the C string {\it psz}.
|
|
The default value of wxSTRING\_MAXLEN means take all the string.
|
|
|
|
\func{}{wxString}{\param{const wchar\_t*}{ psz}}
|
|
|
|
Constructs a string from the wide (UNICODE) string.
|
|
|
|
\membersection{wxString::\destruct{wxString}}\label{wxstringdestruct}
|
|
|
|
\func{}{\destruct{wxString}}{\void}
|
|
|
|
String destructor. Note that this is not virtual, so wxString must not be inherited from.
|
|
|
|
\membersection{wxString::Alloc}\label{wxstringalloc}
|
|
|
|
\func{void}{Alloc}{\param{size\_t}{ nLen}}
|
|
|
|
Preallocate enough space for wxString to store {\it nLen} characters. This function
|
|
may be used to increase speed when the string is constructed by repeated
|
|
concatenation as in
|
|
|
|
\begin{verbatim}
|
|
|
|
// 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;
|
|
}
|
|
|
|
\end{verbatim}
|
|
|
|
because it will avoid the need of reallocating 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 {\it nLen} characters are stored in it. Also, it
|
|
does not truncate the existing string (use
|
|
\helpref{Truncate()}{wxstringtruncate} for this) even if its current length is
|
|
greater than {\it nLen}
|
|
|
|
\membersection{wxString::Append}\label{wxstringappend}
|
|
|
|
\func{wxString\&}{Append}{\param{const char*}{ psz}}
|
|
|
|
Concatenates {\it psz} to this string, returning a reference to it.
|
|
|
|
\func{wxString\&}{Append}{\param{char}{ ch}, \param{int}{ count = 1}}
|
|
|
|
Concatenates character {\it ch} to this string, {\it count} times, returning a reference
|
|
to it.
|
|
|
|
\membersection{wxString::AfterFirst}\label{wxstringafterfirst}
|
|
|
|
\constfunc{wxString}{AfterFirst}{\param{char}{ ch}}
|
|
|
|
Gets all the characters after the first occurrence of {\it ch}.
|
|
Returns the empty string if {\it ch} is not found.
|
|
|
|
\membersection{wxString::AfterLast}\label{wxstringafterlast}
|
|
|
|
\constfunc{wxString}{AfterLast}{\param{char}{ ch}}
|
|
|
|
Gets all the characters after the last occurrence of {\it ch}.
|
|
Returns the whole string if {\it ch} is not found.
|
|
|
|
\membersection{wxString::BeforeFirst}\label{wxstringbeforefirst}
|
|
|
|
\constfunc{wxString}{BeforeFirst}{\param{char}{ ch}}
|
|
|
|
Gets all characters before the first occurrence of {\it ch}.
|
|
Returns the whole string if {\it ch} is not found.
|
|
|
|
\membersection{wxString::BeforeLast}\label{wxstringbeforelast}
|
|
|
|
\constfunc{wxString}{BeforeLast}{\param{char}{ ch}}
|
|
|
|
Gets all characters before the last occurrence of {\it ch}.
|
|
Returns the empty string if {\it ch} is not found.
|
|
|
|
\membersection{wxString::c\_str}\label{wxstringcstr}
|
|
|
|
\constfunc{const char *}{c\_str}{\void}
|
|
|
|
Returns a pointer to the string data.
|
|
|
|
\membersection{wxString::Clear}\label{wxstringclear}
|
|
|
|
\func{void}{Clear}{\void}
|
|
|
|
Empties the string and frees memory occupied by it.
|
|
|
|
See also: \helpref{Empty}{wxstringempty}
|
|
|
|
\membersection{wxString::Cmp}\label{wxstringcmp}
|
|
|
|
\constfunc{int}{Cmp}{\param{const char*}{ psz}}
|
|
|
|
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 {\it strcmp()} function).
|
|
|
|
See also \helpref{CmpNoCase}{wxstringcmpnocase}, \helpref{IsSameAs}{wxstringissameas}.
|
|
|
|
\membersection{wxString::CmpNoCase}\label{wxstringcmpnocase}
|
|
|
|
\constfunc{int}{CmpNoCase}{\param{const char*}{ psz}}
|
|
|
|
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 {\it strcmp()} function).
|
|
|
|
See also \helpref{Cmp}{wxstringcmp}, \helpref{IsSameAs}{wxstringissameas}.
|
|
|
|
\membersection{wxString::CompareTo}\label{wxstringcompareto}
|
|
|
|
\begin{verbatim}
|
|
#define NO_POS ((int)(-1)) // undefined position
|
|
enum caseCompare {exact, ignoreCase};
|
|
\end{verbatim}
|
|
|
|
\constfunc{int}{CompareTo}{\param{const char*}{ psz}, \param{caseCompare}{ cmp = exact}}
|
|
|
|
Case-sensitive comparison. Returns 0 if equal, 1 if greater or -1 if less.
|
|
|
|
\membersection{wxString::Contains}\label{wxstringcontains}
|
|
|
|
\constfunc{bool}{Contains}{\param{const wxString\&}{ str}}
|
|
|
|
Returns 1 if target appears anyhere in wxString; else 0.
|
|
|
|
\membersection{wxString::Empty}\label{wxstringempty}
|
|
|
|
\func{void}{Empty}{\void}
|
|
|
|
Makes the string empty, but doesn't free memory occupied by the string.
|
|
|
|
See also: \helpref{Clear()}{wxstringclear}.
|
|
|
|
\membersection{wxString::Find}\label{wxstringfind}
|
|
|
|
\constfunc{int}{Find}{\param{char}{ ch}, \param{bool}{ fromEnd = FALSE}}
|
|
|
|
Searches for the given character. Returns the starting index, or -1 if not found.
|
|
|
|
\constfunc{int}{Find}{\param{const char*}{ sz}}
|
|
|
|
Searches for the given string. Returns the starting index, or -1 if not found.
|
|
|
|
\membersection{wxString::First}\label{wxstringfirst}
|
|
|
|
\func{size\_t}{First}{\param{char}{ c}}
|
|
|
|
\constfunc{size\_t}{First}{\param{const char*}{ psz}}
|
|
|
|
\constfunc{size\_t}{First}{\param{const wxString\&}{ str}}
|
|
|
|
\constfunc{size\_t}{First}{\param{const char}{ ch}}
|
|
|
|
Returns the first occurrence of the item.
|
|
|
|
\membersection{wxString::Format}\label{wxstringformat}
|
|
|
|
\func{static wxString}{Format}{\param{const wxChar }{*format}, \param{}{...}}
|
|
|
|
This static function returns the string containing the result of calling
|
|
\helpref{Printf}{wxstringprintf} with the passed parameters on it.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{FormatV}{wxstringformatv}, \helpref{Printf}{wxstringprintf}
|
|
|
|
\membersection{wxString::FormatV}\label{wxstringformatv}
|
|
|
|
\func{static wxString}{Format}{\param{const wxChar }{*format}, \param{va\_list }{argptr}}
|
|
|
|
This static function returns the string containing the result of calling
|
|
\helpref{PrintfV}{wxstringprintfv} with the passed parameters on it.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{Format}{wxstringformat}, \helpref{PrintfV}{wxstringprintfv}
|
|
|
|
\membersection{wxString::Freq}\label{wxstringfreq}
|
|
|
|
\constfunc{int}{Freq}{\param{char }{ch}}
|
|
|
|
Returns the number of occurrences of {\it ch} in the string.
|
|
|
|
\membersection{wxString::GetChar}\label{wxstringgetchar}
|
|
|
|
\constfunc{char}{GetChar}{\param{size\_t}{ n}}
|
|
|
|
Returns the character at position {\it n} (read-only).
|
|
|
|
\membersection{wxString::GetData}\label{wxstringgetdata}
|
|
|
|
\constfunc{const char*}{GetData}{\void}
|
|
|
|
wxWindows compatibility conversion. Returns a constant pointer to the data in the string.
|
|
|
|
\membersection{wxString::GetWritableChar}\label{wxstringgetwritablechar}
|
|
|
|
\func{char\&}{GetWritableChar}{\param{size\_t}{ n}}
|
|
|
|
Returns a reference to the character at position {\it n}.
|
|
|
|
\membersection{wxString::GetWriteBuf}\label{wxstringgetwritebuf}
|
|
|
|
\func{char*}{GetWriteBuf}{\param{size\_t}{ len}}
|
|
|
|
Returns a writable buffer of at least {\it len} bytes.
|
|
|
|
Call \helpref{wxString::UngetWriteBuf}{wxstringungetwritebuf} as soon as possible
|
|
to put the string back into a reasonable state.
|
|
|
|
\membersection{wxString::Index}\label{wxstringindex}
|
|
|
|
\constfunc{size\_t}{Index}{\param{char}{ ch}, \param{int}{ startpos = 0}}
|
|
|
|
Same as \helpref{wxString::Find}{wxstringfind}.
|
|
|
|
\constfunc{size\_t}{Index}{\param{const char*}{ sz}}
|
|
|
|
Same as \helpref{wxString::Find}{wxstringfind}.
|
|
|
|
\constfunc{size\_t}{Index}{\param{const char*}{ sz}, \param{bool}{ caseSensitive = TRUE}, \param{bool}{ fromEnd = FALSE}}
|
|
|
|
Search the element in the array, starting from either side.
|
|
|
|
If {\it fromEnd} is TRUE, reverse search direction.
|
|
|
|
If {\bf caseSensitive}, comparison is case sensitive (the default).
|
|
|
|
Returns the index of the first item matched, or NOT\_FOUND.
|
|
|
|
% TODO
|
|
%\membersection{wxString::insert}\label{wxstringinsert}
|
|
% Wrong!
|
|
%\func{void}{insert}{\param{const wxString\&}{ str}, \param{size\_t}{ index}}
|
|
%
|
|
%Add new element at the given position.
|
|
%
|
|
\membersection{wxString::IsAscii}\label{wxstringisascii}
|
|
|
|
\constfunc{bool}{IsAscii}{\void}
|
|
|
|
Returns TRUE if the string contains only ASCII characters.
|
|
|
|
\membersection{wxString::IsEmpty}\label{wxstringisempty}
|
|
|
|
\constfunc{bool}{IsEmpty}{\void}
|
|
|
|
Returns TRUE if the string is empty.
|
|
|
|
\membersection{wxString::IsNull}\label{wxstringisnull}
|
|
|
|
\constfunc{bool}{IsNull}{\void}
|
|
|
|
Returns TRUE if the string is empty (same as \helpref{IsEmpty}{wxstringisempty}).
|
|
|
|
\membersection{wxString::IsNumber}\label{wxstringisnumber}
|
|
|
|
\constfunc{bool}{IsNumber}{\void}
|
|
|
|
Returns TRUE if the string is an integer (with possible sign).
|
|
|
|
\membersection{wxString::IsSameAs}\label{wxstringissameas}
|
|
|
|
\constfunc{bool}{IsSameAs}{\param{const char*}{ psz}, \param{bool}{ caseSensitive = TRUE}}
|
|
|
|
Test for string equality, case-sensitive (default) or not.
|
|
|
|
caseSensitive is TRUE by default (case matters).
|
|
|
|
Returns TRUE if strings are equal, FALSE otherwise.
|
|
|
|
See also \helpref{Cmp}{wxstringcmp}, \helpref{CmpNoCase}{wxstringcmpnocase}, \helpref{IsSameAs}{wxstringissameas2}
|
|
|
|
\membersection{wxString::IsSameAs}\label{wxstringissameas2}
|
|
|
|
\constfunc{bool}{IsSameAs}{\param{char}{ c}, \param{bool}{ caseSensitive = TRUE}}
|
|
|
|
Test whether the string is equal to the single character {\it c}. The test is
|
|
case-sensitive if {\it caseSensitive} is TRUE (default) or not if it is FALSE.
|
|
|
|
Returns TRUE if the string is equal to the character, FALSE otherwise.
|
|
|
|
See also \helpref{Cmp}{wxstringcmp}, \helpref{CmpNoCase}{wxstringcmpnocase}, \helpref{IsSameAs}{wxstringissameas}
|
|
|
|
\membersection{wxString::IsWord}\label{wxstringisword}
|
|
|
|
\constfunc{bool}{IsWord}{\void}
|
|
|
|
Returns TRUE if the string is a word. TODO: what's the definition of a word?
|
|
|
|
\membersection{wxString::Last}\label{wxstringlast}
|
|
|
|
\constfunc{char}{Last}{\void}
|
|
|
|
Returns the last character.
|
|
|
|
\func{char\&}{Last}{\void}
|
|
|
|
Returns a reference to the last character (writable).
|
|
|
|
\membersection{wxString::Left}\label{wxstringleft}
|
|
|
|
\constfunc{wxString}{Left}{\param{size\_t}{ count}}
|
|
|
|
Returns the first {\it count} characters.
|
|
|
|
\constfunc{wxString}{Left}{\param{char}{ ch}}
|
|
|
|
Returns all characters before the first occurrence of {\it ch}.
|
|
Returns the whole string if {\it ch} is not found.
|
|
|
|
\membersection{wxString::Len}\label{wxstringlen}
|
|
|
|
\constfunc{size\_t}{Len}{\void}
|
|
|
|
Returns the length of the string.
|
|
|
|
\membersection{wxString::Length}\label{wxstringlength}
|
|
|
|
\constfunc{size\_t}{Length}{\void}
|
|
|
|
Returns the length of the string (same as Len).
|
|
|
|
\membersection{wxString::Lower}\label{wxstringlower}
|
|
|
|
\constfunc{wxString}{Lower}{\void}
|
|
|
|
Returns this string converted to the lower case.
|
|
|
|
\membersection{wxString::LowerCase}\label{wxstringlowercase}
|
|
|
|
\func{void}{LowerCase}{\void}
|
|
|
|
Same as MakeLower.
|
|
|
|
\membersection{wxString::MakeLower}\label{wxstringmakelower}
|
|
|
|
\func{void}{MakeLower}{\void}
|
|
|
|
Converts all characters to lower case.
|
|
|
|
\membersection{wxString::MakeUpper}\label{wxstringmakeupper}
|
|
|
|
\func{void}{MakeUpper}{\void}
|
|
|
|
Converts all characters to upper case.
|
|
|
|
\membersection{wxString::Matches}\label{wxstringmatches}
|
|
|
|
\constfunc{bool}{Matches}{\param{const char*}{ szMask}}
|
|
|
|
Returns TRUE if the string contents matches a mask containing '*' and '?'.
|
|
|
|
\membersection{wxString::Mid}\label{wxstringmid}
|
|
|
|
\constfunc{wxString}{Mid}{\param{size\_t}{ first}, \param{size\_t}{ count = wxSTRING\_MAXLEN}}
|
|
|
|
Returns a substring starting at {\it first}, with length {\it count}, or the rest of
|
|
the string if {\it count} is the default value.
|
|
|
|
\membersection{wxString::Pad}\label{wxstringpad}
|
|
|
|
\func{wxString\&}{Pad}{\param{size\_t}{ count}, \param{char}{ pad = ' '}, \param{bool}{ fromRight = TRUE}}
|
|
|
|
Adds {\it count} copies of {\it pad} to the beginning, or to the end of the string (the default).
|
|
|
|
Removes spaces from the left or from the right (default).
|
|
|
|
\membersection{wxString::Prepend}\label{wxstringprepend}
|
|
|
|
\func{wxString\&}{Prepend}{\param{const wxString\&}{ str}}
|
|
|
|
Prepends {\it str} to this string, returning a reference to this string.
|
|
|
|
\membersection{wxString::Printf}\label{wxstringprintf}
|
|
|
|
\func{int}{Printf}{\param{const char* }{pszFormat}, \param{}{...}}
|
|
|
|
Similar to the standard function {\it sprintf()}. Returns the number of
|
|
characters written, or an integer less than zero on error.
|
|
|
|
{\bf NB:} This function will use a safe version of {\it vsprintf()} (usually called
|
|
{\it vsnprintf()}) whenever available to always allocate the buffer of correct
|
|
size. Unfortunately, this function is not available on all platforms and the
|
|
dangerous {\it vsprintf()} will be used then which may lead to buffer overflows.
|
|
|
|
\membersection{wxString::PrintfV}\label{wxstringprintfv}
|
|
|
|
\func{int}{PrintfV}{\param{const char* }{pszFormat}, \param{va\_list}{ argPtr}}
|
|
|
|
Similar to vprintf. Returns the number of characters written, or an integer less than zero
|
|
on error.
|
|
|
|
\membersection{wxString::Remove}\label{wxstringremove}
|
|
|
|
\func{wxString\&}{Remove}{\param{size\_t}{ pos}}
|
|
|
|
Same as Truncate. Removes the portion from {\it pos} to the end of the string.
|
|
|
|
\func{wxString\&}{Remove}{\param{size\_t}{ pos}, \param{size\_t}{ len}}
|
|
|
|
Removes the {\it len} characters from the string, starting at {\it pos}.
|
|
|
|
\membersection{wxString::RemoveLast}\label{wxstringremovelast}
|
|
|
|
\func{wxString\&}{RemoveLast}{\void}
|
|
|
|
Removes the last character.
|
|
|
|
\membersection{wxString::Replace}\label{wxstringreplace}
|
|
|
|
\func{size\_t}{Replace}{\param{const char*}{ szOld}, \param{const char*}{ szNew}, \param{bool}{ replaceAll = TRUE}}
|
|
|
|
Replace first (or all) occurrences of substring with another one.
|
|
|
|
{\it replaceAll}: global replace (default), or only the first occurrence.
|
|
|
|
Returns the number of replacements made.
|
|
|
|
\membersection{wxString::Right}\label{wxstringright}
|
|
|
|
\constfunc{wxString}{Right}{\param{size\_t}{ count}}
|
|
|
|
Returns the last {\it count} characters.
|
|
|
|
\membersection{wxString::SetChar}\label{wxstringsetchar}
|
|
|
|
\func{void}{SetChar}{\param{size\_t}{ n}, \param{char}{ch}}
|
|
|
|
Sets the character at position {\it n}.
|
|
|
|
\membersection{wxString::Shrink}\label{wxstringshrink}
|
|
|
|
\func{void}{Shrink}{\void}
|
|
|
|
Minimizes the string's memory. This can be useful after a call to
|
|
\helpref{Alloc()}{wxstringalloc} if too much memory were preallocated.
|
|
|
|
\membersection{wxString::sprintf}\label{wxstringsprintf}
|
|
|
|
\func{void}{sprintf}{\param{const char* }{ fmt}}
|
|
|
|
The same as Printf.
|
|
|
|
\membersection{wxString::StartsWith}\label{wxstringstartswith}
|
|
|
|
\constfunc{bool}{StartsWith}{\param{const wxChar }{*prefix}, \param{wxString }{*rest = NULL}}
|
|
|
|
This function can be used to test if the string starts with the specified
|
|
{\it prefix}. If it does, the function will return {\tt TRUE} and put the rest
|
|
of the string (i.e. after the prefix) into {\it rest} string if it is not
|
|
{\tt NULL}. Otherwise, the function returns {\tt FALSE} and doesn't modify the
|
|
{\it rest}.
|
|
|
|
\membersection{wxString::Strip}\label{wxstringstrip}
|
|
|
|
\begin{verbatim}
|
|
enum stripType {leading = 0x1, trailing = 0x2, both = 0x3};
|
|
\end{verbatim}
|
|
|
|
\constfunc{wxString}{Strip}{\param{stripType}{ s = trailing}}
|
|
|
|
Strip characters at the front and/or end. The same as Trim except that it
|
|
doesn't change this string.
|
|
|
|
\membersection{wxString::SubString}\label{wxstringsubstring}
|
|
|
|
\constfunc{wxString}{SubString}{\param{size\_t}{ from}, \param{size\_t}{ to}}
|
|
|
|
Deprecated, use \helpref{Mid}{wxstringmid} instead (but note that parameters
|
|
have different meaning).
|
|
|
|
Returns the part of the string between the indices {\it from} and {\it to}
|
|
inclusive.
|
|
|
|
\membersection{wxString::ToDouble}\label{wxstringtodouble}
|
|
|
|
\constfunc{bool}{ToDouble}{\param{double}{ *val}}
|
|
|
|
Attempts to convert the string to a floating point number. Returns TRUE on
|
|
success (the number is stored in the location pointed to by {\it val}) or FALSE
|
|
if the string does not represent such number.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxString::ToLong}{wxstringtolong},\\
|
|
\helpref{wxString::ToULong}{wxstringtoulong}
|
|
|
|
\membersection{wxString::ToLong}\label{wxstringtolong}
|
|
|
|
\constfunc{bool}{ToLong}{\param{long}{ *val}}
|
|
|
|
Attempts to convert the string to a signed integer. Returns TRUE on success
|
|
(the number is stored in the location pointed to by {\it val}) or FALSE if the
|
|
string does not represent such number.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxString::ToDouble}{wxstringtodouble},\\
|
|
\helpref{wxString::ToULong}{wxstringtoulong}
|
|
|
|
\membersection{wxString::ToULong}\label{wxstringtoulong}
|
|
|
|
\constfunc{bool}{ToULong}{\param{unsigned long}{ *val}}
|
|
|
|
Attempts to convert the string to an unsigned integer. Returns TRUE on success
|
|
(the number is stored in the location pointed to by {\it val}) or FALSE if the
|
|
string does not represent such number.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxString::ToDouble}{wxstringtodouble},\\
|
|
\helpref{wxString::ToLong}{wxstringtolong}
|
|
|
|
\membersection{wxString::Trim}\label{wxstringtrim}
|
|
|
|
\func{wxString\&}{Trim}{\param{bool}{ fromRight = TRUE}}
|
|
|
|
Removes spaces from the left or from the right (default).
|
|
|
|
\membersection{wxString::Truncate}\label{wxstringtruncate}
|
|
|
|
\func{wxString\&}{Truncate}{\param{size\_t}{ len}}
|
|
|
|
Truncate the string to the given length.
|
|
|
|
\membersection{wxString::UngetWriteBuf}\label{wxstringungetwritebuf}
|
|
|
|
\func{void}{UngetWriteBuf}{\void}
|
|
|
|
Puts the string back into a reasonable state, after
|
|
\rtfsp\helpref{wxString::GetWriteBuf}{wxstringgetwritebuf} was called.
|
|
|
|
\membersection{wxString::Upper}\label{wxstringupper}
|
|
|
|
\constfunc{wxString}{Upper}{\void}
|
|
|
|
Returns this string converted to upper case.
|
|
|
|
\membersection{wxString::UpperCase}\label{wxstringuppercase}
|
|
|
|
\func{void}{UpperCase}{\void}
|
|
|
|
The same as MakeUpper.
|
|
|
|
\membersection{wxString::operator!}\label{wxstringoperatornot}
|
|
|
|
\constfunc{bool}{operator!}{\void}
|
|
|
|
Empty string is FALSE, so !string will only return TRUE if the string is empty.
|
|
This allows the tests for NULLness of a {\it const char *} pointer and emptyness
|
|
of the string to look the same in the code and makes it easier to port old code
|
|
to wxString.
|
|
|
|
See also \helpref{IsEmpty()}{wxstringisempty}.
|
|
|
|
\membersection{wxString::operator $=$}\label{wxstringoperatorassign}
|
|
|
|
\func{wxString\&}{operator $=$}{\param{const wxString\&}{ str}}
|
|
|
|
\func{wxString\&}{operator $=$}{\param{const char*}{ psz}}
|
|
|
|
\func{wxString\&}{operator $=$}{\param{char}{ c}}
|
|
|
|
\func{wxString\&}{operator $=$}{\param{const unsigned char*}{ psz}}
|
|
|
|
\func{wxString\&}{operator $=$}{\param{const wchar\_t*}{ pwz}}
|
|
|
|
Assignment: the effect of each operation is the same as for the corresponding
|
|
constructor (see \helpref{wxString constructors}{wxstringconstruct}).
|
|
|
|
\membersection{wxString::operator $+$}\label{wxstringoperatorplus}
|
|
|
|
Concatenation: all these operators return a new strign equal to the sum of the
|
|
operands.
|
|
|
|
\func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
|
|
|
|
\func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{const char*}{ y}}
|
|
|
|
\func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{char}{ y}}
|
|
|
|
\func{wxString}{operator $+$}{\param{const char*}{ x}, \param{const wxString\&}{ y}}
|
|
|
|
\membersection{wxString::operator $+=$}\label{wxstringplusequal}
|
|
|
|
\func{void}{operator $+=$}{\param{const wxString\&}{ str}}
|
|
|
|
\func{void}{operator $+=$}{\param{const char*}{ psz}}
|
|
|
|
\func{void}{operator $+=$}{\param{char}{ c}}
|
|
|
|
Concatenation in place: the argument is appended to the string.
|
|
|
|
\membersection{wxString::operator []}\label{wxstringoperatorbracket}
|
|
|
|
\func{char\&}{operator []}{\param{size\_t}{ i}}
|
|
|
|
\func{char}{operator []}{\param{size\_t}{ i}}
|
|
|
|
\func{char}{operator []}{\param{int}{ i}}
|
|
|
|
Element extraction.
|
|
|
|
\membersection{wxString::operator ()}\label{wxstringoperatorparenth}
|
|
|
|
\func{wxString}{operator ()}{\param{size\_t}{ start}, \param{size\_t}{ len}}
|
|
|
|
Same as Mid (substring extraction).
|
|
|
|
\membersection{wxString::operator \cinsert}\label{wxstringoperatorout}
|
|
|
|
\func{wxString\&}{operator \cinsert}{\param{const wxString\&}{ str}}
|
|
|
|
\func{wxString\&}{operator \cinsert}{\param{const char*}{ psz}}
|
|
|
|
\func{wxString\&}{operator \cinsert}{\param{char }{ch}}
|
|
|
|
Same as $+=$.
|
|
|
|
\func{wxString\&}{operator \cinsert}{\param{int}{ i}}
|
|
|
|
\func{wxString\&}{operator \cinsert}{\param{float}{ f}}
|
|
|
|
\func{wxString\&}{operator \cinsert}{\param{double}{ d}}
|
|
|
|
These functions work as C++ stream insertion operators: they insert the given
|
|
value into the string. Precision or format cannot be set using them, you can use
|
|
\helpref{Printf}{wxstringprintf} for this.
|
|
|
|
\membersection{wxString::operator \cextract}\label{wxstringoperatorin}
|
|
|
|
\func{friend istream\&}{operator \cextract}{\param{istream\&}{ is}, \param{wxString\&}{ str}}
|
|
|
|
Extraction from a stream.
|
|
|
|
\membersection{wxString::operator const char*}\label{wxstringoperatorconstcharpt}
|
|
|
|
\constfunc{}{operator const char*}{\void}
|
|
|
|
Implicit conversion to a C string.
|
|
|
|
\membersection{Comparison operators}\label{wxstringcomparison}
|
|
|
|
\func{bool}{operator $==$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
|
|
|
|
\func{bool}{operator $==$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
|
|
|
|
\func{bool}{operator $!=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
|
|
|
|
\func{bool}{operator $!=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
|
|
|
|
\func{bool}{operator $>$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
|
|
|
|
\func{bool}{operator $>$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
|
|
|
|
\func{bool}{operator $>=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
|
|
|
|
\func{bool}{operator $>=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
|
|
|
|
\func{bool}{operator $<$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
|
|
|
|
\func{bool}{operator $<$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
|
|
|
|
\func{bool}{operator $<=$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
|
|
|
|
\func{bool}{operator $<=$}{\param{const wxString\&}{ x}, \param{const char*}{ t}}
|
|
|
|
\wxheading{Remarks}
|
|
|
|
These comparisons are case-sensitive.
|
|
|