Ruby: include/ruby/internal/encoding/transcode.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Typedefs | Enumerations | Functions
transcode.h File Reference

econv stuff More...

`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/value.h"`

Go to the source code of this file.

## Typedefs
typedef struct rb_econv_t | rb_econv_t
| An opaque struct that represents a lowest level of encoding conversion.

## Enumerations
enum | rb_econv_result_t { econv_invalid_byte_sequence , econv_undefined_conversion , econv_destination_buffer_full , econv_source_buffer_empty , econv_finished , econv_after_output , econv_incomplete_input }
| return value of rb_econv_convert() More...
enum | ruby_econv_flag_type { RUBY_ECONV_ERROR_HANDLER_MASK = 0x000000ff , RUBY_ECONV_INVALID_MASK = 0x0000000f , RUBY_ECONV_INVALID_REPLACE = 0x00000002 , RUBY_ECONV_UNDEF_MASK = 0x000000f0 , RUBY_ECONV_UNDEF_REPLACE = 0x00000020 , RUBY_ECONV_UNDEF_HEX_CHARREF = 0x00000030 , RUBY_ECONV_DECORATOR_MASK = 0x0001ff00 , RUBY_ECONV_NEWLINE_DECORATOR_MASK = 0x00007f00 , RUBY_ECONV_NEWLINE_DECORATOR_READ_MASK = 0x00000f00 , RUBY_ECONV_NEWLINE_DECORATOR_WRITE_MASK = 0x00007000 , RUBY_ECONV_UNIVERSAL_NEWLINE_DECORATOR = 0x00000100 , RUBY_ECONV_CRLF_NEWLINE_DECORATOR = 0x00001000 , RUBY_ECONV_CR_NEWLINE_DECORATOR = 0x00002000 , RUBY_ECONV_LF_NEWLINE_DECORATOR = 0x00004000 , RUBY_ECONV_XML_TEXT_DECORATOR = 0x00008000 , RUBY_ECONV_XML_ATTR_CONTENT_DECORATOR = 0x00010000 , RUBY_ECONV_STATEFUL_DECORATOR_MASK = 0x00f00000 , RUBY_ECONV_XML_ATTR_QUOTE_DECORATOR = 0x00100000 , RUBY_ECONV_DEFAULT_NEWLINE_DECORATOR , RUBY_ECONV_PARTIAL_INPUT = 0x00020000 , RUBY_ECONV_AFTER_OUTPUT = 0x00040000 , RUBY_ECONV_FLAGS_PLACEHOLDER }
| This enum is kind of omnibus. More...

