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