source: trunk/doc/html/qtextcodec.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 33.3 KB
RevLine 
[190]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/src/codecs/qtextcodec.cpp:201 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QTextCodec Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QTextCodec Class Reference</h1>
33
34<p>The QTextCodec class provides conversion between text encodings.
35<a href="#details">More...</a>
36<p>Almost all the functions in this class are <a href="threads.html#reentrant">reentrant</a> when Qt is built with thread support. The exceptions are <a href="#~QTextCodec"><b>~QTextCodec</b></a>(), <a href="#setCodecForTr"><b>setCodecForTr</b></a>(), <a href="#setCodecForCStrings"><b>setCodecForCStrings</b></a>(), and <a href="#QTextCodec"><b>QTextCodec</b></a>().
37</p><p><tt>#include &lt;<a href="qtextcodec-h.html">qtextcodec.h</a>&gt;</tt>
38<p>Inherited by <a href="qbig5codec.html">QBig5Codec</a>, <a href="qbig5hkscscodec.html">QBig5hkscsCodec</a>, <a href="qeucjpcodec.html">QEucJpCodec</a>, <a href="qeuckrcodec.html">QEucKrCodec</a>, <a href="qgb18030codec.html">QGb18030Codec</a>, <a href="qjiscodec.html">QJisCodec</a>, <a href="qhebrewcodec.html">QHebrewCodec</a>, <a href="qsjiscodec.html">QSjisCodec</a>, and <a href="qtsciicodec.html">QTsciiCodec</a>.
39<p><a href="qtextcodec-members.html">List of all member functions.</a>
40<h2>Public Members</h2>
41<ul>
42<li class=fn>virtual <a href="#~QTextCodec"><b>~QTextCodec</b></a> ()</li>
43<li class=fn>virtual const char * <a href="#name"><b>name</b></a> () const = 0</li>
44<li class=fn>virtual const char * <a href="#mimeName"><b>mimeName</b></a> () const</li>
45<li class=fn>virtual int <a href="#mibEnum"><b>mibEnum</b></a> () const = 0</li>
46<li class=fn>virtual QTextDecoder * <a href="#makeDecoder"><b>makeDecoder</b></a> () const</li>
47<li class=fn>virtual QTextEncoder * <a href="#makeEncoder"><b>makeEncoder</b></a> () const</li>
48<li class=fn>virtual QString <a href="#toUnicode"><b>toUnicode</b></a> ( const&nbsp;char&nbsp;*&nbsp;chars, int&nbsp;len ) const</li>
49<li class=fn>virtual QCString <a href="#fromUnicode"><b>fromUnicode</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;uc, int&nbsp;&amp;&nbsp;lenInOut ) const</li>
50<li class=fn>QCString <a href="#fromUnicode-2"><b>fromUnicode</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;uc ) const</li>
51<li class=fn>QString <a href="#toUnicode-2"><b>toUnicode</b></a> ( const&nbsp;QByteArray&nbsp;&amp;&nbsp;a, int&nbsp;len ) const</li>
52<li class=fn>QString <a href="#toUnicode-3"><b>toUnicode</b></a> ( const&nbsp;QByteArray&nbsp;&amp;&nbsp;a ) const</li>
53<li class=fn>QString <a href="#toUnicode-4"><b>toUnicode</b></a> ( const&nbsp;QCString&nbsp;&amp;&nbsp;a, int&nbsp;len ) const</li>
54<li class=fn>QString <a href="#toUnicode-5"><b>toUnicode</b></a> ( const&nbsp;QCString&nbsp;&amp;&nbsp;a ) const</li>
55<li class=fn>QString <a href="#toUnicode-6"><b>toUnicode</b></a> ( const&nbsp;char&nbsp;*&nbsp;chars ) const</li>
56<li class=fn>virtual bool <a href="#canEncode"><b>canEncode</b></a> ( QChar&nbsp;ch ) const</li>
57<li class=fn>virtual bool <a href="#canEncode-2"><b>canEncode</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;s ) const</li>
58<li class=fn>virtual int <a href="#heuristicContentMatch"><b>heuristicContentMatch</b></a> ( const&nbsp;char&nbsp;*&nbsp;chars, int&nbsp;len ) const = 0</li>
59<li class=fn>virtual int <a href="#heuristicNameMatch"><b>heuristicNameMatch</b></a> ( const&nbsp;char&nbsp;*&nbsp;hint ) const</li>
60</ul>
61<h2>Static Public Members</h2>
62<ul>
63<li class=fn>QTextCodec * <a href="#loadCharmap"><b>loadCharmap</b></a> ( QIODevice&nbsp;*&nbsp;iod )</li>
64<li class=fn>QTextCodec * <a href="#loadCharmapFile"><b>loadCharmapFile</b></a> ( QString&nbsp;filename )</li>
65<li class=fn>QTextCodec * <a href="#codecForMib"><b>codecForMib</b></a> ( int&nbsp;mib )</li>
66<li class=fn>QTextCodec * <a href="#codecForName"><b>codecForName</b></a> ( const&nbsp;char&nbsp;*&nbsp;name, int&nbsp;accuracy = 0 )</li>
67<li class=fn>QTextCodec * <a href="#codecForContent"><b>codecForContent</b></a> ( const&nbsp;char&nbsp;*&nbsp;chars, int&nbsp;len )</li>
68<li class=fn>QTextCodec * <a href="#codecForIndex"><b>codecForIndex</b></a> ( int&nbsp;i )</li>
69<li class=fn>QTextCodec * <a href="#codecForLocale"><b>codecForLocale</b></a> ()</li>
70<li class=fn>void <a href="#setCodecForLocale"><b>setCodecForLocale</b></a> ( QTextCodec&nbsp;*&nbsp;c )</li>
71<li class=fn>QTextCodec * <a href="#codecForTr"><b>codecForTr</b></a> ()</li>
72<li class=fn>void <a href="#setCodecForTr"><b>setCodecForTr</b></a> ( QTextCodec&nbsp;*&nbsp;c )</li>
73<li class=fn>QTextCodec * <a href="#codecForCStrings"><b>codecForCStrings</b></a> ()</li>
74<li class=fn>void <a href="#setCodecForCStrings"><b>setCodecForCStrings</b></a> ( QTextCodec&nbsp;*&nbsp;c )</li>
75<li class=fn>void <a href="#deleteAllCodecs"><b>deleteAllCodecs</b></a> ()</li>
76<li class=fn>const char * <a href="#locale"><b>locale</b></a> ()</li>
77</ul>
78<h2>Protected Members</h2>
79<ul>
80<li class=fn><a href="#QTextCodec"><b>QTextCodec</b></a> ()</li>
81</ul>
82<h2>Static Protected Members</h2>
83<ul>
84<li class=fn>int <a href="#simpleHeuristicNameMatch"><b>simpleHeuristicNameMatch</b></a> ( const&nbsp;char&nbsp;*&nbsp;name, const&nbsp;char&nbsp;*&nbsp;hint )</li>
85</ul>
86<hr><a name="details"></a><h2>Detailed Description</h2>
87
88
89The QTextCodec class provides conversion between text encodings.
90
91
92<p> Qt uses Unicode to store, draw and manipulate strings. In many
93situations you may wish to deal with data that uses a different
94encoding. For example, most Japanese documents are still stored in
95Shift-JIS or ISO2022, while Russian users often have their
96documents in KOI8-R or CP1251.
97<p> Qt provides a set of QTextCodec classes to help with converting
98non-Unicode formats to and from Unicode. You can also create your
99own codec classes (<a href="#subclassing">see later</a>).
100<p> The supported encodings are:
101<ul>
102<li> Latin1
103<li> Big5 -- Chinese
104<li> Big5-HKSCS -- Chinese
105<li> eucJP -- Japanese
106<li> eucKR -- Korean
107<li> GB2312 -- Chinese
108<li> GBK -- Chinese
109<li> GB18030 -- Chinese
110<li> JIS7 -- Japanese
111<li> Shift-JIS -- Japanese
112<li> TSCII -- Tamil
113<li> utf8 -- Unicode, 8-bit
114<li> utf16 -- Unicode
115<li> KOI8-R -- Russian
116<li> KOI8-U -- Ukrainian
117<li> ISO8859-1 -- Western
118<li> ISO8859-2 -- Central European
119<li> ISO8859-3 -- Central European
120<li> ISO8859-4 -- Baltic
121<li> ISO8859-5 -- Cyrillic
122<li> ISO8859-6 -- Arabic
123<li> ISO8859-7 -- Greek
124<li> ISO8859-8 -- Hebrew, visually ordered
125<li> ISO8859-8-i -- Hebrew, logically ordered
126<li> ISO8859-9 -- Turkish
127<li> ISO8859-10
128<li> ISO8859-13
129<li> ISO8859-14
130<li> ISO8859-15 -- Western
131<li> IBM 850
132<li> IBM 866
133<li> CP874
134<li> CP1250 -- Central European
135<li> CP1251 -- Cyrillic
136<li> CP1252 -- Western
137<li> CP1253 -- Greek
138<li> CP1254 -- Turkish
139<li> CP1255 -- Hebrew
140<li> CP1256 -- Arabic
141<li> CP1257 -- Baltic
142<li> CP1258
143<li> Apple Roman
144<li> TIS-620 -- Thai
145</ul>
146<p> QTextCodecs can be used as follows to convert some locally encoded
147string to Unicode. Suppose you have some string encoded in Russian
148KOI8-R encoding, and want to convert it to Unicode. The simple way
149to do this is:
150<p> <pre>
151 <a href="qcstring.html">QCString</a> locallyEncoded = "..."; // text to convert
152 QTextCodec *codec = QTextCodec::<a href="#codecForName">codecForName</a>("KOI8-R"); // get the codec for KOI8-R
153 <a href="qstring.html">QString</a> unicodeString = codec-&gt;<a href="#toUnicode">toUnicode</a>( locallyEncoded );
154 </pre>
155
156<p> After this, <tt>unicodeString</tt> holds the text converted to Unicode.
157Converting a string from Unicode to the local encoding is just as
158easy:
159<p> <pre>
160 <a href="qstring.html">QString</a> unicodeString = "..."; // any Unicode text
161 QTextCodec *codec = QTextCodec::<a href="#codecForName">codecForName</a>("KOI8-R"); // get the codec for KOI8-R
162 <a href="qcstring.html">QCString</a> locallyEncoded = codec-&gt;<a href="#fromUnicode">fromUnicode</a>( unicodeString );
163 </pre>
164
165<p> Some care must be taken when trying to convert the data in chunks,
166for example, when receiving it over a network. In such cases it is
167possible that a multi-byte character will be split over two
168chunks. At best this might result in the loss of a character and
169at worst cause the entire conversion to fail.
170<p> The approach to use in these situations is to create a <a href="qtextdecoder.html">QTextDecoder</a>
171object for the codec and use this QTextDecoder for the whole
172decoding process, as shown below:
173<p> <pre>
174 QTextCodec *codec = QTextCodec::<a href="#codecForName">codecForName</a>( "Shift-JIS" );
175 <a href="qtextdecoder.html">QTextDecoder</a> *decoder = codec-&gt;<a href="#makeDecoder">makeDecoder</a>();
176
177 <a href="qstring.html">QString</a> unicodeString;
178 while( receiving_data ) {
179 <a href="qbytearray.html">QByteArray</a> chunk = new_data;
180 unicodeString += decoder-&gt;<a href="qtextdecoder.html#toUnicode">toUnicode</a>( chunk.<a href="qmemarray.html#data">data</a>(), chunk.length() );
181 }
182 </pre>
183
184<p> The QTextDecoder object maintains state between chunks and therefore
185works correctly even if a multi-byte character is split between
186chunks.
187<p> <a name="subclassing"></a>
188<h3> Creating your own Codec class
189</h3>
190<a name="1"></a><p> Support for new text encodings can be added to Qt by creating
191QTextCodec subclasses.
192<p> Built-in codecs can be overridden by custom codecs since more
193recently created QTextCodec objects take precedence over earlier
194ones.
195<p> You may find it more convenient to make your codec class available
196as a plugin; see the <a href="plugins-howto.html">plugin
197 documentation</a> for more details.
198<p> The abstract virtual functions describe the encoder to the
199system and the coder is used as required in the different
200text file formats supported by <a href="qtextstream.html">QTextStream</a>, and under X11, for the
201locale-specific character input and output.
202<p> To add support for another 8-bit encoding to Qt, make a subclass
203of QTextCodec and implement at least the following methods:
204<p> <pre>
205 const char* name() const
206 </pre>
207
208Return the official name for the encoding.
209<p> <pre>
210 int mibEnum() const
211 </pre>
212
213Return the MIB enum for the encoding if it is listed in the
214<a href="http://www.iana.org/assignments/character-sets">IANA character-sets encoding file</a>.
215<p> If the encoding is multi-byte then it will have "state"; that is,
216the interpretation of some bytes will be dependent on some preceding
217bytes. For such encodings, you must implement:
218<p> <pre>
219 <a href="qtextdecoder.html">QTextDecoder</a>* makeDecoder() const
220 </pre>
221
222Return a <a href="qtextdecoder.html">QTextDecoder</a> that remembers incomplete multi-byte sequence
223prefixes or other required state.
224<p> If the encoding does <em>not</em> require state, you should implement:
225<p> <pre>
226 <a href="qstring.html">QString</a> toUnicode(const char* chars, int len) const
227 </pre>
228
229Converts <em>len</em> characters from <em>chars</em> to Unicode.
230<p> The base QTextCodec class has default implementations of the above
231two functions, <em>but they are mutually recursive</em>, so you must
232re-implement at least one of them, or both for improved efficiency.
233<p> For conversion from Unicode to 8-bit encodings, it is rarely necessary
234to maintain state. However, two functions similar to the two above
235are used for encoding:
236<p> <pre>
237 <a href="qtextencoder.html">QTextEncoder</a>* makeEncoder() const
238 </pre>
239
240Return a <a href="qtextencoder.html">QTextEncoder</a>.
241<p> <pre>
242 <a href="qcstring.html">QCString</a> fromUnicode(const <a href="qstring.html">QString</a>&amp; uc, int&amp; lenInOut ) const
243 </pre>
244
245Converts <em>lenInOut</em> characters (of type <a href="qchar.html">QChar</a>) from the start of
246the string <em>uc</em>, returning a <a href="qcstring.html">QCString</a> result, and also returning
247the <a href="qcstring.html#length">length</a> of the result in
248<em>lenInOut</em>.
249<p> Again, these are mutually recursive so only one needs to be implemented,
250or both if greater efficiency is possible.
251<p> Finally, you must implement:
252<p> <pre>
253 int heuristicContentMatch(const char* chars, int len) const
254 </pre>
255
256Gives a value indicating how likely it is that <em>len</em> characters
257from <em>chars</em> are in the encoding.
258<p> A good model for this function is the
259QWindowsLocalCodec::heuristicContentMatch function found in the Qt
260sources.
261<p> A QTextCodec subclass might have improved performance if you also
262re-implement:
263<p> <pre>
264 bool canEncode( <a href="qchar.html">QChar</a> ) const
265 </pre>
266
267Test if a Unicode character can be encoded.
268<p> <pre>
269 bool canEncode( const <a href="qstring.html">QString</a>&amp; ) const
270 </pre>
271
272Test if a string of Unicode characters can be encoded.
273<p> <pre>
274 int heuristicNameMatch(const char* hint) const
275 </pre>
276
277Test if a possibly non-standard name is referring to the codec.
278<p> Codecs can also be created as <a href="plugins-howto.html">plugins</a>.
279<p>See also <a href="i18n.html">Internationalization with Qt</a>.
280
281<hr><h2>Member Function Documentation</h2>
282<h3 class=fn><a name="QTextCodec"></a>QTextCodec::QTextCodec ()<tt> [protected]</tt>
283</h3><p><b>Warning:</b> This function is <i>not</i> <a href="threads.html#reentrant">reentrant</a>.</p>
284
285
286<p> Constructs a QTextCodec, and gives it the highest precedence. The
287QTextCodec should always be constructed on the heap (i.e. with <tt>new</tt>). Qt takes ownership and will delete it when the application
288terminates.
289
290<h3 class=fn><a name="~QTextCodec"></a>QTextCodec::~QTextCodec ()<tt> [virtual]</tt>
291</h3><p><b>Warning:</b> This function is <i>not</i> <a href="threads.html#reentrant">reentrant</a>.</p>
292
293
294<p> Destroys the QTextCodec. Note that you should not delete codecs
295yourself: once created they become Qt's responsibility.
296
297<h3 class=fn>bool <a name="canEncode"></a>QTextCodec::canEncode ( <a href="qchar.html">QChar</a>&nbsp;ch ) const<tt> [virtual]</tt>
298</h3>
299Returns TRUE if the Unicode character <em>ch</em> can be fully encoded
300with this codec; otherwise returns FALSE. The default
301implementation tests if the result of <a href="#toUnicode">toUnicode</a>(fromUnicode(ch))
302is the original <em>ch</em>. Subclasses may be able to improve the
303efficiency.
304
305<h3 class=fn>bool <a name="canEncode-2"></a>QTextCodec::canEncode ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;s ) const<tt> [virtual]</tt>
306</h3>
307This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
308<p> <em>s</em> contains the string being tested for encode-ability.
309
310<h3 class=fn><a href="qtextcodec.html">QTextCodec</a>&nbsp;* <a name="codecForCStrings"></a>QTextCodec::codecForCStrings ()<tt> [static]</tt>
311</h3>
312
313<p> Returns the codec used by <a href="qstring.html">QString</a> to convert to and from const
314char* and QCStrings. If this function returns 0 (the default),
315QString assumes Latin-1.
316<p> <p>See also <a href="#setCodecForCStrings">setCodecForCStrings</a>().
317
318<h3 class=fn><a href="qtextcodec.html">QTextCodec</a>&nbsp;* <a name="codecForContent"></a>QTextCodec::codecForContent ( const&nbsp;char&nbsp;*&nbsp;chars, int&nbsp;len )<tt> [static]</tt>
319</h3>
320Searches all installed QTextCodec objects, returning the one which
321most recognizes the given content. May return 0.
322<p> Note that this is often a poor choice, since character encodings
323often use most of the available character sequences, and so only
324by linguistic analysis could a true match be made.
325<p> <em>chars</em> contains the string to check, and <em>len</em> contains the
326number of characters in the string to use.
327<p> <p>See also <a href="#heuristicContentMatch">heuristicContentMatch</a>().
328
329<p>Example: <a href="qwerty-example.html#x391">qwerty/qwerty.cpp</a>.
330<h3 class=fn><a href="qtextcodec.html">QTextCodec</a>&nbsp;* <a name="codecForIndex"></a>QTextCodec::codecForIndex ( int&nbsp;i )<tt> [static]</tt>
331</h3>
332Returns the QTextCodec <em>i</em> positions from the most recently
333inserted codec, or 0 if there is no such QTextCodec. Thus,
334<a href="#codecForIndex">codecForIndex</a>(0) returns the most recently created QTextCodec.
335
336<p>Example: <a href="qwerty-example.html#x392">qwerty/qwerty.cpp</a>.
337<h3 class=fn><a href="qtextcodec.html">QTextCodec</a>&nbsp;* <a name="codecForLocale"></a>QTextCodec::codecForLocale ()<tt> [static]</tt>
338</h3> Returns a pointer to the codec most suitable for this locale.
339<p>Example: <a href="qwerty-example.html#x393">qwerty/qwerty.cpp</a>.
340<h3 class=fn><a href="qtextcodec.html">QTextCodec</a>&nbsp;* <a name="codecForMib"></a>QTextCodec::codecForMib ( int&nbsp;mib )<tt> [static]</tt>
341</h3>
342Returns the QTextCodec which matches the <a href="#mibEnum">MIBenum</a> <em>mib</em>.
343
344<h3 class=fn><a href="qtextcodec.html">QTextCodec</a>&nbsp;* <a name="codecForName"></a>QTextCodec::codecForName ( const&nbsp;char&nbsp;*&nbsp;name, int&nbsp;accuracy = 0 )<tt> [static]</tt>
345</h3>
346Searches all installed QTextCodec objects and returns the one
347which best matches <em>name</em>; the match is case-insensitive. Returns
3480 if no codec's <a href="#heuristicNameMatch">heuristicNameMatch</a>() reports a match better than
349<em>accuracy</em>, or if <em>name</em> is a null string.
350<p> <p>See also <a href="#heuristicNameMatch">heuristicNameMatch</a>().
351
352<h3 class=fn><a href="qtextcodec.html">QTextCodec</a>&nbsp;* <a name="codecForTr"></a>QTextCodec::codecForTr ()<tt> [static]</tt>
353</h3>
354
355<p> Returns the codec used by <a href="qobject.html#tr">QObject::tr</a>() on its argument. If this
356function returns 0 (the default), tr() assumes Latin-1.
357<p> <p>See also <a href="#setCodecForTr">setCodecForTr</a>().
358
359<h3 class=fn>void <a name="deleteAllCodecs"></a>QTextCodec::deleteAllCodecs ()<tt> [static]</tt>
360</h3>
361Deletes all the created codecs.
362<p> <b>Warning:</b> Do not call this function.
363<p> <a href="qapplication.html">QApplication</a> calls this function just before exiting to delete
364any QTextCodec objects that may be lying around. Since various
365other classes hold pointers to QTextCodec objects, it is not safe
366to call this function earlier.
367<p> If you are using the utility classes (like <a href="qstring.html">QString</a>) but not using
368QApplication, calling this function at the very end of your
369application may be helpful for chasing down memory leaks by
370eliminating any QTextCodec objects.
371
372<h3 class=fn><a href="qcstring.html">QCString</a> <a name="fromUnicode"></a>QTextCodec::fromUnicode ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;uc, int&nbsp;&amp;&nbsp;lenInOut ) const<tt> [virtual]</tt>
373</h3>
374QTextCodec subclasses must reimplement either this function or
375<a href="#makeEncoder">makeEncoder</a>(). It converts the first <em>lenInOut</em> characters of <em>uc</em> from Unicode to the encoding of the subclass. If <em>lenInOut</em> is
376negative or too large, the length of <em>uc</em> is used instead.
377<p> Converts <em>lenInOut</em> characters (not bytes) from <em>uc</em>, producing
378a <a href="qcstring.html">QCString</a>. <em>lenInOut</em> will be set to the <a href="qcstring.html#length">length</a> of the result (in bytes).
379<p> The default implementation makes an encoder with makeEncoder() and
380converts the input with that. Note that the default makeEncoder()
381implementation makes an encoder that simply calls this function,
382hence subclasses <em>must</em> reimplement one function or the other to
383avoid infinite recursion.
384
385<p>Reimplemented in <a href="qhebrewcodec.html#fromUnicode">QHebrewCodec</a>.
386<h3 class=fn><a href="qcstring.html">QCString</a> <a name="fromUnicode-2"></a>QTextCodec::fromUnicode ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;uc ) const
387</h3>
388This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
389<p> <em>uc</em> is the unicode source string.
390
391<h3 class=fn>int <a name="heuristicContentMatch"></a>QTextCodec::heuristicContentMatch ( const&nbsp;char&nbsp;*&nbsp;chars, int&nbsp;len ) const<tt> [pure virtual]</tt>
392</h3>
393
394<p> QTextCodec subclasses must reimplement this function. It examines
395the first <em>len</em> bytes of <em>chars</em> and returns a value indicating
396how likely it is that the string is a prefix of text encoded in
397the encoding of the subclass. A negative return value indicates
398that the text is detectably not in the encoding (e.g. it contains
399characters undefined in the encoding). A return value of 0
400indicates that the text should be decoded with this codec rather
401than as ASCII, but there is no particular evidence. The value
402should range up to <em>len</em>. Thus, most decoders will return -1, 0,
403or -<em>len</em>.
404<p> The characters are not null terminated.
405<p> <p>See also <a href="#codecForContent">codecForContent</a>().
406
407<h3 class=fn>int <a name="heuristicNameMatch"></a>QTextCodec::heuristicNameMatch ( const&nbsp;char&nbsp;*&nbsp;hint ) const<tt> [virtual]</tt>
408</h3>
409Returns a value indicating how likely it is that this decoder is
410appropriate for decoding some format that has the given name. The
411name is compared with the <em>hint</em>.
412<p> A good match returns a positive number around the length of the
413string. A bad match is negative.
414<p> The default implementation calls <a href="#simpleHeuristicNameMatch">simpleHeuristicNameMatch</a>() with
415the name of the codec.
416
417<h3 class=fn><a href="qtextcodec.html">QTextCodec</a>&nbsp;* <a name="loadCharmap"></a>QTextCodec::loadCharmap ( <a href="qiodevice.html">QIODevice</a>&nbsp;*&nbsp;iod )<tt> [static]</tt>
418</h3>
419Reads a POSIX2 charmap definition from <em>iod</em>.
420The parser recognizes the following lines:
421<p> <font name="sans">
422&nbsp;&nbsp;&lt;code_set_name&gt; <i>name</i></br>
423&nbsp;&nbsp;&lt;escape_char&gt; <i>character</i></br>
424&nbsp;&nbsp;% alias <i>alias</i></br>
425&nbsp;&nbsp;CHARMAP</br>
426&nbsp;&nbsp;&lt;<i>token</i>&gt; /x<i>hexbyte</i> &lt;U<i>unicode</i>&gt; ...</br>
427&nbsp;&nbsp;&lt;<i>token</i>&gt; /d<i>decbyte</i> &lt;U<i>unicode</i>&gt; ...</br>
428&nbsp;&nbsp;&lt;<i>token</i>&gt; /<i>octbyte</i> &lt;U<i>unicode</i>&gt; ...</br>
429&nbsp;&nbsp;&lt;<i>token</i>&gt; /<i>any</i>/<i>any</i>... &lt;U<i>unicode</i>&gt; ...</br>
430&nbsp;&nbsp;END CHARMAP</br>
431</font>
432<p> The resulting QTextCodec is returned (and also added to the global
433list of codecs). The <a href="#name">name</a>() of the result is taken from the
434code_set_name.
435<p> Note that a codec constructed in this way uses much more memory
436and is slower than a hand-written QTextCodec subclass, since
437tables in code are kept in memory shared by all Qt applications.
438<p> <p>See also <a href="#loadCharmapFile">loadCharmapFile</a>().
439
440<p>Example: <a href="qwerty-example.html#x394">qwerty/qwerty.cpp</a>.
441<h3 class=fn><a href="qtextcodec.html">QTextCodec</a>&nbsp;* <a name="loadCharmapFile"></a>QTextCodec::loadCharmapFile ( <a href="qstring.html">QString</a>&nbsp;filename )<tt> [static]</tt>
442</h3>
443A convenience function for <a href="#loadCharmap">loadCharmap</a>() that loads the charmap
444definition from the file <em>filename</em>.
445
446<h3 class=fn>const char * <a name="locale"></a>QTextCodec::locale ()<tt> [static]</tt>
447</h3>
448Returns a string representing the current language and
449sublanguage, e.g. "pt" for Portuguese, or "pt_br" for Portuguese/Brazil.
450
451<p>Example: <a href="i18n-example.html#x1949">i18n/main.cpp</a>.
452<h3 class=fn><a href="qtextdecoder.html">QTextDecoder</a>&nbsp;* <a name="makeDecoder"></a>QTextCodec::makeDecoder () const<tt> [virtual]</tt>
453</h3>
454Creates a <a href="qtextdecoder.html">QTextDecoder</a> which stores enough state to decode chunks
455of char* data to create chunks of Unicode data. The default
456implementation creates a stateless decoder, which is only
457sufficient for the simplest encodings where each byte corresponds
458to exactly one Unicode character.
459<p> The caller is responsible for deleting the returned object.
460
461<h3 class=fn><a href="qtextencoder.html">QTextEncoder</a>&nbsp;* <a name="makeEncoder"></a>QTextCodec::makeEncoder () const<tt> [virtual]</tt>
462</h3>
463Creates a <a href="qtextencoder.html">QTextEncoder</a> which stores enough state to encode chunks
464of Unicode data as char* data. The default implementation creates
465a stateless encoder, which is only sufficient for the simplest
466encodings where each Unicode character corresponds to exactly one
467character.
468<p> The caller is responsible for deleting the returned object.
469
470<h3 class=fn>int <a name="mibEnum"></a>QTextCodec::mibEnum () const<tt> [pure virtual]</tt>
471</h3>
472
473<p> Subclasses of QTextCodec must reimplement this function. It
474returns the MIBenum (see <a href="http://www.iana.org/assignments/character-sets">the
475 IANA character-sets encoding file</a> for more information).
476It is important that each QTextCodec subclass returns the correct
477unique value for this function.
478
479<p>Reimplemented in <a href="qeucjpcodec.html#mibEnum">QEucJpCodec</a>.
480<h3 class=fn>const char * <a name="mimeName"></a>QTextCodec::mimeName () const<tt> [virtual]</tt>
481</h3>
482Returns the preferred mime name of the encoding as defined in the
483<a href="http://www.iana.org/assignments/character-sets">IANA character-sets encoding file</a>.
484
485<p>Reimplemented in <a href="qeucjpcodec.html#mimeName">QEucJpCodec</a>, <a href="qeuckrcodec.html#mimeName">QEucKrCodec</a>, <a href="qjiscodec.html#mimeName">QJisCodec</a>, <a href="qhebrewcodec.html#mimeName">QHebrewCodec</a>, and <a href="qsjiscodec.html#mimeName">QSjisCodec</a>.
486<h3 class=fn>const char * <a name="name"></a>QTextCodec::name () const<tt> [pure virtual]</tt>
487</h3>
488
489<p> QTextCodec subclasses must reimplement this function. It returns
490the name of the encoding supported by the subclass. When choosing
491a name for an encoding, consider these points:
492<ul>
493<li> On X11, <a href="#heuristicNameMatch">heuristicNameMatch</a>( const char * hint )
494is used to test if a the QTextCodec
495can convert between Unicode and the encoding of a font
496with encoding <em>hint</em>, such as "iso8859-1" for Latin-1 fonts,
497"koi8-r" for Russian KOI8 fonts.
498The default algorithm of heuristicNameMatch() uses <a href="#name">name</a>().
499<li> Some applications may use this function to present
500encodings to the end user.
501</ul>
502
503<p>Example: <a href="qwerty-example.html#x395">qwerty/qwerty.cpp</a>.
504<h3 class=fn>void <a name="setCodecForCStrings"></a>QTextCodec::setCodecForCStrings ( <a href="qtextcodec.html">QTextCodec</a>&nbsp;*&nbsp;c )<tt> [static]</tt>
505</h3><p><b>Warning:</b> This function is <i>not</i> <a href="threads.html#reentrant">reentrant</a>.</p>
506
507
508
509<p> Sets the codec used by <a href="qstring.html">QString</a> to convert to and from const char*
510and QCStrings. If <em>c</em> is 0 (the default), QString assumes Latin-1.
511<p> <b>Warning:</b> Some codecs do not preserve the characters in the ascii
512range (0x00 to 0x7f). For example, the Japanese Shift-JIS
513encoding maps the backslash character (0x5a) to the Yen character.
514This leads to unexpected results when using the backslash
515character to escape characters in strings used in e.g. regular
516expressions. Use <a href="qstring.html#fromLatin1">QString::fromLatin1</a>() to preserve characters in
517the ascii range when needed.
518<p> <p>See also <a href="#codecForCStrings">codecForCStrings</a>() and <a href="#setCodecForTr">setCodecForTr</a>().
519
520<h3 class=fn>void <a name="setCodecForLocale"></a>QTextCodec::setCodecForLocale ( <a href="qtextcodec.html">QTextCodec</a>&nbsp;*&nbsp;c )<tt> [static]</tt>
521</h3>
522Set the codec to <em>c</em>; this will be returned by <a href="#codecForLocale">codecForLocale</a>().
523This might be needed for some applications that want to use their
524own mechanism for setting the locale.
525<p> <p>See also <a href="#codecForLocale">codecForLocale</a>().
526
527<h3 class=fn>void <a name="setCodecForTr"></a>QTextCodec::setCodecForTr ( <a href="qtextcodec.html">QTextCodec</a>&nbsp;*&nbsp;c )<tt> [static]</tt>
528</h3><p><b>Warning:</b> This function is <i>not</i> <a href="threads.html#reentrant">reentrant</a>.</p>
529
530
531
532<p> Sets the codec used by <a href="qobject.html#tr">QObject::tr</a>() on its argument to <em>c</em>. If
533<em>c</em> is 0 (the default), tr() assumes Latin-1.
534<p> If the literal quoted text in the program is not in the Latin-1
535encoding, this function can be used to set the appropriate
536encoding. For example, software developed by Korean programmers
537might use eucKR for all the text in the program, in which case the
538main() function might look like this:
539<p> <pre>
540 int main(int argc, char** argv)
541 {
542 <a href="qapplication.html">QApplication</a> app(argc, argv);
543 ... install any additional codecs ...
544 QTextCodec::<a href="#setCodecForTr">setCodecForTr</a>( QTextCodec::<a href="#codecForName">codecForName</a>("eucKR") );
545 ...
546 }
547 </pre>
548
549<p> Note that this is not the way to select the encoding that the <em>user</em> has chosen. For example, to convert an application containing
550literal English strings to Korean, all that is needed is for the
551English strings to be passed through tr() and for translation
552files to be loaded. For details of <a href="i18n.html#internationalization">internationalization</a>, see the
553<a href="i18n.html">Qt internationalization documentation</a>.
554<p> <p>See also <a href="#codecForTr">codecForTr</a>() and <a href="#setCodecForCStrings">setCodecForCStrings</a>().
555
556<h3 class=fn>int <a name="simpleHeuristicNameMatch"></a>QTextCodec::simpleHeuristicNameMatch ( const&nbsp;char&nbsp;*&nbsp;name, const&nbsp;char&nbsp;*&nbsp;hint )<tt> [static protected]</tt>
557</h3>
558A simple utility function for <a href="#heuristicNameMatch">heuristicNameMatch</a>(): it does some
559very minor character-skipping so that almost-exact matches score
560high. <em>name</em> is the text we're matching and <em>hint</em> is used for
561the comparison.
562
563<h3 class=fn><a href="qstring.html">QString</a> <a name="toUnicode"></a>QTextCodec::toUnicode ( const&nbsp;char&nbsp;*&nbsp;chars, int&nbsp;len ) const<tt> [virtual]</tt>
564</h3>
565QTextCodec subclasses must reimplement this function or
566<a href="#makeDecoder">makeDecoder</a>(). It converts the first <em>len</em> characters of <em>chars</em>
567to Unicode.
568<p> The default implementation makes a decoder with makeDecoder() and
569converts the input with that. Note that the default makeDecoder()
570implementation makes a decoder that simply calls
571this function, hence subclasses <em>must</em> reimplement one function or
572the other to avoid infinite recursion.
573
574<h3 class=fn><a href="qstring.html">QString</a> <a name="toUnicode-2"></a>QTextCodec::toUnicode ( const&nbsp;<a href="qbytearray.html">QByteArray</a>&nbsp;&amp;&nbsp;a, int&nbsp;len ) const
575</h3>
576This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
577<p> <em>a</em> contains the source characters; <em>len</em> contains the number of
578characters in <em>a</em> to use.
579
580<h3 class=fn><a href="qstring.html">QString</a> <a name="toUnicode-3"></a>QTextCodec::toUnicode ( const&nbsp;<a href="qbytearray.html">QByteArray</a>&nbsp;&amp;&nbsp;a ) const
581</h3>
582This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
583<p> <em>a</em> contains the source characters.
584
585<h3 class=fn><a href="qstring.html">QString</a> <a name="toUnicode-4"></a>QTextCodec::toUnicode ( const&nbsp;<a href="qcstring.html">QCString</a>&nbsp;&amp;&nbsp;a, int&nbsp;len ) const
586</h3>
587This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
588<p> <em>a</em> contains the source characters; <em>len</em> contains the number of
589characters in <em>a</em> to use.
590
591<h3 class=fn><a href="qstring.html">QString</a> <a name="toUnicode-5"></a>QTextCodec::toUnicode ( const&nbsp;<a href="qcstring.html">QCString</a>&nbsp;&amp;&nbsp;a ) const
592</h3>
593This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
594<p> <em>a</em> contains the source characters.
595
596<h3 class=fn><a href="qstring.html">QString</a> <a name="toUnicode-6"></a>QTextCodec::toUnicode ( const&nbsp;char&nbsp;*&nbsp;chars ) const
597</h3>
598This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
599<p> <em>chars</em> contains the source characters.
600
601<!-- eof -->
602<hr><p>
603This file is part of the <a href="index.html">Qt toolkit</a>.
604Copyright &copy; 1995-2007
605<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
606<table width=100% cellspacing=0 border=0><tr>
607<td>Copyright &copy; 2007
608<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
609<td align=right><div align=right>Qt 3.3.8</div>
610</table></div></address></body>
611</html>
Note: See TracBrowser for help on using the repository browser.