Struct IConv

Source

pub struct IConv(/* private fields */);

Expand description

The GIConv struct wraps an iconv() conversion descriptor. It contains private data and should only be accessed using the following functions.

Implementations§

Source §

impl IConv

Source

pub fn new( to_codeset: impl IntoGStr, from_codeset: impl IntoGStr, ) -> Option<Self>

Same as the standard UNIX routine iconv_open(), but may be implemented via libiconv on UNIX flavors that lack a native implementation.

GLib provides g_convert() and g_locale_to_utf8() which are likely more convenient than the raw iconv wrappers.

§`to_codeset`

destination codeset

§`from_codeset`

source codeset

§Returns

a “conversion descriptor”, or (GIConv)-1 if opening the converter failed.

Source

pub fn convert(&mut self, str_: &[u8]) -> Result<(Slice<u8>, usize), CvtError>

Converts a string from one character set to another.

Note that you should use g_iconv() for streaming conversions. Despite the fact that @bytes_read can return information about partial characters, the g_convert_… functions are not generally suitable for streaming. If the underlying converter maintains internal state, then this won’t be preserved across successive calls to g_convert(), g_convert_with_iconv() or g_convert_with_fallback(). (An example of this is the GNU C converter for CP1255 which does not emit a base character until it knows that the next character is not a mark that could combine with the base character.)

Characters which are valid in the input character set, but which have no representation in the output character set will result in a ConvertError::IllegalSequence error. This is in contrast to the iconv() specification, which leaves this behaviour implementation defined. Note that this is the same error code as is returned for an invalid byte sequence in the input character set. To get defined behaviour for conversion of unrepresentable characters, use g_convert_with_fallback().

§`str`

            the string to convert.

§`converter`

conversion descriptor from g_iconv_open()

§Returns

          If the conversion was successful, a newly allocated buffer
          containing the converted string, which must be freed with
          g_free(). Otherwise [`None`] and @error will be set.

§`bytes_read`

location to store the number of bytes in the input string that were successfully converted, or None. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error ConvertError::IllegalSequence occurs, the value stored will be the byte offset after the last valid input sequence. Converts a string from one character set to another.

Note that you should use g_iconv() for streaming conversions. Despite the fact that @bytes_read can return information about partial characters, the g_convert_… functions are not generally suitable for streaming. If the underlying converter maintains internal state, then this won’t be preserved across successive calls to g_convert(), g_convert_with_iconv() or g_convert_with_fallback(). (An example of this is the GNU C converter for CP1255 which does not emit a base character until it knows that the next character is not a mark that could combine with the base character.)

Characters which are valid in the input character set, but which have no representation in the output character set will result in a ConvertError::IllegalSequence error. This is in contrast to the iconv() specification, which leaves this behaviour implementation defined. Note that this is the same error code as is returned for an invalid byte sequence in the input character set. To get defined behaviour for conversion of unrepresentable characters, use g_convert_with_fallback().

§`str`

            the string to convert.

§`converter`

conversion descriptor from g_iconv_open()

§Returns

          If the conversion was successful, a newly allocated buffer
          containing the converted string, which must be freed with
          g_free(). Otherwise [`None`] and @error will be set.

§`bytes_read`

location to store the number of bytes in the input string that were successfully converted, or None. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error ConvertError::IllegalSequence occurs, the value stored will be the byte offset after the last valid input sequence.

Source

pub fn iconv( &mut self, inbuf: Option<&[u8]>, outbuf: Option<&mut [MaybeUninit<u8>]>, ) -> Result<(usize, usize, usize), IConvError>

Same as the standard UNIX routine iconv(), but may be implemented via libiconv on UNIX flavors that lack a native implementation.

GLib provides g_convert() and g_locale_to_utf8() which are likely more convenient than the raw iconv wrappers.

Note that the behaviour of iconv() for characters which are valid in the input character set, but which have no representation in the output character set, is implementation defined. This function may return success (with a positive number of non-reversible conversions as replacement characters were used), or it may return -1 and set an error such as EILSEQ, in such a situation.

§`converter`

conversion descriptor from g_iconv_open()

§`inbuf`

bytes to convert

§`inbytes_left`

inout parameter, bytes remaining to convert in @inbuf

§`outbuf`

converted output bytes

§`outbytes_left`

inout parameter, bytes available to fill in @outbuf

§Returns

count of non-reversible conversions, or -1 on error Same as the standard UNIX routine iconv(), but may be implemented via libiconv on UNIX flavors that lack a native implementation.

GLib provides g_convert() and g_locale_to_utf8() which are likely more convenient than the raw iconv wrappers.

Note that the behaviour of iconv() for characters which are valid in the input character set, but which have no representation in the output character set, is implementation defined. This function may return success (with a positive number of non-reversible conversions as replacement characters were used), or it may return -1 and set an error such as EILSEQ, in such a situation.