X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/bd8465ff4e9249eb5a202269c94a78bd6532391a..60b1fda237b5544162b8df38ca89cdef23e3f6b1:/docs/latex/wx/wxstring.tex

diff --git a/docs/latex/wx/wxstring.tex b/docs/latex/wx/wxstring.tex
index 0f230c8482..f3296fe1b8 100644
--- a/docs/latex/wx/wxstring.tex
+++ b/docs/latex/wx/wxstring.tex
@@ -36,7 +36,7 @@ Objects:
 
 \latexignore{\rtfignore{\wxheading{Function groups}}}
 
-\membersection{Constructors and assignment operators}
+\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
@@ -47,7 +47,7 @@ operator.
 \helpref{operator $=$}{wxstringoperatorassign}\\
 \helpref{\destruct{wxString}}{wxstringdestruct}
 
-\membersection{String length}
+\membersection{String length}\label{lengthfunctionsinwxstring}
 
 These functions return the string length and check whether the string is empty
 or empty it.
@@ -58,7 +58,7 @@ or empty it.
 \helpref{Empty}{wxstringempty}\\
 \helpref{Clear}{wxstringclear}
 
-\membersection{Character access}
+\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
@@ -84,7 +84,7 @@ use it.
 \helpref{fn\_str}{wxstringfnstr}\\
 \helpref{operator const char*}{wxstringoperatorconstcharpt}
 
-\membersection{Concatenation}
+\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
@@ -96,7 +96,7 @@ should be converted to a wxString first.
 \helpref{Append}{wxstringappend}\\
 \helpref{Prepend}{wxstringprepend}
 
-\membersection{Comparison}
+\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
@@ -121,7 +121,7 @@ length of the prefix then.
 \helpref{Matches}{wxstringmatches}\\
 \helpref{StartsWith}{wxstringstartswith}
 
-\membersection{Substring extraction}
+\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
@@ -137,7 +137,7 @@ substring.
 \helpref{AfterLast}{wxstringafterlast}\\
 \helpref{StartsWith}{wxstringstartswith}
 
-\membersection{Case conversion}
+\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
@@ -148,7 +148,7 @@ lower case and leave the original string unchanged.
 \helpref{MakeLower}{wxstringmakelower}\\
 \helpref{Lower}{wxstringlower}
 
-\membersection{Searching and replacing}
+\membersection{Searching and replacing}\label{searchingandreplacinginwxstring}
 
 These functions replace the standard {\it strchr()} and {\it strstr()} 
 functions.
@@ -156,7 +156,7 @@ functions.
 \helpref{Find}{wxstringfind}\\
 \helpref{Replace}{wxstringreplace}
 
-\membersection{Conversion to numbers}
+\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
@@ -167,7 +167,7 @@ converted to a number.
 \helpref{ToULong}{wxstringtoulong}\\
 \helpref{ToDouble}{wxstringtodouble}
 
-\membersection{Writing values into the string}
+\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 
@@ -190,7 +190,7 @@ formatted value to a string:
 \helpref{PrintfV}{wxstringprintfv}\\
 \helpref{operator \cinsert}{wxstringoperatorout}
 
-\membersection{Memory management}
+\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
@@ -206,7 +206,7 @@ must} be called!
 \helpref{GetWriteBuf}{wxstringgetwritebuf}\\
 \helpref{UngetWriteBuf}{wxstringungetwritebuf}
 
-\membersection{Miscellaneous}
+\membersection{Miscellaneous}\label{miscellaneousinwxstring}
 
 Other string functions.
 
@@ -214,7 +214,7 @@ Other string functions.
 \helpref{Pad}{wxstringpad}\\
 \helpref{Truncate}{wxstringtruncate}
 
-\membersection{wxWidgets 1.xx compatibility functions}
+\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).
@@ -492,7 +492,7 @@ wxString DeleteAllVowels(const wxString& original)
 
 \end{verbatim}
 
