mention that Wait() relocks the mutex before returning (patch 1482390)

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

diff --git a/docs/latex/wx/encconv.tex b/docs/latex/wx/encconv.tex
index 2bacaf41531da66ce949b1aed6c1d1e4723c6ee2..f24df2dd1e4b52e127b6cd20b4bba85a20b70055 100644 (file)
--- a/docs/latex/wx/encconv.tex
+++ b/docs/latex/wx/encconv.tex
@@ -5,9 +5,20 @@
 
 \section{\class{wxEncodingConverter}}\label{wxencodingconverter}
 
-This class is capable of converting strings between any two
+This class is capable of converting strings between two
 8-bit encodings/charsets. It can also convert from/to Unicode (but only
-if you compiled wxWindows with wxUSE\_WCHAR\_T set to 1).
+if you compiled wxWidgets with wxUSE\_WCHAR\_T set to 1). Only a limited subset
+of encodings is supported by wxEncodingConverter:
+{\tt wxFONTENCODING\_ISO8859\_1..15}, {\tt wxFONTENCODING\_CP1250..1257} and 
+{\tt wxFONTENCODING\_KOI8}.
+
+\wxheading{Note}
+
+Please use \helpref{wxMBConv classes}{mbconvclasses} instead
+if possible. \helpref{wxCSConv}{wxcsconv} has much better support for various
+encodings than wxEncodingConverter. wxEncodingConverter is useful only
+if you rely on {\tt wxCONVERT\_SUBSTITUTE} mode of operation (see 
+\helpref{Init}{wxencodingconverterinit}).
 
 \wxheading{Derived from}
 
@@ -26,17 +37,19 @@ if you compiled wxWindows with wxUSE\_WCHAR\_T set to 1).
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 
+
 \membersection{wxEncodingConverter::wxEncodingConverter}\label{wxencodingconverterwxencodingconverter}
 
 \func{}{wxEncodingConverter}{\void}
 
 Constructor.
 
+
 \membersection{wxEncodingConverter::Init}\label{wxencodingconverterinit}
 
 \func{bool}{Init}{\param{wxFontEncoding }{input\_enc}, \param{wxFontEncoding }{output\_enc}, \param{int }{method = wxCONVERT\_STRICT}}
 
-Initialize convertion. Both output or input encoding may
+Initialize conversion. Both output or input encoding may
 be wxFONTENCODING\_UNICODE, but only if wxUSE\_ENCODING is set to 1.
 All subsequent calls to \helpref{Convert()}{wxencodingconverterconvert} 
 will interpret its argument
@@ -61,23 +74,62 @@ as input string.
 
 \wxheading{Return value} 
 
-FALSE if given conversion is impossible, TRUE otherwise
+false if given conversion is impossible, true otherwise
 (conversion may be impossible either if you try to convert
-to Unicode with non-Unicode build of wxWindows or if input
+to Unicode with non-Unicode build of wxWidgets or if input
 or output encoding is not supported.)
 
+
+\membersection{wxEncodingConverter::CanConvert}\label{wxencodingconvertercanconvert}
+
+\func{static bool}{CanConvert}{\param{wxFontEncoding }{encIn}, \param{wxFontEncoding }{encOut}}
+
+Return true if (any text in) multibyte encoding \arg{encIn} can be converted to
+another one ({\it encOut}) losslessly.
+
+Do not call this method with \texttt{wxFONTENCODING\_UNICODE} as either
+parameter, it doesn't make sense (always works in one sense and always depends
+on the text to convert in the other).
+
+
 \membersection{wxEncodingConverter::Convert}\label{wxencodingconverterconvert}
 
-\func{wxString}{Convert}{\param{const wxString\& }{input}}
+\constfunc{bool}{Convert}{\param{const char* }{input}, \param{char* }{output}}
+
+\constfunc{bool}{Convert}{\param{const wchar\_t* }{input}, \param{wchar\_t* }{output}}
 
-\func{void}{Convert}{\param{const wxChar* }{input}, \param{wxChar* }{output}}
+\constfunc{bool}{Convert}{\param{const char* }{input}, \param{wchar\_t* }{output}}
 
-\func{void}{Convert}{\param{wxChar* }{str}}
+\constfunc{bool}{Convert}{\param{const wchar\_t* }{input}, \param{char* }{output}}
 
-\func{void}{Convert}{\param{const char* }{input}, \param{wxChar* }{output}}
+Convert input string according to settings passed to
+\helpref{Init}{wxencodingconverterinit} and writes the result to {\it output}.
+
+\constfunc{bool}{Convert}{\param{char* }{str}}
+
+\constfunc{bool}{Convert}{\param{wchar\_t* }{str}}
+
+Convert input string according to settings passed to
+\helpref{Init}{wxencodingconverterinit} in-place, i.e. write the result to the
+same memory area.
+
+All of the versions above return \true if the conversion was lossless and
+\false if at least one of the characters couldn't be converted and was replaced
+with {\tt '?'} in the output. Note that if {\tt wxCONVERT\_SUBSTITUTE} was
+passed to \helpref{Init}{wxencodingconverterinit}, substitution is considered
+lossless operation.
+
+\constfunc{wxString}{Convert}{\param{const wxString\& }{input}}
+
+Convert wxString and return new wxString object.
+
+\wxheading{Notes}
+
+You must call \helpref{Init}{wxencodingconverterinit} before using this method!
+
+{\tt wchar\_t} versions of the method are not available if wxWidgets was compiled
+with {\tt wxUSE\_WCHAR\_T} set to 0.
 
-Convert input string according to settings passed to \helpref{Init}{wxencodingconverterinit}.
-Note that you must call Init before using Convert!
 
 \membersection{wxEncodingConverter::GetPlatformEquivalents}\label{wxencodingconvertergetplatformequivalents}
 
@@ -94,7 +146,7 @@ under given platform. Supported platforms:
 \item wxPLATFORM\_CURRENT
 \end{itemize}
 
-wxPLATFORM\_CURRENT means the plaform this binary was compiled for.
+wxPLATFORM\_CURRENT means the platform this binary was compiled for.
 
 Examples:
 
@@ -132,6 +184,7 @@ item of it.
 \item Please note that the returned array may contain no items at all.
 \end{itemize}
 
+
 \membersection{wxEncodingConverter::GetAllEquivalents}\label{wxencodingconvertergetallequivalents}
 
 \func{static wxFontEncodingArray}{GetAllEquivalents}{\param{wxFontEncoding }{enc}}