glib/

convert.rs

// Take a look at the license at the top of the repository in the LICENSE file.

use std::{fmt, io, os::raw::c_char, path::PathBuf, ptr};

use crate::{ffi, translate::*, ConvertError, Error, GString, NormalizeMode, Slice};

// rustdoc-stripper-ignore-next
/// A wrapper for [`ConvertError`](crate::ConvertError) that can hold an offset into the input
/// string.
#[derive(Debug)]
pub enum CvtError {
    Convert(Error),
    IllegalSequence { source: Error, offset: usize },
}

impl std::error::Error for CvtError {
    fn source(&self) -> ::core::option::Option<&(dyn std::error::Error + 'static)> {
        match self {
            CvtError::Convert(err) => std::error::Error::source(err),
            CvtError::IllegalSequence { source, .. } => Some(source),
        }
    }
}

impl fmt::Display for CvtError {
    fn fmt(&self, fmt: &mut fmt::Formatter) -> ::core::fmt::Result {
        match self {
            CvtError::Convert(err) => fmt::Display::fmt(err, fmt),
            CvtError::IllegalSequence { source, offset } => {
                write!(fmt, "{source} at offset {offset}")
            }
        }
    }
}

impl std::convert::From<Error> for CvtError {
    fn from(err: Error) -> Self {
        CvtError::Convert(err)
    }
}

impl CvtError {
    #[inline]
    fn new(err: Error, bytes_read: usize) -> Self {
        if err.kind::<ConvertError>() == Some(ConvertError::IllegalSequence) {
            Self::IllegalSequence {
                source: err,
                offset: bytes_read,
            }
        } else {
            err.into()
        }
    }
}

/// 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.)
///
/// Using extensions such as "//TRANSLIT" may not work (or may not work
/// well) on many platforms.  Consider using g_str_to_ascii() instead.
/// ## `str`
///
///                 the string to convert.
/// ## `to_codeset`
/// name of character set into which to convert @str
/// ## `from_codeset`
/// character set of @str.
///
/// # 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`][crate::ConvertError::IllegalSequence] occurs, the value
///                 stored will be the byte offset after the last valid
///                 input sequence.
// rustdoc-stripper-ignore-next-stop
/// 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.)
///
/// Using extensions such as "//TRANSLIT" may not work (or may not work
/// well) on many platforms.  Consider using g_str_to_ascii() instead.
/// ## `str`
///
///                 the string to convert.
/// ## `to_codeset`
/// name of character set into which to convert @str
/// ## `from_codeset`
/// character set of @str.
///
/// # 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`][crate::ConvertError::IllegalSequence] occurs, the value
///                 stored will be the byte offset after the last valid
///                 input sequence.
#[doc(alias = "g_convert")]
pub fn convert(
    str_: &[u8],
    to_codeset: impl IntoGStr,
    from_codeset: impl IntoGStr,
) -> Result<(Slice<u8>, usize), CvtError> {
    assert!(str_.len() <= isize::MAX as usize);
    let mut bytes_read = 0;
    let mut bytes_written = 0;
    let mut error = ptr::null_mut();
    let result = to_codeset.run_with_gstr(|to_codeset| {
        from_codeset.run_with_gstr(|from_codeset| unsafe {
            ffi::g_convert(
                str_.as_ptr(),
                str_.len() as isize,
                to_codeset.to_glib_none().0,
                from_codeset.to_glib_none().0,
                &mut bytes_read,
                &mut bytes_written,
                &mut error,
            )
        })
    });
    if result.is_null() {
        Err(CvtError::new(unsafe { from_glib_full(error) }, bytes_read))
    } else {
        let slice = unsafe { Slice::from_glib_full_num(result, bytes_written as _) };
        Ok((slice, bytes_read))
    }
}

