ruby-changes:7483
From: akr <ko1@a...>
Date: Mon, 1 Sep 2008 00:34:13 +0900 (JST)
Subject: [ruby-changes:7483] Ruby:r19002 (trunk): rdoc update.
akr 2008-09-01 00:31:14 +0900 (Mon, 01 Sep 2008) New Revision: 19002 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=19002 Log: rdoc update. Modified files: trunk/transcode.c Index: transcode.c =================================================================== --- transcode.c (revision 19001) +++ transcode.c (revision 19002) @@ -2158,7 +2158,9 @@ * * Encoding::Converter.new creates an instance of Encoding::Converter. * - * source_encoding and destination_encoding should be a string. + * source_encoding and destination_encoding should be a string or + * Encoding object. + * * flags should be an integer. * * example: @@ -2294,7 +2296,7 @@ * call-seq: * ec.source_encoding -> encoding * - * returns source encoding as Encoding object. + * returns the source encoding as an Encoding object. */ static VALUE econv_source_encoding(VALUE self) @@ -2309,7 +2311,7 @@ * call-seq: * ec.destination_encoding -> encoding * - * returns destination encoding as Encoding object. + * returns the destination encoding as an Encoding object. */ static VALUE econv_destination_encoding(VALUE self) @@ -2366,11 +2368,15 @@ * nil means the end of destination_buffer. * If it is omitted, nil is assumed. * - * destination_bytesize and flags should be an integer or nil. - * nil means that unlimited. + * destination_bytesize should be an integer or nil. + * nil means unlimited. * If it is omitted, nil is assumed. * - * primitive_convert convert the content of source_buffer from beginning + * flags should be an integer or nil. + * nil means no flags. + * If it is omitted, nil is assumed. + * + * primitive_convert converts the content of source_buffer from beginning * and store the result into destination_buffer. * * destination_byteoffset and destination_bytesize specify the region which @@ -2382,10 +2388,10 @@ * If destination_bytesize is nil, * destination size is unlimited. * After conversion, destination_buffer is resized to - * destination_byteoffset + actually converted number of bytes. + * destination_byteoffset + actually produced number of bytes. * Also destination_buffer's encoding is set to destination_encoding. * - * primitive_convert drops the first part of source_buffer. + * primitive_convert drops the converted part of source_buffer. * the dropped part is converted in destination_buffer or * buffered in Encoding::Converter object. * @@ -2630,7 +2636,7 @@ * call-seq: * ec.primitive_errinfo -> array * - * primitive_errinfo returns a precious information of last error result + * primitive_errinfo returns a precious information of the last error result * as a 5-elements array: * * [result, enc1, enc2, error_bytes, readagain_bytes] @@ -2641,8 +2647,8 @@ * :invalid_byte_sequence, :incomplete_input or :undefined_conversion. * * enc1 and enc2 indicates a conversion step as pair of strings. - * For example, EUC-JP to ISO-8859-1 is - * converted as EUC-JP -> UTF-8 -> ISO-8859-1. + * For example, a converter from EUC-JP to ISO-8859-1 converters + * a string as EUC-JP -> UTF-8 -> ISO-8859-1. * So [enc1, enc2] is ["EUC-JP", "UTF-8"] or ["UTF-8", "ISO-8859-1"]. * * error_bytes and readagain_bytes indicates the byte sequences which causes the error. @@ -2732,8 +2738,12 @@ * ec.insert_output(string) -> nil * * inserts string into the encoding converter. - * The string will be output on next conversion. + * The string will be converted into the destination encoding and + * outputed on later conversions. * + * If the destination encoding is stateful, + * string is converted according to the state and update the state. + * * This method should be used only when a conversion error is occur. * * ec = Encoding::Converter.new("utf-8", "iso-8859-1") @@ -2745,6 +2755,15 @@ * p ec.primitive_convert(src, dst) #=> :finished * puts "[#{dst.dump}, #{src.dump}]" #=> ["HIRAGANA LETTER A is <err>.", ""] * + * ec = Encoding::Converter.new("utf-8", "iso-2022-jp") + * src = "\u{306F 3041 3068 2661 3002}" # U+2661 is not representable in iso-2022-jp + * dst = "" + * p ec.primitive_convert(src, dst) #=> :undefined_conversion + * puts "[#{dst.dump}, #{src.dump}]" #=> ["\e$B$O$!$H".force_encoding("ISO-2022-JP"), "\xE3\x80\x82"] + * ec.insert_output "?" # state change required to output "?". + * p ec.primitive_convert(src, dst) #=> :finished + * puts "[#{dst.dump}, #{src.dump}]" #=> ["\e$B$O$!$H\e(B?\e$B!#\e(B".force_encoding("ISO-2022-JP"), ""] + * */ static VALUE econv_insert_output(VALUE self, VALUE string) @@ -2776,7 +2795,7 @@ * * The bytes are caused by invalid_byte_sequence error. * When invalid_byte_sequence error, some bytes are discarded and - * some bytes may be converted again. + * some bytes are buffered to be converted later. * The latter bytes can be put back. * It can be observed by * Encoding::InvalidByteSequence#readagain_bytes and @@ -2825,7 +2844,7 @@ * ec.last_error -> exception or nil * * returns an exception object for the last conversion. - * it returns nil if the last conversion is not an error. + * It returns nil if the last conversion is not an error. * * "error" means that * Encoding::InvalidByteSequence and Encoding::ConversionUndefined for -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/