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