added unit tests for wxStringStreams

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

diff --git a/docs/latex/wx/wxstring.tex b/docs/latex/wx/wxstring.tex
index a77d3324f7005bc22b811b3c37b4f97217193c99..0f230c8482b37bc79457f81fa8f944affff5b37a 100644 (file)
--- a/docs/latex/wx/wxstring.tex
+++ b/docs/latex/wx/wxstring.tex
@@ -6,7 +6,15 @@ there, wxString implements about 90\% of methods of the std::string class (itera
 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
 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.
+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.

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


@@ -71,6 +79,9 @@ use it.
 \helpref{Last}{wxstringlast}\\
 \helpref{operator []}{wxstringoperatorbracket}\\
 \helpref{c\_str}{wxstringcstr}\\
 \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}
 \helpref{operator const char*}{wxstringoperatorconstcharpt}
 
 \membersection{Concatenation}


@@ -203,9 +214,9 @@ Other string functions.
 \helpref{Pad}{wxstringpad}\\
 \helpref{Truncate}{wxstringtruncate}
 
 \helpref{Pad}{wxstringpad}\\
 \helpref{Truncate}{wxstringtruncate}
 

-\membersection{wxWindows 1.xx compatibility functions}
+\membersection{wxWidgets 1.xx compatibility functions}

 
 

-These functions are deprecated, please consider using new wxWindows 2.0
+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}\\
 functions instead of them (or, even better, std::string compatible variants).
 
 \helpref{SubString}{wxstringsubstring}\\


@@ -389,7 +400,7 @@ their documentation.
 
 \func{}{wxString}{\void}
 
 
 \func{}{wxString}{\void}
 

-Default constructor.
+Default constructor. Initializes the string to {\tt ""} (empty string).

 
 \func{}{wxString}{\param{const wxString\&}{ x}}
 
 
 \func{}{wxString}{\param{const wxString\&}{ x}}
 


@@ -402,7 +413,7 @@ Constructs a string of {\it n} copies of character {\it ch}.
 \func{}{wxString}{\param{const char*}{ psz}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}
 
 Takes first {\it nLength} characters from the C string {\it psz}.
 \func{}{wxString}{\param{const char*}{ psz}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}
 
 Takes first {\it nLength} characters from the C string {\it psz}.

-The default value of wxSTRING\_MAXLEN means to take all the string.
+The default value of {\tt wxSTRING\_MAXLEN} means to take all the string.

 
 Note that this constructor may be used even if {\it psz} points to a buffer
 with binary data (i.e. containing {\tt NUL} characters) as long as you provide
 
 Note that this constructor may be used even if {\it psz} points to a buffer
 with binary data (i.e. containing {\tt NUL} characters) as long as you provide


@@ -414,11 +425,36 @@ results otherwise.
 \func{}{wxString}{\param{const unsigned char*}{ psz}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}
 
 For compilers using unsigned char: takes first {\it nLength} characters from the C string {\it psz}.
 \func{}{wxString}{\param{const unsigned char*}{ psz}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}
 
 For compilers using unsigned char: takes first {\it nLength} characters from the C string {\it psz}.

-The default value of wxSTRING\_MAXLEN means take all the string.
+The default value of {\tt wxSTRING\_MAXLEN} means take all the string.
+
+{\bf Note:} In Unicode build, all of the above constructors take
+{\tt wchar\_t} arguments instead of {\tt char}.
+
+\wxheading{Constructors with conversion}
+
+The following constructors allow you to construct wxString from wide string
+in ANSI build or from C string in Unicode build.
+
+\func{}{wxString}{\param{const wchar\_t*}{ psz}, \param{wxMBConv\&}{ conv}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}
+
+Initializes the string from first \arg{nLength} characters of wide string. 
+The default value of {\tt wxSTRING\_MAXLEN} means take all the string.
+In ANSI build, \arg{conv}'s 
+\helpref{WC2MB}{wxmbconvwc2mb} method is called to
+convert \arg{psz} to wide string. It is ignored in Unicode build.

 
 

-\func{}{wxString}{\param{const wchar\_t*}{ psz}}
+\func{}{wxString}{\param{const char*}{ psz}, \param{wxMBConv\&}{ conv}, \param{size\_t}{ nLength = wxSTRING\_MAXLEN}}

 
 

-Constructs a string from the wide (UNICODE) string.
+Initializes the string from first \arg{nLength} characters of C string.
+The default value of {\tt wxSTRING\_MAXLEN} means take all the string.
+In Unicode build, \arg{conv}'s 
+\helpref{MB2WC}{wxmbconvmb2wc} method is called to
+convert \arg{psz} to wide string. It is ignored in ANSI build.
+
+\wxheading{See also}
+
+\helpref{wxMBConv classes}{mbconvclasses}, \helpref{mb\_str}{wxstringmbstr},
+\helpref{wc\_str}{wxstringwcstr}

 
 \membersection{wxString::\destruct{wxString}}\label{wxstringdestruct}
 
 
 \membersection{wxString::\destruct{wxString}}\label{wxstringdestruct}
 