-because it will avoid the need of reallocating string memory many times (in case
+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 {\it nLen} characters are stored in it. Also, it
 does not truncate the existing string (use 
@@ -540,7 +540,7 @@ Returns the empty string if {\it ch} is not found.
 
 \membersection{wxString::c\_str}\label{wxstringcstr}
 
-\constfunc{const char *}{c\_str}{\void}
+\constfunc{const wxChar *}{c\_str}{\void}
 
 Returns a pointer to the string data ({\tt const char*} in ANSI build,
 {\tt const wchar\_t*} in Unicode build).
@@ -597,7 +597,7 @@ Case-sensitive comparison. Returns 0 if equal, 1 if greater or -1 if less.
 
 \constfunc{bool}{Contains}{\param{const wxString\&}{ str}}
 
-Returns 1 if target appears anyhere in wxString; else 0.
+Returns 1 if target appears anywhere in wxString; else 0.
 
 \membersection{wxString::Empty}\label{wxstringempty}
 
@@ -638,7 +638,7 @@ Same as \helpref{Find}{wxstringfind}.
 Returns string representation suitable for passing to OS' functions for
 file handling. In ANSI build, this is same as \helpref{c\_str}{wxstringcstr}.
 In Unicode build, returned value can be either wide character string
-or C string in charset matching the {\tt wxConvFile} object, depending on
+or C string in charset matching the {\tt wxConvFileName} object, depending on
 the OS.
 
 \wxheading{See also}
@@ -659,7 +659,7 @@ This static function returns the string containing the result of calling
 
 \membersection{wxString::FormatV}\label{wxstringformatv}
 
-\func{static wxString}{Format}{\param{const wxChar }{*format}, \param{va\_list }{argptr}}
+\func{static wxString}{FormatV}{\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.
@@ -694,7 +694,7 @@ Returns the character at position {\it n} (read-only).
 
 \membersection{wxString::GetData}\label{wxstringgetdata}
 
-\constfunc{const char*}{GetData}{\void}
+\constfunc{const wxChar*}{GetData}{\void}
 
 wxWidgets compatibility conversion. Returns a constant pointer to the data in the string.
 
@@ -723,16 +723,6 @@ to put the string back into a reasonable state.
 
 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 wxNOT\_FOUND.
-
 % TODO
 %\membersection{wxString::insert}\label{wxstringinsert}
 % Wrong!
@@ -774,9 +764,7 @@ 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}
+See also \helpref{Cmp}{wxstringcmp}, \helpref{CmpNoCase}{wxstringcmpnocase}
 
 \constfunc{bool}{IsSameAs}{\param{char}{ c}, \param{bool}{ caseSensitive = true}}
 
@@ -785,7 +773,7 @@ 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}
+See also \helpref{Cmp}{wxstringcmp}, \helpref{CmpNoCase}{wxstringcmpnocase}
 
 \membersection{wxString::IsWord}\label{wxstringisword}
 
@@ -1045,7 +1033,7 @@ familiar with C) results.
 
 \constfunc{bool}{ToULong}{\param{unsigned long}{ *val}, \param{int }{base = $10$}}
 
-Attempts to convert the string to a ansigned integer in base {\it base}.
+Attempts to convert the string to an unsigned integer in base {\it base}.
 Returns {\tt true} on success in which case the number is stored in the
 location pointed to by {\it val} or {\tt false} if the string does not
 represent a valid number in the given base.
@@ -1122,7 +1110,7 @@ The macro wxWX2WCbuf is defined as the correct return type (without const).
 \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
+This allows the tests for NULLness of a {\it const char *} pointer and emptiness
 of the string to look the same in the code and makes it easier to port old code
 to wxString.
 
@@ -1145,8 +1133,8 @@ 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.
+Concatenation: all these operators return a new string equal to the
+concatenation of the operands.
 
 \func{wxString}{operator $+$}{\param{const wxString\&}{ x}, \param{const wxString\&}{ y}}
 
@@ -1248,7 +1236,7 @@ These comparisons are case-sensitive.
 \section{\class{wxStringBuffer}}\label{wxstringbuffer}
 
 This tiny class allows to conveniently access the \helpref{wxString}{wxstring} 
-internal buffer as a writable pointer without any risk to forget to restore
+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 
@@ -1264,6 +1252,13 @@ buffer (which must be writable, of course) you might call it like this:
     }
 \end{verbatim}
 
+Note that the exact usage of this depends on whether on not wxUSE\_STL is enabled.  If
+wxUSE\_STL is enabled, wxStringBuffer creates a seperate empty character buffer, and
+if wxUSE\_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same buffer
+wxString uses intact.  In other words, relying on wxStringBuffer containing the old 
+wxString data is probably not a good idea if you want to build your program in both
+with and without wxUSE\_STL.
+
 \wxheading{Derived from}
 
 None