/// Converts a string from one character set to another, possibly
/// including fallback sequences for characters not representable
/// in the output. Note that it is not guaranteed that the specification
/// for the fallback sequences in @fallback will be honored. Some
/// systems may do an approximate conversion from @from_codeset
/// to @to_codeset in their iconv() functions,
/// in which case GLib will simply return that approximate conversion.
///
/// 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.)
/// ## `str`
///
///                the string to convert.
/// ## `to_codeset`
/// name of character set into which to convert @str
/// ## `from_codeset`
/// character set of @str.
/// ## `fallback`
/// UTF-8 string to use in place of characters not
///                present in the target encoding. (The string must be
///                representable in the target encoding).
///                If [`None`], characters not in the target encoding will
///                be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
///
/// # 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.
// rustdoc-stripper-ignore-next-stop
/// Converts a string from one character set to another, possibly
/// including fallback sequences for characters not representable
/// in the output. Note that it is not guaranteed that the specification
/// for the fallback sequences in @fallback will be honored. Some
/// systems may do an approximate conversion from @from_codeset
/// to @to_codeset in their iconv() functions,
/// in which case GLib will simply return that approximate conversion.
///
/// 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.)
/// ## `str`
///
///                the string to convert.
/// ## `to_codeset`
/// name of character set into which to convert @str
/// ## `from_codeset`
/// character set of @str.
/// ## `fallback`
/// UTF-8 string to use in place of characters not
///                present in the target encoding. (The string must be
///                representable in the target encoding).
///                If [`None`], characters not in the target encoding will
///                be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
///
/// # 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.
#[doc(alias = "g_convert_with_fallback")]
pub fn convert_with_fallback(
    str_: &[u8],
    to_codeset: impl IntoGStr,
    from_codeset: impl IntoGStr,
    fallback: Option<impl IntoGStr>,
) -> Result<(Slice<u8>, usize), CvtError> {
    assert!(str_.len() <= isize::MAX as usize);
    let mut bytes_read = 0;
    let mut bytes_written = 0;
    let mut error = ptr::null_mut();
    let result = to_codeset.run_with_gstr(|to_codeset| {
        from_codeset.run_with_gstr(|from_codeset| {
            fallback.run_with_gstr(|fallback| unsafe {
                ffi::g_convert_with_fallback(
                    str_.as_ptr(),
                    str_.len() as isize,
                    to_codeset.to_glib_none().0,
                    from_codeset.to_glib_none().0,
                    fallback.to_glib_none().0,
                    &mut bytes_read,
                    &mut bytes_written,
                    &mut error,
                )
            })
        })
    });
    if result.is_null() {
        Err(CvtError::new(unsafe { from_glib_full(error) }, bytes_read))
    } else {
        let slice = unsafe { Slice::from_glib_full_num(result, bytes_written as _) };
        Ok((slice, bytes_read))
    }
}

// rustdoc-stripper-ignore-next
/// A wrapper for [`std::io::Error`] that can hold an offset into an input string.
#[derive(Debug)]
pub enum IConvError {
    Error(io::Error),
    WithOffset { source: io::Error, offset: usize },
}

impl std::error::Error for IConvError {
    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
        match self {
            IConvError::Error(err) => std::error::Error::source(err),
            IConvError::WithOffset { source, .. } => Some(source),
        }
    }
}

impl fmt::Display for IConvError {
    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
        match self {
            IConvError::Error(err) => fmt::Display::fmt(err, fmt),
            IConvError::WithOffset { source, offset } => write!(fmt, "{source} at offset {offset}"),
        }
    }
}

impl std::convert::From<io::Error> for IConvError {
    fn from(err: io::Error) -> Self {
        IConvError::Error(err)
    }
}

/// The GIConv struct wraps an iconv() conversion descriptor. It contains
/// private data and should only be accessed using the following functions.
#[derive(Debug)]
#[repr(transparent)]
#[doc(alias = "GIConv")]
pub struct IConv(ffi::GIConv);

unsafe impl Send for IConv {}