@@ -506,7 +542,13 @@ Returns the empty string if {\it ch} is not found.
 
 \constfunc{const char *}{c\_str}{\void}
 
 
 \constfunc{const char *}{c\_str}{\void}
 

-Returns a pointer to the string data.
+Returns a pointer to the string data ({\tt const char*} in ANSI build,
+{\tt const wchar\_t*} in Unicode build).
+
+\wxheading{See also}
+
+\helpref{mb\_str}{wxstringmbstr}, \helpref{wc\_str}{wxstringwcstr},
+\helpref{fn\_str}{wxstringfnstr}

 
 \membersection{wxString::Clear}\label{wxstringclear}
 
 
 \membersection{wxString::Clear}\label{wxstringclear}
 


@@ -577,15 +619,32 @@ Searches for the given string. Returns the starting index, or -1 if not found.
 
 \membersection{wxString::First}\label{wxstringfirst}
 
 
 \membersection{wxString::First}\label{wxstringfirst}
 

-\func{size\_t}{First}{\param{char}{ c}}
+\func{int}{First}{\param{char}{ c}}

 
 

-\constfunc{size\_t}{First}{\param{const char*}{ psz}}
+\constfunc{int}{First}{\param{const char*}{ psz}}

 
 

-\constfunc{size\_t}{First}{\param{const wxString\&}{ str}}
+\constfunc{int}{First}{\param{const wxString\&}{ str}}

 
 

-\constfunc{size\_t}{First}{\param{const char}{ ch}}
+Same as \helpref{Find}{wxstringfind}.

 
 

-Returns the first occurrence of the item.
+\membersection{wxString::fn\_str}\label{wxstringfnstr}
+
+\constfunc{const wchar\_t*}{fn\_str}{\void}
+
+\constfunc{const char*}{fn\_str}{\void}
+
+\constfunc{const wxCharBuffer}{fn\_str}{\void}
+
+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
+the OS.
+
+\wxheading{See also}
+
+\helpref{wxMBConv}{wxmbconv},
+\helpref{wc\_str}{wxstringwcstr}, \helpref{mb\_str}{wxstringwcstr}

 
 \membersection{wxString::Format}\label{wxstringformat}
 
 
 \membersection{wxString::Format}\label{wxstringformat}
 


@@ -615,6 +674,18 @@ This static function returns the string containing the result of calling
 
 Returns the number of occurrences of {\it ch} in the string.
 
 
 Returns the number of occurrences of {\it ch} in the string.
 

+\membersection{wxString::FromAscii}\label{wxstringfromascii}
+
+\func{static wxString }{FromAscii}{\param{const char*}{ s}}
+
+\func{static wxString }{FromAscii}{\param{const char}{ c}}
+
+Converts the string or character from an ASCII, 7-bit form
+to the native wxString representation. Most useful when using
+a Unicode build of wxWidgets.
+Use \helpref{wxString constructors}{wxstringconstruct} if you
+need to convert from another charset.
+

 \membersection{wxString::GetChar}\label{wxstringgetchar}
 
 \constfunc{char}{GetChar}{\param{size\_t}{ n}}
 \membersection{wxString::GetChar}\label{wxstringgetchar}
 
 \constfunc{char}{GetChar}{\param{size\_t}{ n}}


@@ -625,7 +696,7 @@ Returns the character at position {\it n} (read-only).
 
 \constfunc{const char*}{GetData}{\void}
 
 
 \constfunc{const char*}{GetData}{\void}
 

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

 
 \membersection{wxString::GetWritableChar}\label{wxstringgetwritablechar}
 
 
 \membersection{wxString::GetWritableChar}\label{wxstringgetwritablechar}
 


@@ -635,9 +706,11 @@ Returns a reference to the character at position {\it n}.
 
 \membersection{wxString::GetWriteBuf}\label{wxstringgetwritebuf}
 
 
 \membersection{wxString::GetWriteBuf}\label{wxstringgetwritebuf}
 

-\func{char*}{GetWriteBuf}{\param{size\_t}{ len}}
+\func{wxChar*}{GetWriteBuf}{\param{size\_t}{ len}}

 
 Returns a writable buffer of at least {\it len} bytes.
 
 Returns a writable buffer of at least {\it len} bytes.

+It returns a pointer to a new memory block, and the
+existing data will not be copied.

 
 Call \helpref{wxString::UngetWriteBuf}{wxstringungetwritebuf} as soon as possible
 to put the string back into a reasonable state.
 
 Call \helpref{wxString::UngetWriteBuf}{wxstringungetwritebuf} as soon as possible
 to put the string back into a reasonable state.


@@ -646,8 +719,6 @@ to put the string back into a reasonable state.
 
 \constfunc{size\_t}{Index}{\param{char}{ ch}}
 
 
 \constfunc{size\_t}{Index}{\param{char}{ ch}}
 

-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}}
 
 Same as \helpref{wxString::Find}{wxstringfind}.


