wxstring.tex

来自「Wxpython Implemented on Windows CE, Sou」· TEX 代码 · 共 1,400 行 · 第 1/4 页

\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 (except that wxString is sensitive to null character).

You may notice that wxString sometimes has many functions which do the same
thing like, for example, \helpref{Length()}{wxstringlength}, 
\helpref{Len()}{wxstringlen} and {\tt length()} which all return the string
length. In all cases of such duplication the {\tt std::string}-compatible
method ({\tt length()} in this case, always the lowercase version) should be
used as it will ensure smoother transition to {\tt std::string} when wxWidgets
starts using it instead of wxString.

Also please note that in this manual \texttt{char} is sometimes used instead of 
\texttt{wxChar} because it hasn't been fully updated yet. Please substitute as
necessary and refer to the sources in case of a doubt.


\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}\label{constructorsinwxstring}

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.

\helpref{wxString}{wxstringconstruct}\\
\helpref{operator $=$}{wxstringoperatorassign}\\
\helpref{\destruct{wxString}}{wxstringdestruct}

\membersection{String length}\label{lengthfunctionsinwxstring}

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}\label{characteraccessinwxstring}

Many functions in this section take a character index in the string. As with C
strings and/or arrays, the indices start from $0$, so the first character of a
string is string[$0$]. Attempt to access a character beyond the end of the
string (which may be even $0$ if the string is empty) will provoke an assert
failure in \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{mb\_str}{wxstringmbstr}\\
\helpref{wc\_str}{wxstringwcstr}\\
\helpref{fn\_str}{wxstringfnstr}\\
\helpref{operator const char*}{wxstringoperatorconstcharpt}

\membersection{Concatenation}\label{concatenationinwxstring}

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}\label{comparisoninwxstring}

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 comparison 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}\\
\helpref{EndsWith}{wxstringendswith}

\membersection{Substring extraction}\label{substringextractioninwxstring}

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}\\
\helpref{EndsWith}{wxstringendswith}


\membersection{Case conversion}\label{caseconversioninwxstring}

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.

\helpref{MakeUpper}{wxstringmakeupper}\\
\helpref{Upper}{wxstringupper}\\
\helpref{MakeLower}{wxstringmakelower}\\
\helpref{Lower}{wxstringlower}

\membersection{Searching and replacing}\label{searchingandreplacinginwxstring}

These functions replace the standard {\it strchr()} and {\it strstr()} 
functions.

\helpref{Find}{wxstringfind}\\
\helpref{Replace}{wxstringreplace}

\membersection{Conversion to numbers}\label{conversiontonumbersinwxstring}

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}\label{writingintostringinwxstring}

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}\label{memoryinwxstring}

These are "advanced" functions and they will be needed quite rarely. 
\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}\label{miscellaneousinwxstring}

Other string functions.

\helpref{Trim}{wxstringtrim}\\
\helpref{Pad}{wxstringpad}\\
\helpref{Truncate}{wxstringtruncate}

\membersection{wxWidgets 1.xx compatibility functions}\label{backwardcompatibilityinwxstring}

These functions are deprecated, please consider using new wxWidgets 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