X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7ae8ee141c2c5415a787220a6683ae77b1ceb20e..c00fed0ef4d70c9b45d9b8405f636d30eadb7ea6:/docs/latex/wx/tstring.tex diff --git a/docs/latex/wx/tstring.tex b/docs/latex/wx/tstring.tex index 74f1763fe8..17acb3070c 100644 --- a/docs/latex/wx/tstring.tex +++ b/docs/latex/wx/tstring.tex @@ -2,15 +2,16 @@ Classes: \helpref{wxString}{wxstring}, \helpref{wxArrayString}{wxarraystring}, \helpref{wxStringTokenizer}{wxstringtokenizer} -\subsection{Introduction} +\subsection{Introduction}\label{introductiontowxstring} wxString is a class which represents a character string of arbitrary length (limited by {\it MAX\_INT} which is usually 2147483647 on 32 bit machines) and containing -arbitrary characters. The ASCII NUL character is allowed, although care should be -taken when passing strings containing it to other functions. +arbitrary characters. The ASCII NUL character is allowed, but be aware that +in the current string implementation some methods might not work correctly +in this case. -wxString works with both ASCII (8 bit characters) as well as UNICODE (16 but -characters) strings. +wxString works with both ASCII (traditional, 7 or 8 bit, characters) as well as +Unicode (wide characters) strings. This class has all the standard operations you can expect to find in a string class: dynamic memory management (string extends to accommodate new characters), @@ -21,7 +22,7 @@ replacing and both C-like \helpref{Printf()}{wxstringprintf} and stream-like insertion functions as well as much more - see \helpref{wxString}{wxstring} for a list of all functions. -\subsection{Comparison of wxString to other string classes} +\subsection{Comparison of wxString to other string classes}\label{otherstringclasses} The advantages of using a special string class instead of working directly with C strings are so obvious that there is a huge number of such classes available. @@ -40,7 +41,7 @@ It also provides performance \helpref{statistics gathering code}{wxstringtuning} which may be enabled to fine tune the memory allocation strategy for your particular application - and the gain might be quite big. \item {\bf Compatibility} This class tries to combine almost full compatibility -with the old wxWindows 1.xx wxString class, some reminiscence to MFC CString +with the old wxWidgets 1.xx wxString class, some reminiscence to MFC CString class and 90\% of the functionality of std::string class. \item {\bf Rich set of functions} Some of the functions present in wxString are very useful but don't exist in most of other string classes: for example, @@ -48,13 +49,14 @@ very useful but don't exist in most of other string classes: for example, \helpref{BeforeLast}{wxstringbeforelast}, \helpref{operator<<}{wxstringoperatorout} or \helpref{Printf}{wxstringprintf}. Of course, all the standard string operations are supported as well. -\item {\bf UNICODE} In this release, wxString only supports {\it construction} from -a UNICODE string, but in the next one it will be capable of also storing its -internal data in either ASCII or UNICODE format. -\item {\bf Used by wxWindows} And, of course, this class is used everywhere -inside wxWindows so there is no performance loss which would result from +\item {\bf Unicode} wxString is Unicode friendly: it allows to easily convert +to and from ANSI and Unicode strings in any build mode (see the +\helpref{Unicode overview}{unicode} for more details) and maps to either +{\tt string} or {\tt wstring} transparently depending on the current mode. +\item {\bf Used by wxWidgets} And, of course, this class is used everywhere +inside wxWidgets so there is no performance loss which would result from conversions of objects of any other string class (including std::string) to -wxString internally by wxWindows. +wxString internally by wxWidgets. \end{enumerate} However, there are several problems as well. The most important one is probably @@ -63,18 +65,18 @@ example, to get the length of the string either one of length(), \helpref{Len()}{wxstringlen} or \helpref{Length()}{wxstringlength} may be used. The first function, as almost all the other functions in lowercase, is std::string compatible. The second one -is "native" wxString version and the last one is wxWindows 1.xx way. So the +is "native" wxString version and the last one is wxWidgets 1.xx way. So the question is: which one is better to use? And the answer is that: {\bf The usage of std::string compatible functions is strongly advised!} It will both make your code more familiar to other C++ programmers (who are supposed to have knowledge of std::string but not of wxString), let you reuse the same code -in both wxWindows and other programs (by just typedefing wxString as std::string -when used outside wxWindows) and by staying compatible with future versions of -wxWindows which will probably start using std::string sooner or later too. +in both wxWidgets and other programs (by just typedefing wxString as std::string +when used outside wxWidgets) and by staying compatible with future versions of +wxWidgets which will probably start using std::string sooner or later too. In the situations where there is no corresponding std::string function, please -try to use the new wxString methods and not the old wxWindows 1.xx variants +try to use the new wxString methods and not the old wxWidgets 1.xx variants which are deprecated and may disappear in future versions. \subsection{Some advice about using wxString}\label{wxstringadvices} @@ -129,7 +131,7 @@ strings inside the function faster because of strings should return {\it wxString} - this makes it safe to return local variables. -\subsection{Other string related functions and classes} +\subsection{Other string related functions and classes}\label{relatedtostring} As most programs use character strings, the standard C library provides quite a few functions to work with them. Unfortunately, some of them have rather @@ -139,7 +141,7 @@ to them will probably lead to program crash). Moreover, some very useful functions are not standard at all. This is why in addition to all wxString functions, there are also a few global string functions which try to correct these problems: \helpref{wxIsEmpty()}{wxisempty} verifies whether the string -is empty (returning {\tt TRUE} for {\tt NULL| pointers), +is empty (returning {\tt true} for {\tt NULL} pointers), \helpref{wxStrlen()}{wxstrlen} also handles NULLs correctly and returns 0 for them and \helpref{wxStricmp()}{wxstricmp} is just a platform-independent version of case-insensitive string comparison function known either as