1 //! A UTF-8–encoded, growable string. 2 //! 3 //! This module contains the [`String`] type, the [`ToString`] trait for 4 //! converting to strings, and several error types that may result from 5 //! working with [`String`]s. 6 //! 7 //! # Examples 8 //! 9 //! There are multiple ways to create a new [`String`] from a string literal: 10 //! 11 //! ``` 12 //! let s = "Hello".to_string(); 13 //! 14 //! let s = String::from("world"); 15 //! let s: String = "also this".into(); 16 //! ``` 17 //! 18 //! You can create a new [`String`] from an existing one by concatenating with 19 //! `+`: 20 //! 21 //! ``` 22 //! let s = "Hello".to_string(); 23 //! 24 //! let message = s + " world!"; 25 //! ``` 26 //! 27 //! If you have a vector of valid UTF-8 bytes, you can make a [`String`] out of 28 //! it. You can do the reverse too. 29 //! 30 //! ``` 31 //! let sparkle_heart = vec![240, 159, 146, 150]; 32 //! 33 //! // We know these bytes are valid, so we'll use `unwrap()`. 34 //! let sparkle_heart = String::from_utf8(sparkle_heart).unwrap(); 35 //! 36 //! assert_eq!("��", sparkle_heart); 37 //! 38 //! let bytes = sparkle_heart.into_bytes(); 39 //! 40 //! assert_eq!(bytes, [240, 159, 146, 150]); 41 //! ``` 42 43 #![stable(feature = "rust1", since = "1.0.0")] 44 45 use core::error::Error; 46 use core::fmt; 47 use core::hash; 48 #[cfg(not(no_global_oom_handling))] 49 use core::iter::from_fn; 50 use core::iter::FusedIterator; 51 #[cfg(not(no_global_oom_handling))] 52 use core::ops::Add; 53 #[cfg(not(no_global_oom_handling))] 54 use core::ops::AddAssign; 55 #[cfg(not(no_global_oom_handling))] 56 use core::ops::Bound::{Excluded, Included, Unbounded}; 57 use core::ops::{self, Index, IndexMut, Range, RangeBounds}; 58 use core::ptr; 59 use core::slice; 60 use core::str::pattern::Pattern; 61 #[cfg(not(no_global_oom_handling))] 62 use core::str::Utf8Chunks; 63 64 #[cfg(not(no_global_oom_handling))] 65 use crate::borrow::{Cow, ToOwned}; 66 use crate::boxed::Box; 67 use crate::collections::TryReserveError; 68 use crate::str::{self, from_utf8_unchecked_mut, Chars, Utf8Error}; 69 #[cfg(not(no_global_oom_handling))] 70 use crate::str::{from_boxed_utf8_unchecked, FromStr}; 71 use crate::vec::Vec; 72 73 /// A UTF-8–encoded, growable string. 74 /// 75 /// The `String` type is the most common string type that has ownership over the 76 /// contents of the string. It has a close relationship with its borrowed 77 /// counterpart, the primitive [`str`]. 78 /// 79 /// # Examples 80 /// 81 /// You can create a `String` from [a literal string][`&str`] with [`String::from`]: 82 /// 83 /// [`String::from`]: From::from 84 /// 85 /// ``` 86 /// let hello = String::from("Hello, world!"); 87 /// ``` 88 /// 89 /// You can append a [`char`] to a `String` with the [`push`] method, and 90 /// append a [`&str`] with the [`push_str`] method: 91 /// 92 /// ``` 93 /// let mut hello = String::from("Hello, "); 94 /// 95 /// hello.push('w'); 96 /// hello.push_str("orld!"); 97 /// ``` 98 /// 99 /// [`push`]: String::push 100 /// [`push_str`]: String::push_str 101 /// 102 /// If you have a vector of UTF-8 bytes, you can create a `String` from it with 103 /// the [`from_utf8`] method: 104 /// 105 /// ``` 106 /// // some bytes, in a vector 107 /// let sparkle_heart = vec![240, 159, 146, 150]; 108 /// 109 /// // We know these bytes are valid, so we'll use `unwrap()`. 110 /// let sparkle_heart = String::from_utf8(sparkle_heart).unwrap(); 111 /// 112 /// assert_eq!("��", sparkle_heart); 113 /// ``` 114 /// 115 /// [`from_utf8`]: String::from_utf8 116 /// 117 /// # UTF-8 118 /// 119 /// `String`s are always valid UTF-8. If you need a non-UTF-8 string, consider 120 /// [`OsString`]. It is similar, but without the UTF-8 constraint. Because UTF-8 121 /// is a variable width encoding, `String`s are typically smaller than an array of 122 /// the same `chars`: 123 /// 124 /// ``` 125 /// use std::mem; 126 /// 127 /// // `s` is ASCII which represents each `char` as one byte 128 /// let s = "hello"; 129 /// assert_eq!(s.len(), 5); 130 /// 131 /// // A `char` array with the same contents would be longer because 132 /// // every `char` is four bytes 133 /// let s = ['h', 'e', 'l', 'l', 'o']; 134 /// let size: usize = s.into_iter().map(|c| mem::size_of_val(&c)).sum(); 135 /// assert_eq!(size, 20); 136 /// 137 /// // However, for non-ASCII strings, the difference will be smaller 138 /// // and sometimes they are the same 139 /// let s = "����������"; 140 /// assert_eq!(s.len(), 20); 141 /// 142 /// let s = ['��', '��', '��', '��', '��']; 143 /// let size: usize = s.into_iter().map(|c| mem::size_of_val(&c)).sum(); 144 /// assert_eq!(size, 20); 145 /// ``` 146 /// 147 /// This raises interesting questions as to how `s[i]` should work. 148 /// What should `i` be here? Several options include byte indices and 149 /// `char` indices but, because of UTF-8 encoding, only byte indices 150 /// would provide constant time indexing. Getting the `i`th `char`, for 151 /// example, is available using [`chars`]: 152 /// 153 /// ``` 154 /// let s = "hello"; 155 /// let third_character = s.chars().nth(2); 156 /// assert_eq!(third_character, Some('l')); 157 /// 158 /// let s = "����������"; 159 /// let third_character = s.chars().nth(2); 160 /// assert_eq!(third_character, Some('��')); 161 /// ``` 162 /// 163 /// Next, what should `s[i]` return? Because indexing returns a reference 164 /// to underlying data it could be `&u8`, `&[u8]`, or something else similar. 165 /// Since we're only providing one index, `&u8` makes the most sense but that 166 /// might not be what the user expects and can be explicitly achieved with 167 /// [`as_bytes()`]: 168 /// 169 /// ``` 170 /// // The first byte is 104 - the byte value of `'h'` 171 /// let s = "hello"; 172 /// assert_eq!(s.as_bytes()[0], 104); 173 /// // or 174 /// assert_eq!(s.as_bytes()[0], b'h'); 175 /// 176 /// // The first byte is 240 which isn't obviously useful 177 /// let s = "����������"; 178 /// assert_eq!(s.as_bytes()[0], 240); 179 /// ``` 180 /// 181 /// Due to these ambiguities/restrictions, indexing with a `usize` is simply 182 /// forbidden: 183 /// 184 /// ```compile_fail,E0277 185 /// let s = "hello"; 186 /// 187 /// // The following will not compile! 188 /// println!("The first letter of s is {}", s[0]); 189 /// ``` 190 /// 191 /// It is more clear, however, how `&s[i..j]` should work (that is, 192 /// indexing with a range). It should accept byte indices (to be constant-time) 193 /// and return a `&str` which is UTF-8 encoded. This is also called "string slicing". 194 /// Note this will panic if the byte indices provided are not character 195 /// boundaries - see [`is_char_boundary`] for more details. See the implementations 196 /// for [`SliceIndex<str>`] for more details on string slicing. For a non-panicking 197 /// version of string slicing, see [`get`]. 198 /// 199 /// [`OsString`]: ../../std/ffi/struct.OsString.html "ffi::OsString" 200 /// [`SliceIndex<str>`]: core::slice::SliceIndex 201 /// [`as_bytes()`]: str::as_bytes 202 /// [`get`]: str::get 203 /// [`is_char_boundary`]: str::is_char_boundary 204 /// 205 /// The [`bytes`] and [`chars`] methods return iterators over the bytes and 206 /// codepoints of the string, respectively. To iterate over codepoints along 207 /// with byte indices, use [`char_indices`]. 208 /// 209 /// [`bytes`]: str::bytes 210 /// [`chars`]: str::chars 211 /// [`char_indices`]: str::char_indices 212 /// 213 /// # Deref 214 /// 215 /// `String` implements <code>[Deref]<Target = [str]></code>, and so inherits all of [`str`]'s 216 /// methods. In addition, this means that you can pass a `String` to a 217 /// function which takes a [`&str`] by using an ampersand (`&`): 218 /// 219 /// ``` 220 /// fn takes_str(s: &str) { } 221 /// 222 /// let s = String::from("Hello"); 223 /// 224 /// takes_str(&s); 225 /// ``` 226 /// 227 /// This will create a [`&str`] from the `String` and pass it in. This 228 /// conversion is very inexpensive, and so generally, functions will accept 229 /// [`&str`]s as arguments unless they need a `String` for some specific 230 /// reason. 231 /// 232 /// In certain cases Rust doesn't have enough information to make this 233 /// conversion, known as [`Deref`] coercion. In the following example a string 234 /// slice [`&'a str`][`&str`] implements the trait `TraitExample`, and the function 235 /// `example_func` takes anything that implements the trait. In this case Rust 236 /// would need to make two implicit conversions, which Rust doesn't have the 237 /// means to do. For that reason, the following example will not compile. 238 /// 239 /// ```compile_fail,E0277 240 /// trait TraitExample {} 241 /// 242 /// impl<'a> TraitExample for &'a str {} 243 /// 244 /// fn example_func<A: TraitExample>(example_arg: A) {} 245 /// 246 /// let example_string = String::from("example_string"); 247 /// example_func(&example_string); 248 /// ``` 249 /// 250 /// There are two options that would work instead. The first would be to 251 /// change the line `example_func(&example_string);` to 252 /// `example_func(example_string.as_str());`, using the method [`as_str()`] 253 /// to explicitly extract the string slice containing the string. The second 254 /// way changes `example_func(&example_string);` to 255 /// `example_func(&*example_string);`. In this case we are dereferencing a 256 /// `String` to a [`str`], then referencing the [`str`] back to 257 /// [`&str`]. The second way is more idiomatic, however both work to do the 258 /// conversion explicitly rather than relying on the implicit conversion. 259 /// 260 /// # Representation 261 /// 262 /// A `String` is made up of three components: a pointer to some bytes, a 263 /// length, and a capacity. The pointer points to an internal buffer `String` 264 /// uses to store its data. The length is the number of bytes currently stored 265 /// in the buffer, and the capacity is the size of the buffer in bytes. As such, 266 /// the length will always be less than or equal to the capacity. 267 /// 268 /// This buffer is always stored on the heap. 269 /// 270 /// You can look at these with the [`as_ptr`], [`len`], and [`capacity`] 271 /// methods: 272 /// 273 /// ``` 274 /// use std::mem; 275 /// 276 /// let story = String::from("Once upon a time..."); 277 /// 278 // FIXME Update this when vec_into_raw_parts is stabilized 279 /// // Prevent automatically dropping the String's data 280 /// let mut story = mem::ManuallyDrop::new(story); 281 /// 282 /// let ptr = story.as_mut_ptr(); 283 /// let len = story.len(); 284 /// let capacity = story.capacity(); 285 /// 286 /// // story has nineteen bytes 287 /// assert_eq!(19, len); 288 /// 289 /// // We can re-build a String out of ptr, len, and capacity. This is all 290 /// // unsafe because we are responsible for making sure the components are 291 /// // valid: 292 /// let s = unsafe { String::from_raw_parts(ptr, len, capacity) } ; 293 /// 294 /// assert_eq!(String::from("Once upon a time..."), s); 295 /// ``` 296 /// 297 /// [`as_ptr`]: str::as_ptr 298 /// [`len`]: String::len 299 /// [`capacity`]: String::capacity 300 /// 301 /// If a `String` has enough capacity, adding elements to it will not 302 /// re-allocate. For example, consider this program: 303 /// 304 /// ``` 305 /// let mut s = String::new(); 306 /// 307 /// println!("{}", s.capacity()); 308 /// 309 /// for _ in 0..5 { 310 /// s.push_str("hello"); 311 /// println!("{}", s.capacity()); 312 /// } 313 /// ``` 314 /// 315 /// This will output the following: 316 /// 317 /// ```text 318 /// 0 319 /// 8 320 /// 16 321 /// 16 322 /// 32 323 /// 32 324 /// ``` 325 /// 326 /// At first, we have no memory allocated at all, but as we append to the 327 /// string, it increases its capacity appropriately. If we instead use the 328 /// [`with_capacity`] method to allocate the correct capacity initially: 329 /// 330 /// ``` 331 /// let mut s = String::with_capacity(25); 332 /// 333 /// println!("{}", s.capacity()); 334 /// 335 /// for _ in 0..5 { 336 /// s.push_str("hello"); 337 /// println!("{}", s.capacity()); 338 /// } 339 /// ``` 340 /// 341 /// [`with_capacity`]: String::with_capacity 342 /// 343 /// We end up with a different output: 344 /// 345 /// ```text 346 /// 25 347 /// 25 348 /// 25 349 /// 25 350 /// 25 351 /// 25 352 /// ``` 353 /// 354 /// Here, there's no need to allocate more memory inside the loop. 355 /// 356 /// [str]: prim@str "str" 357 /// [`str`]: prim@str "str" 358 /// [`&str`]: prim@str "&str" 359 /// [Deref]: core::ops::Deref "ops::Deref" 360 /// [`Deref`]: core::ops::Deref "ops::Deref" 361 /// [`as_str()`]: String::as_str 362 #[derive(PartialEq, PartialOrd, Eq, Ord)] 363 #[stable(feature = "rust1", since = "1.0.0")] 364 #[cfg_attr(not(test), lang = "String")] 365 pub struct String { 366 vec: Vec<u8>, 367 } 368 369 /// A possible error value when converting a `String` from a UTF-8 byte vector. 370 /// 371 /// This type is the error type for the [`from_utf8`] method on [`String`]. It 372 /// is designed in such a way to carefully avoid reallocations: the 373 /// [`into_bytes`] method will give back the byte vector that was used in the 374 /// conversion attempt. 375 /// 376 /// [`from_utf8`]: String::from_utf8 377 /// [`into_bytes`]: FromUtf8Error::into_bytes 378 /// 379 /// The [`Utf8Error`] type provided by [`std::str`] represents an error that may 380 /// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's 381 /// an analogue to `FromUtf8Error`, and you can get one from a `FromUtf8Error` 382 /// through the [`utf8_error`] method. 383 /// 384 /// [`Utf8Error`]: str::Utf8Error "std::str::Utf8Error" 385 /// [`std::str`]: core::str "std::str" 386 /// [`&str`]: prim@str "&str" 387 /// [`utf8_error`]: FromUtf8Error::utf8_error 388 /// 389 /// # Examples 390 /// 391 /// Basic usage: 392 /// 393 /// ``` 394 /// // some invalid bytes, in a vector 395 /// let bytes = vec![0, 159]; 396 /// 397 /// let value = String::from_utf8(bytes); 398 /// 399 /// assert!(value.is_err()); 400 /// assert_eq!(vec![0, 159], value.unwrap_err().into_bytes()); 401 /// ``` 402 #[stable(feature = "rust1", since = "1.0.0")] 403 #[cfg_attr(not(no_global_oom_handling), derive(Clone))] 404 #[derive(Debug, PartialEq, Eq)] 405 pub struct FromUtf8Error { 406 bytes: Vec<u8>, 407 error: Utf8Error, 408 } 409 410 /// A possible error value when converting a `String` from a UTF-16 byte slice. 411 /// 412 /// This type is the error type for the [`from_utf16`] method on [`String`]. 413 /// 414 /// [`from_utf16`]: String::from_utf16 415 /// # Examples 416 /// 417 /// Basic usage: 418 /// 419 /// ``` 420 /// // ��mu<invalid>ic 421 /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075, 422 /// 0xD800, 0x0069, 0x0063]; 423 /// 424 /// assert!(String::from_utf16(v).is_err()); 425 /// ``` 426 #[stable(feature = "rust1", since = "1.0.0")] 427 #[derive(Debug)] 428 pub struct FromUtf16Error(()); 429 430 impl String { 431 /// Creates a new empty `String`. 432 /// 433 /// Given that the `String` is empty, this will not allocate any initial 434 /// buffer. While that means that this initial operation is very 435 /// inexpensive, it may cause excessive allocation later when you add 436 /// data. If you have an idea of how much data the `String` will hold, 437 /// consider the [`with_capacity`] method to prevent excessive 438 /// re-allocation. 439 /// 440 /// [`with_capacity`]: String::with_capacity 441 /// 442 /// # Examples 443 /// 444 /// Basic usage: 445 /// 446 /// ``` 447 /// let s = String::new(); 448 /// ``` 449 #[inline] 450 #[rustc_const_stable(feature = "const_string_new", since = "1.39.0")] 451 #[stable(feature = "rust1", since = "1.0.0")] 452 #[must_use] new() -> String453 pub const fn new() -> String { 454 String { vec: Vec::new() } 455 } 456 457 /// Creates a new empty `String` with at least the specified capacity. 458 /// 459 /// `String`s have an internal buffer to hold their data. The capacity is 460 /// the length of that buffer, and can be queried with the [`capacity`] 461 /// method. This method creates an empty `String`, but one with an initial 462 /// buffer that can hold at least `capacity` bytes. This is useful when you 463 /// may be appending a bunch of data to the `String`, reducing the number of 464 /// reallocations it needs to do. 465 /// 466 /// [`capacity`]: String::capacity 467 /// 468 /// If the given capacity is `0`, no allocation will occur, and this method 469 /// is identical to the [`new`] method. 470 /// 471 /// [`new`]: String::new 472 /// 473 /// # Examples 474 /// 475 /// Basic usage: 476 /// 477 /// ``` 478 /// let mut s = String::with_capacity(10); 479 /// 480 /// // The String contains no chars, even though it has capacity for more 481 /// assert_eq!(s.len(), 0); 482 /// 483 /// // These are all done without reallocating... 484 /// let cap = s.capacity(); 485 /// for _ in 0..10 { 486 /// s.push('a'); 487 /// } 488 /// 489 /// assert_eq!(s.capacity(), cap); 490 /// 491 /// // ...but this may make the string reallocate 492 /// s.push('a'); 493 /// ``` 494 #[cfg(not(no_global_oom_handling))] 495 #[inline] 496 #[stable(feature = "rust1", since = "1.0.0")] 497 #[must_use] with_capacity(capacity: usize) -> String498 pub fn with_capacity(capacity: usize) -> String { 499 String { vec: Vec::with_capacity(capacity) } 500 } 501 502 // HACK(japaric): with cfg(test) the inherent `[T]::to_vec` method, which is 503 // required for this method definition, is not available. Since we don't 504 // require this method for testing purposes, I'll just stub it 505 // NB see the slice::hack module in slice.rs for more information 506 #[inline] 507 #[cfg(test)] from_str(_: &str) -> String508 pub fn from_str(_: &str) -> String { 509 panic!("not available with cfg(test)"); 510 } 511 512 /// Converts a vector of bytes to a `String`. 513 /// 514 /// A string ([`String`]) is made of bytes ([`u8`]), and a vector of bytes 515 /// ([`Vec<u8>`]) is made of bytes, so this function converts between the 516 /// two. Not all byte slices are valid `String`s, however: `String` 517 /// requires that it is valid UTF-8. `from_utf8()` checks to ensure that 518 /// the bytes are valid UTF-8, and then does the conversion. 519 /// 520 /// If you are sure that the byte slice is valid UTF-8, and you don't want 521 /// to incur the overhead of the validity check, there is an unsafe version 522 /// of this function, [`from_utf8_unchecked`], which has the same behavior 523 /// but skips the check. 524 /// 525 /// This method will take care to not copy the vector, for efficiency's 526 /// sake. 527 /// 528 /// If you need a [`&str`] instead of a `String`, consider 529 /// [`str::from_utf8`]. 530 /// 531 /// The inverse of this method is [`into_bytes`]. 532 /// 533 /// # Errors 534 /// 535 /// Returns [`Err`] if the slice is not UTF-8 with a description as to why the 536 /// provided bytes are not UTF-8. The vector you moved in is also included. 537 /// 538 /// # Examples 539 /// 540 /// Basic usage: 541 /// 542 /// ``` 543 /// // some bytes, in a vector 544 /// let sparkle_heart = vec![240, 159, 146, 150]; 545 /// 546 /// // We know these bytes are valid, so we'll use `unwrap()`. 547 /// let sparkle_heart = String::from_utf8(sparkle_heart).unwrap(); 548 /// 549 /// assert_eq!("��", sparkle_heart); 550 /// ``` 551 /// 552 /// Incorrect bytes: 553 /// 554 /// ``` 555 /// // some invalid bytes, in a vector 556 /// let sparkle_heart = vec![0, 159, 146, 150]; 557 /// 558 /// assert!(String::from_utf8(sparkle_heart).is_err()); 559 /// ``` 560 /// 561 /// See the docs for [`FromUtf8Error`] for more details on what you can do 562 /// with this error. 563 /// 564 /// [`from_utf8_unchecked`]: String::from_utf8_unchecked 565 /// [`Vec<u8>`]: crate::vec::Vec "Vec" 566 /// [`&str`]: prim@str "&str" 567 /// [`into_bytes`]: String::into_bytes 568 #[inline] 569 #[stable(feature = "rust1", since = "1.0.0")] from_utf8(vec: Vec<u8>) -> Result<String, FromUtf8Error>570 pub fn from_utf8(vec: Vec<u8>) -> Result<String, FromUtf8Error> { 571 match str::from_utf8(&vec) { 572 Ok(..) => Ok(String { vec }), 573 Err(e) => Err(FromUtf8Error { bytes: vec, error: e }), 574 } 575 } 576 577 /// Converts a slice of bytes to a string, including invalid characters. 578 /// 579 /// Strings are made of bytes ([`u8`]), and a slice of bytes 580 /// ([`&[u8]`][byteslice]) is made of bytes, so this function converts 581 /// between the two. Not all byte slices are valid strings, however: strings 582 /// are required to be valid UTF-8. During this conversion, 583 /// `from_utf8_lossy()` will replace any invalid UTF-8 sequences with 584 /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD], which looks like this: � 585 /// 586 /// [byteslice]: prim@slice 587 /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER 588 /// 589 /// If you are sure that the byte slice is valid UTF-8, and you don't want 590 /// to incur the overhead of the conversion, there is an unsafe version 591 /// of this function, [`from_utf8_unchecked`], which has the same behavior 592 /// but skips the checks. 593 /// 594 /// [`from_utf8_unchecked`]: String::from_utf8_unchecked 595 /// 596 /// This function returns a [`Cow<'a, str>`]. If our byte slice is invalid 597 /// UTF-8, then we need to insert the replacement characters, which will 598 /// change the size of the string, and hence, require a `String`. But if 599 /// it's already valid UTF-8, we don't need a new allocation. This return 600 /// type allows us to handle both cases. 601 /// 602 /// [`Cow<'a, str>`]: crate::borrow::Cow "borrow::Cow" 603 /// 604 /// # Examples 605 /// 606 /// Basic usage: 607 /// 608 /// ``` 609 /// // some bytes, in a vector 610 /// let sparkle_heart = vec![240, 159, 146, 150]; 611 /// 612 /// let sparkle_heart = String::from_utf8_lossy(&sparkle_heart); 613 /// 614 /// assert_eq!("��", sparkle_heart); 615 /// ``` 616 /// 617 /// Incorrect bytes: 618 /// 619 /// ``` 620 /// // some invalid bytes 621 /// let input = b"Hello \xF0\x90\x80World"; 622 /// let output = String::from_utf8_lossy(input); 623 /// 624 /// assert_eq!("Hello �World", output); 625 /// ``` 626 #[must_use] 627 #[cfg(not(no_global_oom_handling))] 628 #[stable(feature = "rust1", since = "1.0.0")] from_utf8_lossy(v: &[u8]) -> Cow<'_, str>629 pub fn from_utf8_lossy(v: &[u8]) -> Cow<'_, str> { 630 let mut iter = Utf8Chunks::new(v); 631 632 let first_valid = if let Some(chunk) = iter.next() { 633 let valid = chunk.valid(); 634 if chunk.invalid().is_empty() { 635 debug_assert_eq!(valid.len(), v.len()); 636 return Cow::Borrowed(valid); 637 } 638 valid 639 } else { 640 return Cow::Borrowed(""); 641 }; 642 643 const REPLACEMENT: &str = "\u{FFFD}"; 644 645 let mut res = String::with_capacity(v.len()); 646 res.push_str(first_valid); 647 res.push_str(REPLACEMENT); 648 649 for chunk in iter { 650 res.push_str(chunk.valid()); 651 if !chunk.invalid().is_empty() { 652 res.push_str(REPLACEMENT); 653 } 654 } 655 656 Cow::Owned(res) 657 } 658 659 /// Decode a UTF-16–encoded vector `v` into a `String`, returning [`Err`] 660 /// if `v` contains any invalid data. 661 /// 662 /// # Examples 663 /// 664 /// Basic usage: 665 /// 666 /// ``` 667 /// // ��music 668 /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075, 669 /// 0x0073, 0x0069, 0x0063]; 670 /// assert_eq!(String::from("��music"), 671 /// String::from_utf16(v).unwrap()); 672 /// 673 /// // ��mu<invalid>ic 674 /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075, 675 /// 0xD800, 0x0069, 0x0063]; 676 /// assert!(String::from_utf16(v).is_err()); 677 /// ``` 678 #[cfg(not(no_global_oom_handling))] 679 #[stable(feature = "rust1", since = "1.0.0")] from_utf16(v: &[u16]) -> Result<String, FromUtf16Error>680 pub fn from_utf16(v: &[u16]) -> Result<String, FromUtf16Error> { 681 // This isn't done via collect::<Result<_, _>>() for performance reasons. 682 // FIXME: the function can be simplified again when #48994 is closed. 683 let mut ret = String::with_capacity(v.len()); 684 for c in char::decode_utf16(v.iter().cloned()) { 685 if let Ok(c) = c { 686 ret.push(c); 687 } else { 688 return Err(FromUtf16Error(())); 689 } 690 } 691 Ok(ret) 692 } 693 694 /// Decode a UTF-16–encoded slice `v` into a `String`, replacing 695 /// invalid data with [the replacement character (`U+FFFD`)][U+FFFD]. 696 /// 697 /// Unlike [`from_utf8_lossy`] which returns a [`Cow<'a, str>`], 698 /// `from_utf16_lossy` returns a `String` since the UTF-16 to UTF-8 699 /// conversion requires a memory allocation. 700 /// 701 /// [`from_utf8_lossy`]: String::from_utf8_lossy 702 /// [`Cow<'a, str>`]: crate::borrow::Cow "borrow::Cow" 703 /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER 704 /// 705 /// # Examples 706 /// 707 /// Basic usage: 708 /// 709 /// ``` 710 /// // ��mus<invalid>ic<invalid> 711 /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075, 712 /// 0x0073, 0xDD1E, 0x0069, 0x0063, 713 /// 0xD834]; 714 /// 715 /// assert_eq!(String::from("��mus\u{FFFD}ic\u{FFFD}"), 716 /// String::from_utf16_lossy(v)); 717 /// ``` 718 #[cfg(not(no_global_oom_handling))] 719 #[must_use] 720 #[inline] 721 #[stable(feature = "rust1", since = "1.0.0")] from_utf16_lossy(v: &[u16]) -> String722 pub fn from_utf16_lossy(v: &[u16]) -> String { 723 char::decode_utf16(v.iter().cloned()) 724 .map(|r| r.unwrap_or(char::REPLACEMENT_CHARACTER)) 725 .collect() 726 } 727 728 /// Decomposes a `String` into its raw components. 729 /// 730 /// Returns the raw pointer to the underlying data, the length of 731 /// the string (in bytes), and the allocated capacity of the data 732 /// (in bytes). These are the same arguments in the same order as 733 /// the arguments to [`from_raw_parts`]. 734 /// 735 /// After calling this function, the caller is responsible for the 736 /// memory previously managed by the `String`. The only way to do 737 /// this is to convert the raw pointer, length, and capacity back 738 /// into a `String` with the [`from_raw_parts`] function, allowing 739 /// the destructor to perform the cleanup. 740 /// 741 /// [`from_raw_parts`]: String::from_raw_parts 742 /// 743 /// # Examples 744 /// 745 /// ``` 746 /// #![feature(vec_into_raw_parts)] 747 /// let s = String::from("hello"); 748 /// 749 /// let (ptr, len, cap) = s.into_raw_parts(); 750 /// 751 /// let rebuilt = unsafe { String::from_raw_parts(ptr, len, cap) }; 752 /// assert_eq!(rebuilt, "hello"); 753 /// ``` 754 #[must_use = "`self` will be dropped if the result is not used"] 755 #[unstable(feature = "vec_into_raw_parts", reason = "new API", issue = "65816")] into_raw_parts(self) -> (*mut u8, usize, usize)756 pub fn into_raw_parts(self) -> (*mut u8, usize, usize) { 757 self.vec.into_raw_parts() 758 } 759 760 /// Creates a new `String` from a length, capacity, and pointer. 761 /// 762 /// # Safety 763 /// 764 /// This is highly unsafe, due to the number of invariants that aren't 765 /// checked: 766 /// 767 /// * The memory at `buf` needs to have been previously allocated by the 768 /// same allocator the standard library uses, with a required alignment of exactly 1. 769 /// * `length` needs to be less than or equal to `capacity`. 770 /// * `capacity` needs to be the correct value. 771 /// * The first `length` bytes at `buf` need to be valid UTF-8. 772 /// 773 /// Violating these may cause problems like corrupting the allocator's 774 /// internal data structures. For example, it is normally **not** safe to 775 /// build a `String` from a pointer to a C `char` array containing UTF-8 776 /// _unless_ you are certain that array was originally allocated by the 777 /// Rust standard library's allocator. 778 /// 779 /// The ownership of `buf` is effectively transferred to the 780 /// `String` which may then deallocate, reallocate or change the 781 /// contents of memory pointed to by the pointer at will. Ensure 782 /// that nothing else uses the pointer after calling this 783 /// function. 784 /// 785 /// # Examples 786 /// 787 /// Basic usage: 788 /// 789 /// ``` 790 /// use std::mem; 791 /// 792 /// unsafe { 793 /// let s = String::from("hello"); 794 /// 795 // FIXME Update this when vec_into_raw_parts is stabilized 796 /// // Prevent automatically dropping the String's data 797 /// let mut s = mem::ManuallyDrop::new(s); 798 /// 799 /// let ptr = s.as_mut_ptr(); 800 /// let len = s.len(); 801 /// let capacity = s.capacity(); 802 /// 803 /// let s = String::from_raw_parts(ptr, len, capacity); 804 /// 805 /// assert_eq!(String::from("hello"), s); 806 /// } 807 /// ``` 808 #[inline] 809 #[stable(feature = "rust1", since = "1.0.0")] from_raw_parts(buf: *mut u8, length: usize, capacity: usize) -> String810 pub unsafe fn from_raw_parts(buf: *mut u8, length: usize, capacity: usize) -> String { 811 unsafe { String { vec: Vec::from_raw_parts(buf, length, capacity) } } 812 } 813 814 /// Converts a vector of bytes to a `String` without checking that the 815 /// string contains valid UTF-8. 816 /// 817 /// See the safe version, [`from_utf8`], for more details. 818 /// 819 /// [`from_utf8`]: String::from_utf8 820 /// 821 /// # Safety 822 /// 823 /// This function is unsafe because it does not check that the bytes passed 824 /// to it are valid UTF-8. If this constraint is violated, it may cause 825 /// memory unsafety issues with future users of the `String`, as the rest of 826 /// the standard library assumes that `String`s are valid UTF-8. 827 /// 828 /// # Examples 829 /// 830 /// Basic usage: 831 /// 832 /// ``` 833 /// // some bytes, in a vector 834 /// let sparkle_heart = vec![240, 159, 146, 150]; 835 /// 836 /// let sparkle_heart = unsafe { 837 /// String::from_utf8_unchecked(sparkle_heart) 838 /// }; 839 /// 840 /// assert_eq!("��", sparkle_heart); 841 /// ``` 842 #[inline] 843 #[must_use] 844 #[stable(feature = "rust1", since = "1.0.0")] from_utf8_unchecked(bytes: Vec<u8>) -> String845 pub unsafe fn from_utf8_unchecked(bytes: Vec<u8>) -> String { 846 String { vec: bytes } 847 } 848 849 /// Converts a `String` into a byte vector. 850 /// 851 /// This consumes the `String`, so we do not need to copy its contents. 852 /// 853 /// # Examples 854 /// 855 /// Basic usage: 856 /// 857 /// ``` 858 /// let s = String::from("hello"); 859 /// let bytes = s.into_bytes(); 860 /// 861 /// assert_eq!(&[104, 101, 108, 108, 111][..], &bytes[..]); 862 /// ``` 863 #[inline] 864 #[must_use = "`self` will be dropped if the result is not used"] 865 #[stable(feature = "rust1", since = "1.0.0")] into_bytes(self) -> Vec<u8>866 pub fn into_bytes(self) -> Vec<u8> { 867 self.vec 868 } 869 870 /// Extracts a string slice containing the entire `String`. 871 /// 872 /// # Examples 873 /// 874 /// Basic usage: 875 /// 876 /// ``` 877 /// let s = String::from("foo"); 878 /// 879 /// assert_eq!("foo", s.as_str()); 880 /// ``` 881 #[inline] 882 #[must_use] 883 #[stable(feature = "string_as_str", since = "1.7.0")] as_str(&self) -> &str884 pub fn as_str(&self) -> &str { 885 self 886 } 887 888 /// Converts a `String` into a mutable string slice. 889 /// 890 /// # Examples 891 /// 892 /// Basic usage: 893 /// 894 /// ``` 895 /// let mut s = String::from("foobar"); 896 /// let s_mut_str = s.as_mut_str(); 897 /// 898 /// s_mut_str.make_ascii_uppercase(); 899 /// 900 /// assert_eq!("FOOBAR", s_mut_str); 901 /// ``` 902 #[inline] 903 #[must_use] 904 #[stable(feature = "string_as_str", since = "1.7.0")] as_mut_str(&mut self) -> &mut str905 pub fn as_mut_str(&mut self) -> &mut str { 906 self 907 } 908 909 /// Appends a given string slice onto the end of this `String`. 910 /// 911 /// # Examples 912 /// 913 /// Basic usage: 914 /// 915 /// ``` 916 /// let mut s = String::from("foo"); 917 /// 918 /// s.push_str("bar"); 919 /// 920 /// assert_eq!("foobar", s); 921 /// ``` 922 #[cfg(not(no_global_oom_handling))] 923 #[inline] 924 #[stable(feature = "rust1", since = "1.0.0")] push_str(&mut self, string: &str)925 pub fn push_str(&mut self, string: &str) { 926 self.vec.extend_from_slice(string.as_bytes()) 927 } 928 929 /// Copies elements from `src` range to the end of the string. 930 /// 931 /// # Panics 932 /// 933 /// Panics if the starting point or end point do not lie on a [`char`] 934 /// boundary, or if they're out of bounds. 935 /// 936 /// # Examples 937 /// 938 /// ``` 939 /// #![feature(string_extend_from_within)] 940 /// let mut string = String::from("abcde"); 941 /// 942 /// string.extend_from_within(2..); 943 /// assert_eq!(string, "abcdecde"); 944 /// 945 /// string.extend_from_within(..2); 946 /// assert_eq!(string, "abcdecdeab"); 947 /// 948 /// string.extend_from_within(4..8); 949 /// assert_eq!(string, "abcdecdeabecde"); 950 /// ``` 951 #[cfg(not(no_global_oom_handling))] 952 #[unstable(feature = "string_extend_from_within", issue = "103806")] extend_from_within<R>(&mut self, src: R) where R: RangeBounds<usize>,953 pub fn extend_from_within<R>(&mut self, src: R) 954 where 955 R: RangeBounds<usize>, 956 { 957 let src @ Range { start, end } = slice::range(src, ..self.len()); 958 959 assert!(self.is_char_boundary(start)); 960 assert!(self.is_char_boundary(end)); 961 962 self.vec.extend_from_within(src); 963 } 964 965 /// Returns this `String`'s capacity, in bytes. 966 /// 967 /// # Examples 968 /// 969 /// Basic usage: 970 /// 971 /// ``` 972 /// let s = String::with_capacity(10); 973 /// 974 /// assert!(s.capacity() >= 10); 975 /// ``` 976 #[inline] 977 #[must_use] 978 #[stable(feature = "rust1", since = "1.0.0")] capacity(&self) -> usize979 pub fn capacity(&self) -> usize { 980 self.vec.capacity() 981 } 982 983 /// Reserves capacity for at least `additional` bytes more than the 984 /// current length. The allocator may reserve more space to speculatively 985 /// avoid frequent allocations. After calling `reserve`, 986 /// capacity will be greater than or equal to `self.len() + additional`. 987 /// Does nothing if capacity is already sufficient. 988 /// 989 /// # Panics 990 /// 991 /// Panics if the new capacity overflows [`usize`]. 992 /// 993 /// # Examples 994 /// 995 /// Basic usage: 996 /// 997 /// ``` 998 /// let mut s = String::new(); 999 /// 1000 /// s.reserve(10); 1001 /// 1002 /// assert!(s.capacity() >= 10); 1003 /// ``` 1004 /// 1005 /// This might not actually increase the capacity: 1006 /// 1007 /// ``` 1008 /// let mut s = String::with_capacity(10); 1009 /// s.push('a'); 1010 /// s.push('b'); 1011 /// 1012 /// // s now has a length of 2 and a capacity of at least 10 1013 /// let capacity = s.capacity(); 1014 /// assert_eq!(2, s.len()); 1015 /// assert!(capacity >= 10); 1016 /// 1017 /// // Since we already have at least an extra 8 capacity, calling this... 1018 /// s.reserve(8); 1019 /// 1020 /// // ... doesn't actually increase. 1021 /// assert_eq!(capacity, s.capacity()); 1022 /// ``` 1023 #[cfg(not(no_global_oom_handling))] 1024 #[inline] 1025 #[stable(feature = "rust1", since = "1.0.0")] reserve(&mut self, additional: usize)1026 pub fn reserve(&mut self, additional: usize) { 1027 self.vec.reserve(additional) 1028 } 1029 1030 /// Reserves the minimum capacity for at least `additional` bytes more than 1031 /// the current length. Unlike [`reserve`], this will not 1032 /// deliberately over-allocate to speculatively avoid frequent allocations. 1033 /// After calling `reserve_exact`, capacity will be greater than or equal to 1034 /// `self.len() + additional`. Does nothing if the capacity is already 1035 /// sufficient. 1036 /// 1037 /// [`reserve`]: String::reserve 1038 /// 1039 /// # Panics 1040 /// 1041 /// Panics if the new capacity overflows [`usize`]. 1042 /// 1043 /// # Examples 1044 /// 1045 /// Basic usage: 1046 /// 1047 /// ``` 1048 /// let mut s = String::new(); 1049 /// 1050 /// s.reserve_exact(10); 1051 /// 1052 /// assert!(s.capacity() >= 10); 1053 /// ``` 1054 /// 1055 /// This might not actually increase the capacity: 1056 /// 1057 /// ``` 1058 /// let mut s = String::with_capacity(10); 1059 /// s.push('a'); 1060 /// s.push('b'); 1061 /// 1062 /// // s now has a length of 2 and a capacity of at least 10 1063 /// let capacity = s.capacity(); 1064 /// assert_eq!(2, s.len()); 1065 /// assert!(capacity >= 10); 1066 /// 1067 /// // Since we already have at least an extra 8 capacity, calling this... 1068 /// s.reserve_exact(8); 1069 /// 1070 /// // ... doesn't actually increase. 1071 /// assert_eq!(capacity, s.capacity()); 1072 /// ``` 1073 #[cfg(not(no_global_oom_handling))] 1074 #[inline] 1075 #[stable(feature = "rust1", since = "1.0.0")] reserve_exact(&mut self, additional: usize)1076 pub fn reserve_exact(&mut self, additional: usize) { 1077 self.vec.reserve_exact(additional) 1078 } 1079 1080 /// Tries to reserve capacity for at least `additional` bytes more than the 1081 /// current length. The allocator may reserve more space to speculatively 1082 /// avoid frequent allocations. After calling `try_reserve`, capacity will be 1083 /// greater than or equal to `self.len() + additional` if it returns 1084 /// `Ok(())`. Does nothing if capacity is already sufficient. This method 1085 /// preserves the contents even if an error occurs. 1086 /// 1087 /// # Errors 1088 /// 1089 /// If the capacity overflows, or the allocator reports a failure, then an error 1090 /// is returned. 1091 /// 1092 /// # Examples 1093 /// 1094 /// ``` 1095 /// use std::collections::TryReserveError; 1096 /// 1097 /// fn process_data(data: &str) -> Result<String, TryReserveError> { 1098 /// let mut output = String::new(); 1099 /// 1100 /// // Pre-reserve the memory, exiting if we can't 1101 /// output.try_reserve(data.len())?; 1102 /// 1103 /// // Now we know this can't OOM in the middle of our complex work 1104 /// output.push_str(data); 1105 /// 1106 /// Ok(output) 1107 /// } 1108 /// # process_data("rust").expect("why is the test harness OOMing on 4 bytes?"); 1109 /// ``` 1110 #[stable(feature = "try_reserve", since = "1.57.0")] try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>1111 pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { 1112 self.vec.try_reserve(additional) 1113 } 1114 1115 /// Tries to reserve the minimum capacity for at least `additional` bytes 1116 /// more than the current length. Unlike [`try_reserve`], this will not 1117 /// deliberately over-allocate to speculatively avoid frequent allocations. 1118 /// After calling `try_reserve_exact`, capacity will be greater than or 1119 /// equal to `self.len() + additional` if it returns `Ok(())`. 1120 /// Does nothing if the capacity is already sufficient. 1121 /// 1122 /// Note that the allocator may give the collection more space than it 1123 /// requests. Therefore, capacity can not be relied upon to be precisely 1124 /// minimal. Prefer [`try_reserve`] if future insertions are expected. 1125 /// 1126 /// [`try_reserve`]: String::try_reserve 1127 /// 1128 /// # Errors 1129 /// 1130 /// If the capacity overflows, or the allocator reports a failure, then an error 1131 /// is returned. 1132 /// 1133 /// # Examples 1134 /// 1135 /// ``` 1136 /// use std::collections::TryReserveError; 1137 /// 1138 /// fn process_data(data: &str) -> Result<String, TryReserveError> { 1139 /// let mut output = String::new(); 1140 /// 1141 /// // Pre-reserve the memory, exiting if we can't 1142 /// output.try_reserve_exact(data.len())?; 1143 /// 1144 /// // Now we know this can't OOM in the middle of our complex work 1145 /// output.push_str(data); 1146 /// 1147 /// Ok(output) 1148 /// } 1149 /// # process_data("rust").expect("why is the test harness OOMing on 4 bytes?"); 1150 /// ``` 1151 #[stable(feature = "try_reserve", since = "1.57.0")] try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError>1152 pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> { 1153 self.vec.try_reserve_exact(additional) 1154 } 1155 1156 /// Shrinks the capacity of this `String` to match its length. 1157 /// 1158 /// # Examples 1159 /// 1160 /// Basic usage: 1161 /// 1162 /// ``` 1163 /// let mut s = String::from("foo"); 1164 /// 1165 /// s.reserve(100); 1166 /// assert!(s.capacity() >= 100); 1167 /// 1168 /// s.shrink_to_fit(); 1169 /// assert_eq!(3, s.capacity()); 1170 /// ``` 1171 #[cfg(not(no_global_oom_handling))] 1172 #[inline] 1173 #[stable(feature = "rust1", since = "1.0.0")] shrink_to_fit(&mut self)1174 pub fn shrink_to_fit(&mut self) { 1175 self.vec.shrink_to_fit() 1176 } 1177 1178 /// Shrinks the capacity of this `String` with a lower bound. 1179 /// 1180 /// The capacity will remain at least as large as both the length 1181 /// and the supplied value. 1182 /// 1183 /// If the current capacity is less than the lower limit, this is a no-op. 1184 /// 1185 /// # Examples 1186 /// 1187 /// ``` 1188 /// let mut s = String::from("foo"); 1189 /// 1190 /// s.reserve(100); 1191 /// assert!(s.capacity() >= 100); 1192 /// 1193 /// s.shrink_to(10); 1194 /// assert!(s.capacity() >= 10); 1195 /// s.shrink_to(0); 1196 /// assert!(s.capacity() >= 3); 1197 /// ``` 1198 #[cfg(not(no_global_oom_handling))] 1199 #[inline] 1200 #[stable(feature = "shrink_to", since = "1.56.0")] shrink_to(&mut self, min_capacity: usize)1201 pub fn shrink_to(&mut self, min_capacity: usize) { 1202 self.vec.shrink_to(min_capacity) 1203 } 1204 1205 /// Appends the given [`char`] to the end of this `String`. 1206 /// 1207 /// # Examples 1208 /// 1209 /// Basic usage: 1210 /// 1211 /// ``` 1212 /// let mut s = String::from("abc"); 1213 /// 1214 /// s.push('1'); 1215 /// s.push('2'); 1216 /// s.push('3'); 1217 /// 1218 /// assert_eq!("abc123", s); 1219 /// ``` 1220 #[cfg(not(no_global_oom_handling))] 1221 #[inline] 1222 #[stable(feature = "rust1", since = "1.0.0")] push(&mut self, ch: char)1223 pub fn push(&mut self, ch: char) { 1224 match ch.len_utf8() { 1225 1 => self.vec.push(ch as u8), 1226 _ => self.vec.extend_from_slice(ch.encode_utf8(&mut [0; 4]).as_bytes()), 1227 } 1228 } 1229 1230 /// Returns a byte slice of this `String`'s contents. 1231 /// 1232 /// The inverse of this method is [`from_utf8`]. 1233 /// 1234 /// [`from_utf8`]: String::from_utf8 1235 /// 1236 /// # Examples 1237 /// 1238 /// Basic usage: 1239 /// 1240 /// ``` 1241 /// let s = String::from("hello"); 1242 /// 1243 /// assert_eq!(&[104, 101, 108, 108, 111], s.as_bytes()); 1244 /// ``` 1245 #[inline] 1246 #[must_use] 1247 #[stable(feature = "rust1", since = "1.0.0")] as_bytes(&self) -> &[u8]1248 pub fn as_bytes(&self) -> &[u8] { 1249 &self.vec 1250 } 1251 1252 /// Shortens this `String` to the specified length. 1253 /// 1254 /// If `new_len` is greater than the string's current length, this has no 1255 /// effect. 1256 /// 1257 /// Note that this method has no effect on the allocated capacity 1258 /// of the string 1259 /// 1260 /// # Panics 1261 /// 1262 /// Panics if `new_len` does not lie on a [`char`] boundary. 1263 /// 1264 /// # Examples 1265 /// 1266 /// Basic usage: 1267 /// 1268 /// ``` 1269 /// let mut s = String::from("hello"); 1270 /// 1271 /// s.truncate(2); 1272 /// 1273 /// assert_eq!("he", s); 1274 /// ``` 1275 #[inline] 1276 #[stable(feature = "rust1", since = "1.0.0")] truncate(&mut self, new_len: usize)1277 pub fn truncate(&mut self, new_len: usize) { 1278 if new_len <= self.len() { 1279 assert!(self.is_char_boundary(new_len)); 1280 self.vec.truncate(new_len) 1281 } 1282 } 1283 1284 /// Removes the last character from the string buffer and returns it. 1285 /// 1286 /// Returns [`None`] if this `String` is empty. 1287 /// 1288 /// # Examples 1289 /// 1290 /// Basic usage: 1291 /// 1292 /// ``` 1293 /// let mut s = String::from("foo"); 1294 /// 1295 /// assert_eq!(s.pop(), Some('o')); 1296 /// assert_eq!(s.pop(), Some('o')); 1297 /// assert_eq!(s.pop(), Some('f')); 1298 /// 1299 /// assert_eq!(s.pop(), None); 1300 /// ``` 1301 #[inline] 1302 #[stable(feature = "rust1", since = "1.0.0")] pop(&mut self) -> Option<char>1303 pub fn pop(&mut self) -> Option<char> { 1304 let ch = self.chars().rev().next()?; 1305 let newlen = self.len() - ch.len_utf8(); 1306 unsafe { 1307 self.vec.set_len(newlen); 1308 } 1309 Some(ch) 1310 } 1311 1312 /// Removes a [`char`] from this `String` at a byte position and returns it. 1313 /// 1314 /// This is an *O*(*n*) operation, as it requires copying every element in the 1315 /// buffer. 1316 /// 1317 /// # Panics 1318 /// 1319 /// Panics if `idx` is larger than or equal to the `String`'s length, 1320 /// or if it does not lie on a [`char`] boundary. 1321 /// 1322 /// # Examples 1323 /// 1324 /// Basic usage: 1325 /// 1326 /// ``` 1327 /// let mut s = String::from("foo"); 1328 /// 1329 /// assert_eq!(s.remove(0), 'f'); 1330 /// assert_eq!(s.remove(1), 'o'); 1331 /// assert_eq!(s.remove(0), 'o'); 1332 /// ``` 1333 #[inline] 1334 #[stable(feature = "rust1", since = "1.0.0")] remove(&mut self, idx: usize) -> char1335 pub fn remove(&mut self, idx: usize) -> char { 1336 let ch = match self[idx..].chars().next() { 1337 Some(ch) => ch, 1338 None => panic!("cannot remove a char from the end of a string"), 1339 }; 1340 1341 let next = idx + ch.len_utf8(); 1342 let len = self.len(); 1343 unsafe { 1344 ptr::copy(self.vec.as_ptr().add(next), self.vec.as_mut_ptr().add(idx), len - next); 1345 self.vec.set_len(len - (next - idx)); 1346 } 1347 ch 1348 } 1349 1350 /// Remove all matches of pattern `pat` in the `String`. 1351 /// 1352 /// # Examples 1353 /// 1354 /// ``` 1355 /// #![feature(string_remove_matches)] 1356 /// let mut s = String::from("Trees are not green, the sky is not blue."); 1357 /// s.remove_matches("not "); 1358 /// assert_eq!("Trees are green, the sky is blue.", s); 1359 /// ``` 1360 /// 1361 /// Matches will be detected and removed iteratively, so in cases where 1362 /// patterns overlap, only the first pattern will be removed: 1363 /// 1364 /// ``` 1365 /// #![feature(string_remove_matches)] 1366 /// let mut s = String::from("banana"); 1367 /// s.remove_matches("ana"); 1368 /// assert_eq!("bna", s); 1369 /// ``` 1370 #[cfg(not(no_global_oom_handling))] 1371 #[unstable(feature = "string_remove_matches", reason = "new API", issue = "72826")] remove_matches<'a, P>(&'a mut self, pat: P) where P: for<'x> Pattern<'x>,1372 pub fn remove_matches<'a, P>(&'a mut self, pat: P) 1373 where 1374 P: for<'x> Pattern<'x>, 1375 { 1376 use core::str::pattern::Searcher; 1377 1378 let rejections = { 1379 let mut searcher = pat.into_searcher(self); 1380 // Per Searcher::next: 1381 // 1382 // A Match result needs to contain the whole matched pattern, 1383 // however Reject results may be split up into arbitrary many 1384 // adjacent fragments. Both ranges may have zero length. 1385 // 1386 // In practice the implementation of Searcher::next_match tends to 1387 // be more efficient, so we use it here and do some work to invert 1388 // matches into rejections since that's what we want to copy below. 1389 let mut front = 0; 1390 let rejections: Vec<_> = from_fn(|| { 1391 let (start, end) = searcher.next_match()?; 1392 let prev_front = front; 1393 front = end; 1394 Some((prev_front, start)) 1395 }) 1396 .collect(); 1397 rejections.into_iter().chain(core::iter::once((front, self.len()))) 1398 }; 1399 1400 let mut len = 0; 1401 let ptr = self.vec.as_mut_ptr(); 1402 1403 for (start, end) in rejections { 1404 let count = end - start; 1405 if start != len { 1406 // SAFETY: per Searcher::next: 1407 // 1408 // The stream of Match and Reject values up to a Done will 1409 // contain index ranges that are adjacent, non-overlapping, 1410 // covering the whole haystack, and laying on utf8 1411 // boundaries. 1412 unsafe { 1413 ptr::copy(ptr.add(start), ptr.add(len), count); 1414 } 1415 } 1416 len += count; 1417 } 1418 1419 unsafe { 1420 self.vec.set_len(len); 1421 } 1422 } 1423 1424 /// Retains only the characters specified by the predicate. 1425 /// 1426 /// In other words, remove all characters `c` such that `f(c)` returns `false`. 1427 /// This method operates in place, visiting each character exactly once in the 1428 /// original order, and preserves the order of the retained characters. 1429 /// 1430 /// # Examples 1431 /// 1432 /// ``` 1433 /// let mut s = String::from("f_o_ob_ar"); 1434 /// 1435 /// s.retain(|c| c != '_'); 1436 /// 1437 /// assert_eq!(s, "foobar"); 1438 /// ``` 1439 /// 1440 /// Because the elements are visited exactly once in the original order, 1441 /// external state may be used to decide which elements to keep. 1442 /// 1443 /// ``` 1444 /// let mut s = String::from("abcde"); 1445 /// let keep = [false, true, true, false, true]; 1446 /// let mut iter = keep.iter(); 1447 /// s.retain(|_| *iter.next().unwrap()); 1448 /// assert_eq!(s, "bce"); 1449 /// ``` 1450 #[inline] 1451 #[stable(feature = "string_retain", since = "1.26.0")] retain<F>(&mut self, mut f: F) where F: FnMut(char) -> bool,1452 pub fn retain<F>(&mut self, mut f: F) 1453 where 1454 F: FnMut(char) -> bool, 1455 { 1456 struct SetLenOnDrop<'a> { 1457 s: &'a mut String, 1458 idx: usize, 1459 del_bytes: usize, 1460 } 1461 1462 impl<'a> Drop for SetLenOnDrop<'a> { 1463 fn drop(&mut self) { 1464 let new_len = self.idx - self.del_bytes; 1465 debug_assert!(new_len <= self.s.len()); 1466 unsafe { self.s.vec.set_len(new_len) }; 1467 } 1468 } 1469 1470 let len = self.len(); 1471 let mut guard = SetLenOnDrop { s: self, idx: 0, del_bytes: 0 }; 1472 1473 while guard.idx < len { 1474 let ch = 1475 // SAFETY: `guard.idx` is positive-or-zero and less that len so the `get_unchecked` 1476 // is in bound. `self` is valid UTF-8 like string and the returned slice starts at 1477 // a unicode code point so the `Chars` always return one character. 1478 unsafe { guard.s.get_unchecked(guard.idx..len).chars().next().unwrap_unchecked() }; 1479 let ch_len = ch.len_utf8(); 1480 1481 if !f(ch) { 1482 guard.del_bytes += ch_len; 1483 } else if guard.del_bytes > 0 { 1484 // SAFETY: `guard.idx` is in bound and `guard.del_bytes` represent the number of 1485 // bytes that are erased from the string so the resulting `guard.idx - 1486 // guard.del_bytes` always represent a valid unicode code point. 1487 // 1488 // `guard.del_bytes` >= `ch.len_utf8()`, so taking a slice with `ch.len_utf8()` len 1489 // is safe. 1490 ch.encode_utf8(unsafe { 1491 crate::slice::from_raw_parts_mut( 1492 guard.s.as_mut_ptr().add(guard.idx - guard.del_bytes), 1493 ch.len_utf8(), 1494 ) 1495 }); 1496 } 1497 1498 // Point idx to the next char 1499 guard.idx += ch_len; 1500 } 1501 1502 drop(guard); 1503 } 1504 1505 /// Inserts a character into this `String` at a byte position. 1506 /// 1507 /// This is an *O*(*n*) operation as it requires copying every element in the 1508 /// buffer. 1509 /// 1510 /// # Panics 1511 /// 1512 /// Panics if `idx` is larger than the `String`'s length, or if it does not 1513 /// lie on a [`char`] boundary. 1514 /// 1515 /// # Examples 1516 /// 1517 /// Basic usage: 1518 /// 1519 /// ``` 1520 /// let mut s = String::with_capacity(3); 1521 /// 1522 /// s.insert(0, 'f'); 1523 /// s.insert(1, 'o'); 1524 /// s.insert(2, 'o'); 1525 /// 1526 /// assert_eq!("foo", s); 1527 /// ``` 1528 #[cfg(not(no_global_oom_handling))] 1529 #[inline] 1530 #[stable(feature = "rust1", since = "1.0.0")] insert(&mut self, idx: usize, ch: char)1531 pub fn insert(&mut self, idx: usize, ch: char) { 1532 assert!(self.is_char_boundary(idx)); 1533 let mut bits = [0; 4]; 1534 let bits = ch.encode_utf8(&mut bits).as_bytes(); 1535 1536 unsafe { 1537 self.insert_bytes(idx, bits); 1538 } 1539 } 1540 1541 #[cfg(not(no_global_oom_handling))] insert_bytes(&mut self, idx: usize, bytes: &[u8])1542 unsafe fn insert_bytes(&mut self, idx: usize, bytes: &[u8]) { 1543 let len = self.len(); 1544 let amt = bytes.len(); 1545 self.vec.reserve(amt); 1546 1547 unsafe { 1548 ptr::copy(self.vec.as_ptr().add(idx), self.vec.as_mut_ptr().add(idx + amt), len - idx); 1549 ptr::copy_nonoverlapping(bytes.as_ptr(), self.vec.as_mut_ptr().add(idx), amt); 1550 self.vec.set_len(len + amt); 1551 } 1552 } 1553 1554 /// Inserts a string slice into this `String` at a byte position. 1555 /// 1556 /// This is an *O*(*n*) operation as it requires copying every element in the 1557 /// buffer. 1558 /// 1559 /// # Panics 1560 /// 1561 /// Panics if `idx` is larger than the `String`'s length, or if it does not 1562 /// lie on a [`char`] boundary. 1563 /// 1564 /// # Examples 1565 /// 1566 /// Basic usage: 1567 /// 1568 /// ``` 1569 /// let mut s = String::from("bar"); 1570 /// 1571 /// s.insert_str(0, "foo"); 1572 /// 1573 /// assert_eq!("foobar", s); 1574 /// ``` 1575 #[cfg(not(no_global_oom_handling))] 1576 #[inline] 1577 #[stable(feature = "insert_str", since = "1.16.0")] insert_str(&mut self, idx: usize, string: &str)1578 pub fn insert_str(&mut self, idx: usize, string: &str) { 1579 assert!(self.is_char_boundary(idx)); 1580 1581 unsafe { 1582 self.insert_bytes(idx, string.as_bytes()); 1583 } 1584 } 1585 1586 /// Returns a mutable reference to the contents of this `String`. 1587 /// 1588 /// # Safety 1589 /// 1590 /// This function is unsafe because the returned `&mut Vec` allows writing 1591 /// bytes which are not valid UTF-8. If this constraint is violated, using 1592 /// the original `String` after dropping the `&mut Vec` may violate memory 1593 /// safety, as the rest of the standard library assumes that `String`s are 1594 /// valid UTF-8. 1595 /// 1596 /// # Examples 1597 /// 1598 /// Basic usage: 1599 /// 1600 /// ``` 1601 /// let mut s = String::from("hello"); 1602 /// 1603 /// unsafe { 1604 /// let vec = s.as_mut_vec(); 1605 /// assert_eq!(&[104, 101, 108, 108, 111][..], &vec[..]); 1606 /// 1607 /// vec.reverse(); 1608 /// } 1609 /// assert_eq!(s, "olleh"); 1610 /// ``` 1611 #[inline] 1612 #[stable(feature = "rust1", since = "1.0.0")] as_mut_vec(&mut self) -> &mut Vec<u8>1613 pub unsafe fn as_mut_vec(&mut self) -> &mut Vec<u8> { 1614 &mut self.vec 1615 } 1616 1617 /// Returns the length of this `String`, in bytes, not [`char`]s or 1618 /// graphemes. In other words, it might not be what a human considers the 1619 /// length of the string. 1620 /// 1621 /// # Examples 1622 /// 1623 /// Basic usage: 1624 /// 1625 /// ``` 1626 /// let a = String::from("foo"); 1627 /// assert_eq!(a.len(), 3); 1628 /// 1629 /// let fancy_f = String::from("ƒoo"); 1630 /// assert_eq!(fancy_f.len(), 4); 1631 /// assert_eq!(fancy_f.chars().count(), 3); 1632 /// ``` 1633 #[inline] 1634 #[must_use] 1635 #[stable(feature = "rust1", since = "1.0.0")] len(&self) -> usize1636 pub fn len(&self) -> usize { 1637 self.vec.len() 1638 } 1639 1640 /// Returns `true` if this `String` has a length of zero, and `false` otherwise. 1641 /// 1642 /// # Examples 1643 /// 1644 /// Basic usage: 1645 /// 1646 /// ``` 1647 /// let mut v = String::new(); 1648 /// assert!(v.is_empty()); 1649 /// 1650 /// v.push('a'); 1651 /// assert!(!v.is_empty()); 1652 /// ``` 1653 #[inline] 1654 #[must_use] 1655 #[stable(feature = "rust1", since = "1.0.0")] is_empty(&self) -> bool1656 pub fn is_empty(&self) -> bool { 1657 self.len() == 0 1658 } 1659 1660 /// Splits the string into two at the given byte index. 1661 /// 1662 /// Returns a newly allocated `String`. `self` contains bytes `[0, at)`, and 1663 /// the returned `String` contains bytes `[at, len)`. `at` must be on the 1664 /// boundary of a UTF-8 code point. 1665 /// 1666 /// Note that the capacity of `self` does not change. 1667 /// 1668 /// # Panics 1669 /// 1670 /// Panics if `at` is not on a `UTF-8` code point boundary, or if it is beyond the last 1671 /// code point of the string. 1672 /// 1673 /// # Examples 1674 /// 1675 /// ``` 1676 /// # fn main() { 1677 /// let mut hello = String::from("Hello, World!"); 1678 /// let world = hello.split_off(7); 1679 /// assert_eq!(hello, "Hello, "); 1680 /// assert_eq!(world, "World!"); 1681 /// # } 1682 /// ``` 1683 #[cfg(not(no_global_oom_handling))] 1684 #[inline] 1685 #[stable(feature = "string_split_off", since = "1.16.0")] 1686 #[must_use = "use `.truncate()` if you don't need the other half"] split_off(&mut self, at: usize) -> String1687 pub fn split_off(&mut self, at: usize) -> String { 1688 assert!(self.is_char_boundary(at)); 1689 let other = self.vec.split_off(at); 1690 unsafe { String::from_utf8_unchecked(other) } 1691 } 1692 1693 /// Truncates this `String`, removing all contents. 1694 /// 1695 /// While this means the `String` will have a length of zero, it does not 1696 /// touch its capacity. 1697 /// 1698 /// # Examples 1699 /// 1700 /// Basic usage: 1701 /// 1702 /// ``` 1703 /// let mut s = String::from("foo"); 1704 /// 1705 /// s.clear(); 1706 /// 1707 /// assert!(s.is_empty()); 1708 /// assert_eq!(0, s.len()); 1709 /// assert_eq!(3, s.capacity()); 1710 /// ``` 1711 #[inline] 1712 #[stable(feature = "rust1", since = "1.0.0")] clear(&mut self)1713 pub fn clear(&mut self) { 1714 self.vec.clear() 1715 } 1716 1717 /// Removes the specified range from the string in bulk, returning all 1718 /// removed characters as an iterator. 1719 /// 1720 /// The returned iterator keeps a mutable borrow on the string to optimize 1721 /// its implementation. 1722 /// 1723 /// # Panics 1724 /// 1725 /// Panics if the starting point or end point do not lie on a [`char`] 1726 /// boundary, or if they're out of bounds. 1727 /// 1728 /// # Leaking 1729 /// 1730 /// If the returned iterator goes out of scope without being dropped (due to 1731 /// [`core::mem::forget`], for example), the string may still contain a copy 1732 /// of any drained characters, or may have lost characters arbitrarily, 1733 /// including characters outside the range. 1734 /// 1735 /// # Examples 1736 /// 1737 /// Basic usage: 1738 /// 1739 /// ``` 1740 /// let mut s = String::from("α is alpha, β is beta"); 1741 /// let beta_offset = s.find('β').unwrap_or(s.len()); 1742 /// 1743 /// // Remove the range up until the β from the string 1744 /// let t: String = s.drain(..beta_offset).collect(); 1745 /// assert_eq!(t, "α is alpha, "); 1746 /// assert_eq!(s, "β is beta"); 1747 /// 1748 /// // A full range clears the string, like `clear()` does 1749 /// s.drain(..); 1750 /// assert_eq!(s, ""); 1751 /// ``` 1752 #[stable(feature = "drain", since = "1.6.0")] drain<R>(&mut self, range: R) -> Drain<'_> where R: RangeBounds<usize>,1753 pub fn drain<R>(&mut self, range: R) -> Drain<'_> 1754 where 1755 R: RangeBounds<usize>, 1756 { 1757 // Memory safety 1758 // 1759 // The String version of Drain does not have the memory safety issues 1760 // of the vector version. The data is just plain bytes. 1761 // Because the range removal happens in Drop, if the Drain iterator is leaked, 1762 // the removal will not happen. 1763 let Range { start, end } = slice::range(range, ..self.len()); 1764 assert!(self.is_char_boundary(start)); 1765 assert!(self.is_char_boundary(end)); 1766 1767 // Take out two simultaneous borrows. The &mut String won't be accessed 1768 // until iteration is over, in Drop. 1769 let self_ptr = self as *mut _; 1770 // SAFETY: `slice::range` and `is_char_boundary` do the appropriate bounds checks. 1771 let chars_iter = unsafe { self.get_unchecked(start..end) }.chars(); 1772 1773 Drain { start, end, iter: chars_iter, string: self_ptr } 1774 } 1775 1776 /// Removes the specified range in the string, 1777 /// and replaces it with the given string. 1778 /// The given string doesn't need to be the same length as the range. 1779 /// 1780 /// # Panics 1781 /// 1782 /// Panics if the starting point or end point do not lie on a [`char`] 1783 /// boundary, or if they're out of bounds. 1784 /// 1785 /// # Examples 1786 /// 1787 /// Basic usage: 1788 /// 1789 /// ``` 1790 /// let mut s = String::from("α is alpha, β is beta"); 1791 /// let beta_offset = s.find('β').unwrap_or(s.len()); 1792 /// 1793 /// // Replace the range up until the β from the string 1794 /// s.replace_range(..beta_offset, "Α is capital alpha; "); 1795 /// assert_eq!(s, "Α is capital alpha; β is beta"); 1796 /// ``` 1797 #[cfg(not(no_global_oom_handling))] 1798 #[stable(feature = "splice", since = "1.27.0")] replace_range<R>(&mut self, range: R, replace_with: &str) where R: RangeBounds<usize>,1799 pub fn replace_range<R>(&mut self, range: R, replace_with: &str) 1800 where 1801 R: RangeBounds<usize>, 1802 { 1803 // Memory safety 1804 // 1805 // Replace_range does not have the memory safety issues of a vector Splice. 1806 // of the vector version. The data is just plain bytes. 1807 1808 // WARNING: Inlining this variable would be unsound (#81138) 1809 let start = range.start_bound(); 1810 match start { 1811 Included(&n) => assert!(self.is_char_boundary(n)), 1812 Excluded(&n) => assert!(self.is_char_boundary(n + 1)), 1813 Unbounded => {} 1814 }; 1815 // WARNING: Inlining this variable would be unsound (#81138) 1816 let end = range.end_bound(); 1817 match end { 1818 Included(&n) => assert!(self.is_char_boundary(n + 1)), 1819 Excluded(&n) => assert!(self.is_char_boundary(n)), 1820 Unbounded => {} 1821 }; 1822 1823 // Using `range` again would be unsound (#81138) 1824 // We assume the bounds reported by `range` remain the same, but 1825 // an adversarial implementation could change between calls 1826 unsafe { self.as_mut_vec() }.splice((start, end), replace_with.bytes()); 1827 } 1828 1829 /// Converts this `String` into a <code>[Box]<[str]></code>. 1830 /// 1831 /// This will drop any excess capacity. 1832 /// 1833 /// [str]: prim@str "str" 1834 /// 1835 /// # Examples 1836 /// 1837 /// Basic usage: 1838 /// 1839 /// ``` 1840 /// let s = String::from("hello"); 1841 /// 1842 /// let b = s.into_boxed_str(); 1843 /// ``` 1844 #[cfg(not(no_global_oom_handling))] 1845 #[stable(feature = "box_str", since = "1.4.0")] 1846 #[must_use = "`self` will be dropped if the result is not used"] 1847 #[inline] into_boxed_str(self) -> Box<str>1848 pub fn into_boxed_str(self) -> Box<str> { 1849 let slice = self.vec.into_boxed_slice(); 1850 unsafe { from_boxed_utf8_unchecked(slice) } 1851 } 1852 1853 /// Consumes and leaks the `String`, returning a mutable reference to the contents, 1854 /// `&'a mut str`. 1855 /// 1856 /// The caller has free choice over the returned lifetime, including `'static`. Indeed, 1857 /// this function is ideally used for data that lives for the remainder of the program's life, 1858 /// as dropping the returned reference will cause a memory leak. 1859 /// 1860 /// It does not reallocate or shrink the `String`, 1861 /// so the leaked allocation may include unused capacity that is not part 1862 /// of the returned slice. If you don't want that, call [`into_boxed_str`], 1863 /// and then [`Box::leak`]. 1864 /// 1865 /// [`into_boxed_str`]: Self::into_boxed_str 1866 /// 1867 /// # Examples 1868 /// 1869 /// Simple usage: 1870 /// 1871 /// ``` 1872 /// let x = String::from("bucket"); 1873 /// let static_ref: &'static mut str = x.leak(); 1874 /// assert_eq!(static_ref, "bucket"); 1875 /// ``` 1876 #[stable(feature = "string_leak", since = "1.72.0")] 1877 #[inline] leak<'a>(self) -> &'a mut str1878 pub fn leak<'a>(self) -> &'a mut str { 1879 let slice = self.vec.leak(); 1880 unsafe { from_utf8_unchecked_mut(slice) } 1881 } 1882 } 1883 1884 impl FromUtf8Error { 1885 /// Returns a slice of [`u8`]s bytes that were attempted to convert to a `String`. 1886 /// 1887 /// # Examples 1888 /// 1889 /// Basic usage: 1890 /// 1891 /// ``` 1892 /// // some invalid bytes, in a vector 1893 /// let bytes = vec![0, 159]; 1894 /// 1895 /// let value = String::from_utf8(bytes); 1896 /// 1897 /// assert_eq!(&[0, 159], value.unwrap_err().as_bytes()); 1898 /// ``` 1899 #[must_use] 1900 #[stable(feature = "from_utf8_error_as_bytes", since = "1.26.0")] as_bytes(&self) -> &[u8]1901 pub fn as_bytes(&self) -> &[u8] { 1902 &self.bytes[..] 1903 } 1904 1905 /// Returns the bytes that were attempted to convert to a `String`. 1906 /// 1907 /// This method is carefully constructed to avoid allocation. It will 1908 /// consume the error, moving out the bytes, so that a copy of the bytes 1909 /// does not need to be made. 1910 /// 1911 /// # Examples 1912 /// 1913 /// Basic usage: 1914 /// 1915 /// ``` 1916 /// // some invalid bytes, in a vector 1917 /// let bytes = vec![0, 159]; 1918 /// 1919 /// let value = String::from_utf8(bytes); 1920 /// 1921 /// assert_eq!(vec![0, 159], value.unwrap_err().into_bytes()); 1922 /// ``` 1923 #[must_use = "`self` will be dropped if the result is not used"] 1924 #[stable(feature = "rust1", since = "1.0.0")] into_bytes(self) -> Vec<u8>1925 pub fn into_bytes(self) -> Vec<u8> { 1926 self.bytes 1927 } 1928 1929 /// Fetch a `Utf8Error` to get more details about the conversion failure. 1930 /// 1931 /// The [`Utf8Error`] type provided by [`std::str`] represents an error that may 1932 /// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's 1933 /// an analogue to `FromUtf8Error`. See its documentation for more details 1934 /// on using it. 1935 /// 1936 /// [`std::str`]: core::str "std::str" 1937 /// [`&str`]: prim@str "&str" 1938 /// 1939 /// # Examples 1940 /// 1941 /// Basic usage: 1942 /// 1943 /// ``` 1944 /// // some invalid bytes, in a vector 1945 /// let bytes = vec![0, 159]; 1946 /// 1947 /// let error = String::from_utf8(bytes).unwrap_err().utf8_error(); 1948 /// 1949 /// // the first byte is invalid here 1950 /// assert_eq!(1, error.valid_up_to()); 1951 /// ``` 1952 #[must_use] 1953 #[stable(feature = "rust1", since = "1.0.0")] utf8_error(&self) -> Utf8Error1954 pub fn utf8_error(&self) -> Utf8Error { 1955 self.error 1956 } 1957 } 1958 1959 #[stable(feature = "rust1", since = "1.0.0")] 1960 impl fmt::Display for FromUtf8Error { fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result1961 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 1962 fmt::Display::fmt(&self.error, f) 1963 } 1964 } 1965 1966 #[stable(feature = "rust1", since = "1.0.0")] 1967 impl fmt::Display for FromUtf16Error { fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result1968 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 1969 fmt::Display::fmt("invalid utf-16: lone surrogate found", f) 1970 } 1971 } 1972 1973 #[stable(feature = "rust1", since = "1.0.0")] 1974 impl Error for FromUtf8Error { 1975 #[allow(deprecated)] description(&self) -> &str1976 fn description(&self) -> &str { 1977 "invalid utf-8" 1978 } 1979 } 1980 1981 #[stable(feature = "rust1", since = "1.0.0")] 1982 impl Error for FromUtf16Error { 1983 #[allow(deprecated)] description(&self) -> &str1984 fn description(&self) -> &str { 1985 "invalid utf-16" 1986 } 1987 } 1988 1989 #[cfg(not(no_global_oom_handling))] 1990 #[stable(feature = "rust1", since = "1.0.0")] 1991 impl Clone for String { clone(&self) -> Self1992 fn clone(&self) -> Self { 1993 String { vec: self.vec.clone() } 1994 } 1995 clone_from(&mut self, source: &Self)1996 fn clone_from(&mut self, source: &Self) { 1997 self.vec.clone_from(&source.vec); 1998 } 1999 } 2000 2001 #[cfg(not(no_global_oom_handling))] 2002 #[stable(feature = "rust1", since = "1.0.0")] 2003 impl FromIterator<char> for String { from_iter<I: IntoIterator<Item = char>>(iter: I) -> String2004 fn from_iter<I: IntoIterator<Item = char>>(iter: I) -> String { 2005 let mut buf = String::new(); 2006 buf.extend(iter); 2007 buf 2008 } 2009 } 2010 2011 #[cfg(not(no_global_oom_handling))] 2012 #[stable(feature = "string_from_iter_by_ref", since = "1.17.0")] 2013 impl<'a> FromIterator<&'a char> for String { from_iter<I: IntoIterator<Item = &'a char>>(iter: I) -> String2014 fn from_iter<I: IntoIterator<Item = &'a char>>(iter: I) -> String { 2015 let mut buf = String::new(); 2016 buf.extend(iter); 2017 buf 2018 } 2019 } 2020 2021 #[cfg(not(no_global_oom_handling))] 2022 #[stable(feature = "rust1", since = "1.0.0")] 2023 impl<'a> FromIterator<&'a str> for String { from_iter<I: IntoIterator<Item = &'a str>>(iter: I) -> String2024 fn from_iter<I: IntoIterator<Item = &'a str>>(iter: I) -> String { 2025 let mut buf = String::new(); 2026 buf.extend(iter); 2027 buf 2028 } 2029 } 2030 2031 #[cfg(not(no_global_oom_handling))] 2032 #[stable(feature = "extend_string", since = "1.4.0")] 2033 impl FromIterator<String> for String { from_iter<I: IntoIterator<Item = String>>(iter: I) -> String2034 fn from_iter<I: IntoIterator<Item = String>>(iter: I) -> String { 2035 let mut iterator = iter.into_iter(); 2036 2037 // Because we're iterating over `String`s, we can avoid at least 2038 // one allocation by getting the first string from the iterator 2039 // and appending to it all the subsequent strings. 2040 match iterator.next() { 2041 None => String::new(), 2042 Some(mut buf) => { 2043 buf.extend(iterator); 2044 buf 2045 } 2046 } 2047 } 2048 } 2049 2050 #[cfg(not(no_global_oom_handling))] 2051 #[stable(feature = "box_str2", since = "1.45.0")] 2052 impl FromIterator<Box<str>> for String { from_iter<I: IntoIterator<Item = Box<str>>>(iter: I) -> String2053 fn from_iter<I: IntoIterator<Item = Box<str>>>(iter: I) -> String { 2054 let mut buf = String::new(); 2055 buf.extend(iter); 2056 buf 2057 } 2058 } 2059 2060 #[cfg(not(no_global_oom_handling))] 2061 #[stable(feature = "herd_cows", since = "1.19.0")] 2062 impl<'a> FromIterator<Cow<'a, str>> for String { from_iter<I: IntoIterator<Item = Cow<'a, str>>>(iter: I) -> String2063 fn from_iter<I: IntoIterator<Item = Cow<'a, str>>>(iter: I) -> String { 2064 let mut iterator = iter.into_iter(); 2065 2066 // Because we're iterating over CoWs, we can (potentially) avoid at least 2067 // one allocation by getting the first item and appending to it all the 2068 // subsequent items. 2069 match iterator.next() { 2070 None => String::new(), 2071 Some(cow) => { 2072 let mut buf = cow.into_owned(); 2073 buf.extend(iterator); 2074 buf 2075 } 2076 } 2077 } 2078 } 2079 2080 #[cfg(not(no_global_oom_handling))] 2081 #[stable(feature = "rust1", since = "1.0.0")] 2082 impl Extend<char> for String { extend<I: IntoIterator<Item = char>>(&mut self, iter: I)2083 fn extend<I: IntoIterator<Item = char>>(&mut self, iter: I) { 2084 let iterator = iter.into_iter(); 2085 let (lower_bound, _) = iterator.size_hint(); 2086 self.reserve(lower_bound); 2087 iterator.for_each(move |c| self.push(c)); 2088 } 2089 2090 #[inline] extend_one(&mut self, c: char)2091 fn extend_one(&mut self, c: char) { 2092 self.push(c); 2093 } 2094 2095 #[inline] extend_reserve(&mut self, additional: usize)2096 fn extend_reserve(&mut self, additional: usize) { 2097 self.reserve(additional); 2098 } 2099 } 2100 2101 #[cfg(not(no_global_oom_handling))] 2102 #[stable(feature = "extend_ref", since = "1.2.0")] 2103 impl<'a> Extend<&'a char> for String { extend<I: IntoIterator<Item = &'a char>>(&mut self, iter: I)2104 fn extend<I: IntoIterator<Item = &'a char>>(&mut self, iter: I) { 2105 self.extend(iter.into_iter().cloned()); 2106 } 2107 2108 #[inline] extend_one(&mut self, &c: &'a char)2109 fn extend_one(&mut self, &c: &'a char) { 2110 self.push(c); 2111 } 2112 2113 #[inline] extend_reserve(&mut self, additional: usize)2114 fn extend_reserve(&mut self, additional: usize) { 2115 self.reserve(additional); 2116 } 2117 } 2118 2119 #[cfg(not(no_global_oom_handling))] 2120 #[stable(feature = "rust1", since = "1.0.0")] 2121 impl<'a> Extend<&'a str> for String { extend<I: IntoIterator<Item = &'a str>>(&mut self, iter: I)2122 fn extend<I: IntoIterator<Item = &'a str>>(&mut self, iter: I) { 2123 iter.into_iter().for_each(move |s| self.push_str(s)); 2124 } 2125 2126 #[inline] extend_one(&mut self, s: &'a str)2127 fn extend_one(&mut self, s: &'a str) { 2128 self.push_str(s); 2129 } 2130 } 2131 2132 #[cfg(not(no_global_oom_handling))] 2133 #[stable(feature = "box_str2", since = "1.45.0")] 2134 impl Extend<Box<str>> for String { extend<I: IntoIterator<Item = Box<str>>>(&mut self, iter: I)2135 fn extend<I: IntoIterator<Item = Box<str>>>(&mut self, iter: I) { 2136 iter.into_iter().for_each(move |s| self.push_str(&s)); 2137 } 2138 } 2139 2140 #[cfg(not(no_global_oom_handling))] 2141 #[stable(feature = "extend_string", since = "1.4.0")] 2142 impl Extend<String> for String { extend<I: IntoIterator<Item = String>>(&mut self, iter: I)2143 fn extend<I: IntoIterator<Item = String>>(&mut self, iter: I) { 2144 iter.into_iter().for_each(move |s| self.push_str(&s)); 2145 } 2146 2147 #[inline] extend_one(&mut self, s: String)2148 fn extend_one(&mut self, s: String) { 2149 self.push_str(&s); 2150 } 2151 } 2152 2153 #[cfg(not(no_global_oom_handling))] 2154 #[stable(feature = "herd_cows", since = "1.19.0")] 2155 impl<'a> Extend<Cow<'a, str>> for String { extend<I: IntoIterator<Item = Cow<'a, str>>>(&mut self, iter: I)2156 fn extend<I: IntoIterator<Item = Cow<'a, str>>>(&mut self, iter: I) { 2157 iter.into_iter().for_each(move |s| self.push_str(&s)); 2158 } 2159 2160 #[inline] extend_one(&mut self, s: Cow<'a, str>)2161 fn extend_one(&mut self, s: Cow<'a, str>) { 2162 self.push_str(&s); 2163 } 2164 } 2165 2166 /// A convenience impl that delegates to the impl for `&str`. 2167 /// 2168 /// # Examples 2169 /// 2170 /// ``` 2171 /// assert_eq!(String::from("Hello world").find("world"), Some(6)); 2172 /// ``` 2173 #[unstable( 2174 feature = "pattern", 2175 reason = "API not fully fleshed out and ready to be stabilized", 2176 issue = "27721" 2177 )] 2178 impl<'a, 'b> Pattern<'a> for &'b String { 2179 type Searcher = <&'b str as Pattern<'a>>::Searcher; 2180 into_searcher(self, haystack: &'a str) -> <&'b str as Pattern<'a>>::Searcher2181 fn into_searcher(self, haystack: &'a str) -> <&'b str as Pattern<'a>>::Searcher { 2182 self[..].into_searcher(haystack) 2183 } 2184 2185 #[inline] is_contained_in(self, haystack: &'a str) -> bool2186 fn is_contained_in(self, haystack: &'a str) -> bool { 2187 self[..].is_contained_in(haystack) 2188 } 2189 2190 #[inline] is_prefix_of(self, haystack: &'a str) -> bool2191 fn is_prefix_of(self, haystack: &'a str) -> bool { 2192 self[..].is_prefix_of(haystack) 2193 } 2194 2195 #[inline] strip_prefix_of(self, haystack: &'a str) -> Option<&'a str>2196 fn strip_prefix_of(self, haystack: &'a str) -> Option<&'a str> { 2197 self[..].strip_prefix_of(haystack) 2198 } 2199 2200 #[inline] is_suffix_of(self, haystack: &'a str) -> bool2201 fn is_suffix_of(self, haystack: &'a str) -> bool { 2202 self[..].is_suffix_of(haystack) 2203 } 2204 2205 #[inline] strip_suffix_of(self, haystack: &'a str) -> Option<&'a str>2206 fn strip_suffix_of(self, haystack: &'a str) -> Option<&'a str> { 2207 self[..].strip_suffix_of(haystack) 2208 } 2209 } 2210 2211 macro_rules! impl_eq { 2212 ($lhs:ty, $rhs: ty) => { 2213 #[stable(feature = "rust1", since = "1.0.0")] 2214 #[allow(unused_lifetimes)] 2215 impl<'a, 'b> PartialEq<$rhs> for $lhs { 2216 #[inline] 2217 fn eq(&self, other: &$rhs) -> bool { 2218 PartialEq::eq(&self[..], &other[..]) 2219 } 2220 #[inline] 2221 fn ne(&self, other: &$rhs) -> bool { 2222 PartialEq::ne(&self[..], &other[..]) 2223 } 2224 } 2225 2226 #[stable(feature = "rust1", since = "1.0.0")] 2227 #[allow(unused_lifetimes)] 2228 impl<'a, 'b> PartialEq<$lhs> for $rhs { 2229 #[inline] 2230 fn eq(&self, other: &$lhs) -> bool { 2231 PartialEq::eq(&self[..], &other[..]) 2232 } 2233 #[inline] 2234 fn ne(&self, other: &$lhs) -> bool { 2235 PartialEq::ne(&self[..], &other[..]) 2236 } 2237 } 2238 }; 2239 } 2240 2241 impl_eq! { String, str } 2242 impl_eq! { String, &'a str } 2243 #[cfg(not(no_global_oom_handling))] 2244 impl_eq! { Cow<'a, str>, str } 2245 #[cfg(not(no_global_oom_handling))] 2246 impl_eq! { Cow<'a, str>, &'b str } 2247 #[cfg(not(no_global_oom_handling))] 2248 impl_eq! { Cow<'a, str>, String } 2249 2250 #[stable(feature = "rust1", since = "1.0.0")] 2251 impl Default for String { 2252 /// Creates an empty `String`. 2253 #[inline] default() -> String2254 fn default() -> String { 2255 String::new() 2256 } 2257 } 2258 2259 #[stable(feature = "rust1", since = "1.0.0")] 2260 impl fmt::Display for String { 2261 #[inline] fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result2262 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 2263 fmt::Display::fmt(&**self, f) 2264 } 2265 } 2266 2267 #[stable(feature = "rust1", since = "1.0.0")] 2268 impl fmt::Debug for String { 2269 #[inline] fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result2270 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 2271 fmt::Debug::fmt(&**self, f) 2272 } 2273 } 2274 2275 #[stable(feature = "rust1", since = "1.0.0")] 2276 impl hash::Hash for String { 2277 #[inline] hash<H: hash::Hasher>(&self, hasher: &mut H)2278 fn hash<H: hash::Hasher>(&self, hasher: &mut H) { 2279 (**self).hash(hasher) 2280 } 2281 } 2282 2283 /// Implements the `+` operator for concatenating two strings. 2284 /// 2285 /// This consumes the `String` on the left-hand side and re-uses its buffer (growing it if 2286 /// necessary). This is done to avoid allocating a new `String` and copying the entire contents on 2287 /// every operation, which would lead to *O*(*n*^2) running time when building an *n*-byte string by 2288 /// repeated concatenation. 2289 /// 2290 /// The string on the right-hand side is only borrowed; its contents are copied into the returned 2291 /// `String`. 2292 /// 2293 /// # Examples 2294 /// 2295 /// Concatenating two `String`s takes the first by value and borrows the second: 2296 /// 2297 /// ``` 2298 /// let a = String::from("hello"); 2299 /// let b = String::from(" world"); 2300 /// let c = a + &b; 2301 /// // `a` is moved and can no longer be used here. 2302 /// ``` 2303 /// 2304 /// If you want to keep using the first `String`, you can clone it and append to the clone instead: 2305 /// 2306 /// ``` 2307 /// let a = String::from("hello"); 2308 /// let b = String::from(" world"); 2309 /// let c = a.clone() + &b; 2310 /// // `a` is still valid here. 2311 /// ``` 2312 /// 2313 /// Concatenating `&str` slices can be done by converting the first to a `String`: 2314 /// 2315 /// ``` 2316 /// let a = "hello"; 2317 /// let b = " world"; 2318 /// let c = a.to_string() + b; 2319 /// ``` 2320 #[cfg(not(no_global_oom_handling))] 2321 #[stable(feature = "rust1", since = "1.0.0")] 2322 impl Add<&str> for String { 2323 type Output = String; 2324 2325 #[inline] add(mut self, other: &str) -> String2326 fn add(mut self, other: &str) -> String { 2327 self.push_str(other); 2328 self 2329 } 2330 } 2331 2332 /// Implements the `+=` operator for appending to a `String`. 2333 /// 2334 /// This has the same behavior as the [`push_str`][String::push_str] method. 2335 #[cfg(not(no_global_oom_handling))] 2336 #[stable(feature = "stringaddassign", since = "1.12.0")] 2337 impl AddAssign<&str> for String { 2338 #[inline] add_assign(&mut self, other: &str)2339 fn add_assign(&mut self, other: &str) { 2340 self.push_str(other); 2341 } 2342 } 2343 2344 #[stable(feature = "rust1", since = "1.0.0")] 2345 impl ops::Index<ops::Range<usize>> for String { 2346 type Output = str; 2347 2348 #[inline] index(&self, index: ops::Range<usize>) -> &str2349 fn index(&self, index: ops::Range<usize>) -> &str { 2350 &self[..][index] 2351 } 2352 } 2353 #[stable(feature = "rust1", since = "1.0.0")] 2354 impl ops::Index<ops::RangeTo<usize>> for String { 2355 type Output = str; 2356 2357 #[inline] index(&self, index: ops::RangeTo<usize>) -> &str2358 fn index(&self, index: ops::RangeTo<usize>) -> &str { 2359 &self[..][index] 2360 } 2361 } 2362 #[stable(feature = "rust1", since = "1.0.0")] 2363 impl ops::Index<ops::RangeFrom<usize>> for String { 2364 type Output = str; 2365 2366 #[inline] index(&self, index: ops::RangeFrom<usize>) -> &str2367 fn index(&self, index: ops::RangeFrom<usize>) -> &str { 2368 &self[..][index] 2369 } 2370 } 2371 #[stable(feature = "rust1", since = "1.0.0")] 2372 impl ops::Index<ops::RangeFull> for String { 2373 type Output = str; 2374 2375 #[inline] index(&self, _index: ops::RangeFull) -> &str2376 fn index(&self, _index: ops::RangeFull) -> &str { 2377 unsafe { str::from_utf8_unchecked(&self.vec) } 2378 } 2379 } 2380 #[stable(feature = "inclusive_range", since = "1.26.0")] 2381 impl ops::Index<ops::RangeInclusive<usize>> for String { 2382 type Output = str; 2383 2384 #[inline] index(&self, index: ops::RangeInclusive<usize>) -> &str2385 fn index(&self, index: ops::RangeInclusive<usize>) -> &str { 2386 Index::index(&**self, index) 2387 } 2388 } 2389 #[stable(feature = "inclusive_range", since = "1.26.0")] 2390 impl ops::Index<ops::RangeToInclusive<usize>> for String { 2391 type Output = str; 2392 2393 #[inline] index(&self, index: ops::RangeToInclusive<usize>) -> &str2394 fn index(&self, index: ops::RangeToInclusive<usize>) -> &str { 2395 Index::index(&**self, index) 2396 } 2397 } 2398 2399 #[stable(feature = "derefmut_for_string", since = "1.3.0")] 2400 impl ops::IndexMut<ops::Range<usize>> for String { 2401 #[inline] index_mut(&mut self, index: ops::Range<usize>) -> &mut str2402 fn index_mut(&mut self, index: ops::Range<usize>) -> &mut str { 2403 &mut self[..][index] 2404 } 2405 } 2406 #[stable(feature = "derefmut_for_string", since = "1.3.0")] 2407 impl ops::IndexMut<ops::RangeTo<usize>> for String { 2408 #[inline] index_mut(&mut self, index: ops::RangeTo<usize>) -> &mut str2409 fn index_mut(&mut self, index: ops::RangeTo<usize>) -> &mut str { 2410 &mut self[..][index] 2411 } 2412 } 2413 #[stable(feature = "derefmut_for_string", since = "1.3.0")] 2414 impl ops::IndexMut<ops::RangeFrom<usize>> for String { 2415 #[inline] index_mut(&mut self, index: ops::RangeFrom<usize>) -> &mut str2416 fn index_mut(&mut self, index: ops::RangeFrom<usize>) -> &mut str { 2417 &mut self[..][index] 2418 } 2419 } 2420 #[stable(feature = "derefmut_for_string", since = "1.3.0")] 2421 impl ops::IndexMut<ops::RangeFull> for String { 2422 #[inline] index_mut(&mut self, _index: ops::RangeFull) -> &mut str2423 fn index_mut(&mut self, _index: ops::RangeFull) -> &mut str { 2424 unsafe { str::from_utf8_unchecked_mut(&mut *self.vec) } 2425 } 2426 } 2427 #[stable(feature = "inclusive_range", since = "1.26.0")] 2428 impl ops::IndexMut<ops::RangeInclusive<usize>> for String { 2429 #[inline] index_mut(&mut self, index: ops::RangeInclusive<usize>) -> &mut str2430 fn index_mut(&mut self, index: ops::RangeInclusive<usize>) -> &mut str { 2431 IndexMut::index_mut(&mut **self, index) 2432 } 2433 } 2434 #[stable(feature = "inclusive_range", since = "1.26.0")] 2435 impl ops::IndexMut<ops::RangeToInclusive<usize>> for String { 2436 #[inline] index_mut(&mut self, index: ops::RangeToInclusive<usize>) -> &mut str2437 fn index_mut(&mut self, index: ops::RangeToInclusive<usize>) -> &mut str { 2438 IndexMut::index_mut(&mut **self, index) 2439 } 2440 } 2441 2442 #[stable(feature = "rust1", since = "1.0.0")] 2443 impl ops::Deref for String { 2444 type Target = str; 2445 2446 #[inline] deref(&self) -> &str2447 fn deref(&self) -> &str { 2448 unsafe { str::from_utf8_unchecked(&self.vec) } 2449 } 2450 } 2451 2452 #[stable(feature = "derefmut_for_string", since = "1.3.0")] 2453 impl ops::DerefMut for String { 2454 #[inline] deref_mut(&mut self) -> &mut str2455 fn deref_mut(&mut self) -> &mut str { 2456 unsafe { str::from_utf8_unchecked_mut(&mut *self.vec) } 2457 } 2458 } 2459 2460 /// A type alias for [`Infallible`]. 2461 /// 2462 /// This alias exists for backwards compatibility, and may be eventually deprecated. 2463 /// 2464 /// [`Infallible`]: core::convert::Infallible "convert::Infallible" 2465 #[stable(feature = "str_parse_error", since = "1.5.0")] 2466 pub type ParseError = core::convert::Infallible; 2467 2468 #[cfg(not(no_global_oom_handling))] 2469 #[stable(feature = "rust1", since = "1.0.0")] 2470 impl FromStr for String { 2471 type Err = core::convert::Infallible; 2472 #[inline] from_str(s: &str) -> Result<String, Self::Err>2473 fn from_str(s: &str) -> Result<String, Self::Err> { 2474 Ok(String::from(s)) 2475 } 2476 } 2477 2478 /// A trait for converting a value to a `String`. 2479 /// 2480 /// This trait is automatically implemented for any type which implements the 2481 /// [`Display`] trait. As such, `ToString` shouldn't be implemented directly: 2482 /// [`Display`] should be implemented instead, and you get the `ToString` 2483 /// implementation for free. 2484 /// 2485 /// [`Display`]: fmt::Display 2486 #[cfg_attr(not(test), rustc_diagnostic_item = "ToString")] 2487 #[stable(feature = "rust1", since = "1.0.0")] 2488 pub trait ToString { 2489 /// Converts the given value to a `String`. 2490 /// 2491 /// # Examples 2492 /// 2493 /// Basic usage: 2494 /// 2495 /// ``` 2496 /// let i = 5; 2497 /// let five = String::from("5"); 2498 /// 2499 /// assert_eq!(five, i.to_string()); 2500 /// ``` 2501 #[rustc_conversion_suggestion] 2502 #[stable(feature = "rust1", since = "1.0.0")] to_string(&self) -> String2503 fn to_string(&self) -> String; 2504 } 2505 2506 /// # Panics 2507 /// 2508 /// In this implementation, the `to_string` method panics 2509 /// if the `Display` implementation returns an error. 2510 /// This indicates an incorrect `Display` implementation 2511 /// since `fmt::Write for String` never returns an error itself. 2512 #[cfg(not(no_global_oom_handling))] 2513 #[stable(feature = "rust1", since = "1.0.0")] 2514 impl<T: fmt::Display + ?Sized> ToString for T { 2515 // A common guideline is to not inline generic functions. However, 2516 // removing `#[inline]` from this method causes non-negligible regressions. 2517 // See <https://github.com/rust-lang/rust/pull/74852>, the last attempt 2518 // to try to remove it. 2519 #[inline] to_string(&self) -> String2520 default fn to_string(&self) -> String { 2521 let mut buf = String::new(); 2522 let mut formatter = core::fmt::Formatter::new(&mut buf); 2523 // Bypass format_args!() to avoid write_str with zero-length strs 2524 fmt::Display::fmt(self, &mut formatter) 2525 .expect("a Display implementation returned an error unexpectedly"); 2526 buf 2527 } 2528 } 2529 2530 #[cfg(not(no_global_oom_handling))] 2531 #[unstable(feature = "ascii_char", issue = "110998")] 2532 impl ToString for core::ascii::Char { 2533 #[inline] to_string(&self) -> String2534 fn to_string(&self) -> String { 2535 self.as_str().to_owned() 2536 } 2537 } 2538 2539 #[cfg(not(no_global_oom_handling))] 2540 #[stable(feature = "char_to_string_specialization", since = "1.46.0")] 2541 impl ToString for char { 2542 #[inline] to_string(&self) -> String2543 fn to_string(&self) -> String { 2544 String::from(self.encode_utf8(&mut [0; 4])) 2545 } 2546 } 2547 2548 #[cfg(not(no_global_oom_handling))] 2549 #[stable(feature = "bool_to_string_specialization", since = "1.68.0")] 2550 impl ToString for bool { 2551 #[inline] to_string(&self) -> String2552 fn to_string(&self) -> String { 2553 String::from(if *self { "true" } else { "false" }) 2554 } 2555 } 2556 2557 #[cfg(not(no_global_oom_handling))] 2558 #[stable(feature = "u8_to_string_specialization", since = "1.54.0")] 2559 impl ToString for u8 { 2560 #[inline] to_string(&self) -> String2561 fn to_string(&self) -> String { 2562 let mut buf = String::with_capacity(3); 2563 let mut n = *self; 2564 if n >= 10 { 2565 if n >= 100 { 2566 buf.push((b'0' + n / 100) as char); 2567 n %= 100; 2568 } 2569 buf.push((b'0' + n / 10) as char); 2570 n %= 10; 2571 } 2572 buf.push((b'0' + n) as char); 2573 buf 2574 } 2575 } 2576 2577 #[cfg(not(no_global_oom_handling))] 2578 #[stable(feature = "i8_to_string_specialization", since = "1.54.0")] 2579 impl ToString for i8 { 2580 #[inline] to_string(&self) -> String2581 fn to_string(&self) -> String { 2582 let mut buf = String::with_capacity(4); 2583 if self.is_negative() { 2584 buf.push('-'); 2585 } 2586 let mut n = self.unsigned_abs(); 2587 if n >= 10 { 2588 if n >= 100 { 2589 buf.push('1'); 2590 n -= 100; 2591 } 2592 buf.push((b'0' + n / 10) as char); 2593 n %= 10; 2594 } 2595 buf.push((b'0' + n) as char); 2596 buf 2597 } 2598 } 2599 2600 #[cfg(not(no_global_oom_handling))] 2601 #[stable(feature = "str_to_string_specialization", since = "1.9.0")] 2602 impl ToString for str { 2603 #[inline] to_string(&self) -> String2604 fn to_string(&self) -> String { 2605 String::from(self) 2606 } 2607 } 2608 2609 #[cfg(not(no_global_oom_handling))] 2610 #[stable(feature = "cow_str_to_string_specialization", since = "1.17.0")] 2611 impl ToString for Cow<'_, str> { 2612 #[inline] to_string(&self) -> String2613 fn to_string(&self) -> String { 2614 self[..].to_owned() 2615 } 2616 } 2617 2618 #[cfg(not(no_global_oom_handling))] 2619 #[stable(feature = "string_to_string_specialization", since = "1.17.0")] 2620 impl ToString for String { 2621 #[inline] to_string(&self) -> String2622 fn to_string(&self) -> String { 2623 self.to_owned() 2624 } 2625 } 2626 2627 #[cfg(not(no_global_oom_handling))] 2628 #[stable(feature = "fmt_arguments_to_string_specialization", since = "1.71.0")] 2629 impl ToString for fmt::Arguments<'_> { 2630 #[inline] to_string(&self) -> String2631 fn to_string(&self) -> String { 2632 crate::fmt::format(*self) 2633 } 2634 } 2635 2636 #[stable(feature = "rust1", since = "1.0.0")] 2637 impl AsRef<str> for String { 2638 #[inline] as_ref(&self) -> &str2639 fn as_ref(&self) -> &str { 2640 self 2641 } 2642 } 2643 2644 #[stable(feature = "string_as_mut", since = "1.43.0")] 2645 impl AsMut<str> for String { 2646 #[inline] as_mut(&mut self) -> &mut str2647 fn as_mut(&mut self) -> &mut str { 2648 self 2649 } 2650 } 2651 2652 #[stable(feature = "rust1", since = "1.0.0")] 2653 impl AsRef<[u8]> for String { 2654 #[inline] as_ref(&self) -> &[u8]2655 fn as_ref(&self) -> &[u8] { 2656 self.as_bytes() 2657 } 2658 } 2659 2660 #[cfg(not(no_global_oom_handling))] 2661 #[stable(feature = "rust1", since = "1.0.0")] 2662 impl From<&str> for String { 2663 /// Converts a `&str` into a [`String`]. 2664 /// 2665 /// The result is allocated on the heap. 2666 #[inline] from(s: &str) -> String2667 fn from(s: &str) -> String { 2668 s.to_owned() 2669 } 2670 } 2671 2672 #[cfg(not(no_global_oom_handling))] 2673 #[stable(feature = "from_mut_str_for_string", since = "1.44.0")] 2674 impl From<&mut str> for String { 2675 /// Converts a `&mut str` into a [`String`]. 2676 /// 2677 /// The result is allocated on the heap. 2678 #[inline] from(s: &mut str) -> String2679 fn from(s: &mut str) -> String { 2680 s.to_owned() 2681 } 2682 } 2683 2684 #[cfg(not(no_global_oom_handling))] 2685 #[stable(feature = "from_ref_string", since = "1.35.0")] 2686 impl From<&String> for String { 2687 /// Converts a `&String` into a [`String`]. 2688 /// 2689 /// This clones `s` and returns the clone. 2690 #[inline] from(s: &String) -> String2691 fn from(s: &String) -> String { 2692 s.clone() 2693 } 2694 } 2695 2696 // note: test pulls in std, which causes errors here 2697 #[cfg(not(test))] 2698 #[stable(feature = "string_from_box", since = "1.18.0")] 2699 impl From<Box<str>> for String { 2700 /// Converts the given boxed `str` slice to a [`String`]. 2701 /// It is notable that the `str` slice is owned. 2702 /// 2703 /// # Examples 2704 /// 2705 /// Basic usage: 2706 /// 2707 /// ``` 2708 /// let s1: String = String::from("hello world"); 2709 /// let s2: Box<str> = s1.into_boxed_str(); 2710 /// let s3: String = String::from(s2); 2711 /// 2712 /// assert_eq!("hello world", s3) 2713 /// ``` from(s: Box<str>) -> String2714 fn from(s: Box<str>) -> String { 2715 s.into_string() 2716 } 2717 } 2718 2719 #[cfg(not(no_global_oom_handling))] 2720 #[stable(feature = "box_from_str", since = "1.20.0")] 2721 impl From<String> for Box<str> { 2722 /// Converts the given [`String`] to a boxed `str` slice that is owned. 2723 /// 2724 /// # Examples 2725 /// 2726 /// Basic usage: 2727 /// 2728 /// ``` 2729 /// let s1: String = String::from("hello world"); 2730 /// let s2: Box<str> = Box::from(s1); 2731 /// let s3: String = String::from(s2); 2732 /// 2733 /// assert_eq!("hello world", s3) 2734 /// ``` from(s: String) -> Box<str>2735 fn from(s: String) -> Box<str> { 2736 s.into_boxed_str() 2737 } 2738 } 2739 2740 #[cfg(not(no_global_oom_handling))] 2741 #[stable(feature = "string_from_cow_str", since = "1.14.0")] 2742 impl<'a> From<Cow<'a, str>> for String { 2743 /// Converts a clone-on-write string to an owned 2744 /// instance of [`String`]. 2745 /// 2746 /// This extracts the owned string, 2747 /// clones the string if it is not already owned. 2748 /// 2749 /// # Example 2750 /// 2751 /// ``` 2752 /// # use std::borrow::Cow; 2753 /// // If the string is not owned... 2754 /// let cow: Cow<'_, str> = Cow::Borrowed("eggplant"); 2755 /// // It will allocate on the heap and copy the string. 2756 /// let owned: String = String::from(cow); 2757 /// assert_eq!(&owned[..], "eggplant"); 2758 /// ``` from(s: Cow<'a, str>) -> String2759 fn from(s: Cow<'a, str>) -> String { 2760 s.into_owned() 2761 } 2762 } 2763 2764 #[cfg(not(no_global_oom_handling))] 2765 #[stable(feature = "rust1", since = "1.0.0")] 2766 impl<'a> From<&'a str> for Cow<'a, str> { 2767 /// Converts a string slice into a [`Borrowed`] variant. 2768 /// No heap allocation is performed, and the string 2769 /// is not copied. 2770 /// 2771 /// # Example 2772 /// 2773 /// ``` 2774 /// # use std::borrow::Cow; 2775 /// assert_eq!(Cow::from("eggplant"), Cow::Borrowed("eggplant")); 2776 /// ``` 2777 /// 2778 /// [`Borrowed`]: crate::borrow::Cow::Borrowed "borrow::Cow::Borrowed" 2779 #[inline] from(s: &'a str) -> Cow<'a, str>2780 fn from(s: &'a str) -> Cow<'a, str> { 2781 Cow::Borrowed(s) 2782 } 2783 } 2784 2785 #[cfg(not(no_global_oom_handling))] 2786 #[stable(feature = "rust1", since = "1.0.0")] 2787 impl<'a> From<String> for Cow<'a, str> { 2788 /// Converts a [`String`] into an [`Owned`] variant. 2789 /// No heap allocation is performed, and the string 2790 /// is not copied. 2791 /// 2792 /// # Example 2793 /// 2794 /// ``` 2795 /// # use std::borrow::Cow; 2796 /// let s = "eggplant".to_string(); 2797 /// let s2 = "eggplant".to_string(); 2798 /// assert_eq!(Cow::from(s), Cow::<'static, str>::Owned(s2)); 2799 /// ``` 2800 /// 2801 /// [`Owned`]: crate::borrow::Cow::Owned "borrow::Cow::Owned" 2802 #[inline] from(s: String) -> Cow<'a, str>2803 fn from(s: String) -> Cow<'a, str> { 2804 Cow::Owned(s) 2805 } 2806 } 2807 2808 #[cfg(not(no_global_oom_handling))] 2809 #[stable(feature = "cow_from_string_ref", since = "1.28.0")] 2810 impl<'a> From<&'a String> for Cow<'a, str> { 2811 /// Converts a [`String`] reference into a [`Borrowed`] variant. 2812 /// No heap allocation is performed, and the string 2813 /// is not copied. 2814 /// 2815 /// # Example 2816 /// 2817 /// ``` 2818 /// # use std::borrow::Cow; 2819 /// let s = "eggplant".to_string(); 2820 /// assert_eq!(Cow::from(&s), Cow::Borrowed("eggplant")); 2821 /// ``` 2822 /// 2823 /// [`Borrowed`]: crate::borrow::Cow::Borrowed "borrow::Cow::Borrowed" 2824 #[inline] from(s: &'a String) -> Cow<'a, str>2825 fn from(s: &'a String) -> Cow<'a, str> { 2826 Cow::Borrowed(s.as_str()) 2827 } 2828 } 2829 2830 #[cfg(not(no_global_oom_handling))] 2831 #[stable(feature = "cow_str_from_iter", since = "1.12.0")] 2832 impl<'a> FromIterator<char> for Cow<'a, str> { from_iter<I: IntoIterator<Item = char>>(it: I) -> Cow<'a, str>2833 fn from_iter<I: IntoIterator<Item = char>>(it: I) -> Cow<'a, str> { 2834 Cow::Owned(FromIterator::from_iter(it)) 2835 } 2836 } 2837 2838 #[cfg(not(no_global_oom_handling))] 2839 #[stable(feature = "cow_str_from_iter", since = "1.12.0")] 2840 impl<'a, 'b> FromIterator<&'b str> for Cow<'a, str> { from_iter<I: IntoIterator<Item = &'b str>>(it: I) -> Cow<'a, str>2841 fn from_iter<I: IntoIterator<Item = &'b str>>(it: I) -> Cow<'a, str> { 2842 Cow::Owned(FromIterator::from_iter(it)) 2843 } 2844 } 2845 2846 #[cfg(not(no_global_oom_handling))] 2847 #[stable(feature = "cow_str_from_iter", since = "1.12.0")] 2848 impl<'a> FromIterator<String> for Cow<'a, str> { from_iter<I: IntoIterator<Item = String>>(it: I) -> Cow<'a, str>2849 fn from_iter<I: IntoIterator<Item = String>>(it: I) -> Cow<'a, str> { 2850 Cow::Owned(FromIterator::from_iter(it)) 2851 } 2852 } 2853 2854 #[stable(feature = "from_string_for_vec_u8", since = "1.14.0")] 2855 impl From<String> for Vec<u8> { 2856 /// Converts the given [`String`] to a vector [`Vec`] that holds values of type [`u8`]. 2857 /// 2858 /// # Examples 2859 /// 2860 /// Basic usage: 2861 /// 2862 /// ``` 2863 /// let s1 = String::from("hello world"); 2864 /// let v1 = Vec::from(s1); 2865 /// 2866 /// for b in v1 { 2867 /// println!("{b}"); 2868 /// } 2869 /// ``` from(string: String) -> Vec<u8>2870 fn from(string: String) -> Vec<u8> { 2871 string.into_bytes() 2872 } 2873 } 2874 2875 #[cfg(not(no_global_oom_handling))] 2876 #[stable(feature = "rust1", since = "1.0.0")] 2877 impl fmt::Write for String { 2878 #[inline] write_str(&mut self, s: &str) -> fmt::Result2879 fn write_str(&mut self, s: &str) -> fmt::Result { 2880 self.push_str(s); 2881 Ok(()) 2882 } 2883 2884 #[inline] write_char(&mut self, c: char) -> fmt::Result2885 fn write_char(&mut self, c: char) -> fmt::Result { 2886 self.push(c); 2887 Ok(()) 2888 } 2889 } 2890 2891 /// A draining iterator for `String`. 2892 /// 2893 /// This struct is created by the [`drain`] method on [`String`]. See its 2894 /// documentation for more. 2895 /// 2896 /// [`drain`]: String::drain 2897 #[stable(feature = "drain", since = "1.6.0")] 2898 pub struct Drain<'a> { 2899 /// Will be used as &'a mut String in the destructor 2900 string: *mut String, 2901 /// Start of part to remove 2902 start: usize, 2903 /// End of part to remove 2904 end: usize, 2905 /// Current remaining range to remove 2906 iter: Chars<'a>, 2907 } 2908 2909 #[stable(feature = "collection_debug", since = "1.17.0")] 2910 impl fmt::Debug for Drain<'_> { fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result2911 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { 2912 f.debug_tuple("Drain").field(&self.as_str()).finish() 2913 } 2914 } 2915 2916 #[stable(feature = "drain", since = "1.6.0")] 2917 unsafe impl Sync for Drain<'_> {} 2918 #[stable(feature = "drain", since = "1.6.0")] 2919 unsafe impl Send for Drain<'_> {} 2920 2921 #[stable(feature = "drain", since = "1.6.0")] 2922 impl Drop for Drain<'_> { drop(&mut self)2923 fn drop(&mut self) { 2924 unsafe { 2925 // Use Vec::drain. "Reaffirm" the bounds checks to avoid 2926 // panic code being inserted again. 2927 let self_vec = (*self.string).as_mut_vec(); 2928 if self.start <= self.end && self.end <= self_vec.len() { 2929 self_vec.drain(self.start..self.end); 2930 } 2931 } 2932 } 2933 } 2934 2935 impl<'a> Drain<'a> { 2936 /// Returns the remaining (sub)string of this iterator as a slice. 2937 /// 2938 /// # Examples 2939 /// 2940 /// ``` 2941 /// let mut s = String::from("abc"); 2942 /// let mut drain = s.drain(..); 2943 /// assert_eq!(drain.as_str(), "abc"); 2944 /// let _ = drain.next().unwrap(); 2945 /// assert_eq!(drain.as_str(), "bc"); 2946 /// ``` 2947 #[must_use] 2948 #[stable(feature = "string_drain_as_str", since = "1.55.0")] as_str(&self) -> &str2949 pub fn as_str(&self) -> &str { 2950 self.iter.as_str() 2951 } 2952 } 2953 2954 #[stable(feature = "string_drain_as_str", since = "1.55.0")] 2955 impl<'a> AsRef<str> for Drain<'a> { as_ref(&self) -> &str2956 fn as_ref(&self) -> &str { 2957 self.as_str() 2958 } 2959 } 2960 2961 #[stable(feature = "string_drain_as_str", since = "1.55.0")] 2962 impl<'a> AsRef<[u8]> for Drain<'a> { as_ref(&self) -> &[u8]2963 fn as_ref(&self) -> &[u8] { 2964 self.as_str().as_bytes() 2965 } 2966 } 2967 2968 #[stable(feature = "drain", since = "1.6.0")] 2969 impl Iterator for Drain<'_> { 2970 type Item = char; 2971 2972 #[inline] next(&mut self) -> Option<char>2973 fn next(&mut self) -> Option<char> { 2974 self.iter.next() 2975 } 2976 size_hint(&self) -> (usize, Option<usize>)2977 fn size_hint(&self) -> (usize, Option<usize>) { 2978 self.iter.size_hint() 2979 } 2980 2981 #[inline] last(mut self) -> Option<char>2982 fn last(mut self) -> Option<char> { 2983 self.next_back() 2984 } 2985 } 2986 2987 #[stable(feature = "drain", since = "1.6.0")] 2988 impl DoubleEndedIterator for Drain<'_> { 2989 #[inline] next_back(&mut self) -> Option<char>2990 fn next_back(&mut self) -> Option<char> { 2991 self.iter.next_back() 2992 } 2993 } 2994 2995 #[stable(feature = "fused", since = "1.26.0")] 2996 impl FusedIterator for Drain<'_> {} 2997 2998 #[cfg(not(no_global_oom_handling))] 2999 #[stable(feature = "from_char_for_string", since = "1.46.0")] 3000 impl From<char> for String { 3001 /// Allocates an owned [`String`] from a single character. 3002 /// 3003 /// # Example 3004 /// ```rust 3005 /// let c: char = 'a'; 3006 /// let s: String = String::from(c); 3007 /// assert_eq!("a", &s[..]); 3008 /// ``` 3009 #[inline] from(c: char) -> Self3010 fn from(c: char) -> Self { 3011 c.to_string() 3012 } 3013 } 3014