Debian Codegraph @

.cargo/vendor/widestring/src/ustr.rs

raw
1 //! Wide string slices with undefined encoding.
2 //!
3 //! This module contains wide string slices and related types.
4
5 #[cfg(feature = "alloc")]
6 use crate::{
7 error::{Utf16Error, Utf32Error},
8 U16String, U32String,
9 };
10 #[cfg(feature = "alloc")]
11 #[allow(unused_imports)]
12 use alloc::{boxed::Box, string::String, vec::Vec};
13 use core::{
14 char,
15 fmt::Write,
16 ops::{Index, IndexMut, Range},
17 slice::{self, SliceIndex},
18 };
19
20 mod iter;
21
22 pub use iter::*;
23
24 macro_rules! ustr_common_impl {
25 {
26 $(#[$ustr_meta:meta])*
27 struct $ustr:ident([$uchar:ty]);
28 type UString = $ustring:ident;
29 type UCStr = $ucstr:ident;
30 $(#[$display_meta:meta])*
31 fn display() -> {}
32 } => {
33 $(#[$ustr_meta])*
34 #[allow(clippy::derive_hash_xor_eq)]
35 #[derive(PartialEq, Eq, PartialOrd, Ord, Hash)]
36 pub struct $ustr {
37 pub(crate) inner: [$uchar],
38 }
39
40 impl $ustr {
41 /// Coerces a value into a wide string slice.
42 #[inline]
43 #[must_use]
44 pub fn new<S: AsRef<Self> + ?Sized>(s: &S) -> &Self {
45 s.as_ref()
46 }
47
48 /// Constructs a wide string slice from a pointer and a length.
49 ///
50 /// The `len` argument is the number of elements, **not** the number of bytes. No
51 /// copying or allocation is performed, the resulting value is a direct reference to the
52 /// pointer bytes.
53 ///
54 /// # Safety
55 ///
56 /// This function is unsafe as there is no guarantee that the given pointer is valid for
57 /// `len` elements.
58 ///
59 /// In addition, the data must meet the safety conditions of
60 /// [std::slice::from_raw_parts]. In particular, the returned string reference *must not
61 /// be mutated* for the duration of lifetime `'a`, except inside an
62 /// [`UnsafeCell`][std::cell::UnsafeCell].
63 ///
64 /// # Panics
65 ///
66 /// This function panics if `p` is null.
67 ///
68 /// # Caveat
69 ///
70 /// The lifetime for the returned string is inferred from its usage. To prevent
71 /// accidental misuse, it's suggested to tie the lifetime to whichever source lifetime
72 /// is safe in the context, such as by providing a helper function taking the lifetime
73 /// of a host value for the string, or by explicit annotation.
74 #[inline]
75 #[must_use]
76 pub unsafe fn from_ptr<'a>(p: *const $uchar, len: usize) -> &'a Self {
77 assert!(!p.is_null());
78 let slice: *const [$uchar] = slice::from_raw_parts(p, len);
79 &*(slice as *const $ustr)
80 }
81
82 /// Constructs a mutable wide string slice from a mutable pointer and a length.
83 ///
84 /// The `len` argument is the number of elements, **not** the number of bytes. No
85 /// copying or allocation is performed, the resulting value is a direct reference to the
86 /// pointer bytes.
87 ///
88 /// # Safety
89 ///
90 /// This function is unsafe as there is no guarantee that the given pointer is valid for
91 /// `len` elements.
92 ///
93 /// In addition, the data must meet the safety conditions of
94 /// [std::slice::from_raw_parts_mut].
95 ///
96 /// # Panics
97 ///
98 /// This function panics if `p` is null.
99 ///
100 /// # Caveat
101 ///
102 /// The lifetime for the returned string is inferred from its usage. To prevent
103 /// accidental misuse, it's suggested to tie the lifetime to whichever source lifetime
104 /// is safe in the context, such as by providing a helper function taking the lifetime
105 /// of a host value for the string, or by explicit annotation.
106 #[inline]
107 #[must_use]
108 pub unsafe fn from_ptr_mut<'a>(p: *mut $uchar, len: usize) -> &'a mut Self {
109 assert!(!p.is_null());
110 let slice: *mut [$uchar] = slice::from_raw_parts_mut(p, len);
111 &mut *(slice as *mut $ustr)
112 }
113
114 /// Constructs a wide string slice from a slice of character data.
115 ///
116 /// No checks are performed on the slice. It may be of any encoding and may contain
117 /// invalid or malformed data for that encoding.
118 #[inline]
119 #[must_use]
120 pub const fn from_slice(slice: &[$uchar]) -> &Self {
121 let ptr: *const [$uchar] = slice;
122 unsafe { &*(ptr as *const $ustr) }
123 }
124
125 /// Constructs a mutable wide string slice from a mutable slice of character data.
126 ///
127 /// No checks are performed on the slice. It may be of any encoding and may contain
128 /// invalid or malformed data for that encoding.
129 #[inline]
130 #[must_use]
131 pub fn from_slice_mut(slice: &mut [$uchar]) -> &mut Self {
132 let ptr: *mut [$uchar] = slice;
133 unsafe { &mut *(ptr as *mut $ustr) }
134 }
135
136 /// Copies the string reference to a new owned wide string.
137 #[cfg(feature = "alloc")]
138 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
139 #[inline]
140 #[must_use]
141 pub fn to_ustring(&self) -> $ustring {
142 $ustring::from_vec(&self.inner)
143 }
144
145 /// Converts to a slice of the underlying elements of the string.
146 #[inline]
147 #[must_use]
148 pub const fn as_slice(&self) -> &[$uchar] {
149 &self.inner
150 }
151
152 /// Converts to a mutable slice of the underlying elements of the string.
153 #[must_use]
154 pub fn as_mut_slice(&mut self) -> &mut [$uchar] {
155 &mut self.inner
156 }
157
158 /// Returns a raw pointer to the string.
159 ///
160 /// The caller must ensure that the string outlives the pointer this function returns,
161 /// or else it will end up pointing to garbage.
162 ///
163 /// The caller must also ensure that the memory the pointer (non-transitively) points to
164 /// is never written to (except inside an `UnsafeCell`) using this pointer or any
165 /// pointer derived from it. If you need to mutate the contents of the string, use
166 /// [`as_mut_ptr`][Self::as_mut_ptr].
167 ///
168 /// Modifying the container referenced by this string may cause its buffer to be
169 /// reallocated, which would also make any pointers to it invalid.
170 #[inline]
171 #[must_use]
172 pub const fn as_ptr(&self) -> *const $uchar {
173 self.inner.as_ptr()
174 }
175
176 /// Returns an unsafe mutable raw pointer to the string.
177 ///
178 /// The caller must ensure that the string outlives the pointer this function returns,
179 /// or else it will end up pointing to garbage.
180 ///
181 /// Modifying the container referenced by this string may cause its buffer to be
182 /// reallocated, which would also make any pointers to it invalid.
183 #[inline]
184 #[must_use]
185 pub fn as_mut_ptr(&mut self) -> *mut $uchar {
186 self.inner.as_mut_ptr()
187 }
188
189 /// Returns the two raw pointers spanning the string slice.
190 ///
191 /// The returned range is half-open, which means that the end pointer points one past
192 /// the last element of the slice. This way, an empty slice is represented by two equal
193 /// pointers, and the difference between the two pointers represents the size of the
194 /// slice.
195 ///
196 /// See [`as_ptr`][Self::as_ptr] for warnings on using these pointers. The end pointer
197 /// requires extra caution, as it does not point to a valid element in the slice.
198 ///
199 /// This function is useful for interacting with foreign interfaces which use two
200 /// pointers to refer to a range of elements in memory, as is common in C++.
201 #[inline]
202 #[must_use]
203 pub fn as_ptr_range(&self) -> Range<*const $uchar> {
204 self.inner.as_ptr_range()
205 }
206
207 /// Returns the two unsafe mutable pointers spanning the string slice.
208 ///
209 /// The returned range is half-open, which means that the end pointer points one past
210 /// the last element of the slice. This way, an empty slice is represented by two equal
211 /// pointers, and the difference between the two pointers represents the size of the
212 /// slice.
213 ///
214 /// See [`as_mut_ptr`][Self::as_mut_ptr] for warnings on using these pointers. The end
215 /// pointer requires extra caution, as it does not point to a valid element in the
216 /// slice.
217 ///
218 /// This function is useful for interacting with foreign interfaces which use two
219 /// pointers to refer to a range of elements in memory, as is common in C++.
220 #[inline]
221 #[must_use]
222 pub fn as_mut_ptr_range(&mut self) -> Range<*mut $uchar> {
223 self.inner.as_mut_ptr_range()
224 }
225
226 /// Returns the length of the string as number of elements (**not** number of bytes).
227 #[inline]
228 #[must_use]
229 pub const fn len(&self) -> usize {
230 self.inner.len()
231 }
232
233 /// Returns whether this string contains no data.
234 #[inline]
235 #[must_use]
236 pub const fn is_empty(&self) -> bool {
237 self.inner.is_empty()
238 }
239
240 /// Converts a boxed wide string slice into an owned wide string without copying or
241 /// allocating.
242 #[cfg(feature = "alloc")]
243 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
244 #[must_use]
245 pub fn into_ustring(self: Box<Self>) -> $ustring {
246 let boxed = unsafe { Box::from_raw(Box::into_raw(self) as *mut [$uchar]) };
247 $ustring {
248 inner: boxed.into_vec(),
249 }
250 }
251
252 $(#[$display_meta])*
253 #[inline]
254 #[must_use]
255 pub fn display(&self) -> Display<'_, $ustr> {
256 Display { str: self }
257 }
258
259 /// Returns a subslice of the string.
260 ///
261 /// This is the non-panicking alternative to indexing the string. Returns [`None`]
262 /// whenever equivalent indexing operation would panic.
263 #[inline]
264 #[must_use]
265 pub fn get<I>(&self, i: I) -> Option<&Self>
266 where
267 I: SliceIndex<[$uchar], Output = [$uchar]>,
268 {
269 self.inner.get(i).map(Self::from_slice)
270 }
271
272 /// Returns a mutable subslice of the string.
273 ///
274 /// This is the non-panicking alternative to indexing the string. Returns [`None`]
275 /// whenever equivalent indexing operation would panic.
276 #[inline]
277 #[must_use]
278 pub fn get_mut<I>(&mut self, i: I) -> Option<&mut Self>
279 where
280 I: SliceIndex<[$uchar], Output = [$uchar]>,
281 {
282 self.inner.get_mut(i).map(Self::from_slice_mut)
283 }
284
285 /// Returns an unchecked subslice of the string.
286 ///
287 /// This is the unchecked alternative to indexing the string.
288 ///
289 /// # Safety
290 ///
291 /// Callers of this function are responsible that these preconditions are satisfied:
292 ///
293 /// - The starting index must not exceed the ending index;
294 /// - Indexes must be within bounds of the original slice.
295 ///
296 /// Failing that, the returned string slice may reference invalid memory.
297 #[inline]
298 #[must_use]
299 pub unsafe fn get_unchecked<I>(&self, i: I) -> &Self
300 where
301 I: SliceIndex<[$uchar], Output = [$uchar]>,
302 {
303 Self::from_slice(self.inner.get_unchecked(i))
304 }
305
306 /// Returns aa mutable, unchecked subslice of the string.
307 ///
308 /// This is the unchecked alternative to indexing the string.
309 ///
310 /// # Safety
311 ///
312 /// Callers of this function are responsible that these preconditions are satisfied:
313 ///
314 /// - The starting index must not exceed the ending index;
315 /// - Indexes must be within bounds of the original slice.
316 ///
317 /// Failing that, the returned string slice may reference invalid memory.
318 #[inline]
319 #[must_use]
320 pub unsafe fn get_unchecked_mut<I>(&mut self, i: I) -> &mut Self
321 where
322 I: SliceIndex<[$uchar], Output = [$uchar]>,
323 {
324 Self::from_slice_mut(self.inner.get_unchecked_mut(i))
325 }
326
327 /// Divide one string slice into two at an index.
328 ///
329 /// The argument, `mid`, should be an offset from the start of the string.
330 ///
331 /// The two slices returned go from the start of the string slice to `mid`, and from
332 /// `mid` to the end of the string slice.
333 ///
334 /// To get mutable string slices instead, see the [`split_at_mut`][Self::split_at_mut]
335 /// method.
336 #[inline]
337 #[must_use]
338 pub fn split_at(&self, mid: usize) -> (&Self, &Self) {
339 let split = self.inner.split_at(mid);
340 (Self::from_slice(split.0), Self::from_slice(split.1))
341 }
342
343 /// Divide one mutable string slice into two at an index.
344 ///
345 /// The argument, `mid`, should be an offset from the start of the string.
346 ///
347 /// The two slices returned go from the start of the string slice to `mid`, and from
348 /// `mid` to the end of the string slice.
349 ///
350 /// To get immutable string slices instead, see the [`split_at`][Self::split_at] method.
351 #[inline]
352 #[must_use]
353 pub fn split_at_mut(&mut self, mid: usize) -> (&mut Self, &mut Self) {
354 let split = self.inner.split_at_mut(mid);
355 (Self::from_slice_mut(split.0), Self::from_slice_mut(split.1))
356 }
357
358 /// Creates a new owned string by repeating this string `n` times.
359 ///
360 /// # Panics
361 ///
362 /// This function will panic if the capacity would overflow.
363 #[inline]
364 #[cfg(feature = "alloc")]
365 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
366 #[must_use]
367 pub fn repeat(&self, n: usize) -> $ustring {
368 $ustring::from_vec(self.as_slice().repeat(n))
369 }
370 }
371
372 impl AsMut<$ustr> for $ustr {
373 #[inline]
374 fn as_mut(&mut self) -> &mut $ustr {
375 self
376 }
377 }
378
379 impl AsMut<[$uchar]> for $ustr {
380 #[inline]
381 fn as_mut(&mut self) -> &mut [$uchar] {
382 self.as_mut_slice()
383 }
384 }
385
386 impl AsRef<$ustr> for $ustr {
387 #[inline]
388 fn as_ref(&self) -> &Self {
389 self
390 }
391 }
392
393 impl AsRef<[$uchar]> for $ustr {
394 #[inline]
395 fn as_ref(&self) -> &[$uchar] {
396 self.as_slice()
397 }
398 }
399
400 impl Default for &$ustr {
401 #[inline]
402 fn default() -> Self {
403 $ustr::from_slice(&[])
404 }
405 }
406
407 impl Default for &mut $ustr {
408 #[inline]
409 fn default() -> Self {
410 $ustr::from_slice_mut(&mut [])
411 }
412 }
413
414 impl<'a> From<&'a [$uchar]> for &'a $ustr {
415 #[inline]
416 fn from(value: &'a [$uchar]) -> Self {
417 $ustr::from_slice(value)
418 }
419 }
420
421 impl<'a> From<&'a mut [$uchar]> for &'a $ustr {
422 #[inline]
423 fn from(value: &'a mut [$uchar]) -> Self {
424 $ustr::from_slice(value)
425 }
426 }
427
428 impl<'a> From<&'a mut [$uchar]> for &'a mut $ustr {
429 #[inline]
430 fn from(value: &'a mut [$uchar]) -> Self {
431 $ustr::from_slice_mut(value)
432 }
433 }
434
435 impl<'a> From<&'a $ustr> for &'a [$uchar] {
436 #[inline]
437 fn from(value: &'a $ustr) -> Self {
438 value.as_slice()
439 }
440 }
441
442 impl<'a> From<&'a mut $ustr> for &'a mut [$uchar] {
443 #[inline]
444 fn from(value: &'a mut $ustr) -> Self {
445 value.as_mut_slice()
446 }
447 }
448
449 #[cfg(feature = "std")]
450 impl From<&$ustr> for std::ffi::OsString {
451 #[inline]
452 fn from(s: &$ustr) -> std::ffi::OsString {
453 s.to_os_string()
454 }
455 }
456
457 impl<I> Index<I> for $ustr
458 where
459 I: SliceIndex<[$uchar], Output = [$uchar]>,
460 {
461 type Output = Self;
462
463 #[inline]
464 fn index(&self, index: I) -> &Self::Output {
465 Self::from_slice(&self.inner[index])
466 }
467 }
468
469 impl<I> IndexMut<I> for $ustr
470 where
471 I: SliceIndex<[$uchar], Output = [$uchar]>,
472 {
473 #[inline]
474 fn index_mut(&mut self, index: I) -> &mut Self::Output {
475 Self::from_slice_mut(&mut self.inner[index])
476 }
477 }
478
479 impl PartialEq<$ustr> for &$ustr {
480 #[inline]
481 fn eq(&self, other: &$ustr) -> bool {
482 self.as_slice() == other.as_slice()
483 }
484 }
485
486 impl PartialEq<&$ustr> for $ustr {
487 #[inline]
488 fn eq(&self, other: &&$ustr) -> bool {
489 self.as_slice() == other.as_slice()
490 }
491 }
492
493 impl PartialEq<crate::$ucstr> for $ustr {
494 #[inline]
495 fn eq(&self, other: &crate::$ucstr) -> bool {
496 self.as_slice() == other.as_slice()
497 }
498 }
499
500 impl PartialEq<crate::$ucstr> for &$ustr {
501 #[inline]
502 fn eq(&self, other: &crate::$ucstr) -> bool {
503 self.as_slice() == other.as_slice()
504 }
505 }
506
507 impl PartialEq<&crate::$ucstr> for $ustr {
508 #[inline]
509 fn eq(&self, other: &&crate::$ucstr) -> bool {
510 self.as_slice() == other.as_slice()
511 }
512 }
513
514 impl PartialOrd<crate::$ucstr> for $ustr {
515 #[inline]
516 fn partial_cmp(&self, other: &crate::$ucstr) -> Option<core::cmp::Ordering> {
517 self.partial_cmp(other.as_ustr())
518 }
519 }
520 };
521 }
522
523 ustr_common_impl! {
524 /// 16-bit wide string slice with undefined encoding.
525 ///
526 /// [`U16Str`] is to [`U16String`][crate::U16String] as [`OsStr`][std::ffi::OsStr] is to
527 /// [`OsString`][std::ffi::OsString].
528 ///
529 /// [`U16Str`] are string slices that do not have a defined encoding. While it is sometimes
530 /// assumed that they contain possibly invalid or ill-formed UTF-16 data, they may be used for
531 /// any wide encoded string. This is because [`U16Str`] is intended to be used with FFI
532 /// functions, where proper encoding cannot be guaranteed. If you need string slices that are
533 /// always valid UTF-16 strings, use [`Utf16Str`][crate::Utf16Str] instead.
534 ///
535 /// Because [`U16Str`] does not have a defined encoding, no restrictions are placed on mutating
536 /// or indexing the slice. This means that even if the string contained properly encoded UTF-16
537 /// or other encoding data, mutationing or indexing may result in malformed data. Convert to a
538 /// [`Utf16Str`][crate::Utf16Str] if retaining proper UTF-16 encoding is desired.
539 ///
540 /// # FFI considerations
541 ///
542 /// [`U16Str`] is not aware of nul values and may or may not be nul-terminated. It is intended
543 /// to be used with FFI functions that directly use string length, where the strings are known
544 /// to have proper nul-termination already, or where strings are merely being passed through
545 /// without modification.
546 ///
547 /// [`U16CStr`][crate::U16CStr] should be used instead if nul-aware strings are required.
548 ///
549 /// # Examples
550 ///
551 /// The easiest way to use [`U16Str`] outside of FFI is with the [`u16str!`][crate::u16str]
552 /// macro to convert string literals into UTF-16 string slices at compile time:
553 ///
554 /// ```
555 /// use widestring::u16str;
556 /// let hello = u16str!("Hello, world!");
557 /// ```
558 ///
559 /// You can also convert any [`u16`] slice directly:
560 ///
561 /// ```
562 /// use widestring::{u16str, U16Str};
563 ///
564 /// let sparkle_heart = [0xd83d, 0xdc96];
565 /// let sparkle_heart = U16Str::from_slice(&sparkle_heart);
566 ///
567 /// assert_eq!(u16str!("💖"), sparkle_heart);
568 ///
569 /// // This unpaired UTf-16 surrogate is invalid UTF-16, but is perfectly valid in U16Str
570 /// let malformed_utf16 = [0x0, 0xd83d]; // Note that nul values are also valid an untouched
571 /// let s = U16Str::from_slice(&malformed_utf16);
572 ///
573 /// assert_eq!(s.len(), 2);
574 /// ```
575 ///
576 /// When working with a FFI, it is useful to create a [`U16Str`] from a pointer and a length:
577 ///
578 /// ```
579 /// use widestring::{u16str, U16Str};
580 ///
581 /// let sparkle_heart = [0xd83d, 0xdc96];
582 /// let sparkle_heart = unsafe {
583 /// U16Str::from_ptr(sparkle_heart.as_ptr(), sparkle_heart.len())
584 /// };
585 /// assert_eq!(u16str!("💖"), sparkle_heart);
586 /// ```
587 struct U16Str([u16]);
588
589 type UString = U16String;
590 type UCStr = U16CStr;
591
592 /// Returns an object that implements [`Display`][std::fmt::Display] for printing
593 /// strings that may contain non-Unicode data.
594 ///
595 /// This method assumes this string is intended to be UTF-16 encoding, but handles
596 /// ill-formed UTF-16 sequences lossily. The returned struct implements
597 /// the [`Display`][std::fmt::Display] trait in a way that decoding the string is lossy
598 /// UTF-16 decoding but no heap allocations are performed, such as by
599 /// [`to_string_lossy`][Self::to_string_lossy].
600 ///
601 /// By default, invalid Unicode data is replaced with
602 /// [`U+FFFD REPLACEMENT CHARACTER`][std::char::REPLACEMENT_CHARACTER] (�). If you wish
603 /// to simply skip any invalid Uncode data and forego the replacement, you may use the
604 /// [alternate formatting][std::fmt#sign0] with `{:#}`.
605 ///
606 /// # Examples
607 ///
608 /// Basic usage:
609 ///
610 /// ```
611 /// use widestring::U16Str;
612 ///
613 /// // 𝄞mus<invalid>ic<invalid>
614 /// let s = U16Str::from_slice(&[
615 /// 0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834,
616 /// ]);
617 ///
618 /// assert_eq!(format!("{}", s.display()),
619 /// "𝄞mus�ic�"
620 /// );
621 /// ```
622 ///
623 /// Using alternate formatting style to skip invalid values entirely:
624 ///
625 /// ```
626 /// use widestring::U16Str;
627 ///
628 /// // 𝄞mus<invalid>ic<invalid>
629 /// let s = U16Str::from_slice(&[
630 /// 0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834,
631 /// ]);
632 ///
633 /// assert_eq!(format!("{:#}", s.display()),
634 /// "𝄞music"
635 /// );
636 /// ```
637 fn display() -> {}
638 }
639
640 ustr_common_impl! {
641 /// 32-bit wide string slice with undefined encoding.
642 ///
643 /// [`U32Str`] is to [`U32String`][crate::U32String] as [`OsStr`][std::ffi::OsStr] is to
644 /// [`OsString`][std::ffi::OsString].
645 ///
646 /// [`U32Str`] are string slices that do not have a defined encoding. While it is sometimes
647 /// assumed that they contain possibly invalid or ill-formed UTF-32 data, they may be used for
648 /// any wide encoded string. This is because [`U32Str`] is intended to be used with FFI
649 /// functions, where proper encoding cannot be guaranteed. If you need string slices that are
650 /// always valid UTF-32 strings, use [`Utf32Str`][crate::Utf32Str] instead.
651 ///
652 /// Because [`U32Str`] does not have a defined encoding, no restrictions are placed on mutating
653 /// or indexing the slice. This means that even if the string contained properly encoded UTF-32
654 /// or other encoding data, mutationing or indexing may result in malformed data. Convert to a
655 /// [`Utf32Str`][crate::Utf32Str] if retaining proper UTF-32 encoding is desired.
656 ///
657 /// # FFI considerations
658 ///
659 /// [`U32Str`] is not aware of nul values and may or may not be nul-terminated. It is intended
660 /// to be used with FFI functions that directly use string length, where the strings are known
661 /// to have proper nul-termination already, or where strings are merely being passed through
662 /// without modification.
663 ///
664 /// [`U32CStr`][crate::U32CStr] should be used instead if nul-aware strings are required.
665 ///
666 /// # Examples
667 ///
668 /// The easiest way to use [`U32Str`] outside of FFI is with the [`u32str!`][crate::u32str]
669 /// macro to convert string literals into UTF-32 string slices at compile time:
670 ///
671 /// ```
672 /// use widestring::u32str;
673 /// let hello = u32str!("Hello, world!");
674 /// ```
675 ///
676 /// You can also convert any [`u32`] slice directly:
677 ///
678 /// ```
679 /// use widestring::{u32str, U32Str};
680 ///
681 /// let sparkle_heart = [0x1f496];
682 /// let sparkle_heart = U32Str::from_slice(&sparkle_heart);
683 ///
684 /// assert_eq!(u32str!("💖"), sparkle_heart);
685 ///
686 /// // This UTf-16 surrogate is invalid UTF-32, but is perfectly valid in U32Str
687 /// let malformed_utf32 = [0x0, 0xd83d]; // Note that nul values are also valid an untouched
688 /// let s = U32Str::from_slice(&malformed_utf32);
689 ///
690 /// assert_eq!(s.len(), 2);
691 /// ```
692 ///
693 /// When working with a FFI, it is useful to create a [`U32Str`] from a pointer and a length:
694 ///
695 /// ```
696 /// use widestring::{u32str, U32Str};
697 ///
698 /// let sparkle_heart = [0x1f496];
699 /// let sparkle_heart = unsafe {
700 /// U32Str::from_ptr(sparkle_heart.as_ptr(), sparkle_heart.len())
701 /// };
702 /// assert_eq!(u32str!("💖"), sparkle_heart);
703 /// ```
704 struct U32Str([u32]);
705
706 type UString = U32String;
707 type UCStr = U32CStr;
708
709 /// Returns an object that implements [`Display`][std::fmt::Display] for printing
710 /// strings that may contain non-Unicode data.
711 ///
712 /// This method assumes this string is intended to be UTF-32 encoding, but handles
713 /// ill-formed UTF-32 sequences lossily. The returned struct implements
714 /// the [`Display`][std::fmt::Display] trait in a way that decoding the string is lossy
715 /// UTF-32 decoding but no heap allocations are performed, such as by
716 /// [`to_string_lossy`][Self::to_string_lossy].
717 ///
718 /// By default, invalid Unicode data is replaced with
719 /// [`U+FFFD REPLACEMENT CHARACTER`][std::char::REPLACEMENT_CHARACTER] (�). If you wish
720 /// to simply skip any invalid Uncode data and forego the replacement, you may use the
721 /// [alternate formatting][std::fmt#sign0] with `{:#}`.
722 ///
723 /// # Examples
724 ///
725 /// Basic usage:
726 ///
727 /// ```
728 /// use widestring::U32Str;
729 ///
730 /// // 𝄞mus<invalid>ic<invalid>
731 /// let s = U32Str::from_slice(&[
732 /// 0x1d11e, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834,
733 /// ]);
734 ///
735 /// assert_eq!(format!("{}", s.display()),
736 /// "𝄞mus�ic�"
737 /// );
738 /// ```
739 ///
740 /// Using alternate formatting style to skip invalid values entirely:
741 ///
742 /// ```
743 /// use widestring::U32Str;
744 ///
745 /// // 𝄞mus<invalid>ic<invalid>
746 /// let s = U32Str::from_slice(&[
747 /// 0x1d11e, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834,
748 /// ]);
749 ///
750 /// assert_eq!(format!("{:#}", s.display()),
751 /// "𝄞music"
752 /// );
753 /// ```
754 fn display() -> {}
755 }
756
757 impl U16Str {
758 /// Decodes a string reference to an owned [`OsString`][std::ffi::OsString].
759 ///
760 /// This makes a string copy of the [`U16Str`]. Since [`U16Str`] makes no guarantees that its
761 /// encoding is UTF-16 or that the data valid UTF-16, there is no guarantee that the resulting
762 /// [`OsString`][std::ffi::OsString] will have a valid underlying encoding either.
763 ///
764 /// Note that the encoding of [`OsString`][std::ffi::OsString] is platform-dependent, so on
765 /// some platforms this may make an encoding conversions, while on other platforms (such as
766 /// windows) no changes to the string will be made.
767 ///
768 /// # Examples
769 ///
770 /// ```rust
771 /// use widestring::U16String;
772 /// use std::ffi::OsString;
773 /// let s = "MyString";
774 /// // Create a wide string from the string
775 /// let wstr = U16String::from_str(s);
776 /// // Create an OsString from the wide string
777 /// let osstr = wstr.to_os_string();
778 ///
779 /// assert_eq!(osstr, OsString::from(s));
780 /// ```
781 #[cfg(feature = "std")]
782 #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
783 #[inline]
784 #[must_use]
785 pub fn to_os_string(&self) -> std::ffi::OsString {
786 crate::platform::os_from_wide(&self.inner)
787 }
788
789 /// Decodes this string to a [`String`] if it contains valid UTF-16 data.
790 ///
791 /// This method assumes this string is encoded as UTF-16 and attempts to decode it as such.
792 ///
793 /// # Failures
794 ///
795 /// Returns an error if the string contains any invalid UTF-16 data.
796 ///
797 /// # Examples
798 ///
799 /// ```rust
800 /// use widestring::U16String;
801 /// let s = "MyString";
802 /// // Create a wide string from the string
803 /// let wstr = U16String::from_str(s);
804 /// // Create a regular string from the wide string
805 /// let s2 = wstr.to_string().unwrap();
806 ///
807 /// assert_eq!(s2, s);
808 /// ```
809 #[cfg(feature = "alloc")]
810 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
811 #[inline]
812 pub fn to_string(&self) -> Result<String, Utf16Error> {
813 // Perform conversion ourselves to use our own error types with additional info
814 let mut s = String::with_capacity(self.len());
815 for (index, result) in self.chars().enumerate() {
816 let c = result.map_err(|e| Utf16Error::empty(index, e))?;
817 s.push(c);
818 }
819 Ok(s)
820 }
821
822 /// Decodes the string to a [`String`] even if it is invalid UTF-16 data.
823 ///
824 /// This method assumes this string is encoded as UTF-16 and attempts to decode it as such. Any
825 /// invalid sequences are replaced with
826 /// [`U+FFFD REPLACEMENT CHARACTER`][core::char::REPLACEMENT_CHARACTER], which looks like this:
827 /// �
828 ///
829 /// # Examples
830 ///
831 /// ```rust
832 /// use widestring::U16String;
833 /// let s = "MyString";
834 /// // Create a wide string from the string
835 /// let wstr = U16String::from_str(s);
836 /// // Create a regular string from the wide string
837 /// let lossy = wstr.to_string_lossy();
838 ///
839 /// assert_eq!(lossy, s);
840 /// ```
841 #[cfg(feature = "alloc")]
842 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
843 #[inline]
844 #[must_use]
845 pub fn to_string_lossy(&self) -> String {
846 String::from_utf16_lossy(&self.inner)
847 }
848
849 /// Returns an iterator over the [`char`][prim@char]s of a string slice.
850 ///
851 /// As this string has no defined encoding, this method assumes the string is UTF-16. Since it
852 /// may consist of invalid UTF-16, the iterator returned by this method
853 /// is an iterator over `Result<char, DecodeUtf16Error>` instead of [`char`][prim@char]s
854 /// directly. If you would like a lossy iterator over [`chars`][prim@char]s directly, instead
855 /// use [`chars_lossy`][Self::chars_lossy].
856 ///
857 /// It's important to remember that [`char`][prim@char] represents a Unicode Scalar Value, and
858 /// may not match your idea of what a 'character' is. Iteration over grapheme clusters may be
859 /// what you actually want. That functionality is not provided by by this crate.
860 #[inline]
861 #[must_use]
862 pub fn chars(&self) -> CharsUtf16<'_> {
863 CharsUtf16::new(self.as_slice())
864 }
865
866 /// Returns a lossy iterator over the [`char`][prim@char]s of a string slice.
867 ///
868 /// As this string has no defined encoding, this method assumes the string is UTF-16. Since it
869 /// may consist of invalid UTF-16, the iterator returned by this method will replace unpaired
870 /// surrogates with
871 /// [`U+FFFD REPLACEMENT CHARACTER`][std::char::REPLACEMENT_CHARACTER] (�). This is a lossy
872 /// version of [`chars`][Self::chars].
873 ///
874 /// It's important to remember that [`char`][prim@char] represents a Unicode Scalar Value, and
875 /// may not match your idea of what a 'character' is. Iteration over grapheme clusters may be
876 /// what you actually want. That functionality is not provided by by this crate.
877 #[inline]
878 #[must_use]
879 pub fn chars_lossy(&self) -> CharsLossyUtf16<'_> {
880 CharsLossyUtf16::new(self.as_slice())
881 }
882
883 /// Returns an iterator over the chars of a string slice, and their positions.
884 ///
885 /// As this string has no defined encoding, this method assumes the string is UTF-16. Since it
886 /// may consist of invalid UTF-16, the iterator returned by this method is an iterator over
887 /// `Result<char, DecodeUtf16Error>` as well as their positions, instead of
888 /// [`char`][prim@char]s directly. If you would like a lossy indices iterator over
889 /// [`chars`][prim@char]s directly, instead use
890 /// [`char_indices_lossy`][Self::char_indices_lossy].
891 ///
892 /// The iterator yields tuples. The position is first, the [`char`][prim@char] is second.
893 #[inline]
894 #[must_use]
895 pub fn char_indices(&self) -> CharIndicesUtf16<'_> {
896 CharIndicesUtf16::new(self.as_slice())
897 }
898
899 /// Returns a lossy iterator over the chars of a string slice, and their positions.
900 ///
901 /// As this string slice may consist of invalid UTF-16, the iterator returned by this method
902 /// will replace unpaired surrogates with
903 /// [`U+FFFD REPLACEMENT CHARACTER`][std::char::REPLACEMENT_CHARACTER] (�), as well as the
904 /// positions of all characters. This is a lossy version of
905 /// [`char_indices`][Self::char_indices].
906 ///
907 /// The iterator yields tuples. The position is first, the [`char`][prim@char] is second.
908 #[inline]
909 #[must_use]
910 pub fn char_indices_lossy(&self) -> CharIndicesLossyUtf16<'_> {
911 CharIndicesLossyUtf16::new(self.as_slice())
912 }
913 }
914
915 impl U32Str {
916 /// Constructs a [`U32Str`] from a [`char`][prim@char] pointer and a length.
917 ///
918 /// The `len` argument is the number of `char` elements, **not** the number of bytes. No copying
919 /// or allocation is performed, the resulting value is a direct reference to the pointer bytes.
920 ///
921 /// # Safety
922 ///
923 /// This function is unsafe as there is no guarantee that the given pointer is valid for `len`
924 /// elements.
925 ///
926 /// In addition, the data must meet the safety conditions of [std::slice::from_raw_parts].
927 /// In particular, the returned string reference *must not be mutated* for the duration of
928 /// lifetime `'a`, except inside an [`UnsafeCell`][std::cell::UnsafeCell].
929 ///
930 /// # Panics
931 ///
932 /// This function panics if `p` is null.
933 ///
934 /// # Caveat
935 ///
936 /// The lifetime for the returned string is inferred from its usage. To prevent accidental
937 /// misuse, it's suggested to tie the lifetime to whichever source lifetime is safe in the
938 /// context, such as by providing a helper function taking the lifetime of a host value for the
939 /// string, or by explicit annotation.
940 #[inline]
941 #[must_use]
942 pub unsafe fn from_char_ptr<'a>(p: *const char, len: usize) -> &'a Self {
943 Self::from_ptr(p as *const u32, len)
944 }
945
946 /// Constructs a mutable [`U32Str`] from a mutable [`char`][prim@char] pointer and a length.
947 ///
948 /// The `len` argument is the number of `char` elements, **not** the number of bytes. No copying
949 /// or allocation is performed, the resulting value is a direct reference to the pointer bytes.
950 ///
951 /// # Safety
952 ///
953 /// This function is unsafe as there is no guarantee that the given pointer is valid for `len`
954 /// elements.
955 ///
956 /// In addition, the data must meet the safety conditions of [std::slice::from_raw_parts_mut].
957 ///
958 /// # Panics
959 ///
960 /// This function panics if `p` is null.
961 ///
962 /// # Caveat
963 ///
964 /// The lifetime for the returned string is inferred from its usage. To prevent accidental
965 /// misuse, it's suggested to tie the lifetime to whichever source lifetime is safe in the
966 /// context, such as by providing a helper function taking the lifetime of a host value for the
967 /// string, or by explicit annotation.
968 #[inline]
969 #[must_use]
970 pub unsafe fn from_char_ptr_mut<'a>(p: *mut char, len: usize) -> &'a mut Self {
971 Self::from_ptr_mut(p as *mut u32, len)
972 }
973
974 /// Constructs a [`U32Str`] from a [`char`][prim@char] slice.
975 ///
976 /// No checks are performed on the slice.
977 #[inline]
978 #[must_use]
979 pub fn from_char_slice(slice: &[char]) -> &Self {
980 let ptr: *const [char] = slice;
981 unsafe { &*(ptr as *const Self) }
982 }
983
984 /// Constructs a mutable [`U32Str`] from a mutable [`char`][prim@char] slice.
985 ///
986 /// No checks are performed on the slice.
987 #[inline]
988 #[must_use]
989 pub fn from_char_slice_mut(slice: &mut [char]) -> &mut Self {
990 let ptr: *mut [char] = slice;
991 unsafe { &mut *(ptr as *mut Self) }
992 }
993
994 /// Decodes a string to an owned [`OsString`][std::ffi::OsString].
995 ///
996 /// This makes a string copy of the [`U16Str`]. Since [`U16Str`] makes no guarantees that its
997 /// encoding is UTF-16 or that the data valid UTF-16, there is no guarantee that the resulting
998 /// [`OsString`][std::ffi::OsString] will have a valid underlying encoding either.
999 ///
1000 /// Note that the encoding of [`OsString`][std::ffi::OsString] is platform-dependent, so on
1001 /// some platforms this may make an encoding conversions, while on other platforms no changes to
1002 /// the string will be made.
1003 ///
1004 /// # Examples
1005 ///
1006 /// ```rust
1007 /// use widestring::U32String;
1008 /// use std::ffi::OsString;
1009 /// let s = "MyString";
1010 /// // Create a wide string from the string
1011 /// let wstr = U32String::from_str(s);
1012 /// // Create an OsString from the wide string
1013 /// let osstr = wstr.to_os_string();
1014 ///
1015 /// assert_eq!(osstr, OsString::from(s));
1016 /// ```
1017 #[cfg(feature = "std")]
1018 #[cfg_attr(docsrs, doc(cfg(feature = "std")))]
1019 #[inline]
1020 #[must_use]
1021 pub fn to_os_string(&self) -> std::ffi::OsString {
1022 self.to_string_lossy().into()
1023 }
1024
1025 /// Decodes the string to a [`String`] if it contains valid UTF-32 data.
1026 ///
1027 /// This method assumes this string is encoded as UTF-32 and attempts to decode it as such.
1028 ///
1029 /// # Failures
1030 ///
1031 /// Returns an error if the string contains any invalid UTF-32 data.
1032 ///
1033 /// # Examples
1034 ///
1035 /// ```rust
1036 /// use widestring::U32String;
1037 /// let s = "MyString";
1038 /// // Create a wide string from the string
1039 /// let wstr = U32String::from_str(s);
1040 /// // Create a regular string from the wide string
1041 /// let s2 = wstr.to_string().unwrap();
1042 ///
1043 /// assert_eq!(s2, s);
1044 /// ```
1045 #[cfg(feature = "alloc")]
1046 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
1047 pub fn to_string(&self) -> Result<String, Utf32Error> {
1048 let mut s = String::with_capacity(self.len());
1049 for (index, result) in self.chars().enumerate() {
1050 let c = result.map_err(|e| Utf32Error::empty(index, e))?;
1051 s.push(c);
1052 }
1053 Ok(s)
1054 }
1055
1056 /// Decodes the string reference to a [`String`] even if it is invalid UTF-32 data.
1057 ///
1058 /// This method assumes this string is encoded as UTF-16 and attempts to decode it as such. Any
1059 /// invalid sequences are replaced with
1060 /// [`U+FFFD REPLACEMENT CHARACTER`][core::char::REPLACEMENT_CHARACTER], which looks like this:
1061 /// �
1062 ///
1063 /// # Examples
1064 ///
1065 /// ```rust
1066 /// use widestring::U32String;
1067 /// let s = "MyString";
1068 /// // Create a wide string from the string
1069 /// let wstr = U32String::from_str(s);
1070 /// // Create a regular string from the wide string
1071 /// let lossy = wstr.to_string_lossy();
1072 ///
1073 /// assert_eq!(lossy, s);
1074 /// ```
1075 #[cfg(feature = "alloc")]
1076 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
1077 #[must_use]
1078 pub fn to_string_lossy(&self) -> String {
1079 let chars: Vec<char> = self
1080 .inner
1081 .iter()
1082 .map(|&c| char::from_u32(c).unwrap_or(char::REPLACEMENT_CHARACTER))
1083 .collect();
1084 let size = chars.iter().map(|c| c.len_utf8()).sum();
1085 let mut vec = alloc::vec![0; size];
1086 let mut i = 0;
1087 for c in chars {
1088 c.encode_utf8(&mut vec[i..]);
1089 i += c.len_utf8();
1090 }
1091 unsafe { String::from_utf8_unchecked(vec) }
1092 }
1093
1094 /// Returns an iterator over the [`char`][prim@char]s of a string slice.
1095 ///
1096 /// As this string has no defined encoding, this method assumes the string is UTF-32. Since it
1097 /// may consist of invalid UTF-32, the iterator returned by this method
1098 /// is an iterator over `Result<char, DecodeUtf32Error>` instead of [`char`][prim@char]s
1099 /// directly. If you would like a lossy iterator over [`chars`][prim@char]s directly, instead
1100 /// use [`chars_lossy`][Self::chars_lossy].
1101 ///
1102 /// It's important to remember that [`char`][prim@char] represents a Unicode Scalar Value, and
1103 /// may not match your idea of what a 'character' is. Iteration over grapheme clusters may be
1104 /// what you actually want. That functionality is not provided by by this crate.
1105 #[inline]
1106 #[must_use]
1107 pub fn chars(&self) -> CharsUtf32<'_> {
1108 CharsUtf32::new(self.as_slice())
1109 }
1110
1111 /// Returns a lossy iterator over the [`char`][prim@char]s of a string slice.
1112 ///
1113 /// As this string has no defined encoding, this method assumes the string is UTF-32. Since it
1114 /// may consist of invalid UTF-32, the iterator returned by this method will replace unpaired
1115 /// surrogates with
1116 /// [`U+FFFD REPLACEMENT CHARACTER`][std::char::REPLACEMENT_CHARACTER] (�). This is a lossy
1117 /// version of [`chars`][Self::chars].
1118 ///
1119 /// It's important to remember that [`char`][prim@char] represents a Unicode Scalar Value, and
1120 /// may not match your idea of what a 'character' is. Iteration over grapheme clusters may be
1121 /// what you actually want. That functionality is not provided by by this crate.
1122 #[inline]
1123 #[must_use]
1124 pub fn chars_lossy(&self) -> CharsLossyUtf32<'_> {
1125 CharsLossyUtf32::new(self.as_slice())
1126 }
1127
1128 /// Returns an iterator over the chars of a string slice, and their positions.
1129 ///
1130 /// As this string has no defined encoding, this method assumes the string is UTF-32. Since it
1131 /// may consist of invalid UTF-32, the iterator returned by this method is an iterator over
1132 /// `Result<char, DecodeUtf32Error>` as well as their positions, instead of
1133 /// [`char`][prim@char]s directly. If you would like a lossy indices iterator over
1134 /// [`chars`][prim@char]s directly, instead use
1135 /// [`char_indices_lossy`][Self::char_indices_lossy].
1136 ///
1137 /// The iterator yields tuples. The position is first, the [`char`][prim@char] is second.
1138 #[inline]
1139 #[must_use]
1140 pub fn char_indices(&self) -> CharIndicesUtf32<'_> {
1141 CharIndicesUtf32::new(self.as_slice())
1142 }
1143
1144 /// Returns a lossy iterator over the chars of a string slice, and their positions.
1145 ///
1146 /// As this string slice may consist of invalid UTF-32, the iterator returned by this method
1147 /// will replace invalid values with
1148 /// [`U+FFFD REPLACEMENT CHARACTER`][std::char::REPLACEMENT_CHARACTER] (�), as well as the
1149 /// positions of all characters. This is a lossy version of
1150 /// [`char_indices`][Self::char_indices].
1151 ///
1152 /// The iterator yields tuples. The position is first, the [`char`][prim@char] is second.
1153 #[inline]
1154 #[must_use]
1155 pub fn char_indices_lossy(&self) -> CharIndicesLossyUtf32<'_> {
1156 CharIndicesLossyUtf32::new(self.as_slice())
1157 }
1158 }
1159
1160 impl core::fmt::Debug for U16Str {
1161 #[inline]
1162 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1163 crate::debug_fmt_u16(self.as_slice(), f)
1164 }
1165 }
1166
1167 impl core::fmt::Debug for U32Str {
1168 #[inline]
1169 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1170 crate::debug_fmt_u32(self.as_slice(), f)
1171 }
1172 }
1173
1174 impl<'a> From<&'a [char]> for &'a U32Str {
1175 #[inline]
1176 fn from(value: &'a [char]) -> Self {
1177 U32Str::from_char_slice(value)
1178 }
1179 }
1180
1181 impl<'a> From<&'a mut [char]> for &'a mut U32Str {
1182 #[inline]
1183 fn from(value: &'a mut [char]) -> Self {
1184 U32Str::from_char_slice_mut(value)
1185 }
1186 }
1187
1188 /// Alias for [`U16Str`] or [`U32Str`] depending on platform. Intended to match typical C `wchar_t`
1189 /// size on platform.
1190 #[cfg(not(windows))]
1191 pub type WideStr = U32Str;
1192
1193 /// Alias for [`U16Str`] or [`U32Str`] depending on platform. Intended to match typical C `wchar_t`
1194 /// size on platform.
1195 #[cfg(windows)]
1196 pub type WideStr = U16Str;
1197
1198 /// Helper struct for printing wide string values with [`format!`] and `{}`.
1199 ///
1200 /// A wide string might contain ill-formed UTF encoding. This struct implements the
1201 /// [`Display`][std::fmt::Display] trait in a way that decoding the string is lossy but no heap
1202 /// allocations are performed, such as by [`to_string_lossy`][U16Str::to_string_lossy]. It is
1203 /// created by the [`display`][U16Str::display] method on [`U16Str`] and [`U32Str`].
1204 ///
1205 /// By default, invalid Unicode data is replaced with
1206 /// [`U+FFFD REPLACEMENT CHARACTER`][std::char::REPLACEMENT_CHARACTER] (�). If you wish to simply
1207 /// skip any invalid Uncode data and forego the replacement, you may use the
1208 /// [alternate formatting][std::fmt#sign0] with `{:#}`.
1209 pub struct Display<'a, S: ?Sized> {
1210 str: &'a S,
1211 }
1212
1213 impl<'a> core::fmt::Debug for Display<'a, U16Str> {
1214 #[inline]
1215 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1216 core::fmt::Debug::fmt(&self.str, f)
1217 }
1218 }
1219
1220 impl<'a> core::fmt::Debug for Display<'a, U32Str> {
1221 #[inline]
1222 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1223 core::fmt::Debug::fmt(&self.str, f)
1224 }
1225 }
1226
1227 impl<'a> core::fmt::Display for Display<'a, U16Str> {
1228 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1229 for c in crate::decode_utf16_lossy(self.str.as_slice().iter().copied()) {
1230 // Allow alternate {:#} format which skips replacment chars entirely
1231 if c != core::char::REPLACEMENT_CHARACTER || !f.alternate() {
1232 f.write_char(c)?;
1233 }
1234 }
1235 Ok(())
1236 }
1237 }
1238
1239 impl<'a> core::fmt::Display for Display<'a, U32Str> {
1240 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
1241 for c in crate::decode_utf32_lossy(self.str.as_slice().iter().copied()) {
1242 // Allow alternate {:#} format which skips replacment chars entirely
1243 if c != core::char::REPLACEMENT_CHARACTER || !f.alternate() {
1244 f.write_char(c)?;
1245 }
1246 }
1247 Ok(())
1248 }
1249 }