Commit | Line | Data |
---|---|---|
9a6d1438 RR |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: wx/ustring.h | |
3 | // Purpose: interface of wxUString | |
4 | // Author: Robert Roebling | |
5 | // Copyright: (c) Robert Roebling | |
6 | // RCS-ID: $Id: tab.h 37400 2006-02-09 00:28:34Z VZ $ | |
7 | // Licence: wxWindows licence | |
8 | ///////////////////////////////////////////////////////////////////////////// | |
9 | ||
10 | /** | |
11 | @class wxUString | |
12 | ||
13 | wxUString is a class representing a Unicode character string where | |
14 | each character is stored using a 32-bit value. This is different from | |
15 | wxString which may store a character either as a UTF-8 or as a UTF-16 | |
16 | sequence and different from @c std::string which stores a string | |
17 | as a squence of simple 8-bit charactesr and also different from | |
18 | @c std::wstring which stores the string differently depending on | |
19 | the definition of wchar_t. | |
cfbe5614 | 20 | |
9a6d1438 | 21 | The main purpose of wxUString is a to give users a Unicode string |
cfbe5614 | 22 | class that has O(1) access to its content, to be identical on all |
9a6d1438 RR |
23 | platforms and to be easily convertable to wxString as well as other |
24 | ways to store strings (C string literals, wide character | |
0c339e7c RR |
25 | string literals, character buffer, etc) by providing several overloads |
26 | and built-in conversions to and from the various string formats. | |
cfbe5614 | 27 | |
9a6d1438 RR |
28 | wxUString derives from @c std::basic_string<wxChar32> and therefore |
29 | offers the complete API of @c std::string. | |
cfbe5614 | 30 | |
9a6d1438 RR |
31 | @library{wxbase} |
32 | @category{data} | |
cfbe5614 | 33 | |
9a6d1438 RR |
34 | @see wxString, @ref overview_string "wxString overview", @ref overview_unicode |
35 | "Unicode overview" | |
36 | */ | |
37 | ||
38 | ||
39 | class WXDLLIMPEXP_BASE wxUString: public std::basic_string<wxChar32> | |
40 | { | |
cfbe5614 | 41 | public: |
9a6d1438 RR |
42 | /** |
43 | Default constructor. | |
44 | */ | |
45 | wxUString(); | |
46 | /** | |
47 | Copy constructor. | |
48 | */ | |
a1c9e3de | 49 | wxUString( const wxUString &str ); |
9a6d1438 RR |
50 | /** |
51 | Constructs a string from a 32-bit string literal. | |
52 | */ | |
cfbe5614 | 53 | wxUString( const wxChar32 *str ); |
9a6d1438 RR |
54 | /** |
55 | Constructs a string from 32-bit string buffer. | |
56 | */ | |
cfbe5614 | 57 | wxUString( const wxU32CharBuffer &buf ); |
9a6d1438 RR |
58 | /** |
59 | Constructs a string from C string literal using wxConvLibc to convert it to Unicode. | |
60 | */ | |
a1c9e3de | 61 | wxUString( const char *str ); |
9a6d1438 RR |
62 | /** |
63 | Constructs a string from C string buffer using wxConvLibc to convert it to Unicode. | |
64 | */ | |
a1c9e3de | 65 | wxUString( const wxCharBuffer &buf ); |
9a6d1438 RR |
66 | /** |
67 | Constructs a string from C string literal using @a conv to convert it to Unicode. | |
68 | */ | |
a1c9e3de | 69 | wxUString( const char *str, const wxMBConv &conv ); |
9a6d1438 RR |
70 | /** |
71 | Constructs a string from C string literal using @a conv to convert it to Unicode. | |
72 | */ | |
a1c9e3de | 73 | wxUString( const wxCharBuffer &buf, const wxMBConv &conv ); |
9a6d1438 RR |
74 | /** |
75 | Constructs a string from UTF-16 string literal | |
76 | */ | |
a1c9e3de | 77 | wxUString( const wxChar16 *str ); |
9a6d1438 RR |
78 | /** |
79 | Constructs a string from UTF-16 string buffer | |
80 | */ | |
a1c9e3de | 81 | wxUString( const wxU16CharBuffer &buf ); |
9a6d1438 RR |
82 | /** |
83 | Constructs a string from wxString. | |
84 | */ | |
a1c9e3de | 85 | wxUString( const wxString &str ); |
9a6d1438 RR |
86 | /** |
87 | Constructs a string from using wxConvLibc to convert it to Unicode. | |
88 | */ | |
a1c9e3de | 89 | wxUString( char ch ); |
9a6d1438 RR |
90 | /** |
91 | Constructs a string from a UTF-16 character. | |
92 | */ | |
a1c9e3de | 93 | wxUString( wxChar16 ch ); |
9a6d1438 RR |
94 | /** |
95 | Constructs a string from 32-bit Unicode character. | |
96 | */ | |
a1c9e3de | 97 | wxUString( wxChar32 ch ); |
9a6d1438 RR |
98 | /** |
99 | Constructs a string from wxUniChar (returned by wxString's access operator) | |
100 | */ | |
a1c9e3de | 101 | wxUString( wxUniChar ch ); |
9a6d1438 RR |
102 | /** |
103 | Constructs a string from wxUniCharRef (returned by wxString's access operator) | |
104 | */ | |
a1c9e3de | 105 | wxUString( wxUniCharRef ch ); |
9a6d1438 RR |
106 | /** |
107 | Constructs a string from @a n characters @a ch. | |
108 | */ | |
cfbe5614 | 109 | wxUString( size_t n, char ch ); |
9a6d1438 RR |
110 | /** |
111 | Constructs a string from @a n characters @a ch. | |
112 | */ | |
cfbe5614 | 113 | wxUString( size_t n, wxChar16 ch ); |
9a6d1438 RR |
114 | /** |
115 | Constructs a string from @a n characters @a ch. | |
116 | */ | |
cfbe5614 | 117 | wxUString( size_t n, wxChar32 ch ); |
9a6d1438 RR |
118 | /** |
119 | Constructs a string from @a n characters @a ch. | |
120 | */ | |
cfbe5614 | 121 | wxUString( size_t n, wxUniChar ch ); |
9a6d1438 RR |
122 | /** |
123 | Constructs a string from @a n characters @a ch. | |
124 | */ | |
cfbe5614 FM |
125 | wxUString( size_t n, wxUniCharRef ch ); |
126 | ||
9a6d1438 RR |
127 | /** |
128 | Static construction of a wxUString from a 7-bit ASCII string | |
129 | */ | |
cfbe5614 | 130 | static wxUString FromAscii( const char *str, size_t n ); |
9a6d1438 RR |
131 | /** |
132 | Static construction of a wxUString from a 7-bit ASCII string | |
133 | */ | |
134 | static wxUString FromAscii( const char *str ); | |
135 | /** | |
136 | Static construction of a wxUString from a UTF-8 encoded string | |
137 | */ | |
cfbe5614 | 138 | static wxUString FromUTF8( const char *str, size_t n ); |
9a6d1438 RR |
139 | /** |
140 | Static construction of a wxUString from a UTF-8 encoded string | |
141 | */ | |
142 | static wxUString FromUTF8( const char *str ); | |
143 | /** | |
144 | Static construction of a wxUString from a UTF-16 encoded string | |
145 | */ | |
cfbe5614 | 146 | static wxUString FromUTF16( const wxChar16 *str, size_t n ); |
9a6d1438 RR |
147 | /** |
148 | Static construction of a wxUString from a UTF-16 encoded string | |
149 | */ | |
150 | static wxUString FromUTF16( const wxChar16 *str ); | |
cfbe5614 | 151 | |
9a6d1438 RR |
152 | |
153 | /** | |
154 | Assigment from a 7-bit ASCII string literal | |
cfbe5614 | 155 | */ |
9a6d1438 RR |
156 | wxUString &assignFromAscii( const char *str ); |
157 | /** | |
158 | Assigment from a 7-bit ASCII string literal | |
cfbe5614 FM |
159 | */ |
160 | wxUString &assignFromAscii( const char *str, size_t n ); | |
9a6d1438 RR |
161 | /** |
162 | Assigment from a UTF-8 string literal | |
cfbe5614 | 163 | */ |
9a6d1438 RR |
164 | wxUString &assignFromUTF8( const char *str ); |
165 | /** | |
166 | Assigment from a UTF-8 string literal | |
cfbe5614 FM |
167 | */ |
168 | wxUString &assignFromUTF8( const char *str, size_t n ); | |
9a6d1438 RR |
169 | /** |
170 | Assigment from a UTF-16 string literal | |
cfbe5614 | 171 | */ |
9a6d1438 RR |
172 | wxUString &assignFromUTF16( const wxChar16* str ); |
173 | /** | |
174 | Assigment from a UTF-16 string literal | |
cfbe5614 FM |
175 | */ |
176 | wxUString &assignFromUTF16( const wxChar16* str, size_t n ); | |
9a6d1438 RR |
177 | /** |
178 | Assigment from a C string literal using wxConvLibc | |
cfbe5614 | 179 | */ |
9a6d1438 RR |
180 | wxUString &assignFromCString( const char* str ); |
181 | /** | |
182 | Assigment from a C string literal using @a conv | |
cfbe5614 | 183 | */ |
9a6d1438 | 184 | wxUString &assignFromCString( const char* str, const wxMBConv &conv ); |
cfbe5614 | 185 | |
9a6d1438 RR |
186 | /** |
187 | Conversion to a UTF-8 string | |
188 | */ | |
189 | wxCharBuffer utf8_str() const; | |
190 | /** | |
191 | Conversion to a UTF-16 string | |
192 | */ | |
193 | wxU16CharBuffer utf16_str() const; | |
cfbe5614 | 194 | |
9a6d1438 RR |
195 | /** |
196 | Conversion to a wide character string (either UTF-16 | |
197 | or UCS-4, depending on the size of wchar_t). | |
198 | */ | |
199 | wxWCharBuffer wc_str() const; | |
200 | ||
201 | /** | |
202 | Implicit conversion to wxString. | |
203 | */ | |
204 | operator wxString() const; | |
205 | ||
206 | /** | |
0c339e7c | 207 | wxUString assignment. wxUString additionally provides overloads for |
9a6d1438 RR |
208 | wxString, C string, UTF-16 strings, 32-bit strings, char buffers, |
209 | single and repeated characters etc. | |
210 | */ | |
211 | wxUString &assign( const wxUString &str ); | |
cfbe5614 | 212 | |
9a6d1438 | 213 | /** |
0c339e7c | 214 | Appending. wxUString additionally provides overloads for |
9a6d1438 RR |
215 | wxString, C string, UTF-16 strings, 32-bit strings, char buffers, |
216 | single and repeated characters etc. | |
217 | */ | |
218 | wxUString &append( const wxUString &s ); | |
cfbe5614 | 219 | |
9a6d1438 | 220 | /** |
0c339e7c | 221 | Insertion. wxUString additionally provides overloads for |
9a6d1438 RR |
222 | wxString, C string, UTF-16 strings, 32-bit strings, char buffers, |
223 | single characters etc. | |
224 | */ | |
cfbe5614 | 225 | wxUString &insert( size_t pos, const wxUString &s ); |
9a6d1438 RR |
226 | |
227 | /** | |
0c339e7c | 228 | Assignment operator. wxUString additionally provides overloads for |
9a6d1438 RR |
229 | wxString, C string, UTF-16 strings, 32-bit strings, char buffers, |
230 | single characters etc. | |
231 | */ | |
232 | inline wxUString& operator=(const wxUString& s); | |
cfbe5614 | 233 | |
9a6d1438 | 234 | /** |
0c339e7c | 235 | Concatenation operator. wxUString additionally provides overloads for |
9a6d1438 RR |
236 | wxString, C string, UTF-16 strings, 32-bit strings, char buffers, |
237 | single characters etc. | |
238 | */ | |
239 | inline wxUString& operator+=(const wxUString& s); | |
cfbe5614 | 240 | |
9a6d1438 RR |
241 | }; |
242 | ||
243 | /** | |
0c339e7c | 244 | Concatenation operator. wxUString additionally provides overloads for |
9a6d1438 RR |
245 | wxString, C string, UTF-16 strings, 32-bit strings, char buffers, |
246 | single characters etc. | |
247 | */ | |
248 | inline wxUString operator+(const wxUString &s1, const wxUString &s2); | |
249 | ||
250 | /** | |
0c339e7c | 251 | Equality operator. wxUString additionally provides overloads for |
9a6d1438 RR |
252 | wxString, C string, UTF-16 strings, 32-bit strings, char buffers, |
253 | single characters etc. | |
254 | */ | |
255 | inline bool operator==(const wxUString& s1, const wxUString& s2); | |
256 | /** | |
0c339e7c | 257 | Inequality operator. wxUString additionally provides overloads for |
9a6d1438 RR |
258 | wxString, C string, UTF-16 strings, 32-bit strings, char buffers, |
259 | single characters etc. | |
260 | */ | |
261 | inline bool operator!=(const wxUString& s1, const wxUString& s2); | |
262 | /** | |
0c339e7c | 263 | Comparison operator. wxUString additionally provides overloads for |
9a6d1438 RR |
264 | wxString, C string, UTF-16 strings, 32-bit strings, char buffers, |
265 | single characters etc. | |
266 | */ | |
267 | inline bool operator< (const wxUString& s1, const wxUString& s2); | |
268 | /** | |
0c339e7c | 269 | Comparison operator. wxUString additionally provides overloads for |
9a6d1438 RR |
270 | wxString, C string, UTF-16 strings, 32-bit strings, char buffers, |
271 | single characters etc. | |
272 | */ | |
273 | inline bool operator> (const wxUString& s1, const wxUString& s2); | |
274 | /** | |
0c339e7c | 275 | Comparison operator. wxUString additionally provides overloads for |
9a6d1438 RR |
276 | wxString, C string, UTF-16 strings, 32-bit strings, char buffers, |
277 | single characters etc. | |
278 | */ | |
279 | inline bool operator<=(const wxUString& s1, const wxUString& s2); | |
280 | /** | |
0c339e7c | 281 | Comparison operator. wxUString additionally provides overloads for |
9a6d1438 RR |
282 | wxString, C string, UTF-16 strings, 32-bit strings, char buffers, |
283 | single characters etc. | |
284 | */ | |
285 | inline bool operator>=(const wxUString& s1, const wxUString& s2); |