## Functions
VALUE | rb_str_encode (VALUE str, VALUE to, int ecflags, VALUE ecopts)
| Converts the contents of the passed string from its encoding to the passed one.
int | rb_econv_has_convpath_p (const char *from_encoding, const char *to_encoding)
| Queries if there is more than one way to convert between the passed two encodings.
int | rb_econv_prepare_options (VALUE opthash, VALUE *ecopts, int ecflags)
| Identical to rb_econv_prepare_opts(), except it additionally takes the initial value of flags.
int | rb_econv_prepare_opts (VALUE opthash, VALUE *ecopts)
| Splits a keyword arguments hash (that for instance `String#encode` took) into a set of enum ruby_econv_flag_type and a hash storing replacement characters etc.
rb_econv_t * | rb_econv_open (const char *source_encoding, const char *destination_encoding, int ecflags)
| Creates a new instance of struct rb_econv_t.
rb_econv_t * | rb_econv_open_opts (const char *source_encoding, const char *destination_encoding, int ecflags, VALUE ecopts)
| Identical to rb_econv_open(), except it additionally takes a hash of optional strings.
rb_econv_result_t | rb_econv_convert (rb_econv_t *ec, const unsigned char **source_buffer_ptr, const unsigned char *source_buffer_end, unsigned char **destination_buffer_ptr, unsigned char *destination_buffer_end, int flags)
| Converts a string from an encoding to another.
void | rb_econv_close (rb_econv_t *ec)
| Destructs a converter.
int | rb_econv_set_replacement (rb_econv_t *ec, const unsigned char *str, size_t len, const char *encname)
| Assigns the replacement string.
int | rb_econv_decorate_at_first (rb_econv_t *ec, const char *decorator_name)
| "Decorate"s a converter.
int | rb_econv_decorate_at_last (rb_econv_t *ec, const char *decorator_name)
| Identical to rb_econv_decorate_at_first(), except it adds to the opposite direction.
VALUE | rb_econv_open_exc (const char *senc, const char *denc, int ecflags)
| Creates a `rb_eConverterNotFoundError` exception object (but does not raise).
int | rb_econv_insert_output (rb_econv_t *ec, const unsigned char *str, size_t len, const char *str_encoding)
| Appends the passed string to the passed converter's output buffer.
const char * | rb_econv_encoding_to_insert_output (rb_econv_t *ec)
| Queries an encoding name which best suits for rb_econv_insert_output()'s last parameter.
void | rb_econv_check_error (rb_econv_t *ec)
| This is a rb_econv_make_exception() + rb_exc_raise() combo.
VALUE | rb_econv_make_exception (rb_econv_t *ec)
| This function makes sense right after rb_econv_convert() returns.
int | rb_econv_putbackable (rb_econv_t *ec)
| Queries if rb_econv_putback() makes sense, i.e.
void | rb_econv_putback (rb_econv_t *ec, unsigned char *p, int n)
| Puts back the bytes.
const char * | rb_econv_asciicompat_encoding (const char *encname)
| Queries the passed encoding's corresponding ASCII compatible encoding.
VALUE | rb_econv_str_convert (rb_econv_t *ec, VALUE src, int flags)
| Identical to rb_econv_convert(), except it takes Ruby's string instead of C's pointer.
VALUE | rb_econv_substr_convert (rb_econv_t *ec, VALUE src, long byteoff, long bytesize, int flags)
| Identical to rb_econv_str_convert(), except it converts only a part of the passed string.
VALUE | rb_econv_str_append (rb_econv_t *ec, VALUE src, VALUE dst, int flags)
| Identical to rb_econv_str_convert(), except it appends the conversion result to the additionally passed string instead of creating a new string.
VALUE | rb_econv_substr_append (rb_econv_t *ec, VALUE src, long byteoff, long bytesize, VALUE dst, int flags)
| Identical to rb_econv_str_append(), except it appends only a part of the passed string with conversion.
VALUE | rb_econv_append (rb_econv_t *ec, const char *bytesrc, long bytesize, VALUE dst, int flags)
| Converts the passed C's pointer according to the passed converter, then append the conversion result to the passed Ruby's string.
void | rb_econv_binmode (rb_econv_t *ec)
| This badly named function does not set the destination encoding to binary, but instead just nullifies newline conversion decorators if any.

