don't place NULL pointers in the GDK window array in GTKGetWindow()
[wxWidgets.git] / interface / wx / ustring.h
CommitLineData
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
39class WXDLLIMPEXP_BASE wxUString: public std::basic_string<wxChar32>
40{
cfbe5614 41public:
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 */
248inline 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 */
255inline 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 */
261inline 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 */
267inline 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 */
273inline 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 */
279inline 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 */
285inline bool operator>=(const wxUString& s1, const wxUString& s2);