X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/cc81d32f2bf8c159f3b1bf6ddaf62e6d77720209..a607d8d633e055fc5cea22c0b829cd65b5c3dbfb:/docs/latex/wx/tstring.tex?ds=sidebyside diff --git a/docs/latex/wx/tstring.tex b/docs/latex/wx/tstring.tex index dce111c7cb..fa25faee5e 100644 --- a/docs/latex/wx/tstring.tex +++ b/docs/latex/wx/tstring.tex @@ -2,12 +2,13 @@ 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 (traditional, 7 or 8 bit, characters) as well as Unicode (wide characters) strings. @@ -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, @@ -52,10 +53,10 @@ operations are supported as well. 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 wxWindows} And, of course, this class is used everywhere -inside wxWindows so there is no performance loss which would result from +\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 @@ -64,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} @@ -130,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 @@ -166,20 +167,8 @@ vastly better from a performance point of view than a wxObjectArray of wxStrings \subsection{Reference counting and why you shouldn't care about it}\label{wxstringrefcount} -wxString objects use a technique known as {\it copy on write} (COW). This means -that when a string is assigned to another, no copying really takes place: only -the reference count on the shared string data is incremented and both strings -share the same data. - -But as soon as one of the two (or more) strings is modified, the data has to be -copied because the changes to one of the strings shouldn't be seen in the -others. As data copying only happens when the string is written to, this is -known as COW. - -What is important to understand is that all this happens absolutely -transparently to the class users and that whether a string is shared or not is -not seen from the outside of the class - in any case, the result of any -operation on it is the same. +All considerations for wxObject-derived \helpref{reference counted}{trefcount} objects +are valid also for wxString, even if it does not derive from wxObject. Probably the unique case when you might want to think about reference counting is when a string character is taken from a string which is not a