1 //! A UTF-8βencoded, growable string.
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.
9 //! There are multiple ways to create a new [`String`] from a string literal:
12 //! let s = "Hello".to_string();
14 //! let s = String::from("world");
15 //! let s: String = "also this".into();
18 //! You can create a new [`String`] from an existing one by concatenating with
22 //! let s = "Hello".to_string();
24 //! let message = s + " world!";
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.
31 //! let sparkle_heart = vec![240, 159, 146, 150];
33 //! // We know these bytes are valid, so we'll use `unwrap()`.
34 //! let sparkle_heart = String::from_utf8(sparkle_heart).unwrap();
36 //! assert_eq!("π", sparkle_heart);
38 //! let bytes = sparkle_heart.into_bytes();
40 //! assert_eq!(bytes, [240, 159, 146, 150]);
43 #![stable(feature = "rust1", since = "1.0.0")]
45 #[cfg(not(no_global_oom_handling))]
46 use core
::char::{decode_utf16, REPLACEMENT_CHARACTER}
;
47 use core
::error
::Error
;
50 use core
::iter
::FusedIterator
;
51 #[cfg(not(no_global_oom_handling))]
52 use core
::iter
::{from_fn, FromIterator}
;
53 #[cfg(not(no_global_oom_handling))]
55 #[cfg(not(no_global_oom_handling))]
56 use core
::ops
::AddAssign
;
57 #[cfg(not(no_global_oom_handling))]
58 use core
::ops
::Bound
::{Excluded, Included, Unbounded}
;
59 use core
::ops
::{self, Index, IndexMut, Range, RangeBounds}
;
62 use core
::str::pattern
::Pattern
;
63 #[cfg(not(no_global_oom_handling))]
64 use core
::str::Utf8Chunks
;
66 #[cfg(not(no_global_oom_handling))]
67 use crate::borrow
::{Cow, ToOwned}
;
68 use crate::boxed
::Box
;
69 use crate::collections
::TryReserveError
;
70 use crate::str::{self, from_utf8_unchecked_mut, Chars, Utf8Error}
;
71 #[cfg(not(no_global_oom_handling))]
72 use crate::str::{from_boxed_utf8_unchecked, FromStr}
;
75 /// A UTF-8βencoded, growable string.
77 /// The `String` type is the most common string type that has ownership over the
78 /// contents of the string. It has a close relationship with its borrowed
79 /// counterpart, the primitive [`str`].
83 /// You can create a `String` from [a literal string][`&str`] with [`String::from`]:
85 /// [`String::from`]: From::from
88 /// let hello = String::from("Hello, world!");
91 /// You can append a [`char`] to a `String` with the [`push`] method, and
92 /// append a [`&str`] with the [`push_str`] method:
95 /// let mut hello = String::from("Hello, ");
98 /// hello.push_str("orld!");
101 /// [`push`]: String::push
102 /// [`push_str`]: String::push_str
104 /// If you have a vector of UTF-8 bytes, you can create a `String` from it with
105 /// the [`from_utf8`] method:
108 /// // some bytes, in a vector
109 /// let sparkle_heart = vec![240, 159, 146, 150];
111 /// // We know these bytes are valid, so we'll use `unwrap()`.
112 /// let sparkle_heart = String::from_utf8(sparkle_heart).unwrap();
114 /// assert_eq!("π", sparkle_heart);
117 /// [`from_utf8`]: String::from_utf8
121 /// `String`s are always valid UTF-8. If you need a non-UTF-8 string, consider
122 /// [`OsString`]. It is similar, but without the UTF-8 constraint. Because UTF-8
123 /// is a variable width encoding, `String`s are typically smaller than an array of
124 /// the same `chars`:
129 /// // `s` is ASCII which represents each `char` as one byte
131 /// assert_eq!(s.len(), 5);
133 /// // A `char` array with the same contents would be longer because
134 /// // every `char` is four bytes
135 /// let s = ['h', 'e', 'l', 'l', 'o'];
136 /// let size: usize = s.into_iter().map(|c| mem::size_of_val(&c)).sum();
137 /// assert_eq!(size, 20);
139 /// // However, for non-ASCII strings, the difference will be smaller
140 /// // and sometimes they are the same
141 /// let s = "πππππ";
142 /// assert_eq!(s.len(), 20);
144 /// let s = ['π', 'π', 'π', 'π', 'π'];
145 /// let size: usize = s.into_iter().map(|c| mem::size_of_val(&c)).sum();
146 /// assert_eq!(size, 20);
149 /// This raises interesting questions as to how `s[i]` should work.
150 /// What should `i` be here? Several options include byte indices and
151 /// `char` indices but, because of UTF-8 encoding, only byte indices
152 /// would provide constant time indexing. Getting the `i`th `char`, for
153 /// example, is available using [`chars`]:
157 /// let third_character = s.chars().nth(2);
158 /// assert_eq!(third_character, Some('l'));
160 /// let s = "πππππ";
161 /// let third_character = s.chars().nth(2);
162 /// assert_eq!(third_character, Some('π'));
165 /// Next, what should `s[i]` return? Because indexing returns a reference
166 /// to underlying data it could be `&u8`, `&[u8]`, or something else similar.
167 /// Since we're only providing one index, `&u8` makes the most sense but that
168 /// might not be what the user expects and can be explicitly achieved with
172 /// // The first byte is 104 - the byte value of `'h'`
174 /// assert_eq!(s.as_bytes()[0], 104);
176 /// assert_eq!(s.as_bytes()[0], b'h');
178 /// // The first byte is 240 which isn't obviously useful
179 /// let s = "πππππ";
180 /// assert_eq!(s.as_bytes()[0], 240);
183 /// Due to these ambiguities/restrictions, indexing with a `usize` is simply
186 /// ```compile_fail,E0277
189 /// // The following will not compile!
190 /// println!("The first letter of s is {}", s[0]);
193 /// It is more clear, however, how `&s[i..j]` should work (that is,
194 /// indexing with a range). It should accept byte indices (to be constant-time)
195 /// and return a `&str` which is UTF-8 encoded. This is also called "string slicing".
196 /// Note this will panic if the byte indices provided are not character
197 /// boundaries - see [`is_char_boundary`] for more details. See the implementations
198 /// for [`SliceIndex<str>`] for more details on string slicing. For a non-panicking
199 /// version of string slicing, see [`get`].
201 /// [`OsString`]: ../../std/ffi/struct.OsString.html "ffi::OsString"
202 /// [`SliceIndex<str>`]: core::slice::SliceIndex
203 /// [`as_bytes()`]: str::as_bytes
204 /// [`get`]: str::get
205 /// [`is_char_boundary`]: str::is_char_boundary
207 /// The [`bytes`] and [`chars`] methods return iterators over the bytes and
208 /// codepoints of the string, respectively. To iterate over codepoints along
209 /// with byte indices, use [`char_indices`].
211 /// [`bytes`]: str::bytes
212 /// [`chars`]: str::chars
213 /// [`char_indices`]: str::char_indices
217 /// `String` implements <code>[Deref]<Target = [str]></code>, and so inherits all of [`str`]'s
218 /// methods. In addition, this means that you can pass a `String` to a
219 /// function which takes a [`&str`] by using an ampersand (`&`):
222 /// fn takes_str(s: &str) { }
224 /// let s = String::from("Hello");
229 /// This will create a [`&str`] from the `String` and pass it in. This
230 /// conversion is very inexpensive, and so generally, functions will accept
231 /// [`&str`]s as arguments unless they need a `String` for some specific
234 /// In certain cases Rust doesn't have enough information to make this
235 /// conversion, known as [`Deref`] coercion. In the following example a string
236 /// slice [`&'a str`][`&str`] implements the trait `TraitExample`, and the function
237 /// `example_func` takes anything that implements the trait. In this case Rust
238 /// would need to make two implicit conversions, which Rust doesn't have the
239 /// means to do. For that reason, the following example will not compile.
241 /// ```compile_fail,E0277
242 /// trait TraitExample {}
244 /// impl<'a> TraitExample for &'a str {}
246 /// fn example_func<A: TraitExample>(example_arg: A) {}
248 /// let example_string = String::from("example_string");
249 /// example_func(&example_string);
252 /// There are two options that would work instead. The first would be to
253 /// change the line `example_func(&example_string);` to
254 /// `example_func(example_string.as_str());`, using the method [`as_str()`]
255 /// to explicitly extract the string slice containing the string. The second
256 /// way changes `example_func(&example_string);` to
257 /// `example_func(&*example_string);`. In this case we are dereferencing a
258 /// `String` to a [`str`], then referencing the [`str`] back to
259 /// [`&str`]. The second way is more idiomatic, however both work to do the
260 /// conversion explicitly rather than relying on the implicit conversion.
264 /// A `String` is made up of three components: a pointer to some bytes, a
265 /// length, and a capacity. The pointer points to an internal buffer `String`
266 /// uses to store its data. The length is the number of bytes currently stored
267 /// in the buffer, and the capacity is the size of the buffer in bytes. As such,
268 /// the length will always be less than or equal to the capacity.
270 /// This buffer is always stored on the heap.
272 /// You can look at these with the [`as_ptr`], [`len`], and [`capacity`]
278 /// let story = String::from("Once upon a time...");
280 // FIXME Update this when vec_into_raw_parts is stabilized
281 /// // Prevent automatically dropping the String's data
282 /// let mut story = mem::ManuallyDrop::new(story);
284 /// let ptr = story.as_mut_ptr();
285 /// let len = story.len();
286 /// let capacity = story.capacity();
288 /// // story has nineteen bytes
289 /// assert_eq!(19, len);
291 /// // We can re-build a String out of ptr, len, and capacity. This is all
292 /// // unsafe because we are responsible for making sure the components are
294 /// let s = unsafe { String::from_raw_parts(ptr, len, capacity) } ;
296 /// assert_eq!(String::from("Once upon a time..."), s);
299 /// [`as_ptr`]: str::as_ptr
300 /// [`len`]: String::len
301 /// [`capacity`]: String::capacity
303 /// If a `String` has enough capacity, adding elements to it will not
304 /// re-allocate. For example, consider this program:
307 /// let mut s = String::new();
309 /// println!("{}", s.capacity());
312 /// s.push_str("hello");
313 /// println!("{}", s.capacity());
317 /// This will output the following:
328 /// At first, we have no memory allocated at all, but as we append to the
329 /// string, it increases its capacity appropriately. If we instead use the
330 /// [`with_capacity`] method to allocate the correct capacity initially:
333 /// let mut s = String::with_capacity(25);
335 /// println!("{}", s.capacity());
338 /// s.push_str("hello");
339 /// println!("{}", s.capacity());
343 /// [`with_capacity`]: String::with_capacity
345 /// We end up with a different output:
356 /// Here, there's no need to allocate more memory inside the loop.
358 /// [str]: prim@str "str"
359 /// [`str`]: prim@str "str"
360 /// [`&str`]: prim@str "&str"
361 /// [Deref]: core::ops::Deref "ops::Deref"
362 /// [`Deref`]: core::ops::Deref "ops::Deref"
363 /// [`as_str()`]: String::as_str
364 #[derive(PartialOrd, Eq, Ord)]
365 #[stable(feature = "rust1", since = "1.0.0")]
366 #[cfg_attr(all(not(bootstrap), not(test)), lang = "String")]
371 /// A possible error value when converting a `String` from a UTF-8 byte vector.
373 /// This type is the error type for the [`from_utf8`] method on [`String`]. It
374 /// is designed in such a way to carefully avoid reallocations: the
375 /// [`into_bytes`] method will give back the byte vector that was used in the
376 /// conversion attempt.
378 /// [`from_utf8`]: String::from_utf8
379 /// [`into_bytes`]: FromUtf8Error::into_bytes
381 /// The [`Utf8Error`] type provided by [`std::str`] represents an error that may
382 /// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's
383 /// an analogue to `FromUtf8Error`, and you can get one from a `FromUtf8Error`
384 /// through the [`utf8_error`] method.
386 /// [`Utf8Error`]: str::Utf8Error "std::str::Utf8Error"
387 /// [`std::str`]: core::str "std::str"
388 /// [`&str`]: prim@str "&str"
389 /// [`utf8_error`]: FromUtf8Error::utf8_error
396 /// // some invalid bytes, in a vector
397 /// let bytes = vec![0, 159];
399 /// let value = String::from_utf8(bytes);
401 /// assert!(value.is_err());
402 /// assert_eq!(vec![0, 159], value.unwrap_err().into_bytes());
404 #[stable(feature = "rust1", since = "1.0.0")]
405 #[cfg_attr(not(no_global_oom_handling), derive(Clone))]
406 #[derive(Debug, PartialEq, Eq)]
407 pub struct FromUtf8Error
{
412 /// A possible error value when converting a `String` from a UTF-16 byte slice.
414 /// This type is the error type for the [`from_utf16`] method on [`String`].
416 /// [`from_utf16`]: String::from_utf16
422 /// // πmu<invalid>ic
423 /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075,
424 /// 0xD800, 0x0069, 0x0063];
426 /// assert!(String::from_utf16(v).is_err());
428 #[stable(feature = "rust1", since = "1.0.0")]
430 pub struct FromUtf16Error(());
433 /// Creates a new empty `String`.
435 /// Given that the `String` is empty, this will not allocate any initial
436 /// buffer. While that means that this initial operation is very
437 /// inexpensive, it may cause excessive allocation later when you add
438 /// data. If you have an idea of how much data the `String` will hold,
439 /// consider the [`with_capacity`] method to prevent excessive
442 /// [`with_capacity`]: String::with_capacity
449 /// let s = String::new();
452 #[rustc_const_stable(feature = "const_string_new", since = "1.39.0")]
453 #[stable(feature = "rust1", since = "1.0.0")]
455 pub const fn new() -> String
{
456 String { vec: Vec::new() }
459 /// Creates a new empty `String` with at least the specified capacity.
461 /// `String`s have an internal buffer to hold their data. The capacity is
462 /// the length of that buffer, and can be queried with the [`capacity`]
463 /// method. This method creates an empty `String`, but one with an initial
464 /// buffer that can hold at least `capacity` bytes. This is useful when you
465 /// may be appending a bunch of data to the `String`, reducing the number of
466 /// reallocations it needs to do.
468 /// [`capacity`]: String::capacity
470 /// If the given capacity is `0`, no allocation will occur, and this method
471 /// is identical to the [`new`] method.
473 /// [`new`]: String::new
480 /// let mut s = String::with_capacity(10);
482 /// // The String contains no chars, even though it has capacity for more
483 /// assert_eq!(s.len(), 0);
485 /// // These are all done without reallocating...
486 /// let cap = s.capacity();
491 /// assert_eq!(s.capacity(), cap);
493 /// // ...but this may make the string reallocate
496 #[cfg(not(no_global_oom_handling))]
498 #[stable(feature = "rust1", since = "1.0.0")]
500 pub fn with_capacity(capacity
: usize) -> String
{
501 String { vec: Vec::with_capacity(capacity) }
504 // HACK(japaric): with cfg(test) the inherent `[T]::to_vec` method, which is
505 // required for this method definition, is not available. Since we don't
506 // require this method for testing purposes, I'll just stub it
507 // NB see the slice::hack module in slice.rs for more information
510 pub fn from_str(_
: &str) -> String
{
511 panic
!("not available with cfg(test)");
514 /// Converts a vector of bytes to a `String`.
516 /// A string ([`String`]) is made of bytes ([`u8`]), and a vector of bytes
517 /// ([`Vec<u8>`]) is made of bytes, so this function converts between the
518 /// two. Not all byte slices are valid `String`s, however: `String`
519 /// requires that it is valid UTF-8. `from_utf8()` checks to ensure that
520 /// the bytes are valid UTF-8, and then does the conversion.
522 /// If you are sure that the byte slice is valid UTF-8, and you don't want
523 /// to incur the overhead of the validity check, there is an unsafe version
524 /// of this function, [`from_utf8_unchecked`], which has the same behavior
525 /// but skips the check.
527 /// This method will take care to not copy the vector, for efficiency's
530 /// If you need a [`&str`] instead of a `String`, consider
531 /// [`str::from_utf8`].
533 /// The inverse of this method is [`into_bytes`].
537 /// Returns [`Err`] if the slice is not UTF-8 with a description as to why the
538 /// provided bytes are not UTF-8. The vector you moved in is also included.
545 /// // some bytes, in a vector
546 /// let sparkle_heart = vec![240, 159, 146, 150];
548 /// // We know these bytes are valid, so we'll use `unwrap()`.
549 /// let sparkle_heart = String::from_utf8(sparkle_heart).unwrap();
551 /// assert_eq!("π", sparkle_heart);
557 /// // some invalid bytes, in a vector
558 /// let sparkle_heart = vec![0, 159, 146, 150];
560 /// assert!(String::from_utf8(sparkle_heart).is_err());
563 /// See the docs for [`FromUtf8Error`] for more details on what you can do
566 /// [`from_utf8_unchecked`]: String::from_utf8_unchecked
567 /// [`Vec<u8>`]: crate::vec::Vec "Vec"
568 /// [`&str`]: prim@str "&str"
569 /// [`into_bytes`]: String::into_bytes
571 #[stable(feature = "rust1", since = "1.0.0")]
572 pub fn from_utf8(vec
: Vec
<u8>) -> Result
<String
, FromUtf8Error
> {
573 match str::from_utf8(&vec
) {
574 Ok(..) => Ok(String { vec }
),
575 Err(e
) => Err(FromUtf8Error { bytes: vec, error: e }
),
579 /// Converts a slice of bytes to a string, including invalid characters.
581 /// Strings are made of bytes ([`u8`]), and a slice of bytes
582 /// ([`&[u8]`][byteslice]) is made of bytes, so this function converts
583 /// between the two. Not all byte slices are valid strings, however: strings
584 /// are required to be valid UTF-8. During this conversion,
585 /// `from_utf8_lossy()` will replace any invalid UTF-8 sequences with
586 /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD], which looks like this: οΏ½
588 /// [byteslice]: prim@slice
589 /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER
591 /// If you are sure that the byte slice is valid UTF-8, and you don't want
592 /// to incur the overhead of the conversion, there is an unsafe version
593 /// of this function, [`from_utf8_unchecked`], which has the same behavior
594 /// but skips the checks.
596 /// [`from_utf8_unchecked`]: String::from_utf8_unchecked
598 /// This function returns a [`Cow<'a, str>`]. If our byte slice is invalid
599 /// UTF-8, then we need to insert the replacement characters, which will
600 /// change the size of the string, and hence, require a `String`. But if
601 /// it's already valid UTF-8, we don't need a new allocation. This return
602 /// type allows us to handle both cases.
604 /// [`Cow<'a, str>`]: crate::borrow::Cow "borrow::Cow"
611 /// // some bytes, in a vector
612 /// let sparkle_heart = vec![240, 159, 146, 150];
614 /// let sparkle_heart = String::from_utf8_lossy(&sparkle_heart);
616 /// assert_eq!("π", sparkle_heart);
622 /// // some invalid bytes
623 /// let input = b"Hello \xF0\x90\x80World";
624 /// let output = String::from_utf8_lossy(input);
626 /// assert_eq!("Hello οΏ½World", output);
629 #[cfg(not(no_global_oom_handling))]
630 #[stable(feature = "rust1", since = "1.0.0")]
631 pub fn from_utf8_lossy(v
: &[u8]) -> Cow
<'_
, str> {
632 let mut iter
= Utf8Chunks
::new(v
);
634 let first_valid
= if let Some(chunk
) = iter
.next() {
635 let valid
= chunk
.valid();
636 if chunk
.invalid().is_empty() {
637 debug_assert_eq
!(valid
.len(), v
.len());
638 return Cow
::Borrowed(valid
);
642 return Cow
::Borrowed("");
645 const REPLACEMENT
: &str = "\u{FFFD}";
647 let mut res
= String
::with_capacity(v
.len());
648 res
.push_str(first_valid
);
649 res
.push_str(REPLACEMENT
);
652 res
.push_str(chunk
.valid());
653 if !chunk
.invalid().is_empty() {
654 res
.push_str(REPLACEMENT
);
661 /// Decode a UTF-16βencoded vector `v` into a `String`, returning [`Err`]
662 /// if `v` contains any invalid data.
670 /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075,
671 /// 0x0073, 0x0069, 0x0063];
672 /// assert_eq!(String::from("πmusic"),
673 /// String::from_utf16(v).unwrap());
675 /// // πmu<invalid>ic
676 /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075,
677 /// 0xD800, 0x0069, 0x0063];
678 /// assert!(String::from_utf16(v).is_err());
680 #[cfg(not(no_global_oom_handling))]
681 #[stable(feature = "rust1", since = "1.0.0")]
682 pub fn from_utf16(v
: &[u16]) -> Result
<String
, FromUtf16Error
> {
683 // This isn't done via collect::<Result<_, _>>() for performance reasons.
684 // FIXME: the function can be simplified again when #48994 is closed.
685 let mut ret
= String
::with_capacity(v
.len());
686 for c
in decode_utf16(v
.iter().cloned()) {
690 return Err(FromUtf16Error(()));
696 /// Decode a UTF-16βencoded slice `v` into a `String`, replacing
697 /// invalid data with [the replacement character (`U+FFFD`)][U+FFFD].
699 /// Unlike [`from_utf8_lossy`] which returns a [`Cow<'a, str>`],
700 /// `from_utf16_lossy` returns a `String` since the UTF-16 to UTF-8
701 /// conversion requires a memory allocation.
703 /// [`from_utf8_lossy`]: String::from_utf8_lossy
704 /// [`Cow<'a, str>`]: crate::borrow::Cow "borrow::Cow"
705 /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER
712 /// // πmus<invalid>ic<invalid>
713 /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075,
714 /// 0x0073, 0xDD1E, 0x0069, 0x0063,
717 /// assert_eq!(String::from("πmus\u{FFFD}ic\u{FFFD}"),
718 /// String::from_utf16_lossy(v));
720 #[cfg(not(no_global_oom_handling))]
723 #[stable(feature = "rust1", since = "1.0.0")]
724 pub fn from_utf16_lossy(v
: &[u16]) -> String
{
725 decode_utf16(v
.iter().cloned()).map(|r
| r
.unwrap_or(REPLACEMENT_CHARACTER
)).collect()
728 /// Decomposes a `String` into its raw components.
730 /// Returns the raw pointer to the underlying data, the length of
731 /// the string (in bytes), and the allocated capacity of the data
732 /// (in bytes). These are the same arguments in the same order as
733 /// the arguments to [`from_raw_parts`].
735 /// After calling this function, the caller is responsible for the
736 /// memory previously managed by the `String`. The only way to do
737 /// this is to convert the raw pointer, length, and capacity back
738 /// into a `String` with the [`from_raw_parts`] function, allowing
739 /// the destructor to perform the cleanup.
741 /// [`from_raw_parts`]: String::from_raw_parts
746 /// #![feature(vec_into_raw_parts)]
747 /// let s = String::from("hello");
749 /// let (ptr, len, cap) = s.into_raw_parts();
751 /// let rebuilt = unsafe { String::from_raw_parts(ptr, len, cap) };
752 /// assert_eq!(rebuilt, "hello");
754 #[must_use = "`self` will be dropped if the result is not used"]
755 #[unstable(feature = "vec_into_raw_parts", reason = "new API", issue = "65816")]
756 pub fn into_raw_parts(self) -> (*mut u8, usize, usize) {
757 self.vec
.into_raw_parts()
760 /// Creates a new `String` from a length, capacity, and pointer.
764 /// This is highly unsafe, due to the number of invariants that aren't
767 /// * The memory at `buf` needs to have been previously allocated by the
768 /// same allocator the standard library uses, with a required alignment of exactly 1.
769 /// * `length` needs to be less than or equal to `capacity`.
770 /// * `capacity` needs to be the correct value.
771 /// * The first `length` bytes at `buf` need to be valid UTF-8.
773 /// Violating these may cause problems like corrupting the allocator's
774 /// internal data structures. For example, it is normally **not** safe to
775 /// build a `String` from a pointer to a C `char` array containing UTF-8
776 /// _unless_ you are certain that array was originally allocated by the
777 /// Rust standard library's allocator.
779 /// The ownership of `buf` is effectively transferred to the
780 /// `String` which may then deallocate, reallocate or change the
781 /// contents of memory pointed to by the pointer at will. Ensure
782 /// that nothing else uses the pointer after calling this
793 /// let s = String::from("hello");
795 // FIXME Update this when vec_into_raw_parts is stabilized
796 /// // Prevent automatically dropping the String's data
797 /// let mut s = mem::ManuallyDrop::new(s);
799 /// let ptr = s.as_mut_ptr();
800 /// let len = s.len();
801 /// let capacity = s.capacity();
803 /// let s = String::from_raw_parts(ptr, len, capacity);
805 /// assert_eq!(String::from("hello"), s);
809 #[stable(feature = "rust1", since = "1.0.0")]
810 pub unsafe fn from_raw_parts(buf
: *mut u8, length
: usize, capacity
: usize) -> String
{
811 unsafe { String { vec: Vec::from_raw_parts(buf, length, capacity) }
}
814 /// Converts a vector of bytes to a `String` without checking that the
815 /// string contains valid UTF-8.
817 /// See the safe version, [`from_utf8`], for more details.
819 /// [`from_utf8`]: String::from_utf8
823 /// This function is unsafe because it does not check that the bytes passed
824 /// to it are valid UTF-8. If this constraint is violated, it may cause
825 /// memory unsafety issues with future users of the `String`, as the rest of
826 /// the standard library assumes that `String`s are valid UTF-8.
833 /// // some bytes, in a vector
834 /// let sparkle_heart = vec![240, 159, 146, 150];
836 /// let sparkle_heart = unsafe {
837 /// String::from_utf8_unchecked(sparkle_heart)
840 /// assert_eq!("π", sparkle_heart);
844 #[stable(feature = "rust1", since = "1.0.0")]
845 pub unsafe fn from_utf8_unchecked(bytes
: Vec
<u8>) -> String
{
846 String { vec: bytes }
849 /// Converts a `String` into a byte vector.
851 /// This consumes the `String`, so we do not need to copy its contents.
858 /// let s = String::from("hello");
859 /// let bytes = s.into_bytes();
861 /// assert_eq!(&[104, 101, 108, 108, 111][..], &bytes[..]);
864 #[must_use = "`self` will be dropped if the result is not used"]
865 #[stable(feature = "rust1", since = "1.0.0")]
866 pub fn into_bytes(self) -> Vec
<u8> {
870 /// Extracts a string slice containing the entire `String`.
877 /// let s = String::from("foo");
879 /// assert_eq!("foo", s.as_str());
883 #[stable(feature = "string_as_str", since = "1.7.0")]
884 pub fn as_str(&self) -> &str {
888 /// Converts a `String` into a mutable string slice.
895 /// let mut s = String::from("foobar");
896 /// let s_mut_str = s.as_mut_str();
898 /// s_mut_str.make_ascii_uppercase();
900 /// assert_eq!("FOOBAR", s_mut_str);
904 #[stable(feature = "string_as_str", since = "1.7.0")]
905 pub fn as_mut_str(&mut self) -> &mut str {
909 /// Appends a given string slice onto the end of this `String`.
916 /// let mut s = String::from("foo");
918 /// s.push_str("bar");
920 /// assert_eq!("foobar", s);
922 #[cfg(not(no_global_oom_handling))]
924 #[stable(feature = "rust1", since = "1.0.0")]
925 pub fn push_str(&mut self, string
: &str) {
926 self.vec
.extend_from_slice(string
.as_bytes())
929 /// Copies elements from `src` range to the end of the string.
933 /// Panics if the starting point or end point do not lie on a [`char`]
934 /// boundary, or if they're out of bounds.
939 /// #![feature(string_extend_from_within)]
940 /// let mut string = String::from("abcde");
942 /// string.extend_from_within(2..);
943 /// assert_eq!(string, "abcdecde");
945 /// string.extend_from_within(..2);
946 /// assert_eq!(string, "abcdecdeab");
948 /// string.extend_from_within(4..8);
949 /// assert_eq!(string, "abcdecdeabecde");
951 #[cfg(not(no_global_oom_handling))]
952 #[unstable(feature = "string_extend_from_within", issue = "103806")]
953 pub fn extend_from_within
<R
>(&mut self, src
: R
)
955 R
: RangeBounds
<usize>,
957 let src @ Range { start, end }
= slice
::range(src
, ..self.len());
959 assert
!(self.is_char_boundary(start
));
960 assert
!(self.is_char_boundary(end
));
962 self.vec
.extend_from_within(src
);
965 /// Returns this `String`'s capacity, in bytes.
972 /// let s = String::with_capacity(10);
974 /// assert!(s.capacity() >= 10);
978 #[stable(feature = "rust1", since = "1.0.0")]
979 pub fn capacity(&self) -> usize {
983 /// Reserves capacity for at least `additional` bytes more than the
984 /// current length. The allocator may reserve more space to speculatively
985 /// avoid frequent allocations. After calling `reserve`,
986 /// capacity will be greater than or equal to `self.len() + additional`.
987 /// Does nothing if capacity is already sufficient.
991 /// Panics if the new capacity overflows [`usize`].
998 /// let mut s = String::new();
1002 /// assert!(s.capacity() >= 10);
1005 /// This might not actually increase the capacity:
1008 /// let mut s = String::with_capacity(10);
1012 /// // s now has a length of 2 and a capacity of at least 10
1013 /// let capacity = s.capacity();
1014 /// assert_eq!(2, s.len());
1015 /// assert!(capacity >= 10);
1017 /// // Since we already have at least an extra 8 capacity, calling this...
1020 /// // ... doesn't actually increase.
1021 /// assert_eq!(capacity, s.capacity());
1023 #[cfg(not(no_global_oom_handling))]
1025 #[stable(feature = "rust1", since = "1.0.0")]
1026 pub fn reserve(&mut self, additional
: usize) {
1027 self.vec
.reserve(additional
)
1030 /// Reserves the minimum capacity for at least `additional` bytes more than
1031 /// the current length. Unlike [`reserve`], this will not
1032 /// deliberately over-allocate to speculatively avoid frequent allocations.
1033 /// After calling `reserve_exact`, capacity will be greater than or equal to
1034 /// `self.len() + additional`. Does nothing if the capacity is already
1037 /// [`reserve`]: String::reserve
1041 /// Panics if the new capacity overflows [`usize`].
1048 /// let mut s = String::new();
1050 /// s.reserve_exact(10);
1052 /// assert!(s.capacity() >= 10);
1055 /// This might not actually increase the capacity:
1058 /// let mut s = String::with_capacity(10);
1062 /// // s now has a length of 2 and a capacity of at least 10
1063 /// let capacity = s.capacity();
1064 /// assert_eq!(2, s.len());
1065 /// assert!(capacity >= 10);
1067 /// // Since we already have at least an extra 8 capacity, calling this...
1068 /// s.reserve_exact(8);
1070 /// // ... doesn't actually increase.
1071 /// assert_eq!(capacity, s.capacity());
1073 #[cfg(not(no_global_oom_handling))]
1075 #[stable(feature = "rust1", since = "1.0.0")]
1076 pub fn reserve_exact(&mut self, additional
: usize) {
1077 self.vec
.reserve_exact(additional
)
1080 /// Tries to reserve capacity for at least `additional` bytes more than the
1081 /// current length. The allocator may reserve more space to speculatively
1082 /// avoid frequent allocations. After calling `try_reserve`, capacity will be
1083 /// greater than or equal to `self.len() + additional` if it returns
1084 /// `Ok(())`. Does nothing if capacity is already sufficient. This method
1085 /// preserves the contents even if an error occurs.
1089 /// If the capacity overflows, or the allocator reports a failure, then an error
1095 /// use std::collections::TryReserveError;
1097 /// fn process_data(data: &str) -> Result<String, TryReserveError> {
1098 /// let mut output = String::new();
1100 /// // Pre-reserve the memory, exiting if we can't
1101 /// output.try_reserve(data.len())?;
1103 /// // Now we know this can't OOM in the middle of our complex work
1104 /// output.push_str(data);
1108 /// # process_data("rust").expect("why is the test harness OOMing on 4 bytes?");
1110 #[stable(feature = "try_reserve", since = "1.57.0")]
1111 pub fn try_reserve(&mut self, additional
: usize) -> Result
<(), TryReserveError
> {
1112 self.vec
.try_reserve(additional
)
1115 /// Tries to reserve the minimum capacity for at least `additional` bytes
1116 /// more than the current length. Unlike [`try_reserve`], this will not
1117 /// deliberately over-allocate to speculatively avoid frequent allocations.
1118 /// After calling `try_reserve_exact`, capacity will be greater than or
1119 /// equal to `self.len() + additional` if it returns `Ok(())`.
1120 /// Does nothing if the capacity is already sufficient.
1122 /// Note that the allocator may give the collection more space than it
1123 /// requests. Therefore, capacity can not be relied upon to be precisely
1124 /// minimal. Prefer [`try_reserve`] if future insertions are expected.
1126 /// [`try_reserve`]: String::try_reserve
1130 /// If the capacity overflows, or the allocator reports a failure, then an error
1136 /// use std::collections::TryReserveError;
1138 /// fn process_data(data: &str) -> Result<String, TryReserveError> {
1139 /// let mut output = String::new();
1141 /// // Pre-reserve the memory, exiting if we can't
1142 /// output.try_reserve_exact(data.len())?;
1144 /// // Now we know this can't OOM in the middle of our complex work
1145 /// output.push_str(data);
1149 /// # process_data("rust").expect("why is the test harness OOMing on 4 bytes?");
1151 #[stable(feature = "try_reserve", since = "1.57.0")]
1152 pub fn try_reserve_exact(&mut self, additional
: usize) -> Result
<(), TryReserveError
> {
1153 self.vec
.try_reserve_exact(additional
)
1156 /// Shrinks the capacity of this `String` to match its length.
1163 /// let mut s = String::from("foo");
1166 /// assert!(s.capacity() >= 100);
1168 /// s.shrink_to_fit();
1169 /// assert_eq!(3, s.capacity());
1171 #[cfg(not(no_global_oom_handling))]
1173 #[stable(feature = "rust1", since = "1.0.0")]
1174 pub fn shrink_to_fit(&mut self) {
1175 self.vec
.shrink_to_fit()
1178 /// Shrinks the capacity of this `String` with a lower bound.
1180 /// The capacity will remain at least as large as both the length
1181 /// and the supplied value.
1183 /// If the current capacity is less than the lower limit, this is a no-op.
1188 /// let mut s = String::from("foo");
1191 /// assert!(s.capacity() >= 100);
1193 /// s.shrink_to(10);
1194 /// assert!(s.capacity() >= 10);
1196 /// assert!(s.capacity() >= 3);
1198 #[cfg(not(no_global_oom_handling))]
1200 #[stable(feature = "shrink_to", since = "1.56.0")]
1201 pub fn shrink_to(&mut self, min_capacity
: usize) {
1202 self.vec
.shrink_to(min_capacity
)
1205 /// Appends the given [`char`] to the end of this `String`.
1212 /// let mut s = String::from("abc");
1218 /// assert_eq!("abc123", s);
1220 #[cfg(not(no_global_oom_handling))]
1222 #[stable(feature = "rust1", since = "1.0.0")]
1223 pub fn push(&mut self, ch
: char) {
1224 match ch
.len_utf8() {
1225 1 => self.vec
.push(ch
as u8),
1226 _
=> self.vec
.extend_from_slice(ch
.encode_utf8(&mut [0; 4]).as_bytes()),
1230 /// Returns a byte slice of this `String`'s contents.
1232 /// The inverse of this method is [`from_utf8`].
1234 /// [`from_utf8`]: String::from_utf8
1241 /// let s = String::from("hello");
1243 /// assert_eq!(&[104, 101, 108, 108, 111], s.as_bytes());
1247 #[stable(feature = "rust1", since = "1.0.0")]
1248 pub fn as_bytes(&self) -> &[u8] {
1252 /// Shortens this `String` to the specified length.
1254 /// If `new_len` is greater than the string's current length, this has no
1257 /// Note that this method has no effect on the allocated capacity
1262 /// Panics if `new_len` does not lie on a [`char`] boundary.
1269 /// let mut s = String::from("hello");
1273 /// assert_eq!("he", s);
1276 #[stable(feature = "rust1", since = "1.0.0")]
1277 pub fn truncate(&mut self, new_len
: usize) {
1278 if new_len
<= self.len() {
1279 assert
!(self.is_char_boundary(new_len
));
1280 self.vec
.truncate(new_len
)
1284 /// Removes the last character from the string buffer and returns it.
1286 /// Returns [`None`] if this `String` is empty.
1293 /// let mut s = String::from("foo");
1295 /// assert_eq!(s.pop(), Some('o'));
1296 /// assert_eq!(s.pop(), Some('o'));
1297 /// assert_eq!(s.pop(), Some('f'));
1299 /// assert_eq!(s.pop(), None);
1302 #[stable(feature = "rust1", since = "1.0.0")]
1303 pub fn pop(&mut self) -> Option
<char> {
1304 let ch
= self.chars().rev().next()?
;
1305 let newlen
= self.len() - ch
.len_utf8();
1307 self.vec
.set_len(newlen
);
1312 /// Removes a [`char`] from this `String` at a byte position and returns it.
1314 /// This is an *O*(*n*) operation, as it requires copying every element in the
1319 /// Panics if `idx` is larger than or equal to the `String`'s length,
1320 /// or if it does not lie on a [`char`] boundary.
1327 /// let mut s = String::from("foo");
1329 /// assert_eq!(s.remove(0), 'f');
1330 /// assert_eq!(s.remove(1), 'o');
1331 /// assert_eq!(s.remove(0), 'o');
1334 #[stable(feature = "rust1", since = "1.0.0")]
1335 pub fn remove(&mut self, idx
: usize) -> char {
1336 let ch
= match self[idx
..].chars().next() {
1338 None
=> panic
!("cannot remove a char from the end of a string"),
1341 let next
= idx
+ ch
.len_utf8();
1342 let len
= self.len();
1344 ptr
::copy(self.vec
.as_ptr().add(next
), self.vec
.as_mut_ptr().add(idx
), len
- next
);
1345 self.vec
.set_len(len
- (next
- idx
));
1350 /// Remove all matches of pattern `pat` in the `String`.
1355 /// #![feature(string_remove_matches)]
1356 /// let mut s = String::from("Trees are not green, the sky is not blue.");
1357 /// s.remove_matches("not ");
1358 /// assert_eq!("Trees are green, the sky is blue.", s);
1361 /// Matches will be detected and removed iteratively, so in cases where
1362 /// patterns overlap, only the first pattern will be removed:
1365 /// #![feature(string_remove_matches)]
1366 /// let mut s = String::from("banana");
1367 /// s.remove_matches("ana");
1368 /// assert_eq!("bna", s);
1370 #[cfg(not(no_global_oom_handling))]
1371 #[unstable(feature = "string_remove_matches", reason = "new API", issue = "72826")]
1372 pub fn remove_matches
<'a
, P
>(&'a
mut self, pat
: P
)
1374 P
: for<'x
> Pattern
<'x
>,
1376 use core
::str::pattern
::Searcher
;
1379 let mut searcher
= pat
.into_searcher(self);
1380 // Per Searcher::next:
1382 // A Match result needs to contain the whole matched pattern,
1383 // however Reject results may be split up into arbitrary many
1384 // adjacent fragments. Both ranges may have zero length.
1386 // In practice the implementation of Searcher::next_match tends to
1387 // be more efficient, so we use it here and do some work to invert
1388 // matches into rejections since that's what we want to copy below.
1390 let rejections
: Vec
<_
> = from_fn(|| {
1391 let (start
, end
) = searcher
.next_match()?
;
1392 let prev_front
= front
;
1394 Some((prev_front
, start
))
1397 rejections
.into_iter().chain(core
::iter
::once((front
, self.len())))
1401 let ptr
= self.vec
.as_mut_ptr();
1403 for (start
, end
) in rejections
{
1404 let count
= end
- start
;
1406 // SAFETY: per Searcher::next:
1408 // The stream of Match and Reject values up to a Done will
1409 // contain index ranges that are adjacent, non-overlapping,
1410 // covering the whole haystack, and laying on utf8
1413 ptr
::copy(ptr
.add(start
), ptr
.add(len
), count
);
1420 self.vec
.set_len(len
);
1424 /// Retains only the characters specified by the predicate.
1426 /// In other words, remove all characters `c` such that `f(c)` returns `false`.
1427 /// This method operates in place, visiting each character exactly once in the
1428 /// original order, and preserves the order of the retained characters.
1433 /// let mut s = String::from("f_o_ob_ar");
1435 /// s.retain(|c| c != '_');
1437 /// assert_eq!(s, "foobar");
1440 /// Because the elements are visited exactly once in the original order,
1441 /// external state may be used to decide which elements to keep.
1444 /// let mut s = String::from("abcde");
1445 /// let keep = [false, true, true, false, true];
1446 /// let mut iter = keep.iter();
1447 /// s.retain(|_| *iter.next().unwrap());
1448 /// assert_eq!(s, "bce");
1451 #[stable(feature = "string_retain", since = "1.26.0")]
1452 pub fn retain
<F
>(&mut self, mut f
: F
)
1454 F
: FnMut(char) -> bool
,
1456 struct SetLenOnDrop
<'a
> {
1462 impl<'a
> Drop
for SetLenOnDrop
<'a
> {
1463 fn drop(&mut self) {
1464 let new_len
= self.idx
- self.del_bytes
;
1465 debug_assert
!(new_len
<= self.s
.len());
1466 unsafe { self.s.vec.set_len(new_len) }
;
1470 let len
= self.len();
1471 let mut guard
= SetLenOnDrop { s: self, idx: 0, del_bytes: 0 }
;
1473 while guard
.idx
< len
{
1475 // SAFETY: `guard.idx` is positive-or-zero and less that len so the `get_unchecked`
1476 // is in bound. `self` is valid UTF-8 like string and the returned slice starts at
1477 // a unicode code point so the `Chars` always return one character.
1478 unsafe { guard.s.get_unchecked(guard.idx..len).chars().next().unwrap_unchecked() }
;
1479 let ch_len
= ch
.len_utf8();
1482 guard
.del_bytes
+= ch_len
;
1483 } else if guard
.del_bytes
> 0 {
1484 // SAFETY: `guard.idx` is in bound and `guard.del_bytes` represent the number of
1485 // bytes that are erased from the string so the resulting `guard.idx -
1486 // guard.del_bytes` always represent a valid unicode code point.
1488 // `guard.del_bytes` >= `ch.len_utf8()`, so taking a slice with `ch.len_utf8()` len
1490 ch
.encode_utf8(unsafe {
1491 crate::slice
::from_raw_parts_mut(
1492 guard
.s
.as_mut_ptr().add(guard
.idx
- guard
.del_bytes
),
1498 // Point idx to the next char
1499 guard
.idx
+= ch_len
;
1505 /// Inserts a character into this `String` at a byte position.
1507 /// This is an *O*(*n*) operation as it requires copying every element in the
1512 /// Panics if `idx` is larger than the `String`'s length, or if it does not
1513 /// lie on a [`char`] boundary.
1520 /// let mut s = String::with_capacity(3);
1522 /// s.insert(0, 'f');
1523 /// s.insert(1, 'o');
1524 /// s.insert(2, 'o');
1526 /// assert_eq!("foo", s);
1528 #[cfg(not(no_global_oom_handling))]
1530 #[stable(feature = "rust1", since = "1.0.0")]
1531 pub fn insert(&mut self, idx
: usize, ch
: char) {
1532 assert
!(self.is_char_boundary(idx
));
1533 let mut bits
= [0; 4];
1534 let bits
= ch
.encode_utf8(&mut bits
).as_bytes();
1537 self.insert_bytes(idx
, bits
);
1541 #[cfg(not(no_global_oom_handling))]
1542 unsafe fn insert_bytes(&mut self, idx
: usize, bytes
: &[u8]) {
1543 let len
= self.len();
1544 let amt
= bytes
.len();
1545 self.vec
.reserve(amt
);
1548 ptr
::copy(self.vec
.as_ptr().add(idx
), self.vec
.as_mut_ptr().add(idx
+ amt
), len
- idx
);
1549 ptr
::copy_nonoverlapping(bytes
.as_ptr(), self.vec
.as_mut_ptr().add(idx
), amt
);
1550 self.vec
.set_len(len
+ amt
);
1554 /// Inserts a string slice into this `String` at a byte position.
1556 /// This is an *O*(*n*) operation as it requires copying every element in the
1561 /// Panics if `idx` is larger than the `String`'s length, or if it does not
1562 /// lie on a [`char`] boundary.
1569 /// let mut s = String::from("bar");
1571 /// s.insert_str(0, "foo");
1573 /// assert_eq!("foobar", s);
1575 #[cfg(not(no_global_oom_handling))]
1577 #[stable(feature = "insert_str", since = "1.16.0")]
1578 pub fn insert_str(&mut self, idx
: usize, string
: &str) {
1579 assert
!(self.is_char_boundary(idx
));
1582 self.insert_bytes(idx
, string
.as_bytes());
1586 /// Returns a mutable reference to the contents of this `String`.
1590 /// This function is unsafe because the returned `&mut Vec` allows writing
1591 /// bytes which are not valid UTF-8. If this constraint is violated, using
1592 /// the original `String` after dropping the `&mut Vec` may violate memory
1593 /// safety, as the rest of the standard library assumes that `String`s are
1601 /// let mut s = String::from("hello");
1604 /// let vec = s.as_mut_vec();
1605 /// assert_eq!(&[104, 101, 108, 108, 111][..], &vec[..]);
1609 /// assert_eq!(s, "olleh");
1612 #[stable(feature = "rust1", since = "1.0.0")]
1613 pub unsafe fn as_mut_vec(&mut self) -> &mut Vec
<u8> {
1617 /// Returns the length of this `String`, in bytes, not [`char`]s or
1618 /// graphemes. In other words, it might not be what a human considers the
1619 /// length of the string.
1626 /// let a = String::from("foo");
1627 /// assert_eq!(a.len(), 3);
1629 /// let fancy_f = String::from("Ζoo");
1630 /// assert_eq!(fancy_f.len(), 4);
1631 /// assert_eq!(fancy_f.chars().count(), 3);
1635 #[stable(feature = "rust1", since = "1.0.0")]
1636 pub fn len(&self) -> usize {
1640 /// Returns `true` if this `String` has a length of zero, and `false` otherwise.
1647 /// let mut v = String::new();
1648 /// assert!(v.is_empty());
1651 /// assert!(!v.is_empty());
1655 #[stable(feature = "rust1", since = "1.0.0")]
1656 pub fn is_empty(&self) -> bool
{
1660 /// Splits the string into two at the given byte index.
1662 /// Returns a newly allocated `String`. `self` contains bytes `[0, at)`, and
1663 /// the returned `String` contains bytes `[at, len)`. `at` must be on the
1664 /// boundary of a UTF-8 code point.
1666 /// Note that the capacity of `self` does not change.
1670 /// Panics if `at` is not on a `UTF-8` code point boundary, or if it is beyond the last
1671 /// code point of the string.
1677 /// let mut hello = String::from("Hello, World!");
1678 /// let world = hello.split_off(7);
1679 /// assert_eq!(hello, "Hello, ");
1680 /// assert_eq!(world, "World!");
1683 #[cfg(not(no_global_oom_handling))]
1685 #[stable(feature = "string_split_off", since = "1.16.0")]
1686 #[must_use = "use `.truncate()` if you don't need the other half"]
1687 pub fn split_off(&mut self, at
: usize) -> String
{
1688 assert
!(self.is_char_boundary(at
));
1689 let other
= self.vec
.split_off(at
);
1690 unsafe { String::from_utf8_unchecked(other) }
1693 /// Truncates this `String`, removing all contents.
1695 /// While this means the `String` will have a length of zero, it does not
1696 /// touch its capacity.
1703 /// let mut s = String::from("foo");
1707 /// assert!(s.is_empty());
1708 /// assert_eq!(0, s.len());
1709 /// assert_eq!(3, s.capacity());
1712 #[stable(feature = "rust1", since = "1.0.0")]
1713 pub fn clear(&mut self) {
1717 /// Removes the specified range from the string in bulk, returning all
1718 /// removed characters as an iterator.
1720 /// The returned iterator keeps a mutable borrow on the string to optimize
1721 /// its implementation.
1725 /// Panics if the starting point or end point do not lie on a [`char`]
1726 /// boundary, or if they're out of bounds.
1730 /// If the returned iterator goes out of scope without being dropped (due to
1731 /// [`core::mem::forget`], for example), the string may still contain a copy
1732 /// of any drained characters, or may have lost characters arbitrarily,
1733 /// including characters outside the range.
1740 /// let mut s = String::from("Ξ± is alpha, Ξ² is beta");
1741 /// let beta_offset = s.find('Ξ²').unwrap_or(s.len());
1743 /// // Remove the range up until the Ξ² from the string
1744 /// let t: String = s.drain(..beta_offset).collect();
1745 /// assert_eq!(t, "Ξ± is alpha, ");
1746 /// assert_eq!(s, "Ξ² is beta");
1748 /// // A full range clears the string, like `clear()` does
1750 /// assert_eq!(s, "");
1752 #[stable(feature = "drain", since = "1.6.0")]
1753 pub fn drain
<R
>(&mut self, range
: R
) -> Drain
<'_
>
1755 R
: RangeBounds
<usize>,
1759 // The String version of Drain does not have the memory safety issues
1760 // of the vector version. The data is just plain bytes.
1761 // Because the range removal happens in Drop, if the Drain iterator is leaked,
1762 // the removal will not happen.
1763 let Range { start, end }
= slice
::range(range
, ..self.len());
1764 assert
!(self.is_char_boundary(start
));
1765 assert
!(self.is_char_boundary(end
));
1767 // Take out two simultaneous borrows. The &mut String won't be accessed
1768 // until iteration is over, in Drop.
1769 let self_ptr
= self as *mut _
;
1770 // SAFETY: `slice::range` and `is_char_boundary` do the appropriate bounds checks.
1771 let chars_iter
= unsafe { self.get_unchecked(start..end) }
.chars();
1773 Drain { start, end, iter: chars_iter, string: self_ptr }
1776 /// Removes the specified range in the string,
1777 /// and replaces it with the given string.
1778 /// The given string doesn't need to be the same length as the range.
1782 /// Panics if the starting point or end point do not lie on a [`char`]
1783 /// boundary, or if they're out of bounds.
1790 /// let mut s = String::from("Ξ± is alpha, Ξ² is beta");
1791 /// let beta_offset = s.find('Ξ²').unwrap_or(s.len());
1793 /// // Replace the range up until the Ξ² from the string
1794 /// s.replace_range(..beta_offset, "Ξ is capital alpha; ");
1795 /// assert_eq!(s, "Ξ is capital alpha; Ξ² is beta");
1797 #[cfg(not(no_global_oom_handling))]
1798 #[stable(feature = "splice", since = "1.27.0")]
1799 pub fn replace_range
<R
>(&mut self, range
: R
, replace_with
: &str)
1801 R
: RangeBounds
<usize>,
1805 // Replace_range does not have the memory safety issues of a vector Splice.
1806 // of the vector version. The data is just plain bytes.
1808 // WARNING: Inlining this variable would be unsound (#81138)
1809 let start
= range
.start_bound();
1811 Included(&n
) => assert
!(self.is_char_boundary(n
)),
1812 Excluded(&n
) => assert
!(self.is_char_boundary(n
+ 1)),
1815 // WARNING: Inlining this variable would be unsound (#81138)
1816 let end
= range
.end_bound();
1818 Included(&n
) => assert
!(self.is_char_boundary(n
+ 1)),
1819 Excluded(&n
) => assert
!(self.is_char_boundary(n
)),
1823 // Using `range` again would be unsound (#81138)
1824 // We assume the bounds reported by `range` remain the same, but
1825 // an adversarial implementation could change between calls
1826 unsafe { self.as_mut_vec() }
.splice((start
, end
), replace_with
.bytes());
1829 /// Converts this `String` into a <code>[Box]<[str]></code>.
1831 /// This will drop any excess capacity.
1833 /// [str]: prim@str "str"
1840 /// let s = String::from("hello");
1842 /// let b = s.into_boxed_str();
1844 #[cfg(not(no_global_oom_handling))]
1845 #[stable(feature = "box_str", since = "1.4.0")]
1846 #[must_use = "`self` will be dropped if the result is not used"]
1848 pub fn into_boxed_str(self) -> Box
<str> {
1849 let slice
= self.vec
.into_boxed_slice();
1850 unsafe { from_boxed_utf8_unchecked(slice) }
1853 /// Consumes and leaks the `String`, returning a mutable reference to the contents,
1854 /// `&'static mut str`.
1856 /// This is mainly useful for data that lives for the remainder of
1857 /// the program's life. Dropping the returned reference will cause a memory
1860 /// It does not reallocate or shrink the `String`,
1861 /// so the leaked allocation may include unused capacity that is not part
1862 /// of the returned slice.
1869 /// #![feature(string_leak)]
1871 /// let x = String::from("bucket");
1872 /// let static_ref: &'static mut str = x.leak();
1873 /// assert_eq!(static_ref, "bucket");
1875 #[unstable(feature = "string_leak", issue = "102929")]
1877 pub fn leak(self) -> &'
static mut str {
1878 let slice
= self.vec
.leak();
1879 unsafe { from_utf8_unchecked_mut(slice) }
1883 impl FromUtf8Error
{
1884 /// Returns a slice of [`u8`]s bytes that were attempted to convert to a `String`.
1891 /// // some invalid bytes, in a vector
1892 /// let bytes = vec![0, 159];
1894 /// let value = String::from_utf8(bytes);
1896 /// assert_eq!(&[0, 159], value.unwrap_err().as_bytes());
1899 #[stable(feature = "from_utf8_error_as_bytes", since = "1.26.0")]
1900 pub fn as_bytes(&self) -> &[u8] {
1904 /// Returns the bytes that were attempted to convert to a `String`.
1906 /// This method is carefully constructed to avoid allocation. It will
1907 /// consume the error, moving out the bytes, so that a copy of the bytes
1908 /// does not need to be made.
1915 /// // some invalid bytes, in a vector
1916 /// let bytes = vec![0, 159];
1918 /// let value = String::from_utf8(bytes);
1920 /// assert_eq!(vec![0, 159], value.unwrap_err().into_bytes());
1922 #[must_use = "`self` will be dropped if the result is not used"]
1923 #[stable(feature = "rust1", since = "1.0.0")]
1924 pub fn into_bytes(self) -> Vec
<u8> {
1928 /// Fetch a `Utf8Error` to get more details about the conversion failure.
1930 /// The [`Utf8Error`] type provided by [`std::str`] represents an error that may
1931 /// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's
1932 /// an analogue to `FromUtf8Error`. See its documentation for more details
1935 /// [`std::str`]: core::str "std::str"
1936 /// [`&str`]: prim@str "&str"
1943 /// // some invalid bytes, in a vector
1944 /// let bytes = vec![0, 159];
1946 /// let error = String::from_utf8(bytes).unwrap_err().utf8_error();
1948 /// // the first byte is invalid here
1949 /// assert_eq!(1, error.valid_up_to());
1952 #[stable(feature = "rust1", since = "1.0.0")]
1953 pub fn utf8_error(&self) -> Utf8Error
{
1958 #[stable(feature = "rust1", since = "1.0.0")]
1959 impl fmt
::Display
for FromUtf8Error
{
1960 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
1961 fmt
::Display
::fmt(&self.error
, f
)
1965 #[stable(feature = "rust1", since = "1.0.0")]
1966 impl fmt
::Display
for FromUtf16Error
{
1967 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
1968 fmt
::Display
::fmt("invalid utf-16: lone surrogate found", f
)
1972 #[stable(feature = "rust1", since = "1.0.0")]
1973 impl Error
for FromUtf8Error
{
1974 #[allow(deprecated)]
1975 fn description(&self) -> &str {
1980 #[stable(feature = "rust1", since = "1.0.0")]
1981 impl Error
for FromUtf16Error
{
1982 #[allow(deprecated)]
1983 fn description(&self) -> &str {
1988 #[cfg(not(no_global_oom_handling))]
1989 #[stable(feature = "rust1", since = "1.0.0")]
1990 impl Clone
for String
{
1991 fn clone(&self) -> Self {
1992 String { vec: self.vec.clone() }
1995 fn clone_from(&mut self, source
: &Self) {
1996 self.vec
.clone_from(&source
.vec
);
2000 #[cfg(not(no_global_oom_handling))]
2001 #[stable(feature = "rust1", since = "1.0.0")]
2002 impl FromIterator
<char> for String
{
2003 fn from_iter
<I
: IntoIterator
<Item
= char>>(iter
: I
) -> String
{
2004 let mut buf
= String
::new();
2010 #[cfg(not(no_global_oom_handling))]
2011 #[stable(feature = "string_from_iter_by_ref", since = "1.17.0")]
2012 impl<'a
> FromIterator
<&'a
char> for String
{
2013 fn from_iter
<I
: IntoIterator
<Item
= &'a
char>>(iter
: I
) -> String
{
2014 let mut buf
= String
::new();
2020 #[cfg(not(no_global_oom_handling))]
2021 #[stable(feature = "rust1", since = "1.0.0")]
2022 impl<'a
> FromIterator
<&'a
str> for String
{
2023 fn from_iter
<I
: IntoIterator
<Item
= &'a
str>>(iter
: I
) -> String
{
2024 let mut buf
= String
::new();
2030 #[cfg(not(no_global_oom_handling))]
2031 #[stable(feature = "extend_string", since = "1.4.0")]
2032 impl FromIterator
<String
> for String
{
2033 fn from_iter
<I
: IntoIterator
<Item
= String
>>(iter
: I
) -> String
{
2034 let mut iterator
= iter
.into_iter();
2036 // Because we're iterating over `String`s, we can avoid at least
2037 // one allocation by getting the first string from the iterator
2038 // and appending to it all the subsequent strings.
2039 match iterator
.next() {
2040 None
=> String
::new(),
2042 buf
.extend(iterator
);
2049 #[cfg(not(no_global_oom_handling))]
2050 #[stable(feature = "box_str2", since = "1.45.0")]
2051 impl FromIterator
<Box
<str>> for String
{
2052 fn from_iter
<I
: IntoIterator
<Item
= Box
<str>>>(iter
: I
) -> String
{
2053 let mut buf
= String
::new();
2059 #[cfg(not(no_global_oom_handling))]
2060 #[stable(feature = "herd_cows", since = "1.19.0")]
2061 impl<'a
> FromIterator
<Cow
<'a
, str>> for String
{
2062 fn from_iter
<I
: IntoIterator
<Item
= Cow
<'a
, str>>>(iter
: I
) -> String
{
2063 let mut iterator
= iter
.into_iter();
2065 // Because we're iterating over CoWs, we can (potentially) avoid at least
2066 // one allocation by getting the first item and appending to it all the
2067 // subsequent items.
2068 match iterator
.next() {
2069 None
=> String
::new(),
2071 let mut buf
= cow
.into_owned();
2072 buf
.extend(iterator
);
2079 #[cfg(not(no_global_oom_handling))]
2080 #[stable(feature = "rust1", since = "1.0.0")]
2081 impl Extend
<char> for String
{
2082 fn extend
<I
: IntoIterator
<Item
= char>>(&mut self, iter
: I
) {
2083 let iterator
= iter
.into_iter();
2084 let (lower_bound
, _
) = iterator
.size_hint();
2085 self.reserve(lower_bound
);
2086 iterator
.for_each(move |c
| self.push(c
));
2090 fn extend_one(&mut self, c
: char) {
2095 fn extend_reserve(&mut self, additional
: usize) {
2096 self.reserve(additional
);
2100 #[cfg(not(no_global_oom_handling))]
2101 #[stable(feature = "extend_ref", since = "1.2.0")]
2102 impl<'a
> Extend
<&'a
char> for String
{
2103 fn extend
<I
: IntoIterator
<Item
= &'a
char>>(&mut self, iter
: I
) {
2104 self.extend(iter
.into_iter().cloned());
2108 fn extend_one(&mut self, &c
: &'a
char) {
2113 fn extend_reserve(&mut self, additional
: usize) {
2114 self.reserve(additional
);
2118 #[cfg(not(no_global_oom_handling))]
2119 #[stable(feature = "rust1", since = "1.0.0")]
2120 impl<'a
> Extend
<&'a
str> for String
{
2121 fn extend
<I
: IntoIterator
<Item
= &'a
str>>(&mut self, iter
: I
) {
2122 iter
.into_iter().for_each(move |s
| self.push_str(s
));
2126 fn extend_one(&mut self, s
: &'a
str) {
2131 #[cfg(not(no_global_oom_handling))]
2132 #[stable(feature = "box_str2", since = "1.45.0")]
2133 impl Extend
<Box
<str>> for String
{
2134 fn extend
<I
: IntoIterator
<Item
= Box
<str>>>(&mut self, iter
: I
) {
2135 iter
.into_iter().for_each(move |s
| self.push_str(&s
));
2139 #[cfg(not(no_global_oom_handling))]
2140 #[stable(feature = "extend_string", since = "1.4.0")]
2141 impl Extend
<String
> for String
{
2142 fn extend
<I
: IntoIterator
<Item
= String
>>(&mut self, iter
: I
) {
2143 iter
.into_iter().for_each(move |s
| self.push_str(&s
));
2147 fn extend_one(&mut self, s
: String
) {
2152 #[cfg(not(no_global_oom_handling))]
2153 #[stable(feature = "herd_cows", since = "1.19.0")]
2154 impl<'a
> Extend
<Cow
<'a
, str>> for String
{
2155 fn extend
<I
: IntoIterator
<Item
= Cow
<'a
, str>>>(&mut self, iter
: I
) {
2156 iter
.into_iter().for_each(move |s
| self.push_str(&s
));
2160 fn extend_one(&mut self, s
: Cow
<'a
, str>) {
2165 /// A convenience impl that delegates to the impl for `&str`.
2170 /// assert_eq!(String::from("Hello world").find("world"), Some(6));
2173 feature
= "pattern",
2174 reason
= "API not fully fleshed out and ready to be stabilized",
2177 impl<'a
, 'b
> Pattern
<'a
> for &'b String
{
2178 type Searcher
= <&'b
str as Pattern
<'a
>>::Searcher
;
2180 fn into_searcher(self, haystack
: &'a
str) -> <&'b
str as Pattern
<'a
>>::Searcher
{
2181 self[..].into_searcher(haystack
)
2185 fn is_contained_in(self, haystack
: &'a
str) -> bool
{
2186 self[..].is_contained_in(haystack
)
2190 fn is_prefix_of(self, haystack
: &'a
str) -> bool
{
2191 self[..].is_prefix_of(haystack
)
2195 fn strip_prefix_of(self, haystack
: &'a
str) -> Option
<&'a
str> {
2196 self[..].strip_prefix_of(haystack
)
2200 fn is_suffix_of(self, haystack
: &'a
str) -> bool
{
2201 self[..].is_suffix_of(haystack
)
2205 fn strip_suffix_of(self, haystack
: &'a
str) -> Option
<&'a
str> {
2206 self[..].strip_suffix_of(haystack
)
2210 #[stable(feature = "rust1", since = "1.0.0")]
2211 impl PartialEq
for String
{
2213 fn eq(&self, other
: &String
) -> bool
{
2214 PartialEq
::eq(&self[..], &other
[..])
2217 fn ne(&self, other
: &String
) -> bool
{
2218 PartialEq
::ne(&self[..], &other
[..])
2222 macro_rules
! impl_eq
{
2223 ($lhs
:ty
, $rhs
: ty
) => {
2224 #[stable(feature = "rust1", since = "1.0.0")]
2225 #[allow(unused_lifetimes)]
2226 impl<'a
, 'b
> PartialEq
<$rhs
> for $lhs
{
2228 fn eq(&self, other
: &$rhs
) -> bool
{
2229 PartialEq
::eq(&self[..], &other
[..])
2232 fn ne(&self, other
: &$rhs
) -> bool
{
2233 PartialEq
::ne(&self[..], &other
[..])
2237 #[stable(feature = "rust1", since = "1.0.0")]
2238 #[allow(unused_lifetimes)]
2239 impl<'a
, 'b
> PartialEq
<$lhs
> for $rhs
{
2241 fn eq(&self, other
: &$lhs
) -> bool
{
2242 PartialEq
::eq(&self[..], &other
[..])
2245 fn ne(&self, other
: &$lhs
) -> bool
{
2246 PartialEq
::ne(&self[..], &other
[..])
2252 impl_eq
! { String, str }
2253 impl_eq
! { String, &'a str }
2254 #[cfg(not(no_global_oom_handling))]
2255 impl_eq
! { Cow<'a, str>, str }
2256 #[cfg(not(no_global_oom_handling))]
2257 impl_eq
! { Cow<'a, str>, &'b str }
2258 #[cfg(not(no_global_oom_handling))]
2259 impl_eq
! { Cow<'a, str>, String }
2261 #[stable(feature = "rust1", since = "1.0.0")]
2262 #[rustc_const_unstable(feature = "const_default_impls", issue = "87864")]
2263 impl const Default
for String
{
2264 /// Creates an empty `String`.
2266 fn default() -> String
{
2271 #[stable(feature = "rust1", since = "1.0.0")]
2272 impl fmt
::Display
for String
{
2274 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
2275 fmt
::Display
::fmt(&**self, f
)
2279 #[stable(feature = "rust1", since = "1.0.0")]
2280 impl fmt
::Debug
for String
{
2282 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
2283 fmt
::Debug
::fmt(&**self, f
)
2287 #[stable(feature = "rust1", since = "1.0.0")]
2288 impl hash
::Hash
for String
{
2290 fn hash
<H
: hash
::Hasher
>(&self, hasher
: &mut H
) {
2291 (**self).hash(hasher
)
2295 /// Implements the `+` operator for concatenating two strings.
2297 /// This consumes the `String` on the left-hand side and re-uses its buffer (growing it if
2298 /// necessary). This is done to avoid allocating a new `String` and copying the entire contents on
2299 /// every operation, which would lead to *O*(*n*^2) running time when building an *n*-byte string by
2300 /// repeated concatenation.
2302 /// The string on the right-hand side is only borrowed; its contents are copied into the returned
2307 /// Concatenating two `String`s takes the first by value and borrows the second:
2310 /// let a = String::from("hello");
2311 /// let b = String::from(" world");
2313 /// // `a` is moved and can no longer be used here.
2316 /// If you want to keep using the first `String`, you can clone it and append to the clone instead:
2319 /// let a = String::from("hello");
2320 /// let b = String::from(" world");
2321 /// let c = a.clone() + &b;
2322 /// // `a` is still valid here.
2325 /// Concatenating `&str` slices can be done by converting the first to a `String`:
2328 /// let a = "hello";
2329 /// let b = " world";
2330 /// let c = a.to_string() + b;
2332 #[cfg(not(no_global_oom_handling))]
2333 #[stable(feature = "rust1", since = "1.0.0")]
2334 impl Add
<&str> for String
{
2335 type Output
= String
;
2338 fn add(mut self, other
: &str) -> String
{
2339 self.push_str(other
);
2344 /// Implements the `+=` operator for appending to a `String`.
2346 /// This has the same behavior as the [`push_str`][String::push_str] method.
2347 #[cfg(not(no_global_oom_handling))]
2348 #[stable(feature = "stringaddassign", since = "1.12.0")]
2349 impl AddAssign
<&str> for String
{
2351 fn add_assign(&mut self, other
: &str) {
2352 self.push_str(other
);
2356 #[stable(feature = "rust1", since = "1.0.0")]
2357 impl ops
::Index
<ops
::Range
<usize>> for String
{
2361 fn index(&self, index
: ops
::Range
<usize>) -> &str {
2365 #[stable(feature = "rust1", since = "1.0.0")]
2366 impl ops
::Index
<ops
::RangeTo
<usize>> for String
{
2370 fn index(&self, index
: ops
::RangeTo
<usize>) -> &str {
2374 #[stable(feature = "rust1", since = "1.0.0")]
2375 impl ops
::Index
<ops
::RangeFrom
<usize>> for String
{
2379 fn index(&self, index
: ops
::RangeFrom
<usize>) -> &str {
2383 #[stable(feature = "rust1", since = "1.0.0")]
2384 impl ops
::Index
<ops
::RangeFull
> for String
{
2388 fn index(&self, _index
: ops
::RangeFull
) -> &str {
2389 unsafe { str::from_utf8_unchecked(&self.vec) }
2392 #[stable(feature = "inclusive_range", since = "1.26.0")]
2393 impl ops
::Index
<ops
::RangeInclusive
<usize>> for String
{
2397 fn index(&self, index
: ops
::RangeInclusive
<usize>) -> &str {
2398 Index
::index(&**self, index
)
2401 #[stable(feature = "inclusive_range", since = "1.26.0")]
2402 impl ops
::Index
<ops
::RangeToInclusive
<usize>> for String
{
2406 fn index(&self, index
: ops
::RangeToInclusive
<usize>) -> &str {
2407 Index
::index(&**self, index
)
2411 #[stable(feature = "derefmut_for_string", since = "1.3.0")]
2412 impl ops
::IndexMut
<ops
::Range
<usize>> for String
{
2414 fn index_mut(&mut self, index
: ops
::Range
<usize>) -> &mut str {
2415 &mut self[..][index
]
2418 #[stable(feature = "derefmut_for_string", since = "1.3.0")]
2419 impl ops
::IndexMut
<ops
::RangeTo
<usize>> for String
{
2421 fn index_mut(&mut self, index
: ops
::RangeTo
<usize>) -> &mut str {
2422 &mut self[..][index
]
2425 #[stable(feature = "derefmut_for_string", since = "1.3.0")]
2426 impl ops
::IndexMut
<ops
::RangeFrom
<usize>> for String
{
2428 fn index_mut(&mut self, index
: ops
::RangeFrom
<usize>) -> &mut str {
2429 &mut self[..][index
]
2432 #[stable(feature = "derefmut_for_string", since = "1.3.0")]
2433 impl ops
::IndexMut
<ops
::RangeFull
> for String
{
2435 fn index_mut(&mut self, _index
: ops
::RangeFull
) -> &mut str {
2436 unsafe { str::from_utf8_unchecked_mut(&mut *self.vec) }
2439 #[stable(feature = "inclusive_range", since = "1.26.0")]
2440 impl ops
::IndexMut
<ops
::RangeInclusive
<usize>> for String
{
2442 fn index_mut(&mut self, index
: ops
::RangeInclusive
<usize>) -> &mut str {
2443 IndexMut
::index_mut(&mut **self, index
)
2446 #[stable(feature = "inclusive_range", since = "1.26.0")]
2447 impl ops
::IndexMut
<ops
::RangeToInclusive
<usize>> for String
{
2449 fn index_mut(&mut self, index
: ops
::RangeToInclusive
<usize>) -> &mut str {
2450 IndexMut
::index_mut(&mut **self, index
)
2454 #[stable(feature = "rust1", since = "1.0.0")]
2455 impl ops
::Deref
for String
{
2459 fn deref(&self) -> &str {
2460 unsafe { str::from_utf8_unchecked(&self.vec) }
2464 #[stable(feature = "derefmut_for_string", since = "1.3.0")]
2465 impl ops
::DerefMut
for String
{
2467 fn deref_mut(&mut self) -> &mut str {
2468 unsafe { str::from_utf8_unchecked_mut(&mut *self.vec) }
2472 /// A type alias for [`Infallible`].
2474 /// This alias exists for backwards compatibility, and may be eventually deprecated.
2476 /// [`Infallible`]: core::convert::Infallible "convert::Infallible"
2477 #[stable(feature = "str_parse_error", since = "1.5.0")]
2478 pub type ParseError
= core
::convert
::Infallible
;
2480 #[cfg(not(no_global_oom_handling))]
2481 #[stable(feature = "rust1", since = "1.0.0")]
2482 impl FromStr
for String
{
2483 type Err
= core
::convert
::Infallible
;
2485 fn from_str(s
: &str) -> Result
<String
, Self::Err
> {
2490 /// A trait for converting a value to a `String`.
2492 /// This trait is automatically implemented for any type which implements the
2493 /// [`Display`] trait. As such, `ToString` shouldn't be implemented directly:
2494 /// [`Display`] should be implemented instead, and you get the `ToString`
2495 /// implementation for free.
2497 /// [`Display`]: fmt::Display
2498 #[cfg_attr(not(test), rustc_diagnostic_item = "ToString")]
2499 #[stable(feature = "rust1", since = "1.0.0")]
2500 pub trait ToString
{
2501 /// Converts the given value to a `String`.
2509 /// let five = String::from("5");
2511 /// assert_eq!(five, i.to_string());
2513 #[rustc_conversion_suggestion]
2514 #[stable(feature = "rust1", since = "1.0.0")]
2515 fn to_string(&self) -> String
;
2520 /// In this implementation, the `to_string` method panics
2521 /// if the `Display` implementation returns an error.
2522 /// This indicates an incorrect `Display` implementation
2523 /// since `fmt::Write for String` never returns an error itself.
2524 #[cfg(not(no_global_oom_handling))]
2525 #[stable(feature = "rust1", since = "1.0.0")]
2526 impl<T
: fmt
::Display
+ ?Sized
> ToString
for T
{
2527 // A common guideline is to not inline generic functions. However,
2528 // removing `#[inline]` from this method causes non-negligible regressions.
2529 // See <https://github.com/rust-lang/rust/pull/74852>, the last attempt
2530 // to try to remove it.
2532 default fn to_string(&self) -> String
{
2533 let mut buf
= String
::new();
2534 let mut formatter
= core
::fmt
::Formatter
::new(&mut buf
);
2535 // Bypass format_args!() to avoid write_str with zero-length strs
2536 fmt
::Display
::fmt(self, &mut formatter
)
2537 .expect("a Display implementation returned an error unexpectedly");
2542 #[cfg(not(no_global_oom_handling))]
2543 #[stable(feature = "char_to_string_specialization", since = "1.46.0")]
2544 impl ToString
for char {
2546 fn to_string(&self) -> String
{
2547 String
::from(self.encode_utf8(&mut [0; 4]))
2551 #[cfg(not(no_global_oom_handling))]
2552 #[stable(feature = "u8_to_string_specialization", since = "1.54.0")]
2553 impl ToString
for u8 {
2555 fn to_string(&self) -> String
{
2556 let mut buf
= String
::with_capacity(3);
2560 buf
.push((b'
0'
+ n
/ 100) as char);
2563 buf
.push((b'
0'
+ n
/ 10) as char);
2566 buf
.push((b'
0'
+ n
) as char);
2571 #[cfg(not(no_global_oom_handling))]
2572 #[stable(feature = "i8_to_string_specialization", since = "1.54.0")]
2573 impl ToString
for i8 {
2575 fn to_string(&self) -> String
{
2576 let mut buf
= String
::with_capacity(4);
2577 if self.is_negative() {
2580 let mut n
= self.unsigned_abs();
2586 buf
.push((b'
0'
+ n
/ 10) as char);
2589 buf
.push((b'
0'
+ n
) as char);
2594 #[cfg(not(no_global_oom_handling))]
2595 #[stable(feature = "str_to_string_specialization", since = "1.9.0")]
2596 impl ToString
for str {
2598 fn to_string(&self) -> String
{
2603 #[cfg(not(no_global_oom_handling))]
2604 #[stable(feature = "cow_str_to_string_specialization", since = "1.17.0")]
2605 impl ToString
for Cow
<'_
, str> {
2607 fn to_string(&self) -> String
{
2612 #[cfg(not(no_global_oom_handling))]
2613 #[stable(feature = "string_to_string_specialization", since = "1.17.0")]
2614 impl ToString
for String
{
2616 fn to_string(&self) -> String
{
2621 #[stable(feature = "rust1", since = "1.0.0")]
2622 impl AsRef
<str> for String
{
2624 fn as_ref(&self) -> &str {
2629 #[stable(feature = "string_as_mut", since = "1.43.0")]
2630 impl AsMut
<str> for String
{
2632 fn as_mut(&mut self) -> &mut str {
2637 #[stable(feature = "rust1", since = "1.0.0")]
2638 impl AsRef
<[u8]> for String
{
2640 fn as_ref(&self) -> &[u8] {
2645 #[cfg(not(no_global_oom_handling))]
2646 #[stable(feature = "rust1", since = "1.0.0")]
2647 impl From
<&str> for String
{
2648 /// Converts a `&str` into a [`String`].
2650 /// The result is allocated on the heap.
2652 fn from(s
: &str) -> String
{
2657 #[cfg(not(no_global_oom_handling))]
2658 #[stable(feature = "from_mut_str_for_string", since = "1.44.0")]
2659 impl From
<&mut str> for String
{
2660 /// Converts a `&mut str` into a [`String`].
2662 /// The result is allocated on the heap.
2664 fn from(s
: &mut str) -> String
{
2669 #[cfg(not(no_global_oom_handling))]
2670 #[stable(feature = "from_ref_string", since = "1.35.0")]
2671 impl From
<&String
> for String
{
2672 /// Converts a `&String` into a [`String`].
2674 /// This clones `s` and returns the clone.
2676 fn from(s
: &String
) -> String
{
2681 // note: test pulls in libstd, which causes errors here
2683 #[stable(feature = "string_from_box", since = "1.18.0")]
2684 impl From
<Box
<str>> for String
{
2685 /// Converts the given boxed `str` slice to a [`String`].
2686 /// It is notable that the `str` slice is owned.
2693 /// let s1: String = String::from("hello world");
2694 /// let s2: Box<str> = s1.into_boxed_str();
2695 /// let s3: String = String::from(s2);
2697 /// assert_eq!("hello world", s3)
2699 fn from(s
: Box
<str>) -> String
{
2704 #[cfg(not(no_global_oom_handling))]
2705 #[stable(feature = "box_from_str", since = "1.20.0")]
2706 impl From
<String
> for Box
<str> {
2707 /// Converts the given [`String`] to a boxed `str` slice that is owned.
2714 /// let s1: String = String::from("hello world");
2715 /// let s2: Box<str> = Box::from(s1);
2716 /// let s3: String = String::from(s2);
2718 /// assert_eq!("hello world", s3)
2720 fn from(s
: String
) -> Box
<str> {
2725 #[cfg(not(no_global_oom_handling))]
2726 #[stable(feature = "string_from_cow_str", since = "1.14.0")]
2727 impl<'a
> From
<Cow
<'a
, str>> for String
{
2728 /// Converts a clone-on-write string to an owned
2729 /// instance of [`String`].
2731 /// This extracts the owned string,
2732 /// clones the string if it is not already owned.
2737 /// # use std::borrow::Cow;
2738 /// // If the string is not owned...
2739 /// let cow: Cow<str> = Cow::Borrowed("eggplant");
2740 /// // It will allocate on the heap and copy the string.
2741 /// let owned: String = String::from(cow);
2742 /// assert_eq!(&owned[..], "eggplant");
2744 fn from(s
: Cow
<'a
, str>) -> String
{
2749 #[cfg(not(no_global_oom_handling))]
2750 #[stable(feature = "rust1", since = "1.0.0")]
2751 impl<'a
> From
<&'a
str> for Cow
<'a
, str> {
2752 /// Converts a string slice into a [`Borrowed`] variant.
2753 /// No heap allocation is performed, and the string
2759 /// # use std::borrow::Cow;
2760 /// assert_eq!(Cow::from("eggplant"), Cow::Borrowed("eggplant"));
2763 /// [`Borrowed`]: crate::borrow::Cow::Borrowed "borrow::Cow::Borrowed"
2765 fn from(s
: &'a
str) -> Cow
<'a
, str> {
2770 #[cfg(not(no_global_oom_handling))]
2771 #[stable(feature = "rust1", since = "1.0.0")]
2772 impl<'a
> From
<String
> for Cow
<'a
, str> {
2773 /// Converts a [`String`] into an [`Owned`] variant.
2774 /// No heap allocation is performed, and the string
2780 /// # use std::borrow::Cow;
2781 /// let s = "eggplant".to_string();
2782 /// let s2 = "eggplant".to_string();
2783 /// assert_eq!(Cow::from(s), Cow::<'static, str>::Owned(s2));
2786 /// [`Owned`]: crate::borrow::Cow::Owned "borrow::Cow::Owned"
2788 fn from(s
: String
) -> Cow
<'a
, str> {
2793 #[cfg(not(no_global_oom_handling))]
2794 #[stable(feature = "cow_from_string_ref", since = "1.28.0")]
2795 impl<'a
> From
<&'a String
> for Cow
<'a
, str> {
2796 /// Converts a [`String`] reference into a [`Borrowed`] variant.
2797 /// No heap allocation is performed, and the string
2803 /// # use std::borrow::Cow;
2804 /// let s = "eggplant".to_string();
2805 /// assert_eq!(Cow::from(&s), Cow::Borrowed("eggplant"));
2808 /// [`Borrowed`]: crate::borrow::Cow::Borrowed "borrow::Cow::Borrowed"
2810 fn from(s
: &'a String
) -> Cow
<'a
, str> {
2811 Cow
::Borrowed(s
.as_str())
2815 #[cfg(not(no_global_oom_handling))]
2816 #[stable(feature = "cow_str_from_iter", since = "1.12.0")]
2817 impl<'a
> FromIterator
<char> for Cow
<'a
, str> {
2818 fn from_iter
<I
: IntoIterator
<Item
= char>>(it
: I
) -> Cow
<'a
, str> {
2819 Cow
::Owned(FromIterator
::from_iter(it
))
2823 #[cfg(not(no_global_oom_handling))]
2824 #[stable(feature = "cow_str_from_iter", since = "1.12.0")]
2825 impl<'a
, 'b
> FromIterator
<&'b
str> for Cow
<'a
, str> {
2826 fn from_iter
<I
: IntoIterator
<Item
= &'b
str>>(it
: I
) -> Cow
<'a
, str> {
2827 Cow
::Owned(FromIterator
::from_iter(it
))
2831 #[cfg(not(no_global_oom_handling))]
2832 #[stable(feature = "cow_str_from_iter", since = "1.12.0")]
2833 impl<'a
> FromIterator
<String
> for Cow
<'a
, str> {
2834 fn from_iter
<I
: IntoIterator
<Item
= String
>>(it
: I
) -> Cow
<'a
, str> {
2835 Cow
::Owned(FromIterator
::from_iter(it
))
2839 #[stable(feature = "from_string_for_vec_u8", since = "1.14.0")]
2840 impl From
<String
> for Vec
<u8> {
2841 /// Converts the given [`String`] to a vector [`Vec`] that holds values of type [`u8`].
2848 /// let s1 = String::from("hello world");
2849 /// let v1 = Vec::from(s1);
2852 /// println!("{b}");
2855 fn from(string
: String
) -> Vec
<u8> {
2860 #[cfg(not(no_global_oom_handling))]
2861 #[stable(feature = "rust1", since = "1.0.0")]
2862 impl fmt
::Write
for String
{
2864 fn write_str(&mut self, s
: &str) -> fmt
::Result
{
2870 fn write_char(&mut self, c
: char) -> fmt
::Result
{
2876 /// A draining iterator for `String`.
2878 /// This struct is created by the [`drain`] method on [`String`]. See its
2879 /// documentation for more.
2881 /// [`drain`]: String::drain
2882 #[stable(feature = "drain", since = "1.6.0")]
2883 pub struct Drain
<'a
> {
2884 /// Will be used as &'a mut String in the destructor
2885 string
: *mut String
,
2886 /// Start of part to remove
2888 /// End of part to remove
2890 /// Current remaining range to remove
2894 #[stable(feature = "collection_debug", since = "1.17.0")]
2895 impl fmt
::Debug
for Drain
<'_
> {
2896 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
2897 f
.debug_tuple("Drain").field(&self.as_str()).finish()
2901 #[stable(feature = "drain", since = "1.6.0")]
2902 unsafe impl Sync
for Drain
<'_
> {}
2903 #[stable(feature = "drain", since = "1.6.0")]
2904 unsafe impl Send
for Drain
<'_
> {}
2906 #[stable(feature = "drain", since = "1.6.0")]
2907 impl Drop
for Drain
<'_
> {
2908 fn drop(&mut self) {
2910 // Use Vec::drain. "Reaffirm" the bounds checks to avoid
2911 // panic code being inserted again.
2912 let self_vec
= (*self.string
).as_mut_vec();
2913 if self.start
<= self.end
&& self.end
<= self_vec
.len() {
2914 self_vec
.drain(self.start
..self.end
);
2920 impl<'a
> Drain
<'a
> {
2921 /// Returns the remaining (sub)string of this iterator as a slice.
2926 /// let mut s = String::from("abc");
2927 /// let mut drain = s.drain(..);
2928 /// assert_eq!(drain.as_str(), "abc");
2929 /// let _ = drain.next().unwrap();
2930 /// assert_eq!(drain.as_str(), "bc");
2933 #[stable(feature = "string_drain_as_str", since = "1.55.0")]
2934 pub fn as_str(&self) -> &str {
2939 #[stable(feature = "string_drain_as_str", since = "1.55.0")]
2940 impl<'a
> AsRef
<str> for Drain
<'a
> {
2941 fn as_ref(&self) -> &str {
2946 #[stable(feature = "string_drain_as_str", since = "1.55.0")]
2947 impl<'a
> AsRef
<[u8]> for Drain
<'a
> {
2948 fn as_ref(&self) -> &[u8] {
2949 self.as_str().as_bytes()
2953 #[stable(feature = "drain", since = "1.6.0")]
2954 impl Iterator
for Drain
<'_
> {
2958 fn next(&mut self) -> Option
<char> {
2962 fn size_hint(&self) -> (usize, Option
<usize>) {
2963 self.iter
.size_hint()
2967 fn last(mut self) -> Option
<char> {
2972 #[stable(feature = "drain", since = "1.6.0")]
2973 impl DoubleEndedIterator
for Drain
<'_
> {
2975 fn next_back(&mut self) -> Option
<char> {
2976 self.iter
.next_back()
2980 #[stable(feature = "fused", since = "1.26.0")]
2981 impl FusedIterator
for Drain
<'_
> {}
2983 #[cfg(not(no_global_oom_handling))]
2984 #[stable(feature = "from_char_for_string", since = "1.46.0")]
2985 impl From
<char> for String
{
2986 /// Allocates an owned [`String`] from a single character.
2990 /// let c: char = 'a';
2991 /// let s: String = String::from(c);
2992 /// assert_eq!("a", &s[..]);
2995 fn from(c
: char) -> Self {