corrected EVT_NOTIFY[_RANGE] docs (bug 1439078)

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

diff --git a/docs/latex/wx/wxstring.tex b/docs/latex/wx/wxstring.tex
index b9a50317541c57b213e94dbfddf4c139e29b30e4..85529acf02889abe8faa0a2b7c37af35be4f3816 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


@@ -119,7 +124,8 @@ length of the prefix then.
 \helpref{CmpNoCase}{wxstringcmpnocase}\\
 \helpref{IsSameAs}{wxstringissameas}\\
 \helpref{Matches}{wxstringmatches}\\
 \helpref{CmpNoCase}{wxstringcmpnocase}\\
 \helpref{IsSameAs}{wxstringissameas}\\
 \helpref{Matches}{wxstringmatches}\\

-\helpref{StartsWith}{wxstringstartswith}
+\helpref{StartsWith}{wxstringstartswith}\\
+\helpref{EndsWith}{wxstringendswith}

 
 \membersection{Substring extraction}\label{substringextractioninwxstring}
 
 
 \membersection{Substring extraction}\label{substringextractioninwxstring}
 


@@ -135,7 +141,9 @@ substring.
 \helpref{BeforeLast}{wxstringbeforelast}\\
 \helpref{AfterFirst}{wxstringafterfirst}\\
 \helpref{AfterLast}{wxstringafterlast}\\
 \helpref{BeforeLast}{wxstringbeforelast}\\
 \helpref{AfterFirst}{wxstringafterfirst}\\
 \helpref{AfterLast}{wxstringafterlast}\\

-\helpref{StartsWith}{wxstringstartswith}
+\helpref{StartsWith}{wxstringstartswith}\\
+\helpref{EndsWith}{wxstringendswith}
+

 
 \membersection{Case conversion}\label{caseconversioninwxstring}
 
 
 \membersection{Case conversion}\label{caseconversioninwxstring}
 


@@ -540,7 +548,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 +568,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 +582,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 +650,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 +671,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 +706,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 +735,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!


@@ -895,6 +897,19 @@ Prepends {\it str} to this string, returning a reference to this string.
 Similar to the standard function {\it sprintf()}. Returns the number of
 characters written, or an integer less than zero on error.
 
 Similar to the standard function {\it sprintf()}. Returns the number of
 characters written, or an integer less than zero on error.
 

+Note that if {\tt wxUSE\_PRINTF\_POS\_PARAMS} is set to 1, then this function supports
+Unix98-style positional parameters:
+
+\begin{verbatim}
+    wxString str;
+
+    str.Printf(wxT("%d %d %d"), 1, 2, 3);
+    // str now contains "1 2 3"
+
+    str.Printf(wxT("%2$d %3$d %1$d"), 1, 2, 3);
+    // str now contains "2 3 1"
+\end{verbatim}
+

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


@@ -915,7 +930,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}
 


@@ -968,6 +983,16 @@ 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}.
 
 {\tt NULL}. Otherwise, the function returns {\tt false} and doesn't modify the 
 {\it rest}.
 

+\membersection{wxString::EndsWith}\label{wxstringendswith}
+
+\constfunc{bool}{EndsWith}{\param{const wxChar }{*suffix}, \param{wxString }{*rest = NULL}}
+
+This function can be used to test if the string ends with the specified 
+{\it suffix}. If it does, the function will return {\tt true} and put the
+beginning of the string before the suffix 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}
 \membersection{wxString::Strip}\label{wxstringstrip}
 
 \begin{verbatim}


@@ -1043,10 +1068,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.


@@ -1060,7 +1088,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}
 


@@ -1166,11 +1195,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.
 


@@ -1262,6 +1293,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


@@ -1320,6 +1358,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}


@@ -1334,7 +1379,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