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}