@@ -764,15 +835,15 @@ Same as MakeLower.
 
 \membersection{wxString::MakeLower}\label{wxstringmakelower}
 
 
 \membersection{wxString::MakeLower}\label{wxstringmakelower}
 

-\func{void}{MakeLower}{\void}
+\func{wxString\&}{MakeLower}{\void}

 
 

-Converts all characters to lower case.
+Converts all characters to lower case and returns the result.

 
 \membersection{wxString::MakeUpper}\label{wxstringmakeupper}
 
 
 \membersection{wxString::MakeUpper}\label{wxstringmakeupper}
 

-\func{void}{MakeUpper}{\void}
+\func{wxString\&}{MakeUpper}{\void}

 
 

-Converts all characters to upper case.
+Converts all characters to upper case and returns the result.

 
 \membersection{wxString::Matches}\label{wxstringmatches}
 
 
 \membersection{wxString::Matches}\label{wxstringmatches}
 


@@ -780,6 +851,24 @@ Converts all characters to upper case.
 
 Returns true if the string contents matches a mask containing '*' and '?'.
 
 
 Returns true if the string contents matches a mask containing '*' and '?'.
 

+\membersection{wxString::mb\_str}\label{wxstringmbstr}
+
+\constfunc{const char*}{mb\_str}{\param{wxMBConv\&}{ conv}}
+
+\constfunc{const wxCharBuffer}{mb\_str}{\param{wxMBConv\&}{ conv}}
+
+Returns multibyte (C string) representation of the string.
+In Unicode build, converts using \arg{conv}'s \helpref{cWC2MB}{wxmbconvcwc2mb}
+method and returns wxCharBuffer. In ANSI build, this function is same
+as \helpref{c\_str}{wxstringcstr}.
+The macro wxWX2MBbuf is defined as the correct return type (without const).
+
+\wxheading{See also}
+
+\helpref{wxMBConv}{wxmbconv},
+\helpref{c\_str}{wxstringcstr}, \helpref{wc\_str}{wxstringwcstr},
+\helpref{fn\_str}{wxstringfnstr}
+

 \membersection{wxString::Mid}\label{wxstringmid}
 
 \constfunc{wxString}{Mid}{\param{size\_t}{ first}, \param{size\_t}{ count = wxSTRING\_MAXLEN}}
 \membersection{wxString::Mid}\label{wxstringmid}
 
 \constfunc{wxString}{Mid}{\param{size\_t}{ first}, \param{size\_t}{ count = wxSTRING\_MAXLEN}}


@@ -902,6 +991,21 @@ have different meaning).
 Returns the part of the string between the indices {\it from} and {\it to}
 inclusive.
 
 Returns the part of the string between the indices {\it from} and {\it to}
 inclusive.
 

+\membersection{wxString::ToAscii}\label{wxstringtoascii}
+
+\constfunc{const char*}{ToAscii}{\void}
+
+Converts the string to an ASCII, 7-bit string (ANSI builds only).
+
+\constfunc{const wxCharBuffer}{ToAscii}{\void}
+
+Converts the string to an ASCII, 7-bit string in the form of
+a wxCharBuffer (Unicode builds only).
+
+Note that this conversion only works if the string contains only ASCII
+characters. The \helpref{mb\_str}{wxstringmbstr} method provides more
+powerful means of converting wxString to C string.
+

 \membersection{wxString::ToDouble}\label{wxstringtodouble}
 
 \constfunc{bool}{ToDouble}{\param{double}{ *val}}
 \membersection{wxString::ToDouble}\label{wxstringtodouble}
 
 \constfunc{bool}{ToDouble}{\param{double}{ *val}}


@@ -995,6 +1099,24 @@ Returns this string converted to upper case.
 
 The same as MakeUpper.
 
 
 The same as MakeUpper.
 

+\membersection{wxString::wc\_str}\label{wxstringwcstr}
+
+\constfunc{const wchar\_t*}{wc\_str}{\param{wxMBConv\&}{ conv}}
+
+\constfunc{const wxWCharBuffer}{wc\_str}{\param{wxMBConv\&}{ conv}}
+
+Returns wide character representation of the string.
+In ANSI build, converts using \arg{conv}'s \helpref{cMB2WC}{wxmbconvcmb2wc}
+method and returns wxWCharBuffer. In Unicode build, this function is same
+as \helpref{c\_str}{wxstringcstr}.
+The macro wxWX2WCbuf is defined as the correct return type (without const).
+
+\wxheading{See also}
+
+\helpref{wxMBConv}{wxmbconv},
+\helpref{c\_str}{wxstringcstr}, \helpref{mb\_str}{wxstringwcstr},
+\helpref{fn\_str}{wxstringfnstr}
+

 \membersection{wxString::operator!}\label{wxstringoperatornot}
 
 \constfunc{bool}{operator!}{\void}
 \membersection{wxString::operator!}\label{wxstringoperatornot}
 
 \constfunc{bool}{operator!}{\void}