impl IConv {
    /// 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.
    #[doc(alias = "g_iconv_open")]
    #[allow(clippy::unnecessary_lazy_evaluations)]
    pub fn new(to_codeset: impl IntoGStr, from_codeset: impl IntoGStr) -> Option<Self> {
        let iconv = to_codeset.run_with_gstr(|to_codeset| {
            from_codeset.run_with_gstr(|from_codeset| unsafe {
                ffi::g_iconv_open(to_codeset.to_glib_none().0, from_codeset.to_glib_none().0)
            })
        });
        (iconv as isize != -1).then(|| Self(iconv))
    }
    /// 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`][crate::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`][crate::ConvertError::IllegalSequence] occurs, the value
    ///                 stored will be the byte offset after the last valid
    ///                 input sequence.
    // rustdoc-stripper-ignore-next-stop
    /// 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`][crate::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`][crate::ConvertError::IllegalSequence] occurs, the value
    ///                 stored will be the byte offset after the last valid
    ///                 input sequence.
    #[doc(alias = "g_convert_with_iconv")]
    pub fn convert(&mut self, str_: &[u8]) -> Result<(Slice<u8>, usize), CvtError> {
        assert!(str_.len() <= isize::MAX as usize);
        let mut bytes_read = 0;
        let mut bytes_written = 0;
        let mut error = ptr::null_mut();
        let result = unsafe {
            ffi::g_convert_with_iconv(
                str_.as_ptr(),
                str_.len() as isize,
                self.0,
                &mut bytes_read,
                &mut bytes_written,
                &mut error,
            )
        };
        if result.is_null() {
            Err(CvtError::new(unsafe { from_glib_full(error) }, bytes_read))
        } else {
            let slice = unsafe { Slice::from_glib_full_num(result, bytes_written as _) };
            Ok((slice, bytes_read))
        }
    }
    /// 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.
    ///
    /// See [`iconv(3posix)`](man:iconv(3posix)) and [`iconv(3)`](man:iconv(3)) for more details about behavior when an
    /// error occurs.
    /// ## `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
    // rustdoc-stripper-ignore-next-stop
    /// 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.
    ///
    /// See [`iconv(3posix)`](man:iconv(3posix)) and [`iconv(3)`](man:iconv(3)) for more details about behavior when an
    /// error occurs.
    /// ## `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
    #[doc(alias = "g_iconv")]
    pub fn iconv(
        &mut self,
        inbuf: Option<&[u8]>,
        outbuf: Option<&mut [std::mem::MaybeUninit<u8>]>,
    ) -> Result<(usize, usize, usize), IConvError> {
        let input_len = inbuf.as_ref().map(|b| b.len()).unwrap_or_default();
        let mut inbytes_left = input_len;
        let mut outbytes_left = outbuf.as_ref().map(|b| b.len()).unwrap_or_default();
        let mut inbuf = inbuf
            .map(|b| mut_override(b.as_ptr()) as *mut c_char)
            .unwrap_or_else(ptr::null_mut);
        let mut outbuf = outbuf
            .map(|b| b.as_mut_ptr() as *mut c_char)
            .unwrap_or_else(ptr::null_mut);
        let conversions = unsafe {
            ffi::g_iconv(
                self.0,
                &mut inbuf,
                &mut inbytes_left,
                &mut outbuf,
                &mut outbytes_left,
            )
        };
        if conversions as isize == -1 {
            let err = io::Error::last_os_error();
            let code = err.raw_os_error().unwrap();
            if code == libc::EILSEQ || code == libc::EINVAL {
                Err(IConvError::WithOffset {
                    source: err,
                    offset: input_len - inbytes_left,
                })
            } else {
                Err(err.into())
            }
        } else {
            Ok((conversions, inbytes_left, outbytes_left))
        }
    }
}

impl Drop for IConv {
    #[inline]
    fn drop(&mut self) {
        unsafe {
            ffi::g_iconv_close(self.0);
        }
    }
}

