]>
Commit | Line | Data |
---|---|---|
1a4d82fc JJ |
1 | // Copyright 2014 The Rust Project Developers. See the COPYRIGHT |
2 | // file at the top-level directory of this distribution and at | |
3 | // http://rust-lang.org/COPYRIGHT. | |
4 | // | |
5 | // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or | |
6 | // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license | |
7 | // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your | |
8 | // option. This file may not be copied, modified, or distributed | |
9 | // except according to those terms. | |
1a4d82fc | 10 | |
92a42be0 SL |
11 | //! A UTF-8 encoded, growable string. |
12 | //! | |
13 | //! This module contains the [`String`] type, a trait for converting | |
14 | //! [`ToString`]s, and several error types that may result from working with | |
15 | //! [`String`]s. | |
16 | //! | |
92a42be0 | 17 | //! [`ToString`]: trait.ToString.html |
9cc50fc6 SL |
18 | //! |
19 | //! # Examples | |
20 | //! | |
c30ab7b3 | 21 | //! There are multiple ways to create a new [`String`] from a string literal: |
9cc50fc6 | 22 | //! |
c30ab7b3 | 23 | //! ``` |
9cc50fc6 SL |
24 | //! let s = "Hello".to_string(); |
25 | //! | |
26 | //! let s = String::from("world"); | |
27 | //! let s: String = "also this".into(); | |
28 | //! ``` | |
29 | //! | |
c30ab7b3 | 30 | //! You can create a new [`String`] from an existing one by concatenating with |
9cc50fc6 SL |
31 | //! `+`: |
32 | //! | |
c30ab7b3 SL |
33 | //! [`String`]: struct.String.html |
34 | //! | |
35 | //! ``` | |
9cc50fc6 SL |
36 | //! let s = "Hello".to_string(); |
37 | //! | |
38 | //! let message = s + " world!"; | |
39 | //! ``` | |
40 | //! | |
41 | //! If you have a vector of valid UTF-8 bytes, you can make a `String` out of | |
42 | //! it. You can do the reverse too. | |
43 | //! | |
c30ab7b3 | 44 | //! ``` |
9cc50fc6 SL |
45 | //! let sparkle_heart = vec![240, 159, 146, 150]; |
46 | //! | |
47 | //! // We know these bytes are valid, so we'll use `unwrap()`. | |
48 | //! let sparkle_heart = String::from_utf8(sparkle_heart).unwrap(); | |
49 | //! | |
50 | //! assert_eq!("💖", sparkle_heart); | |
51 | //! | |
52 | //! let bytes = sparkle_heart.into_bytes(); | |
53 | //! | |
54 | //! assert_eq!(bytes, [240, 159, 146, 150]); | |
55 | //! ``` | |
1a4d82fc | 56 | |
85aaf69f | 57 | #![stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 58 | |
1a4d82fc JJ |
59 | use core::fmt; |
60 | use core::hash; | |
9e0c209e | 61 | use core::iter::{FromIterator, FusedIterator}; |
1a4d82fc | 62 | use core::mem; |
5bcae85e | 63 | use core::ops::{self, Add, AddAssign, Index, IndexMut}; |
1a4d82fc | 64 | use core::ptr; |
8bb4bdeb | 65 | use core::str as core_str; |
9346a6ac | 66 | use core::str::pattern::Pattern; |
476ff2be | 67 | use std_unicode::char::{decode_utf16, REPLACEMENT_CHARACTER}; |
1a4d82fc | 68 | |
54a0048b | 69 | use borrow::{Cow, ToOwned}; |
d9579d0f | 70 | use range::RangeArgument; |
32a655c1 | 71 | use Bound::{Excluded, Included, Unbounded}; |
d9579d0f | 72 | use str::{self, FromStr, Utf8Error, Chars}; |
c1a9b12d SL |
73 | use vec::Vec; |
74 | use boxed::Box; | |
1a4d82fc | 75 | |
92a42be0 SL |
76 | /// A UTF-8 encoded, growable string. |
77 | /// | |
78 | /// The `String` type is the most common string type that has ownership over the | |
79 | /// contents of the string. It has a close relationship with its borrowed | |
80 | /// counterpart, the primitive [`str`]. | |
81 | /// | |
54a0048b | 82 | /// [`str`]: ../../std/primitive.str.html |
92a42be0 SL |
83 | /// |
84 | /// # Examples | |
85 | /// | |
86 | /// You can create a `String` from a literal string with `String::from`: | |
87 | /// | |
88 | /// ``` | |
89 | /// let hello = String::from("Hello, world!"); | |
90 | /// ``` | |
91 | /// | |
92 | /// You can append a [`char`] to a `String` with the [`push()`] method, and | |
93 | /// append a [`&str`] with the [`push_str()`] method: | |
94 | /// | |
95 | /// ``` | |
96 | /// let mut hello = String::from("Hello, "); | |
97 | /// | |
98 | /// hello.push('w'); | |
99 | /// hello.push_str("orld!"); | |
100 | /// ``` | |
101 | /// | |
54a0048b | 102 | /// [`char`]: ../../std/primitive.char.html |
92a42be0 SL |
103 | /// [`push()`]: #method.push |
104 | /// [`push_str()`]: #method.push_str | |
105 | /// | |
106 | /// If you have a vector of UTF-8 bytes, you can create a `String` from it with | |
107 | /// the [`from_utf8()`] method: | |
108 | /// | |
109 | /// ``` | |
110 | /// // some bytes, in a vector | |
111 | /// let sparkle_heart = vec![240, 159, 146, 150]; | |
112 | /// | |
113 | /// // We know these bytes are valid, so we'll use `unwrap()`. | |
114 | /// let sparkle_heart = String::from_utf8(sparkle_heart).unwrap(); | |
115 | /// | |
116 | /// assert_eq!("💖", sparkle_heart); | |
117 | /// ``` | |
118 | /// | |
119 | /// [`from_utf8()`]: #method.from_utf8 | |
120 | /// | |
121 | /// # UTF-8 | |
122 | /// | |
123 | /// `String`s are always valid UTF-8. This has a few implications, the first of | |
124 | /// which is that if you need a non-UTF-8 string, consider [`OsString`]. It is | |
125 | /// similar, but without the UTF-8 constraint. The second implication is that | |
126 | /// you cannot index into a `String`: | |
127 | /// | |
128 | /// ```ignore | |
129 | /// let s = "hello"; | |
130 | /// | |
131 | /// println!("The first letter of s is {}", s[0]); // ERROR!!! | |
132 | /// ``` | |
133 | /// | |
54a0048b | 134 | /// [`OsString`]: ../../std/ffi/struct.OsString.html |
92a42be0 SL |
135 | /// |
136 | /// Indexing is intended to be a constant-time operation, but UTF-8 encoding | |
9e0c209e | 137 | /// does not allow us to do this. Furthermore, it's not clear what sort of |
92a42be0 | 138 | /// thing the index should return: a byte, a codepoint, or a grapheme cluster. |
c30ab7b3 | 139 | /// The [`bytes()`] and [`chars()`] methods return iterators over the first |
92a42be0 SL |
140 | /// two, respectively. |
141 | /// | |
c30ab7b3 | 142 | /// [`bytes()`]: #method.bytes |
92a42be0 SL |
143 | /// [`chars()`]: #method.chars |
144 | /// | |
145 | /// # Deref | |
146 | /// | |
147 | /// `String`s implement [`Deref`]`<Target=str>`, and so inherit all of [`str`]'s | |
148 | /// methods. In addition, this means that you can pass a `String` to any | |
149 | /// function which takes a [`&str`] by using an ampersand (`&`): | |
150 | /// | |
151 | /// ``` | |
152 | /// fn takes_str(s: &str) { } | |
153 | /// | |
154 | /// let s = String::from("Hello"); | |
155 | /// | |
156 | /// takes_str(&s); | |
157 | /// ``` | |
158 | /// | |
54a0048b SL |
159 | /// [`&str`]: ../../std/primitive.str.html |
160 | /// [`Deref`]: ../../std/ops/trait.Deref.html | |
92a42be0 SL |
161 | /// |
162 | /// This will create a [`&str`] from the `String` and pass it in. This | |
163 | /// conversion is very inexpensive, and so generally, functions will accept | |
164 | /// [`&str`]s as arguments unless they need a `String` for some specific reason. | |
165 | /// | |
166 | /// | |
167 | /// # Representation | |
168 | /// | |
169 | /// A `String` is made up of three components: a pointer to some bytes, a | |
170 | /// length, and a capacity. The pointer points to an internal buffer `String` | |
171 | /// uses to store its data. The length is the number of bytes currently stored | |
172 | /// in the buffer, and the capacity is the size of the buffer in bytes. As such, | |
173 | /// the length will always be less than or equal to the capacity. | |
174 | /// | |
175 | /// This buffer is always stored on the heap. | |
176 | /// | |
177 | /// You can look at these with the [`as_ptr()`], [`len()`], and [`capacity()`] | |
178 | /// methods: | |
179 | /// | |
180 | /// ``` | |
181 | /// use std::mem; | |
182 | /// | |
183 | /// let story = String::from("Once upon a time..."); | |
184 | /// | |
185 | /// let ptr = story.as_ptr(); | |
186 | /// let len = story.len(); | |
187 | /// let capacity = story.capacity(); | |
188 | /// | |
a7813a04 | 189 | /// // story has nineteen bytes |
92a42be0 SL |
190 | /// assert_eq!(19, len); |
191 | /// | |
192 | /// // Now that we have our parts, we throw the story away. | |
193 | /// mem::forget(story); | |
194 | /// | |
195 | /// // We can re-build a String out of ptr, len, and capacity. This is all | |
7453a54e | 196 | /// // unsafe because we are responsible for making sure the components are |
92a42be0 SL |
197 | /// // valid: |
198 | /// let s = unsafe { String::from_raw_parts(ptr as *mut _, len, capacity) } ; | |
199 | /// | |
200 | /// assert_eq!(String::from("Once upon a time..."), s); | |
201 | /// ``` | |
202 | /// | |
203 | /// [`as_ptr()`]: #method.as_ptr | |
9cc50fc6 SL |
204 | /// [`len()`]: #method.len |
205 | /// [`capacity()`]: #method.capacity | |
92a42be0 SL |
206 | /// |
207 | /// If a `String` has enough capacity, adding elements to it will not | |
208 | /// re-allocate. For example, consider this program: | |
209 | /// | |
210 | /// ``` | |
211 | /// let mut s = String::new(); | |
212 | /// | |
213 | /// println!("{}", s.capacity()); | |
214 | /// | |
215 | /// for _ in 0..5 { | |
216 | /// s.push_str("hello"); | |
217 | /// println!("{}", s.capacity()); | |
218 | /// } | |
219 | /// ``` | |
220 | /// | |
221 | /// This will output the following: | |
222 | /// | |
223 | /// ```text | |
224 | /// 0 | |
225 | /// 5 | |
226 | /// 10 | |
227 | /// 20 | |
228 | /// 20 | |
229 | /// 40 | |
230 | /// ``` | |
231 | /// | |
232 | /// At first, we have no memory allocated at all, but as we append to the | |
233 | /// string, it increases its capacity appropriately. If we instead use the | |
234 | /// [`with_capacity()`] method to allocate the correct capacity initially: | |
235 | /// | |
236 | /// ``` | |
237 | /// let mut s = String::with_capacity(25); | |
238 | /// | |
239 | /// println!("{}", s.capacity()); | |
240 | /// | |
241 | /// for _ in 0..5 { | |
242 | /// s.push_str("hello"); | |
243 | /// println!("{}", s.capacity()); | |
244 | /// } | |
245 | /// ``` | |
246 | /// | |
247 | /// [`with_capacity()`]: #method.with_capacity | |
248 | /// | |
249 | /// We end up with a different output: | |
250 | /// | |
251 | /// ```text | |
252 | /// 25 | |
253 | /// 25 | |
254 | /// 25 | |
255 | /// 25 | |
256 | /// 25 | |
257 | /// 25 | |
258 | /// ``` | |
259 | /// | |
260 | /// Here, there's no need to allocate more memory inside the loop. | |
b039eaaf | 261 | #[derive(PartialOrd, Eq, Ord)] |
85aaf69f | 262 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
263 | pub struct String { |
264 | vec: Vec<u8>, | |
265 | } | |
266 | ||
92a42be0 SL |
267 | /// A possible error value when converting a `String` from a UTF-8 byte vector. |
268 | /// | |
269 | /// This type is the error type for the [`from_utf8()`] method on [`String`]. It | |
270 | /// is designed in such a way to carefully avoid reallocations: the | |
271 | /// [`into_bytes()`] method will give back the byte vector that was used in the | |
272 | /// conversion attempt. | |
273 | /// | |
274 | /// [`from_utf8()`]: struct.String.html#method.from_utf8 | |
275 | /// [`String`]: struct.String.html | |
276 | /// [`into_bytes()`]: struct.FromUtf8Error.html#method.into_bytes | |
277 | /// | |
278 | /// The [`Utf8Error`] type provided by [`std::str`] represents an error that may | |
279 | /// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's | |
280 | /// an analogue to `FromUtf8Error`, and you can get one from a `FromUtf8Error` | |
281 | /// through the [`utf8_error()`] method. | |
282 | /// | |
54a0048b SL |
283 | /// [`Utf8Error`]: ../../std/str/struct.Utf8Error.html |
284 | /// [`std::str`]: ../../std/str/index.html | |
285 | /// [`u8`]: ../../std/primitive.u8.html | |
286 | /// [`&str`]: ../../std/primitive.str.html | |
92a42be0 SL |
287 | /// [`utf8_error()`]: #method.utf8_error |
288 | /// | |
289 | /// # Examples | |
290 | /// | |
291 | /// Basic usage: | |
292 | /// | |
293 | /// ``` | |
294 | /// // some invalid bytes, in a vector | |
295 | /// let bytes = vec![0, 159]; | |
296 | /// | |
297 | /// let value = String::from_utf8(bytes); | |
298 | /// | |
299 | /// assert!(value.is_err()); | |
300 | /// assert_eq!(vec![0, 159], value.unwrap_err().into_bytes()); | |
301 | /// ``` | |
85aaf69f SL |
302 | #[stable(feature = "rust1", since = "1.0.0")] |
303 | #[derive(Debug)] | |
1a4d82fc JJ |
304 | pub struct FromUtf8Error { |
305 | bytes: Vec<u8>, | |
306 | error: Utf8Error, | |
307 | } | |
308 | ||
92a42be0 SL |
309 | /// A possible error value when converting a `String` from a UTF-16 byte slice. |
310 | /// | |
311 | /// This type is the error type for the [`from_utf16()`] method on [`String`]. | |
312 | /// | |
313 | /// [`from_utf16()`]: struct.String.html#method.from_utf16 | |
314 | /// [`String`]: struct.String.html | |
315 | /// | |
316 | /// # Examples | |
317 | /// | |
318 | /// Basic usage: | |
319 | /// | |
320 | /// ``` | |
321 | /// // 𝄞mu<invalid>ic | |
322 | /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075, | |
323 | /// 0xD800, 0x0069, 0x0063]; | |
324 | /// | |
325 | /// assert!(String::from_utf16(v).is_err()); | |
326 | /// ``` | |
85aaf69f SL |
327 | #[stable(feature = "rust1", since = "1.0.0")] |
328 | #[derive(Debug)] | |
1a4d82fc JJ |
329 | pub struct FromUtf16Error(()); |
330 | ||
331 | impl String { | |
9cc50fc6 SL |
332 | /// Creates a new empty `String`. |
333 | /// | |
334 | /// Given that the `String` is empty, this will not allocate any initial | |
335 | /// buffer. While that means that this initial operation is very | |
336 | /// inexpensive, but may cause excessive allocation later, when you add | |
337 | /// data. If you have an idea of how much data the `String` will hold, | |
338 | /// consider the [`with_capacity()`] method to prevent excessive | |
339 | /// re-allocation. | |
340 | /// | |
341 | /// [`with_capacity()`]: #method.with_capacity | |
1a4d82fc JJ |
342 | /// |
343 | /// # Examples | |
344 | /// | |
9cc50fc6 SL |
345 | /// Basic usage: |
346 | /// | |
1a4d82fc | 347 | /// ``` |
9cc50fc6 | 348 | /// let s = String::new(); |
1a4d82fc JJ |
349 | /// ``` |
350 | #[inline] | |
85aaf69f | 351 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 352 | pub fn new() -> String { |
92a42be0 | 353 | String { vec: Vec::new() } |
1a4d82fc JJ |
354 | } |
355 | ||
9cc50fc6 SL |
356 | /// Creates a new empty `String` with a particular capacity. |
357 | /// | |
358 | /// `String`s have an internal buffer to hold their data. The capacity is | |
359 | /// the length of that buffer, and can be queried with the [`capacity()`] | |
360 | /// method. This method creates an empty `String`, but one with an initial | |
361 | /// buffer that can hold `capacity` bytes. This is useful when you may be | |
362 | /// appending a bunch of data to the `String`, reducing the number of | |
363 | /// reallocations it needs to do. | |
364 | /// | |
365 | /// [`capacity()`]: #method.capacity | |
366 | /// | |
367 | /// If the given capacity is `0`, no allocation will occur, and this method | |
368 | /// is identical to the [`new()`] method. | |
369 | /// | |
370 | /// [`new()`]: #method.new | |
1a4d82fc JJ |
371 | /// |
372 | /// # Examples | |
373 | /// | |
9cc50fc6 SL |
374 | /// Basic usage: |
375 | /// | |
1a4d82fc JJ |
376 | /// ``` |
377 | /// let mut s = String::with_capacity(10); | |
92a42be0 SL |
378 | /// |
379 | /// // The String contains no chars, even though it has capacity for more | |
380 | /// assert_eq!(s.len(), 0); | |
381 | /// | |
382 | /// // These are all done without reallocating... | |
383 | /// let cap = s.capacity(); | |
384 | /// for i in 0..10 { | |
385 | /// s.push('a'); | |
386 | /// } | |
387 | /// | |
388 | /// assert_eq!(s.capacity(), cap); | |
389 | /// | |
390 | /// // ...but this may make the vector reallocate | |
391 | /// s.push('a'); | |
1a4d82fc JJ |
392 | /// ``` |
393 | #[inline] | |
85aaf69f SL |
394 | #[stable(feature = "rust1", since = "1.0.0")] |
395 | pub fn with_capacity(capacity: usize) -> String { | |
92a42be0 | 396 | String { vec: Vec::with_capacity(capacity) } |
1a4d82fc JJ |
397 | } |
398 | ||
c34b1796 AL |
399 | // HACK(japaric): with cfg(test) the inherent `[T]::to_vec` method, which is |
400 | // required for this method definition, is not available. Since we don't | |
401 | // require this method for testing purposes, I'll just stub it | |
402 | // NB see the slice::hack module in slice.rs for more information | |
403 | #[inline] | |
404 | #[cfg(test)] | |
405 | pub fn from_str(_: &str) -> String { | |
406 | panic!("not available with cfg(test)"); | |
1a4d82fc JJ |
407 | } |
408 | ||
b039eaaf SL |
409 | /// Converts a vector of bytes to a `String`. |
410 | /// | |
9cc50fc6 SL |
411 | /// A string slice ([`&str`]) is made of bytes ([`u8`]), and a vector of bytes |
412 | /// ([`Vec<u8>`]) is made of bytes, so this function converts between the | |
b039eaaf SL |
413 | /// two. Not all byte slices are valid `String`s, however: `String` |
414 | /// requires that it is valid UTF-8. `from_utf8()` checks to ensure that | |
415 | /// the bytes are valid UTF-8, and then does the conversion. | |
416 | /// | |
54a0048b SL |
417 | /// [`&str`]: ../../std/primitive.str.html |
418 | /// [`u8`]: ../../std/primitive.u8.html | |
419 | /// [`Vec<u8>`]: ../../std/vec/struct.Vec.html | |
9cc50fc6 | 420 | /// |
b039eaaf SL |
421 | /// If you are sure that the byte slice is valid UTF-8, and you don't want |
422 | /// to incur the overhead of the validity check, there is an unsafe version | |
9cc50fc6 SL |
423 | /// of this function, [`from_utf8_unchecked()`], which has the same behavior |
424 | /// but skips the check. | |
b039eaaf | 425 | /// |
9cc50fc6 | 426 | /// [`from_utf8_unchecked()`]: struct.String.html#method.from_utf8_unchecked |
b039eaaf SL |
427 | /// |
428 | /// This method will take care to not copy the vector, for efficiency's | |
429 | /// sake. | |
430 | /// | |
431 | /// If you need a `&str` instead of a `String`, consider | |
9cc50fc6 | 432 | /// [`str::from_utf8()`]. |
b039eaaf | 433 | /// |
54a0048b | 434 | /// [`str::from_utf8()`]: ../../std/str/fn.from_utf8.html |
1a4d82fc | 435 | /// |
8bb4bdeb XL |
436 | /// The inverse of this method is [`as_bytes`]. |
437 | /// | |
438 | /// [`as_bytes`]: #method.as_bytes | |
439 | /// | |
7453a54e | 440 | /// # Errors |
1a4d82fc | 441 | /// |
b039eaaf SL |
442 | /// Returns `Err` if the slice is not UTF-8 with a description as to why the |
443 | /// provided bytes are not UTF-8. The vector you moved in is also included. | |
1a4d82fc JJ |
444 | /// |
445 | /// # Examples | |
446 | /// | |
b039eaaf SL |
447 | /// Basic usage: |
448 | /// | |
c34b1796 | 449 | /// ``` |
b039eaaf SL |
450 | /// // some bytes, in a vector |
451 | /// let sparkle_heart = vec![240, 159, 146, 150]; | |
452 | /// | |
92a42be0 | 453 | /// // We know these bytes are valid, so we'll use `unwrap()`. |
b039eaaf SL |
454 | /// let sparkle_heart = String::from_utf8(sparkle_heart).unwrap(); |
455 | /// | |
456 | /// assert_eq!("💖", sparkle_heart); | |
457 | /// ``` | |
458 | /// | |
459 | /// Incorrect bytes: | |
460 | /// | |
1a4d82fc | 461 | /// ``` |
b039eaaf SL |
462 | /// // some invalid bytes, in a vector |
463 | /// let sparkle_heart = vec![0, 159, 146, 150]; | |
464 | /// | |
465 | /// assert!(String::from_utf8(sparkle_heart).is_err()); | |
466 | /// ``` | |
467 | /// | |
9cc50fc6 SL |
468 | /// See the docs for [`FromUtf8Error`] for more details on what you can do |
469 | /// with this error. | |
b039eaaf | 470 | /// |
9cc50fc6 | 471 | /// [`FromUtf8Error`]: struct.FromUtf8Error.html |
1a4d82fc | 472 | #[inline] |
85aaf69f | 473 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 474 | pub fn from_utf8(vec: Vec<u8>) -> Result<String, FromUtf8Error> { |
85aaf69f | 475 | match str::from_utf8(&vec) { |
1a4d82fc | 476 | Ok(..) => Ok(String { vec: vec }), |
92a42be0 SL |
477 | Err(e) => { |
478 | Err(FromUtf8Error { | |
479 | bytes: vec, | |
480 | error: e, | |
481 | }) | |
482 | } | |
1a4d82fc JJ |
483 | } |
484 | } | |
485 | ||
7453a54e | 486 | /// Converts a slice of bytes to a string, including invalid characters. |
b039eaaf | 487 | /// |
7453a54e SL |
488 | /// Strings are made of bytes ([`u8`]), and a slice of bytes |
489 | /// ([`&[u8]`][byteslice]) is made of bytes, so this function converts | |
490 | /// between the two. Not all byte slices are valid strings, however: strings | |
491 | /// are required to be valid UTF-8. During this conversion, | |
9cc50fc6 | 492 | /// `from_utf8_lossy()` will replace any invalid UTF-8 sequences with |
b039eaaf SL |
493 | /// `U+FFFD REPLACEMENT CHARACTER`, which looks like this: � |
494 | /// | |
54a0048b SL |
495 | /// [`u8`]: ../../std/primitive.u8.html |
496 | /// [byteslice]: ../../std/primitive.slice.html | |
9cc50fc6 | 497 | /// |
b039eaaf SL |
498 | /// If you are sure that the byte slice is valid UTF-8, and you don't want |
499 | /// to incur the overhead of the conversion, there is an unsafe version | |
9cc50fc6 SL |
500 | /// of this function, [`from_utf8_unchecked()`], which has the same behavior |
501 | /// but skips the checks. | |
b039eaaf | 502 | /// |
9cc50fc6 | 503 | /// [`from_utf8_unchecked()`]: struct.String.html#method.from_utf8_unchecked |
b039eaaf | 504 | /// |
7453a54e SL |
505 | /// This function returns a [`Cow<'a, str>`]. If our byte slice is invalid |
506 | /// UTF-8, then we need to insert the replacement characters, which will | |
507 | /// change the size of the string, and hence, require a `String`. But if | |
508 | /// it's already valid UTF-8, we don't need a new allocation. This return | |
509 | /// type allows us to handle both cases. | |
b039eaaf | 510 | /// |
54a0048b | 511 | /// [`Cow<'a, str>`]: ../../std/borrow/enum.Cow.html |
1a4d82fc JJ |
512 | /// |
513 | /// # Examples | |
514 | /// | |
b039eaaf SL |
515 | /// Basic usage: |
516 | /// | |
c34b1796 | 517 | /// ``` |
b039eaaf SL |
518 | /// // some bytes, in a vector |
519 | /// let sparkle_heart = vec![240, 159, 146, 150]; | |
520 | /// | |
7453a54e | 521 | /// let sparkle_heart = String::from_utf8_lossy(&sparkle_heart); |
b039eaaf SL |
522 | /// |
523 | /// assert_eq!("💖", sparkle_heart); | |
524 | /// ``` | |
525 | /// | |
526 | /// Incorrect bytes: | |
527 | /// | |
528 | /// ``` | |
529 | /// // some invalid bytes | |
1a4d82fc JJ |
530 | /// let input = b"Hello \xF0\x90\x80World"; |
531 | /// let output = String::from_utf8_lossy(input); | |
b039eaaf SL |
532 | /// |
533 | /// assert_eq!("Hello �World", output); | |
1a4d82fc | 534 | /// ``` |
85aaf69f SL |
535 | #[stable(feature = "rust1", since = "1.0.0")] |
536 | pub fn from_utf8_lossy<'a>(v: &'a [u8]) -> Cow<'a, str> { | |
9346a6ac | 537 | let mut i; |
1a4d82fc JJ |
538 | match str::from_utf8(v) { |
539 | Ok(s) => return Cow::Borrowed(s), | |
9346a6ac | 540 | Err(e) => i = e.valid_up_to(), |
1a4d82fc JJ |
541 | } |
542 | ||
c34b1796 AL |
543 | const TAG_CONT_U8: u8 = 128; |
544 | const REPLACEMENT: &'static [u8] = b"\xEF\xBF\xBD"; // U+FFFD in UTF-8 | |
1a4d82fc | 545 | let total = v.len(); |
85aaf69f | 546 | fn unsafe_get(xs: &[u8], i: usize) -> u8 { |
1a4d82fc JJ |
547 | unsafe { *xs.get_unchecked(i) } |
548 | } | |
85aaf69f | 549 | fn safe_get(xs: &[u8], i: usize, total: usize) -> u8 { |
32a655c1 | 550 | if i >= total { 0 } else { unsafe_get(xs, i) } |
1a4d82fc JJ |
551 | } |
552 | ||
553 | let mut res = String::with_capacity(total); | |
554 | ||
555 | if i > 0 { | |
92a42be0 | 556 | unsafe { res.as_mut_vec().extend_from_slice(&v[..i]) }; |
1a4d82fc JJ |
557 | } |
558 | ||
9346a6ac AL |
559 | // subseqidx is the index of the first byte of the subsequence we're |
560 | // looking at. It's used to copy a bunch of contiguous good codepoints | |
561 | // at once instead of copying them one by one. | |
1a4d82fc JJ |
562 | let mut subseqidx = i; |
563 | ||
564 | while i < total { | |
565 | let i_ = i; | |
566 | let byte = unsafe_get(v, i); | |
567 | i += 1; | |
568 | ||
569 | macro_rules! error { () => ({ | |
570 | unsafe { | |
571 | if subseqidx != i_ { | |
92a42be0 | 572 | res.as_mut_vec().extend_from_slice(&v[subseqidx..i_]); |
1a4d82fc JJ |
573 | } |
574 | subseqidx = i; | |
92a42be0 | 575 | res.as_mut_vec().extend_from_slice(REPLACEMENT); |
1a4d82fc JJ |
576 | } |
577 | })} | |
578 | ||
c34b1796 | 579 | if byte < 128 { |
1a4d82fc JJ |
580 | // subseqidx handles this |
581 | } else { | |
8bb4bdeb | 582 | let w = core_str::utf8_char_width(byte); |
1a4d82fc JJ |
583 | |
584 | match w { | |
585 | 2 => { | |
c34b1796 | 586 | if safe_get(v, i, total) & 192 != TAG_CONT_U8 { |
1a4d82fc JJ |
587 | error!(); |
588 | continue; | |
589 | } | |
590 | i += 1; | |
591 | } | |
592 | 3 => { | |
593 | match (byte, safe_get(v, i, total)) { | |
92a42be0 SL |
594 | (0xE0, 0xA0...0xBF) => (), |
595 | (0xE1...0xEC, 0x80...0xBF) => (), | |
596 | (0xED, 0x80...0x9F) => (), | |
597 | (0xEE...0xEF, 0x80...0xBF) => (), | |
1a4d82fc JJ |
598 | _ => { |
599 | error!(); | |
600 | continue; | |
601 | } | |
602 | } | |
603 | i += 1; | |
c34b1796 | 604 | if safe_get(v, i, total) & 192 != TAG_CONT_U8 { |
1a4d82fc JJ |
605 | error!(); |
606 | continue; | |
607 | } | |
608 | i += 1; | |
609 | } | |
610 | 4 => { | |
611 | match (byte, safe_get(v, i, total)) { | |
92a42be0 SL |
612 | (0xF0, 0x90...0xBF) => (), |
613 | (0xF1...0xF3, 0x80...0xBF) => (), | |
614 | (0xF4, 0x80...0x8F) => (), | |
1a4d82fc JJ |
615 | _ => { |
616 | error!(); | |
617 | continue; | |
618 | } | |
619 | } | |
620 | i += 1; | |
c34b1796 | 621 | if safe_get(v, i, total) & 192 != TAG_CONT_U8 { |
1a4d82fc JJ |
622 | error!(); |
623 | continue; | |
624 | } | |
625 | i += 1; | |
c34b1796 | 626 | if safe_get(v, i, total) & 192 != TAG_CONT_U8 { |
1a4d82fc JJ |
627 | error!(); |
628 | continue; | |
629 | } | |
630 | i += 1; | |
631 | } | |
632 | _ => { | |
633 | error!(); | |
634 | continue; | |
635 | } | |
636 | } | |
637 | } | |
638 | } | |
639 | if subseqidx < total { | |
92a42be0 | 640 | unsafe { res.as_mut_vec().extend_from_slice(&v[subseqidx..total]) }; |
1a4d82fc JJ |
641 | } |
642 | Cow::Owned(res) | |
643 | } | |
644 | ||
7453a54e | 645 | /// Decode a UTF-16 encoded vector `v` into a `String`, returning `Err` |
1a4d82fc JJ |
646 | /// if `v` contains any invalid data. |
647 | /// | |
648 | /// # Examples | |
649 | /// | |
9cc50fc6 SL |
650 | /// Basic usage: |
651 | /// | |
c34b1796 | 652 | /// ``` |
1a4d82fc | 653 | /// // 𝄞music |
92a42be0 SL |
654 | /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075, |
655 | /// 0x0073, 0x0069, 0x0063]; | |
9cc50fc6 SL |
656 | /// assert_eq!(String::from("𝄞music"), |
657 | /// String::from_utf16(v).unwrap()); | |
1a4d82fc JJ |
658 | /// |
659 | /// // 𝄞mu<invalid>ic | |
92a42be0 SL |
660 | /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075, |
661 | /// 0xD800, 0x0069, 0x0063]; | |
1a4d82fc JJ |
662 | /// assert!(String::from_utf16(v).is_err()); |
663 | /// ``` | |
85aaf69f | 664 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 665 | pub fn from_utf16(v: &[u16]) -> Result<String, FromUtf16Error> { |
e9174d1e | 666 | decode_utf16(v.iter().cloned()).collect::<Result<_, _>>().map_err(|_| FromUtf16Error(())) |
1a4d82fc JJ |
667 | } |
668 | ||
669 | /// Decode a UTF-16 encoded vector `v` into a string, replacing | |
670 | /// invalid data with the replacement character (U+FFFD). | |
671 | /// | |
672 | /// # Examples | |
673 | /// | |
9cc50fc6 SL |
674 | /// Basic usage: |
675 | /// | |
c34b1796 | 676 | /// ``` |
1a4d82fc JJ |
677 | /// // 𝄞mus<invalid>ic<invalid> |
678 | /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075, | |
679 | /// 0x0073, 0xDD1E, 0x0069, 0x0063, | |
680 | /// 0xD834]; | |
681 | /// | |
9cc50fc6 SL |
682 | /// assert_eq!(String::from("𝄞mus\u{FFFD}ic\u{FFFD}"), |
683 | /// String::from_utf16_lossy(v)); | |
1a4d82fc | 684 | /// ``` |
85aaf69f SL |
685 | #[inline] |
686 | #[stable(feature = "rust1", since = "1.0.0")] | |
1a4d82fc | 687 | pub fn from_utf16_lossy(v: &[u16]) -> String { |
e9174d1e | 688 | decode_utf16(v.iter().cloned()).map(|r| r.unwrap_or(REPLACEMENT_CHARACTER)).collect() |
1a4d82fc JJ |
689 | } |
690 | ||
691 | /// Creates a new `String` from a length, capacity, and pointer. | |
692 | /// | |
b039eaaf | 693 | /// # Safety |
c1a9b12d | 694 | /// |
9cc50fc6 SL |
695 | /// This is highly unsafe, due to the number of invariants that aren't |
696 | /// checked: | |
697 | /// | |
698 | /// * The memory at `ptr` needs to have been previously allocated by the | |
699 | /// same allocator the standard library uses. | |
700 | /// * `length` needs to be less than or equal to `capacity`. | |
701 | /// * `capacity` needs to be the correct value. | |
702 | /// | |
703 | /// Violating these may cause problems like corrupting the allocator's | |
704 | /// internal datastructures. | |
705 | /// | |
5bcae85e SL |
706 | /// The ownership of `ptr` is effectively transferred to the |
707 | /// `String` which may then deallocate, reallocate or change the | |
708 | /// contents of memory pointed to by the pointer at will. Ensure | |
709 | /// that nothing else uses the pointer after calling this | |
710 | /// function. | |
711 | /// | |
9cc50fc6 SL |
712 | /// # Examples |
713 | /// | |
714 | /// Basic usage: | |
715 | /// | |
716 | /// ``` | |
717 | /// use std::mem; | |
718 | /// | |
719 | /// unsafe { | |
720 | /// let s = String::from("hello"); | |
721 | /// let ptr = s.as_ptr(); | |
722 | /// let len = s.len(); | |
723 | /// let capacity = s.capacity(); | |
724 | /// | |
725 | /// mem::forget(s); | |
726 | /// | |
727 | /// let s = String::from_raw_parts(ptr as *mut _, len, capacity); | |
c34b1796 | 728 | /// |
9cc50fc6 SL |
729 | /// assert_eq!(String::from("hello"), s); |
730 | /// } | |
731 | /// ``` | |
1a4d82fc | 732 | #[inline] |
85aaf69f SL |
733 | #[stable(feature = "rust1", since = "1.0.0")] |
734 | pub unsafe fn from_raw_parts(buf: *mut u8, length: usize, capacity: usize) -> String { | |
92a42be0 | 735 | String { vec: Vec::from_raw_parts(buf, length, capacity) } |
1a4d82fc JJ |
736 | } |
737 | ||
b039eaaf SL |
738 | /// Converts a vector of bytes to a `String` without checking that the |
739 | /// string contains valid UTF-8. | |
740 | /// | |
9cc50fc6 | 741 | /// See the safe version, [`from_utf8()`], for more details. |
b039eaaf | 742 | /// |
9cc50fc6 | 743 | /// [`from_utf8()`]: struct.String.html#method.from_utf8 |
b039eaaf SL |
744 | /// |
745 | /// # Safety | |
746 | /// | |
9cc50fc6 SL |
747 | /// This function is unsafe because it does not check that the bytes passed |
748 | /// to it are valid UTF-8. If this constraint is violated, it may cause | |
749 | /// memory unsafety issues with future users of the `String`, as the rest of | |
750 | /// the standard library assumes that `String`s are valid UTF-8. | |
b039eaaf SL |
751 | /// |
752 | /// # Examples | |
753 | /// | |
754 | /// Basic usage: | |
755 | /// | |
756 | /// ``` | |
757 | /// // some bytes, in a vector | |
758 | /// let sparkle_heart = vec![240, 159, 146, 150]; | |
759 | /// | |
760 | /// let sparkle_heart = unsafe { | |
761 | /// String::from_utf8_unchecked(sparkle_heart) | |
762 | /// }; | |
763 | /// | |
764 | /// assert_eq!("💖", sparkle_heart); | |
765 | /// ``` | |
1a4d82fc | 766 | #[inline] |
85aaf69f | 767 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
768 | pub unsafe fn from_utf8_unchecked(bytes: Vec<u8>) -> String { |
769 | String { vec: bytes } | |
770 | } | |
771 | ||
9cc50fc6 SL |
772 | /// Converts a `String` into a byte vector. |
773 | /// | |
774 | /// This consumes the `String`, so we do not need to copy its contents. | |
1a4d82fc JJ |
775 | /// |
776 | /// # Examples | |
777 | /// | |
9cc50fc6 SL |
778 | /// Basic usage: |
779 | /// | |
1a4d82fc | 780 | /// ``` |
62682a34 | 781 | /// let s = String::from("hello"); |
1a4d82fc | 782 | /// let bytes = s.into_bytes(); |
9cc50fc6 SL |
783 | /// |
784 | /// assert_eq!(&[104, 101, 108, 108, 111][..], &bytes[..]); | |
1a4d82fc JJ |
785 | /// ``` |
786 | #[inline] | |
85aaf69f | 787 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
788 | pub fn into_bytes(self) -> Vec<u8> { |
789 | self.vec | |
790 | } | |
791 | ||
9346a6ac | 792 | /// Extracts a string slice containing the entire string. |
c34b1796 | 793 | #[inline] |
9cc50fc6 | 794 | #[stable(feature = "string_as_str", since = "1.7.0")] |
c34b1796 AL |
795 | pub fn as_str(&self) -> &str { |
796 | self | |
797 | } | |
798 | ||
9cc50fc6 SL |
799 | /// Extracts a string slice containing the entire string. |
800 | #[inline] | |
801 | #[stable(feature = "string_as_str", since = "1.7.0")] | |
802 | pub fn as_mut_str(&mut self) -> &mut str { | |
803 | self | |
804 | } | |
805 | ||
806 | /// Appends a given string slice onto the end of this `String`. | |
1a4d82fc JJ |
807 | /// |
808 | /// # Examples | |
809 | /// | |
9cc50fc6 SL |
810 | /// Basic usage: |
811 | /// | |
1a4d82fc | 812 | /// ``` |
62682a34 | 813 | /// let mut s = String::from("foo"); |
9cc50fc6 | 814 | /// |
1a4d82fc | 815 | /// s.push_str("bar"); |
9cc50fc6 SL |
816 | /// |
817 | /// assert_eq!("foobar", s); | |
1a4d82fc JJ |
818 | /// ``` |
819 | #[inline] | |
85aaf69f | 820 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 821 | pub fn push_str(&mut self, string: &str) { |
92a42be0 | 822 | self.vec.extend_from_slice(string.as_bytes()) |
1a4d82fc JJ |
823 | } |
824 | ||
9cc50fc6 | 825 | /// Returns this `String`'s capacity, in bytes. |
1a4d82fc JJ |
826 | /// |
827 | /// # Examples | |
828 | /// | |
9cc50fc6 SL |
829 | /// Basic usage: |
830 | /// | |
1a4d82fc JJ |
831 | /// ``` |
832 | /// let s = String::with_capacity(10); | |
9cc50fc6 | 833 | /// |
1a4d82fc JJ |
834 | /// assert!(s.capacity() >= 10); |
835 | /// ``` | |
836 | #[inline] | |
85aaf69f SL |
837 | #[stable(feature = "rust1", since = "1.0.0")] |
838 | pub fn capacity(&self) -> usize { | |
1a4d82fc JJ |
839 | self.vec.capacity() |
840 | } | |
841 | ||
9cc50fc6 SL |
842 | /// Ensures that this `String`'s capacity is at least `additional` bytes |
843 | /// larger than its length. | |
844 | /// | |
845 | /// The capacity may be increased by more than `additional` bytes if it | |
846 | /// chooses, to prevent frequent reallocations. | |
847 | /// | |
848 | /// If you do not want this "at least" behavior, see the [`reserve_exact()`] | |
849 | /// method. | |
850 | /// | |
851 | /// [`reserve_exact()`]: #method.reserve_exact | |
1a4d82fc JJ |
852 | /// |
853 | /// # Panics | |
854 | /// | |
85aaf69f | 855 | /// Panics if the new capacity overflows `usize`. |
1a4d82fc JJ |
856 | /// |
857 | /// # Examples | |
858 | /// | |
9cc50fc6 SL |
859 | /// Basic usage: |
860 | /// | |
1a4d82fc JJ |
861 | /// ``` |
862 | /// let mut s = String::new(); | |
9cc50fc6 | 863 | /// |
1a4d82fc | 864 | /// s.reserve(10); |
9cc50fc6 | 865 | /// |
1a4d82fc JJ |
866 | /// assert!(s.capacity() >= 10); |
867 | /// ``` | |
9cc50fc6 SL |
868 | /// |
869 | /// This may not actually increase the capacity: | |
870 | /// | |
871 | /// ``` | |
872 | /// let mut s = String::with_capacity(10); | |
873 | /// s.push('a'); | |
874 | /// s.push('b'); | |
875 | /// | |
876 | /// // s now has a length of 2 and a capacity of 10 | |
877 | /// assert_eq!(2, s.len()); | |
878 | /// assert_eq!(10, s.capacity()); | |
879 | /// | |
880 | /// // Since we already have an extra 8 capacity, calling this... | |
881 | /// s.reserve(8); | |
882 | /// | |
883 | /// // ... doesn't actually increase. | |
884 | /// assert_eq!(10, s.capacity()); | |
885 | /// ``` | |
1a4d82fc | 886 | #[inline] |
85aaf69f SL |
887 | #[stable(feature = "rust1", since = "1.0.0")] |
888 | pub fn reserve(&mut self, additional: usize) { | |
1a4d82fc JJ |
889 | self.vec.reserve(additional) |
890 | } | |
891 | ||
9cc50fc6 SL |
892 | /// Ensures that this `String`'s capacity is `additional` bytes |
893 | /// larger than its length. | |
1a4d82fc | 894 | /// |
9cc50fc6 SL |
895 | /// Consider using the [`reserve()`] method unless you absolutely know |
896 | /// better than the allocator. | |
897 | /// | |
898 | /// [`reserve()`]: #method.reserve | |
1a4d82fc JJ |
899 | /// |
900 | /// # Panics | |
901 | /// | |
85aaf69f | 902 | /// Panics if the new capacity overflows `usize`. |
1a4d82fc JJ |
903 | /// |
904 | /// # Examples | |
905 | /// | |
9cc50fc6 SL |
906 | /// Basic usage: |
907 | /// | |
1a4d82fc JJ |
908 | /// ``` |
909 | /// let mut s = String::new(); | |
9cc50fc6 | 910 | /// |
62682a34 | 911 | /// s.reserve_exact(10); |
9cc50fc6 | 912 | /// |
1a4d82fc JJ |
913 | /// assert!(s.capacity() >= 10); |
914 | /// ``` | |
9cc50fc6 SL |
915 | /// |
916 | /// This may not actually increase the capacity: | |
917 | /// | |
918 | /// ``` | |
919 | /// let mut s = String::with_capacity(10); | |
920 | /// s.push('a'); | |
921 | /// s.push('b'); | |
922 | /// | |
923 | /// // s now has a length of 2 and a capacity of 10 | |
924 | /// assert_eq!(2, s.len()); | |
925 | /// assert_eq!(10, s.capacity()); | |
926 | /// | |
927 | /// // Since we already have an extra 8 capacity, calling this... | |
928 | /// s.reserve_exact(8); | |
929 | /// | |
930 | /// // ... doesn't actually increase. | |
931 | /// assert_eq!(10, s.capacity()); | |
932 | /// ``` | |
1a4d82fc | 933 | #[inline] |
85aaf69f SL |
934 | #[stable(feature = "rust1", since = "1.0.0")] |
935 | pub fn reserve_exact(&mut self, additional: usize) { | |
1a4d82fc JJ |
936 | self.vec.reserve_exact(additional) |
937 | } | |
938 | ||
9cc50fc6 | 939 | /// Shrinks the capacity of this `String` to match its length. |
1a4d82fc JJ |
940 | /// |
941 | /// # Examples | |
942 | /// | |
9cc50fc6 SL |
943 | /// Basic usage: |
944 | /// | |
1a4d82fc | 945 | /// ``` |
62682a34 | 946 | /// let mut s = String::from("foo"); |
9cc50fc6 | 947 | /// |
1a4d82fc JJ |
948 | /// s.reserve(100); |
949 | /// assert!(s.capacity() >= 100); | |
9cc50fc6 | 950 | /// |
1a4d82fc | 951 | /// s.shrink_to_fit(); |
9cc50fc6 | 952 | /// assert_eq!(3, s.capacity()); |
1a4d82fc JJ |
953 | /// ``` |
954 | #[inline] | |
85aaf69f | 955 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
956 | pub fn shrink_to_fit(&mut self) { |
957 | self.vec.shrink_to_fit() | |
958 | } | |
959 | ||
9cc50fc6 | 960 | /// Appends the given `char` to the end of this `String`. |
1a4d82fc JJ |
961 | /// |
962 | /// # Examples | |
963 | /// | |
9cc50fc6 SL |
964 | /// Basic usage: |
965 | /// | |
1a4d82fc | 966 | /// ``` |
62682a34 | 967 | /// let mut s = String::from("abc"); |
9cc50fc6 | 968 | /// |
1a4d82fc JJ |
969 | /// s.push('1'); |
970 | /// s.push('2'); | |
971 | /// s.push('3'); | |
9cc50fc6 SL |
972 | /// |
973 | /// assert_eq!("abc123", s); | |
1a4d82fc JJ |
974 | /// ``` |
975 | #[inline] | |
85aaf69f | 976 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 977 | pub fn push(&mut self, ch: char) { |
62682a34 SL |
978 | match ch.len_utf8() { |
979 | 1 => self.vec.push(ch as u8), | |
32a655c1 | 980 | _ => self.vec.extend_from_slice(ch.encode_utf8(&mut [0; 4]).as_bytes()), |
1a4d82fc JJ |
981 | } |
982 | } | |
983 | ||
9cc50fc6 | 984 | /// Returns a byte slice of this `String`'s contents. |
1a4d82fc | 985 | /// |
8bb4bdeb XL |
986 | /// The inverse of this method is [`from_utf8`]. |
987 | /// | |
988 | /// [`from_utf8`]: #method.from_utf8 | |
989 | /// | |
1a4d82fc JJ |
990 | /// # Examples |
991 | /// | |
9cc50fc6 SL |
992 | /// Basic usage: |
993 | /// | |
1a4d82fc | 994 | /// ``` |
62682a34 | 995 | /// let s = String::from("hello"); |
9cc50fc6 SL |
996 | /// |
997 | /// assert_eq!(&[104, 101, 108, 108, 111], s.as_bytes()); | |
1a4d82fc JJ |
998 | /// ``` |
999 | #[inline] | |
85aaf69f SL |
1000 | #[stable(feature = "rust1", since = "1.0.0")] |
1001 | pub fn as_bytes(&self) -> &[u8] { | |
1002 | &self.vec | |
1a4d82fc JJ |
1003 | } |
1004 | ||
9cc50fc6 | 1005 | /// Shortens this `String` to the specified length. |
1a4d82fc | 1006 | /// |
a7813a04 XL |
1007 | /// If `new_len` is greater than the string's current length, this has no |
1008 | /// effect. | |
1009 | /// | |
8bb4bdeb XL |
1010 | /// Note that this method has no effect on the allocated capacity |
1011 | /// of the string | |
1012 | /// | |
1a4d82fc JJ |
1013 | /// # Panics |
1014 | /// | |
a7813a04 | 1015 | /// Panics if `new_len` does not lie on a [`char`] boundary. |
9cc50fc6 | 1016 | /// |
54a0048b | 1017 | /// [`char`]: ../../std/primitive.char.html |
1a4d82fc JJ |
1018 | /// |
1019 | /// # Examples | |
1020 | /// | |
9cc50fc6 SL |
1021 | /// Basic usage: |
1022 | /// | |
1a4d82fc | 1023 | /// ``` |
62682a34 | 1024 | /// let mut s = String::from("hello"); |
9cc50fc6 | 1025 | /// |
1a4d82fc | 1026 | /// s.truncate(2); |
9cc50fc6 SL |
1027 | /// |
1028 | /// assert_eq!("he", s); | |
1a4d82fc JJ |
1029 | /// ``` |
1030 | #[inline] | |
85aaf69f SL |
1031 | #[stable(feature = "rust1", since = "1.0.0")] |
1032 | pub fn truncate(&mut self, new_len: usize) { | |
a7813a04 XL |
1033 | if new_len <= self.len() { |
1034 | assert!(self.is_char_boundary(new_len)); | |
1035 | self.vec.truncate(new_len) | |
1036 | } | |
1a4d82fc JJ |
1037 | } |
1038 | ||
1039 | /// Removes the last character from the string buffer and returns it. | |
9cc50fc6 SL |
1040 | /// |
1041 | /// Returns `None` if this `String` is empty. | |
1a4d82fc JJ |
1042 | /// |
1043 | /// # Examples | |
1044 | /// | |
9cc50fc6 SL |
1045 | /// Basic usage: |
1046 | /// | |
1a4d82fc | 1047 | /// ``` |
62682a34 | 1048 | /// let mut s = String::from("foo"); |
9cc50fc6 | 1049 | /// |
1a4d82fc JJ |
1050 | /// assert_eq!(s.pop(), Some('o')); |
1051 | /// assert_eq!(s.pop(), Some('o')); | |
1052 | /// assert_eq!(s.pop(), Some('f')); | |
9cc50fc6 | 1053 | /// |
1a4d82fc JJ |
1054 | /// assert_eq!(s.pop(), None); |
1055 | /// ``` | |
1056 | #[inline] | |
85aaf69f | 1057 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1058 | pub fn pop(&mut self) -> Option<char> { |
54a0048b SL |
1059 | let ch = match self.chars().rev().next() { |
1060 | Some(ch) => ch, | |
1061 | None => return None, | |
1062 | }; | |
1063 | let newlen = self.len() - ch.len_utf8(); | |
1a4d82fc | 1064 | unsafe { |
54a0048b | 1065 | self.vec.set_len(newlen); |
1a4d82fc JJ |
1066 | } |
1067 | Some(ch) | |
1068 | } | |
1069 | ||
9cc50fc6 | 1070 | /// Removes a `char` from this `String` at a byte position and returns it. |
1a4d82fc | 1071 | /// |
9cc50fc6 | 1072 | /// This is an `O(n)` operation, as it requires copying every element in the |
1a4d82fc JJ |
1073 | /// buffer. |
1074 | /// | |
1075 | /// # Panics | |
1076 | /// | |
9cc50fc6 SL |
1077 | /// Panics if `idx` is larger than or equal to the `String`'s length, |
1078 | /// or if it does not lie on a [`char`] boundary. | |
1079 | /// | |
54a0048b | 1080 | /// [`char`]: ../../std/primitive.char.html |
1a4d82fc JJ |
1081 | /// |
1082 | /// # Examples | |
1083 | /// | |
9cc50fc6 SL |
1084 | /// Basic usage: |
1085 | /// | |
1a4d82fc | 1086 | /// ``` |
62682a34 | 1087 | /// let mut s = String::from("foo"); |
9cc50fc6 | 1088 | /// |
1a4d82fc JJ |
1089 | /// assert_eq!(s.remove(0), 'f'); |
1090 | /// assert_eq!(s.remove(1), 'o'); | |
1091 | /// assert_eq!(s.remove(0), 'o'); | |
1092 | /// ``` | |
85aaf69f SL |
1093 | #[inline] |
1094 | #[stable(feature = "rust1", since = "1.0.0")] | |
1095 | pub fn remove(&mut self, idx: usize) -> char { | |
54a0048b SL |
1096 | let ch = match self[idx..].chars().next() { |
1097 | Some(ch) => ch, | |
1098 | None => panic!("cannot remove a char from the end of a string"), | |
1099 | }; | |
1a4d82fc | 1100 | |
c34b1796 | 1101 | let next = idx + ch.len_utf8(); |
54a0048b | 1102 | let len = self.len(); |
1a4d82fc | 1103 | unsafe { |
c34b1796 AL |
1104 | ptr::copy(self.vec.as_ptr().offset(next as isize), |
1105 | self.vec.as_mut_ptr().offset(idx as isize), | |
1106 | len - next); | |
1a4d82fc JJ |
1107 | self.vec.set_len(len - (next - idx)); |
1108 | } | |
1109 | ch | |
1110 | } | |
1111 | ||
9cc50fc6 | 1112 | /// Inserts a character into this `String` at a byte position. |
1a4d82fc | 1113 | /// |
9cc50fc6 | 1114 | /// This is an `O(n)` operation as it requires copying every element in the |
1a4d82fc JJ |
1115 | /// buffer. |
1116 | /// | |
1117 | /// # Panics | |
1118 | /// | |
9cc50fc6 SL |
1119 | /// Panics if `idx` is larger than the `String`'s length, or if it does not |
1120 | /// lie on a [`char`] boundary. | |
1121 | /// | |
54a0048b | 1122 | /// [`char`]: ../../std/primitive.char.html |
9cc50fc6 SL |
1123 | /// |
1124 | /// # Examples | |
1125 | /// | |
1126 | /// Basic usage: | |
1127 | /// | |
1128 | /// ``` | |
1129 | /// let mut s = String::with_capacity(3); | |
1130 | /// | |
1131 | /// s.insert(0, 'f'); | |
1132 | /// s.insert(1, 'o'); | |
1133 | /// s.insert(2, 'o'); | |
1134 | /// | |
1135 | /// assert_eq!("foo", s); | |
1136 | /// ``` | |
85aaf69f SL |
1137 | #[inline] |
1138 | #[stable(feature = "rust1", since = "1.0.0")] | |
1139 | pub fn insert(&mut self, idx: usize, ch: char) { | |
1a4d82fc | 1140 | assert!(self.is_char_boundary(idx)); |
c30ab7b3 SL |
1141 | let mut bits = [0; 4]; |
1142 | let bits = ch.encode_utf8(&mut bits).as_bytes(); | |
5bcae85e SL |
1143 | |
1144 | unsafe { | |
c30ab7b3 | 1145 | self.insert_bytes(idx, bits); |
5bcae85e SL |
1146 | } |
1147 | } | |
1148 | ||
1149 | unsafe fn insert_bytes(&mut self, idx: usize, bytes: &[u8]) { | |
1150 | let len = self.len(); | |
1151 | let amt = bytes.len(); | |
54a0048b | 1152 | self.vec.reserve(amt); |
1a4d82fc | 1153 | |
5bcae85e SL |
1154 | ptr::copy(self.vec.as_ptr().offset(idx as isize), |
1155 | self.vec.as_mut_ptr().offset((idx + amt) as isize), | |
1156 | len - idx); | |
1157 | ptr::copy(bytes.as_ptr(), | |
1158 | self.vec.as_mut_ptr().offset(idx as isize), | |
1159 | amt); | |
1160 | self.vec.set_len(len + amt); | |
1161 | } | |
1162 | ||
1163 | /// Inserts a string slice into this `String` at a byte position. | |
1164 | /// | |
1165 | /// This is an `O(n)` operation as it requires copying every element in the | |
1166 | /// buffer. | |
1167 | /// | |
1168 | /// # Panics | |
1169 | /// | |
1170 | /// Panics if `idx` is larger than the `String`'s length, or if it does not | |
1171 | /// lie on a [`char`] boundary. | |
1172 | /// | |
1173 | /// [`char`]: ../../std/primitive.char.html | |
1174 | /// | |
1175 | /// # Examples | |
1176 | /// | |
1177 | /// Basic usage: | |
1178 | /// | |
1179 | /// ``` | |
5bcae85e SL |
1180 | /// let mut s = String::from("bar"); |
1181 | /// | |
1182 | /// s.insert_str(0, "foo"); | |
1183 | /// | |
1184 | /// assert_eq!("foobar", s); | |
1185 | /// ``` | |
1186 | #[inline] | |
32a655c1 | 1187 | #[stable(feature = "insert_str", since = "1.16.0")] |
5bcae85e | 1188 | pub fn insert_str(&mut self, idx: usize, string: &str) { |
5bcae85e SL |
1189 | assert!(self.is_char_boundary(idx)); |
1190 | ||
1a4d82fc | 1191 | unsafe { |
5bcae85e | 1192 | self.insert_bytes(idx, string.as_bytes()); |
1a4d82fc JJ |
1193 | } |
1194 | } | |
1195 | ||
9cc50fc6 | 1196 | /// Returns a mutable reference to the contents of this `String`. |
1a4d82fc | 1197 | /// |
9cc50fc6 SL |
1198 | /// # Safety |
1199 | /// | |
1200 | /// This function is unsafe because it does not check that the bytes passed | |
1201 | /// to it are valid UTF-8. If this constraint is violated, it may cause | |
1202 | /// memory unsafety issues with future users of the `String`, as the rest of | |
1203 | /// the standard library assumes that `String`s are valid UTF-8. | |
1a4d82fc JJ |
1204 | /// |
1205 | /// # Examples | |
1206 | /// | |
9cc50fc6 SL |
1207 | /// Basic usage: |
1208 | /// | |
1a4d82fc | 1209 | /// ``` |
62682a34 | 1210 | /// let mut s = String::from("hello"); |
9cc50fc6 | 1211 | /// |
1a4d82fc JJ |
1212 | /// unsafe { |
1213 | /// let vec = s.as_mut_vec(); | |
9cc50fc6 SL |
1214 | /// assert_eq!(&[104, 101, 108, 108, 111][..], &vec[..]); |
1215 | /// | |
1a4d82fc JJ |
1216 | /// vec.reverse(); |
1217 | /// } | |
c34b1796 | 1218 | /// assert_eq!(s, "olleh"); |
1a4d82fc | 1219 | /// ``` |
85aaf69f SL |
1220 | #[inline] |
1221 | #[stable(feature = "rust1", since = "1.0.0")] | |
1222 | pub unsafe fn as_mut_vec(&mut self) -> &mut Vec<u8> { | |
1a4d82fc JJ |
1223 | &mut self.vec |
1224 | } | |
1225 | ||
9cc50fc6 | 1226 | /// Returns the length of this `String`, in bytes. |
1a4d82fc JJ |
1227 | /// |
1228 | /// # Examples | |
1229 | /// | |
9cc50fc6 SL |
1230 | /// Basic usage: |
1231 | /// | |
1a4d82fc | 1232 | /// ``` |
9cc50fc6 SL |
1233 | /// let a = String::from("foo"); |
1234 | /// | |
1a4d82fc JJ |
1235 | /// assert_eq!(a.len(), 3); |
1236 | /// ``` | |
1237 | #[inline] | |
85aaf69f | 1238 | #[stable(feature = "rust1", since = "1.0.0")] |
92a42be0 SL |
1239 | pub fn len(&self) -> usize { |
1240 | self.vec.len() | |
1241 | } | |
1a4d82fc | 1242 | |
9cc50fc6 SL |
1243 | /// Returns `true` if this `String` has a length of zero. |
1244 | /// | |
1245 | /// Returns `false` otherwise. | |
1a4d82fc JJ |
1246 | /// |
1247 | /// # Examples | |
1248 | /// | |
9cc50fc6 SL |
1249 | /// Basic usage: |
1250 | /// | |
1a4d82fc JJ |
1251 | /// ``` |
1252 | /// let mut v = String::new(); | |
1253 | /// assert!(v.is_empty()); | |
9cc50fc6 | 1254 | /// |
1a4d82fc JJ |
1255 | /// v.push('a'); |
1256 | /// assert!(!v.is_empty()); | |
1257 | /// ``` | |
85aaf69f SL |
1258 | #[inline] |
1259 | #[stable(feature = "rust1", since = "1.0.0")] | |
92a42be0 SL |
1260 | pub fn is_empty(&self) -> bool { |
1261 | self.len() == 0 | |
1262 | } | |
1a4d82fc | 1263 | |
8bb4bdeb | 1264 | /// Splits the string into two at the given index. |
476ff2be | 1265 | /// |
8bb4bdeb XL |
1266 | /// Returns a newly allocated `String`. `self` contains bytes `[0, at)`, and |
1267 | /// the returned `String` contains bytes `[at, len)`. `at` must be on the | |
1268 | /// boundary of a UTF-8 code point. | |
476ff2be | 1269 | /// |
8bb4bdeb | 1270 | /// Note that the capacity of `self` does not change. |
476ff2be SL |
1271 | /// |
1272 | /// # Panics | |
1273 | /// | |
8bb4bdeb | 1274 | /// Panics if `at` is not on a `UTF-8` code point boundary, or if it is beyond the last |
476ff2be SL |
1275 | /// code point of the string. |
1276 | /// | |
1277 | /// # Examples | |
1278 | /// | |
1279 | /// ``` | |
476ff2be SL |
1280 | /// # fn main() { |
1281 | /// let mut hello = String::from("Hello, World!"); | |
1282 | /// let world = hello.split_off(7); | |
1283 | /// assert_eq!(hello, "Hello, "); | |
1284 | /// assert_eq!(world, "World!"); | |
1285 | /// # } | |
1286 | /// ``` | |
1287 | #[inline] | |
32a655c1 | 1288 | #[stable(feature = "string_split_off", since = "1.16.0")] |
8bb4bdeb XL |
1289 | pub fn split_off(&mut self, at: usize) -> String { |
1290 | assert!(self.is_char_boundary(at)); | |
1291 | let other = self.vec.split_off(at); | |
476ff2be SL |
1292 | unsafe { String::from_utf8_unchecked(other) } |
1293 | } | |
1294 | ||
9cc50fc6 SL |
1295 | /// Truncates this `String`, removing all contents. |
1296 | /// | |
1297 | /// While this means the `String` will have a length of zero, it does not | |
1298 | /// touch its capacity. | |
1a4d82fc JJ |
1299 | /// |
1300 | /// # Examples | |
1301 | /// | |
9cc50fc6 SL |
1302 | /// Basic usage: |
1303 | /// | |
1a4d82fc | 1304 | /// ``` |
9cc50fc6 SL |
1305 | /// let mut s = String::from("foo"); |
1306 | /// | |
1a4d82fc | 1307 | /// s.clear(); |
9cc50fc6 | 1308 | /// |
1a4d82fc | 1309 | /// assert!(s.is_empty()); |
9cc50fc6 SL |
1310 | /// assert_eq!(0, s.len()); |
1311 | /// assert_eq!(3, s.capacity()); | |
1a4d82fc JJ |
1312 | /// ``` |
1313 | #[inline] | |
85aaf69f | 1314 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1315 | pub fn clear(&mut self) { |
1316 | self.vec.clear() | |
1317 | } | |
d9579d0f AL |
1318 | |
1319 | /// Create a draining iterator that removes the specified range in the string | |
9cc50fc6 SL |
1320 | /// and yields the removed chars. |
1321 | /// | |
1322 | /// Note: The element range is removed even if the iterator is not | |
1323 | /// consumed until the end. | |
d9579d0f AL |
1324 | /// |
1325 | /// # Panics | |
1326 | /// | |
9cc50fc6 SL |
1327 | /// Panics if the starting point or end point do not lie on a [`char`] |
1328 | /// boundary, or if they're out of bounds. | |
1329 | /// | |
54a0048b | 1330 | /// [`char`]: ../../std/primitive.char.html |
d9579d0f AL |
1331 | /// |
1332 | /// # Examples | |
1333 | /// | |
9cc50fc6 SL |
1334 | /// Basic usage: |
1335 | /// | |
d9579d0f | 1336 | /// ``` |
d9579d0f AL |
1337 | /// let mut s = String::from("α is alpha, β is beta"); |
1338 | /// let beta_offset = s.find('β').unwrap_or(s.len()); | |
1339 | /// | |
1340 | /// // Remove the range up until the β from the string | |
1341 | /// let t: String = s.drain(..beta_offset).collect(); | |
1342 | /// assert_eq!(t, "α is alpha, "); | |
1343 | /// assert_eq!(s, "β is beta"); | |
1344 | /// | |
1345 | /// // A full range clears the string | |
1346 | /// s.drain(..); | |
1347 | /// assert_eq!(s, ""); | |
1348 | /// ``` | |
92a42be0 SL |
1349 | #[stable(feature = "drain", since = "1.6.0")] |
1350 | pub fn drain<R>(&mut self, range: R) -> Drain | |
1351 | where R: RangeArgument<usize> | |
1352 | { | |
d9579d0f AL |
1353 | // Memory safety |
1354 | // | |
1355 | // The String version of Drain does not have the memory safety issues | |
1356 | // of the vector version. The data is just plain bytes. | |
1357 | // Because the range removal happens in Drop, if the Drain iterator is leaked, | |
1358 | // the removal will not happen. | |
1359 | let len = self.len(); | |
32a655c1 SL |
1360 | let start = match range.start() { |
1361 | Included(&n) => n, | |
1362 | Excluded(&n) => n + 1, | |
1363 | Unbounded => 0, | |
1364 | }; | |
1365 | let end = match range.end() { | |
1366 | Included(&n) => n + 1, | |
1367 | Excluded(&n) => n, | |
1368 | Unbounded => len, | |
1369 | }; | |
d9579d0f AL |
1370 | |
1371 | // Take out two simultaneous borrows. The &mut String won't be accessed | |
1372 | // until iteration is over, in Drop. | |
1373 | let self_ptr = self as *mut _; | |
1374 | // slicing does the appropriate bounds checks | |
1375 | let chars_iter = self[start..end].chars(); | |
1376 | ||
1377 | Drain { | |
1378 | start: start, | |
1379 | end: end, | |
1380 | iter: chars_iter, | |
1381 | string: self_ptr, | |
1382 | } | |
1383 | } | |
c1a9b12d | 1384 | |
9cc50fc6 SL |
1385 | /// Converts this `String` into a `Box<str>`. |
1386 | /// | |
1387 | /// This will drop any excess capacity. | |
1388 | /// | |
1389 | /// # Examples | |
1390 | /// | |
1391 | /// Basic usage: | |
1392 | /// | |
1393 | /// ``` | |
1394 | /// let s = String::from("hello"); | |
c1a9b12d | 1395 | /// |
9cc50fc6 SL |
1396 | /// let b = s.into_boxed_str(); |
1397 | /// ``` | |
e9174d1e SL |
1398 | #[stable(feature = "box_str", since = "1.4.0")] |
1399 | pub fn into_boxed_str(self) -> Box<str> { | |
c1a9b12d SL |
1400 | let slice = self.vec.into_boxed_slice(); |
1401 | unsafe { mem::transmute::<Box<[u8]>, Box<str>>(slice) } | |
1402 | } | |
1a4d82fc JJ |
1403 | } |
1404 | ||
1405 | impl FromUtf8Error { | |
92a42be0 SL |
1406 | /// Returns the bytes that were attempted to convert to a `String`. |
1407 | /// | |
1408 | /// This method is carefully constructed to avoid allocation. It will | |
1409 | /// consume the error, moving out the bytes, so that a copy of the bytes | |
1410 | /// does not need to be made. | |
1411 | /// | |
1412 | /// # Examples | |
1413 | /// | |
1414 | /// Basic usage: | |
1415 | /// | |
1416 | /// ``` | |
1417 | /// // some invalid bytes, in a vector | |
1418 | /// let bytes = vec![0, 159]; | |
1419 | /// | |
1420 | /// let value = String::from_utf8(bytes); | |
1421 | /// | |
1422 | /// assert_eq!(vec![0, 159], value.unwrap_err().into_bytes()); | |
1423 | /// ``` | |
85aaf69f | 1424 | #[stable(feature = "rust1", since = "1.0.0")] |
92a42be0 SL |
1425 | pub fn into_bytes(self) -> Vec<u8> { |
1426 | self.bytes | |
1427 | } | |
1a4d82fc | 1428 | |
92a42be0 SL |
1429 | /// Fetch a `Utf8Error` to get more details about the conversion failure. |
1430 | /// | |
1431 | /// The [`Utf8Error`] type provided by [`std::str`] represents an error that may | |
1432 | /// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's | |
1433 | /// an analogue to `FromUtf8Error`. See its documentation for more details | |
1434 | /// on using it. | |
1435 | /// | |
54a0048b SL |
1436 | /// [`Utf8Error`]: ../../std/str/struct.Utf8Error.html |
1437 | /// [`std::str`]: ../../std/str/index.html | |
1438 | /// [`u8`]: ../../std/primitive.u8.html | |
1439 | /// [`&str`]: ../../std/primitive.str.html | |
92a42be0 SL |
1440 | /// |
1441 | /// # Examples | |
1442 | /// | |
1443 | /// Basic usage: | |
1444 | /// | |
1445 | /// ``` | |
1446 | /// // some invalid bytes, in a vector | |
1447 | /// let bytes = vec![0, 159]; | |
1448 | /// | |
1449 | /// let error = String::from_utf8(bytes).unwrap_err().utf8_error(); | |
1450 | /// | |
1451 | /// // the first byte is invalid here | |
1452 | /// assert_eq!(1, error.valid_up_to()); | |
1453 | /// ``` | |
85aaf69f | 1454 | #[stable(feature = "rust1", since = "1.0.0")] |
92a42be0 SL |
1455 | pub fn utf8_error(&self) -> Utf8Error { |
1456 | self.error | |
1457 | } | |
1a4d82fc JJ |
1458 | } |
1459 | ||
85aaf69f SL |
1460 | #[stable(feature = "rust1", since = "1.0.0")] |
1461 | impl fmt::Display for FromUtf8Error { | |
1a4d82fc | 1462 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
85aaf69f | 1463 | fmt::Display::fmt(&self.error, f) |
1a4d82fc JJ |
1464 | } |
1465 | } | |
1466 | ||
85aaf69f SL |
1467 | #[stable(feature = "rust1", since = "1.0.0")] |
1468 | impl fmt::Display for FromUtf16Error { | |
1a4d82fc | 1469 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
85aaf69f | 1470 | fmt::Display::fmt("invalid utf-16: lone surrogate found", f) |
1a4d82fc JJ |
1471 | } |
1472 | } | |
1473 | ||
b039eaaf SL |
1474 | #[stable(feature = "rust1", since = "1.0.0")] |
1475 | impl Clone for String { | |
1476 | fn clone(&self) -> Self { | |
1477 | String { vec: self.vec.clone() } | |
1478 | } | |
1479 | ||
1480 | fn clone_from(&mut self, source: &Self) { | |
1481 | self.vec.clone_from(&source.vec); | |
1482 | } | |
1483 | } | |
1484 | ||
85aaf69f | 1485 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1486 | impl FromIterator<char> for String { |
54a0048b | 1487 | fn from_iter<I: IntoIterator<Item = char>>(iter: I) -> String { |
1a4d82fc | 1488 | let mut buf = String::new(); |
54a0048b | 1489 | buf.extend(iter); |
1a4d82fc JJ |
1490 | buf |
1491 | } | |
1492 | } | |
1493 | ||
8bb4bdeb XL |
1494 | #[stable(feature = "string_from_iter_by_ref", since = "1.17.0")] |
1495 | impl<'a> FromIterator<&'a char> for String { | |
1496 | fn from_iter<I: IntoIterator<Item = &'a char>>(iter: I) -> String { | |
1497 | let mut buf = String::new(); | |
1498 | buf.extend(iter); | |
1499 | buf | |
1500 | } | |
1501 | } | |
1502 | ||
85aaf69f | 1503 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1504 | impl<'a> FromIterator<&'a str> for String { |
54a0048b | 1505 | fn from_iter<I: IntoIterator<Item = &'a str>>(iter: I) -> String { |
e9174d1e | 1506 | let mut buf = String::new(); |
54a0048b | 1507 | buf.extend(iter); |
e9174d1e SL |
1508 | buf |
1509 | } | |
1510 | } | |
1511 | ||
1512 | #[stable(feature = "extend_string", since = "1.4.0")] | |
1513 | impl FromIterator<String> for String { | |
54a0048b | 1514 | fn from_iter<I: IntoIterator<Item = String>>(iter: I) -> String { |
1a4d82fc | 1515 | let mut buf = String::new(); |
54a0048b | 1516 | buf.extend(iter); |
1a4d82fc JJ |
1517 | buf |
1518 | } | |
1519 | } | |
1520 | ||
bd371182 | 1521 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1522 | impl Extend<char> for String { |
54a0048b SL |
1523 | fn extend<I: IntoIterator<Item = char>>(&mut self, iter: I) { |
1524 | let iterator = iter.into_iter(); | |
1a4d82fc JJ |
1525 | let (lower_bound, _) = iterator.size_hint(); |
1526 | self.reserve(lower_bound); | |
1527 | for ch in iterator { | |
1528 | self.push(ch) | |
1529 | } | |
1530 | } | |
1531 | } | |
1532 | ||
62682a34 SL |
1533 | #[stable(feature = "extend_ref", since = "1.2.0")] |
1534 | impl<'a> Extend<&'a char> for String { | |
54a0048b SL |
1535 | fn extend<I: IntoIterator<Item = &'a char>>(&mut self, iter: I) { |
1536 | self.extend(iter.into_iter().cloned()); | |
62682a34 SL |
1537 | } |
1538 | } | |
1539 | ||
bd371182 | 1540 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1541 | impl<'a> Extend<&'a str> for String { |
54a0048b SL |
1542 | fn extend<I: IntoIterator<Item = &'a str>>(&mut self, iter: I) { |
1543 | for s in iter { | |
1a4d82fc JJ |
1544 | self.push_str(s) |
1545 | } | |
1546 | } | |
1547 | } | |
1548 | ||
e9174d1e SL |
1549 | #[stable(feature = "extend_string", since = "1.4.0")] |
1550 | impl Extend<String> for String { | |
54a0048b SL |
1551 | fn extend<I: IntoIterator<Item = String>>(&mut self, iter: I) { |
1552 | for s in iter { | |
e9174d1e SL |
1553 | self.push_str(&s) |
1554 | } | |
1555 | } | |
1556 | } | |
1557 | ||
c34b1796 | 1558 | /// A convenience impl that delegates to the impl for `&str` |
92a42be0 SL |
1559 | #[unstable(feature = "pattern", |
1560 | reason = "API not fully fleshed out and ready to be stabilized", | |
1561 | issue = "27721")] | |
c34b1796 AL |
1562 | impl<'a, 'b> Pattern<'a> for &'b String { |
1563 | type Searcher = <&'b str as Pattern<'a>>::Searcher; | |
1564 | ||
1565 | fn into_searcher(self, haystack: &'a str) -> <&'b str as Pattern<'a>>::Searcher { | |
1566 | self[..].into_searcher(haystack) | |
1567 | } | |
1568 | ||
1569 | #[inline] | |
1570 | fn is_contained_in(self, haystack: &'a str) -> bool { | |
1571 | self[..].is_contained_in(haystack) | |
1572 | } | |
1573 | ||
1574 | #[inline] | |
1575 | fn is_prefix_of(self, haystack: &'a str) -> bool { | |
1576 | self[..].is_prefix_of(haystack) | |
1577 | } | |
1578 | } | |
1579 | ||
85aaf69f | 1580 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1581 | impl PartialEq for String { |
1582 | #[inline] | |
92a42be0 SL |
1583 | fn eq(&self, other: &String) -> bool { |
1584 | PartialEq::eq(&self[..], &other[..]) | |
1585 | } | |
1a4d82fc | 1586 | #[inline] |
92a42be0 SL |
1587 | fn ne(&self, other: &String) -> bool { |
1588 | PartialEq::ne(&self[..], &other[..]) | |
1589 | } | |
1a4d82fc JJ |
1590 | } |
1591 | ||
1592 | macro_rules! impl_eq { | |
1593 | ($lhs:ty, $rhs: ty) => { | |
85aaf69f | 1594 | #[stable(feature = "rust1", since = "1.0.0")] |
92a42be0 | 1595 | impl<'a, 'b> PartialEq<$rhs> for $lhs { |
1a4d82fc | 1596 | #[inline] |
9346a6ac | 1597 | fn eq(&self, other: &$rhs) -> bool { PartialEq::eq(&self[..], &other[..]) } |
1a4d82fc | 1598 | #[inline] |
9346a6ac | 1599 | fn ne(&self, other: &$rhs) -> bool { PartialEq::ne(&self[..], &other[..]) } |
1a4d82fc JJ |
1600 | } |
1601 | ||
85aaf69f | 1602 | #[stable(feature = "rust1", since = "1.0.0")] |
92a42be0 | 1603 | impl<'a, 'b> PartialEq<$lhs> for $rhs { |
1a4d82fc | 1604 | #[inline] |
9346a6ac | 1605 | fn eq(&self, other: &$lhs) -> bool { PartialEq::eq(&self[..], &other[..]) } |
1a4d82fc | 1606 | #[inline] |
9346a6ac | 1607 | fn ne(&self, other: &$lhs) -> bool { PartialEq::ne(&self[..], &other[..]) } |
1a4d82fc JJ |
1608 | } |
1609 | ||
1610 | } | |
1611 | } | |
1612 | ||
9346a6ac | 1613 | impl_eq! { String, str } |
1a4d82fc | 1614 | impl_eq! { String, &'a str } |
9346a6ac | 1615 | impl_eq! { Cow<'a, str>, str } |
92a42be0 | 1616 | impl_eq! { Cow<'a, str>, &'b str } |
85aaf69f | 1617 | impl_eq! { Cow<'a, str>, String } |
1a4d82fc | 1618 | |
85aaf69f | 1619 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1620 | impl Default for String { |
9e0c209e | 1621 | /// Creates an empty `String`. |
85aaf69f | 1622 | #[inline] |
1a4d82fc JJ |
1623 | fn default() -> String { |
1624 | String::new() | |
1625 | } | |
1626 | } | |
1627 | ||
85aaf69f SL |
1628 | #[stable(feature = "rust1", since = "1.0.0")] |
1629 | impl fmt::Display for String { | |
1630 | #[inline] | |
1a4d82fc | 1631 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
85aaf69f | 1632 | fmt::Display::fmt(&**self, f) |
1a4d82fc JJ |
1633 | } |
1634 | } | |
1635 | ||
85aaf69f SL |
1636 | #[stable(feature = "rust1", since = "1.0.0")] |
1637 | impl fmt::Debug for String { | |
1638 | #[inline] | |
1a4d82fc | 1639 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { |
85aaf69f | 1640 | fmt::Debug::fmt(&**self, f) |
1a4d82fc JJ |
1641 | } |
1642 | } | |
1643 | ||
85aaf69f | 1644 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f | 1645 | impl hash::Hash for String { |
1a4d82fc | 1646 | #[inline] |
85aaf69f | 1647 | fn hash<H: hash::Hasher>(&self, hasher: &mut H) { |
1a4d82fc JJ |
1648 | (**self).hash(hasher) |
1649 | } | |
1650 | } | |
1651 | ||
8bb4bdeb XL |
1652 | /// Implements the `+` operator for concatenating two strings. |
1653 | /// | |
1654 | /// This consumes the `String` on the left-hand side and re-uses its buffer (growing it if | |
1655 | /// necessary). This is done to avoid allocating a new `String` and copying the entire contents on | |
1656 | /// every operation, which would lead to `O(n^2)` running time when building an `n`-byte string by | |
1657 | /// repeated concatenation. | |
1658 | /// | |
1659 | /// The string on the right-hand side is only borrowed; its contents are copied into the returned | |
1660 | /// `String`. | |
1661 | /// | |
1662 | /// # Examples | |
1663 | /// | |
1664 | /// Concatenating two `String`s takes the first by value and borrows the second: | |
1665 | /// | |
1666 | /// ``` | |
1667 | /// let a = String::from("hello"); | |
1668 | /// let b = String::from(" world"); | |
1669 | /// let c = a + &b; | |
1670 | /// // `a` is moved and can no longer be used here. | |
1671 | /// ``` | |
1672 | /// | |
1673 | /// If you want to keep using the first `String`, you can clone it and append to the clone instead: | |
1674 | /// | |
1675 | /// ``` | |
1676 | /// let a = String::from("hello"); | |
1677 | /// let b = String::from(" world"); | |
1678 | /// let c = a.clone() + &b; | |
1679 | /// // `a` is still valid here. | |
1680 | /// ``` | |
1681 | /// | |
1682 | /// Concatenating `&str` slices can be done by converting the first to a `String`: | |
1683 | /// | |
1684 | /// ``` | |
1685 | /// let a = "hello"; | |
1686 | /// let b = " world"; | |
1687 | /// let c = a.to_string() + b; | |
1688 | /// ``` | |
bd371182 | 1689 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1690 | impl<'a> Add<&'a str> for String { |
1691 | type Output = String; | |
1692 | ||
85aaf69f | 1693 | #[inline] |
1a4d82fc JJ |
1694 | fn add(mut self, other: &str) -> String { |
1695 | self.push_str(other); | |
1696 | self | |
1697 | } | |
1698 | } | |
1699 | ||
8bb4bdeb XL |
1700 | /// Implements the `+=` operator for appending to a `String`. |
1701 | /// | |
1702 | /// This has the same behavior as the [`push_str()`] method. | |
1703 | /// | |
1704 | /// [`push_str()`]: struct.String.html#method.push_str | |
5bcae85e SL |
1705 | #[stable(feature = "stringaddassign", since = "1.12.0")] |
1706 | impl<'a> AddAssign<&'a str> for String { | |
1707 | #[inline] | |
1708 | fn add_assign(&mut self, other: &str) { | |
1709 | self.push_str(other); | |
1710 | } | |
1711 | } | |
1712 | ||
85aaf69f SL |
1713 | #[stable(feature = "rust1", since = "1.0.0")] |
1714 | impl ops::Index<ops::Range<usize>> for String { | |
1a4d82fc | 1715 | type Output = str; |
c34b1796 | 1716 | |
1a4d82fc | 1717 | #[inline] |
c34b1796 AL |
1718 | fn index(&self, index: ops::Range<usize>) -> &str { |
1719 | &self[..][index] | |
1a4d82fc JJ |
1720 | } |
1721 | } | |
85aaf69f SL |
1722 | #[stable(feature = "rust1", since = "1.0.0")] |
1723 | impl ops::Index<ops::RangeTo<usize>> for String { | |
1a4d82fc | 1724 | type Output = str; |
c34b1796 | 1725 | |
1a4d82fc | 1726 | #[inline] |
c34b1796 AL |
1727 | fn index(&self, index: ops::RangeTo<usize>) -> &str { |
1728 | &self[..][index] | |
1a4d82fc JJ |
1729 | } |
1730 | } | |
85aaf69f SL |
1731 | #[stable(feature = "rust1", since = "1.0.0")] |
1732 | impl ops::Index<ops::RangeFrom<usize>> for String { | |
1a4d82fc | 1733 | type Output = str; |
c34b1796 | 1734 | |
1a4d82fc | 1735 | #[inline] |
c34b1796 AL |
1736 | fn index(&self, index: ops::RangeFrom<usize>) -> &str { |
1737 | &self[..][index] | |
1a4d82fc JJ |
1738 | } |
1739 | } | |
85aaf69f SL |
1740 | #[stable(feature = "rust1", since = "1.0.0")] |
1741 | impl ops::Index<ops::RangeFull> for String { | |
1a4d82fc | 1742 | type Output = str; |
c34b1796 | 1743 | |
1a4d82fc | 1744 | #[inline] |
c34b1796 | 1745 | fn index(&self, _index: ops::RangeFull) -> &str { |
e9174d1e | 1746 | unsafe { str::from_utf8_unchecked(&self.vec) } |
1a4d82fc JJ |
1747 | } |
1748 | } | |
54a0048b SL |
1749 | #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")] |
1750 | impl ops::Index<ops::RangeInclusive<usize>> for String { | |
1751 | type Output = str; | |
1752 | ||
1753 | #[inline] | |
1754 | fn index(&self, index: ops::RangeInclusive<usize>) -> &str { | |
1755 | Index::index(&**self, index) | |
1756 | } | |
1757 | } | |
1758 | #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")] | |
1759 | impl ops::Index<ops::RangeToInclusive<usize>> for String { | |
1760 | type Output = str; | |
1761 | ||
1762 | #[inline] | |
1763 | fn index(&self, index: ops::RangeToInclusive<usize>) -> &str { | |
1764 | Index::index(&**self, index) | |
1765 | } | |
1766 | } | |
1a4d82fc | 1767 | |
c1a9b12d SL |
1768 | #[stable(feature = "derefmut_for_string", since = "1.2.0")] |
1769 | impl ops::IndexMut<ops::Range<usize>> for String { | |
1770 | #[inline] | |
1771 | fn index_mut(&mut self, index: ops::Range<usize>) -> &mut str { | |
1772 | &mut self[..][index] | |
1773 | } | |
1774 | } | |
1775 | #[stable(feature = "derefmut_for_string", since = "1.2.0")] | |
1776 | impl ops::IndexMut<ops::RangeTo<usize>> for String { | |
1777 | #[inline] | |
1778 | fn index_mut(&mut self, index: ops::RangeTo<usize>) -> &mut str { | |
1779 | &mut self[..][index] | |
1780 | } | |
1781 | } | |
1782 | #[stable(feature = "derefmut_for_string", since = "1.2.0")] | |
1783 | impl ops::IndexMut<ops::RangeFrom<usize>> for String { | |
1784 | #[inline] | |
1785 | fn index_mut(&mut self, index: ops::RangeFrom<usize>) -> &mut str { | |
1786 | &mut self[..][index] | |
1787 | } | |
1788 | } | |
1789 | #[stable(feature = "derefmut_for_string", since = "1.2.0")] | |
1790 | impl ops::IndexMut<ops::RangeFull> for String { | |
1791 | #[inline] | |
1792 | fn index_mut(&mut self, _index: ops::RangeFull) -> &mut str { | |
1793 | unsafe { mem::transmute(&mut *self.vec) } | |
1794 | } | |
1795 | } | |
54a0048b SL |
1796 | #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")] |
1797 | impl ops::IndexMut<ops::RangeInclusive<usize>> for String { | |
1798 | #[inline] | |
1799 | fn index_mut(&mut self, index: ops::RangeInclusive<usize>) -> &mut str { | |
1800 | IndexMut::index_mut(&mut **self, index) | |
1801 | } | |
1802 | } | |
1803 | #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")] | |
1804 | impl ops::IndexMut<ops::RangeToInclusive<usize>> for String { | |
1805 | #[inline] | |
1806 | fn index_mut(&mut self, index: ops::RangeToInclusive<usize>) -> &mut str { | |
1807 | IndexMut::index_mut(&mut **self, index) | |
1808 | } | |
1809 | } | |
c1a9b12d | 1810 | |
85aaf69f | 1811 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1812 | impl ops::Deref for String { |
1813 | type Target = str; | |
1814 | ||
85aaf69f SL |
1815 | #[inline] |
1816 | fn deref(&self) -> &str { | |
e9174d1e | 1817 | unsafe { str::from_utf8_unchecked(&self.vec) } |
1a4d82fc JJ |
1818 | } |
1819 | } | |
1820 | ||
c1a9b12d SL |
1821 | #[stable(feature = "derefmut_for_string", since = "1.2.0")] |
1822 | impl ops::DerefMut for String { | |
85aaf69f | 1823 | #[inline] |
c1a9b12d | 1824 | fn deref_mut(&mut self) -> &mut str { |
e9174d1e | 1825 | unsafe { mem::transmute(&mut *self.vec) } |
1a4d82fc JJ |
1826 | } |
1827 | } | |
1828 | ||
92a42be0 SL |
1829 | /// An error when parsing a `String`. |
1830 | /// | |
1831 | /// This `enum` is slightly awkward: it will never actually exist. This error is | |
1832 | /// part of the type signature of the implementation of [`FromStr`] on | |
1833 | /// [`String`]. The return type of [`from_str()`], requires that an error be | |
1834 | /// defined, but, given that a [`String`] can always be made into a new | |
1835 | /// [`String`] without error, this type will never actually be returned. As | |
1836 | /// such, it is only here to satisfy said signature, and is useless otherwise. | |
1837 | /// | |
54a0048b | 1838 | /// [`FromStr`]: ../../std/str/trait.FromStr.html |
92a42be0 | 1839 | /// [`String`]: struct.String.html |
54a0048b | 1840 | /// [`from_str()`]: ../../std/str/trait.FromStr.html#tymethod.from_str |
b039eaaf SL |
1841 | #[stable(feature = "str_parse_error", since = "1.5.0")] |
1842 | #[derive(Copy)] | |
1843 | pub enum ParseError {} | |
bd371182 AL |
1844 | |
1845 | #[stable(feature = "rust1", since = "1.0.0")] | |
1a4d82fc | 1846 | impl FromStr for String { |
bd371182 | 1847 | type Err = ParseError; |
1a4d82fc | 1848 | #[inline] |
bd371182 | 1849 | fn from_str(s: &str) -> Result<String, ParseError> { |
62682a34 | 1850 | Ok(String::from(s)) |
1a4d82fc JJ |
1851 | } |
1852 | } | |
1853 | ||
92a42be0 | 1854 | #[stable(feature = "str_parse_error", since = "1.5.0")] |
b039eaaf SL |
1855 | impl Clone for ParseError { |
1856 | fn clone(&self) -> ParseError { | |
1857 | match *self {} | |
1858 | } | |
1859 | } | |
1860 | ||
92a42be0 | 1861 | #[stable(feature = "str_parse_error", since = "1.5.0")] |
b039eaaf SL |
1862 | impl fmt::Debug for ParseError { |
1863 | fn fmt(&self, _: &mut fmt::Formatter) -> fmt::Result { | |
1864 | match *self {} | |
1865 | } | |
1866 | } | |
1867 | ||
7453a54e SL |
1868 | #[stable(feature = "str_parse_error2", since = "1.8.0")] |
1869 | impl fmt::Display for ParseError { | |
1870 | fn fmt(&self, _: &mut fmt::Formatter) -> fmt::Result { | |
1871 | match *self {} | |
1872 | } | |
1873 | } | |
1874 | ||
92a42be0 | 1875 | #[stable(feature = "str_parse_error", since = "1.5.0")] |
b039eaaf SL |
1876 | impl PartialEq for ParseError { |
1877 | fn eq(&self, _: &ParseError) -> bool { | |
1878 | match *self {} | |
1879 | } | |
1880 | } | |
1881 | ||
92a42be0 | 1882 | #[stable(feature = "str_parse_error", since = "1.5.0")] |
b039eaaf SL |
1883 | impl Eq for ParseError {} |
1884 | ||
92a42be0 SL |
1885 | /// A trait for converting a value to a `String`. |
1886 | /// | |
1887 | /// This trait is automatically implemented for any type which implements the | |
1888 | /// [`Display`] trait. As such, `ToString` shouldn't be implemented directly: | |
1889 | /// [`Display`] should be implemented instead, and you get the `ToString` | |
1890 | /// implementation for free. | |
1891 | /// | |
54a0048b | 1892 | /// [`Display`]: ../../std/fmt/trait.Display.html |
85aaf69f | 1893 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc | 1894 | pub trait ToString { |
92a42be0 SL |
1895 | /// Converts the given value to a `String`. |
1896 | /// | |
1897 | /// # Examples | |
1898 | /// | |
1899 | /// Basic usage: | |
1900 | /// | |
1901 | /// ``` | |
1902 | /// let i = 5; | |
1903 | /// let five = String::from("5"); | |
1904 | /// | |
1905 | /// assert_eq!(five, i.to_string()); | |
1906 | /// ``` | |
85aaf69f | 1907 | #[stable(feature = "rust1", since = "1.0.0")] |
1a4d82fc JJ |
1908 | fn to_string(&self) -> String; |
1909 | } | |
1910 | ||
8bb4bdeb XL |
1911 | /// # Panics |
1912 | /// | |
1913 | /// In this implementation, the `to_string` method panics | |
1914 | /// if the `Display` implementation returns an error. | |
1915 | /// This indicates an incorrect `Display` implementation | |
1916 | /// since `fmt::Write for String` never returns an error itself. | |
85aaf69f SL |
1917 | #[stable(feature = "rust1", since = "1.0.0")] |
1918 | impl<T: fmt::Display + ?Sized> ToString for T { | |
1919 | #[inline] | |
54a0048b | 1920 | default fn to_string(&self) -> String { |
85aaf69f | 1921 | use core::fmt::Write; |
1a4d82fc | 1922 | let mut buf = String::new(); |
8bb4bdeb XL |
1923 | buf.write_fmt(format_args!("{}", self)) |
1924 | .expect("a Display implementation return an error unexpectedly"); | |
1a4d82fc JJ |
1925 | buf.shrink_to_fit(); |
1926 | buf | |
1927 | } | |
1928 | } | |
1929 | ||
54a0048b SL |
1930 | #[stable(feature = "str_to_string_specialization", since = "1.9.0")] |
1931 | impl ToString for str { | |
1932 | #[inline] | |
1933 | fn to_string(&self) -> String { | |
1934 | String::from(self) | |
1935 | } | |
1936 | } | |
1937 | ||
8bb4bdeb XL |
1938 | #[stable(feature = "cow_str_to_string_specialization", since = "1.17.0")] |
1939 | impl<'a> ToString for Cow<'a, str> { | |
1940 | #[inline] | |
1941 | fn to_string(&self) -> String { | |
1942 | self[..].to_owned() | |
1943 | } | |
1944 | } | |
1945 | ||
1946 | #[stable(feature = "string_to_string_specialization", since = "1.17.0")] | |
1947 | impl ToString for String { | |
1948 | #[inline] | |
1949 | fn to_string(&self) -> String { | |
1950 | self.to_owned() | |
1951 | } | |
1952 | } | |
1953 | ||
85aaf69f | 1954 | #[stable(feature = "rust1", since = "1.0.0")] |
c34b1796 | 1955 | impl AsRef<str> for String { |
d9579d0f | 1956 | #[inline] |
c34b1796 AL |
1957 | fn as_ref(&self) -> &str { |
1958 | self | |
1959 | } | |
1960 | } | |
1961 | ||
bd371182 AL |
1962 | #[stable(feature = "rust1", since = "1.0.0")] |
1963 | impl AsRef<[u8]> for String { | |
1964 | #[inline] | |
1965 | fn as_ref(&self) -> &[u8] { | |
1966 | self.as_bytes() | |
1967 | } | |
1968 | } | |
1969 | ||
c34b1796 AL |
1970 | #[stable(feature = "rust1", since = "1.0.0")] |
1971 | impl<'a> From<&'a str> for String { | |
c34b1796 | 1972 | fn from(s: &'a str) -> String { |
54a0048b | 1973 | s.to_owned() |
c34b1796 AL |
1974 | } |
1975 | } | |
1976 | ||
c30ab7b3 SL |
1977 | #[stable(feature = "string_from_cow_str", since = "1.14.0")] |
1978 | impl<'a> From<Cow<'a, str>> for String { | |
1979 | fn from(s: Cow<'a, str>) -> String { | |
1980 | s.into_owned() | |
1981 | } | |
1982 | } | |
1983 | ||
c34b1796 AL |
1984 | #[stable(feature = "rust1", since = "1.0.0")] |
1985 | impl<'a> From<&'a str> for Cow<'a, str> { | |
1986 | #[inline] | |
1987 | fn from(s: &'a str) -> Cow<'a, str> { | |
1988 | Cow::Borrowed(s) | |
1989 | } | |
1990 | } | |
1991 | ||
1992 | #[stable(feature = "rust1", since = "1.0.0")] | |
1993 | impl<'a> From<String> for Cow<'a, str> { | |
1994 | #[inline] | |
1995 | fn from(s: String) -> Cow<'a, str> { | |
1996 | Cow::Owned(s) | |
1997 | } | |
1998 | } | |
1999 | ||
5bcae85e SL |
2000 | #[stable(feature = "cow_str_from_iter", since = "1.12.0")] |
2001 | impl<'a> FromIterator<char> for Cow<'a, str> { | |
2002 | fn from_iter<I: IntoIterator<Item = char>>(it: I) -> Cow<'a, str> { | |
2003 | Cow::Owned(FromIterator::from_iter(it)) | |
2004 | } | |
2005 | } | |
2006 | ||
2007 | #[stable(feature = "cow_str_from_iter", since = "1.12.0")] | |
2008 | impl<'a, 'b> FromIterator<&'b str> for Cow<'a, str> { | |
2009 | fn from_iter<I: IntoIterator<Item = &'b str>>(it: I) -> Cow<'a, str> { | |
2010 | Cow::Owned(FromIterator::from_iter(it)) | |
2011 | } | |
2012 | } | |
2013 | ||
2014 | #[stable(feature = "cow_str_from_iter", since = "1.12.0")] | |
2015 | impl<'a> FromIterator<String> for Cow<'a, str> { | |
2016 | fn from_iter<I: IntoIterator<Item = String>>(it: I) -> Cow<'a, str> { | |
2017 | Cow::Owned(FromIterator::from_iter(it)) | |
2018 | } | |
2019 | } | |
2020 | ||
c30ab7b3 SL |
2021 | #[stable(feature = "from_string_for_vec_u8", since = "1.14.0")] |
2022 | impl From<String> for Vec<u8> { | |
32a655c1 | 2023 | fn from(string: String) -> Vec<u8> { |
c30ab7b3 | 2024 | string.into_bytes() |
c34b1796 AL |
2025 | } |
2026 | } | |
2027 | ||
85aaf69f SL |
2028 | #[stable(feature = "rust1", since = "1.0.0")] |
2029 | impl fmt::Write for String { | |
2030 | #[inline] | |
1a4d82fc JJ |
2031 | fn write_str(&mut self, s: &str) -> fmt::Result { |
2032 | self.push_str(s); | |
2033 | Ok(()) | |
2034 | } | |
d9579d0f AL |
2035 | |
2036 | #[inline] | |
2037 | fn write_char(&mut self, c: char) -> fmt::Result { | |
2038 | self.push(c); | |
2039 | Ok(()) | |
2040 | } | |
2041 | } | |
2042 | ||
2043 | /// A draining iterator for `String`. | |
7453a54e SL |
2044 | /// |
2045 | /// This struct is created by the [`drain()`] method on [`String`]. See its | |
2046 | /// documentation for more. | |
2047 | /// | |
2048 | /// [`drain()`]: struct.String.html#method.drain | |
2049 | /// [`String`]: struct.String.html | |
92a42be0 | 2050 | #[stable(feature = "drain", since = "1.6.0")] |
d9579d0f AL |
2051 | pub struct Drain<'a> { |
2052 | /// Will be used as &'a mut String in the destructor | |
2053 | string: *mut String, | |
2054 | /// Start of part to remove | |
2055 | start: usize, | |
2056 | /// End of part to remove | |
2057 | end: usize, | |
2058 | /// Current remaining range to remove | |
2059 | iter: Chars<'a>, | |
2060 | } | |
2061 | ||
8bb4bdeb XL |
2062 | #[stable(feature = "collection_debug", since = "1.17.0")] |
2063 | impl<'a> fmt::Debug for Drain<'a> { | |
2064 | fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { | |
2065 | f.pad("Drain { .. }") | |
2066 | } | |
2067 | } | |
2068 | ||
92a42be0 | 2069 | #[stable(feature = "drain", since = "1.6.0")] |
d9579d0f | 2070 | unsafe impl<'a> Sync for Drain<'a> {} |
92a42be0 | 2071 | #[stable(feature = "drain", since = "1.6.0")] |
d9579d0f AL |
2072 | unsafe impl<'a> Send for Drain<'a> {} |
2073 | ||
92a42be0 | 2074 | #[stable(feature = "drain", since = "1.6.0")] |
d9579d0f AL |
2075 | impl<'a> Drop for Drain<'a> { |
2076 | fn drop(&mut self) { | |
2077 | unsafe { | |
2078 | // Use Vec::drain. "Reaffirm" the bounds checks to avoid | |
2079 | // panic code being inserted again. | |
2080 | let self_vec = (*self.string).as_mut_vec(); | |
2081 | if self.start <= self.end && self.end <= self_vec.len() { | |
2082 | self_vec.drain(self.start..self.end); | |
2083 | } | |
2084 | } | |
2085 | } | |
2086 | } | |
2087 | ||
92a42be0 | 2088 | #[stable(feature = "drain", since = "1.6.0")] |
d9579d0f AL |
2089 | impl<'a> Iterator for Drain<'a> { |
2090 | type Item = char; | |
2091 | ||
2092 | #[inline] | |
2093 | fn next(&mut self) -> Option<char> { | |
2094 | self.iter.next() | |
2095 | } | |
2096 | ||
2097 | fn size_hint(&self) -> (usize, Option<usize>) { | |
2098 | self.iter.size_hint() | |
2099 | } | |
2100 | } | |
2101 | ||
92a42be0 | 2102 | #[stable(feature = "drain", since = "1.6.0")] |
d9579d0f AL |
2103 | impl<'a> DoubleEndedIterator for Drain<'a> { |
2104 | #[inline] | |
2105 | fn next_back(&mut self) -> Option<char> { | |
2106 | self.iter.next_back() | |
2107 | } | |
1a4d82fc | 2108 | } |
9e0c209e SL |
2109 | |
2110 | #[unstable(feature = "fused", issue = "35602")] | |
2111 | impl<'a> FusedIterator for Drain<'a> {} |