]> git.saurik.com Git - wxWidgets.git/blob - docs/doxygen/overviews/string.h
Fix column sorting UI in wxDataViewCtrl under wxOSX.
[wxWidgets.git] / docs / doxygen / overviews / string.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: string.h
3 // Purpose: topic overview
4 // Author: wxWidgets team
5 // Licence: wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
7
8 /**
9
10 @page overview_string wxString Overview
11
12 @tableofcontents
13
14 wxString is a class which represents a Unicode string of arbitrary length and
15 containing arbitrary Unicode characters.
16
17 This class has all the standard operations you can expect to find in a string
18 class: dynamic memory management (string extends to accommodate new
19 characters), construction from other strings, compatibility with C strings and
20 wide character C strings, assignment operators, access to individual characters, string
21 concatenation and comparison, substring extraction, case conversion, trimming and
22 padding (with spaces), searching and replacing and both C-like @c printf (wxString::Printf)
23 and stream-like insertion functions as well as much more - see wxString for a
24 list of all functions.
25
26 The wxString class has been completely rewritten for wxWidgets 3.0 but much work
27 has been done to make existing code using ANSI string literals work as it did
28 in previous versions.
29
30
31 @section overview_string_internal Internal wxString Encoding
32
33 Since wxWidgets 3.0 wxString internally uses <b>UTF-16</b> (with Unicode
34 code units stored in @c wchar_t) under Windows and <b>UTF-8</b> (with Unicode
35 code units stored in @c char) under Unix, Linux and Mac OS X to store its content.
36
37 For definitions of <em>code units</em> and <em>code points</em> terms, please
38 see the @ref overview_unicode_encodings paragraph.
39
40 For simplicity of implementation, wxString when <tt>wxUSE_UNICODE_WCHAR==1</tt>
41 (e.g. on Windows) uses <em>per code unit indexing</em> instead of
42 <em>per code point indexing</em> and doesn't know anything about surrogate pairs;
43 in other words it always considers code points to be composed by 1 code unit,
44 while this is really true only for characters in the @e BMP (Basic Multilingual Plane).
45 Thus when iterating over a UTF-16 string stored in a wxString under Windows, the user
46 code has to take care of <em>surrogate pairs</em> himself.
47 (Note however that Windows itself has built-in support for surrogate pairs in UTF-16,
48 such as for drawing strings on screen.)
49
50 @remarks
51 Note that while the behaviour of wxString when <tt>wxUSE_UNICODE_WCHAR==1</tt>
52 resembles UCS-2 encoding, it's not completely correct to refer to wxString as
53 UCS-2 encoded since you can encode code points outside the @e BMP in a wxString
54 as two code units (i.e. as a surrogate pair; as already mentioned however wxString
55 will "see" them as two different code points)
56
57 When instead <tt>wxUSE_UNICODE_UTF8==1</tt> (e.g. on Linux and Mac OS X)
58 wxString handles UTF8 multi-bytes sequences just fine also for characters outside
59 the BMP (it implements <em>per code point indexing</em>), so that you can use
60 UTF8 in a completely transparent way:
61
62 Example:
63 @code
64 // first test, using exotic characters outside of the Unicode BMP:
65
66 wxString test = wxString::FromUTF8("\xF0\x90\x8C\x80");
67 // U+10300 is "OLD ITALIC LETTER A" and is part of Unicode Plane 1
68 // in UTF8 it's encoded as 0xF0 0x90 0x8C 0x80
69
70 // it's a single Unicode code-point encoded as:
71 // - a UTF16 surrogate pair under Windows
72 // - a UTF8 multiple-bytes sequence under Linux
73 // (without considering the final NULL)
74
75 wxPrintf("wxString reports a length of %d character(s)", test.length());
76 // prints "wxString reports a length of 1 character(s)" on Linux
77 // prints "wxString reports a length of 2 character(s)" on Windows
78 // since wxString on Windows doesn't have surrogate pairs support!
79
80
81 // second test, this time using characters part of the Unicode BMP:
82
83 wxString test2 = wxString::FromUTF8("\x41\xC3\xA0\xE2\x82\xAC");
84 // this is the UTF8 encoding of capital letter A followed by
85 // 'small case letter a with grave' followed by the 'euro sign'
86
87 // they are 3 Unicode code-points encoded as:
88 // - 3 UTF16 code units under Windows
89 // - 6 UTF8 code units under Linux
90 // (without considering the final NULL)
91
92 wxPrintf("wxString reports a length of %d character(s)", test2.length());
93 // prints "wxString reports a length of 3 character(s)" on Linux
94 // prints "wxString reports a length of 3 character(s)" on Windows
95 @endcode
96
97 To better explain what stated above, consider the second string of the example
98 above; it's composed by 3 characters and the final @c NULL:
99
100 @image html overview_wxstring_encoding.png
101
102 As you can see, UTF16 encoding is straightforward (for characters in the @e BMP)
103 and in this example the UTF16-encoded wxString takes 8 bytes.
104 UTF8 encoding is more elaborated and in this example takes 7 bytes.
105
106 In general, for strings containing many latin characters UTF8 provides a big
107 advantage with regards to the memory footprint respect UTF16, but requires some
108 more processing for common operations like e.g. length calculation.
109
110 Finally, note that the type used by wxString to store Unicode code units
111 (@c wchar_t or @c char) is always @c typedef-ined to be ::wxStringCharType.
112
113
114 @section overview_string_binary Using wxString to store binary data
115
116 wxString can be used to store binary data (even if it contains @c NULs) using the
117 functions wxString::To8BitData and wxString::From8BitData.
118
119 Beware that even if @c NUL character is allowed, in the current string implementation
120 some methods might not work correctly with them.
121
122 Note however that other classes like wxMemoryBuffer are more suited to this task.
123 For handling binary data you may also want to look at the wxStreamBuffer,
124 wxMemoryOutputStream, wxMemoryInputStream classes.
125
126
127 @section overview_string_comparison Comparison to Other String Classes
128
129 The advantages of using a special string class instead of working directly with
130 C strings are so obvious that there is a huge number of such classes available.
131 The most important advantage is the need to always remember to allocate/free
132 memory for C strings; working with fixed size buffers almost inevitably leads
133 to buffer overflows. At last, C++ has a standard string class (@c std::string). So
134 why the need for wxString? There are several advantages:
135
136 @li <b>Efficiency:</b> Since wxWidgets 3.0 wxString uses @c std::string (in UTF8
137 mode under Linux, Unix and OS X) or @c std::wstring (in UTF16 mode under Windows)
138 internally by default to store its contents. wxString will therefore inherit the
139 performance characteristics from @c std::string.
140 @li <b>Compatibility:</b> This class tries to combine almost full compatibility
141 with the old wxWidgets 1.xx wxString class, some reminiscence of MFC's
142 CString class and 90% of the functionality of @c std::string class.
143 @li <b>Rich set of functions:</b> Some of the functions present in wxString are
144 very useful but don't exist in most of other string classes: for example,
145 wxString::AfterFirst, wxString::BeforeLast, wxString::Printf.
146 Of course, all the standard string operations are supported as well.
147 @li <b>wxString is Unicode friendly:</b> it allows to easily convert to
148 and from ANSI and Unicode strings (see @ref overview_unicode
149 for more details) and maps to @c std::wstring transparently.
150 @li <b>Used by wxWidgets:</b> And, of course, this class is used everywhere
151 inside wxWidgets so there is no performance loss which would result from
152 conversions of objects of any other string class (including @c std::string) to
153 wxString internally by wxWidgets.
154
155 However, there are several problems as well. The most important one is probably
156 that there are often several functions to do exactly the same thing: for
157 example, to get the length of the string either one of wxString::length(),
158 wxString::Len() or wxString::Length() may be used. The first function, as
159 almost all the other functions in lowercase, is @c std::string compatible. The
160 second one is the "native" wxString version and the last one is the wxWidgets
161 1.xx way.
162
163 So which is better to use? The usage of the @c std::string compatible functions is
164 strongly advised! It will both make your code more familiar to other C++
165 programmers (who are supposed to have knowledge of @c std::string but not of
166 wxString), let you reuse the same code in both wxWidgets and other programs (by
167 just typedefing wxString as @c std::string when used outside wxWidgets) and by
168 staying compatible with future versions of wxWidgets which will probably start
169 using @c std::string sooner or later too.
170
171 In the situations where there is no corresponding @c std::string function, please
172 try to use the new wxString methods and not the old wxWidgets 1.xx variants
173 which are deprecated and may disappear in future versions.
174
175
176 @section overview_string_advice Advice About Using wxString
177
178 @subsection overview_string_implicitconv Implicit conversions
179
180 Probably the main trap with using this class is the implicit conversion
181 operator to <tt>const char*</tt>. It is advised that you use wxString::c_str()
182 instead to clearly indicate when the conversion is done. Specifically, the
183 danger of this implicit conversion may be seen in the following code fragment:
184
185 @code
186 // this function converts the input string to uppercase,
187 // output it to the screen and returns the result
188 const char *SayHELLO(const wxString& input)
189 {
190 wxString output = input.Upper();
191 printf("Hello, %s!\n", output);
192 return output;
193 }
194 @endcode
195
196 There are two nasty bugs in these three lines. The first is in the call to the
197 @c printf() function. Although the implicit conversion to C strings is applied
198 automatically by the compiler in the case of
199
200 @code
201 puts(output);
202 @endcode
203
204 because the argument of @c puts() is known to be of the type
205 <tt>const char*</tt>, this is @b not done for @c printf() which is a function
206 with variable number of arguments (and whose arguments are of unknown types).
207 So this call may do any number of things (including displaying the correct
208 string on screen), although the most likely result is a program crash.
209 The solution is to use wxString::c_str(). Just replace this line with this:
210
211 @code
212 printf("Hello, %s!\n", output.c_str());
213 @endcode
214
215 The second bug is that returning @c output doesn't work. The implicit cast is
216 used again, so the code compiles, but as it returns a pointer to a buffer
217 belonging to a local variable which is deleted as soon as the function exits,
218 its contents are completely arbitrary. The solution to this problem is also
219 easy, just make the function return wxString instead of a C string.
220
221 This leads us to the following general advice: all functions taking string
222 arguments should take <tt>const wxString&</tt> (this makes assignment to the
223 strings inside the function faster) and all functions returning strings
224 should return wxString - this makes it safe to return local variables.
225
226 Finally note that wxString uses the current locale encoding to convert any C string
227 literal to Unicode. The same is done for converting to and from @c std::string
228 and for the return value of c_str().
229 For this conversion, the @a wxConvLibc class instance is used.
230 See wxCSConv and wxMBConv.
231
232
233 @subsection overview_string_iterating Iterating wxString Characters
234
235 As previously described, when <tt>wxUSE_UNICODE_UTF8==1</tt>, wxString internally
236 uses the variable-length UTF8 encoding.
237 Accessing a UTF-8 string by index can be very @b inefficient because
238 a single character is represented by a variable number of bytes so that
239 the entire string has to be parsed in order to find the character.
240 Since iterating over a string by index is a common programming technique and
241 was also possible and encouraged by wxString using the access operator[]()
242 wxString implements caching of the last used index so that iterating over
243 a string is a linear operation even in UTF-8 mode.
244
245 It is nonetheless recommended to use @b iterators (instead of index based
246 access) like this:
247
248 @code
249 wxString s = "hello";
250 wxString::const_iterator i;
251 for (i = s.begin(); i != s.end(); ++i)
252 {
253 wxUniChar uni_ch = *i;
254 // do something with it
255 }
256 @endcode
257
258
259
260 @section overview_string_related String Related Functions and Classes
261
262 As most programs use character strings, the standard C library provides quite
263 a few functions to work with them. Unfortunately, some of them have rather
264 counter-intuitive behaviour (like @c strncpy() which doesn't always terminate
265 the resulting string with a @NULL) and are in general not very safe (passing
266 @NULL to them will probably lead to program crash). Moreover, some very useful
267 functions are not standard at all. This is why in addition to all wxString
268 functions, there are also a few global string functions which try to correct
269 these problems: wxIsEmpty() verifies whether the string is empty (returning
270 @true for @NULL pointers), wxStrlen() also handles @NULL correctly and returns
271 0 for them and wxStricmp() is just a platform-independent version of
272 case-insensitive string comparison function known either as @c stricmp() or
273 @c strcasecmp() on different platforms.
274
275 The <tt>@<wx/string.h@></tt> header also defines wxSnprintf() and wxVsnprintf()
276 functions which should be used instead of the inherently dangerous standard
277 @c sprintf() and which use @c snprintf() instead which does buffer size checks
278 whenever possible. Of course, you may also use wxString::Printf which is also
279 safe.
280
281 There is another class which might be useful when working with wxString:
282 wxStringTokenizer. It is helpful when a string must be broken into tokens and
283 replaces the standard C library @c strtok() function.
284
285 And the very last string-related class is wxArrayString: it is just a version
286 of the "template" dynamic array class which is specialized to work with
287 strings. Please note that this class is specially optimized (using its
288 knowledge of the internal structure of wxString) for storing strings and so it
289 is vastly better from a performance point of view than a wxObjectArray of
290 wxStrings.
291
292
293 @section overview_string_tuning Tuning wxString for Your Application
294
295 @note This section is strictly about performance issues and is absolutely not
296 necessary to read for using wxString class. Please skip it unless you feel
297 familiar with profilers and relative tools.
298
299 For the performance reasons wxString doesn't allocate exactly the amount of
300 memory needed for each string. Instead, it adds a small amount of space to each
301 allocated block which allows it to not reallocate memory (a relatively
302 expensive operation) too often as when, for example, a string is constructed by
303 subsequently adding one character at a time to it, as for example in:
304
305 @code
306 // delete all vowels from the string
307 wxString DeleteAllVowels(const wxString& original)
308 {
309 wxString vowels( "aeuioAEIOU" );
310 wxString result;
311 wxString::const_iterator i;
312 for ( i = original.begin(); i != original.end(); ++i )
313 {
314 if (vowels.Find( *i ) == wxNOT_FOUND)
315 result += *i;
316 }
317
318 return result;
319 }
320 @endcode
321
322 This is quite a common situation and not allocating extra memory at all would
323 lead to very bad performance in this case because there would be as many memory
324 (re)allocations as there are consonants in the original string. Allocating too
325 much extra memory would help to improve the speed in this situation, but due to
326 a great number of wxString objects typically used in a program would also
327 increase the memory consumption too much.
328
329 The very best solution in precisely this case would be to use wxString::Alloc()
330 function to preallocate, for example, len bytes from the beginning - this will
331 lead to exactly one memory allocation being performed (because the result is at
332 most as long as the original string).
333
334 However, using wxString::Alloc() is tedious and so wxString tries to do its
335 best. The default algorithm assumes that memory allocation is done in
336 granularity of at least 16 bytes (which is the case on almost all of
337 wide-spread platforms) and so nothing is lost if the amount of memory to
338 allocate is rounded up to the next multiple of 16. Like this, no memory is lost
339 and 15 iterations from 16 in the example above won't allocate memory but use
340 the already allocated pool.
341
342 The default approach is quite conservative. Allocating more memory may bring
343 important performance benefits for programs using (relatively) few very long
344 strings. The amount of memory allocated is configured by the setting of
345 @c EXTRA_ALLOC in the file string.cpp during compilation (be sure to understand
346 why its default value is what it is before modifying it!). You may try setting
347 it to greater amount (say twice nLen) or to 0 (to see performance degradation
348 which will follow) and analyse the impact of it on your program. If you do it,
349 you will probably find it helpful to also define @c WXSTRING_STATISTICS symbol
350 which tells the wxString class to collect performance statistics and to show
351 them on stderr on program termination. This will show you the average length of
352 strings your program manipulates, their average initial length and also the
353 percent of times when memory wasn't reallocated when string concatenation was
354 done but the already preallocated memory was used (this value should be about
355 98% for the default allocation policy, if it is less than 90% you should
356 really consider fine tuning wxString for your application).
357
358 It goes without saying that a profiler should be used to measure the precise
359 difference the change to @c EXTRA_ALLOC makes to your program.
360
361
362 @section overview_string_settings wxString Related Compilation Settings
363
364 Much work has been done to make existing code using ANSI string literals
365 work as before version 3.0.
366
367 If you nonetheless need to have a wxString that uses @c wchar_t
368 on Unix and Linux, too, you can specify this on the command line with the
369 @c configure @c --disable-utf8 switch or you can consider using wxUString
370 or @c std::wstring instead.
371
372 @c wxUSE_UNICODE is now defined as @c 1 by default to indicate Unicode support.
373 If UTF-8 is used for the internal storage in wxString, @c wxUSE_UNICODE_UTF8 is
374 also defined, otherwise @c wxUSE_UNICODE_WCHAR is.
375 See also @ref page_wxusedef_important.
376
377 */