/// Determines the preferred character sets used for filenames.
/// The first character set from the @charsets is the filename encoding, the
/// subsequent character sets are used when trying to generate a displayable
/// representation of a filename, see g_filename_display_name().
///
/// On Unix, the character sets are determined by consulting the
/// environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`.
/// On Windows, the character set used in the GLib API is always UTF-8
/// and said environment variables have no effect.
///
/// `G_FILENAME_ENCODING` may be set to a comma-separated list of
/// character set names. The special token `@locale` is taken to mean the
/// character set for the [current locale](running.html#locale).
/// If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is,
/// the character set of the current locale is taken as the filename
/// encoding. If neither environment variable  is set, UTF-8 is taken
/// as the filename encoding, but the character set of the current locale
/// is also put in the list of encodings.
///
/// The returned @charsets belong to GLib and must not be freed.
///
/// Note that on Unix, regardless of the locale character set or
/// `G_FILENAME_ENCODING` value, the actual file names present
/// on a system might be in any random encoding or just gibberish.
///
/// # Returns
///
/// [`true`] if the filename encoding is UTF-8.
///
/// ## `filename_charsets`
///
///    return location for the [`None`]-terminated list of encoding names
// rustdoc-stripper-ignore-next-stop
/// Determines the preferred character sets used for filenames.
/// The first character set from the @charsets is the filename encoding, the
/// subsequent character sets are used when trying to generate a displayable
/// representation of a filename, see g_filename_display_name().
///
/// On Unix, the character sets are determined by consulting the
/// environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`.
/// On Windows, the character set used in the GLib API is always UTF-8
/// and said environment variables have no effect.
///
/// `G_FILENAME_ENCODING` may be set to a comma-separated list of
/// character set names. The special token `@locale` is taken to mean the
/// character set for the [current locale](running.html#locale).
/// If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is,
/// the character set of the current locale is taken as the filename
/// encoding. If neither environment variable  is set, UTF-8 is taken
/// as the filename encoding, but the character set of the current locale
/// is also put in the list of encodings.
///
/// The returned @charsets belong to GLib and must not be freed.
///
/// Note that on Unix, regardless of the locale character set or
/// `G_FILENAME_ENCODING` value, the actual file names present
/// on a system might be in any random encoding or just gibberish.
///
/// # Returns
///
/// [`true`] if the filename encoding is UTF-8.
///
/// ## `filename_charsets`
///
///    return location for the [`None`]-terminated list of encoding names
#[doc(alias = "g_get_filename_charsets")]
#[doc(alias = "get_filename_charsets")]
pub fn filename_charsets() -> (bool, Vec<GString>) {
    let mut filename_charsets = ptr::null_mut();
    unsafe {
        let is_utf8 = ffi::g_get_filename_charsets(&mut filename_charsets);
        (
            from_glib(is_utf8),
            FromGlibPtrContainer::from_glib_none(filename_charsets),
        )
    }
}

/// Converts a string from UTF-8 to the encoding GLib uses for
/// filenames. Note that on Windows GLib uses UTF-8 for filenames;
/// on other platforms, this function indirectly depends on the
/// [current locale](running.html#locale).
///
/// The input string shall not contain nul characters even if the @len
/// argument is positive. A nul character found inside the string will result
/// in error [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence]. If the filename encoding is
/// not UTF-8 and the conversion output contains a nul character, the error
/// [`ConvertError::EmbeddedNul`][crate::ConvertError::EmbeddedNul] is set and the function returns [`None`].
/// ## `utf8string`
/// a UTF-8 encoded string.
/// ## `len`
/// the length of the string, or -1 if the string is
///                 nul-terminated.
///
/// # Returns
///
///
///               The converted string, or [`None`] on an error.
///
/// ## `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`][crate::ConvertError::IllegalSequence] occurs, the value
///                 stored will be the byte offset after the last valid
///                 input sequence.
///
/// ## `bytes_written`
/// the number of bytes stored in
///                 the output buffer (not including the terminating nul).
// rustdoc-stripper-ignore-next-stop
/// Converts a string from UTF-8 to the encoding GLib uses for
/// filenames. Note that on Windows GLib uses UTF-8 for filenames;
/// on other platforms, this function indirectly depends on the
/// [current locale](running.html#locale).
///
/// The input string shall not contain nul characters even if the @len
/// argument is positive. A nul character found inside the string will result
/// in error [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence]. If the filename encoding is
/// not UTF-8 and the conversion output contains a nul character, the error
/// [`ConvertError::EmbeddedNul`][crate::ConvertError::EmbeddedNul] is set and the function returns [`None`].
/// ## `utf8string`
/// a UTF-8 encoded string.
/// ## `len`
/// the length of the string, or -1 if the string is
///                 nul-terminated.
///
/// # Returns
///
///
///               The converted string, or [`None`] on an error.
///
/// ## `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`][crate::ConvertError::IllegalSequence] occurs, the value
///                 stored will be the byte offset after the last valid
///                 input sequence.
///
/// ## `bytes_written`
/// the number of bytes stored in
///                 the output buffer (not including the terminating nul).
#[doc(alias = "g_filename_from_utf8")]
pub fn filename_from_utf8(utf8string: impl IntoGStr) -> Result<(PathBuf, usize), CvtError> {
    let mut bytes_read = 0;
    let mut bytes_written = std::mem::MaybeUninit::uninit();
    let mut error = ptr::null_mut();
    let ret = utf8string.run_with_gstr(|utf8string| {
        assert!(utf8string.len() <= isize::MAX as usize);
        let len = utf8string.len() as isize;
        unsafe {
            ffi::g_filename_from_utf8(
                utf8string.to_glib_none().0,
                len,
                &mut bytes_read,
                bytes_written.as_mut_ptr(),
                &mut error,
            )
        }
    });
    if error.is_null() {
        Ok(unsafe {
            (
                PathBuf::from_glib_full_num(ret, bytes_written.assume_init()),
                bytes_read,
            )
        })
    } else {
        Err(unsafe { CvtError::new(from_glib_full(error), bytes_read) })
    }
}

