|
|
|
|
@@ -4,52 +4,51 @@ Classes: \helpref{wxString}{wxstring}, \helpref{wxArrayString}{wxarray}, \helpre
|
|
|
|
|
|
|
|
|
|
\subsection{Introduction}
|
|
|
|
|
|
|
|
|
|
wxString is a class which represents a character string of arbitrary (limited by
|
|
|
|
|
{\it MAX\_INT} which is usually 2147483647 on 32 bit machines) length and containing
|
|
|
|
|
arbitrary characters (i.e. ASCII NUL character is allowed, although care should be
|
|
|
|
|
taken when passing strings containing it to other functions).
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
wxString only works with ASCII (8 bit characters) strings as of this release,
|
|
|
|
|
however support for UNICODE (16 but characters) is planned for the next one.
|
|
|
|
|
but support for UNICODE (16 but characters) is planned for the next one.
|
|
|
|
|
|
|
|
|
|
This class has all 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),
|
|
|
|
|
construction from other strings, C strings and characters, assignment operators,
|
|
|
|
|
access to separate characters, string concatenation and comparison, substring
|
|
|
|
|
access to individual characters, string concatenation and comparison, substring
|
|
|
|
|
extraction, case conversion, trimming and padding (with spaces), searching and
|
|
|
|
|
replacing and both C-like \helpref{Printf()}{wxstringprintf} and stream-like
|
|
|
|
|
insertion functions as well as much else - see \helpref{wxString}{wxstring}
|
|
|
|
|
for the 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}
|
|
|
|
|
|
|
|
|
|
The advantages of using a special string class instead of working directly with
|
|
|
|
|
C strings are so obvious (the most imoprtant being, of course, the need to always
|
|
|
|
|
remember to allocate/free memory for C strings unless the programmer prefers
|
|
|
|
|
working with fixed size buffers which almost certainly leads to the dreaded
|
|
|
|
|
buffer overflows) that there is a huge number of such classes available and now,
|
|
|
|
|
finally, C++ even has one (std::string) in standard. Why use wxString then?
|
|
|
|
|
C strings are so obvious that there is a huge number of such classes available.
|
|
|
|
|
The most important advantage is the need to always
|
|
|
|
|
remember to allocate/free memory for C strings; working with fixed size buffers almost inevitably leads to buffer overflows).
|
|
|
|
|
At last, C++ has a standard string class (std::string). So why the need for wxString?
|
|
|
|
|
|
|
|
|
|
There are several advantages:
|
|
|
|
|
|
|
|
|
|
\begin{enumerate}\itemsep=0pt
|
|
|
|
|
\item {\bf Efficiency} This class was made to be as efficient as possible: both
|
|
|
|
|
in terms of size (each wxString objects takes exactly the same place as {\it
|
|
|
|
|
char *} pointer, \helpref{reference counting}{wxstringrefcount}) and speed.
|
|
|
|
|
in terms of size (each wxString objects takes exactly the same space as a {\it
|
|
|
|
|
char *} pointer, sing \helpref{reference counting}{wxstringrefcount}) and speed.
|
|
|
|
|
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
|
|
|
|
|
class and 90\% of functionality of std::string class.
|
|
|
|
|
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,
|
|
|
|
|
\helpref{AfterFirst}{wxstringafterfirst},
|
|
|
|
|
\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 construction from
|
|
|
|
|
an UNICODE string, but in the next one it will be capable of also storing its
|
|
|
|
|
\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
|
|
|
|
|
@@ -73,15 +72,15 @@ 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 the situations when there is no correspondinw std::string function, please
|
|
|
|
|
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
|
|
|
|
|
which are deprecated and risk to disappear in future versions.
|
|
|
|
|
which are deprecated and may disappear in future versions.
|
|
|
|
|
|
|
|
|
|
\subsection{Some advice about using wxString}\label{wxstringadvices}
|
|
|
|
|
|
|
|
|
|
Probably the main trap with using this class is the implicit conversion operator to
|
|
|
|
|
{\it const char *}. It is advised that you use \helpref{c\_str()}{wxstringcstr}
|
|
|
|
|
instead of it to clearly indicate when the conversion is done. Specifically, the
|
|
|
|
|
instead to clearly indicate when the conversion is done. Specifically, the
|
|
|
|
|
danger of this implicit conversion may be seen in the following code fragment:
|
|
|
|
|
|
|
|
|
|
\begin{verbatim}
|
|
|
|
|
@@ -120,7 +119,7 @@ The second bug is that returning {\it output} doesn't work. The implicit cast is
|
|
|
|
|
used again, so the code compiles, but as it returns a pointer to a buffer
|
|
|
|
|
belonging to a local variable which is deleted as soon as the function exits,
|
|
|
|
|
its contents is totally arbitrary. The solution to this problem is also easy:
|
|
|
|
|
just make the function return wxString instead of C string.
|
|
|
|
|
just make the function return wxString instead of a C string.
|
|
|
|
|
|
|
|
|
|
This leads us to the following general advice: all functions taking string
|
|
|
|
|
arguments should take {\it const wxString\&} (this makes assignment to the
|
|
|
|
|
@@ -131,13 +130,13 @@ variables.
|
|
|
|
|
|
|
|
|
|
\subsection{Other string related functions and classes}
|
|
|
|
|
|
|
|
|
|
As any program operates with character strings, the standard C library provides quite a
|
|
|
|
|
few of functions to work with them. Unfortunately, some of them have rather non
|
|
|
|
|
intuitive behaviour (like strncpy() which doesn't always terminate the resulting
|
|
|
|
|
string with a NUL) and are in general not very safe (passing NULL to them will
|
|
|
|
|
probably lead to program crash). Moreover, some of very useful functions are not
|
|
|
|
|
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 of global string functions which try to correct these problems:
|
|
|
|
|
also a few global string functions which try to correct these problems:
|
|
|
|
|
\helpref{IsEmpty()}{wxstringisempty} verifies whether the string is empty (returning
|
|
|
|
|
TRUE for NULL pointers), \helpref{Strlen()}{wxstringstrlen} also handles NULLs correctly
|
|
|
|
|
and returns 0 for them and \helpref{Stricmp()}{wxstringstricmp} is just a
|
|
|
|
|
@@ -149,17 +148,17 @@ There is another class which might be useful when working with wxString:
|
|
|
|
|
be broken into tokens and replaces the standard C library {\it
|
|
|
|
|
strtok()} function.
|
|
|
|
|
|
|
|
|
|
And the very last string related class is \helpref{wxArrayString}{wxarray}: it
|
|
|
|
|
And the very last string-related class is \helpref{wxArrayString}{wxarray}: it
|
|
|
|
|
is just a version of the "template" dynamic array class which is specialized to work
|
|
|
|
|
with strings. Please note that this class is specially optimized (it uses its
|
|
|
|
|
knowledge of internal structure of wxString) for storing strings and so it is
|
|
|
|
|
vastly better from performance point of view than wxObjectArray of wxString.
|
|
|
|
|
with strings. Please note that this class is specially optimized (using its
|
|
|
|
|
knowledge of the internal structure of wxString) for storing strings and so it is
|
|
|
|
|
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 increased and both strings
|
|
|
|
|
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
|
|
|
|
|
@@ -183,8 +182,8 @@ call to this operator may modify the string, its data is unshared (COW is done)
|
|
|
|
|
and so if the string was really shared there is some performance loss (both in
|
|
|
|
|
terms of speed and memory consumption). In the rare cases when this may be
|
|
|
|
|
important, you might prefer using \helpref{GetChar()}{wxstringgetchar} instead
|
|
|
|
|
of array subscript operator for this reasons. Please note that
|
|
|
|
|
\helpref{at()}{wxstringat} method has the same problem as subscript operator in
|
|
|
|
|
of the array subscript operator for this reasons. Please note that
|
|
|
|
|
\helpref{at()}{wxstringat} method has the same problem as the subscript operator in
|
|
|
|
|
this situation and so using it is not really better. Also note that if all
|
|
|
|
|
string arguments to your functions are passed as {\it const wxString\&} (see the
|
|
|
|
|
section \helpref{Some advice}{wxstringadvices}) this situation will almost
|
|
|
|
|
@@ -200,7 +199,7 @@ also read the preceding section about
|
|
|
|
|
|
|
|
|
|
For the performance reasons wxString doesn't allocate exactly the amount of
|
|
|
|
|
memory needed for each string. Instead, it adds a small amount of space to each
|
|
|
|
|
allocated block which allows it to not reallocate memory (this is a relatively
|
|
|
|
|
allocated block which allows it to not reallocate memory (a relatively
|
|
|
|
|
expensive operation) too often as when, for example, a string is constructed by
|
|
|
|
|
subsequently adding one character at a time to it, as for example in:
|
|
|
|
|
|
|
|
|
|
|
Julian Smart