allow to optionally use vendor name component in standard paths (slightly modified...

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

diff --git a/docs/latex/wx/tstring.tex b/docs/latex/wx/tstring.tex
index 3f9ccbb41649d81d746d1e08b744e95c3f4e2a76..fa25faee5eec8c7233b863345c4d4c0868d18f96 100644 (file)
--- 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}
 
 
 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 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),
 
 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.
 
 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,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.
 \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
 \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
 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
 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
 
 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}
 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{wxIsEmpty()}{wxisempty} verifies whether the string is empty (returning
-TRUE for 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.
+\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
-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
 
 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