## Flags for rb_econv_open()
#define | ECONV_ERROR_HANDLER_MASK RUBY_ECONV_ERROR_HANDLER_MASK
| Old name of RUBY_ECONV_ERROR_HANDLER_MASK.
#define | ECONV_INVALID_MASK RUBY_ECONV_INVALID_MASK
| Old name of RUBY_ECONV_INVALID_MASK.
#define | ECONV_INVALID_REPLACE RUBY_ECONV_INVALID_REPLACE
| Old name of RUBY_ECONV_INVALID_REPLACE.
#define | ECONV_UNDEF_MASK RUBY_ECONV_UNDEF_MASK
| Old name of RUBY_ECONV_UNDEF_MASK.
#define | ECONV_UNDEF_REPLACE RUBY_ECONV_UNDEF_REPLACE
| Old name of RUBY_ECONV_UNDEF_REPLACE.
#define | ECONV_UNDEF_HEX_CHARREF RUBY_ECONV_UNDEF_HEX_CHARREF
| Old name of RUBY_ECONV_UNDEF_HEX_CHARREF.
#define | ECONV_DECORATOR_MASK RUBY_ECONV_DECORATOR_MASK
| Old name of RUBY_ECONV_DECORATOR_MASK.
#define | ECONV_NEWLINE_DECORATOR_MASK RUBY_ECONV_NEWLINE_DECORATOR_MASK
| Old name of RUBY_ECONV_NEWLINE_DECORATOR_MASK.
#define | ECONV_NEWLINE_DECORATOR_READ_MASK RUBY_ECONV_NEWLINE_DECORATOR_READ_MASK
| Old name of RUBY_ECONV_NEWLINE_DECORATOR_READ_MASK.
#define | ECONV_NEWLINE_DECORATOR_WRITE_MASK RUBY_ECONV_NEWLINE_DECORATOR_WRITE_MASK
| Old name of RUBY_ECONV_NEWLINE_DECORATOR_WRITE_MASK.
#define | ECONV_UNIVERSAL_NEWLINE_DECORATOR RUBY_ECONV_UNIVERSAL_NEWLINE_DECORATOR
| Old name of RUBY_ECONV_UNIVERSAL_NEWLINE_DECORATOR.
#define | ECONV_CRLF_NEWLINE_DECORATOR RUBY_ECONV_CRLF_NEWLINE_DECORATOR
| Old name of RUBY_ECONV_CRLF_NEWLINE_DECORATOR.
#define | ECONV_CR_NEWLINE_DECORATOR RUBY_ECONV_CR_NEWLINE_DECORATOR
| Old name of RUBY_ECONV_CR_NEWLINE_DECORATOR.
#define | ECONV_LF_NEWLINE_DECORATOR RUBY_ECONV_LF_NEWLINE_DECORATOR
| Old name of RUBY_ECONV_LF_NEWLINE_DECORATOR.
#define | ECONV_XML_TEXT_DECORATOR RUBY_ECONV_XML_TEXT_DECORATOR
| Old name of RUBY_ECONV_XML_TEXT_DECORATOR.
#define | ECONV_XML_ATTR_CONTENT_DECORATOR RUBY_ECONV_XML_ATTR_CONTENT_DECORATOR
| Old name of RUBY_ECONV_XML_ATTR_CONTENT_DECORATOR.
#define | ECONV_STATEFUL_DECORATOR_MASK RUBY_ECONV_STATEFUL_DECORATOR_MASK
| Old name of RUBY_ECONV_STATEFUL_DECORATOR_MASK.
#define | ECONV_XML_ATTR_QUOTE_DECORATOR RUBY_ECONV_XML_ATTR_QUOTE_DECORATOR
| Old name of RUBY_ECONV_XML_ATTR_QUOTE_DECORATOR.
#define | ECONV_DEFAULT_NEWLINE_DECORATOR RUBY_ECONV_DEFAULT_NEWLINE_DECORATOR
| Old name of RUBY_ECONV_DEFAULT_NEWLINE_DECORATOR.

## Flags for rb_econv_convert()
#define | ECONV_PARTIAL_INPUT RUBY_ECONV_PARTIAL_INPUT
| Old name of RUBY_ECONV_PARTIAL_INPUT.
#define | ECONV_AFTER_OUTPUT RUBY_ECONV_AFTER_OUTPUT
| Old name of RUBY_ECONV_AFTER_OUTPUT.

## Detailed Description

econv stuff

Author
  Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Warning
  Symbols prefixed with either `RBIMPL` or `rbimpl` are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note
  To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance `__VA_ARGS__` is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file transcode.h.

## Typedef Documentation

## ◆ rb_econv_t

typedef struct rb_econv_t rb_econv_t

An opaque struct that represents a lowest level of encoding conversion.

Definition at line 73 of file transcode.h.

## Enumeration Type Documentation

## ◆ rb_econv_result_t

enum rb_econv_result_t

return value of rb_econv_convert()

Enumerator
econv_invalid_byte_sequence | The conversion stopped when it found an invalid sequence.
econv_undefined_conversion | The conversion stopped when it found a character in the input which cannot be representable in the output.
econv_destination_buffer_full | The conversion stopped because there is no destination.
econv_source_buffer_empty | The conversion stopped because there is no input.
econv_finished | The conversion stopped after converting everything. This is arguably the expected normal end of conversion.
econv_after_output | The conversion stopped after writing something to somewhere, before reading everything.
econv_incomplete_input | The conversion stopped in middle of reading a character, possibly due to a partial read of a socket etc.

Definition at line 30 of file transcode.h.

## ◆ ruby_econv_flag_type

enum ruby_econv_flag_type

This enum is kind of omnibus.

Gathers various constants.

