glib/
convert.rs

1// Take a look at the license at the top of the repository in the LICENSE file.
2
3use std::{fmt, io, os::raw::c_char, path::PathBuf, ptr};
4
5use crate::{ffi, translate::*, ConvertError, Error, GString, NormalizeMode, Slice};
6
7// rustdoc-stripper-ignore-next
8/// A wrapper for [`ConvertError`](crate::ConvertError) that can hold an offset into the input
9/// string.
10#[derive(Debug)]
11pub enum CvtError {
12    Convert(Error),
13    IllegalSequence { source: Error, offset: usize },
14}
15
16impl std::error::Error for CvtError {
17    fn source(&self) -> ::core::option::Option<&(dyn std::error::Error + 'static)> {
18        match self {
19            CvtError::Convert(err) => std::error::Error::source(err),
20            CvtError::IllegalSequence { source, .. } => Some(source),
21        }
22    }
23}
24
25impl fmt::Display for CvtError {
26    fn fmt(&self, fmt: &mut fmt::Formatter) -> ::core::fmt::Result {
27        match self {
28            CvtError::Convert(err) => fmt::Display::fmt(err, fmt),
29            CvtError::IllegalSequence { source, offset } => {
30                write!(fmt, "{source} at offset {offset}")
31            }
32        }
33    }
34}
35
36impl std::convert::From<Error> for CvtError {
37    fn from(err: Error) -> Self {
38        CvtError::Convert(err)
39    }
40}
41
42impl CvtError {
43    #[inline]
44    fn new(err: Error, bytes_read: usize) -> Self {
45        if err.kind::<ConvertError>() == Some(ConvertError::IllegalSequence) {
46            Self::IllegalSequence {
47                source: err,
48                offset: bytes_read,
49            }
50        } else {
51            err.into()
52        }
53    }
54}
55
56/// Converts a string from one character set to another.
57///
58/// Note that you should use g_iconv() for streaming conversions.
59/// Despite the fact that @bytes_read can return information about partial
60/// characters, the g_convert_... functions are not generally suitable
61/// for streaming. If the underlying converter maintains internal state,
62/// then this won't be preserved across successive calls to g_convert(),
63/// g_convert_with_iconv() or g_convert_with_fallback(). (An example of
64/// this is the GNU C converter for CP1255 which does not emit a base
65/// character until it knows that the next character is not a mark that
66/// could combine with the base character.)
67///
68/// Using extensions such as "//TRANSLIT" may not work (or may not work
69/// well) on many platforms.  Consider using g_str_to_ascii() instead.
70/// ## `str`
71///
72///                 the string to convert.
73/// ## `to_codeset`
74/// name of character set into which to convert @str
75/// ## `from_codeset`
76/// character set of @str.
77///
78/// # Returns
79///
80///
81///          If the conversion was successful, a newly allocated buffer
82///          containing the converted string, which must be freed with g_free().
83///          Otherwise [`None`] and @error will be set.
84///
85/// ## `bytes_read`
86/// location to store the number of bytes in
87///                 the input string that were successfully converted, or [`None`].
88///                 Even if the conversion was successful, this may be
89///                 less than @len if there were partial characters
90///                 at the end of the input. If the error
91///                 [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence] occurs, the value
92///                 stored will be the byte offset after the last valid
93///                 input sequence.
94#[doc(alias = "g_convert")]
95pub fn convert(
96    str_: &[u8],
97    to_codeset: impl IntoGStr,
98    from_codeset: impl IntoGStr,
99) -> Result<(Slice<u8>, usize), CvtError> {
100    assert!(str_.len() <= isize::MAX as usize);
101    let mut bytes_read = 0;
102    let mut bytes_written = 0;
103    let mut error = ptr::null_mut();
104    let result = to_codeset.run_with_gstr(|to_codeset| {
105        from_codeset.run_with_gstr(|from_codeset| unsafe {
106            ffi::g_convert(
107                str_.as_ptr(),
108                str_.len() as isize,
109                to_codeset.to_glib_none().0,
110                from_codeset.to_glib_none().0,
111                &mut bytes_read,
112                &mut bytes_written,
113                &mut error,
114            )
115        })
116    });
117    if result.is_null() {
118        Err(CvtError::new(unsafe { from_glib_full(error) }, bytes_read))
119    } else {
120        let slice = unsafe { Slice::from_glib_full_num(result, bytes_written as _) };
121        Ok((slice, bytes_read))
122    }
123}
124
125/// Converts a string from one character set to another, possibly
126/// including fallback sequences for characters not representable
127/// in the output. Note that it is not guaranteed that the specification
128/// for the fallback sequences in @fallback will be honored. Some
129/// systems may do an approximate conversion from @from_codeset
130/// to @to_codeset in their iconv() functions,
131/// in which case GLib will simply return that approximate conversion.
132///
133/// Note that you should use g_iconv() for streaming conversions.
134/// Despite the fact that @bytes_read can return information about partial
135/// characters, the g_convert_... functions are not generally suitable
136/// for streaming. If the underlying converter maintains internal state,
137/// then this won't be preserved across successive calls to g_convert(),
138/// g_convert_with_iconv() or g_convert_with_fallback(). (An example of
139/// this is the GNU C converter for CP1255 which does not emit a base
140/// character until it knows that the next character is not a mark that
141/// could combine with the base character.)
142/// ## `str`
143///
144///                the string to convert.
145/// ## `to_codeset`
146/// name of character set into which to convert @str
147/// ## `from_codeset`
148/// character set of @str.
149/// ## `fallback`
150/// UTF-8 string to use in place of characters not
151///                present in the target encoding. (The string must be
152///                representable in the target encoding).
153///                If [`None`], characters not in the target encoding will
154///                be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
155///
156/// # Returns
157///
158///
159///          If the conversion was successful, a newly allocated buffer
160///          containing the converted string, which must be freed with g_free().
161///          Otherwise [`None`] and @error will be set.
162///
163/// ## `bytes_read`
164/// location to store the number of bytes in
165///                the input string that were successfully converted, or [`None`].
166///                Even if the conversion was successful, this may be
167///                less than @len if there were partial characters
168///                at the end of the input.
169#[doc(alias = "g_convert_with_fallback")]
170pub fn convert_with_fallback(
171    str_: &[u8],
172    to_codeset: impl IntoGStr,
173    from_codeset: impl IntoGStr,
174    fallback: Option<impl IntoGStr>,
175) -> Result<(Slice<u8>, usize), CvtError> {
176    assert!(str_.len() <= isize::MAX as usize);
177    let mut bytes_read = 0;
178    let mut bytes_written = 0;
179    let mut error = ptr::null_mut();
180    let result = to_codeset.run_with_gstr(|to_codeset| {
181        from_codeset.run_with_gstr(|from_codeset| {
182            fallback.run_with_gstr(|fallback| unsafe {
183                ffi::g_convert_with_fallback(
184                    str_.as_ptr(),
185                    str_.len() as isize,
186                    to_codeset.to_glib_none().0,
187                    from_codeset.to_glib_none().0,
188                    fallback.to_glib_none().0,
189                    &mut bytes_read,
190                    &mut bytes_written,
191                    &mut error,
192                )
193            })
194        })
195    });
196    if result.is_null() {
197        Err(CvtError::new(unsafe { from_glib_full(error) }, bytes_read))
198    } else {
199        let slice = unsafe { Slice::from_glib_full_num(result, bytes_written as _) };
200        Ok((slice, bytes_read))
201    }
202}
203
204// rustdoc-stripper-ignore-next
205/// A wrapper for [`std::io::Error`] that can hold an offset into an input string.
206#[derive(Debug)]
207pub enum IConvError {
208    Error(io::Error),
209    WithOffset { source: io::Error, offset: usize },
210}
211
212impl std::error::Error for IConvError {
213    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
214        match self {
215            IConvError::Error(err) => std::error::Error::source(err),
216            IConvError::WithOffset { source, .. } => Some(source),
217        }
218    }
219}
220
221impl fmt::Display for IConvError {
222    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
223        match self {
224            IConvError::Error(err) => fmt::Display::fmt(err, fmt),
225            IConvError::WithOffset { source, offset } => write!(fmt, "{source} at offset {offset}"),
226        }
227    }
228}
229
230impl std::convert::From<io::Error> for IConvError {
231    fn from(err: io::Error) -> Self {
232        IConvError::Error(err)
233    }
234}
235
236/// The GIConv struct wraps an iconv() conversion descriptor. It contains
237/// private data and should only be accessed using the following functions.
238#[derive(Debug)]
239#[repr(transparent)]
240#[doc(alias = "GIConv")]
241pub struct IConv(ffi::GIConv);
242
243unsafe impl Send for IConv {}
244
245impl IConv {
246    /// Same as the standard UNIX routine iconv_open(), but
247    /// may be implemented via libiconv on UNIX flavors that lack
248    /// a native implementation.
249    ///
250    /// GLib provides g_convert() and g_locale_to_utf8() which are likely
251    /// more convenient than the raw iconv wrappers.
252    /// ## `to_codeset`
253    /// destination codeset
254    /// ## `from_codeset`
255    /// source codeset
256    ///
257    /// # Returns
258    ///
259    /// a "conversion descriptor", or (GIConv)-1 if
260    ///  opening the converter failed.
261    #[doc(alias = "g_iconv_open")]
262    #[allow(clippy::unnecessary_lazy_evaluations)]
263    pub fn new(to_codeset: impl IntoGStr, from_codeset: impl IntoGStr) -> Option<Self> {
264        let iconv = to_codeset.run_with_gstr(|to_codeset| {
265            from_codeset.run_with_gstr(|from_codeset| unsafe {
266                ffi::g_iconv_open(to_codeset.to_glib_none().0, from_codeset.to_glib_none().0)
267            })
268        });
269        (iconv as isize != -1).then(|| Self(iconv))
270    }
271    /// Converts a string from one character set to another.
272    ///
273    /// Note that you should use g_iconv() for streaming conversions.
274    /// Despite the fact that @bytes_read can return information about partial
275    /// characters, the g_convert_... functions are not generally suitable
276    /// for streaming. If the underlying converter maintains internal state,
277    /// then this won't be preserved across successive calls to g_convert(),
278    /// g_convert_with_iconv() or g_convert_with_fallback(). (An example of
279    /// this is the GNU C converter for CP1255 which does not emit a base
280    /// character until it knows that the next character is not a mark that
281    /// could combine with the base character.)
282    ///
283    /// Characters which are valid in the input character set, but which have no
284    /// representation in the output character set will result in a
285    /// [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence] error. This is in contrast to the iconv()
286    /// specification, which leaves this behaviour implementation defined. Note that
287    /// this is the same error code as is returned for an invalid byte sequence in
288    /// the input character set. To get defined behaviour for conversion of
289    /// unrepresentable characters, use g_convert_with_fallback().
290    /// ## `str`
291    ///
292    ///                 the string to convert.
293    /// ## `converter`
294    /// conversion descriptor from g_iconv_open()
295    ///
296    /// # Returns
297    ///
298    ///
299    ///               If the conversion was successful, a newly allocated buffer
300    ///               containing the converted string, which must be freed with
301    ///               g_free(). Otherwise [`None`] and @error will be set.
302    ///
303    /// ## `bytes_read`
304    /// location to store the number of bytes in
305    ///                 the input string that were successfully converted, or [`None`].
306    ///                 Even if the conversion was successful, this may be
307    ///                 less than @len if there were partial characters
308    ///                 at the end of the input. If the error
309    ///                 [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence] occurs, the value
310    ///                 stored will be the byte offset after the last valid
311    ///                 input sequence.
312    #[doc(alias = "g_convert_with_iconv")]
313    pub fn convert(&mut self, str_: &[u8]) -> Result<(Slice<u8>, usize), CvtError> {
314        assert!(str_.len() <= isize::MAX as usize);
315        let mut bytes_read = 0;
316        let mut bytes_written = 0;
317        let mut error = ptr::null_mut();
318        let result = unsafe {
319            ffi::g_convert_with_iconv(
320                str_.as_ptr(),
321                str_.len() as isize,
322                self.0,
323                &mut bytes_read,
324                &mut bytes_written,
325                &mut error,
326            )
327        };
328        if result.is_null() {
329            Err(CvtError::new(unsafe { from_glib_full(error) }, bytes_read))
330        } else {
331            let slice = unsafe { Slice::from_glib_full_num(result, bytes_written as _) };
332            Ok((slice, bytes_read))
333        }
334    }
335    /// Same as the standard UNIX routine iconv(), but
336    /// may be implemented via libiconv on UNIX flavors that lack
337    /// a native implementation.
338    ///
339    /// GLib provides g_convert() and g_locale_to_utf8() which are likely
340    /// more convenient than the raw iconv wrappers.
341    ///
342    /// Note that the behaviour of iconv() for characters which are valid in the
343    /// input character set, but which have no representation in the output character
344    /// set, is implementation defined. This function may return success (with a
345    /// positive number of non-reversible conversions as replacement characters were
346    /// used), or it may return -1 and set an error such as `EILSEQ`, in such a
347    /// situation.
348    /// ## `converter`
349    /// conversion descriptor from g_iconv_open()
350    /// ## `inbuf`
351    /// bytes to convert
352    /// ## `inbytes_left`
353    /// inout parameter, bytes remaining to convert in @inbuf
354    /// ## `outbuf`
355    /// converted output bytes
356    /// ## `outbytes_left`
357    /// inout parameter, bytes available to fill in @outbuf
358    ///
359    /// # Returns
360    ///
361    /// count of non-reversible conversions, or -1 on error
362    #[doc(alias = "g_iconv")]
363    pub fn iconv(
364        &mut self,
365        inbuf: Option<&[u8]>,
366        outbuf: Option<&mut [std::mem::MaybeUninit<u8>]>,
367    ) -> Result<(usize, usize, usize), IConvError> {
368        let input_len = inbuf.as_ref().map(|b| b.len()).unwrap_or_default();
369        let mut inbytes_left = input_len;
370        let mut outbytes_left = outbuf.as_ref().map(|b| b.len()).unwrap_or_default();
371        let mut inbuf = inbuf
372            .map(|b| mut_override(b.as_ptr()) as *mut c_char)
373            .unwrap_or_else(ptr::null_mut);
374        let mut outbuf = outbuf
375            .map(|b| b.as_mut_ptr() as *mut c_char)
376            .unwrap_or_else(ptr::null_mut);
377        let conversions = unsafe {
378            ffi::g_iconv(
379                self.0,
380                &mut inbuf,
381                &mut inbytes_left,
382                &mut outbuf,
383                &mut outbytes_left,
384            )
385        };
386        if conversions as isize == -1 {
387            let err = io::Error::last_os_error();
388            let code = err.raw_os_error().unwrap();
389            if code == libc::EILSEQ || code == libc::EINVAL {
390                Err(IConvError::WithOffset {
391                    source: err,
392                    offset: input_len - inbytes_left,
393                })
394            } else {
395                Err(err.into())
396            }
397        } else {
398            Ok((conversions, inbytes_left, outbytes_left))
399        }
400    }
401}
402
403impl Drop for IConv {
404    #[inline]
405    fn drop(&mut self) {
406        unsafe {
407            ffi::g_iconv_close(self.0);
408        }
409    }
410}
411
412/// Determines the preferred character sets used for filenames.
413/// The first character set from the @charsets is the filename encoding, the
414/// subsequent character sets are used when trying to generate a displayable
415/// representation of a filename, see g_filename_display_name().
416///
417/// On Unix, the character sets are determined by consulting the
418/// environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`.
419/// On Windows, the character set used in the GLib API is always UTF-8
420/// and said environment variables have no effect.
421///
422/// `G_FILENAME_ENCODING` may be set to a comma-separated list of
423/// character set names. The special token `@locale` is taken to mean the
424/// character set for the [current locale](running.html#locale).
425/// If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is,
426/// the character set of the current locale is taken as the filename
427/// encoding. If neither environment variable  is set, UTF-8 is taken
428/// as the filename encoding, but the character set of the current locale
429/// is also put in the list of encodings.
430///
431/// The returned @charsets belong to GLib and must not be freed.
432///
433/// Note that on Unix, regardless of the locale character set or
434/// `G_FILENAME_ENCODING` value, the actual file names present
435/// on a system might be in any random encoding or just gibberish.
436///
437/// # Returns
438///
439/// [`true`] if the filename encoding is UTF-8.
440///
441/// ## `filename_charsets`
442///
443///    return location for the [`None`]-terminated list of encoding names
444#[doc(alias = "g_get_filename_charsets")]
445#[doc(alias = "get_filename_charsets")]
446pub fn filename_charsets() -> (bool, Vec<GString>) {
447    let mut filename_charsets = ptr::null_mut();
448    unsafe {
449        let is_utf8 = ffi::g_get_filename_charsets(&mut filename_charsets);
450        (
451            from_glib(is_utf8),
452            FromGlibPtrContainer::from_glib_none(filename_charsets),
453        )
454    }
455}
456
457/// Converts a string from UTF-8 to the encoding GLib uses for
458/// filenames. Note that on Windows GLib uses UTF-8 for filenames;
459/// on other platforms, this function indirectly depends on the
460/// [current locale](running.html#locale).
461///
462/// The input string shall not contain nul characters even if the @len
463/// argument is positive. A nul character found inside the string will result
464/// in error [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence]. If the filename encoding is
465/// not UTF-8 and the conversion output contains a nul character, the error
466/// [`ConvertError::EmbeddedNul`][crate::ConvertError::EmbeddedNul] is set and the function returns [`None`].
467/// ## `utf8string`
468/// a UTF-8 encoded string.
469/// ## `len`
470/// the length of the string, or -1 if the string is
471///                 nul-terminated.
472///
473/// # Returns
474///
475///
476///               The converted string, or [`None`] on an error.
477///
478/// ## `bytes_read`
479/// location to store the number of bytes in
480///                 the input string that were successfully converted, or [`None`].
481///                 Even if the conversion was successful, this may be
482///                 less than @len if there were partial characters
483///                 at the end of the input. If the error
484///                 [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence] occurs, the value
485///                 stored will be the byte offset after the last valid
486///                 input sequence.
487///
488/// ## `bytes_written`
489/// the number of bytes stored in
490///                 the output buffer (not including the terminating nul).
491#[doc(alias = "g_filename_from_utf8")]
492pub fn filename_from_utf8(utf8string: impl IntoGStr) -> Result<(PathBuf, usize), CvtError> {
493    let mut bytes_read = 0;
494    let mut bytes_written = std::mem::MaybeUninit::uninit();
495    let mut error = ptr::null_mut();
496    let ret = utf8string.run_with_gstr(|utf8string| {
497        assert!(utf8string.len() <= isize::MAX as usize);
498        let len = utf8string.len() as isize;
499        unsafe {
500            ffi::g_filename_from_utf8(
501                utf8string.to_glib_none().0,
502                len,
503                &mut bytes_read,
504                bytes_written.as_mut_ptr(),
505                &mut error,
506            )
507        }
508    });
509    if error.is_null() {
510        Ok(unsafe {
511            (
512                PathBuf::from_glib_full_num(ret, bytes_written.assume_init()),
513                bytes_read,
514            )
515        })
516    } else {
517        Err(unsafe { CvtError::new(from_glib_full(error), bytes_read) })
518    }
519}
520
521/// Converts a string which is in the encoding used by GLib for
522/// filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
523/// for filenames; on other platforms, this function indirectly depends on
524/// the [current locale](running.html#locale).
525///
526/// The input string shall not contain nul characters even if the @len
527/// argument is positive. A nul character found inside the string will result
528/// in error [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence].
529/// If the source encoding is not UTF-8 and the conversion output contains a
530/// nul character, the error [`ConvertError::EmbeddedNul`][crate::ConvertError::EmbeddedNul] is set and the
531/// function returns [`None`]. Use g_convert() to produce output that
532/// may contain embedded nul characters.
533/// ## `opsysstring`
534/// a string in the encoding for filenames
535/// ## `len`
536/// the length of the string, or -1 if the string is
537///                 nul-terminated (Note that some encodings may allow nul
538///                 bytes to occur inside strings. In that case, using -1
539///                 for the @len parameter is unsafe)
540///
541/// # Returns
542///
543/// The converted string, or [`None`] on an error.
544///
545/// ## `bytes_read`
546/// location to store the number of bytes in the
547///                 input string that were successfully converted, or [`None`].
548///                 Even if the conversion was successful, this may be
549///                 less than @len if there were partial characters
550///                 at the end of the input. If the error
551///                 [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence] occurs, the value
552///                 stored will be the byte offset after the last valid
553///                 input sequence.
554///
555/// ## `bytes_written`
556/// the number of bytes stored in the output
557///                 buffer (not including the terminating nul).
558#[doc(alias = "g_filename_to_utf8")]
559pub fn filename_to_utf8(
560    opsysstring: impl AsRef<std::path::Path>,
561) -> Result<(crate::GString, usize), CvtError> {
562    let path = opsysstring.as_ref().to_glib_none();
563    let mut bytes_read = 0;
564    let mut bytes_written = std::mem::MaybeUninit::uninit();
565    let mut error = ptr::null_mut();
566    let ret = unsafe {
567        ffi::g_filename_to_utf8(
568            path.0,
569            path.1.as_bytes().len() as isize,
570            &mut bytes_read,
571            bytes_written.as_mut_ptr(),
572            &mut error,
573        )
574    };
575    if error.is_null() {
576        Ok(unsafe {
577            (
578                GString::from_glib_full_num(ret, bytes_written.assume_init()),
579                bytes_read,
580            )
581        })
582    } else {
583        Err(unsafe { CvtError::new(from_glib_full(error), bytes_read) })
584    }
585}
586
587/// Converts a string from UTF-8 to the encoding used for strings by
588/// the C runtime (usually the same as that used by the operating
589/// system) in the [current locale](running.html#locale).
590/// On Windows this means the system codepage.
591///
592/// The input string shall not contain nul characters even if the @len
593/// argument is positive. A nul character found inside the string will result
594/// in error [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence]. Use g_convert() to convert
595/// input that may contain embedded nul characters.
596/// ## `utf8string`
597/// a UTF-8 encoded string
598/// ## `len`
599/// the length of the string, or -1 if the string is
600///                 nul-terminated.
601///
602/// # Returns
603///
604///
605///          A newly-allocated buffer containing the converted string,
606///          or [`None`] on an error, and error will be set.
607///
608/// ## `bytes_read`
609/// location to store the number of bytes in the
610///                 input string that were successfully converted, or [`None`].
611///                 Even if the conversion was successful, this may be
612///                 less than @len if there were partial characters
613///                 at the end of the input. If the error
614///                 [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence] occurs, the value
615///                 stored will be the byte offset after the last valid
616///                 input sequence.
617#[doc(alias = "g_locale_from_utf8")]
618pub fn locale_from_utf8(utf8string: impl IntoGStr) -> Result<(Slice<u8>, usize), CvtError> {
619    let mut bytes_read = 0;
620    let mut bytes_written = std::mem::MaybeUninit::uninit();
621    let mut error = ptr::null_mut();
622    let ret = utf8string.run_with_gstr(|utf8string| {
623        assert!(utf8string.len() <= isize::MAX as usize);
624        unsafe {
625            ffi::g_locale_from_utf8(
626                utf8string.as_ptr(),
627                utf8string.len() as isize,
628                &mut bytes_read,
629                bytes_written.as_mut_ptr(),
630                &mut error,
631            )
632        }
633    });
634    if error.is_null() {
635        Ok(unsafe {
636            (
637                Slice::from_glib_full_num(ret, bytes_written.assume_init() + 1),
638                bytes_read,
639            )
640        })
641    } else {
642        Err(unsafe { CvtError::new(from_glib_full(error), bytes_read) })
643    }
644}
645
646/// Converts a string which is in the encoding used for strings by
647/// the C runtime (usually the same as that used by the operating
648/// system) in the [current locale](running.html#locale) into a UTF-8 string.
649///
650/// If the source encoding is not UTF-8 and the conversion output contains a
651/// nul character, the error [`ConvertError::EmbeddedNul`][crate::ConvertError::EmbeddedNul] is set and the
652/// function returns [`None`].
653/// If the source encoding is UTF-8, an embedded nul character is treated with
654/// the [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence] error for backward compatibility with
655/// earlier versions of this library. Use g_convert() to produce output that
656/// may contain embedded nul characters.
657/// ## `opsysstring`
658/// a string in the
659///                 encoding of the current locale. On Windows
660///                 this means the system codepage.
661///
662/// # Returns
663///
664/// The converted string, or [`None`] on an error.
665///
666/// ## `bytes_read`
667/// location to store the number of bytes in the
668///                 input string that were successfully converted, or [`None`].
669///                 Even if the conversion was successful, this may be
670///                 less than @len if there were partial characters
671///                 at the end of the input. If the error
672///                 [`ConvertError::IllegalSequence`][crate::ConvertError::IllegalSequence] occurs, the value
673///                 stored will be the byte offset after the last valid
674///                 input sequence.
675///
676/// ## `bytes_written`
677/// the number of bytes stored in the output
678///                 buffer (not including the terminating nul).
679#[doc(alias = "g_locale_to_utf8")]
680pub fn locale_to_utf8(opsysstring: &[u8]) -> Result<(crate::GString, usize), CvtError> {
681    let len = opsysstring.len() as isize;
682    let mut bytes_read = 0;
683    let mut bytes_written = std::mem::MaybeUninit::uninit();
684    let mut error = ptr::null_mut();
685    let ret = unsafe {
686        ffi::g_locale_to_utf8(
687            opsysstring.to_glib_none().0,
688            len,
689            &mut bytes_read,
690            bytes_written.as_mut_ptr(),
691            &mut error,
692        )
693    };
694    if error.is_null() {
695        Ok(unsafe {
696            (
697                GString::from_glib_full_num(ret, bytes_written.assume_init()),
698                bytes_read,
699            )
700        })
701    } else {
702        Err(unsafe { CvtError::new(from_glib_full(error), bytes_read) })
703    }
704}
705
706#[doc(alias = "g_utf8_to_ucs4")]
707#[doc(alias = "g_utf8_to_ucs4_fast")]
708#[doc(alias = "utf8_to_ucs4")]
709pub fn utf8_to_utf32(str: impl AsRef<str>) -> Slice<char> {
710    unsafe {
711        let mut items_written = 0;
712
713        let str_as_utf32 = ffi::g_utf8_to_ucs4_fast(
714            str.as_ref().as_ptr().cast::<c_char>(),
715            str.as_ref().len() as _,
716            &mut items_written,
717        );
718
719        // NOTE: We assume that u32 and char have the same layout and trust that glib won't give us
720        //       invalid UTF-32 codepoints
721        Slice::from_glib_full_num(str_as_utf32, items_written as usize)
722    }
723}
724
725#[doc(alias = "g_ucs4_to_utf8")]
726#[doc(alias = "ucs4_to_utf8")]
727pub fn utf32_to_utf8(str: impl AsRef<[char]>) -> GString {
728    let mut items_read = 0;
729    let mut items_written = 0;
730    let mut error = ptr::null_mut();
731
732    unsafe {
733        let str_as_utf8 = ffi::g_ucs4_to_utf8(
734            str.as_ref().as_ptr().cast::<u32>(),
735            str.as_ref().len() as _,
736            &mut items_read,
737            &mut items_written,
738            &mut error,
739        );
740
741        debug_assert!(
742            error.is_null(),
743            "Rust `char` should always be convertible to UTF-8"
744        );
745
746        GString::from_glib_full_num(str_as_utf8, items_written as usize)
747    }
748}
749
750#[doc(alias = "g_utf8_casefold")]
751#[doc(alias = "utf8_casefold")]
752pub fn casefold(str: impl AsRef<str>) -> GString {
753    unsafe {
754        let str = ffi::g_utf8_casefold(str.as_ref().as_ptr().cast(), str.as_ref().len() as isize);
755
756        from_glib_full(str)
757    }
758}
759
760#[doc(alias = "g_utf8_normalize")]
761#[doc(alias = "utf8_normalize")]
762pub fn normalize(str: impl AsRef<str>, mode: NormalizeMode) -> GString {
763    unsafe {
764        let str = ffi::g_utf8_normalize(
765            str.as_ref().as_ptr().cast(),
766            str.as_ref().len() as isize,
767            mode.into_glib(),
768        );
769
770        from_glib_full(str)
771    }
772}
773
774#[cfg(test)]
775mod tests {
776    #[test]
777    fn convert_ascii() {
778        assert!(super::convert(b"Hello", "utf-8", "ascii").is_ok());
779        assert!(super::convert(b"He\xaallo", "utf-8", "ascii").is_err());
780        assert_eq!(
781            super::convert_with_fallback(b"H\xc3\xa9llo", "ascii", "utf-8", crate::NONE_STR)
782                .unwrap()
783                .0
784                .as_slice(),
785            b"H\\u00e9llo"
786        );
787        assert_eq!(
788            super::convert_with_fallback(b"H\xc3\xa9llo", "ascii", "utf-8", Some("_"))
789                .unwrap()
790                .0
791                .as_slice(),
792            b"H_llo"
793        );
794    }
795    #[test]
796    fn iconv() {
797        let mut conv = super::IConv::new("utf-8", "ascii").unwrap();
798        assert!(conv.convert(b"Hello").is_ok());
799        assert!(conv.convert(b"He\xaallo").is_err());
800        assert!(super::IConv::new("utf-8", "badcharset123456789").is_none());
801    }
802    #[test]
803    fn filename_charsets() {
804        let _ = super::filename_charsets();
805    }
806
807    #[test]
808    fn utf8_and_utf32() {
809        let utf32 = ['A', 'b', '🤔'];
810        let utf8 = super::utf32_to_utf8(utf32);
811        assert_eq!(utf8, "Ab🤔");
812
813        let utf8 = "🤔 ț";
814        let utf32 = super::utf8_to_utf32(utf8);
815        assert_eq!(utf32.as_slice(), &['🤔', ' ', 'ț']);
816    }
817}