library/std/src/sys_common/wtf8.rs

   1 //! Implementation of [the WTF-8 encoding](https://simonsapin.github.io/wtf-8/).
   2 //!
   3 //! This library uses Rust’s type system to maintain
   4 //! [well-formedness](https://simonsapin.github.io/wtf-8/#well-formed),
   5 //! like the `String` and `&str` types do for UTF-8.
   6 //!
   7 //! Since [WTF-8 must not be used
   8 //! for interchange](https://simonsapin.github.io/wtf-8/#intended-audience),
   9 //! this library deliberately does not provide access to the underlying bytes
  10 //! of WTF-8 strings,
  11 //! nor can it decode WTF-8 from arbitrary bytes.
  12 //! WTF-8 strings can be obtained from UTF-8, UTF-16, or code points.
  13
  14 // this module is imported from @SimonSapin's repo and has tons of dead code on
  15 // unix (it's mostly used on windows), so don't worry about dead code here.
  16 #![allow(dead_code)]
  17
  18 #[cfg(test)]
  19 mod tests;
  20
  21 use core::str::next_code_point;
  22
  23 use crate::borrow::Cow;
  24 use crate::char;
  25 use crate::collections::TryReserveError;
  26 use crate::fmt;
  27 use crate::hash::{Hash, Hasher};
  28 use crate::iter::FromIterator;
  29 use crate::mem;
  30 use crate::ops;
  31 use crate::rc::Rc;
  32 use crate::slice;
  33 use crate::str;
  34 use crate::sync::Arc;
  35 use crate::sys_common::AsInner;
  36
  37 const UTF8_REPLACEMENT_CHARACTER: &str = "\u{FFFD}";
  38
  39 /// A Unicode code point: from U+0000 to U+10FFFF.
  40 ///
  41 /// Compares with the `char` type,
  42 /// which represents a Unicode scalar value:
  43 /// a code point that is not a surrogate (U+D800 to U+DFFF).
  44 #[derive(Eq, PartialEq, Ord, PartialOrd, Clone, Copy)]
  45 pub struct CodePoint {
  46     value: u32,
  47 }
  48
  49 /// Format the code point as `U+` followed by four to six hexadecimal digits.
  50 /// Example: `U+1F4A9`
  51 impl fmt::Debug for CodePoint {
  52     #[inline]
  53     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
  54         write!(formatter, "U+{:04X}", self.value)
  55     }
  56 }
  57
  58 impl CodePoint {
  59     /// Unsafely creates a new `CodePoint` without checking the value.
  60     ///
  61     /// Only use when `value` is known to be less than or equal to 0x10FFFF.
  62     #[inline]
  63     pub unsafe fn from_u32_unchecked(value: u32) -> CodePoint {
  64         CodePoint { value }
  65     }
  66
  67     /// Creates a new `CodePoint` if the value is a valid code point.
  68     ///
  69     /// Returns `None` if `value` is above 0x10FFFF.
  70     #[inline]
  71     pub fn from_u32(value: u32) -> Option<CodePoint> {
  72         match value {
  73             0..=0x10FFFF => Some(CodePoint { value }),
  74             _ => None,
  75         }
  76     }
  77
  78     /// Creates a new `CodePoint` from a `char`.
  79     ///
  80     /// Since all Unicode scalar values are code points, this always succeeds.
  81     #[inline]
  82     pub fn from_char(value: char) -> CodePoint {
  83         CodePoint { value: value as u32 }
  84     }
  85
  86     /// Returns the numeric value of the code point.
  87     #[inline]
  88     pub fn to_u32(&self) -> u32 {
  89         self.value
  90     }
  91
  92     /// Optionally returns a Unicode scalar value for the code point.
  93     ///
  94     /// Returns `None` if the code point is a surrogate (from U+D800 to U+DFFF).
  95     #[inline]
  96     pub fn to_char(&self) -> Option<char> {
  97         match self.value {
  98             0xD800..=0xDFFF => None,
  99             _ => Some(unsafe { char::from_u32_unchecked(self.value) }),
 100         }
 101     }
 102
 103     /// Returns a Unicode scalar value for the code point.
 104     ///
 105     /// Returns `'\u{FFFD}'` (the replacement character “�”)
 106     /// if the code point is a surrogate (from U+D800 to U+DFFF).
 107     #[inline]
 108     pub fn to_char_lossy(&self) -> char {
 109         self.to_char().unwrap_or('\u{FFFD}')
 110     }
 111 }
 112
 113 /// An owned, growable string of well-formed WTF-8 data.
 114 ///
 115 /// Similar to `String`, but can additionally contain surrogate code points
 116 /// if they’re not in a surrogate pair.
 117 #[derive(Eq, PartialEq, Ord, PartialOrd, Clone)]
 118 pub struct Wtf8Buf {
 119     bytes: Vec<u8>,
 120 }
 121
 122 impl ops::Deref for Wtf8Buf {
 123     type Target = Wtf8;
 124
 125     fn deref(&self) -> &Wtf8 {
 126         self.as_slice()
 127     }
 128 }
 129
 130 impl ops::DerefMut for Wtf8Buf {
 131     fn deref_mut(&mut self) -> &mut Wtf8 {
 132         self.as_mut_slice()
 133     }
 134 }
 135
 136 /// Format the string with double quotes,
 137 /// and surrogates as `\u` followed by four hexadecimal digits.
 138 /// Example: `"a\u{D800}"` for a string with code points [U+0061, U+D800]
 139 impl fmt::Debug for Wtf8Buf {
 140     #[inline]
 141     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
 142         fmt::Debug::fmt(&**self, formatter)
 143     }
 144 }
 145
 146 impl Wtf8Buf {
 147     /// Creates a new, empty WTF-8 string.
 148     #[inline]
 149     pub fn new() -> Wtf8Buf {
 150         Wtf8Buf { bytes: Vec::new() }
 151     }
 152
 153     /// Creates a new, empty WTF-8 string with pre-allocated capacity for `capacity` bytes.
 154     #[inline]
 155     pub fn with_capacity(capacity: usize) -> Wtf8Buf {
 156         Wtf8Buf { bytes: Vec::with_capacity(capacity) }
 157     }
 158
 159     /// Creates a WTF-8 string from a UTF-8 `String`.
 160     ///
 161     /// This takes ownership of the `String` and does not copy.
 162     ///
 163     /// Since WTF-8 is a superset of UTF-8, this always succeeds.
 164     #[inline]
 165     pub fn from_string(string: String) -> Wtf8Buf {
 166         Wtf8Buf { bytes: string.into_bytes() }
 167     }
 168
 169     /// Creates a WTF-8 string from a UTF-8 `&str` slice.
 170     ///
 171     /// This copies the content of the slice.
 172     ///
 173     /// Since WTF-8 is a superset of UTF-8, this always succeeds.
 174     #[inline]
 175     pub fn from_str(str: &str) -> Wtf8Buf {
 176         Wtf8Buf { bytes: <[_]>::to_vec(str.as_bytes()) }
 177     }
 178
 179     pub fn clear(&mut self) {
 180         self.bytes.clear()
 181     }
 182
 183     /// Creates a WTF-8 string from a potentially ill-formed UTF-16 slice of 16-bit code units.
 184     ///
 185     /// This is lossless: calling `.encode_wide()` on the resulting string
 186     /// will always return the original code units.
 187     pub fn from_wide(v: &[u16]) -> Wtf8Buf {
 188         let mut string = Wtf8Buf::with_capacity(v.len());
 189         for item in char::decode_utf16(v.iter().cloned()) {
 190             match item {
 191                 Ok(ch) => string.push_char(ch),
 192                 Err(surrogate) => {
 193                     let surrogate = surrogate.unpaired_surrogate();
 194                     // Surrogates are known to be in the code point range.
 195                     let code_point = unsafe { CodePoint::from_u32_unchecked(surrogate as u32) };
 196                     // Skip the WTF-8 concatenation check,
 197                     // surrogate pairs are already decoded by decode_utf16
 198                     string.push_code_point_unchecked(code_point)
 199                 }
 200             }
 201         }
 202         string
 203     }
 204
 205     /// Copied from String::push
 206     /// This does **not** include the WTF-8 concatenation check.
 207     fn push_code_point_unchecked(&mut self, code_point: CodePoint) {
 208         let mut bytes = [0; 4];
 209         let bytes = char::encode_utf8_raw(code_point.value, &mut bytes);
 210         self.bytes.extend_from_slice(bytes)
 211     }
 212
 213     #[inline]
 214     pub fn as_slice(&self) -> &Wtf8 {
 215         unsafe { Wtf8::from_bytes_unchecked(&self.bytes) }
 216     }
 217
 218     #[inline]
 219     pub fn as_mut_slice(&mut self) -> &mut Wtf8 {
 220         unsafe { Wtf8::from_mut_bytes_unchecked(&mut self.bytes) }
 221     }
 222
 223     /// Reserves capacity for at least `additional` more bytes to be inserted
 224     /// in the given `Wtf8Buf`.
 225     /// The collection may reserve more space to avoid frequent reallocations.
 226     ///
 227     /// # Panics
 228     ///
 229     /// Panics if the new capacity overflows `usize`.
 230     #[inline]
 231     pub fn reserve(&mut self, additional: usize) {
 232         self.bytes.reserve(additional)
 233     }
 234
 235     /// Tries to reserve capacity for at least `additional` more length units
 236     /// in the given `Wtf8Buf`. The `Wtf8Buf` may reserve more space to avoid
 237     /// frequent reallocations. After calling `try_reserve`, capacity will be
 238     /// greater than or equal to `self.len() + additional`. Does nothing if
 239     /// capacity is already sufficient.
 240     ///
 241     /// # Errors
 242     ///
 243     /// If the capacity overflows, or the allocator reports a failure, then an error
 244     /// is returned.
 245     #[inline]
 246     pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> {
 247         self.bytes.try_reserve(additional)
 248     }
 249
 250     #[inline]
 251     pub fn reserve_exact(&mut self, additional: usize) {
 252         self.bytes.reserve_exact(additional)
 253     }
 254
 255     /// Tries to reserve the minimum capacity for exactly `additional`
 256     /// length units in the given `Wtf8Buf`. After calling
 257     /// `try_reserve_exact`, capacity will be greater than or equal to
 258     /// `self.len() + additional` if it returns `Ok(())`.
 259     /// Does nothing if the capacity is already sufficient.
 260     ///
 261     /// Note that the allocator may give the `Wtf8Buf` more space than it
 262     /// requests. Therefore, capacity can not be relied upon to be precisely
 263     /// minimal. Prefer [`try_reserve`] if future insertions are expected.
 264     ///
 265     /// [`try_reserve`]: Wtf8Buf::try_reserve
 266     ///
 267     /// # Errors
 268     ///
 269     /// If the capacity overflows, or the allocator reports a failure, then an error
 270     /// is returned.
 271     #[inline]
 272     pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> {
 273         self.bytes.try_reserve_exact(additional)
 274     }
 275
 276     #[inline]
 277     pub fn shrink_to_fit(&mut self) {
 278         self.bytes.shrink_to_fit()
 279     }
 280
 281     #[inline]
 282     pub fn shrink_to(&mut self, min_capacity: usize) {
 283         self.bytes.shrink_to(min_capacity)
 284     }
 285
 286     /// Returns the number of bytes that this string buffer can hold without reallocating.
 287     #[inline]
 288     pub fn capacity(&self) -> usize {
 289         self.bytes.capacity()
 290     }
 291
 292     /// Append a UTF-8 slice at the end of the string.
 293     #[inline]
 294     pub fn push_str(&mut self, other: &str) {
 295         self.bytes.extend_from_slice(other.as_bytes())
 296     }
 297
 298     /// Append a WTF-8 slice at the end of the string.
 299     ///
 300     /// This replaces newly paired surrogates at the boundary
 301     /// with a supplementary code point,
 302     /// like concatenating ill-formed UTF-16 strings effectively would.
 303     #[inline]
 304     pub fn push_wtf8(&mut self, other: &Wtf8) {
 305         match ((&*self).final_lead_surrogate(), other.initial_trail_surrogate()) {
 306             // Replace newly paired surrogates by a supplementary code point.
 307             (Some(lead), Some(trail)) => {
 308                 let len_without_lead_surrogate = self.len() - 3;
 309                 self.bytes.truncate(len_without_lead_surrogate);
 310                 let other_without_trail_surrogate = &other.bytes[3..];
 311                 // 4 bytes for the supplementary code point
 312                 self.bytes.reserve(4 + other_without_trail_surrogate.len());
 313                 self.push_char(decode_surrogate_pair(lead, trail));
 314                 self.bytes.extend_from_slice(other_without_trail_surrogate);
 315             }
 316             _ => self.bytes.extend_from_slice(&other.bytes),
 317         }
 318     }
 319
 320     /// Append a Unicode scalar value at the end of the string.
 321     #[inline]
 322     pub fn push_char(&mut self, c: char) {
 323         self.push_code_point_unchecked(CodePoint::from_char(c))
 324     }
 325
 326     /// Append a code point at the end of the string.
 327     ///
 328     /// This replaces newly paired surrogates at the boundary
 329     /// with a supplementary code point,
 330     /// like concatenating ill-formed UTF-16 strings effectively would.
 331     #[inline]
 332     pub fn push(&mut self, code_point: CodePoint) {
 333         if let trail @ 0xDC00..=0xDFFF = code_point.to_u32() {
 334             if let Some(lead) = (&*self).final_lead_surrogate() {
 335                 let len_without_lead_surrogate = self.len() - 3;
 336                 self.bytes.truncate(len_without_lead_surrogate);
 337                 self.push_char(decode_surrogate_pair(lead, trail as u16));
 338                 return;
 339             }
 340         }
 341
 342         // No newly paired surrogates at the boundary.
 343         self.push_code_point_unchecked(code_point)
 344     }
 345
 346     /// Shortens a string to the specified length.
 347     ///
 348     /// # Panics
 349     ///
 350     /// Panics if `new_len` > current length,
 351     /// or if `new_len` is not a code point boundary.
 352     #[inline]
 353     pub fn truncate(&mut self, new_len: usize) {
 354         assert!(is_code_point_boundary(self, new_len));
 355         self.bytes.truncate(new_len)
 356     }
 357
 358     /// Consumes the WTF-8 string and tries to convert it to UTF-8.
 359     ///
 360     /// This does not copy the data.
 361     ///
 362     /// If the contents are not well-formed UTF-8
 363     /// (that is, if the string contains surrogates),
 364     /// the original WTF-8 string is returned instead.
 365     pub fn into_string(self) -> Result<String, Wtf8Buf> {
 366         match self.next_surrogate(0) {
 367             None => Ok(unsafe { String::from_utf8_unchecked(self.bytes) }),
 368             Some(_) => Err(self),
 369         }
 370     }
 371
 372     /// Consumes the WTF-8 string and converts it lossily to UTF-8.
 373     ///
 374     /// This does not copy the data (but may overwrite parts of it in place).
 375     ///
 376     /// Surrogates are replaced with `"\u{FFFD}"` (the replacement character “�”)
 377     pub fn into_string_lossy(mut self) -> String {
 378         let mut pos = 0;
 379         loop {
 380             match self.next_surrogate(pos) {
 381                 Some((surrogate_pos, _)) => {
 382                     pos = surrogate_pos + 3;
 383                     self.bytes[surrogate_pos..pos]
 384                         .copy_from_slice(UTF8_REPLACEMENT_CHARACTER.as_bytes());
 385                 }
 386                 None => return unsafe { String::from_utf8_unchecked(self.bytes) },
 387             }
 388         }
 389     }
 390
 391     /// Converts this `Wtf8Buf` into a boxed `Wtf8`.
 392     #[inline]
 393     pub fn into_box(self) -> Box<Wtf8> {
 394         unsafe { mem::transmute(self.bytes.into_boxed_slice()) }
 395     }
 396
 397     /// Converts a `Box<Wtf8>` into a `Wtf8Buf`.
 398     pub fn from_box(boxed: Box<Wtf8>) -> Wtf8Buf {
 399         let bytes: Box<[u8]> = unsafe { mem::transmute(boxed) };
 400         Wtf8Buf { bytes: bytes.into_vec() }
 401     }
 402 }
 403
 404 /// Creates a new WTF-8 string from an iterator of code points.
 405 ///
 406 /// This replaces surrogate code point pairs with supplementary code points,
 407 /// like concatenating ill-formed UTF-16 strings effectively would.
 408 impl FromIterator<CodePoint> for Wtf8Buf {
 409     fn from_iter<T: IntoIterator<Item = CodePoint>>(iter: T) -> Wtf8Buf {
 410         let mut string = Wtf8Buf::new();
 411         string.extend(iter);
 412         string
 413     }
 414 }
 415
 416 /// Append code points from an iterator to the string.
 417 ///
 418 /// This replaces surrogate code point pairs with supplementary code points,
 419 /// like concatenating ill-formed UTF-16 strings effectively would.
 420 impl Extend<CodePoint> for Wtf8Buf {
 421     fn extend<T: IntoIterator<Item = CodePoint>>(&mut self, iter: T) {
 422         let iterator = iter.into_iter();
 423         let (low, _high) = iterator.size_hint();
 424         // Lower bound of one byte per code point (ASCII only)
 425         self.bytes.reserve(low);
 426         iterator.for_each(move |code_point| self.push(code_point));
 427     }
 428
 429     #[inline]
 430     fn extend_one(&mut self, code_point: CodePoint) {
 431         self.push(code_point);
 432     }
 433
 434     #[inline]
 435     fn extend_reserve(&mut self, additional: usize) {
 436         // Lower bound of one byte per code point (ASCII only)
 437         self.bytes.reserve(additional);
 438     }
 439 }
 440
 441 /// A borrowed slice of well-formed WTF-8 data.
 442 ///
 443 /// Similar to `&str`, but can additionally contain surrogate code points
 444 /// if they’re not in a surrogate pair.
 445 #[derive(Eq, Ord, PartialEq, PartialOrd)]
 446 pub struct Wtf8 {
 447     bytes: [u8],
 448 }
 449
 450 impl AsInner<[u8]> for Wtf8 {
 451     fn as_inner(&self) -> &[u8] {
 452         &self.bytes
 453     }
 454 }
 455
 456 /// Format the slice with double quotes,
 457 /// and surrogates as `\u` followed by four hexadecimal digits.
 458 /// Example: `"a\u{D800}"` for a slice with code points [U+0061, U+D800]
 459 impl fmt::Debug for Wtf8 {
 460     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
 461         fn write_str_escaped(f: &mut fmt::Formatter<'_>, s: &str) -> fmt::Result {
 462             use crate::fmt::Write;
 463             for c in s.chars().flat_map(|c| c.escape_debug()) {
 464                 f.write_char(c)?
 465             }
 466             Ok(())
 467         }
 468
 469         formatter.write_str("\"")?;
 470         let mut pos = 0;
 471         while let Some((surrogate_pos, surrogate)) = self.next_surrogate(pos) {
 472             write_str_escaped(formatter, unsafe {
 473                 str::from_utf8_unchecked(&self.bytes[pos..surrogate_pos])
 474             })?;
 475             write!(formatter, "\\u{{{:x}}}", surrogate)?;
 476             pos = surrogate_pos + 3;
 477         }
 478         write_str_escaped(formatter, unsafe { str::from_utf8_unchecked(&self.bytes[pos..]) })?;
 479         formatter.write_str("\"")
 480     }
 481 }
 482
 483 impl fmt::Display for Wtf8 {
 484     fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
 485         let wtf8_bytes = &self.bytes;
 486         let mut pos = 0;
 487         loop {
 488             match self.next_surrogate(pos) {
 489                 Some((surrogate_pos, _)) => {
 490                     formatter.write_str(unsafe {
 491                         str::from_utf8_unchecked(&wtf8_bytes[pos..surrogate_pos])
 492                     })?;
 493                     formatter.write_str(UTF8_REPLACEMENT_CHARACTER)?;
 494                     pos = surrogate_pos + 3;
 495                 }
 496                 None => {
 497                     let s = unsafe { str::from_utf8_unchecked(&wtf8_bytes[pos..]) };
 498                     if pos == 0 { return s.fmt(formatter) } else { return formatter.write_str(s) }
 499                 }
 500             }
 501         }
 502     }
 503 }
 504
 505 impl Wtf8 {
 506     /// Creates a WTF-8 slice from a UTF-8 `&str` slice.
 507     ///
 508     /// Since WTF-8 is a superset of UTF-8, this always succeeds.
 509     #[inline]
 510     pub fn from_str(value: &str) -> &Wtf8 {
 511         unsafe { Wtf8::from_bytes_unchecked(value.as_bytes()) }
 512     }
 513
 514     /// Creates a WTF-8 slice from a WTF-8 byte slice.
 515     ///
 516     /// Since the byte slice is not checked for valid WTF-8, this functions is
 517     /// marked unsafe.
 518     #[inline]
 519     unsafe fn from_bytes_unchecked(value: &[u8]) -> &Wtf8 {
 520         mem::transmute(value)
 521     }
 522
 523     /// Creates a mutable WTF-8 slice from a mutable WTF-8 byte slice.
 524     ///
 525     /// Since the byte slice is not checked for valid WTF-8, this functions is
 526     /// marked unsafe.
 527     #[inline]
 528     unsafe fn from_mut_bytes_unchecked(value: &mut [u8]) -> &mut Wtf8 {
 529         mem::transmute(value)
 530     }
 531
 532     /// Returns the length, in WTF-8 bytes.
 533     #[inline]
 534     pub fn len(&self) -> usize {
 535         self.bytes.len()
 536     }
 537
 538     #[inline]
 539     pub fn is_empty(&self) -> bool {
 540         self.bytes.is_empty()
 541     }
 542
 543     /// Returns the code point at `position` if it is in the ASCII range,
 544     /// or `b'\xFF' otherwise.
 545     ///
 546     /// # Panics
 547     ///
 548     /// Panics if `position` is beyond the end of the string.
 549     #[inline]
 550     pub fn ascii_byte_at(&self, position: usize) -> u8 {
 551         match self.bytes[position] {
 552             ascii_byte @ 0x00..=0x7F => ascii_byte,
 553             _ => 0xFF,
 554         }
 555     }
 556
 557     /// Returns an iterator for the string’s code points.
 558     #[inline]
 559     pub fn code_points(&self) -> Wtf8CodePoints<'_> {
 560         Wtf8CodePoints { bytes: self.bytes.iter() }
 561     }
 562
 563     /// Tries to convert the string to UTF-8 and return a `&str` slice.
 564     ///
 565     /// Returns `None` if the string contains surrogates.
 566     ///
 567     /// This does not copy the data.
 568     #[inline]
 569     pub fn as_str(&self) -> Option<&str> {
 570         // Well-formed WTF-8 is also well-formed UTF-8
 571         // if and only if it contains no surrogate.
 572         match self.next_surrogate(0) {
 573             None => Some(unsafe { str::from_utf8_unchecked(&self.bytes) }),
 574             Some(_) => None,
 575         }
 576     }
 577
 578     /// Lossily converts the string to UTF-8.
 579     /// Returns a UTF-8 `&str` slice if the contents are well-formed in UTF-8.
 580     ///
 581     /// Surrogates are replaced with `"\u{FFFD}"` (the replacement character “�”).
 582     ///
 583     /// This only copies the data if necessary (if it contains any surrogate).
 584     pub fn to_string_lossy(&self) -> Cow<'_, str> {
 585         let surrogate_pos = match self.next_surrogate(0) {
 586             None => return Cow::Borrowed(unsafe { str::from_utf8_unchecked(&self.bytes) }),
 587             Some((pos, _)) => pos,
 588         };
 589         let wtf8_bytes = &self.bytes;
 590         let mut utf8_bytes = Vec::with_capacity(self.len());
 591         utf8_bytes.extend_from_slice(&wtf8_bytes[..surrogate_pos]);
 592         utf8_bytes.extend_from_slice(UTF8_REPLACEMENT_CHARACTER.as_bytes());
 593         let mut pos = surrogate_pos + 3;
 594         loop {
 595             match self.next_surrogate(pos) {
 596                 Some((surrogate_pos, _)) => {
 597                     utf8_bytes.extend_from_slice(&wtf8_bytes[pos..surrogate_pos]);
 598                     utf8_bytes.extend_from_slice(UTF8_REPLACEMENT_CHARACTER.as_bytes());
 599                     pos = surrogate_pos + 3;
 600                 }
 601                 None => {
 602                     utf8_bytes.extend_from_slice(&wtf8_bytes[pos..]);
 603                     return Cow::Owned(unsafe { String::from_utf8_unchecked(utf8_bytes) });
 604                 }
 605             }
 606         }
 607     }
 608
 609     /// Converts the WTF-8 string to potentially ill-formed UTF-16
 610     /// and return an iterator of 16-bit code units.
 611     ///
 612     /// This is lossless:
 613     /// calling `Wtf8Buf::from_ill_formed_utf16` on the resulting code units
 614     /// would always return the original WTF-8 string.
 615     #[inline]
 616     pub fn encode_wide(&self) -> EncodeWide<'_> {
 617         EncodeWide { code_points: self.code_points(), extra: 0 }
 618     }
 619
 620     #[inline]
 621     fn next_surrogate(&self, mut pos: usize) -> Option<(usize, u16)> {
 622         let mut iter = self.bytes[pos..].iter();
 623         loop {
 624             let b = *iter.next()?;
 625             if b < 0x80 {
 626                 pos += 1;
 627             } else if b < 0xE0 {
 628                 iter.next();
 629                 pos += 2;
 630             } else if b == 0xED {
 631                 match (iter.next(), iter.next()) {
 632                     (Some(&b2), Some(&b3)) if b2 >= 0xA0 => {
 633                         return Some((pos, decode_surrogate(b2, b3)));
 634                     }
 635                     _ => pos += 3,
 636                 }
 637             } else if b < 0xF0 {
 638                 iter.next();
 639                 iter.next();
 640                 pos += 3;
 641             } else {
 642                 iter.next();
 643                 iter.next();
 644                 iter.next();
 645                 pos += 4;
 646             }
 647         }
 648     }
 649
 650     #[inline]
 651     fn final_lead_surrogate(&self) -> Option<u16> {
 652         match self.bytes {
 653             [.., 0xED, b2 @ 0xA0..=0xAF, b3] => Some(decode_surrogate(b2, b3)),
 654             _ => None,
 655         }
 656     }
 657
 658     #[inline]
 659     fn initial_trail_surrogate(&self) -> Option<u16> {
 660         match self.bytes {
 661             [0xED, b2 @ 0xB0..=0xBF, b3, ..] => Some(decode_surrogate(b2, b3)),
 662             _ => None,
 663         }
 664     }
 665
 666     pub fn clone_into(&self, buf: &mut Wtf8Buf) {
 667         self.bytes.clone_into(&mut buf.bytes)
 668     }
 669
 670     /// Boxes this `Wtf8`.
 671     #[inline]
 672     pub fn into_box(&self) -> Box<Wtf8> {
 673         let boxed: Box<[u8]> = self.bytes.into();
 674         unsafe { mem::transmute(boxed) }
 675     }
 676
 677     /// Creates a boxed, empty `Wtf8`.
 678     pub fn empty_box() -> Box<Wtf8> {
 679         let boxed: Box<[u8]> = Default::default();
 680         unsafe { mem::transmute(boxed) }
 681     }
 682
 683     #[inline]
 684     pub fn into_arc(&self) -> Arc<Wtf8> {
 685         let arc: Arc<[u8]> = Arc::from(&self.bytes);
 686         unsafe { Arc::from_raw(Arc::into_raw(arc) as *const Wtf8) }
 687     }
 688
 689     #[inline]
 690     pub fn into_rc(&self) -> Rc<Wtf8> {
 691         let rc: Rc<[u8]> = Rc::from(&self.bytes);
 692         unsafe { Rc::from_raw(Rc::into_raw(rc) as *const Wtf8) }
 693     }
 694
 695     #[inline]
 696     pub fn make_ascii_lowercase(&mut self) {
 697         self.bytes.make_ascii_lowercase()
 698     }
 699
 700     #[inline]
 701     pub fn make_ascii_uppercase(&mut self) {
 702         self.bytes.make_ascii_uppercase()
 703     }
 704
 705     #[inline]
 706     pub fn to_ascii_lowercase(&self) -> Wtf8Buf {
 707         Wtf8Buf { bytes: self.bytes.to_ascii_lowercase() }
 708     }
 709
 710     #[inline]
 711     pub fn to_ascii_uppercase(&self) -> Wtf8Buf {
 712         Wtf8Buf { bytes: self.bytes.to_ascii_uppercase() }
 713     }
 714
 715     #[inline]
 716     pub fn is_ascii(&self) -> bool {
 717         self.bytes.is_ascii()
 718     }
 719
 720     #[inline]
 721     pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool {
 722         self.bytes.eq_ignore_ascii_case(&other.bytes)
 723     }
 724 }
 725
 726 /// Returns a slice of the given string for the byte range \[`begin`..`end`).
 727 ///
 728 /// # Panics
 729 ///
 730 /// Panics when `begin` and `end` do not point to code point boundaries,
 731 /// or point beyond the end of the string.
 732 impl ops::Index<ops::Range<usize>> for Wtf8 {
 733     type Output = Wtf8;
 734
 735     #[inline]
 736     fn index(&self, range: ops::Range<usize>) -> &Wtf8 {
 737         // is_code_point_boundary checks that the index is in [0, .len()]
 738         if range.start <= range.end
 739             && is_code_point_boundary(self, range.start)
 740             && is_code_point_boundary(self, range.end)
 741         {
 742             unsafe { slice_unchecked(self, range.start, range.end) }
 743         } else {
 744             slice_error_fail(self, range.start, range.end)
 745         }
 746     }
 747 }
 748
 749 /// Returns a slice of the given string from byte `begin` to its end.
 750 ///
 751 /// # Panics
 752 ///
 753 /// Panics when `begin` is not at a code point boundary,
 754 /// or is beyond the end of the string.
 755 impl ops::Index<ops::RangeFrom<usize>> for Wtf8 {
 756     type Output = Wtf8;
 757
 758     #[inline]
 759     fn index(&self, range: ops::RangeFrom<usize>) -> &Wtf8 {
 760         // is_code_point_boundary checks that the index is in [0, .len()]
 761         if is_code_point_boundary(self, range.start) {
 762             unsafe { slice_unchecked(self, range.start, self.len()) }
 763         } else {
 764             slice_error_fail(self, range.start, self.len())
 765         }
 766     }
 767 }
 768
 769 /// Returns a slice of the given string from its beginning to byte `end`.
 770 ///
 771 /// # Panics
 772 ///
 773 /// Panics when `end` is not at a code point boundary,
 774 /// or is beyond the end of the string.
 775 impl ops::Index<ops::RangeTo<usize>> for Wtf8 {
 776     type Output = Wtf8;
 777
 778     #[inline]
 779     fn index(&self, range: ops::RangeTo<usize>) -> &Wtf8 {
 780         // is_code_point_boundary checks that the index is in [0, .len()]
 781         if is_code_point_boundary(self, range.end) {
 782             unsafe { slice_unchecked(self, 0, range.end) }
 783         } else {
 784             slice_error_fail(self, 0, range.end)
 785         }
 786     }
 787 }
 788
 789 impl ops::Index<ops::RangeFull> for Wtf8 {
 790     type Output = Wtf8;
 791
 792     #[inline]
 793     fn index(&self, _range: ops::RangeFull) -> &Wtf8 {
 794         self
 795     }
 796 }
 797
 798 #[inline]
 799 fn decode_surrogate(second_byte: u8, third_byte: u8) -> u16 {
 800     // The first byte is assumed to be 0xED
 801     0xD800 | (second_byte as u16 & 0x3F) << 6 | third_byte as u16 & 0x3F
 802 }
 803
 804 #[inline]
 805 fn decode_surrogate_pair(lead: u16, trail: u16) -> char {
 806     let code_point = 0x10000 + ((((lead - 0xD800) as u32) << 10) | (trail - 0xDC00) as u32);
 807     unsafe { char::from_u32_unchecked(code_point) }
 808 }
 809
 810 /// Copied from core::str::StrPrelude::is_char_boundary
 811 #[inline]
 812 pub fn is_code_point_boundary(slice: &Wtf8, index: usize) -> bool {
 813     if index == slice.len() {
 814         return true;
 815     }
 816     match slice.bytes.get(index) {
 817         None => false,
 818         Some(&b) => b < 128 || b >= 192,
 819     }
 820 }
 821
 822 /// Copied from core::str::raw::slice_unchecked
 823 #[inline]
 824 pub unsafe fn slice_unchecked(s: &Wtf8, begin: usize, end: usize) -> &Wtf8 {
 825     // memory layout of a &[u8] and &Wtf8 are the same
 826     Wtf8::from_bytes_unchecked(slice::from_raw_parts(s.bytes.as_ptr().add(begin), end - begin))
 827 }
 828
 829 /// Copied from core::str::raw::slice_error_fail
 830 #[inline(never)]
 831 pub fn slice_error_fail(s: &Wtf8, begin: usize, end: usize) -> ! {
 832     assert!(begin <= end);
 833     panic!("index {begin} and/or {end} in `{s:?}` do not lie on character boundary");
 834 }
 835
 836 /// Iterator for the code points of a WTF-8 string.
 837 ///
 838 /// Created with the method `.code_points()`.
 839 #[derive(Clone)]
 840 pub struct Wtf8CodePoints<'a> {
 841     bytes: slice::Iter<'a, u8>,
 842 }
 843
 844 impl<'a> Iterator for Wtf8CodePoints<'a> {
 845     type Item = CodePoint;
 846
 847     #[inline]
 848     fn next(&mut self) -> Option<CodePoint> {
 849         // SAFETY: `self.bytes` has been created from a WTF-8 string
 850         unsafe { next_code_point(&mut self.bytes).map(|c| CodePoint { value: c }) }
 851     }
 852
 853     #[inline]
 854     fn size_hint(&self) -> (usize, Option<usize>) {
 855         let len = self.bytes.len();
 856         (len.saturating_add(3) / 4, Some(len))
 857     }
 858 }
 859
 860 /// Generates a wide character sequence for potentially ill-formed UTF-16.
 861 #[stable(feature = "rust1", since = "1.0.0")]
 862 #[derive(Clone)]
 863 pub struct EncodeWide<'a> {
 864     code_points: Wtf8CodePoints<'a>,
 865     extra: u16,
 866 }
 867
 868 // Copied from libunicode/u_str.rs
 869 #[stable(feature = "rust1", since = "1.0.0")]
 870 impl<'a> Iterator for EncodeWide<'a> {
 871     type Item = u16;
 872
 873     #[inline]
 874     fn next(&mut self) -> Option<u16> {
 875         if self.extra != 0 {
 876             let tmp = self.extra;
 877             self.extra = 0;
 878             return Some(tmp);
 879         }
 880
 881         let mut buf = [0; 2];
 882         self.code_points.next().map(|code_point| {
 883             let n = char::encode_utf16_raw(code_point.value, &mut buf).len();
 884             if n == 2 {
 885                 self.extra = buf[1];
 886             }
 887             buf[0]
 888         })
 889     }
 890
 891     #[inline]
 892     fn size_hint(&self) -> (usize, Option<usize>) {
 893         let (low, high) = self.code_points.size_hint();
 894         let ext = (self.extra != 0) as usize;
 895         // every code point gets either one u16 or two u16,
 896         // so this iterator is between 1 or 2 times as
 897         // long as the underlying iterator.
 898         (low + ext, high.and_then(|n| n.checked_mul(2)).and_then(|n| n.checked_add(ext)))
 899     }
 900 }
 901
 902 impl Hash for CodePoint {
 903     #[inline]
 904     fn hash<H: Hasher>(&self, state: &mut H) {
 905         self.value.hash(state)
 906     }
 907 }
 908
 909 impl Hash for Wtf8Buf {
 910     #[inline]
 911     fn hash<H: Hasher>(&self, state: &mut H) {
 912         state.write(&self.bytes);
 913         0xfeu8.hash(state)
 914     }
 915 }
 916
 917 impl Hash for Wtf8 {
 918     #[inline]
 919     fn hash<H: Hasher>(&self, state: &mut H) {
 920         state.write(&self.bytes);
 921         0xfeu8.hash(state)
 922     }
 923 }