/// Converts a string which is in the encoding used by GLib for
/// filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
/// for filenames; on other platforms, this function indirectly depends on
/// the [current locale](running.html#locale).
///
/// The input string shall not contain nul characters even if the @len
/// argument is positive. A nul character found inside the string will result
/// in error [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence].
/// If the source encoding is not UTF-8 and the conversion output contains a
/// nul character, the error [`ConvertError::EmbeddedNul`][crate::ConvertError::EmbeddedNul] is set and the
/// function returns [`None`]. Use g_convert() to produce output that
/// may contain embedded nul characters.
/// ## `opsysstring`
/// a string in the encoding for filenames
/// ## `len`
/// the length of the string, or -1 if the string is
///                 nul-terminated (Note that some encodings may allow nul
///                 bytes to occur inside strings. In that case, using -1
///                 for the @len parameter is unsafe)
///
/// # Returns
///
/// The converted string, or [`None`] on an error.
///
/// ## `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`][crate::ConvertError::IllegalSequence] occurs, the value
///                 stored will be the byte offset after the last valid
///                 input sequence.
///
/// ## `bytes_written`
/// the number of bytes stored in the output
///                 buffer (not including the terminating nul).
// rustdoc-stripper-ignore-next-stop
/// Converts a string which is in the encoding used by GLib for
/// filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
/// for filenames; on other platforms, this function indirectly depends on
/// the [current locale](running.html#locale).
///
/// The input string shall not contain nul characters even if the @len
/// argument is positive. A nul character found inside the string will result
/// in error [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence].
/// If the source encoding is not UTF-8 and the conversion output contains a
/// nul character, the error [`ConvertError::EmbeddedNul`][crate::ConvertError::EmbeddedNul] is set and the
/// function returns [`None`]. Use g_convert() to produce output that
/// may contain embedded nul characters.
/// ## `opsysstring`
/// a string in the encoding for filenames
/// ## `len`
/// the length of the string, or -1 if the string is
///                 nul-terminated (Note that some encodings may allow nul
///                 bytes to occur inside strings. In that case, using -1
///                 for the @len parameter is unsafe)
///
/// # Returns
///
/// The converted string, or [`None`] on an error.
///
/// ## `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`][crate::ConvertError::IllegalSequence] occurs, the value
///                 stored will be the byte offset after the last valid
///                 input sequence.
///
/// ## `bytes_written`
/// the number of bytes stored in the output
///                 buffer (not including the terminating nul).
#[doc(alias = "g_filename_to_utf8")]
pub fn filename_to_utf8(
    opsysstring: impl AsRef<std::path::Path>,
) -> Result<(crate::GString, usize), CvtError> {
    let path = opsysstring.as_ref().to_glib_none();
    let mut bytes_read = 0;
    let mut bytes_written = std::mem::MaybeUninit::uninit();
    let mut error = ptr::null_mut();
    let ret = unsafe {
        ffi::g_filename_to_utf8(
            path.0,
            path.1.as_bytes().len() as isize,
            &mut bytes_read,
            bytes_written.as_mut_ptr(),
            &mut error,
        )
    };
    if error.is_null() {
        Ok(unsafe {
            (
                GString::from_glib_full_num(ret, bytes_written.assume_init()),
                bytes_read,
            )
        })
    } else {
        Err(unsafe { CvtError::new(from_glib_full(error), bytes_read) })
    }
}