Enumerator
RUBY_ECONV_ERROR_HANDLER_MASK | Mask for error handling related bits.
RUBY_ECONV_INVALID_MASK | Special handling of invalid sequences are there.
RUBY_ECONV_INVALID_REPLACE | Invalid sequences shall be replaced.
RUBY_ECONV_UNDEF_MASK | Special handling of undefined conversion are there.
RUBY_ECONV_UNDEF_REPLACE | Undefined characters shall be replaced.
RUBY_ECONV_UNDEF_HEX_CHARREF | Undefined characters shall be escaped.
RUBY_ECONV_DECORATOR_MASK | Decorators are there.
RUBY_ECONV_NEWLINE_DECORATOR_MASK | Newline converters are there.
RUBY_ECONV_NEWLINE_DECORATOR_READ_MASK | (Unclear; seems unused).
RUBY_ECONV_NEWLINE_DECORATOR_WRITE_MASK | (Unclear; seems unused).
RUBY_ECONV_UNIVERSAL_NEWLINE_DECORATOR | Universal newline mode.
RUBY_ECONV_CRLF_NEWLINE_DECORATOR | CR to CRLF conversion shall happen.
RUBY_ECONV_CR_NEWLINE_DECORATOR | CRLF to CR conversion shall happen.
RUBY_ECONV_LF_NEWLINE_DECORATOR | CRLF to LF conversion shall happen.
RUBY_ECONV_XML_TEXT_DECORATOR | Texts shall be XML-escaped.
RUBY_ECONV_XML_ATTR_CONTENT_DECORATOR | Texts shall be AttrValue escaped.
RUBY_ECONV_STATEFUL_DECORATOR_MASK | (Unclear; seems unused).
RUBY_ECONV_XML_ATTR_QUOTE_DECORATOR | Texts shall be AttrValue escaped.
RUBY_ECONV_DEFAULT_NEWLINE_DECORATOR | Newline decorator's default.
RUBY_ECONV_PARTIAL_INPUT | Indicates the input is a part of much larger one.
RUBY_ECONV_AFTER_OUTPUT | Instructs the converter to stop after output.
RUBY_ECONV_FLAGS_PLACEHOLDER | Placeholder (not used)

Definition at line 452 of file transcode.h.

## Function Documentation

## ◆ rb_econv_append()

VALUE rb_econv_append | ( | rb_econv_t * | ec,
|  | const char * | bytesrc,
|  | long | bytesize,
|  | VALUE | dst,
|  | int | flags )

Converts the passed C's pointer according to the passed converter, then append the conversion result to the passed Ruby's string.

This way buffer overflow is properly avoided to resize the destination properly.

Parameters

  [in,out] | ec | Target converter.
  [in] | bytesrc | Target string.
  [in] | bytesize | Number of bytes of `bytesrc`.
  [in] | dst | Return buffer.
  [in] | flags | Flags (see rb_econv_convert).

Exceptions

  rb_eArgError | Converted string is too long.
  rb_eInvalidByteSequenceError | Invalid byte sequence.
  rb_eUndefinedConversionError | Conversion undefined.

Returns
  The conversion result.

Definition at line 1826 of file transcode.c.

Referenced by rb_econv_append(), and rb_econv_substr_append().

## ◆ rb_econv_asciicompat_encoding()

const char * rb_econv_asciicompat_encoding | ( | const char * | encname | ) |

Queries the passed encoding's corresponding ASCII compatible encoding.

"The corresponding ASCII compatible encoding" in this context is an ASCII compatible encoding which can represent exactly the same character sets as the given ASCII incompatible encoding. For instance that of UTF-16LE is UTF-8.

Parameters

  [in] | encname | Name of an ASCII incompatible encoding.

Return values

  NULL | `encname` is already ASCII compatible.
  otherwise | The corresponding ASCII compatible encoding.

Definition at line 1793 of file transcode.c.

Referenced by rb_econv_asciicompat_encoding().

## ◆ rb_econv_binmode()

void rb_econv_binmode | ( | rb_econv_t * | ec | ) |

This badly named function does not set the destination encoding to binary, but instead just nullifies newline conversion decorators if any.

Other ordinal character conversions still happen after this; something non-binary would still be generated.

Parameters

  [out] | ec | Target converter to modify.

Postcondition
  Any newline conversions, if any, would be killed.

Definition at line 1975 of file transcode.c.

Referenced by rb_econv_binmode(), and rb_io_binmode().

## ◆ rb_econv_check_error()

