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