@@ -1274,7 +1269,7 @@ None
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
-\membersection{wxStringBuffer::wxStringBuffer}
+\membersection{wxStringBuffer::wxStringBuffer}\label{wxstringbufferctor}
 
 \func{}{wxStringBuffer}{\param{const wxString\& }{str}, \param{size\_t }{len}}
 
@@ -1283,16 +1278,92 @@ and containing enough space for at least {\it len} characters. Basically, this
 is equivalent to calling \helpref{GetWriteBuf}{wxstringgetwritebuf} and
 saving the result.
 
-\membersection{wxStringBuffer::\destruct{wxStringBuffer}}
+\membersection{wxStringBuffer::\destruct{wxStringBuffer}}\label{wxstringbufferdtor}
 
 \func{}{\destruct{wxStringBuffer}}{\void}
 
 Restores the string passed to the constructor to the usable state by calling 
 \helpref{UngetWriteBuf}{wxstringungetwritebuf} on it.
 
-\membersection{wxStringBuffer::operator wxChar *}
+\membersection{wxStringBuffer::operator wxChar *}\label{wxstringbufferwxchar}
+
+\func{wxChar *}{operator wxChar *}{\void}
+
+Returns the writable pointer to a buffer of the size at least equal to the
+length specified in the constructor.
+
+
+
+\section{\class{wxStringBufferLength}}\label{wxstringbufferlength}
+
+This tiny class allows to conveniently access the \helpref{wxString}{wxstring} 
+internal buffer as a writable pointer without any risk of forgetting to restore
+the string to the usable state later, and allows the user to set the internal
+length of the string.
+
+For example, assuming you have a low-level OS function called 
+{\tt int GetMeaningOfLifeAsString(char *)} copying the value in the provided
+buffer (which must be writable, of course), and returning the actual length
+of the string, you might call it like this:
+
+\begin{verbatim}
+    wxString theAnswer;
+    wxStringBuffer theAnswerBuffer(theAnswer, 1024);
+    int nLength = GetMeaningOfLifeAsString(theAnswerBuffer);
+    theAnswerBuffer.SetLength(nLength);
+    if ( theAnswer != "42" )
+    {
+        wxLogError("Something is very wrong!");
+    }
+\end{verbatim}
+
+Note that the exact usage of this depends on whether on not wxUSE\_STL is enabled.  If
+wxUSE\_STL is enabled, wxStringBuffer creates a seperate empty character buffer, and
+if wxUSE\_STL is disabled, it uses GetWriteBuf() from wxString, keeping the same buffer
+wxString uses intact.  In other words, relying on wxStringBuffer containing the old 
+wxString data is probably not a good idea if you want to build your program in both
+with and without wxUSE\_STL.
+
+Note that SetLength {\tt must} be called before wxStringBufferLength destructs.
+
+\wxheading{Derived from}
+
+None
+
+\wxheading{Include files}
+
+<wx/string.h>
+
+\latexignore{\rtfignore{\wxheading{Members}}}
+
+\membersection{wxStringBufferLength::wxStringBufferLength}\label{wxstringbufferlengthctor}
+
+\func{}{wxStringBufferLength}{\param{const wxString\& }{str}, \param{size\_t }{len}}
+
+Constructs a writable string buffer object associated with the given string
+and containing enough space for at least {\it len} characters. Basically, this
+is equivalent to calling \helpref{GetWriteBuf}{wxstringgetwritebuf} and
+saving the result.
+
+\membersection{wxStringBufferLength::\destruct{wxStringBufferLength}}\label{wxstringbufferlengthdtor}
+
+\func{}{\destruct{wxStringBufferLength}}{\void}
+
+Restores the string passed to the constructor to the usable state by calling 
+\helpref{UngetWriteBuf}{wxstringungetwritebuf} on it.
+
+\membersection{wxStringBufferLength::SetLength}\label{wxstringbufferlengthsetlength}
+
+\func{void}{SetLength}{\param{size\_t }{nLength}}
+
+Sets the internal length of the string referred to by wxStringBufferLength to 
+{\it nLength} characters.
+
+Must be called before wxStringBufferLength destructs.
+
+\membersection{wxStringBufferLength::operator wxChar *}\label{wxstringbufferlengthwxchar}
 
-\constfunc{wxChar *}{operator wxChar *}{\void}
+\func{wxChar *}{operator wxChar *}{\void}
 
 Returns the writable pointer to a buffer of the size at least equal to the
 length specified in the constructor.
