Debian Codegraph @

.cargo/vendor/widestring/src/utfstr.rs

raw
1 //! UTF string slices.
2 //!
3 //! This module contains UTF string slices and related types.
4
5 use crate::{
6 error::{Utf16Error, Utf32Error},
7 is_utf16_low_surrogate,
8 iter::{EncodeUtf16, EncodeUtf32, EncodeUtf8},
9 validate_utf16, validate_utf32, U16Str, U32Str,
10 };
11 #[cfg(feature = "alloc")]
12 use crate::{Utf16String, Utf32String};
13 #[cfg(feature = "alloc")]
14 #[allow(unused_imports)]
15 use alloc::{borrow::Cow, boxed::Box, string::String};
16 #[allow(unused_imports)]
17 use core::{
18 convert::{AsMut, AsRef, TryFrom},
19 fmt::Write,
20 ops::{Index, IndexMut, RangeBounds},
21 slice::SliceIndex,
22 };
23
24 mod iter;
25
26 pub use iter::*;
27
28 macro_rules! utfstr_common_impl {
29 {
30 $(#[$utfstr_meta:meta])*
31 struct $utfstr:ident([$uchar:ty]);
32 type UtfString = $utfstring:ident;
33 type UStr = $ustr:ident;
34 type UCStr = $ucstr:ident;
35 type UtfError = $utferror:ident;
36 $(#[$from_slice_unchecked_meta:meta])*
37 fn from_slice_unchecked() -> {}
38 $(#[$from_slice_unchecked_mut_meta:meta])*
39 fn from_slice_unchecked_mut() -> {}
40 $(#[$from_boxed_slice_unchecked_meta:meta])*
41 fn from_boxed_slice_unchecked() -> {}
42 $(#[$get_unchecked_meta:meta])*
43 fn get_unchecked() -> {}
44 $(#[$get_unchecked_mut_meta:meta])*
45 fn get_unchecked_mut() -> {}
46 $(#[$len_meta:meta])*
47 fn len() -> {}
48 } => {
49 $(#[$utfstr_meta])*
50 #[allow(clippy::derive_hash_xor_eq)]
51 #[derive(PartialEq, Eq, PartialOrd, Ord, Hash)]
52 pub struct $utfstr {
53 pub(crate) inner: [$uchar],
54 }
55
56 impl $utfstr {
57 $(#[$from_slice_unchecked_meta])*
58 #[allow(trivial_casts)]
59 #[inline]
60 #[must_use]
61 pub const unsafe fn from_slice_unchecked(s: &[$uchar]) -> &Self {
62 &*(s as *const [$uchar] as *const Self)
63 }
64
65 $(#[$from_slice_unchecked_mut_meta])*
66 #[allow(trivial_casts)]
67 #[inline]
68 #[must_use]
69 pub unsafe fn from_slice_unchecked_mut(s: &mut [$uchar]) -> &mut Self {
70 &mut *(s as *mut [$uchar] as *mut Self)
71 }
72
73 $(#[$from_boxed_slice_unchecked_meta])*
74 #[inline]
75 #[cfg(feature = "alloc")]
76 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
77 #[must_use]
78 pub unsafe fn from_boxed_slice_unchecked(s: Box<[$uchar]>) -> Box<Self> {
79 Box::from_raw(Box::into_raw(s) as *mut Self)
80 }
81
82 $(#[$get_unchecked_meta])*
83 #[inline]
84 #[must_use]
85 pub unsafe fn get_unchecked<I>(&self, index: I) -> &Self
86 where
87 I: SliceIndex<[$uchar], Output = [$uchar]>,
88 {
89 Self::from_slice_unchecked(self.inner.get_unchecked(index))
90 }
91
92 $(#[$get_unchecked_mut_meta])*
93 #[inline]
94 #[must_use]
95 pub unsafe fn get_unchecked_mut<I>(&mut self, index: I) -> &mut Self
96 where
97 I: SliceIndex<[$uchar], Output = [$uchar]>,
98 {
99 Self::from_slice_unchecked_mut(self.inner.get_unchecked_mut(index))
100 }
101
102 $(#[$len_meta])*
103 #[inline]
104 #[must_use]
105 pub const fn len(&self) -> usize {
106 self.inner.len()
107 }
108
109 /// Returns `true` if the string has a length of zero.
110 #[inline]
111 #[must_use]
112 pub const fn is_empty(&self) -> bool {
113 self.inner.is_empty()
114 }
115
116 /// Converts a string to a slice of its underlying elements.
117 ///
118 /// To convert the slice back into a string slice, use the
119 /// [`from_slice`][Self::from_slice] function.
120 #[inline]
121 #[must_use]
122 pub const fn as_slice(&self) -> &[$uchar] {
123 &self.inner
124 }
125
126 /// Converts a mutable string to a mutable slice of its underlying elements.
127 ///
128 /// # Safety
129 ///
130 /// This function is unsafe because you can violate the invariants of this type when
131 /// mutating the slice. The caller must ensure that the contents of the slice is valid
132 /// UTF before the borrow ends and the underlying string is used.
133 ///
134 /// Use of this string type whose contents have been mutated to invalid UTF is
135 /// undefined behavior.
136 #[inline]
137 #[must_use]
138 pub unsafe fn as_mut_slice(&mut self) -> &mut [$uchar] {
139 &mut self.inner
140 }
141
142 /// Converts a string slice to a raw pointer.
143 ///
144 /// This pointer will be pointing to the first element of the string slice.
145 ///
146 /// The caller must ensure that the returned pointer is never written to. If you need to
147 /// mutate the contents of the string slice, use [`as_mut_ptr`][Self::as_mut_ptr].
148 #[inline]
149 #[must_use]
150 pub const fn as_ptr(&self) -> *const $uchar {
151 self.inner.as_ptr()
152 }
153
154 /// Converts a mutable string slice to a mutable pointer.
155 ///
156 /// This pointer will be pointing to the first element of the string slice.
157 #[inline]
158 #[must_use]
159 pub fn as_mut_ptr(&mut self) -> *mut $uchar {
160 self.inner.as_mut_ptr()
161 }
162
163 /// Returns this string as a wide string slice of undefined encoding.
164 #[inline]
165 #[must_use]
166 pub const fn as_ustr(&self) -> &$ustr {
167 $ustr::from_slice(self.as_slice())
168 }
169
170 /// Returns a string slice with leading and trailing whitespace removed.
171 ///
172 /// 'Whitespace' is defined according to the terms of the Unicode Derived Core Property
173 /// `White_Space`.
174 #[must_use]
175 pub fn trim(&self) -> &Self {
176 self.trim_start().trim_end()
177 }
178
179 /// Returns a string slice with leading whitespace removed.
180 ///
181 /// 'Whitespace' is defined according to the terms of the Unicode Derived Core Property
182 /// `White_Space`.
183 ///
184 /// # Text directionality
185 ///
186 /// A string is a sequence of elements. `start` in this context means the first position
187 /// of that sequence; for a left-to-right language like English or Russian, this will be
188 /// left side, and for right-to-left languages like Arabic or Hebrew, this will be the
189 /// right side.
190 #[must_use]
191 pub fn trim_start(&self) -> &Self {
192 if let Some((index, _)) = self.char_indices().find(|(_, c)| !c.is_whitespace()) {
193 &self[index..]
194 } else {
195 <&Self as Default>::default()
196 }
197 }
198
199 /// Returns a string slice with trailing whitespace removed.
200 ///
201 /// 'Whitespace' is defined according to the terms of the Unicode Derived Core Property
202 /// `White_Space`.
203 ///
204 /// # Text directionality
205 ///
206 /// A string is a sequence of elements. `end` in this context means the last position of
207 /// that sequence; for a left-to-right language like English or Russian, this will be
208 /// right side, and for right-to-left languages like Arabic or Hebrew, this will be the
209 /// left side.
210 #[must_use]
211 pub fn trim_end(&self) -> &Self {
212 if let Some((index, _)) = self.char_indices().rfind(|(_, c)| !c.is_whitespace()) {
213 &self[..=index]
214 } else {
215 <&Self as Default>::default()
216 }
217 }
218
219 /// Converts a boxed string into a boxed slice without copying or allocating.
220 #[inline]
221 #[cfg(feature = "alloc")]
222 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
223 #[must_use]
224 pub fn into_boxed_slice(self: Box<Self>) -> Box<[$uchar]> {
225 // SAFETY: from_raw pointer is from into_raw
226 unsafe { Box::from_raw(Box::into_raw(self) as *mut [$uchar]) }
227 }
228
229 /// Converts a boxed string slice into an owned UTF string without copying or
230 /// allocating.
231 #[inline]
232 #[cfg(feature = "alloc")]
233 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
234 #[must_use]
235 pub fn into_utfstring(self: Box<Self>) -> $utfstring {
236 unsafe { $utfstring::from_vec_unchecked(self.into_boxed_slice().into_vec()) }
237 }
238
239 /// Creates a new owned string by repeating this string `n` times.
240 ///
241 /// # Panics
242 ///
243 /// This function will panic if the capacity would overflow.
244 #[inline]
245 #[cfg(feature = "alloc")]
246 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
247 #[must_use]
248 pub fn repeat(&self, n: usize) -> $utfstring {
249 unsafe { $utfstring::from_vec_unchecked(self.as_slice().repeat(n)) }
250 }
251 }
252
253 impl AsMut<$utfstr> for $utfstr {
254 #[inline]
255 fn as_mut(&mut self) -> &mut $utfstr {
256 self
257 }
258 }
259
260 impl AsRef<$utfstr> for $utfstr {
261 #[inline]
262 fn as_ref(&self) -> &$utfstr {
263 self
264 }
265 }
266
267 impl AsRef<[$uchar]> for $utfstr {
268 #[inline]
269 fn as_ref(&self) -> &[$uchar] {
270 self.as_slice()
271 }
272 }
273
274 impl AsRef<$ustr> for $utfstr {
275 #[inline]
276 fn as_ref(&self) -> &$ustr {
277 self.as_ustr()
278 }
279 }
280
281 impl core::fmt::Debug for $utfstr {
282 #[inline]
283 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
284 f.write_char('"')?;
285 self.escape_debug().try_for_each(|c| f.write_char(c))?;
286 f.write_char('"')
287 }
288 }
289
290 impl Default for &$utfstr {
291 #[inline]
292 fn default() -> Self {
293 // SAFETY: Empty slice is always valid
294 unsafe { $utfstr::from_slice_unchecked(&[]) }
295 }
296 }
297
298 impl Default for &mut $utfstr {
299 #[inline]
300 fn default() -> Self {
301 // SAFETY: Empty slice is valways valid
302 unsafe { $utfstr::from_slice_unchecked_mut(&mut []) }
303 }
304 }
305
306 impl core::fmt::Display for $utfstr {
307 #[inline]
308 fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
309 self.chars().try_for_each(|c| f.write_char(c))
310 }
311 }
312
313 #[cfg(feature = "alloc")]
314 impl From<Box<$utfstr>> for Box<[$uchar]> {
315 #[inline]
316 fn from(value: Box<$utfstr>) -> Self {
317 value.into_boxed_slice()
318 }
319 }
320
321 impl<'a> From<&'a $utfstr> for &'a $ustr {
322 #[inline]
323 fn from(value: &'a $utfstr) -> Self {
324 value.as_ustr()
325 }
326 }
327
328 impl<'a> From<&'a $utfstr> for &'a [$uchar] {
329 #[inline]
330 fn from(value: &'a $utfstr) -> Self {
331 value.as_slice()
332 }
333 }
334
335 #[cfg(feature = "std")]
336 impl From<&$utfstr> for std::ffi::OsString {
337 #[inline]
338 fn from(value: &$utfstr) -> std::ffi::OsString {
339 value.as_ustr().to_os_string()
340 }
341 }
342
343 impl PartialEq<$utfstr> for &$utfstr {
344 #[inline]
345 fn eq(&self, other: &$utfstr) -> bool {
346 self.as_slice() == other.as_slice()
347 }
348 }
349
350 #[cfg(feature = "alloc")]
351 impl<'a, 'b> PartialEq<Cow<'a, $utfstr>> for &'b $utfstr {
352 #[inline]
353 fn eq(&self, other: &Cow<'a, $utfstr>) -> bool {
354 self == other.as_ref()
355 }
356 }
357
358 #[cfg(feature = "alloc")]
359 impl PartialEq<$utfstr> for Cow<'_, $utfstr> {
360 #[inline]
361 fn eq(&self, other: &$utfstr) -> bool {
362 self.as_ref() == other
363 }
364 }
365
366 #[cfg(feature = "alloc")]
367 impl<'a, 'b> PartialEq<&'a $utfstr> for Cow<'b, $utfstr> {
368 #[inline]
369 fn eq(&self, other: &&'a $utfstr) -> bool {
370 self.as_ref() == *other
371 }
372 }
373
374 impl PartialEq<$ustr> for $utfstr {
375 #[inline]
376 fn eq(&self, other: &$ustr) -> bool {
377 self.as_slice() == other.as_slice()
378 }
379 }
380
381 impl PartialEq<$utfstr> for $ustr {
382 #[inline]
383 fn eq(&self, other: &$utfstr) -> bool {
384 self.as_slice() == other.as_slice()
385 }
386 }
387
388 impl PartialEq<crate::$ucstr> for $utfstr {
389 #[inline]
390 fn eq(&self, other: &crate::$ucstr) -> bool {
391 self.as_slice() == other.as_slice()
392 }
393 }
394
395 impl PartialEq<$utfstr> for crate::$ucstr {
396 #[inline]
397 fn eq(&self, other: &$utfstr) -> bool {
398 self.as_slice() == other.as_slice()
399 }
400 }
401
402 impl PartialEq<str> for $utfstr {
403 #[inline]
404 fn eq(&self, other: &str) -> bool {
405 self.chars().eq(other.chars())
406 }
407 }
408
409 impl PartialEq<&str> for $utfstr {
410 #[inline]
411 fn eq(&self, other: &&str) -> bool {
412 self.chars().eq(other.chars())
413 }
414 }
415
416 impl PartialEq<str> for &$utfstr {
417 #[inline]
418 fn eq(&self, other: &str) -> bool {
419 self.chars().eq(other.chars())
420 }
421 }
422
423 impl PartialEq<$utfstr> for str {
424 #[inline]
425 fn eq(&self, other: &$utfstr) -> bool {
426 self.chars().eq(other.chars())
427 }
428 }
429
430 impl PartialEq<$utfstr> for &str {
431 #[inline]
432 fn eq(&self, other: &$utfstr) -> bool {
433 self.chars().eq(other.chars())
434 }
435 }
436
437 #[cfg(feature = "alloc")]
438 impl<'a, 'b> PartialEq<Cow<'a, str>> for &'b $utfstr {
439 #[inline]
440 fn eq(&self, other: &Cow<'a, str>) -> bool {
441 self == other.as_ref()
442 }
443 }
444
445 #[cfg(feature = "alloc")]
446 impl PartialEq<$utfstr> for Cow<'_, str> {
447 #[inline]
448 fn eq(&self, other: &$utfstr) -> bool {
449 self.as_ref() == other
450 }
451 }
452
453 #[cfg(feature = "alloc")]
454 impl<'a, 'b> PartialEq<&'a $utfstr> for Cow<'b, str> {
455 #[inline]
456 fn eq(&self, other: &&'a $utfstr) -> bool {
457 self.as_ref() == *other
458 }
459 }
460
461 impl<'a> TryFrom<&'a $ustr> for &'a $utfstr {
462 type Error = $utferror;
463
464 #[inline]
465 fn try_from(value: &'a $ustr) -> Result<Self, Self::Error> {
466 $utfstr::from_ustr(value)
467 }
468 }
469
470 impl<'a> TryFrom<&'a crate::$ucstr> for &'a $utfstr {
471 type Error = $utferror;
472
473 #[inline]
474 fn try_from(value: &'a crate::$ucstr) -> Result<Self, Self::Error> {
475 $utfstr::from_ucstr(value)
476 }
477 }
478 };
479 }
480
481 utfstr_common_impl! {
482 /// UTF-16 string slice for [`Utf16String`][crate::Utf16String].
483 ///
484 /// [`Utf16Str`] is to [`Utf16String`][crate::Utf16String] as [`str`] is to [`String`].
485 ///
486 /// [`Utf16Str`] slices are string slices that are always valid UTF-16 encoding. This is unlike
487 /// the [`U16Str`][crate::U16Str] string slices, which may not have valid encoding. In this way,
488 /// [`Utf16Str`] string slices most resemble native [`str`] slices of all the types in this
489 /// crate.
490 ///
491 /// # Examples
492 ///
493 /// The easiest way to use [`Utf16Str`] is with the [`utf16str!`][crate::utf16str] macro to
494 /// convert string literals into string slices at compile time:
495 ///
496 /// ```
497 /// use widestring::utf16str;
498 /// let hello = utf16str!("Hello, world!");
499 /// ```
500 ///
501 /// You can also convert a [`u16`] slice directly, provided it is valid UTF-16:
502 ///
503 /// ```
504 /// use widestring::Utf16Str;
505 ///
506 /// let sparkle_heart = [0xd83d, 0xdc96];
507 /// let sparkle_heart = Utf16Str::from_slice(&sparkle_heart).unwrap();
508 ///
509 /// assert_eq!("💖", sparkle_heart);
510 /// ```
511 struct Utf16Str([u16]);
512
513 type UtfString = Utf16String;
514 type UStr = U16Str;
515 type UCStr = U16CStr;
516 type UtfError = Utf16Error;
517
518 /// Converts a slice to a string slice without checking that the string contains valid UTF-16.
519 ///
520 /// See the safe version, [`from_slice`][Self::from_slice], for more information.
521 ///
522 /// # Safety
523 ///
524 /// This function is unsafe because it does not check that the slice passed to it is valid
525 /// UTF-16. If this constraint is violated, undefined behavior results as it is assumed the
526 /// [`Utf16Str`] is always valid UTF-16.
527 ///
528 /// # Examples
529 ///
530 /// ```
531 /// use widestring::Utf16Str;
532 ///
533 /// let sparkle_heart = vec![0xd83d, 0xdc96]; // Raw surrogate pair
534 /// let sparkle_heart = unsafe { Utf16Str::from_slice_unchecked(&sparkle_heart) };
535 ///
536 /// assert_eq!("💖", sparkle_heart);
537 /// ```
538 fn from_slice_unchecked() -> {}
539
540 /// Converts a mutable slice to a mutable string slice without checking that the string contains
541 /// valid UTF-16.
542 ///
543 /// See the safe version, [`from_slice_mut`][Self::from_slice_mut], for more information.
544 ///
545 /// # Safety
546 ///
547 /// This function is unsafe because it does not check that the slice passed to it is valid
548 /// UTF-16. If this constraint is violated, undefined behavior results as it is assumed the
549 /// [`Utf16Str`] is always valid UTF-16.
550 ///
551 /// # Examples
552 ///
553 /// ```
554 /// use widestring::Utf16Str;
555 ///
556 /// let mut sparkle_heart = vec![0xd83d, 0xdc96]; // Raw surrogate pair
557 /// let sparkle_heart = unsafe { Utf16Str::from_slice_unchecked_mut(&mut sparkle_heart) };
558 ///
559 /// assert_eq!("💖", sparkle_heart);
560 /// ```
561 fn from_slice_unchecked_mut() -> {}
562
563 /// Converts a boxed slice to a boxed string slice without checking that the string contains
564 /// valid UTF-16.
565 ///
566 /// # Safety
567 ///
568 /// This function is unsafe because it does not check if the string slice is valid UTF-16, and
569 /// [`Utf16Str`] must always be valid UTF-16.
570 fn from_boxed_slice_unchecked() -> {}
571
572 /// Returns an unchecked subslice of this string slice.
573 ///
574 /// This is the unchecked alternative to indexing the string slice.
575 ///
576 /// # Safety
577 ///
578 /// Callers of this function are responsible that these preconditions are satisfied:
579 ///
580 /// - The starting index must not exceed the ending index;
581 /// - Indexes must be within bounds of the original slice;
582 /// - Indexes must lie on UTF-16 sequence boundaries.
583 ///
584 /// Failing that, the returned string slice may reference invalid memory or violate the
585 /// invariants communicated by the type.
586 ///
587 /// # Examples
588 ///
589 /// ```
590 /// # use widestring::{utf16str};
591 /// let v = utf16str!("⚧️🏳️‍⚧️➡️s");
592 /// unsafe {
593 /// assert_eq!(utf16str!("⚧️"), v.get_unchecked(..2));
594 /// assert_eq!(utf16str!("🏳️‍⚧️"), v.get_unchecked(2..8));
595 /// assert_eq!(utf16str!("➡️"), v.get_unchecked(8..10));
596 /// assert_eq!(utf16str!("s"), v.get_unchecked(10..));
597 /// }
598 /// ```
599 fn get_unchecked() -> {}
600
601 /// Returns a mutable, unchecked subslice of this string slice
602 ///
603 /// This is the unchecked alternative to indexing the string slice.
604 ///
605 /// # Safety
606 ///
607 /// Callers of this function are responsible that these preconditions are satisfied:
608 ///
609 /// - The starting index must not exceed the ending index;
610 /// - Indexes must be within bounds of the original slice;
611 /// - Indexes must lie on UTF-16 sequence boundaries.
612 ///
613 /// Failing that, the returned string slice may reference invalid memory or violate the
614 /// invariants communicated by the type.
615 ///
616 /// # Examples
617 ///
618 /// ```
619 /// # use widestring::{utf16str};
620 /// # #[cfg(feature = "alloc")] {
621 /// let mut v = utf16str!("⚧️🏳️‍⚧️➡️s").to_owned();
622 /// unsafe {
623 /// assert_eq!(utf16str!("⚧️"), v.get_unchecked_mut(..2));
624 /// assert_eq!(utf16str!("🏳️‍⚧️"), v.get_unchecked_mut(2..8));
625 /// assert_eq!(utf16str!("➡️"), v.get_unchecked_mut(8..10));
626 /// assert_eq!(utf16str!("s"), v.get_unchecked_mut(10..));
627 /// }
628 /// # }
629 /// ```
630 fn get_unchecked_mut() -> {}
631
632 /// Returns the length of `self`.
633 ///
634 /// This length is in `u16` values, not [`char`]s or graphemes. In other words, it may not be
635 /// what human considers the length of the string.
636 ///
637 /// # Examples
638 ///
639 /// ```
640 /// # use widestring::utf16str;
641 /// assert_eq!(utf16str!("foo").len(), 3);
642 ///
643 /// let complex = utf16str!("⚧️🏳️‍⚧️➡️s");
644 /// assert_eq!(complex.len(), 11);
645 /// assert_eq!(complex.chars().count(), 10);
646 /// ```
647 fn len() -> {}
648 }
649
650 utfstr_common_impl! {
651 /// UTF-32 string slice for [`Utf32String`][crate::Utf32String].
652 ///
653 /// [`Utf32Str`] is to [`Utf32String`][crate::Utf32String] as [`str`] is to [`String`].
654 ///
655 /// [`Utf32Str`] slices are string slices that are always valid UTF-32 encoding. This is unlike
656 /// the [`U32Str`][crate::U16Str] string slices, which may not have valid encoding. In this way,
657 /// [`Utf32Str`] string slices most resemble native [`str`] slices of all the types in this
658 /// crate.
659 ///
660 /// # Examples
661 ///
662 /// The easiest way to use [`Utf32Str`] is with the [`utf32str!`][crate::utf32str] macro to
663 /// convert string literals into string slices at compile time:
664 ///
665 /// ```
666 /// use widestring::utf32str;
667 /// let hello = utf32str!("Hello, world!");
668 /// ```
669 ///
670 /// You can also convert a [`u32`] slice directly, provided it is valid UTF-32:
671 ///
672 /// ```
673 /// use widestring::Utf32Str;
674 ///
675 /// let sparkle_heart = [0x1f496];
676 /// let sparkle_heart = Utf32Str::from_slice(&sparkle_heart).unwrap();
677 ///
678 /// assert_eq!("💖", sparkle_heart);
679 /// ```
680 ///
681 /// Since [`char`] slices are valid UTF-32, a slice of [`char`]s can be easily converted to a
682 /// string slice:
683 ///
684 /// ```
685 /// use widestring::Utf32Str;
686 ///
687 /// let sparkle_heart = ['💖'; 3];
688 /// let sparkle_heart = Utf32Str::from_char_slice(&sparkle_heart);
689 ///
690 /// assert_eq!("💖💖💖", sparkle_heart);
691 /// ```
692 struct Utf32Str([u32]);
693
694 type UtfString = Utf32String;
695 type UStr = U32Str;
696 type UCStr = U32CStr;
697 type UtfError = Utf32Error;
698
699 /// Converts a slice to a string slice without checking that the string contains valid UTF-32.
700 ///
701 /// See the safe version, [`from_slice`][Self::from_slice], for more information.
702 ///
703 /// # Safety
704 ///
705 /// This function is unsafe because it does not check that the slice passed to it is valid
706 /// UTF-32. If this constraint is violated, undefined behavior results as it is assumed the
707 /// [`Utf32Str`] is always valid UTF-32.
708 ///
709 /// # Examples
710 ///
711 /// ```
712 /// use widestring::Utf32Str;
713 ///
714 /// let sparkle_heart = vec![0x1f496];
715 /// let sparkle_heart = unsafe { Utf32Str::from_slice_unchecked(&sparkle_heart) };
716 ///
717 /// assert_eq!("💖", sparkle_heart);
718 /// ```
719 fn from_slice_unchecked() -> {}
720
721 /// Converts a mutable slice to a mutable string slice without checking that the string contains
722 /// valid UTF-32.
723 ///
724 /// See the safe version, [`from_slice_mut`][Self::from_slice_mut], for more information.
725 ///
726 /// # Safety
727 ///
728 /// This function is unsafe because it does not check that the slice passed to it is valid
729 /// UTF-32. If this constraint is violated, undefined behavior results as it is assumed the
730 /// [`Utf32Str`] is always valid UTF-32.
731 ///
732 /// # Examples
733 ///
734 /// ```
735 /// use widestring::Utf32Str;
736 ///
737 /// let mut sparkle_heart = vec![0x1f496];
738 /// let sparkle_heart = unsafe { Utf32Str::from_slice_unchecked_mut(&mut sparkle_heart) };
739 ///
740 /// assert_eq!("💖", sparkle_heart);
741 /// ```
742 fn from_slice_unchecked_mut() -> {}
743
744 /// Converts a boxed slice to a boxed string slice without checking that the string contains
745 /// valid UTF-32.
746 ///
747 /// # Safety
748 ///
749 /// This function is unsafe because it does not check if the string slice is valid UTF-32, and
750 /// [`Utf32Str`] must always be valid UTF-32.
751 fn from_boxed_slice_unchecked() -> {}
752
753 /// Returns an unchecked subslice of this string slice.
754 ///
755 /// This is the unchecked alternative to indexing the string slice.
756 ///
757 /// # Safety
758 ///
759 /// Callers of this function are responsible that these preconditions are satisfied:
760 ///
761 /// - The starting index must not exceed the ending index;
762 /// - Indexes must be within bounds of the original slice;
763 ///
764 /// Failing that, the returned string slice may reference invalid memory or violate the
765 /// invariants communicated by the type.
766 ///
767 /// # Examples
768 ///
769 /// ```
770 /// # use widestring::utf32str;
771 /// let v = utf32str!("⚧️🏳️‍⚧️➡️s");
772 /// unsafe {
773 /// assert_eq!(utf32str!("⚧️"), v.get_unchecked(..2));
774 /// assert_eq!(utf32str!("🏳️‍⚧️"), v.get_unchecked(2..7));
775 /// assert_eq!(utf32str!("➡️"), v.get_unchecked(7..9));
776 /// assert_eq!(utf32str!("s"), v.get_unchecked(9..))
777 /// }
778 /// ```
779 fn get_unchecked() -> {}
780
781 /// Returns a mutable, unchecked subslice of this string slice
782 ///
783 /// This is the unchecked alternative to indexing the string slice.
784 ///
785 /// # Safety
786 ///
787 /// Callers of this function are responsible that these preconditions are satisfied:
788 ///
789 /// - The starting index must not exceed the ending index;
790 /// - Indexes must be within bounds of the original slice;
791 ///
792 /// Failing that, the returned string slice may reference invalid memory or violate the
793 /// invariants communicated by the type.
794 ///
795 /// # Examples
796 ///
797 /// ```
798 /// # use widestring::utf32str;
799 /// # #[cfg(feature = "alloc")] {
800 /// let mut v = utf32str!("⚧️🏳️‍⚧️➡️s").to_owned();
801 /// unsafe {
802 /// assert_eq!(utf32str!("⚧️"), v.get_unchecked_mut(..2));
803 /// assert_eq!(utf32str!("🏳️‍⚧️"), v.get_unchecked_mut(2..7));
804 /// assert_eq!(utf32str!("➡️"), v.get_unchecked_mut(7..9));
805 /// assert_eq!(utf32str!("s"), v.get_unchecked_mut(9..))
806 /// }
807 /// # }
808 /// ```
809 fn get_unchecked_mut() -> {}
810
811 /// Returns the length of `self`.
812 ///
813 /// This length is in the number of [`char`]s in the slice, not graphemes. In other words, it
814 /// may not be what human considers the length of the string.
815 ///
816 /// # Examples
817 ///
818 /// ```
819 /// # use widestring::utf32str;
820 /// assert_eq!(utf32str!("foo").len(), 3);
821 ///
822 /// let complex = utf32str!("⚧️🏳️‍⚧️➡️s");
823 /// assert_eq!(complex.len(), 10);
824 /// assert_eq!(complex.chars().count(), 10);
825 /// ```
826 fn len() -> {}
827 }
828
829 impl Utf16Str {
830 /// Converts a slice of UTF-16 data to a string slice.
831 ///
832 /// Not all slices of [`u16`] values are valid to convert, since [`Utf16Str`] requires that it
833 /// is always valid UTF-16. This function checks to ensure that the values are valid UTF-16, and
834 /// then does the conversion.
835 ///
836 /// If you are sure that the slice is valid UTF-16, and you don't want to incur the overhead of
837 /// the validity check, there is an unsafe version of this function,
838 /// [`from_slice_unchecked`][Self::from_slice_unchecked], which has the same behavior but skips
839 /// the check.
840 ///
841 /// If you need an owned string, consider using [`Utf16String::from_vec`] instead.
842 ///
843 /// Because you can stack-allocate a `[u16; N]`, this function is one way to have a
844 /// stack-allocated string. Indeed, the [`utf16str!`][crate::utf16str] macro does exactly this
845 /// after converting from UTF-8 to UTF-16.
846 ///
847 /// # Errors
848 ///
849 /// Returns an error if the slice is not UTF-16 with a description as to why the provided slice
850 /// is not UTF-16.
851 ///
852 /// # Examples
853 ///
854 /// ```
855 /// use widestring::Utf16Str;
856 ///
857 /// let sparkle_heart = vec![0xd83d, 0xdc96]; // Raw surrogate pair
858 /// let sparkle_heart = Utf16Str::from_slice(&sparkle_heart).unwrap();
859 ///
860 /// assert_eq!("💖", sparkle_heart);
861 /// ```
862 ///
863 /// With incorrect values that return an error:
864 ///
865 /// ```
866 /// use widestring::Utf16Str;
867 ///
868 /// let sparkle_heart = vec![0xd83d, 0x0]; // This is an invalid unpaired surrogate
869 ///
870 /// assert!(Utf16Str::from_slice(&sparkle_heart).is_err());
871 /// ```
872 pub fn from_slice(s: &[u16]) -> Result<&Self, Utf16Error> {
873 validate_utf16(s)?;
874 // SAFETY: Just validated
875 Ok(unsafe { Self::from_slice_unchecked(s) })
876 }
877
878 /// Converts a mutable slice of UTF-16 data to a mutable string slice.
879 ///
880 /// Not all slices of [`u16`] values are valid to convert, since [`Utf16Str`] requires that it
881 /// is always valid UTF-16. This function checks to ensure that the values are valid UTF-16, and
882 /// then does the conversion.
883 ///
884 /// If you are sure that the slice is valid UTF-16, and you don't want to incur the overhead of
885 /// the validity check, there is an unsafe version of this function,
886 /// [`from_slice_unchecked_mut`][Self::from_slice_unchecked_mut], which has the same behavior
887 /// but skips the check.
888 ///
889 /// If you need an owned string, consider using [`Utf16String::from_vec`] instead.
890 ///
891 /// Because you can stack-allocate a `[u16; N]`, this function is one way to have a
892 /// stack-allocated string. Indeed, the [`utf16str!`][crate::utf16str] macro does exactly this
893 /// after converting from UTF-8 to UTF-16.
894 ///
895 /// # Errors
896 ///
897 /// Returns an error if the slice is not UTF-16 with a description as to why the provided slice
898 /// is not UTF-16.
899 ///
900 /// # Examples
901 ///
902 /// ```
903 /// use widestring::Utf16Str;
904 ///
905 /// let mut sparkle_heart = vec![0xd83d, 0xdc96]; // Raw surrogate pair
906 /// let sparkle_heart = Utf16Str::from_slice_mut(&mut sparkle_heart).unwrap();
907 ///
908 /// assert_eq!("💖", sparkle_heart);
909 /// ```
910 ///
911 /// With incorrect values that return an error:
912 ///
913 /// ```
914 /// use widestring::Utf16Str;
915 ///
916 /// let mut sparkle_heart = vec![0xd83d, 0x0]; // This is an invalid unpaired surrogate
917 ///
918 /// assert!(Utf16Str::from_slice_mut(&mut sparkle_heart).is_err());
919 /// ```
920 pub fn from_slice_mut(s: &mut [u16]) -> Result<&mut Self, Utf16Error> {
921 validate_utf16(s)?;
922 // SAFETY: Just validated
923 Ok(unsafe { Self::from_slice_unchecked_mut(s) })
924 }
925
926 /// Converts a wide string slice of undefined encoding to a UTF-16 string slice without checking
927 /// if the string slice is valid UTF-16.
928 ///
929 /// See the safe version, [`from_ustr`][Self::from_ustr], for more information.
930 ///
931 /// # Safety
932 ///
933 /// This function is unsafe because it does not check that the string slice passed to it is
934 /// valid UTF-16. If this constraint is violated, undefined behavior results as it is assumed
935 /// the [`Utf16Str`] is always valid UTF-16.
936 ///
937 /// # Examples
938 ///
939 /// ```
940 /// use widestring::{Utf16Str, u16str};
941 ///
942 /// let sparkle_heart = u16str!("💖");
943 /// let sparkle_heart = unsafe { Utf16Str::from_ustr_unchecked(sparkle_heart) };
944 ///
945 /// assert_eq!("💖", sparkle_heart);
946 /// ```
947 #[must_use]
948 pub const unsafe fn from_ustr_unchecked(s: &U16Str) -> &Self {
949 Self::from_slice_unchecked(s.as_slice())
950 }
951
952 /// Converts a mutable wide string slice of undefined encoding to a mutable UTF-16 string slice
953 /// without checking if the string slice is valid UTF-16.
954 ///
955 /// See the safe version, [`from_ustr_mut`][Self::from_ustr_mut], for more information.
956 ///
957 /// # Safety
958 ///
959 /// This function is unsafe because it does not check that the string slice passed to it is
960 /// valid UTF-16. If this constraint is violated, undefined behavior results as it is assumed
961 /// the [`Utf16Str`] is always valid UTF-16.
962 #[must_use]
963 pub unsafe fn from_ustr_unchecked_mut(s: &mut U16Str) -> &mut Self {
964 Self::from_slice_unchecked_mut(s.as_mut_slice())
965 }
966
967 /// Converts a wide string slice of undefined encoding to a UTF-16 string slice.
968 ///
969 /// Since [`U16Str`] does not have a specified encoding, this conversion may fail if the
970 /// [`U16Str`] does not contain valid UTF-16 data.
971 ///
972 /// If you are sure that the slice is valid UTF-16, and you don't want to incur the overhead of
973 /// the validity check, there is an unsafe version of this function,
974 /// [`from_ustr_unchecked`][Self::from_ustr_unchecked], which has the same behavior
975 /// but skips the check.
976 ///
977 /// # Errors
978 ///
979 /// Returns an error if the string slice is not UTF-16 with a description as to why the
980 /// provided string slice is not UTF-16.
981 ///
982 /// # Examples
983 ///
984 /// ```
985 /// use widestring::{Utf16Str, u16str};
986 ///
987 /// let sparkle_heart = u16str!("💖");
988 /// let sparkle_heart = Utf16Str::from_ustr(sparkle_heart).unwrap();
989 ///
990 /// assert_eq!("💖", sparkle_heart);
991 /// ```
992 #[inline]
993 pub fn from_ustr(s: &U16Str) -> Result<&Self, Utf16Error> {
994 Self::from_slice(s.as_slice())
995 }
996
997 /// Converts a mutable wide string slice of undefined encoding to a mutable UTF-16 string slice.
998 ///
999 /// Since [`U16Str`] does not have a specified encoding, this conversion may fail if the
1000 /// [`U16Str`] does not contain valid UTF-16 data.
1001 ///
1002 /// If you are sure that the slice is valid UTF-16, and you don't want to incur the overhead of
1003 /// the validity check, there is an unsafe version of this function,
1004 /// [`from_ustr_unchecked_mut`][Self::from_ustr_unchecked_mut], which has the same behavior
1005 /// but skips the check.
1006 ///
1007 /// # Errors
1008 ///
1009 /// Returns an error if the string slice is not UTF-16 with a description as to why the
1010 /// provided string slice is not UTF-16.
1011 #[inline]
1012 pub fn from_ustr_mut(s: &mut U16Str) -> Result<&mut Self, Utf16Error> {
1013 Self::from_slice_mut(s.as_mut_slice())
1014 }
1015
1016 /// Converts a wide C string slice to a UTF-16 string slice without checking if the
1017 /// string slice is valid UTF-16.
1018 ///
1019 /// The resulting string slice does *not* contain the nul terminator.
1020 ///
1021 /// See the safe version, [`from_ucstr`][Self::from_ucstr], for more information.
1022 ///
1023 /// # Safety
1024 ///
1025 /// This function is unsafe because it does not check that the string slice passed to it is
1026 /// valid UTF-16. If this constraint is violated, undefined behavior results as it is assumed
1027 /// the [`Utf16Str`] is always valid UTF-16.
1028 ///
1029 /// # Examples
1030 ///
1031 /// ```
1032 /// use widestring::{Utf16Str, u16cstr};
1033 ///
1034 /// let sparkle_heart = u16cstr!("💖");
1035 /// let sparkle_heart = unsafe { Utf16Str::from_ucstr_unchecked(sparkle_heart) };
1036 ///
1037 /// assert_eq!("💖", sparkle_heart);
1038 /// ```
1039 #[inline]
1040 #[must_use]
1041 pub unsafe fn from_ucstr_unchecked(s: &crate::U16CStr) -> &Self {
1042 Self::from_slice_unchecked(s.as_slice())
1043 }
1044
1045 /// Converts a mutable wide C string slice to a mutable UTF-16 string slice without
1046 /// checking if the string slice is valid UTF-16.
1047 ///
1048 /// The resulting string slice does *not* contain the nul terminator.
1049 ///
1050 /// See the safe version, [`from_ucstr_mut`][Self::from_ucstr_mut], for more information.
1051 ///
1052 /// # Safety
1053 ///
1054 /// This function is unsafe because it does not check that the string slice passed to it is
1055 /// valid UTF-16. If this constraint is violated, undefined behavior results as it is assumed
1056 /// the [`Utf16Str`] is always valid UTF-16.
1057 #[inline]
1058 #[must_use]
1059 pub unsafe fn from_ucstr_unchecked_mut(s: &mut crate::U16CStr) -> &mut Self {
1060 Self::from_slice_unchecked_mut(s.as_mut_slice())
1061 }
1062
1063 /// Converts a wide C string slice to a UTF-16 string slice.
1064 ///
1065 /// The resulting string slice does *not* contain the nul terminator.
1066 ///
1067 /// Since [`U16CStr`][crate::U16CStr] does not have a specified encoding, this conversion may
1068 /// fail if the [`U16CStr`][crate::U16CStr] does not contain valid UTF-16 data.
1069 ///
1070 /// If you are sure that the slice is valid UTF-16, and you don't want to incur the overhead of
1071 /// the validity check, there is an unsafe version of this function,
1072 /// [`from_ucstr_unchecked`][Self::from_ucstr_unchecked], which has the same behavior
1073 /// but skips the check.
1074 ///
1075 /// # Errors
1076 ///
1077 /// Returns an error if the string slice is not UTF-16 with a description as to why the
1078 /// provided string slice is not UTF-16.
1079 ///
1080 /// # Examples
1081 ///
1082 /// ```
1083 /// use widestring::{Utf16Str, u16cstr};
1084 ///
1085 /// let sparkle_heart = u16cstr!("💖");
1086 /// let sparkle_heart = Utf16Str::from_ucstr(sparkle_heart).unwrap();
1087 ///
1088 /// assert_eq!("💖", sparkle_heart);
1089 /// ```
1090 #[inline]
1091 pub fn from_ucstr(s: &crate::U16CStr) -> Result<&Self, Utf16Error> {
1092 Self::from_slice(s.as_slice())
1093 }
1094
1095 /// Converts a mutable wide C string slice to a mutable UTF-16 string slice.
1096 ///
1097 /// The resulting string slice does *not* contain the nul terminator.
1098 ///
1099 /// Since [`U16CStr`][crate::U16CStr] does not have a specified encoding, this conversion may
1100 /// fail if the [`U16CStr`][crate::U16CStr] does not contain valid UTF-16 data.
1101 ///
1102 /// If you are sure that the slice is valid UTF-16, and you don't want to incur the overhead of
1103 /// the validity check, there is an unsafe version of this function,
1104 /// [`from_ucstr_unchecked_mut`][Self::from_ucstr_unchecked_mut], which has the same behavior
1105 /// but skips the check.
1106 ///
1107 /// # Safety
1108 ///
1109 /// This method is unsafe because you can violate the invariants of [`U16CStr`][crate::U16CStr]
1110 /// when mutating the slice (i.e. by adding interior nul values).
1111 ///
1112 /// # Errors
1113 ///
1114 /// Returns an error if the string slice is not UTF-16 with a description as to why the
1115 /// provided string slice is not UTF-16.
1116 #[inline]
1117 pub unsafe fn from_ucstr_mut(s: &mut crate::U16CStr) -> Result<&mut Self, Utf16Error> {
1118 Self::from_slice_mut(s.as_mut_slice())
1119 }
1120
1121 /// Converts to a standard UTF-8 [`String`].
1122 ///
1123 /// Because this string is always valid UTF-16, the conversion is lossless and non-fallible.
1124 #[inline]
1125 #[allow(clippy::inherent_to_string_shadow_display)]
1126 #[cfg(feature = "alloc")]
1127 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
1128 #[must_use]
1129 pub fn to_string(&self) -> String {
1130 String::from_utf16(self.as_slice()).unwrap()
1131 }
1132
1133 /// Checks that `index`-th value is the value in a UTF-16 code point sequence or the end of the
1134 /// string.
1135 ///
1136 /// Returns `true` if the value at `index` is not a UTF-16 surrogate value, or if the value at
1137 /// `index` is the first value of a surrogate pair (the "high" surrogate). Returns `false` if
1138 /// the value at `index` is the second value of a surrogate pair (a.k.a the "low" surrogate).
1139 ///
1140 /// The start and end of the string (when `index == self.len()`) are considered to be
1141 /// boundaries.
1142 ///
1143 /// Returns `false` if `index is greater than `self.len()`.
1144 ///
1145 /// # Examples
1146 ///
1147 /// ```
1148 /// # use widestring::utf16str;
1149 /// let s = utf16str!("Sparkle 💖 Heart");
1150 /// assert!(s.is_char_boundary(0));
1151 ///
1152 /// // high surrogate of `💖`
1153 /// assert!(s.is_char_boundary(8));
1154 /// // low surrogate of `💖`
1155 /// assert!(!s.is_char_boundary(9));
1156 ///
1157 /// assert!(s.is_char_boundary(s.len()));
1158 /// ```
1159 #[inline]
1160 #[must_use]
1161 pub const fn is_char_boundary(&self, index: usize) -> bool {
1162 if index > self.len() {
1163 false
1164 } else if index == self.len() {
1165 true
1166 } else {
1167 !is_utf16_low_surrogate(self.inner[index])
1168 }
1169 }
1170
1171 /// Returns a subslice of this string.
1172 ///
1173 /// This is the non-panicking alternative to indexing the string. Returns [`None`] whenever
1174 /// equivalent indexing operation would panic.
1175 ///
1176 /// # Examples
1177 ///
1178 /// ```
1179 /// # use widestring::{utf16str};
1180 /// let v = utf16str!("⚧️🏳️‍⚧️➡️s");
1181 ///
1182 /// assert_eq!(Some(utf16str!("⚧️")), v.get(..2));
1183 /// assert_eq!(Some(utf16str!("🏳️‍⚧️")), v.get(2..8));
1184 /// assert_eq!(Some(utf16str!("➡️")), v.get(8..10));
1185 /// assert_eq!(Some(utf16str!("s")), v.get(10..));
1186 ///
1187 /// assert!(v.get(3..4).is_none());
1188 /// ```
1189 #[inline]
1190 #[must_use]
1191 pub fn get<I>(&self, index: I) -> Option<&Self>
1192 where
1193 I: RangeBounds<usize> + SliceIndex<[u16], Output = [u16]>,
1194 {
1195 // TODO: Use SliceIndex directly when it is stabilized
1196 let range = crate::range_check(index, ..self.len())?;
1197 if !self.is_char_boundary(range.start) || !self.is_char_boundary(range.end) {
1198 return None;
1199 }
1200
1201 // SAFETY: range_check verified bounds, and we just verified char boundaries
1202 Some(unsafe { self.get_unchecked(range) })
1203 }
1204
1205 /// Returns a mutable subslice of this string.
1206 ///
1207 /// This is the non-panicking alternative to indexing the string. Returns [`None`] whenever
1208 /// equivalent indexing operation would panic.
1209 ///
1210 /// # Examples
1211 ///
1212 /// ```
1213 /// # use widestring::{utf16str};
1214 /// # #[cfg(feature = "alloc")] {
1215 /// let mut v = utf16str!("⚧️🏳️‍⚧️➡️s").to_owned();
1216 ///
1217 /// assert_eq!(utf16str!("⚧️"), v.get_mut(..2).unwrap());
1218 /// assert_eq!(utf16str!("🏳️‍⚧️"), v.get_mut(2..8).unwrap());
1219 /// assert_eq!(utf16str!("➡️"), v.get_mut(8..10).unwrap());
1220 /// assert_eq!(utf16str!("s"), v.get_mut(10..).unwrap());
1221 ///
1222 /// assert!(v.get_mut(3..4).is_none());
1223 /// # }
1224 /// ```
1225 #[inline]
1226 #[must_use]
1227 pub fn get_mut<I>(&mut self, index: I) -> Option<&mut Self>
1228 where
1229 I: RangeBounds<usize> + SliceIndex<[u16], Output = [u16]>,
1230 {
1231 // TODO: Use SliceIndex directly when it is stabilized
1232 let range = crate::range_check(index, ..self.len())?;
1233 if !self.is_char_boundary(range.start) || !self.is_char_boundary(range.end) {
1234 return None;
1235 }
1236
1237 // SAFETY: range_check verified bounds, and we just verified char boundaries
1238 Some(unsafe { self.get_unchecked_mut(range) })
1239 }
1240
1241 /// Divide one string slice into two at an index.
1242 ///
1243 /// The argument, `mid`, should be an offset from the start of the string. It must also be on
1244 /// the boundary of a UTF-16 code point.
1245 ///
1246 /// The two slices returned go from the start of the string slice to `mid`, and from `mid` to
1247 /// the end of the string slice.
1248 ///
1249 /// To get mutable string slices instead, see the [`split_at_mut`][Self::split_at_mut] method.
1250 ///
1251 /// # Panics
1252 ///
1253 /// Panics if `mid` is not on a UTF-16 code point boundary, or if it is past the end of the last
1254 /// code point of the string slice.
1255 ///
1256 /// # Examples
1257 ///
1258 /// ```
1259 /// # use widestring::utf16str;
1260 /// let s = utf16str!("Per Martin-Löf");
1261 ///
1262 /// let (first, last) = s.split_at(3);
1263 ///
1264 /// assert_eq!("Per", first);
1265 /// assert_eq!(" Martin-Löf", last);
1266 /// ```
1267 #[inline]
1268 #[must_use]
1269 pub fn split_at(&self, mid: usize) -> (&Self, &Self) {
1270 assert!(self.is_char_boundary(mid));
1271 let (a, b) = self.inner.split_at(mid);
1272 unsafe { (Self::from_slice_unchecked(a), Self::from_slice_unchecked(b)) }
1273 }
1274
1275 /// Divide one mutable string slice into two at an index.
1276 ///
1277 /// The argument, `mid`, should be an offset from the start of the string. It must also be on
1278 /// the boundary of a UTF-16 code point.
1279 ///
1280 /// The two slices returned go from the start of the string slice to `mid`, and from `mid` to
1281 /// the end of the string slice.
1282 ///
1283 /// To get immutable string slices instead, see the [`split_at`][Self::split_at] method.
1284 ///
1285 /// # Panics
1286 ///
1287 /// Panics if `mid` is not on a UTF-16 code point boundary, or if it is past the end of the last
1288 /// code point of the string slice.
1289 ///
1290 /// # Examples
1291 ///
1292 /// ```
1293 /// # use widestring::utf16str;
1294 /// # #[cfg(feature = "alloc")] {
1295 /// let mut s = utf16str!("Per Martin-Löf").to_owned();
1296 ///
1297 /// let (first, last) = s.split_at_mut(3);
1298 ///
1299 /// assert_eq!("Per", first);
1300 /// assert_eq!(" Martin-Löf", last);
1301 /// # }
1302 /// ```
1303 #[inline]
1304 #[must_use]
1305 pub fn split_at_mut(&mut self, mid: usize) -> (&mut Self, &mut Self) {
1306 assert!(self.is_char_boundary(mid));
1307 let (a, b) = self.inner.split_at_mut(mid);
1308 unsafe {
1309 (
1310 Self::from_slice_unchecked_mut(a),
1311 Self::from_slice_unchecked_mut(b),
1312 )
1313 }
1314 }
1315
1316 /// Returns an iterator over the [`char`]s of a string slice.
1317 ///
1318 /// As this string slice consists of valid UTF-16, we can iterate through a string slice by
1319 /// [`char`]. This method returns such an iterator.
1320 ///
1321 /// It's important to remember that [`char`] represents a Unicode Scalar Value, and might not
1322 /// match your idea of what a 'character' is. Iteration over grapheme clusters may be what you
1323 /// actually want. This functionality is not provided by this crate.
1324 #[inline]
1325 #[must_use]
1326 pub fn chars(&self) -> CharsUtf16<'_> {
1327 CharsUtf16::new(self.as_slice())
1328 }
1329
1330 /// Returns an iterator over the [`char`]s of a string slice and their positions.
1331 ///
1332 /// As this string slice consists of valid UTF-16, we can iterate through a string slice by
1333 /// [`char`]. This method returns an iterator of both these [`char`]s as well as their offsets.
1334 ///
1335 /// The iterator yields tuples. The position is first, the [`char`] is second.
1336 #[inline]
1337 #[must_use]
1338 pub fn char_indices(&self) -> CharIndicesUtf16<'_> {
1339 CharIndicesUtf16::new(self.as_slice())
1340 }
1341
1342 /// An iterator over the [`u16`] code units of a string slice.
1343 ///
1344 /// As a UTF-16 string slice consists of a sequence of [`u16`] code units, we can iterate
1345 /// through a string slice by each code unit. This method returns such an iterator.
1346 #[must_use]
1347 pub fn code_units(&self) -> CodeUnits<'_> {
1348 CodeUnits::new(self.as_slice())
1349 }
1350
1351 /// Returns an iterator of bytes over the string encoded as UTF-8.
1352 #[must_use]
1353 pub fn encode_utf8(&self) -> EncodeUtf8<CharsUtf16<'_>> {
1354 crate::encode_utf8(self.chars())
1355 }
1356
1357 /// Returns an iterator of [`u32`] over the sting encoded as UTF-32.
1358 #[must_use]
1359 pub fn encode_utf32(&self) -> EncodeUtf32<CharsUtf16<'_>> {
1360 crate::encode_utf32(self.chars())
1361 }
1362
1363 /// Returns an iterator that escapes each [`char`] in `self` with [`char::escape_debug`].
1364 #[inline]
1365 #[must_use]
1366 pub fn escape_debug(&self) -> EscapeDebug<CharsUtf16<'_>> {
1367 EscapeDebug::<CharsUtf16>::new(self.as_slice())
1368 }
1369
1370 /// Returns an iterator that escapes each [`char`] in `self` with [`char::escape_default`].
1371 #[inline]
1372 #[must_use]
1373 pub fn escape_default(&self) -> EscapeDefault<CharsUtf16<'_>> {
1374 EscapeDefault::<CharsUtf16>::new(self.as_slice())
1375 }
1376
1377 /// Returns an iterator that escapes each [`char`] in `self` with [`char::escape_unicode`].
1378 #[inline]
1379 #[must_use]
1380 pub fn escape_unicode(&self) -> EscapeUnicode<CharsUtf16<'_>> {
1381 EscapeUnicode::<CharsUtf16>::new(self.as_slice())
1382 }
1383
1384 /// Returns the lowercase equivalent of this string slice, as a new [`Utf16String`].
1385 ///
1386 /// 'Lowercase' is defined according to the terms of the Unicode Derived Core Property
1387 /// `Lowercase`.
1388 ///
1389 /// Since some characters can expand into multiple characters when changing the case, this
1390 /// function returns a [`Utf16String`] instead of modifying the parameter in-place.
1391 #[inline]
1392 #[cfg(feature = "alloc")]
1393 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
1394 #[must_use]
1395 pub fn to_lowercase(&self) -> Utf16String {
1396 let mut s = Utf16String::with_capacity(self.len());
1397 for c in self.chars() {
1398 for lower in c.to_lowercase() {
1399 s.push(lower);
1400 }
1401 }
1402 s
1403 }
1404
1405 /// Returns the uppercase equivalent of this string slice, as a new [`Utf16String`].
1406 ///
1407 /// 'Uppercase' is defined according to the terms of the Unicode Derived Core Property
1408 /// `Uppercase`.
1409 ///
1410 /// Since some characters can expand into multiple characters when changing the case, this
1411 /// function returns a [`Utf16String`] instead of modifying the parameter in-place.
1412 #[inline]
1413 #[cfg(feature = "alloc")]
1414 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
1415 #[must_use]
1416 pub fn to_uppercase(&self) -> Utf16String {
1417 let mut s = Utf16String::with_capacity(self.len());
1418 for c in self.chars() {
1419 for lower in c.to_uppercase() {
1420 s.push(lower);
1421 }
1422 }
1423 s
1424 }
1425 }
1426
1427 impl Utf32Str {
1428 /// Converts a slice of UTF-32 data to a string slice.
1429 ///
1430 /// Not all slices of [`u32`] values are valid to convert, since [`Utf32Str`] requires that it
1431 /// is always valid UTF-32. This function checks to ensure that the values are valid UTF-32, and
1432 /// then does the conversion.
1433 ///
1434 /// If you are sure that the slice is valid UTF-32, and you don't want to incur the overhead of
1435 /// the validity check, there is an unsafe version of this function,
1436 /// [`from_slice_unchecked`][Self::from_slice_unchecked], which has the same behavior but skips
1437 /// the check.
1438 ///
1439 /// If you need an owned string, consider using [`Utf32String::from_vec`] instead.
1440 ///
1441 /// Because you can stack-allocate a `[u32; N]`, this function is one way to have a
1442 /// stack-allocated string. Indeed, the [`utf32str!`][crate::utf32str] macro does exactly this
1443 /// after converting from UTF-8 to UTF-32.
1444 ///
1445 /// # Errors
1446 ///
1447 /// Returns an error if the slice is not UTF-32 with a description as to why the provided slice
1448 /// is not UTF-32.
1449 ///
1450 /// # Examples
1451 ///
1452 /// ```
1453 /// use widestring::Utf32Str;
1454 ///
1455 /// let sparkle_heart = vec![0x1f496];
1456 /// let sparkle_heart = Utf32Str::from_slice(&sparkle_heart).unwrap();
1457 ///
1458 /// assert_eq!("💖", sparkle_heart);
1459 /// ```
1460 ///
1461 /// With incorrect values that return an error:
1462 ///
1463 /// ```
1464 /// use widestring::Utf32Str;
1465 ///
1466 /// let sparkle_heart = vec![0xd83d, 0xdc96]; // UTF-16 surrogates are invalid
1467 ///
1468 /// assert!(Utf32Str::from_slice(&sparkle_heart).is_err());
1469 /// ```
1470 pub fn from_slice(s: &[u32]) -> Result<&Self, Utf32Error> {
1471 validate_utf32(s)?;
1472 // SAFETY: Just validated
1473 Ok(unsafe { Self::from_slice_unchecked(s) })
1474 }
1475
1476 /// Converts a mutable slice of UTF-32 data to a mutable string slice.
1477 ///
1478 /// Not all slices of [`u32`] values are valid to convert, since [`Utf32Str`] requires that it
1479 /// is always valid UTF-32. This function checks to ensure that the values are valid UTF-32, and
1480 /// then does the conversion.
1481 ///
1482 /// If you are sure that the slice is valid UTF-32, and you don't want to incur the overhead of
1483 /// the validity check, there is an unsafe version of this function,
1484 /// [`from_slice_unchecked_mut`][Self::from_slice_unchecked_mut], which has the same behavior
1485 /// but skips the check.
1486 ///
1487 /// If you need an owned string, consider using [`Utf32String::from_vec`] instead.
1488 ///
1489 /// Because you can stack-allocate a `[u32; N]`, this function is one way to have a
1490 /// stack-allocated string. Indeed, the [`utf32str!`][crate::utf32str] macro does exactly this
1491 /// after converting from UTF-8 to UTF-32.
1492 ///
1493 /// # Errors
1494 ///
1495 /// Returns an error if the slice is not UTF-32 with a description as to why the provided slice
1496 /// is not UTF-32.
1497 ///
1498 /// # Examples
1499 ///
1500 /// ```
1501 /// use widestring::Utf32Str;
1502 ///
1503 /// let mut sparkle_heart = vec![0x1f496];
1504 /// let sparkle_heart = Utf32Str::from_slice_mut(&mut sparkle_heart).unwrap();
1505 ///
1506 /// assert_eq!("💖", sparkle_heart);
1507 /// ```
1508 ///
1509 /// With incorrect values that return an error:
1510 ///
1511 /// ```
1512 /// use widestring::Utf32Str;
1513 ///
1514 /// let mut sparkle_heart = vec![0xd83d, 0xdc96]; // UTF-16 surrogates are invalid
1515 ///
1516 /// assert!(Utf32Str::from_slice_mut(&mut sparkle_heart).is_err());
1517 /// ```
1518 pub fn from_slice_mut(s: &mut [u32]) -> Result<&mut Self, Utf32Error> {
1519 validate_utf32(s)?;
1520 // SAFETY: Just validated
1521 Ok(unsafe { Self::from_slice_unchecked_mut(s) })
1522 }
1523
1524 /// Converts a wide string slice of undefined encoding to a UTF-32 string slice without checking
1525 /// if the string slice is valid UTF-32.
1526 ///
1527 /// See the safe version, [`from_ustr`][Self::from_ustr], for more information.
1528 ///
1529 /// # Safety
1530 ///
1531 /// This function is unsafe because it does not check that the string slice passed to it is
1532 /// valid UTF-32. If this constraint is violated, undefined behavior results as it is assumed
1533 /// the [`Utf32Str`] is always valid UTF-32.
1534 ///
1535 /// # Examples
1536 ///
1537 /// ```
1538 /// use widestring::{Utf32Str, u32str};
1539 ///
1540 /// let sparkle_heart = u32str!("💖");
1541 /// let sparkle_heart = unsafe { Utf32Str::from_ustr_unchecked(sparkle_heart) };
1542 ///
1543 /// assert_eq!("💖", sparkle_heart);
1544 /// ```
1545 #[inline]
1546 #[must_use]
1547 pub const unsafe fn from_ustr_unchecked(s: &crate::U32Str) -> &Self {
1548 Self::from_slice_unchecked(s.as_slice())
1549 }
1550
1551 /// Converts a mutable wide string slice of undefined encoding to a mutable UTF-32 string slice
1552 /// without checking if the string slice is valid UTF-32.
1553 ///
1554 /// See the safe version, [`from_ustr_mut`][Self::from_ustr_mut], for more information.
1555 ///
1556 /// # Safety
1557 ///
1558 /// This function is unsafe because it does not check that the string slice passed to it is
1559 /// valid UTF-32. If this constraint is violated, undefined behavior results as it is assumed
1560 /// the [`Utf32Str`] is always valid UTF-32.
1561 #[inline]
1562 #[must_use]
1563 pub unsafe fn from_ustr_unchecked_mut(s: &mut crate::U32Str) -> &mut Self {
1564 Self::from_slice_unchecked_mut(s.as_mut_slice())
1565 }
1566
1567 /// Converts a wide string slice of undefined encoding to a UTF-32 string slice.
1568 ///
1569 /// Since [`U32Str`] does not have a specified encoding, this conversion may fail if the
1570 /// [`U32Str`] does not contain valid UTF-32 data.
1571 ///
1572 /// If you are sure that the slice is valid UTF-32, and you don't want to incur the overhead of
1573 /// the validity check, there is an unsafe version of this function,
1574 /// [`from_ustr_unchecked`][Self::from_ustr_unchecked], which has the same behavior
1575 /// but skips the check.
1576 ///
1577 /// # Errors
1578 ///
1579 /// Returns an error if the string slice is not UTF-32 with a description as to why the
1580 /// provided string slice is not UTF-32.
1581 ///
1582 /// # Examples
1583 ///
1584 /// ```
1585 /// use widestring::{Utf32Str, u32str};
1586 ///
1587 /// let sparkle_heart = u32str!("💖");
1588 /// let sparkle_heart = Utf32Str::from_ustr(sparkle_heart).unwrap();
1589 ///
1590 /// assert_eq!("💖", sparkle_heart);
1591 /// ```
1592 #[inline]
1593 pub fn from_ustr(s: &crate::U32Str) -> Result<&Self, Utf32Error> {
1594 Self::from_slice(s.as_slice())
1595 }
1596
1597 /// Converts a mutable wide string slice of undefined encoding to a mutable UTF-32 string slice.
1598 ///
1599 /// Since [`U32Str`] does not have a specified encoding, this conversion may fail if the
1600 /// [`U32Str`] does not contain valid UTF-32 data.
1601 ///
1602 /// If you are sure that the slice is valid UTF-32, and you don't want to incur the overhead of
1603 /// the validity check, there is an unsafe version of this function,
1604 /// [`from_ustr_unchecked_mut`][Self::from_ustr_unchecked_mut], which has the same behavior
1605 /// but skips the check.
1606 ///
1607 /// # Errors
1608 ///
1609 /// Returns an error if the string slice is not UTF-32 with a description as to why the
1610 /// provided string slice is not UTF-32.
1611 #[inline]
1612 pub fn from_ustr_mut(s: &mut crate::U32Str) -> Result<&mut Self, Utf32Error> {
1613 Self::from_slice_mut(s.as_mut_slice())
1614 }
1615
1616 /// Converts a wide C string slice to a UTF-32 string slice without checking if the
1617 /// string slice is valid UTF-32.
1618 ///
1619 /// The resulting string slice does *not* contain the nul terminator.
1620 ///
1621 /// See the safe version, [`from_ucstr`][Self::from_ucstr], for more information.
1622 ///
1623 /// # Safety
1624 ///
1625 /// This function is unsafe because it does not check that the string slice passed to it is
1626 /// valid UTF-32. If this constraint is violated, undefined behavior results as it is assumed
1627 /// the [`Utf32Str`] is always valid UTF-32.
1628 ///
1629 /// # Examples
1630 ///
1631 /// ```
1632 /// use widestring::{Utf32Str, u32cstr};
1633 ///
1634 /// let sparkle_heart = u32cstr!("💖");
1635 /// let sparkle_heart = unsafe { Utf32Str::from_ucstr_unchecked(sparkle_heart) };
1636 ///
1637 /// assert_eq!("💖", sparkle_heart);
1638 /// ```
1639 #[inline]
1640 #[must_use]
1641 pub unsafe fn from_ucstr_unchecked(s: &crate::U32CStr) -> &Self {
1642 Self::from_slice_unchecked(s.as_slice())
1643 }
1644
1645 /// Converts a mutable wide C string slice to a mutable UTF-32 string slice without
1646 /// checking if the string slice is valid UTF-32.
1647 ///
1648 /// The resulting string slice does *not* contain the nul terminator.
1649 ///
1650 /// See the safe version, [`from_ucstr_mut`][Self::from_ucstr_mut], for more information.
1651 ///
1652 /// # Safety
1653 ///
1654 /// This function is unsafe because it does not check that the string slice passed to it is
1655 /// valid UTF-32. If this constraint is violated, undefined behavior results as it is assumed
1656 /// the [`Utf32Str`] is always valid UTF-32.
1657 #[inline]
1658 #[must_use]
1659 pub unsafe fn from_ucstr_unchecked_mut(s: &mut crate::U32CStr) -> &mut Self {
1660 Self::from_slice_unchecked_mut(s.as_mut_slice())
1661 }
1662
1663 /// Converts a wide C string slice to a UTF-32 string slice.
1664 ///
1665 /// The resulting string slice does *not* contain the nul terminator.
1666 ///
1667 /// Since [`U32CStr`][crate::U32CStr] does not have a specified encoding, this conversion may
1668 /// fail if the [`U32CStr`][crate::U32CStr] does not contain valid UTF-32 data.
1669 ///
1670 /// If you are sure that the slice is valid UTF-32, and you don't want to incur the overhead of
1671 /// the validity check, there is an unsafe version of this function,
1672 /// [`from_ucstr_unchecked`][Self::from_ucstr_unchecked], which has the same behavior
1673 /// but skips the check.
1674 ///
1675 /// # Errors
1676 ///
1677 /// Returns an error if the string slice is not UTF-32 with a description as to why the
1678 /// provided string slice is not UTF-32.
1679 ///
1680 /// # Examples
1681 ///
1682 /// ```
1683 /// use widestring::{Utf32Str, u32cstr};
1684 ///
1685 /// let sparkle_heart = u32cstr!("💖");
1686 /// let sparkle_heart = Utf32Str::from_ucstr(sparkle_heart).unwrap();
1687 ///
1688 /// assert_eq!("💖", sparkle_heart);
1689 /// ```
1690 #[inline]
1691 pub fn from_ucstr(s: &crate::U32CStr) -> Result<&Self, Utf32Error> {
1692 Self::from_slice(s.as_slice())
1693 }
1694
1695 /// Converts a mutable wide C string slice to a mutable UTF-32 string slice.
1696 ///
1697 /// The resulting string slice does *not* contain the nul terminator.
1698 ///
1699 /// Since [`U32CStr`][crate::U32CStr] does not have a specified encoding, this conversion may
1700 /// fail if the [`U32CStr`][crate::U32CStr] does not contain valid UTF-32 data.
1701 ///
1702 /// If you are sure that the slice is valid UTF-32, and you don't want to incur the overhead of
1703 /// the validity check, there is an unsafe version of this function,
1704 /// [`from_ucstr_unchecked_mut`][Self::from_ucstr_unchecked_mut], which has the same behavior
1705 /// but skips the check.
1706 ///
1707 /// # Safety
1708 ///
1709 /// This method is unsafe because you can violate the invariants of [`U16CStr`][crate::U16CStr]
1710 /// when mutating the slice (i.e. by adding interior nul values).
1711 ///
1712 /// # Errors
1713 ///
1714 /// Returns an error if the string slice is not UTF-32 with a description as to why the
1715 /// provided string slice is not UTF-32.
1716 #[inline]
1717 pub unsafe fn from_ucstr_mut(s: &mut crate::U32CStr) -> Result<&mut Self, Utf32Error> {
1718 Self::from_slice_mut(s.as_mut_slice())
1719 }
1720
1721 /// Converts a slice of [`char`]s to a string slice.
1722 ///
1723 /// Since [`char`] slices are always valid UTF-32, this conversion always suceeds.
1724 ///
1725 /// If you need an owned string, consider using [`Utf32String::from_chars`] instead.
1726 ///
1727 /// # Examples
1728 ///
1729 /// ```
1730 /// use widestring::Utf32Str;
1731 ///
1732 /// let sparkle_heart = ['💖'];
1733 /// let sparkle_heart = Utf32Str::from_char_slice(&sparkle_heart);
1734 ///
1735 /// assert_eq!("💖", sparkle_heart);
1736 /// ```
1737 #[allow(trivial_casts)]
1738 #[inline]
1739 #[must_use]
1740 pub const fn from_char_slice(s: &[char]) -> &Self {
1741 // SAFETY: char slice is always valid UTF-32
1742 unsafe { Self::from_slice_unchecked(&*(s as *const [char] as *const [u32])) }
1743 }
1744
1745 /// Converts a mutable slice of [`char`]s to a string slice.
1746 ///
1747 /// Since [`char`] slices are always valid UTF-32, this conversion always suceeds.
1748 ///
1749 /// If you need an owned string, consider using [`Utf32String::from_chars`] instead.
1750 ///
1751 /// # Examples
1752 ///
1753 /// ```
1754 /// use widestring::Utf32Str;
1755 ///
1756 /// let mut sparkle_heart = ['💖'];
1757 /// let sparkle_heart = Utf32Str::from_char_slice_mut(&mut sparkle_heart);
1758 ///
1759 /// assert_eq!("💖", sparkle_heart);
1760 /// ```
1761 #[allow(trivial_casts)]
1762 #[inline]
1763 #[must_use]
1764 pub fn from_char_slice_mut(s: &mut [char]) -> &mut Self {
1765 // SAFETY: char slice is always valid UTF-32
1766 unsafe { Self::from_slice_unchecked_mut(&mut *(s as *mut [char] as *mut [u32])) }
1767 }
1768
1769 /// Converts a string slice into a slice of [`char`]s.
1770 #[allow(trivial_casts)]
1771 #[inline]
1772 #[must_use]
1773 pub const fn as_char_slice(&self) -> &[char] {
1774 // SAFETY: Self should be valid UTF-32 so chars will be in range
1775 unsafe { &*(self.as_slice() as *const [u32] as *const [char]) }
1776 }
1777
1778 /// Converts a mutable string slice into a mutable slice of [`char`]s.
1779 #[allow(trivial_casts)]
1780 #[inline]
1781 #[must_use]
1782 pub fn as_char_slice_mut(&mut self) -> &mut [char] {
1783 // SAFETY: Self should be valid UTF-32 so chars will be in range
1784 unsafe { &mut *(self.as_mut_slice() as *mut [u32] as *mut [char]) }
1785 }
1786
1787 /// Converts to a standard UTF-8 [`String`].
1788 ///
1789 /// Because this string is always valid UTF-32, the conversion is lossless and non-fallible.
1790 #[inline]
1791 #[allow(clippy::inherent_to_string_shadow_display)]
1792 #[cfg(feature = "alloc")]
1793 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
1794 #[must_use]
1795 pub fn to_string(&self) -> String {
1796 let mut s = String::with_capacity(self.len());
1797 s.extend(self.as_char_slice());
1798 s
1799 }
1800
1801 /// Returns a subslice of this string.
1802 ///
1803 /// This is the non-panicking alternative to indexing the string. Returns [`None`] whenever
1804 /// equivalent indexing operation would panic.
1805 ///
1806 /// # Examples
1807 ///
1808 /// ```
1809 /// # use widestring::{utf32str};
1810 /// let v = utf32str!("⚧️🏳️‍⚧️➡️s");
1811 ///
1812 /// assert_eq!(Some(utf32str!("⚧️")), v.get(..2));
1813 /// assert_eq!(Some(utf32str!("🏳️‍⚧️")), v.get(2..7));
1814 /// assert_eq!(Some(utf32str!("➡️")), v.get(7..9));
1815 /// assert_eq!(Some(utf32str!("s")), v.get(9..));
1816 /// ```
1817 #[inline]
1818 #[must_use]
1819 pub fn get<I>(&self, index: I) -> Option<&Self>
1820 where
1821 I: SliceIndex<[u32], Output = [u32]>,
1822 {
1823 // TODO: Use SliceIndex directly when it is stabilized
1824 // SAFETY: subslice has already been verified
1825 self.inner
1826 .get(index)
1827 .map(|s| unsafe { Self::from_slice_unchecked(s) })
1828 }
1829
1830 /// Returns a mutable subslice of this string.
1831 ///
1832 /// This is the non-panicking alternative to indexing the string. Returns [`None`] whenever
1833 /// equivalent indexing operation would panic.
1834 ///
1835 /// # Examples
1836 ///
1837 /// ```
1838 /// # use widestring::{utf32str};
1839 /// # #[cfg(feature = "alloc")] {
1840 /// let mut v = utf32str!("⚧️🏳️‍⚧️➡️s").to_owned();
1841 ///
1842 /// assert_eq!(utf32str!("⚧️"), v.get_mut(..2).unwrap());
1843 /// assert_eq!(utf32str!("🏳️‍⚧️"), v.get_mut(2..7).unwrap());
1844 /// assert_eq!(utf32str!("➡️"), v.get_mut(7..9).unwrap());
1845 /// assert_eq!(utf32str!("s"), v.get_mut(9..).unwrap());
1846 /// # }
1847 /// ```
1848 #[inline]
1849 #[must_use]
1850 pub fn get_mut<I>(&mut self, index: I) -> Option<&mut Self>
1851 where
1852 I: SliceIndex<[u32], Output = [u32]>,
1853 {
1854 // TODO: Use SliceIndex directly when it is stabilized
1855 // SAFETY: subslice has already been verified
1856 self.inner
1857 .get_mut(index)
1858 .map(|s| unsafe { Self::from_slice_unchecked_mut(s) })
1859 }
1860
1861 /// Divide one string slice into two at an index.
1862 ///
1863 /// The argument, `mid`, should be an offset from the start of the string.
1864 ///
1865 /// The two slices returned go from the start of the string slice to `mid`, and from `mid` to
1866 /// the end of the string slice.
1867 ///
1868 /// To get mutable string slices instead, see the [`split_at_mut`][Self::split_at_mut] method.
1869 ///
1870 /// # Panics
1871 ///
1872 /// Panics if `mid` is past the end of the last code point of the string slice.
1873 ///
1874 /// # Examples
1875 ///
1876 /// ```
1877 /// # use widestring::utf32str;
1878 /// let s = utf32str!("Per Martin-Löf");
1879 ///
1880 /// let (first, last) = s.split_at(3);
1881 ///
1882 /// assert_eq!("Per", first);
1883 /// assert_eq!(" Martin-Löf", last);
1884 /// ```
1885 #[inline]
1886 #[must_use]
1887 pub fn split_at(&self, mid: usize) -> (&Self, &Self) {
1888 let (a, b) = self.inner.split_at(mid);
1889 unsafe { (Self::from_slice_unchecked(a), Self::from_slice_unchecked(b)) }
1890 }
1891
1892 /// Divide one mutable string slice into two at an index.
1893 ///
1894 /// The argument, `mid`, should be an offset from the start of the string.
1895 ///
1896 /// The two slices returned go from the start of the string slice to `mid`, and from `mid` to
1897 /// the end of the string slice.
1898 ///
1899 /// To get immutable string slices instead, see the [`split_at`][Self::split_at] method.
1900 ///
1901 /// # Panics
1902 ///
1903 /// Panics if `mid` is past the end of the last code point of the string slice.
1904 ///
1905 /// # Examples
1906 ///
1907 /// ```
1908 /// # use widestring::utf32str;
1909 /// # #[cfg(feature = "alloc")] {
1910 /// let mut s = utf32str!("Per Martin-Löf").to_owned();
1911 ///
1912 /// let (first, last) = s.split_at_mut(3);
1913 ///
1914 /// assert_eq!("Per", first);
1915 /// assert_eq!(" Martin-Löf", last);
1916 /// # }
1917 /// ```
1918 #[inline]
1919 #[must_use]
1920 pub fn split_at_mut(&mut self, mid: usize) -> (&mut Self, &mut Self) {
1921 let (a, b) = self.inner.split_at_mut(mid);
1922 unsafe {
1923 (
1924 Self::from_slice_unchecked_mut(a),
1925 Self::from_slice_unchecked_mut(b),
1926 )
1927 }
1928 }
1929
1930 /// Returns an iterator over the [`char`]s of a string slice.
1931 ///
1932 /// As this string slice consists of valid UTF-32, we can iterate through a string slice by
1933 /// [`char`]. This method returns such an iterator.
1934 ///
1935 /// It's important to remember that [`char`] represents a Unicode Scalar Value, and might not
1936 /// match your idea of what a 'character' is. Iteration over grapheme clusters may be what you
1937 /// actually want. This functionality is not provided by this crate.
1938 #[inline]
1939 #[must_use]
1940 pub fn chars(&self) -> CharsUtf32<'_> {
1941 CharsUtf32::new(self.as_slice())
1942 }
1943
1944 /// Returns an iterator over the [`char`]s of a string slice and their positions.
1945 ///
1946 /// As this string slice consists of valid UTF-32, we can iterate through a string slice by
1947 /// [`char`]. This method returns an iterator of both these [`char`]s as well as their offsets.
1948 ///
1949 /// The iterator yields tuples. The position is first, the [`char`] is second.
1950 #[inline]
1951 #[must_use]
1952 pub fn char_indices(&self) -> CharIndicesUtf32<'_> {
1953 CharIndicesUtf32::new(self.as_slice())
1954 }
1955
1956 /// Returns an iterator of bytes over the string encoded as UTF-8.
1957 #[must_use]
1958 pub fn encode_utf8(&self) -> EncodeUtf8<CharsUtf32<'_>> {
1959 crate::encode_utf8(self.chars())
1960 }
1961
1962 /// Returns an iterator of [`u16`] over the sting encoded as UTF-16.
1963 #[must_use]
1964 pub fn encode_utf16(&self) -> EncodeUtf16<CharsUtf32<'_>> {
1965 crate::encode_utf16(self.chars())
1966 }
1967
1968 /// Returns an iterator that escapes each [`char`] in `self` with [`char::escape_debug`].
1969 #[inline]
1970 #[must_use]
1971 pub fn escape_debug(&self) -> EscapeDebug<CharsUtf32<'_>> {
1972 EscapeDebug::<CharsUtf32>::new(self.as_slice())
1973 }
1974
1975 /// Returns an iterator that escapes each [`char`] in `self` with [`char::escape_default`].
1976 #[inline]
1977 #[must_use]
1978 pub fn escape_default(&self) -> EscapeDefault<CharsUtf32<'_>> {
1979 EscapeDefault::<CharsUtf32>::new(self.as_slice())
1980 }
1981
1982 /// Returns an iterator that escapes each [`char`] in `self` with [`char::escape_unicode`].
1983 #[inline]
1984 #[must_use]
1985 pub fn escape_unicode(&self) -> EscapeUnicode<CharsUtf32<'_>> {
1986 EscapeUnicode::<CharsUtf32>::new(self.as_slice())
1987 }
1988
1989 /// Returns the lowercase equivalent of this string slice, as a new [`Utf32String`].
1990 ///
1991 /// 'Lowercase' is defined according to the terms of the Unicode Derived Core Property
1992 /// `Lowercase`.
1993 ///
1994 /// Since some characters can expand into multiple characters when changing the case, this
1995 /// function returns a [`Utf32String`] instead of modifying the parameter in-place.
1996 #[inline]
1997 #[cfg(feature = "alloc")]
1998 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
1999 #[must_use]
2000 pub fn to_lowercase(&self) -> Utf32String {
2001 let mut s = Utf32String::with_capacity(self.len());
2002 for c in self.chars() {
2003 for lower in c.to_lowercase() {
2004 s.push(lower);
2005 }
2006 }
2007 s
2008 }
2009
2010 /// Returns the uppercase equivalent of this string slice, as a new [`Utf32String`].
2011 ///
2012 /// 'Uppercase' is defined according to the terms of the Unicode Derived Core Property
2013 /// `Uppercase`.
2014 ///
2015 /// Since some characters can expand into multiple characters when changing the case, this
2016 /// function returns a [`Utf32String`] instead of modifying the parameter in-place.
2017 #[inline]
2018 #[cfg(feature = "alloc")]
2019 #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
2020 #[must_use]
2021 pub fn to_uppercase(&self) -> Utf32String {
2022 let mut s = Utf32String::with_capacity(self.len());
2023 for c in self.chars() {
2024 for lower in c.to_uppercase() {
2025 s.push(lower);
2026 }
2027 }
2028 s
2029 }
2030 }
2031
2032 impl AsMut<[char]> for Utf32Str {
2033 #[inline]
2034 fn as_mut(&mut self) -> &mut [char] {
2035 self.as_char_slice_mut()
2036 }
2037 }
2038
2039 impl AsRef<[char]> for Utf32Str {
2040 #[inline]
2041 fn as_ref(&self) -> &[char] {
2042 self.as_char_slice()
2043 }
2044 }
2045
2046 impl<'a> From<&'a [char]> for &'a Utf32Str {
2047 #[inline]
2048 fn from(value: &'a [char]) -> Self {
2049 Utf32Str::from_char_slice(value)
2050 }
2051 }
2052
2053 impl<'a> From<&'a mut [char]> for &'a mut Utf32Str {
2054 #[inline]
2055 fn from(value: &'a mut [char]) -> Self {
2056 Utf32Str::from_char_slice_mut(value)
2057 }
2058 }
2059
2060 impl<'a> From<&'a Utf32Str> for &'a [char] {
2061 #[inline]
2062 fn from(value: &'a Utf32Str) -> Self {
2063 value.as_char_slice()
2064 }
2065 }
2066
2067 impl<'a> From<&'a mut Utf32Str> for &'a mut [char] {
2068 #[inline]
2069 fn from(value: &'a mut Utf32Str) -> Self {
2070 value.as_char_slice_mut()
2071 }
2072 }
2073
2074 impl<I> Index<I> for Utf16Str
2075 where
2076 I: RangeBounds<usize> + SliceIndex<[u16], Output = [u16]>,
2077 {
2078 type Output = Utf16Str;
2079
2080 #[inline]
2081 fn index(&self, index: I) -> &Self::Output {
2082 self.get(index)
2083 .expect("index out of bounds or not on char boundary")
2084 }
2085 }
2086
2087 impl<I> Index<I> for Utf32Str
2088 where
2089 I: SliceIndex<[u32], Output = [u32]>,
2090 {
2091 type Output = Utf32Str;
2092
2093 #[inline]
2094 fn index(&self, index: I) -> &Self::Output {
2095 self.get(index).expect("index out of bounds")
2096 }
2097 }
2098
2099 impl<I> IndexMut<I> for Utf16Str
2100 where
2101 I: RangeBounds<usize> + SliceIndex<[u16], Output = [u16]>,
2102 {
2103 #[inline]
2104 fn index_mut(&mut self, index: I) -> &mut Self::Output {
2105 self.get_mut(index)
2106 .expect("index out of bounds or not on char boundary")
2107 }
2108 }
2109
2110 impl<I> IndexMut<I> for Utf32Str
2111 where
2112 I: SliceIndex<[u32], Output = [u32]>,
2113 {
2114 #[inline]
2115 fn index_mut(&mut self, index: I) -> &mut Self::Output {
2116 self.get_mut(index).expect("index out of bounds")
2117 }
2118 }
2119
2120 impl PartialEq<[char]> for Utf32Str {
2121 #[inline]
2122 fn eq(&self, other: &[char]) -> bool {
2123 self.as_char_slice() == other
2124 }
2125 }
2126
2127 impl PartialEq<Utf32Str> for [char] {
2128 #[inline]
2129 fn eq(&self, other: &Utf32Str) -> bool {
2130 self == other.as_char_slice()
2131 }
2132 }
2133
2134 impl PartialEq<Utf16Str> for Utf32Str {
2135 #[inline]
2136 fn eq(&self, other: &Utf16Str) -> bool {
2137 self.chars().eq(other.chars())
2138 }
2139 }
2140
2141 impl PartialEq<Utf32Str> for Utf16Str {
2142 #[inline]
2143 fn eq(&self, other: &Utf32Str) -> bool {
2144 self.chars().eq(other.chars())
2145 }
2146 }
2147
2148 impl PartialEq<&Utf16Str> for Utf32Str {
2149 #[inline]
2150 fn eq(&self, other: &&Utf16Str) -> bool {
2151 self.chars().eq(other.chars())
2152 }
2153 }
2154
2155 impl PartialEq<&Utf32Str> for Utf16Str {
2156 #[inline]
2157 fn eq(&self, other: &&Utf32Str) -> bool {
2158 self.chars().eq(other.chars())
2159 }
2160 }
2161
2162 impl PartialEq<Utf16Str> for &Utf32Str {
2163 #[inline]
2164 fn eq(&self, other: &Utf16Str) -> bool {
2165 self.chars().eq(other.chars())
2166 }
2167 }
2168
2169 impl PartialEq<Utf32Str> for &Utf16Str {
2170 #[inline]
2171 fn eq(&self, other: &Utf32Str) -> bool {
2172 self.chars().eq(other.chars())
2173 }
2174 }
2175
2176 impl<'a> TryFrom<&'a [u16]> for &'a Utf16Str {
2177 type Error = Utf16Error;
2178
2179 #[inline]
2180 fn try_from(value: &'a [u16]) -> Result<Self, Self::Error> {
2181 Utf16Str::from_slice(value)
2182 }
2183 }
2184
2185 impl<'a> TryFrom<&'a mut [u16]> for &'a mut Utf16Str {
2186 type Error = Utf16Error;
2187
2188 #[inline]
2189 fn try_from(value: &'a mut [u16]) -> Result<Self, Self::Error> {
2190 Utf16Str::from_slice_mut(value)
2191 }
2192 }
2193
2194 impl<'a> TryFrom<&'a [u32]> for &'a Utf32Str {
2195 type Error = Utf32Error;
2196
2197 #[inline]
2198 fn try_from(value: &'a [u32]) -> Result<Self, Self::Error> {
2199 Utf32Str::from_slice(value)
2200 }
2201 }
2202
2203 impl<'a> TryFrom<&'a mut [u32]> for &'a mut Utf32Str {
2204 type Error = Utf32Error;
2205
2206 #[inline]
2207 fn try_from(value: &'a mut [u32]) -> Result<Self, Self::Error> {
2208 Utf32Str::from_slice_mut(value)
2209 }
2210 }
2211
2212 /// Alias for [`Utf16Str`] or [`Utf32Str`] depending on platform. Intended to match typical C
2213 /// `wchar_t` size on platform.
2214 #[cfg(not(windows))]
2215 pub type WideUtfStr = Utf32Str;
2216
2217 /// Alias for [`Utf16Str`] or [`Utf32Str`] depending on platform. Intended to match typical C
2218 /// `wchar_t` size on platform.
2219 #[cfg(windows)]
2220 pub type WideUtfStr = Utf16Str;
2221
2222 #[cfg(test)]
2223 mod test {
2224 use crate::*;
2225
2226 #[test]
2227 fn utf16_trim() {
2228 let s = utf16str!(" Hello\tworld\t");
2229 assert_eq!(utf16str!("Hello\tworld\t"), s.trim_start());
2230
2231 let s = utf16str!(" English ");
2232 assert!(Some('E') == s.trim_start().chars().next());
2233
2234 let s = utf16str!(" עברית ");
2235 assert!(Some('ע') == s.trim_start().chars().next());
2236 }
2237
2238 #[test]
2239 fn utf32_trim() {
2240 let s = utf32str!(" Hello\tworld\t");
2241 assert_eq!(utf32str!("Hello\tworld\t"), s.trim_start());
2242
2243 let s = utf32str!(" English ");
2244 assert!(Some('E') == s.trim_start().chars().next());
2245
2246 let s = utf32str!(" עברית ");
2247 assert!(Some('ע') == s.trim_start().chars().next());
2248 }
2249 }