/// Converts a string from UTF-8 to the encoding used for strings by
/// the C runtime (usually the same as that used by the operating
/// system) in the [current locale](running.html#locale).
/// On Windows this means the system codepage.
///
/// The input string shall not contain nul characters even if the @len
/// argument is positive. A nul character found inside the string will result
/// in error [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence]. Use g_convert() to convert
/// input that may contain embedded nul characters.
/// ## `utf8string`
/// a UTF-8 encoded string
/// ## `len`
/// the length of the string, or -1 if the string is
///                 nul-terminated.
///
/// # Returns
///
///
///          A newly-allocated buffer containing the converted string,
///          or [`None`] on an error, 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`][crate::ConvertError::IllegalSequence] occurs, the value
///                 stored will be the byte offset after the last valid
///                 input sequence.
// rustdoc-stripper-ignore-next-stop
/// Converts a string from UTF-8 to the encoding used for strings by
/// the C runtime (usually the same as that used by the operating
/// system) in the [current locale](running.html#locale).
/// On Windows this means the system codepage.
///
/// The input string shall not contain nul characters even if the @len
/// argument is positive. A nul character found inside the string will result
/// in error [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence]. Use g_convert() to convert
/// input that may contain embedded nul characters.
/// ## `utf8string`
/// a UTF-8 encoded string
/// ## `len`
/// the length of the string, or -1 if the string is
///                 nul-terminated.
///
/// # Returns
///
///
///          A newly-allocated buffer containing the converted string,
///          or [`None`] on an error, 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`][crate::ConvertError::IllegalSequence] occurs, the value
///                 stored will be the byte offset after the last valid
///                 input sequence.
#[doc(alias = "g_locale_from_utf8")]
pub fn locale_from_utf8(utf8string: impl IntoGStr) -> Result<(Slice<u8>, usize), CvtError> {
    let mut bytes_read = 0;
    let mut bytes_written = std::mem::MaybeUninit::uninit();
    let mut error = ptr::null_mut();
    let ret = utf8string.run_with_gstr(|utf8string| {
        assert!(utf8string.len() <= isize::MAX as usize);
        unsafe {
            ffi::g_locale_from_utf8(
                utf8string.as_ptr(),
                utf8string.len() as isize,
                &mut bytes_read,
                bytes_written.as_mut_ptr(),
                &mut error,
            )
        }
    });
    if error.is_null() {
        Ok(unsafe {
            (
                Slice::from_glib_full_num(ret, bytes_written.assume_init() + 1),
                bytes_read,
            )
        })
    } else {
        Err(unsafe { CvtError::new(from_glib_full(error), bytes_read) })
    }
}

/// Converts a string which is in the encoding used for strings by
/// the C runtime (usually the same as that used by the operating
/// system) in the [current locale](running.html#locale) into a UTF-8 string.
///
/// If the source encoding is not UTF-8 and the conversion output contains a
/// nul character, the error [`ConvertError::EmbeddedNul`][crate::ConvertError::EmbeddedNul] is set and the
/// function returns [`None`].
/// If the source encoding is UTF-8, an embedded nul character is treated with
/// the [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence] error for backward compatibility with
/// earlier versions of this library. Use g_convert() to produce output that
/// may contain embedded nul characters.
/// ## `opsysstring`
/// a string in the
///                 encoding of the current locale. On Windows
///                 this means the system codepage.
///
/// # Returns
///
/// The converted string, or [`None`] on an error.
///
/// ## `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`][crate::ConvertError::IllegalSequence] occurs, the value
///                 stored will be the byte offset after the last valid
///                 input sequence.
///
/// ## `bytes_written`
/// the number of bytes stored in the output
///                 buffer (not including the terminating nul).
// rustdoc-stripper-ignore-next-stop
/// Converts a string which is in the encoding used for strings by
/// the C runtime (usually the same as that used by the operating
/// system) in the [current locale](running.html#locale) into a UTF-8 string.
///
/// If the source encoding is not UTF-8 and the conversion output contains a
/// nul character, the error [`ConvertError::EmbeddedNul`][crate::ConvertError::EmbeddedNul] is set and the
/// function returns [`None`].
/// If the source encoding is UTF-8, an embedded nul character is treated with
/// the [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence] error for backward compatibility with
/// earlier versions of this library. Use g_convert() to produce output that
/// may contain embedded nul characters.
/// ## `opsysstring`
/// a string in the
///                 encoding of the current locale. On Windows
///                 this means the system codepage.
///
/// # Returns
///
/// The converted string, or [`None`] on an error.
///
/// ## `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`][crate::ConvertError::IllegalSequence] occurs, the value
///                 stored will be the byte offset after the last valid
///                 input sequence.
///
/// ## `bytes_written`
/// the number of bytes stored in the output
///                 buffer (not including the terminating nul).
#[doc(alias = "g_locale_to_utf8")]
pub fn locale_to_utf8(opsysstring: &[u8]) -> Result<(crate::GString, usize), CvtError> {
    let len = opsysstring.len() as isize;
    let mut bytes_read = 0;
    let mut bytes_written = std::mem::MaybeUninit::uninit();
    let mut error = ptr::null_mut();
    let ret = unsafe {
        ffi::g_locale_to_utf8(
            opsysstring.to_glib_none().0,
            len,
            &mut bytes_read,
            bytes_written.as_mut_ptr(),
            &mut error,
        )
    };
    if error.is_null() {
        Ok(unsafe {
            (
                GString::from_glib_full_num(ret, bytes_written.assume_init()),
                bytes_read,
            )
        })
    } else {
        Err(unsafe { CvtError::new(from_glib_full(error), bytes_read) })
    }
}