void rb_econv_check_error | ( | rb_econv_t * | ec | ) |

This is a rb_econv_make_exception() + rb_exc_raise() combo.

Parameters

  [in] | ec | (Possibly failed) conversion.

Exceptions

  rb_eInvalidByteSequenceError | Invalid byte sequence.
  rb_eUndefinedConversionError | Conversion undefined.

Note
  This function can return when no error.

Definition at line 4251 of file transcode.c.

Referenced by rb_econv_append(), and rb_econv_check_error().

## ◆ rb_econv_close()

void rb_econv_close | ( | rb_econv_t * | ec | ) |

Destructs a converter.

Note that a converter can have a buffer, and can be non-empty. Calling this would lose your data then.

Parameters

  [out] | ec | The converter to destroy.

Postcondition
  `ec` is no longer a valid pointer.

Definition at line 1709 of file transcode.c.

Referenced by rb_econv_close(), rb_econv_open(), and rb_econv_open_opts().

## ◆ rb_econv_convert()

rb_econv_result_t rb_econv_convert | ( | rb_econv_t * | ec,
|  | const unsigned char ** | source_buffer_ptr,
|  | const unsigned char * | source_buffer_end,
|  | unsigned char ** | destination_buffer_ptr,
|  | unsigned char * | destination_buffer_end,
|  | int | flags )

Converts a string from an encoding to another.

Possible flags are either RUBY_ECONV_PARTIAL_INPUT (means the source buffer is a part of much larger one), RUBY_ECONV_AFTER_OUTPUT (instructs the converter to stop after output before input), or both of them.

Parameters

  [in,out] | ec | Conversion specification/state etc.
  [in] | source_buffer_ptr | Target string.
  [in] | source_buffer_end | End of target string.
  [out] | destination_buffer_ptr | Return buffer.
  [out] | destination_buffer_end | End of return buffer.
  [in] | flags | Flags (see above).

Returns
  The status of the conversion.

Postcondition
  `destination_buffer_ptr` holds conversion results.

Definition at line 1453 of file transcode.c.

Referenced by rb_econv_append(), and rb_econv_convert().

## ◆ rb_econv_decorate_at_first()

int rb_econv_decorate_at_first | ( | rb_econv_t * | ec,
|  | const char * | decorator_name )

"Decorate"s a converter.

There are special kind of converters that transforms the contents, like replacing CR into CRLF. You can add such decorators to a converter using this API. By using this function a decorator is prepended at the beginning of a conversion sequence: in case of CRLF conversion, newlines are converted before encodings are converted.

Parameters

  [out] | ec | Target converter to decorate.
  [in] | decorator_name | Name of decorator to prepend.

Return values

  0 | Success.
  -1 | Failure (no such decorator etc.).

Postcondition
  Decorator works before encoding conversion happens.

Definition at line 1941 of file transcode.c.

Referenced by rb_econv_decorate_at_first().

## ◆ rb_econv_decorate_at_last()

int rb_econv_decorate_at_last | ( | rb_econv_t * | ec,
|  | const char * | decorator_name )

Identical to rb_econv_decorate_at_first(), except it adds to the opposite direction.

For instance CRLF conversion would run after encodings are converted.

Parameters

  [out] | ec | Target converter to decorate.
  [in] | decorator_name | Name of decorator to prepend.

Return values

  0 | Success.
  -1 | Failure (no such decorator etc.).

Postcondition
  Decorator works after encoding conversion happens.

Definition at line 1958 of file transcode.c.

Referenced by rb_econv_decorate_at_last(), and rb_econv_open().

## ◆ rb_econv_encoding_to_insert_output()

const char * rb_econv_encoding_to_insert_output | ( | rb_econv_t * | ec | ) |

Queries an encoding name which best suits for rb_econv_insert_output()'s last parameter.

Strings in this encoding need no conversion when inserted; can be both time/space efficient.

Parameters

  [in] | ec | Target converter.

Returns
  Its encoding for insertion.

Definition at line 1510 of file transcode.c.

Referenced by rb_econv_encoding_to_insert_output(), rb_econv_insert_output(), and rb_econv_set_replacement().

## ◆ rb_econv_has_convpath_p()

int rb_econv_has_convpath_p | ( | const char * | from_encoding,
|  | const char * | to_encoding )

