wxDataObject documented

[wxWidgets.git] / docs / latex / wx / wxstring.tex

\section{\class{wxString}}\label{wxstring}

\wxheading{Derived from}

None

\wxheading{See also}

\overview{Overview}{wxstringoverview}

\latexignore{\rtfignore{\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 = STRING\_MAXLEN}}

Takes first {\it nLength} characters from the C string {\it psz}.
The default value of STRING\_MAXLEN means take all the string.

\func{}{wxString}{\param{const unsigned char*}{ psz}, \param{size\_t}{ nLength = STRING\_MAXLEN}}

For compilers using unsigned char: takes first {\it nLength} characters from the C string {\it psz}.
The default value of STRING\_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{uint}{ newsize}}

Preallocate some space for wxString. Only works if the data of this string is not shared.

\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::After}\label{wxstringAfter}

\constfunc{wxString}{After}{\param{char}{ ch}}

Gets all the characters after the first occurence of {\it ch}.
Returns the empty string if {\it ch} is not found.

\membersection{wxString::Before}\label{wxstringBefore}

\constfunc{wxString}{Before}{\param{char}{ ch}}

Gets all characters before the last occurence of {\it ch}.
Returns empty string if {\it ch} is not found.

\membersection{wxString::Cmp}\label{wxstringcmp}

\constfunc{int}{Cmp}{\param{const char*}{ psz}}

Case-sensitive comparison.

Returns 0 if equal, +1 if greater or -1 if less.

See also CmpNoCase, IsSameAs.

\membersection{wxString::CmpNoCase}\label{wxstringcmpnocase}

\constfunc{int}{CmpNoCase}{\param{const char*}{ psz}}

Case-insensitive comparison.

Returns 0 if equal, +1 if greater or -1 if less.

See also Cmp, IsSameAs.

\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}

\func{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}

Reinitializes the string and frees the data.

\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::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{uint}{ 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{uint}{ index}}
%
%Add new element at the given position.
%
\membersection{wxString::IsAscii}\label{wxstringIsAscii}

\constfunc{bool}{IsAscii}{\void}

Returns TRUE if the string is ASCII.

\membersection{wxString::IsEmpty}\label{wxstringisempty}

\constfunc{bool}{IsEmpty}{\void}

Returns TRUE if the string is NULL.

\membersection{wxString::IsNull}\label{wxstringIsNull}

\constfunc{bool}{IsNull}{\void}

Returns TRUE if the string is NULL (same as IsEmpty).

\membersection{wxString::IsNumber}\label{wxstringIsNumber}

\constfunc{bool}{IsNumber}{\void}

Returns TRUE if the string is a number.

\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 Cmp, CmpNoCase.

\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 occurence 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::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 = STRING\_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 sprintf. Returns the number of characters written, or an integer less than zero
on error.

\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 last {\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{uint}{Replace}{\param{const char*}{ szOld}, \param{const char*}{ szNew}, \param{bool}{ replaceAll}}

Replace first (or all) occurences of substring with another one.

{\it replaceAll}: global replace (default), or only the first occurence.

Returns the number of replacements made.

\membersection{wxString::Right}\label{wxstringright}

\constfunc{wxString}{Right}{\param{size\_t}{ count}}

Returns the last {\it count} characters.

\constfunc{wxString}{Right}{\param{char}{ ch}}

Returns all characters after the last occurence of {\it ch}.
Returns the whole string if {\it ch} is not found.

\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. Only works if the data of this string is not shared.

\membersection{wxString::sprintf}\label{wxstringsprintf}

\func{void}{sprintf}{\param{const char* }{ fmt}}

The same as Printf.

\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::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::UpperCase}\label{wxstringUpperCase}

\func{void}{UpperCase}{\void}

The same as MakeUpper.

\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.

\membersection{operator wxString::$+$}\label{wxstringoperatorplus}

Concatenation.

\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.

\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 $+=$.

\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.