Line-up interfaces to use size_t for GetCount()s (and count related api).

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

diff --git a/docs/latex/wx/wxstring.tex b/docs/latex/wx/wxstring.tex
index 8c01f74f11ab60d0b734a9118899ce7ef9e86c1a..e6f1334c4fcd5e4c5129e8708be48a007de63b55 100644 (file)
--- a/docs/latex/wx/wxstring.tex
+++ b/docs/latex/wx/wxstring.tex
@@ -16,6 +16,11 @@ 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.
 
 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{Derived from}
 
 None


@@ -540,7 +545,7 @@ Returns the empty string if {\it ch} is not found.
 
 \membersection{wxString::c\_str}\label{wxstringcstr}
 
 
 \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).
 
 Returns a pointer to the string data ({\tt const char*} in ANSI build,
 {\tt const wchar\_t*} in Unicode build).


@@ -560,6 +565,8 @@ See also: \helpref{Empty}{wxstringempty}
 
 \membersection{wxString::Cmp}\label{wxstringcmp}
 
 
 \membersection{wxString::Cmp}\label{wxstringcmp}
 

+\constfunc{int}{Cmp}{\param{const wxString\&}{ s}}
+

 \constfunc{int}{Cmp}{\param{const char*}{ psz}}
 
 Case-sensitive comparison.
 \constfunc{int}{Cmp}{\param{const char*}{ psz}}
 
 Case-sensitive comparison.


@@ -572,6 +579,8 @@ See also \helpref{CmpNoCase}{wxstringcmpnocase}, \helpref{IsSameAs}{wxstringissa
 
 \membersection{wxString::CmpNoCase}\label{wxstringcmpnocase}
 
 
 \membersection{wxString::CmpNoCase}\label{wxstringcmpnocase}
 

+\constfunc{int}{CmpNoCase}{\param{const wxString\&}{ s}}
+

 \constfunc{int}{CmpNoCase}{\param{const char*}{ psz}}
 
 Case-insensitive comparison.
 \constfunc{int}{CmpNoCase}{\param{const char*}{ psz}}
 
 Case-insensitive comparison.


@@ -638,7 +647,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
 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}
 the OS.
 
 \wxheading{See also}


@@ -659,7 +668,7 @@ This static function returns the string containing the result of calling
 
 \membersection{wxString::FormatV}\label{wxstringformatv}
 
 
 \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.
 
 This static function returns the string containing the result of calling 
 \helpref{PrintfV}{wxstringprintfv} with the passed parameters on it.


@@ -694,7 +703,7 @@ Returns the character at position {\it n} (read-only).
 
 \membersection{wxString::GetData}\label{wxstringgetdata}
 
 
 \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.
 
 
 wxWidgets compatibility conversion. Returns a constant pointer to the data in the string.
 


@@ -723,16 +732,6 @@ to put the string back into a reasonable state.
 
 Same as \helpref{wxString::Find}{wxstringfind}.
 
 
 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 {\tt wxNOT\_FOUND}.
-

 % TODO
 %\membersection{wxString::insert}\label{wxstringinsert}
 % Wrong!
 % TODO
 %\membersection{wxString::insert}\label{wxstringinsert}
 % Wrong!


@@ -774,9 +773,7 @@ caseSensitive is true by default (case matters).
 
 Returns true if strings are equal, false otherwise.
 
 
 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}}
 
 
 \constfunc{bool}{IsSameAs}{\param{char}{ c}, \param{bool}{ caseSensitive = true}}
 


@@ -785,7 +782,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.
 
 
 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}
 
 
 \membersection{wxString::IsWord}\label{wxstringisword}
 


@@ -917,7 +914,7 @@ 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}}
 
 
 \func{wxString\&}{Remove}{\param{size\_t}{ pos}, \param{size\_t}{ len}}
 

-Removes the {\it len} characters from the string, starting at {\it pos}.
+Removes {\it len} characters from the string, starting at {\it pos}.

 
 \membersection{wxString::RemoveLast}\label{wxstringremovelast}
 
 
 \membersection{wxString::RemoveLast}\label{wxstringremovelast}
 


@@ -1045,10 +1042,13 @@ familiar with C) results.
 
 \constfunc{bool}{ToULong}{\param{unsigned long}{ *val}, \param{int }{base = $10$}}
 
 
 \constfunc{bool}{ToULong}{\param{unsigned long}{ *val}, \param{int }{base = $10$}}
 

-Attempts to convert the string to a unsigned 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
 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.
+represent a valid number in the given base. Please notice that this function
+behaves in the same way as the standard \texttt{strtoul()} and so it simply
+converts negative numbers to unsigned representation instead of rejecting them
+(e.g. $-1$ is returned as \texttt{ULONG\_MAX}).

 
 See \helpref{wxString::ToLong}{wxstringtolong} for the more detailed
 description of the {\it base} parameter.
 
 See \helpref{wxString::ToLong}{wxstringtolong} for the more detailed
 description of the {\it base} parameter.


@@ -1062,7 +1062,8 @@ description of the {\it base} parameter.
 
 \func{wxString\&}{Trim}{\param{bool}{ fromRight = true}}
 
 
 \func{wxString\&}{Trim}{\param{bool}{ fromRight = true}}
 

-Removes spaces from the left or from the right (default).
+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).

 
 \membersection{wxString::Truncate}\label{wxstringtruncate}
 
 
 \membersection{wxString::Truncate}\label{wxstringtruncate}
 


@@ -1168,11 +1169,13 @@ Concatenation in place: the argument is appended to the string.
 
 \membersection{wxString::operator []}\label{wxstringoperatorbracket}
 
 
 \membersection{wxString::operator []}\label{wxstringoperatorbracket}
 

-\func{char\&}{operator []}{\param{size\_t}{ i}}
+\func{wxChar\&}{operator []}{\param{size\_t}{ i}}
+
+\constfunc{wxChar}{operator []}{\param{size\_t}{ i}}

 
 

-\func{char}{operator []}{\param{size\_t}{ i}}
+\func{wxChar\&}{operator []}{\param{int}{ i}}

 
 

-\func{char}{operator []}{\param{int}{ i}}
+\constfunc{wxChar}{operator []}{\param{int}{ i}}

 
 Element extraction.
 
 
 Element extraction.
 


@@ -1264,6 +1267,13 @@ buffer (which must be writable, of course) you might call it like this:
     }
 \end{verbatim}
 
     }
 \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 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 probably not a good idea if you want to build your program in both
+with and without wxUSE\_STL.
+

 \wxheading{Derived from}
 
 None
 \wxheading{Derived from}
 
 None


@@ -1322,6 +1332,13 @@ of the string, you might call it like this:
     }
 \end{verbatim}
 
     }
 \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 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 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}
 Note that SetLength {\tt must} be called before wxStringBufferLength destructs.
 
 \wxheading{Derived from}


@@ -1336,7 +1353,7 @@ None
 
 \membersection{wxStringBufferLength::wxStringBufferLength}\label{wxstringbufferlengthctor}
 
 
 \membersection{wxStringBufferLength::wxStringBufferLength}\label{wxstringbufferlengthctor}
 

-\func{}{wxStringBuffer}{\param{const wxString\& }{str}, \param{size\_t }{len}}
+\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
 
 Constructs a writable string buffer object associated with the given string
 and containing enough space for at least {\it len} characters. Basically, this