Queries if there is more than one way to convert between the passed two encodings.

Encoding conversion are has_and_belongs_to_many relationships. There could be no direct conversion defined for the passed pair. Ruby tries to find an indirect way to do so then. For instance ISO-8859-1 has no direct conversion to ISO-2022-JP. But there is ISO-8859-1 to UTF-8 conversion; then there is UTF-8 to EUC-JP conversion; finally there also is EUC-JP to ISO-2022-JP conversion. So in short ISO-8859-1 can be converted to ISO-2022-JP using that path. This function returns true. Obviously not everything that can be represented using UTF-8 can also be represented using EUC-JP. Conversions in practice can fail depending on the actual input, and that renders exceptions in case of rb_str_encode().

Parameters

  [in] | from_encoding | One encoding.
  [in] | to_encoding | Another encoding.

Return values

  0 | No way to convert the two.
  1 | At least one way to convert the two.

Definition at line 3181 of file transcode.c.

Referenced by rb_econv_has_convpath_p().

## ◆ rb_econv_insert_output()

int rb_econv_insert_output | ( | rb_econv_t * | ec,
|  | const unsigned char * | str,
|  | size_t | len,
|  | const char * | str_encoding )

Appends the passed string to the passed converter's output buffer.

This can be handy when an encoding needs bytes out of thin air; for instance ISO-2022-JP has "shift function" which does not correspond to any characters.

Parameters

  [out] | ec | Target converter.
  [in] | str | String to insert.
  [in] | len | Number of bytes of `str`.
  [in] | str_encoding | Encoding of `str`.

Return values

  0 | Success.
  -1 | Failure (conversion error etc.).

Note
  `str_encoding` can be anything, and `str` itself is converted when necessary.

Definition at line 1594 of file transcode.c.

Referenced by rb_econv_insert_output().

## ◆ rb_econv_make_exception()

VALUE rb_econv_make_exception | ( | rb_econv_t * | ec | ) |

This function makes sense right after rb_econv_convert() returns.

As listed in rb_econv_result_t, rb_econv_convert() can bail out for various reasons. This function checks the passed converter's internal state and convert it to an appropriate exception object.

Parameters

  [in] | ec | Target converter.

Return values

  RUBY_Qnil | The converter has no error.
  otherwise | Conversion error turned into an exception.

Definition at line 4245 of file transcode.c.

Referenced by rb_econv_make_exception().

## ◆ rb_econv_open()

rb_econv_t * rb_econv_open | ( | const char * | source_encoding,
|  | const char * | destination_encoding,
|  | int | ecflags )

Creates a new instance of struct rb_econv_t.

Parameters

  [in] | source_encoding | Name of an encoding.
  [in] | destination_encoding | Name of another encoding.
  [in] | ecflags | A set of enum ruby_econv_flag_type.

Exceptions

  rb_eArgError | No such encoding.

Return values

  NULL | Failed to create a struct rb_econv_t.
  otherwise | Allocated struct rb_econv_t.

Warning
  Return value must be passed to rb_econv_close() exactly once.

Definition at line 1076 of file transcode.c.

Referenced by rb_econv_open(), and rb_econv_open_opts().

## ◆ rb_econv_open_exc()

VALUE rb_econv_open_exc | ( | const char * | senc,
|  | const char * | denc,
|  | int | ecflags )

Creates a `rb_eConverterNotFoundError` exception object (but does not raise).

Parameters

  [in] | senc | Name of source encoding.
  [in] | denc | Name of destination encoding.
  [in] | ecflags | A set of enum ruby_econv_flag_type.

Returns
  An instance of `rb_eConverterNotFoundError`.

Definition at line 2076 of file transcode.c.

Referenced by rb_econv_open_exc().

## ◆ rb_econv_open_opts()

rb_econv_t * rb_econv_open_opts | ( | const char * | source_encoding,
|  | const char * | destination_encoding,
|  | int | ecflags,
|  | VALUE | ecopts )

Identical to rb_econv_open(), except it additionally takes a hash of optional strings.

Parameters

  [in] | source_encoding | Name of an encoding.
  [in] | destination_encoding | Name of another encoding.
  [in] | ecflags | A set of enum ruby_econv_flag_type.
  [in] | ecopts | Optional set of strings.

Exceptions

  rb_eArgError | No such encoding.

