]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/tstring.tex
1. (very) short i18n overview added, wxGetTranslation() documented.
[wxWidgets.git] / docs / latex / wx / tstring.tex
1 \section{wxString overview}\label{wxstringoverview}
2
3 Classes: \helpref{wxString}{wxstring}, \helpref{wxArrayString}{wxarray}, \helpref{wxStringTokenizer}{wxstringtokenizer}
4
5 \subsection{Introduction}
6
7 wxString is a class which represents a character string of arbitrary length (limited by
8 {\it MAX\_INT} which is usually 2147483647 on 32 bit machines) and containing
9 arbitrary characters. The ASCII NUL character is allowed, although care should be
10 taken when passing strings containing it to other functions.
11
12 wxString only works with ASCII (8 bit characters) strings as of this release,
13 but support for UNICODE (16 but characters) is planned for the next one.
14
15 This class has all the standard operations you can expect to find in a string class:
16 dynamic memory management (string extends to accomodate new characters),
17 construction from other strings, C strings and characters, assignment operators,
18 access to individual characters, string concatenation and comparison, substring
19 extraction, case conversion, trimming and padding (with spaces), searching and
20 replacing and both C-like \helpref{Printf()}{wxstringprintf} and stream-like
21 insertion functions as well as much more - see \helpref{wxString}{wxstring}
22 for a list of all functions.
23
24 \subsection{Comparison of wxString to other string classes}
25
26 The advantages of using a special string class instead of working directly with
27 C strings are so obvious that there is a huge number of such classes available.
28 The most important advantage is the need to always
29 remember to allocate/free memory for C strings; working with fixed size buffers almost
30 inevitably leads to buffer overflows. At last, C++ has a standard string class
31 (std::string). So why the need for wxString?
32
33 There are several advantages:
34
35 \begin{enumerate}\itemsep=0pt
36 \item {\bf Efficiency} This class was made to be as efficient as possible: both
37 in terms of size (each wxString objects takes exactly the same space as a {\it
38 char *} pointer, sing \helpref{reference counting}{wxstringrefcount}) and speed.
39 It also provides performance \helpref{statistics gathering code}{wxstringtuning}
40 which may be enabled to fine tune the memory allocation strategy for your
41 particular application - and the gain might be quite big.
42 \item {\bf Compatibility} This class tries to combine almost full compatibility
43 with the old wxWindows 1.xx wxString class, some reminiscence to MFC CString
44 class and 90\% of the functionality of std::string class.
45 \item {\bf Rich set of functions} Some of the functions present in wxString are
46 very useful but don't exist in most of other string classes: for example,
47 \helpref{AfterFirst}{wxstringafterfirst},
48 \helpref{BeforeLast}{wxstringbeforelast}, \helpref{operator<<}{wxstringoperatorout}
49 or \helpref{Printf}{wxstringprintf}. Of course, all the standard string
50 operations are supported as well.
51 \item {\bf UNICODE} In this release, wxString only supports {\it construction} from
52 a UNICODE string, but in the next one it will be capable of also storing its
53 internal data in either ASCII or UNICODE format.
54 \item {\bf Used by wxWindows} And, of course, this class is used everywhere
55 inside wxWindows so there is no performance loss which would result from
56 conversions of objects of any other string class (including std::string) to
57 wxString internally by wxWindows.
58 \end{enumerate}
59
60 However, there are several problems as well. The most important one is probably
61 that there are often several functions to do exactly the same thing: for
62 example, to get the length of the string either one of
63 \helpref{length()}{wxstringlength}, \helpref{Len()}{wxstringlen} or
64 \helpref{Length()}{wxstringLength} may be used. The first function, as almost
65 all the other functions in lowercase, is std::string compatible. The second one
66 is "native" wxString version and the last one is wxWindows 1.xx way. So the
67 question is: which one is better to use? And the answer is that:
68
69 {\bf The usage of std::string compatible functions is strongly advised!} It will
70 both make your code more familiar to other C++ programmers (who are supposed to
71 have knowledge of std::string but not of wxString), let you reuse the same code
72 in both wxWindows and other programs (by just typedefing wxString as std::string
73 when used outside wxWindows) and by staying compatible with future versions of
74 wxWindows which will probably start using std::string sooner or later too.
75
76 In the situations where there is no correspondinw std::string function, please
77 try to use the new wxString methods and not the old wxWindows 1.xx variants
78 which are deprecated and may disappear in future versions.
79
80 \subsection{Some advice about using wxString}\label{wxstringadvices}
81
82 Probably the main trap with using this class is the implicit conversion operator to
83 {\it const char *}. It is advised that you use \helpref{c\_str()}{wxstringcstr}
84 instead to clearly indicate when the conversion is done. Specifically, the
85 danger of this implicit conversion may be seen in the following code fragment:
86
87 \begin{verbatim}
88 // this function converts the input string to uppercase, output it to the screen
89 // and returns the result
90 const char *SayHELLO(const wxString& input)
91 {
92 wxString output = input.Upper();
93
94 printf("Hello, %s!\n", output);
95
96 return output;
97 }
98 \end{verbatim}
99
100 There are two nasty bugs in these three lines. First of them is in the call to the
101 {\it printf()} function. Although the implicit conversion to C strings is applied
102 automatically by the compiler in the case of
103
104 \begin{verbatim}
105 puts(output);
106 \end{verbatim}
107
108 because the argument of {\it puts()} is known to be of the type {\it const char *},
109 this is {\bf not} done for {\it printf()} which is a function with variable
110 number of arguments (and whose arguments are of unknown types). So this call may
111 do anything at all (including displaying the correct string on screen), although
112 the most likely result is a program crash. The solution is to use
113 \helpref{c\_str()}{wxstringcstr}: just replace this line with
114
115 \begin{verbatim}
116 printf("Hello, %s!\n", output.c_str());
117 \end{verbatim}
118
119 The second bug is that returning {\it output} doesn't work. The implicit cast is
120 used again, so the code compiles, but as it returns a pointer to a buffer
121 belonging to a local variable which is deleted as soon as the function exits,
122 its contents is totally arbitrary. The solution to this problem is also easy:
123 just make the function return wxString instead of a C string.
124
125 This leads us to the following general advice: all functions taking string
126 arguments should take {\it const wxString\&} (this makes assignment to the
127 strings inside the function faster because of
128 \helpref{reference counting}{wxstringrefcount}) and all functions returning
129 strings should return {\it wxString} - this makes it safe to return local
130 variables.
131
132 \subsection{Other string related functions and classes}
133
134 As most programs use character strings, the standard C library provides quite a
135 few functions to work with them. Unfortunately, some of them have rather
136 counter-intuitive behaviour (like strncpy() which doesn't always terminate the resulting
137 string with a NULL) and are in general not very safe (passing NULL to them will
138 probably lead to program crash). Moreover, some very useful functions are not
139 standard at all. This is why in addition to all wxString functions, there are
140 also a few global string functions which try to correct these problems:
141 \helpref{IsEmpty()}{IsEmpty} verifies whether the string is empty (returning
142 TRUE for NULL pointers), \helpref{Strlen()}{Strlen} also handles NULLs correctly
143 and returns 0 for them and \helpref{Stricmp()}{Stricmp} is just a
144 platform-independent version of case-insensitive string comparison function
145 known either as stricmp() or strcasecmp() on different platforms.
146
147 There is another class which might be useful when working with wxString:
148 \helpref{wxStringTokenizer}{wxstringtokenizer}. It is helpful when a string must
149 be broken into tokens and replaces the standard C library {\it
150 strtok()} function.
151
152 And the very last string-related class is \helpref{wxArrayString}{wxarray}: it
153 is just a version of the "template" dynamic array class which is specialized to work
154 with strings. Please note that this class is specially optimized (using its
155 knowledge of the internal structure of wxString) for storing strings and so it is
156 vastly better from a performance point of view than a wxObjectArray of wxStrings.
157
158 \subsection{Reference counting and why you shouldn't care about it}\label{wxstringrefcount}
159
160 wxString objects use a technique known as {\it copy on write} (COW). This means
161 that when a string is assigned to another, no copying really takes place: only
162 the reference count on the shared string data is incremented and both strings
163 share the same data.
164
165 But as soon as one of the two (or more) strings is modified, the data has to be
166 copied because the changes to one of the strings shouldn't be seen in the
167 otheres. As data copying only happens when the string is written to, this is
168 known as COW.
169
170 What is important to understand is that all this happens absolutely
171 transparently to the class users and that whether a string is shared or not is
172 not seen from the outside of the class - in any case, the result of any
173 operation on it is the same.
174
175 Probably the unique case when you might want to think about reference
176 counting is when a string character is taken from a string which is not a
177 constant (or a constant reference). In this case, due to C++ rules, the
178 "read-only" {\it operator[]} (which is the same as
179 \helpref{GetChar()}{wxstringgetchar}) cannot be chosen and the "read/write"
180 {\it operator[]} (the same as
181 \helpref{GetWritableChar()}{wxstringgetwritablechar}) is used instead. As the
182 call to this operator may modify the string, its data is unshared (COW is done)
183 and so if the string was really shared there is some performance loss (both in
184 terms of speed and memory consumption). In the rare cases when this may be
185 important, you might prefer using \helpref{GetChar()}{wxstringgetchar} instead
186 of the array subscript operator for this reasons. Please note that
187 \helpref{at()}{wxstringat} method has the same problem as the subscript operator in
188 this situation and so using it is not really better. Also note that if all
189 string arguments to your functions are passed as {\it const wxString\&} (see the
190 section \helpref{Some advice}{wxstringadvices}) this situation will almost
191 never arise because for constant references the correct operator is called automatically.
192
193 \subsection{Tuning wxString for your application}\label{wxstringtuning}
194
195 \normalbox{{\bf Note:} this section is strictly about performance issues and is
196 absolutely not necessary to read for using wxString class. Please skip it unless
197 you feel familiar with profilers and relative tools. If you do read it, please
198 also read the preceding section about
199 \helpref{reference counting}{wxstringrefcount}.}
200
201 For the performance reasons wxString doesn't allocate exactly the amount of
202 memory needed for each string. Instead, it adds a small amount of space to each
203 allocated block which allows it to not reallocate memory (a relatively
204 expensive operation) too often as when, for example, a string is constructed by
205 subsequently adding one character at a time to it, as for example in:
206
207 \begin{verbatim}
208 // delete all vowels from the string
209 wxString DeleteAllVowels(const wxString& original)
210 {
211 wxString result;
212
213 size_t len = original.length();
214 for ( size_t n = 0; n < len; n++ )
215 {
216 if ( strchr("aeuio", tolower(original[n])) == NULL )
217 result += original[n];
218 }
219
220 return result;
221 }
222 \end{verbatim}
223
224 This is quite a common situation and not allocating extra memory at all would
225 lead to very bad performance in this case because there would be as many memory
226 (re)allocations as there are consonants in the original string. Allocating too
227 much extra memory would help to improve the speed in this situation, but due to
228 a great number of wxString objects typically used in a program would also
229 increase the memory consumption too much.
230
231 The very best solution in precisely this case would be to use
232 \helpref{Alloc()}{wxstringalloc} function to preallocate, for example, len bytes
233 from the beginning - this will lead to exactly one memory allocation being
234 performed (because the result is at most as long as the original string).
235
236 However, using Alloc() is tedious and so wxString tries to do its best. The
237 default algorithm assumes that memory allocation is done in granularity of at
238 least 16 bytes (which is the case on almost all of wide-spread platforms) and so
239 nothing is lost if the amount of memory to allocate is rounded up to the next
240 multiple of 16. Like this, no memory is lost and 15 iterations from 16 in the
241 example above won't allocate memory but use the already allocated pool.
242
243 The default approach is quite conservative. Allocating more memory may bring
244 important performance benefits for programs using (relatively) few very long
245 strings. The amount of memory allocated is configured by the setting of {\it
246 EXTRA\_ALLOC} in the file string.cpp during compilation (be sure to understand
247 why its default value is what it is before modifying it!). You may try setting
248 it to greater amount (say twice nLen) or to 0 (to see performance degradation
249 which will follow) and analyse the impact of it on your program. If you do it,
250 you will probably find it helpful to also define WXSTRING\_STATISTICS symbol
251 which tells the wxString class to collect performance statistics and to show
252 them on stderr on program termination. This will show you the average length of
253 strings your program manipulates, their average initial length and also the
254 percent of times when memory wasn't reallocated when string concatenation was
255 done but the alread preallocated memory was used (this value should be about
256 98\% for the default allocation policy, if it is less than 90\% you should
257 really consider fine tuning wxString for your application).
258
259 It goes without saying that a profiler should be used to measure the precise
260 difference the change to EXTRA\_ALLOC makes to your program.
261