diff options
Diffstat (limited to 'ext/iconv/iconv.c')
-rw-r--r-- | ext/iconv/iconv.c | 417 |
1 files changed, 205 insertions, 212 deletions
diff --git a/ext/iconv/iconv.c b/ext/iconv/iconv.c index 84b14309af..951f89e8a3 100644 --- a/ext/iconv/iconv.c +++ b/ext/iconv/iconv.c @@ -10,27 +10,9 @@ All the files in this distribution are covered under the Ruby's license (see the file COPYING). -**********************************************************************/ - -/* -=begin -= Summary -Ruby extension for codeset conversion. - -= Abstract -Iconv is a wrapper class for UNIX 95 (({iconv()})) function family, which -translates string between various coding systems. + Documentation by Yukihiro Matsumoto and Gavin Sinclair. -See ((<Open Group|URL:http://www.opengroup.org/>))'s on-line documents for more details. -* ((<iconv.h|URL:http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.h.html>)) -* ((<iconv_open()|URL:http://www.opengroup.org/onlinepubs/007908799/xsh/iconv_open.html>)) -* ((<iconv()|URL:http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.html>)) -* ((<iconv_close()|URL:http://www.opengroup.org/onlinepubs/007908799/xsh/iconv_close.html>)) - -Which coding systems are available, it depends on the platform. - -=end -*/ +**********************************************************************/ #include "ruby.h" #include <errno.h> @@ -39,6 +21,54 @@ Which coding systems are available, it depends on the platform. #include "st.h" #include "intern.h" +/* + * Document-class: Iconv + * + * == Summary + * + * Ruby extension for charset conversion. + * + * == Abstract + * + * Iconv is a wrapper class for the UNIX 95 <tt>iconv()</tt> function family, + * which translates string between various encoding systems. + * + * See Open Group's on-line documents for more details. + * * <tt>iconv.h</tt>: http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.h.html + * * <tt>iconv_open()</tt>: http://www.opengroup.org/onlinepubs/007908799/xsh/iconv_open.html + * * <tt>iconv()</tt>: http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.html + * * <tt>iconv_close()</tt>: http://www.opengroup.org/onlinepubs/007908799/xsh/iconv_close.html + * + * Which coding systems are available is platform-dependent. + * + * == Examples + * + * 1. Instantiate a new Iconv and use method Iconv#iconv. + * + * cd = Iconv.new(to, from) + * begin + * input.each { |s| output << cd.iconv(s) } + * output << cd.iconv(nil) # Don't forget this! + * ensure + * cd.close + * end + * + * 2. Invoke Iconv.open with a block. + * + * Iconv.open(to, from) do |cd| + * input.each { |s| output << cd.iconv(s) } + * output << cd.iconv(nil) + * end + * + * 3. Shorthand for (2). + * + * Iconv.iconv(to, from, *input.to_a) + * + * 4. Simple conversion between two charsets. + * + * converted_text = Iconv.new('iso-8859-15', 'utf-8').iconv(text) + */ + /* Invalid value for iconv_t is -1 but 0 for VALUE, I hope VALUE is big enough to keep iconv_t */ #define VALUE2ICONV(v) ((iconv_t)((VALUE)(v) ^ -1)) @@ -80,18 +110,6 @@ static VALUE iconv_init_state _((VALUE cd)); static VALUE iconv_finish _((VALUE self)); static VALUE iconv_iconv _((int argc, VALUE *argv, VALUE self)); - -/* -=begin -= Classes & Modules -=end -*/ - -/* -=begin -== Iconv -=end -*/ static VALUE charset_map; static VALUE charset_map_get _((void)) @@ -465,36 +483,6 @@ iconv_convert return ret; } - -/* -=begin -=== Class methods -=end -*/ -/* -=begin ---- Iconv.new(to, from) {|cd| ...} - Creates new code converter from a coding-system designated with ((|from|)) - to another one designated with ((|to|)). - :Parameters - :((|to|)) - coding-system name for destination. - :((|from|)) - coding-system name for source. - :Exceptions - :(({TypeError})) - if ((|to|)) or ((|from|)) aren't String - :(({ArgumentError})) - if designated converter couldn't find out. - :(({SystemCallError})) - when (({iconv_open(3)})) failed. - ---- Iconv.open(to, from) - Equivalents to ((<Iconv.new>)) except with in the case of called - with a block, yields with the new instance and closes it, and - returns the result which returned from the block. -=end -*/ static VALUE iconv_s_allocate #ifdef HAVE_PROTOTYPES @@ -507,6 +495,24 @@ iconv_s_allocate return Data_Wrap_Struct(klass, 0, ICONV_FREE, 0); } +/* + * Document-method: new + * call-seq: Iconv.new(to, from) + * + * Creates new code converter from a coding-system designated with +from+ + * to another one designated with +to+. + * + * === Parameters + * + * +to+:: encoding name for destination + * +from+:: encoding name for source + * + * === Exceptions + * + * TypeError:: if +to+ or +from+ aren't String + * ArgumentError:: if designated converter couldn't find out + * SystemCallError:: if <tt>iconv_open3</tt> fails + */ static VALUE iconv_initialize #ifdef HAVE_PROTOTYPES @@ -524,6 +530,14 @@ iconv_initialize return self; } +/* + * Document-method: open + * call-seq: Iconv.open(to, from) { |iconv| ... } + * + * Equivalent to Iconv.new except that when it is called with a block, it + * yields with the new instance and closes it, and returns the result which + * returned from the block. + */ static VALUE iconv_s_open #ifdef HAVE_PROTOTYPES @@ -546,22 +560,6 @@ iconv_s_open } } -/* -=begin ---- Iconv.iconv(to, from, *strs) - Shorthand for - Iconv.open(to, from) {|cd| (strs + [nil]).collect {|s| cd.iconv(s)}} - :Parameters - :((|to|)), ((|from|)) - see ((<Iconv.new>)). - :((|strs|)) - strings to be converted. - :Exceptions - exceptions thrown by ((<Iconv.new>)), ((<Iconv.open>)) and - ((<Iconv#iconv>)). -=end -*/ - static VALUE iconv_s_convert #ifdef HAVE_PROTOTYPES @@ -587,6 +585,24 @@ iconv_s_convert return env->ret; } +/* + * Document-method: iconv + * call-seq: Iconv.iconv(to, from, *strs) + * + * Shorthand for + * Iconv.open(to, from) { |cd| + * (strs + [nil]).collect { |s| cd.iconv(s) } + * } + * + * === Parameters + * + * <tt>to, from</tt>:: see Iconv.new + * <tt>strs</tt>:: strings to be converted + * + * === Exceptions + * + * Exceptions thrown by Iconv.new, Iconv.open and Iconv#iconv. +*/ static VALUE iconv_s_iconv #ifdef HAVE_PROTOTYPES @@ -612,14 +628,13 @@ iconv_s_iconv } /* -=begin ---- Iconv.conv(to, from, str) - Shorthand for - Iconv.iconv(to, from, str).join - see ((<Iconv.iconv>)) -=end -*/ - + * Document-method: Iconv::conv + * call-seq: Iconv.iconv(to, from, *strs) + * + * Shorthand for + * Iconv.iconv(to, from, str).join + * See Iconv.iconv ??? + */ static VALUE iconv_s_conv #ifdef HAVE_PROTOTYPES @@ -640,10 +655,10 @@ iconv_s_conv } /* -=begin ---- Iconv.list {|*aliases| ... } - Iterates each alias sets. -=end + * Document-method: list + * call-seq: Iconv.list {|*aliases| ... } + * + * Iterates each alias sets. */ #ifdef HAVE_ICONVLIST @@ -716,22 +731,16 @@ iconv_s_list _((void)) return Qnil; } - /* -=begin -=== Instance methods -=end -*/ -/* -=begin ---- Iconv#close - Finishes conversion. - * After calling this, invoking method ((<Iconv#iconv>)) will cause - exception, but multiple calls of (({close})) are guaranteed to - end successfully. - * Returns a string contains the byte sequence to change the - output buffer to its initial shift state. -=end + * Document-method: close + * + * Finishes conversion. + * + * After calling this, calling Iconv#iconv will cause an exception, but + * multiple calls of #close are guaranteed to end successfully. + * + * Returns a string containing the byte sequence to change the output buffer to + * its initial shift state. <i>???</i> */ static VALUE iconv_init_state @@ -763,29 +772,31 @@ iconv_finish } /* -=begin ---- Iconv#iconv(str, [ start = 0, [ length = -1 ] ]) - Converts string and returns converted one. - * In the case of ((|str|)) is (({String})), converts (({str[start, length]})). - Returns converted string. - * In the case of ((|str|)) is (({nil})), places ((|converter|)) - itself into initial shift state and just returns a string contains - the byte sequence to change the output buffer to its initial shift - state. - * Otherwise, causes exception. - :Parameters - :((|str|)) - string to be converted or (({nil})). - :((|start|)) - starting offset. - :((|length|)) - conversion length, - (({nil})) or (({-1})) means whole string from (({start})). - :Exceptions - * ((<Iconv::IllegalSequence>)) - * ((<Iconv::InvalidCharacter>)) - * ((<Iconv::OutOfRange>)) -=end + * Document-method: iconv + * call-seq: iconv(str, start=0, length=-1) + * + * Converts string and returns the result. + * * If +str+ is a String, converts <tt>str[start, length]</tt> and returns the converted string. + * * If +str+ is +nil+, places converter itself into initial shift state and + * just returns a string containing the byte sequence to change the output + * buffer to its initial shift state. + * * Otherwise, raises an exception. + * + * === Parameters + * + * str:: string to be converted, or nil + * start:: starting offset + * length:: conversion length; nil or -1 means whole the string from start + * + * === Exceptions + * + * * IconvIllegalSequence + * * IconvInvalidCharacter + * * IconvOutOfRange + * + * === Examples + * + * See the Iconv documentation. */ static VALUE iconv_iconv @@ -806,33 +817,31 @@ iconv_iconv return iconv_convert(VALUE2ICONV(cd), str, NIL_P(n1) ? 0 : NUM2INT(n1), - NIL_P(n2) ? -1 : NUM2INT(n2), + NIL_P(n2) ? -1 : NUM2INT(n2), NULL); } - -/* -=begin -= Exceptions -=end -*/ -/* -=begin -== Iconv::Failure -Base exceptional attributes from ((<Iconv>)). - -=== Instance methods -=end -*/ /* -=begin ---- Iconv::Failure#success - Returns string(s) translated successfully until the exception occurred. - * In the case of failure occurred within ((<Iconv.iconv>)), returned - value is an array of strings translated successfully preceding - failure and the last element is string on the way. -=end -*/ + * Document-class: Iconv::Failure + * + * Base attributes for Iconv exceptions. + * + * === Iconv::Failure#success + * + * Returns string(s) translated successfully until the exception occurred. + * * In the case of failure occurred within Iconv.iconv, returned + * value is an array of strings translated successfully preceding + * failure and the last element is string on the way. + * + * === Iconv::Failure#failed + * + * Returns substring of the original string passed to Iconv that starts at the + * character caused the exception. + * + * === Iconv::Failure#inspect + * + * Returns inspected string like as: #<_class_: _success_, _failed_> + */ static VALUE iconv_failure_success #ifdef HAVE_PROTOTYPES @@ -846,12 +855,8 @@ iconv_failure_success } /* -=begin ---- Iconv::Failure#failed - Returns substring of the original string passed to ((<Iconv>)) that - starts at the character caused the exception. -=end -*/ + * Comment! + */ static VALUE iconv_failure_failed #ifdef HAVE_PROTOTYPES @@ -864,12 +869,6 @@ iconv_failure_failed return rb_attr_get(self, rb_failed); } -/* -=begin ---- Iconv::Failure#inspect - Returns inspected string like as: #<(({type})): "(({success}))", "(({failed}))"> -=end -*/ static VALUE iconv_failure_inspect #ifdef HAVE_PROTOTYPES @@ -891,34 +890,49 @@ iconv_failure_inspect } /* - Hmmm, I don't like to write RD inside of function :-<. - -=begin -== Iconv::IllegalSequence -Input conversion stopped due to an input byte that does not belong to -the input codeset, or the output codeset does not contain the -character. -=== Superclass -(({ArgumentError})) -=== Included Modules -((<Iconv::Failure>)) - -== Iconv::InvalidCharacter -Input conversion stopped due to an incomplete character or shift -sequence at the end of the input buffer. -=== Superclass -(({ArgumentError})) -=== Included Modules -((<Iconv::Failure>)) - -== Iconv::OutOfRange -Iconv library internal error. Must not occur. -=== Superclass -(({RuntimeError})) -=== Included Modules -((<Iconv::Failure>)) -=end -*/ + * Document-class: Iconv::IllegalSequence + * + * Input conversion stopped due to an input byte that does not belong to + * the input codeset, or the output codeset does not contain the + * character. + * + * === Superclass + * + * ArgumentError + * + * === Included Modules + * + * Iconv::Failure + */ + +/* + * Document-class: Iconv::InvalidCharacter + * + * Input conversion stopped due to an incomplete character or shift + * sequence at the end of the input buffer. + * + * === Superclass + * + * ArgumentError + * + * === Included Modules + * + * Iconv::Failure + */ + +/* + * Document-class: Iconv::OutOfRange + * + * Iconv library internal error. Must not occur. + * + * === Superclass + * + * RuntimeError + * + * === Included Modules + * + * Iconv::Failure + */ void Init_iconv _((void)) @@ -956,24 +970,3 @@ Init_iconv _((void)) rb_define_singleton_method(rb_cIconv, "charset_map", charset_map_get, 0); } - -/* -=begin -== Example -(1) Instantiate a new ((<Iconv>)), use method ((<Iconv#iconv>)). - cd = Iconv.new(to, from) - begin - input.each {|s| output << cd.iconv(s)} - output << cd.iconv(nil) # don't forget this - ensure - cd.close - end -(2) Invoke ((<Iconv.open>)) with a block. - Iconv.open(to, from) do |cd| - input.each {|s| output << cd.iconv(s)} - output << cd.iconv(nil) - end -(3) Shorthand for (2). - Iconv.iconv(to, from, *input.to_a) -=end -*/ |