Return values

  NULL | Failed to create a struct rb_econv_t.
  otherwise | Allocated struct rb_econv_t.

Warning
  Return value must be passed to rb_econv_close() exactly once.

Definition at line 2630 of file transcode.c.

Referenced by rb_econv_open_opts().

## ◆ rb_econv_prepare_options()

int rb_econv_prepare_options | ( | VALUE | opthash,
|  | VALUE * | ecopts,
|  | int | ecflags )

Identical to rb_econv_prepare_opts(), except it additionally takes the initial value of flags.

The extra bits are bitwise-ORed to the return value.

Parameters

  [in] | opthash | Keyword arguments.
  [out] | ecopts | Return buffer.
  [in] | ecflags | Default set of enum ruby_econv_flag_type.

Exceptions

  rb_eArgError | Unknown/Broken values passed.

Returns
  Calculated set of enum ruby_econv_flag_type.

Postcondition
  `ecopts` holds a hash object suitable for ::rb_io_t::rb_io_enc_t::ecopts.

Definition at line 2579 of file transcode.c.

Referenced by rb_econv_prepare_options(), rb_econv_prepare_opts(), and rb_io_extract_modeenc().

## ◆ rb_econv_prepare_opts()

int rb_econv_prepare_opts | ( | VALUE | opthash,
|  | VALUE * | ecopts )

Splits a keyword arguments hash (that for instance `String#encode` took) into a set of enum ruby_econv_flag_type and a hash storing replacement characters etc.

Parameters

  [in] | opthash | Keyword arguments.
  [out] | ecopts | Return buffer.

Exceptions

  rb_eArgError | Unknown/Broken values passed.

Returns
  Calculated set of enum ruby_econv_flag_type.

Postcondition
  `ecopts` holds a hash object suitable for ::rb_io_t::rb_io_enc_t::ecopts.

Definition at line 2624 of file transcode.c.

Referenced by rb_econv_prepare_opts().

## ◆ rb_econv_putback()

void rb_econv_putback | ( | rb_econv_t * | ec,
|  | unsigned char * | p,
|  | int | n )

Puts back the bytes.

In case of econv_invalid_byte_sequence, some of those invalid bytes are discarded and the others are buffered to be converted later. The latter bytes can be put back using this API.

Parameters

  [out] | ec | Target converter (invalid byte sequence).
  [out] | p | Return buffer.
  [in] | n | Max number of bytes to put back.

Postcondition
  At most `n` bytes of what was put back is written to `p`.

Definition at line 1760 of file transcode.c.

Referenced by rb_econv_putback().

## ◆ rb_econv_putbackable()

int rb_econv_putbackable | ( | rb_econv_t * | ec | ) |

Queries if rb_econv_putback() makes sense, i.e.

there are invalid byte sequences remain in the buffer.

Parameters

  [in] | ec | Target converter.

Returns
  Number of bytes that can be pushed back.

Definition at line 1749 of file transcode.c.

Referenced by rb_econv_putbackable().

## ◆ rb_econv_set_replacement()

int rb_econv_set_replacement | ( | rb_econv_t * | ec,
|  | const unsigned char * | str,
|  | size_t | len,
|  | const char * | encname )

Assigns the replacement string.

The string passed here would appear in converted string when it cannot represent its source counterpart. This can happen for instance you convert an emoji to ISO-8859-1.

Parameters

  [out] | ec | Target converter.
  [in] | str | Replacement string.
  [in] | len | Number of bytes of `str`.
  [in] | encname | Name of encoding of `str`.

Return values

  0 | Success.
  -1 | Failure (ENOMEM etc.).

Postcondition
  `ec`'s replacement string is set to `str`.

Definition at line 2238 of file transcode.c.

Referenced by rb_econv_open_opts(), and rb_econv_set_replacement().

## ◆ rb_econv_str_append()

VALUE rb_econv_str_append | ( | rb_econv_t * | ec,
|  | VALUE | src,
|  | VALUE | dst,
|  | int | flags )

Identical to rb_econv_str_convert(), except it appends the conversion result to the additionally passed string instead of creating a new string.

It can also be seen as a routine identical to rb_econv_append(), except it takes a Ruby's string instead of C's pointer.

