added vendor display name (for consistency with app display name &c) (patch 1831303)

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

diff --git a/docs/latex/wx/tstring.tex b/docs/latex/wx/tstring.tex
index 4bd1f1aa26dd9ef271f6b72ed8d21df01d64840e..fa25faee5eec8c7233b863345c4d4c0868d18f96 100644 (file)
--- a/docs/latex/wx/tstring.tex
+++ b/docs/latex/wx/tstring.tex
@@ -2,18 +2,19 @@
 
 Classes: \helpref{wxString}{wxstring}, \helpref{wxArrayString}{wxarraystring}, \helpref{wxStringTokenizer}{wxstringtokenizer}
 
 
 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
 
 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 only works with ASCII (8 bit characters) strings as of this release,
-but support for UNICODE (16 but characters) is planned for the next one.
+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:
 
 This class has all the standard operations you can expect to find in a string class:

-dynamic memory management (string extends to accomodate new characters),
+dynamic memory management (string extends to accommodate new characters),

 construction from other strings, C strings and characters, assignment operators,
 access to individual characters, string concatenation and comparison, substring
 extraction, case conversion, trimming and padding (with spaces), searching and
 construction from other strings, C strings and characters, assignment operators,
 access to individual characters, string concatenation and comparison, substring
 extraction, case conversion, trimming and padding (with spaces), searching and


@@ -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.
 
 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.
 
 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
 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, 
 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,33 +49,34 @@ 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.
 \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
 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
 that there are often several functions to do exactly the same thing: for
 example, to get the length of the string either one of 
 \end{enumerate}
 
 However, there are several problems as well. The most important one is probably
 that there are often several functions to do exactly the same thing: for
 example, to get the length of the string either one of 

-\helpref{length()}{wxstringlength}, \helpref{Len()}{wxstringlen} or 
-\helpref{Length()}{wxstringLength} may be used. The first function, as almost
+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
 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
 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 correspondinw std::string function, please
-try to use the new wxString methods and not the old wxWindows 1.xx variants
+In the situations where there is no corresponding std::string function, please
+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}
 which are deprecated and may disappear in future versions.
 
 \subsection{Some advice about using wxString}\label{wxstringadvices}


@@ -129,20 +131,21 @@ strings inside the function faster because of
 strings should return {\it wxString} - this makes it safe to return local
 variables.
 
 strings should return {\it wxString} - this makes it safe to return local
 variables.
 

-\subsection{Other string related functions and classes}
-
-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
-counter-intuitive behaviour (like strncpy() which doesn't always terminate the resulting
-string with a NULL) and are in general not very safe (passing NULL 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{IsEmpty()}{IsEmpty} verifies whether the string is empty (returning
-TRUE for NULL pointers), \helpref{Strlen()}{Strlen} also handles NULLs correctly
-and returns 0 for them and \helpref{Stricmp()}{Stricmp} is just a
-platform-independent version of case-insensitive string comparison function
-known either as stricmp() or strcasecmp() on different platforms.
+\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
+counter-intuitive behaviour (like strncpy() which doesn't always terminate the
+resulting string with a NULL) and are in general not very safe (passing NULL
+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), 
+\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
+stricmp() or strcasecmp() on different platforms.

 
 The {\tt <wx/string.h>} header also defines \helpref{wxSnprintf}{wxsnprintf} 
 and \helpref{wxVsnprintf}{wxvsnprintf} functions which should be used instead
 
 The {\tt <wx/string.h>} header also defines \helpref{wxSnprintf}{wxsnprintf} 
 and \helpref{wxVsnprintf}{wxvsnprintf} functions which should be used instead


@@ -164,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}
 
 
 \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
-otheres. 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
 
 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


@@ -259,7 +250,7 @@ which tells the wxString class to collect performance statistics and to show
 them on stderr on program termination. This will show you the average length of
 strings your program manipulates, their average initial length and also the
 percent of times when memory wasn't reallocated when string concatenation was
 them on stderr on program termination. This will show you the average length of
 strings your program manipulates, their average initial length and also the
 percent of times when memory wasn't reallocated when string concatenation was

-done but the alread preallocated memory was used (this value should be about
+done but the already preallocated memory was used (this value should be about

 98\% for the default allocation policy, if it is less than 90\% you should
 really consider fine tuning wxString for your application).
 
 98\% for the default allocation policy, if it is less than 90\% you should
 really consider fine tuning wxString for your application).