<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Class Poco::TextEncoding</title> <meta http-equiv="content-type" content="text/html; charset=utf-8"/> <meta name="author" content="Applied Informatics Software Engineering GmbH and Contributors"/> <meta name="publisher" content="Applied Informatics Software Engineering GmbH and Contributors"/> <meta name="copyright" content="Copyright (c) 2009, Applied Informatics Software Engineering GmbH and Contributors"/> <meta name="language" content="en"/> <meta name="date" content="2009-11-24"/> <meta name="generator" content="PocoDoc"/> <link rel="stylesheet" href="css/styles.css" type="text/css"/> </head> <body bgcolor="#ffffff" leftmargin="0" topmargin="0"> <div class="header"> <h1 class="namespace"><a href="Poco.html" class="namespace">Poco</a></h1> <h1 class="symbol">class TextEncoding</h1> </div> <div class="body"> <p> <b>Library:</b> Foundation<br /> <b>Package:</b> Text<br /> <b>Header:</b> Poco/TextEncoding.h</p> <h2>Description</h2> <div class="description"> <p>An abstract base class for implementing text encodings like UTF-8 or ISO 8859-1. </p> <p>Subclasses must override the <a href="Poco.TextEncoding.html#10746" title="Poco::TextEncoding::canonicalName()">canonicalName</a>(), <a href="Poco.TextEncoding.html#10747" title="Poco::TextEncoding::isA()">isA</a>(), <a href="Poco.TextEncoding.html#10749" title="Poco::TextEncoding::characterMap()">characterMap</a>() and <a href="Poco.TextEncoding.html#10750" title="Poco::TextEncoding::convert()">convert</a>() methods and need to be thread safe and stateless. </p> <p><a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a> also provides static member functions for managing mappings from encoding names to <a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a> objects. </p> </div> <h2>Inheritance</h2> <p><b>Known Derived Classes: </b><a href="Poco.ASCIIEncoding.html" title="class Poco::ASCIIEncoding">ASCIIEncoding</a>, <a href="Poco.Latin1Encoding.html" title="class Poco::Latin1Encoding">Latin1Encoding</a>, <a href="Poco.Latin9Encoding.html" title="class Poco::Latin9Encoding">Latin9Encoding</a>, <a href="Poco.UTF16Encoding.html" title="class Poco::UTF16Encoding">UTF16Encoding</a>, <a href="Poco.UTF8Encoding.html" title="class Poco::UTF8Encoding">UTF8Encoding</a>, <a href="Poco.Windows1252Encoding.html" title="class Poco::Windows1252Encoding">Windows1252Encoding</a></p> <h2>Member Summary</h2> <p><b>Member Functions: </b><a href="Poco.TextEncoding.html#10766" title="Poco::TextEncoding::add()">add</a>, <a href="Poco.TextEncoding.html#10762" title="Poco::TextEncoding::byName()">byName</a>, <a href="Poco.TextEncoding.html#10746" title="Poco::TextEncoding::canonicalName()">canonicalName</a>, <a href="Poco.TextEncoding.html#10749" title="Poco::TextEncoding::characterMap()">characterMap</a>, <a href="Poco.TextEncoding.html#10750" title="Poco::TextEncoding::convert()">convert</a>, <a href="Poco.TextEncoding.html#10764" title="Poco::TextEncoding::find()">find</a>, <a href="Poco.TextEncoding.html#10773" title="Poco::TextEncoding::global()">global</a>, <a href="Poco.TextEncoding.html#10747" title="Poco::TextEncoding::isA()">isA</a>, <a href="Poco.TextEncoding.html#10777" title="Poco::TextEncoding::manager()">manager</a>, <a href="Poco.TextEncoding.html#10752" title="Poco::TextEncoding::queryConvert()">queryConvert</a>, <a href="Poco.TextEncoding.html#10771" title="Poco::TextEncoding::remove()">remove</a>, <a href="Poco.TextEncoding.html#10755" title="Poco::TextEncoding::sequenceLength()">sequenceLength</a></p> <h2>Types</h2> <h3><a name="10744">CharacterMap</a></h3> <p class="decl">typedef int <a href="Poco.TextEncoding.html#10744" title="Poco::TextEncoding::CharacterMap">CharacterMap</a>[256];</p> <div class="description"> <p>The map[b] member gives information about byte sequences whose first byte is b. If map[b] is c where c is >= 0, then b by itself encodes the <a href="Poco.Unicode.html" title="class Poco::Unicode">Unicode</a> scalar value c. If map[b] is -1, then the byte sequence is malformed. If map[b] is -n, where n >= 2, then b is the first byte of an n-byte sequence that encodes a single <a href="Poco.Unicode.html" title="class Poco::Unicode">Unicode</a> scalar value. Byte sequences up to 6 bytes in length are supported. </p> </div> <h3><a name="10741">Ptr</a></h3> <p class="decl">typedef <a href="Poco.SharedPtr.html" title="class Poco::SharedPtr">SharedPtr</a> < <a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a> > <a href="Poco.TextEncoding.html#10741" title="Poco::TextEncoding::Ptr">Ptr</a>;</p> <div class="description"> <p></p> </div> <h2>Enumerations</h2> <h3><i>Anonymous</i></h3> <div class="description"> <p></p> </div> <p class="decl"><a name="10743">MAX_SEQUENCE_LENGTH</a> = 6</p> <div class="description"> <p>The maximum character byte sequence length supported. </p> </div> <h2>Destructor</h2> <h3><a name="10745">~TextEncoding</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">virtual ~<a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a>();</p> <div class="description"> <p>Destroys the encoding. </p> </div> <h2>Member Functions</h2> <h3><a name="10766">add</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">static void add(<br /> <a href="Poco.TextEncoding.html#10741" title="Poco::TextEncoding::Ptr">TextEncoding::Ptr</a> encoding<br />);</p> <div class="description"> <p>Adds the given <a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a> to the table of text encodings, under the encoding's canonical name. </p> <p>If an encoding with the given name is already registered, it is replaced. </p> </div> <h3><a name="10768">add</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">static void add(<br /> <a href="Poco.TextEncoding.html#10741" title="Poco::TextEncoding::Ptr">TextEncoding::Ptr</a> encoding,<br /> const std::string & name<br />);</p> <div class="description"> <p>Adds the given <a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a> to the table of text encodings, under the given name. </p> <p>If an encoding with the given name is already registered, it is replaced. </p> </div> <h3><a name="10762">byName</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">static <a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a> & byName(<br /> const std::string & encodingName<br />);</p> <div class="description"> <p>Returns the <a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a> object for the given encoding name. </p> <p>Throws a <a href="Poco.NotFoundException.html" title="class Poco::NotFoundException">NotFoundException</a> if the encoding with given name is not available. </p> </div> <h3><a name="10746">canonicalName</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">virtual const char * canonicalName() const = 0;</p> <div class="description"> <p>Returns the canonical name of this encoding, e.g. "ISO-8859-1". Encoding name comparisons are case insensitive. </p> </div> <h3><a name="10749">characterMap</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">virtual const <a href="Poco.TextEncoding.html#10744" title="Poco::TextEncoding::CharacterMap">CharacterMap</a> & characterMap() const = 0;</p> <div class="description"> <p>Returns the <a href="Poco.TextEncoding.html#10744" title="Poco::TextEncoding::CharacterMap">CharacterMap</a> for the encoding. The <a href="Poco.TextEncoding.html#10744" title="Poco::TextEncoding::CharacterMap">CharacterMap</a> should be kept in a static member. As <a href="Poco.TextEncoding.html#10749" title="Poco::TextEncoding::characterMap()">characterMap</a>() can be called frequently, it should be implemented in such a way that it just returns a static map. If the map is built at runtime, this should be done in the constructor. </p> </div> <h3><a name="10750">convert</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">virtual int convert(<br /> const unsigned char * bytes<br />) const;</p> <div class="description"> <p>The convert function is used to convert multibyte sequences; bytes will point to a byte sequence of n bytes where <a href="Poco.TextEncoding.html#10755" title="Poco::TextEncoding::sequenceLength()">sequenceLength</a>(bytes, length) == -n, with length >= n. </p> <p>The convert function must return the <a href="Poco.Unicode.html" title="class Poco::Unicode">Unicode</a> scalar value represented by this byte sequence or -1 if the byte sequence is malformed. The default implementation returns (int) bytes[0]. </p> </div> <h3><a name="10758">convert</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">virtual int convert(<br /> int ch,<br /> unsigned char * bytes,<br /> int length<br />) const;</p> <div class="description"> <p>Transform the <a href="Poco.Unicode.html" title="class Poco::Unicode">Unicode</a> character ch into the encoding's byte sequence. The method returns the number of bytes used. The method must not use more than length characters. Bytes and length can also be null - in this case only the number of bytes required to represent ch is returned. If the character cannot be converted, 0 is returned and the byte sequence remains unchanged. The default implementation simply returns 0. </p> </div> <h3><a name="10764">find</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">static <a href="Poco.TextEncoding.html#10741" title="Poco::TextEncoding::Ptr">TextEncoding::Ptr</a> find(<br /> const std::string & encodingName<br />);</p> <div class="description"> <p>Returns a pointer to the <a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a> object for the given encodingName, or NULL if no such <a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a> object exists. </p> </div> <h3><a name="10773">global</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">static <a href="Poco.TextEncoding.html#10741" title="Poco::TextEncoding::Ptr">TextEncoding::Ptr</a> global(<br /> <a href="Poco.TextEncoding.html#10741" title="Poco::TextEncoding::Ptr">TextEncoding::Ptr</a> encoding<br />);</p> <div class="description"> <p>Sets global <a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a> object. </p> <p>This function sets the global encoding to the argument and returns a reference of the previous global encoding. </p> </div> <h3><a name="10775">global</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">static <a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a> & global();</p> <div class="description"> <p>Return the current global <a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a> object </p> </div> <h3><a name="10747">isA</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">virtual bool isA(<br /> const std::string & encodingName<br />) const = 0;</p> <div class="description"> <p>Returns true if the given name is one of the names of this encoding. For example, the "ISO-8859-1" encoding is also known as "Latin-1". </p> <p>Encoding name comparision are be case insensitive. </p> </div> <h3><a name="10752">queryConvert</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">virtual int queryConvert(<br /> const unsigned char * bytes,<br /> int length<br />) const;</p> <div class="description"> <p>The queryConvert function is used to convert single byte characters or multibyte sequences; bytes will point to a byte sequence of length bytes. </p> <p>The queryConvert function must return the <a href="Poco.Unicode.html" title="class Poco::Unicode">Unicode</a> scalar value represented by this byte sequence or -1 if the byte sequence is malformed or -n where n is number of bytes requested for the sequence, if lenght is shorter than the sequence. The length of the sequence might not be determined by the first byte, in which case the conversion becomes an iterative process: First call with length == 1 might return -2, Then a second call with lenght == 2 might return -4 Eventually, the third call with length == 4 should return either a <a href="Poco.Unicode.html" title="class Poco::Unicode">Unicode</a> scalar value, or -1 if the byte sequence is malformed. The default implementation returns (int) bytes[0]. </p> </div> <h3><a name="10771">remove</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">static void remove(<br /> const std::string & encodingName<br />);</p> <div class="description"> <p>Removes the encoding with the given name from the table of text encodings. </p> </div> <h3><a name="10755">sequenceLength</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">virtual int sequenceLength(<br /> const unsigned char * bytes,<br /> int length<br />) const;</p> <div class="description"> <p>The sequenceLength function is used to get the lenth of the sequence pointed by bytes. The length paramater should be greater or equal to the length of the sequence. </p> <p>The sequenceLength function must return the lenght of the sequence represented by this byte sequence or a negative value -n if length is shorter than the sequence, where n is the number of byte requested to determine the length of the sequence. The length of the sequence might not be determined by the first byte, in which case the conversion becomes an iterative process as long as the result is negative: First call with length == 1 might return -2, Then a second call with lenght == 2 might return -4 Eventually, the third call with length == 4 should return 4. The default implementation returns 1. </p> </div> <h3><a name="10777">manager</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">static TextEncodingManager & manager();</p> <div class="description"> <p>Returns the TextEncodingManager. </p> </div> <h2>Variables</h2> <h3><a name="10776">GLOBAL</a> <img src="images/static.gif" alt="static" title="static" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">static const std::string <a href="Poco.TextEncoding.html#10776" title="Poco::TextEncoding::GLOBAL">GLOBAL</a>;</p> <div class="description"> <p>Name of the global <a href="Poco.TextEncoding.html" title="class Poco::TextEncoding">TextEncoding</a>, which is the empty string. </p> </div> <p class="footer">POCO C++ Libraries 1.3.6-all<br /> Copyright © 2009, <a href="http://pocoproject.org/" target="_blank">Applied Informatics Software Engineering GmbH and Contributors</a></p> </div> </body> </html>
