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