| Class | Iconv |
| In: |
iconv/iconv.c
|
| Parent: | Data |
Ruby extension for charset conversion.
Iconv is a wrapper class for the UNIX 95 iconv() function family, which translates string between various encoding systems.
See Open Group’s on-line documents for more details.
Which coding systems are available is platform-dependent.
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
Iconv.open(to, from) do |cd|
input.each { |s| output << cd.iconv(s) }
output << cd.iconv(nil)
end
Iconv.iconv(to, from, *input.to_a)
converted_text = Iconv.new('iso-8859-15', 'utf-8').iconv(text)
Document-method: Iconv::conv
Shorthand for
Iconv.iconv(to, from, str).join
See Iconv.iconv.
/*
* 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
(self, to, from, str)
VALUE self, to, from, str;
{
struct iconv_env_t arg;
arg.argc = 1;
arg.argv = &str;
arg.append = rb_str_append;
arg.ret = rb_str_new(0, 0);
arg.cd = iconv_create(to, from);
return rb_ensure(iconv_s_convert, (VALUE)&arg, iconv_free, ICONV2VALUE(arg.cd));
}
Shorthand for
Iconv.open(to, from) { |cd|
(strs + [nil]).collect { |s| cd.iconv(s) }
}
| to, from: | see Iconv.new |
| strs: | strings to be converted |
Exceptions thrown by Iconv.new, Iconv.open and Iconv#iconv.
/*
* 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
(argc, argv, self)
int argc;
VALUE *argv;
VALUE self;
{
struct iconv_env_t arg;
if (argc < 2) /* needs `to' and `from' arguments at least */
rb_raise(rb_eArgError, "wrong number of arguments (%d for %d)", argc, 2);
arg.argc = argc -= 2;
arg.argv = argv + 2;
arg.append = rb_ary_push;
arg.ret = rb_ary_new2(argc);
arg.cd = iconv_create(argv[0], argv[1]);
return rb_ensure(iconv_s_convert, (VALUE)&arg, iconv_free, ICONV2VALUE(arg.cd));
}
Creates new code converter from a coding-system designated with from to another one designated with to.
| to: | encoding name for destination |
| from: | encoding name for source |
| TypeError: | if to or from aren’t String |
| InvalidEncoding: | if designated converter couldn’t find out |
| SystemCallError: | if iconv_open(3) fails |
/*
* 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
* InvalidEncoding:: if designated converter couldn't find out
* SystemCallError:: if <tt>iconv_open(3)</tt> fails
*/
static VALUE
iconv_initialize
(self, to, from)
VALUE self;
VALUE to;
VALUE from;
{
iconv_free(check_iconv(self));
DATA_PTR(self) = NULL;
DATA_PTR(self) = (void *)ICONV2VALUE(iconv_create(to, from));
return self;
}
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.
/*
* 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
(self, to, from)
VALUE self;
VALUE to;
VALUE from;
{
VALUE cd = ICONV2VALUE(iconv_create(to, from));
self = Data_Wrap_Struct(self, NULL, ICONV_FREE, (void *)cd);
if (rb_block_given_p()) {
return rb_ensure(rb_yield, self, (VALUE(*)())iconv_finish, self);
}
else {
return self;
}
}
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.
Shorthand for
Iconv.open(to, from) { |cd|
(strs + [nil]).collect { |s| cd.iconv(s) }
}
| to, from: | see Iconv.new |
| strs: | strings to be converted |
Exceptions thrown by Iconv.new, Iconv.open and Iconv#iconv.
/*
* 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
(argc, argv, self)
int argc;
VALUE *argv;
VALUE self;
{
VALUE str, n1, n2;
VALUE cd = check_iconv(self);
n1 = n2 = Qnil;
rb_scan_args(argc, argv, "12", &str, &n1, &n2);
return iconv_convert(VALUE2ICONV(cd), str,
NIL_P(n1) ? 0 : NUM2INT(n1),
NIL_P(n2) ? -1 : NUM2INT(n2),
NULL);
}