Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Last doxygen topic overview cleanup assigned to myself.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52168 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty
2008-02-28 03:13:22 +00:00
parent 82d1a19568
commit f05d2fde68
1 changed files with 247 additions and 231 deletions
Download Patch File Download Diff File Expand all files Collapse all files

320
docs/doxygen/overviews/string.h
View File

@@ -1,5 +1,5 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: string // Name: string.h
// Purpose: topic overview // Purpose: topic overview
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
@@ -8,198 +8,209 @@
/*! /*!
@page string_overview wxString overview @page overview_string wxString Overview
Classes: #wxString, #wxArrayString, #wxStringTokenizer Classes: wxString, wxArrayString, wxStringTokenizer
#Introduction
@ref otherstringclasses_overview @li @ref overview_string_intro
@ref stringadvices_overview @li @ref overview_string_comparison
@ref relatedtostring_overview @li @ref overview_string_advice
@ref stringrefcount_overview @li @ref overview_string_related
@ref stringtuning_overview @li @ref overview_string_refcount
@li @ref overview_string_tuning
@section introductiontowxstring Introduction <hr>
@section overview_string_intro Introduction
wxString is a class which represents a character string of arbitrary length
(limited by @c MAX_INT which is usually 2147483647 on 32 bit machines) and
containing 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 is a class which represents a character string of arbitrary length (limited by
@e MAX_INT which is usually 2147483647 on 32 bit machines) and containing
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 wxString works with both ASCII (traditional, 7 or 8 bit, characters) as well as
Unicode (wide characters) strings. 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),
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
replacing and both C-like #Printf() and stream-like
insertion functions as well as much more - see #wxString
for a list of all functions.
@section otherstringclasses Comparison of wxString to other string classes 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), 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 replacing and both C-like @c printf (wxString::Printf)
and stream-like insertion functions as well as much more - see wxString for a
list of all functions.
@section overview_string_comparison Comparison to Other String Classes
The advantages of using a special string class instead of working directly with 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. C strings are so obvious that there is a huge number of such classes available.
The most important advantage is the need to always The most important advantage is the need to always remember to allocate/free
remember to allocate/free memory for C strings; working with fixed size buffers almost memory for C strings; working with fixed size buffers almost inevitably leads
inevitably leads to buffer overflows. At last, C++ has a standard string class to buffer overflows. At last, C++ has a standard string class (std::string). So
(std::string). So why the need for wxString? why the need for wxString? There are several advantages:
There are several advantages:
@li <b>Efficiency:</b> This class was made to be as efficient as possible: both in
@b Efficiency This class was made to be as efficient as possible: both terms of size (each wxString objects takes exactly the same space as a
in terms of size (each wxString objects takes exactly the same space as a @e char * pointer, sing @ref stringrefcount_overview) and speed. <tt>char*</tt> pointer, see @ref overview_string_refcount
It also provides performance @ref stringtuning_overview "reference counting") and speed. It also provides performance
which may be enabled to fine tune the memory allocation strategy for your @ref overview_string_tuning "statistics gathering code" which may be
particular application - and the gain might be quite big. enabled to fine tune the memory allocation strategy for your particular
@b Compatibility This class tries to combine almost full compatibility application - and the gain might be quite big.
with the old wxWidgets 1.xx wxString class, some reminiscence to MFC CString @li <b>Compatibility:</b> This class tries to combine almost full compatibility
class and 90% of the functionality of std::string class. with the old wxWidgets 1.xx wxString class, some reminiscence to MFC
@b Rich set of functions Some of the functions present in wxString are CString class and 90% of the functionality of std::string class.
very useful but don't exist in most of other string classes: for example, @li <b>Rich set of functions:</b> Some of the functions present in wxString are very
#AfterFirst, useful but don't exist in most of other string classes: for example,
#BeforeLast, #operator wxString::AfterFirst, wxString::BeforeLast, wxString::operators or
or #Printf. Of course, all the standard string wxString::Printf. Of course, all the standard string operations are
operations are supported as well. supported as well.
@b Unicode wxString is Unicode friendly: it allows to easily convert @li <b>Unicode wxString is Unicode friendly:</b> it allows to easily convert to
to and from ANSI and Unicode strings in any build mode (see the and from ANSI and Unicode strings in any build mode (see the
@ref unicode_overview for more details) and maps to either @ref overview_unicode "unicode overview" for more details) and maps to
@c string or @c wstring transparently depending on the current mode. either @c string or @c wstring transparently depending on the current mode.
@b Used by wxWidgets And, of course, this class is used everywhere @li <b>Used by wxWidgets:</b> And, of course, this class is used everywhere
inside wxWidgets so there is no performance loss which would result from 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 wxWidgets. wxString internally by wxWidgets.
However, there are several problems as well. The most important one is probably 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 that there are often several functions to do exactly the same thing: for
example, to get the length of the string either one of example, to get the length of the string either one of @c length(),
length(), #Len() or wxString::Len() or wxString::Length() may be used. The first function, as
#Length() may be used. The first function, as almost almost all the other functions in lowercase, is std::string compatible. The
all the other functions in lowercase, is std::string compatible. The second one second one is the "native" wxString version and the last one is the wxWidgets
is "native" wxString version and the last one is wxWidgets 1.xx way. So the 1.xx way.
question is: which one is better to use? And the answer is that:
@b The usage of std::string compatible functions is strongly advised! It will So which is better to use? The usage of the std::string compatible functions is
both make your code more familiar to other C++ programmers (who are supposed to strongly advised! It will both make your code more familiar to other C++
have knowledge of std::string but not of wxString), let you reuse the same code programmers (who are supposed to have knowledge of std::string but not of
in both wxWidgets and other programs (by just typedefing wxString as std::string wxString), let you reuse the same code in both wxWidgets and other programs (by
when used outside wxWidgets) and by staying compatible with future versions of just typedefing wxString as std::string when used outside wxWidgets) and by
wxWidgets which will probably start using std::string sooner or later too. 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 wxWidgets 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. which are deprecated and may disappear in future versions.
@section wxstringadvices Some advice about using wxString
Probably the main trap with using this class is the implicit conversion operator to @section overview_string_advice Advice About Using wxString
@e const char *. It is advised that you use #c_str()
Probably the main trap with using this class is the implicit conversion
operator to <tt>const char*</tt>. It is advised that you use wxString::c_str()
instead 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: danger of this implicit conversion may be seen in the following code fragment:
@code @code
// this function converts the input string to uppercase, output it to the screen // this function converts the input string to uppercase,
// and returns the result // output it to the screen and returns the result
const char *SayHELLO(const wxString& input) const char *SayHELLO(const wxString& input)
{ {
wxString output = input.Upper(); wxString output = input.Upper();
printf("Hello, %s!\n", output); printf("Hello, %s!\n", output);
return output; return output;
} }
@endcode @endcode
There are two nasty bugs in these three lines. First of them is in the call to the There are two nasty bugs in these three lines. The first is in the call to the
@e printf() function. Although the implicit conversion to C strings is applied @c printf() function. Although the implicit conversion to C strings is applied
automatically by the compiler in the case of automatically by the compiler in the case of
@code @code
puts(output); puts(output);
@endcode @endcode
because the argument of @e puts() is known to be of the type @e const char *, because the argument of @c puts() is known to be of the type
this is @b not done for @e printf() which is a function with variable <tt>const char*</tt>, this is @b not done for @c printf() which is a function
number of arguments (and whose arguments are of unknown types). So this call may with variable number of arguments (and whose arguments are of unknown types).
do anything at all (including displaying the correct string on screen), although So this call may do any number of things (including displaying the correct
the most likely result is a program crash. The solution is to use string on screen), although the most likely result is a program crash. The
#c_str(): just replace this line with solution is to use wxString::c_str(). Just replace this line with this:
@code @code
printf("Hello, %s!\n", output.c_str()); printf("Hello, %s!\n", output.c_str());
@endcode @endcode
The second bug is that returning @e output doesn't work. The implicit cast is The second bug is that returning @c output doesn't work. The implicit cast is
used again, so the code compiles, but as it returns a pointer to a buffer 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, 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: its contents are completely arbitrary. The solution to this problem is also
just make the function return wxString instead of a C string. easy, 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 @e const wxString (this makes assignment to the
strings inside the function faster because of
@ref stringrefcount_overview) and all functions returning
strings should return @e wxString - this makes it safe to return local
variables.
@section relatedtostring Other string related functions and classes This leads us to the following general advice: all functions taking string
arguments should take <tt>const wxString</tt> (this makes assignment to the
strings inside the function faster because of
@ref overview_string_refcount "reference counting") and all functions returning
strings should return wxString - this makes it safe to return local variables.
@section overview_string_related String Related Functions and Classes
As most programs use character strings, the standard C library provides quite 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 a few functions to work with them. Unfortunately, some of them have rather
counter-intuitive behaviour (like strncpy() which doesn't always terminate the counter-intuitive behaviour (like @c strncpy() which doesn't always terminate
resulting string with a @NULL) and are in general not very safe (passing @NULL the resulting string with a @NULL) and are in general not very safe (passing
to them will probably lead to program crash). Moreover, some very useful @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 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 functions, there are also a few global string functions which try to correct
these problems: #wxIsEmpty() verifies whether the string these problems: wxIsEmpty() verifies whether the string is empty (returning
is empty (returning @true for @NULL pointers), @true for @NULL pointers), wxStrlen() also handles @NULLs correctly and returns
#wxStrlen() also handles @NULLs correctly and returns 0 for 0 for them and wxStricmp() is just a platform-independent version of
them and #wxStricmp() is just a platform-independent case-insensitive string comparison function known either as @c stricmp() or
version of case-insensitive string comparison function known either as @c strcasecmp() on different platforms.
stricmp() or strcasecmp() on different platforms.
The @c wx/string.h header also defines #wxSnprintf The <tt>@<wx/string.h@></tt> header also defines wxSnprintf and wxVsnprintf
and #wxVsnprintf functions which should be used instead functions which should be used instead of the inherently dangerous standard
of the inherently dangerous standard @c sprintf() and which use @c snprintf() instead which does buffer size checks whenever possible. Of @c sprintf() and which use @c snprintf() instead which does buffer size checks
course, you may also use wxString::Printf which is whenever possible. Of course, you may also use wxString::Printf which is also
also safe. safe.
There is another class which might be useful when working with wxString: There is another class which might be useful when working with wxString:
#wxStringTokenizer. It is helpful when a string must wxStringTokenizer. It is helpful when a string must be broken into tokens and
be broken into tokens and replaces the standard C library @e strtok() function. replaces the standard C library @c strtok() function.
And the very last string-related class is #wxArrayString: 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 (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.
@section wxstringrefcount Reference counting and why you shouldn't care about it And the very last string-related class is wxArrayString: it is just a version
of the "template" dynamic array class which is specialized to work with
All considerations for wxObject-derived @ref trefcount_overview objects strings. Please note that this class is specially optimized (using its
are valid also for wxString, even if it does not derive from wxObject. knowledge of the internal structure of wxString) for storing strings and so it
Probably the unique case when you might want to think about reference is vastly better from a performance point of view than a wxObjectArray of
counting is when a string character is taken from a string which is not a wxStrings.
constant (or a constant reference). In this case, due to C++ rules, the
"read-only" @e operator[] (which is the same as
#GetChar()) cannot be chosen and the "read/write"
@e operator[] (the same as
#GetWritableChar()) is used instead. As the
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 #GetChar() instead
of the array subscript operator for this reasons. Please note that
#at() 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 @e const wxString (see the
section @ref stringadvices_overview) this situation will almost
never arise because for constant references the correct operator is called automatically.
@section wxstringtuning Tuning wxString for your application
@b Note: this section is strictly about performance issues and is @section overview_string_refcount Reference Counting and Why You Shouldn't Care
absolutely not necessary to read for using wxString class. Please skip it unless
you feel familiar with profilers and relative tools. If you do read it, please All considerations for wxObject-derived
also read the preceding section about @ref overview_refcount "reference counted" objects are valid also for wxString,
@ref stringrefcount_overview. 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 constant (or
a constant reference). In this case, due to C++ rules, the "read-only"
@c operator[] (which is the same as wxString::GetChar()) cannot be chosen and
the "read/write" @c operator[] (the same as wxString::GetWritableChar()) is
used instead. As the 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 wxString::GetChar()
instead of the array subscript operator for this reasons. Please note that
wxString::at() 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 <tt>const wxString</tt> (see the
@ref overview_string_advice section) this situation will almost never arise
because for constant references the correct operator is called automatically.
@section overview_string_tuning Tuning wxString for Your Application
@note This section is strictly about performance issues and is absolutely not
necessary to read for using wxString class. Please skip it unless you feel
familiar with profilers and relative tools. If you do read it, please also
read the preceding section about
@ref overview_string_refcount "reference counting".
For the performance reasons wxString doesn't allocate exactly the amount of 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 memory needed for each string. Instead, it adds a small amount of space to each
@@ -214,9 +225,9 @@
wxString result; wxString result;
size_t len = original.length(); size_t len = original.length();
for ( size_t n = 0; n len; n++ ) for ( size_t n = 0; n < len; n++ )
{ {
if ( strchr("aeuio", tolower(original[n])) == @NULL ) if ( strchr("aeuio", tolower(original[n])) == NULL )
result += original[n]; result += original[n];
} }
@@ -230,23 +241,28 @@
much extra memory would help to improve the speed in this situation, but due to much extra memory would help to improve the speed in this situation, but due to
a great number of wxString objects typically used in a program would also a great number of wxString objects typically used in a program would also
increase the memory consumption too much. increase the memory consumption too much.
The very best solution in precisely this case would be to use
#Alloc() function to preallocate, for example, len bytes The very best solution in precisely this case would be to use wxString::Alloc()
from the beginning - this will lead to exactly one memory allocation being function to preallocate, for example, len bytes from the beginning - this will
performed (because the result is at most as long as the original string). lead to exactly one memory allocation being performed (because the result is at
However, using Alloc() is tedious and so wxString tries to do its best. The most as long as the original string).
default algorithm assumes that memory allocation is done in granularity of at
least 16 bytes (which is the case on almost all of wide-spread platforms) and so However, using wxString::Alloc() is tedious and so wxString tries to do its
nothing is lost if the amount of memory to allocate is rounded up to the next best. The default algorithm assumes that memory allocation is done in
multiple of 16. Like this, no memory is lost and 15 iterations from 16 in the granularity of at least 16 bytes (which is the case on almost all of
example above won't allocate memory but use the already allocated pool. wide-spread platforms) and so nothing is lost if the amount of memory to
allocate is rounded up to the next multiple of 16. Like this, no memory is lost
and 15 iterations from 16 in the example above won't allocate memory but use
the already allocated pool.
The default approach is quite conservative. Allocating more memory may bring The default approach is quite conservative. Allocating more memory may bring
important performance benefits for programs using (relatively) few very long important performance benefits for programs using (relatively) few very long
strings. The amount of memory allocated is configured by the setting of @e EXTRA_ALLOC in the file string.cpp during compilation (be sure to understand strings. The amount of memory allocated is configured by the setting of
@c EXTRA_ALLOC in the file string.cpp during compilation (be sure to understand
why its default value is what it is before modifying it!). You may try setting why its default value is what it is before modifying it!). You may try setting
it to greater amount (say twice nLen) or to 0 (to see performance degradation it to greater amount (say twice nLen) or to 0 (to see performance degradation
which will follow) and analyse the impact of it on your program. If you do it, which will follow) and analyse the impact of it on your program. If you do it,
you will probably find it helpful to also define WXSTRING_STATISTICS symbol you will probably find it helpful to also define @c WXSTRING_STATISTICS symbol
which tells the wxString class to collect performance statistics and to show 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 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 strings your program manipulates, their average initial length and also the
@@ -254,9 +270,9 @@
done but the already 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 98% for the default allocation policy, if it is less than 90% you should
really consider fine tuning wxString for your application). really consider fine tuning wxString for your application).
It goes without saying that a profiler should be used to measure the precise It goes without saying that a profiler should be used to measure the precise
difference the change to EXTRA_ALLOC makes to your program. difference the change to @c EXTRA_ALLOC makes to your program.
*/ */