#[doc(alias = "g_utf8_to_ucs4")]
#[doc(alias = "g_utf8_to_ucs4_fast")]
#[doc(alias = "utf8_to_ucs4")]
pub fn utf8_to_utf32(str: impl AsRef<str>) -> Slice<char> {
    unsafe {
        let mut items_written = 0;

        let str_as_utf32 = ffi::g_utf8_to_ucs4_fast(
            str.as_ref().as_ptr().cast::<c_char>(),
            str.as_ref().len() as _,
            &mut items_written,
        );

        // NOTE: We assume that u32 and char have the same layout and trust that glib won't give us
        //       invalid UTF-32 codepoints
        Slice::from_glib_full_num(str_as_utf32, items_written as usize)
    }
}

#[doc(alias = "g_ucs4_to_utf8")]
#[doc(alias = "ucs4_to_utf8")]
pub fn utf32_to_utf8(str: impl AsRef<[char]>) -> GString {
    let mut items_read = 0;
    let mut items_written = 0;
    let mut error = ptr::null_mut();

    unsafe {
        let str_as_utf8 = ffi::g_ucs4_to_utf8(
            str.as_ref().as_ptr().cast::<u32>(),
            str.as_ref().len() as _,
            &mut items_read,
            &mut items_written,
            &mut error,
        );

        debug_assert!(
            error.is_null(),
            "Rust `char` should always be convertible to UTF-8"
        );

        GString::from_glib_full_num(str_as_utf8, items_written as usize)
    }
}

#[doc(alias = "g_utf8_casefold")]
#[doc(alias = "utf8_casefold")]
pub fn casefold(str: impl AsRef<str>) -> GString {
    unsafe {
        let str = ffi::g_utf8_casefold(str.as_ref().as_ptr().cast(), str.as_ref().len() as isize);

        from_glib_full(str)
    }
}

#[doc(alias = "g_utf8_normalize")]
#[doc(alias = "utf8_normalize")]
pub fn normalize(str: impl AsRef<str>, mode: NormalizeMode) -> GString {
    unsafe {
        let str = ffi::g_utf8_normalize(
            str.as_ref().as_ptr().cast(),
            str.as_ref().len() as isize,
            mode.into_glib(),
        );

        from_glib_full(str)
    }
}

#[cfg(test)]
mod tests {
    #[test]
    fn convert_ascii() {
        assert!(super::convert(b"Hello", "utf-8", "ascii").is_ok());
        assert!(super::convert(b"He\xaallo", "utf-8", "ascii").is_err());
        assert_eq!(
            super::convert_with_fallback(b"H\xc3\xa9llo", "ascii", "utf-8", crate::NONE_STR)
                .unwrap()
                .0
                .as_slice(),
            b"H\\u00e9llo"
        );
        assert_eq!(
            super::convert_with_fallback(b"H\xc3\xa9llo", "ascii", "utf-8", Some("_"))
                .unwrap()
                .0
                .as_slice(),
            b"H_llo"
        );
    }
    #[test]
    fn iconv() {
        let mut conv = super::IConv::new("utf-8", "ascii").unwrap();
        assert!(conv.convert(b"Hello").is_ok());
        assert!(conv.convert(b"He\xaallo").is_err());
        assert!(super::IConv::new("utf-8", "badcharset123456789").is_none());
    }
    #[test]
    fn filename_charsets() {
        let _ = super::filename_charsets();
    }

    #[test]
    fn utf8_and_utf32() {
        let utf32 = ['A', 'b', '🤔'];
        let utf8 = super::utf32_to_utf8(utf32);
        assert_eq!(utf8, "Ab🤔");

        let utf8 = "🤔 ț";
        let utf32 = super::utf8_to_utf32(utf8);
        assert_eq!(utf32.as_slice(), &['🤔', ' ', 'ț']);
    }
}