Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Ref/Encoding::Converter: Write reference page for Encoding::Converter.

  • Loading branch information...
commit 081c67ce030344d717167461cd54266c31aa52c4 1 parent 234d40f
@runpaint authored
Showing with 42 additions and 0 deletions.
  1. +1 −0  book.xml
  2. +41 −0 src/ref/encoding-converter.xml
View
1  book.xml
@@ -52,6 +52,7 @@
<xi:include href="src/ref/complex.xml"/>
<xi:include href="src/ref/dir.xml"/>
<xi:include href="src/ref/encoding.xml"/>
+ <xi:include href="src/ref/encoding-converter.xml"/>
<xi:include href="src/ref/enumerable.xml"/>
<xi:include href="src/ref/enumerator.xml"/>
<xi:include href="src/ref/exception.xml"/>
View
41 src/ref/encoding-converter.xml
@@ -0,0 +1,41 @@
+<?xml version="1.0" encoding="utf-8"?>
+<appendix version="5.0"
+ xml:id="ref.encoding-converter"
+ xml:lang="en" xmlns="http://docbook.org/ns/docbook"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink">
+
+ <title>Encoding::Converter</title>
+
+
+ <para><methodsynopsis><type>Encoding or nil</type><methodname>Encoding::Converter.asciicompat_encoding</methodname><methodparam><parameter>encoding</parameter></methodparam></methodsynopsis> Returns the ASCII-compatible encoding corresponding to the given encoding, where <parameter>encoding</parameter> is either an <literal>Encoding</literal> object or an encoding name as a <literal>String</literal>. Returns <literal>nil</literal> if there isn’t such an encoding.</para>
+
+ <para><methodsynopsis><type>Encoding::Converter</type><methodname>Encoding::Converter.new</methodname><methodparam><parameter>source</parameter></methodparam><methodparam><parameter>destination</parameter></methodparam><methodparam choice="opt"><parameter>options</parameter></methodparam></methodsynopsis>
+ <methodsynopsis><type>Encoding::Converter</type><methodname>Encoding::Converter.new</methodname><methodparam><parameter>conversion_path</parameter></methodparam></methodsynopsis> Instantiates an <literal>Encoding::Converter</literal> object for transcoding between a <parameter>source</parameter> and <parameter>destination</parameter> encoding, both of which may be either <literal>Encoding</literal> objects or the names of encodings as <literal>String</literal>s. <parameter>options</parameter> is a <link linkend="enc.options-hash">transcoding options <literal>Hash</literal></link>. If <parameter>conversion_path</parameter> is given it should be an <literal>Array</literal> in the form returned by either <function>Encoding::Converter.search_convpath</function> or <function>Encoding::Converter#convpath</function>.</para>
+
+ <para><methodsynopsis><type>Array</type><methodname>Encoding::Converter.search_convpath</methodname><methodparam><parameter>source</parameter></methodparam><methodparam><parameter>destination</parameter></methodparam><methodparam choice="opt"><parameter>options</parameter></methodparam></methodsynopsis> Returns the steps in the conversion path between a <parameter>source</parameter> and <parameter>destination</parameter> encoding, both of which may be either <literal>Encoding</literal> objects or the names of encodings as <literal>String</literal>s. <parameter>options</parameter> is a <link linkend="enc.options-hash">transcoding options <literal>Hash</literal></link>. A step involving transcoding from one encoding to another is represented as <literal>Array</literal> containing two <literal>Encoding</literal> objects. A step involving a decorator is the decorator’s name as a <literal>String</literal>.</para>
+
+ <para><methodsynopsis><type>String</type><methodname>Encoding::Converter#convert</methodname><methodparam><parameter>source</parameter></methodparam></methodsynopsis> Transcodes the given <literal>String</literal> along the receiver’s conversion path. <parameter>source</parameter> is assumed to be part of a larger <literal>String</literal>, so this method can be called repeatedly with the next chunk of input. Accordingly, after all input has been transcoded, <function>Encoding::Converter#finish</function> should be invoked.</para>
+
+ <para><methodsynopsis><type>Array</type><methodname>Encoding::Converter#convpath</methodname><void/></methodsynopsis> Returns the steps in the conversion path used by the receiver. A step involving transcoding from one encoding to another is represented as <literal>Array</literal> containing two <literal>Encoding</literal> objects. A step involving a decorator is the decorator’s name as a <literal>String</literal>.</para>
+
+ <para><methodsynopsis><type>Encoding</type><methodname>Encoding::Converter#destination_encoding</methodname><void/></methodsynopsis> Returns the <literal>Encoding</literal> to which the receiver transcodes.</para>
+
+ <para><methodsynopsis><type>String</type><methodname>Encoding::Converter#finish</methodname><void/></methodsynopsis> Signals that there is no more input to be transcoded, returning the final piece of the destination <literal>String</literal>.</para>
+
+ <para><methodsynopsis><type>nil</type><methodname>Encoding::Converter#insert_output</methodname><methodparam><parameter>string</parameter></methodparam></methodsynopsis> Converts the given <literal>String</literal> into the destination encoding, then appends it to the output buffer.</para>
+
+ <para><methodsynopsis><type>Exception or nil</type><methodname>Encoding::Converter#last_error</methodname><void/></methodsynopsis> Returns an <literal>Exception</literal> corresponding to the last error the receiver encountered—i.e. <exceptionname>Encoding::InvalidByteSequenceError</exceptionname> or <exceptionname>Encoding::UndefinedConversionError</exceptionname>—or <literal>nil</literal> if no <literal>Exception</literal> occurred.</para>
+
+ <para><methodsynopsis><type>Symbol</type><methodname>Encoding::Converter#primitive_convert</methodname><methodparam><parameter>source</parameter></methodparam><methodparam><parameter>destination</parameter></methodparam><methodparam choice="opt"><parameter>destination_offset=nil</parameter></methodparam><methodparam choice="opt"><parameter>destination_size=nil</parameter></methodparam><methodparam choice="opt"><parameter>options</parameter></methodparam></methodsynopsis> Converts the <parameter>source</parameter> <literal>String</literal> along the receiver’s conversion path, appending the result to the <parameter>destination</parameter> <literal>String</literal>, and returning a <literal>Symbol</literal> indicating the state of the converter. If <parameter>destination_offset</parameter> is non-<literal>nil</literal>, it is an <literal>Integer</literal> specifying the byte position in <parameter>destination</parameter> where the result should be inserted. If <parameter>destination_size</parameter> is non-<literal>nil</literal>, it is an <literal>Integer</literal> specifying the maximum number of bytes to insert into <parameter>destination</parameter>. <parameter>options</parameter> is an options <literal>Hash</literal>. See <xref linkend="enc.primitive-convert"/> for details.</para>
+
+ <para><methodsynopsis><type>Array</type><methodname>Encoding::Converter#primitive_errinfo</methodname><void/></methodsynopsis> Returns details of the last transcoding error the receiver encountered as an <literal>Array</literal>: the first element is the last <literal>Symbol</literal> returned by <function>Encoding::Converter#primitive_convert</function>, the next two are the names of the encodings in the current step in the conversion path as <literal>String</literal>s, the next is the byte sequence which caused this error, and the last is the byte sequence which will be read again when <function>Encoding::Converter#primitive_convert</function> is next called. The last four of these elements are only meaningful when the first is <literal>:invalid_byte_sequence</literal>, <literal>:incomplete_input</literal>, or <literal>:undefined_conversion</literal>.</para>
+
+ <para><methodsynopsis><type>String</type><methodname>Encoding::Converter#putback</methodname><methodparam choice="opt"><parameter>max</parameter></methodparam></methodsynopsis> Puts the <emphasis>read again</emphasis> bytes from the last <exceptionname>Encoding::InvalidByteSequenceError</exceptionname> back into the input buffer so they will be transcoded again. If <parameter>max</parameter> is given, it is an <literal>Integer</literal> specifying the maximum number of bytes to put back.</para>
+
+ <para><methodsynopsis><type>String</type><methodname>Encoding::Converter#replacement</methodname><void/></methodsynopsis> Returns the receiver’s replacement <literal>String</literal>.</para>
+
+ <para><methodsynopsis><type>String</type><methodname>Encoding::Converter#replacement=</methodname><methodparam><parameter>string</parameter></methodparam></methodsynopsis> Sets the receiver’s replacement <literal>String</literal> to <parameter>string</parameter>, which it then returns.</para>
+
+ <para><methodsynopsis><type>Encoding</type><methodname>Encoding::Converter#source_encoding</methodname><void/></methodsynopsis> Returns the <literal>Encoding</literal> from which the receiver transcodes.</para>
+</appendix>
Please sign in to comment.
Something went wrong with that request. Please try again.