Parameters

  [in,out] | ec | Target converter.
  [in] | src | Source string.
  [in] | dst | Return buffer.
  [in] | flags | Flags (see rb_econv_convert).

Exceptions

  rb_eArgError | Converted string is too long.
  rb_eInvalidByteSequenceError | Invalid byte sequence.
  rb_eUndefinedConversionError | Conversion undefined.

Returns
  The conversion result.

Definition at line 1898 of file transcode.c.

Referenced by rb_econv_str_append().

## ◆ rb_econv_str_convert()

VALUE rb_econv_str_convert | ( | rb_econv_t * | ec,
|  | VALUE | src,
|  | int | flags )

Identical to rb_econv_convert(), except it takes Ruby's string instead of C's pointer.

Parameters

  [in,out] | ec | Target converter.
  [in] | src | Source string.
  [in] | flags | Flags (see rb_econv_convert).

Exceptions

  rb_eArgError | Converted string is too long.
  rb_eInvalidByteSequenceError | Invalid byte sequence.
  rb_eUndefinedConversionError | Conversion undefined.

Returns
  The conversion result.

Definition at line 1910 of file transcode.c.

Referenced by rb_econv_str_convert().

## ◆ rb_econv_substr_append()

VALUE rb_econv_substr_append | ( | rb_econv_t * | ec,
|  | VALUE | src,
|  | long | byteoff,
|  | long | bytesize,
|  | VALUE | dst,
|  | int | flags )

Identical to rb_econv_str_append(), except it appends only a part of the passed string with conversion.

It can also be seen as a routine identical to rb_econv_substr_convert(), except it appends the conversion result to the additionally passed string instead of creating a new string.

Parameters

  [in,out] | ec | Target converter.
  [in] | src | Source string.
  [in] | byteoff | Number of bytes to seek.
  [in] | bytesize | Number of bytes to read.
  [in] | dst | Return buffer.
  [in] | flags | Flags (see rb_econv_convert).

Exceptions

  rb_eArgError | Converted string is too long.
  rb_eInvalidByteSequenceError | Invalid byte sequence.
  rb_eUndefinedConversionError | Conversion undefined.

Returns
  The conversion result.

Definition at line 1889 of file transcode.c.

Referenced by rb_econv_str_append(), rb_econv_str_convert(), rb_econv_substr_append(), and rb_econv_substr_convert().

## ◆ rb_econv_substr_convert()

VALUE rb_econv_substr_convert | ( | rb_econv_t * | ec,
|  | VALUE | src,
|  | long | byteoff,
|  | long | bytesize,
|  | int | flags )

Identical to rb_econv_str_convert(), except it converts only a part of the passed string.

Can be handy when you for instance want to do line-buffered conversion.

Parameters

  [in,out] | ec | Target converter.
  [in] | src | Source string.
  [in] | byteoff | Number of bytes to seek.
  [in] | bytesize | Number of bytes to read.
  [in] | flags | Flags (see rb_econv_convert).

Exceptions

  rb_eArgError | Converted string is too long.
  rb_eInvalidByteSequenceError | Invalid byte sequence.
  rb_eUndefinedConversionError | Conversion undefined.

Returns
  The conversion result.

Definition at line 1904 of file transcode.c.

Referenced by rb_econv_substr_convert().

## ◆ rb_str_encode()

VALUE rb_str_encode | ( | VALUE | str,
|  | VALUE | to,
|  | int | ecflags,
|  | VALUE | ecopts )

Converts the contents of the passed string from its encoding to the passed one.

Parameters

  [in] | str | Target string.
  [in] | to | Destination encoding.
  [in] | ecflags | A set of enum ruby_econv_flag_type.
  [in] | ecopts | A keyword hash, like ::rb_io_t::rb_io_enc_t::ecopts.

Exceptions

  rb_eArgError | Not fully converted.
  rb_eInvalidByteSequenceError | `str` is malformed.
  rb_eUndefinedConversionError | `str` has a character not representable using `to`.
  rb_eConversionNotFoundError | There is no known conversion from `str`'s encoding to `to`.

Returns
  A string whose encoding is `to`, and whose contents is converted contents of `str`.

Note
  Use rb_econv_prepare_options() to generate `ecopts`.

Definition at line 2884 of file transcode.c.

Referenced by rb_str_ellipsize(), and rb_str_encode().