1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
|
/////////////////////////////////////////////////////////////////////////////
// Name: convauto.h
// Purpose: interface of wxConvAuto
// Author: wxWidgets team
// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
Constants representing various BOM types.
BOM is an abbreviation for "Byte Order Mark", a special Unicode character
which may be inserted into the beginning of a text stream to indicate its
encoding.
@since 2.9.3
*/
enum wxBOM
{
/**
Unknown BOM.
This is returned if BOM presence couldn't be determined and normally
happens because not enough bytes of input have been analysed.
*/
wxBOM_Unknown = -1,
/**
No BOM.
The stream doesn't contain BOM character at all.
*/
wxBOM_None,
/**
UTF-32 big endian BOM.
The stream is encoded in big endian variant of UTF-32.
*/
wxBOM_UTF32BE,
/**
UTF-32 little endian BOM.
The stream is encoded in little endian variant of UTF-32.
*/
wxBOM_UTF32LE,
/**
UTF-16 big endian BOM.
The stream is encoded in big endian variant of UTF-16.
*/
wxBOM_UTF16BE,
/**
UTF-16 little endian BOM.
The stream is encoded in little endian variant of UTF-16.
*/
wxBOM_UTF16LE,
/**
UTF-8 BOM.
The stream is encoded in UTF-8.
Notice that contrary to a popular belief, it's perfectly possible and,
n fact, common under Microsoft Windows systems, to have a BOM in an
UTF-8 stream: while it's not used to indicate the endianness of UTF-8
stream (as it's byte-oriented), the BOM can still be useful just as an
unambiguous indicator of UTF-8 being used.
*/
wxBOM_UTF8
};
/**
@class wxConvAuto
This class implements a Unicode to/from multibyte converter capable of
automatically recognizing the encoding of the multibyte text on input. The
logic used is very simple: the class uses the BOM (byte order mark) if it's
present and tries to interpret the input as UTF-8 otherwise. If this fails,
the input is interpreted as being in the default multibyte encoding which
can be specified in the constructor of a wxConvAuto instance and, in turn,
defaults to the value of GetFallbackEncoding() if not explicitly given.
For the conversion from Unicode to multibyte, the same encoding as was
previously used for multibyte to Unicode conversion is reused. If there had
been no previous multibyte to Unicode conversion, UTF-8 is used by default.
Notice that once the multibyte encoding is automatically detected, it
doesn't change any more, i.e. it is entirely determined by the first use of
wxConvAuto object in the multibyte-to-Unicode direction. However creating a
copy of wxConvAuto object, either via the usual copy constructor or
assignment operator, or using wxMBConv::Clone(), resets the automatically
detected encoding so that the new copy will try to detect the encoding of
the input on first use.
This class is used by default in wxWidgets classes and functions reading
text from files such as wxFile, wxFFile, wxTextFile, wxFileConfig and
various stream classes so the encoding set with its SetFallbackEncoding()
method will affect how these classes treat input files. In particular, use
this method to change the fall-back multibyte encoding used to interpret
the contents of the files whose contents isn't valid UTF-8 or to disallow
it completely.
@library{wxbase}
@category{data}
@see @ref overview_mbconv
*/
class wxConvAuto : public wxMBConv
{
public:
/**
Constructs a new wxConvAuto instance. The object will try to detect the
input of the multibyte text given to its wxMBConv::ToWChar() method
automatically but if the automatic detection of Unicode encodings
fails, the fall-back encoding @a enc will be used to interpret it as
multibyte text.
The default value of @a enc, @c wxFONTENCODING_DEFAULT, means that the
global default value (which can be set using SetFallbackEncoding())
should be used. As with that method, passing @c wxFONTENCODING_MAX
inhibits using this encoding completely so the input multibyte text
will always be interpreted as UTF-8 in the absence of BOM and the
conversion will fail if the input doesn't form valid UTF-8 sequence.
Another special value is @c wxFONTENCODING_SYSTEM which means to use
the encoding currently used on the user system, i.e. the encoding
returned by wxLocale::GetSystemEncoding(). Any other encoding will be
used as is, e.g. passing @c wxFONTENCODING_ISO8859_1 ensures that
non-UTF-8 input will be treated as latin1.
*/
wxConvAuto(wxFontEncoding enc = wxFONTENCODING_DEFAULT);
/**
Return the detected BOM type.
The BOM type is detected after sufficiently many initial bytes have
passed through this conversion object so it will always return
wxBOM_Unknown immediately after the object creation but may return a
different value later.
@since 2.9.3
*/
wxBOM GetBOM() const;
/**
Return a pointer to the characters that makes up this BOM.
The returned character count is 2, 3 or 4, or undefined if the return
value is NULL.
@param bom
A valid BOM type, i.e. not wxBOM_Unknown or wxBOM_None.
@param count
A non-@NULL pointer receiving the number of characters in this BOM.
@return
Pointer to characters composing the BOM or @NULL if BOM is unknown
or invalid. Notice that the returned string is not NUL-terminated
and may contain embedded NULs so @a count must be used to handle it
correctly.
@since 2.9.3
*/
const char* GetBOMChars(wxBOM bom, size_t* count);
/**
Disable the use of the fall back encoding: if the input doesn't have a
BOM and is not valid UTF-8, the conversion will fail.
*/
static void DisableFallbackEncoding();
/**
Returns the encoding used by default by wxConvAuto if no other encoding
is explicitly specified in constructor. By default, returns
@c wxFONTENCODING_ISO8859_1 but can be changed using
SetFallbackEncoding().
*/
static wxFontEncoding GetFallbackEncoding();
/**
Changes the encoding used by default by wxConvAuto if no other encoding
is explicitly specified in constructor. The default value, which can be
retrieved using GetFallbackEncoding(), is @c wxFONTENCODING_ISO8859_1.
Special values of @c wxFONTENCODING_SYSTEM or @c wxFONTENCODING_MAX can
be used for the @a enc parameter to use the encoding of the current
user locale as fall back or not use any encoding for fall back at all,
respectively (just as with the similar constructor parameter). However,
@c wxFONTENCODING_DEFAULT can't be used here.
*/
static void SetFallbackEncoding(wxFontEncoding enc);
/**
Return the BOM type of this buffer.
This is a helper function which is normally only used internally by
wxConvAuto but provided for convenience of the code that wants to
detect the encoding of a stream by checking it for BOM presence on its
own.
@since 2.9.3
*/
static wxBOM DetectBOM(const char *src, size_t srcLen);
};
|
