]>
Commit | Line | Data |
---|---|---|
1 | // Copyright 2012-2017 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. | |
10 | ||
11 | //! Unicode string slices. | |
12 | //! | |
13 | //! *[See also the `str` primitive type](../../std/primitive.str.html).* | |
14 | //! | |
15 | //! The `&str` type is one of the two main string types, the other being `String`. | |
16 | //! Unlike its `String` counterpart, its contents are borrowed. | |
17 | //! | |
18 | //! # Basic Usage | |
19 | //! | |
20 | //! A basic string declaration of `&str` type: | |
21 | //! | |
22 | //! ``` | |
23 | //! let hello_world = "Hello, World!"; | |
24 | //! ``` | |
25 | //! | |
26 | //! Here we have declared a string literal, also known as a string slice. | |
27 | //! String literals have a static lifetime, which means the string `hello_world` | |
28 | //! is guaranteed to be valid for the duration of the entire program. | |
29 | //! We can explicitly specify `hello_world`'s lifetime as well: | |
30 | //! | |
31 | //! ``` | |
32 | //! let hello_world: &'static str = "Hello, world!"; | |
33 | //! ``` | |
34 | ||
35 | #![stable(feature = "rust1", since = "1.0.0")] | |
36 | ||
37 | // Many of the usings in this module are only used in the test configuration. | |
38 | // It's cleaner to just turn off the unused_imports warning than to fix them. | |
39 | #![allow(unused_imports)] | |
40 | ||
41 | use core::fmt; | |
42 | use core::str as core_str; | |
43 | use core::str::pattern::Pattern; | |
44 | use core::str::pattern::{Searcher, ReverseSearcher, DoubleEndedSearcher}; | |
45 | use core::mem; | |
46 | use core::ptr; | |
47 | use core::iter::FusedIterator; | |
48 | use core::unicode::conversions; | |
49 | ||
50 | use borrow::{Borrow, ToOwned}; | |
51 | use boxed::Box; | |
52 | use slice::{SliceConcatExt, SliceIndex}; | |
53 | use string::String; | |
54 | use vec::Vec; | |
55 | ||
56 | #[stable(feature = "rust1", since = "1.0.0")] | |
57 | pub use core::str::{FromStr, Utf8Error}; | |
58 | #[allow(deprecated)] | |
59 | #[stable(feature = "rust1", since = "1.0.0")] | |
60 | pub use core::str::{Lines, LinesAny}; | |
61 | #[stable(feature = "rust1", since = "1.0.0")] | |
62 | pub use core::str::{Split, RSplit}; | |
63 | #[stable(feature = "rust1", since = "1.0.0")] | |
64 | pub use core::str::{SplitN, RSplitN}; | |
65 | #[stable(feature = "rust1", since = "1.0.0")] | |
66 | pub use core::str::{SplitTerminator, RSplitTerminator}; | |
67 | #[stable(feature = "rust1", since = "1.0.0")] | |
68 | pub use core::str::{Matches, RMatches}; | |
69 | #[stable(feature = "rust1", since = "1.0.0")] | |
70 | pub use core::str::{MatchIndices, RMatchIndices}; | |
71 | #[stable(feature = "rust1", since = "1.0.0")] | |
72 | pub use core::str::{from_utf8, from_utf8_mut, Chars, CharIndices, Bytes}; | |
73 | #[stable(feature = "rust1", since = "1.0.0")] | |
74 | pub use core::str::{from_utf8_unchecked, from_utf8_unchecked_mut, ParseBoolError}; | |
75 | #[stable(feature = "rust1", since = "1.0.0")] | |
76 | pub use core::str::SplitWhitespace; | |
77 | #[stable(feature = "rust1", since = "1.0.0")] | |
78 | pub use core::str::pattern; | |
79 | #[stable(feature = "encode_utf16", since = "1.8.0")] | |
80 | pub use core::str::EncodeUtf16; | |
81 | #[unstable(feature = "split_ascii_whitespace", issue = "48656")] | |
82 | pub use core::str::SplitAsciiWhitespace; | |
83 | ||
84 | #[unstable(feature = "slice_concat_ext", | |
85 | reason = "trait should not have to exist", | |
86 | issue = "27747")] | |
87 | impl<S: Borrow<str>> SliceConcatExt<str> for [S] { | |
88 | type Output = String; | |
89 | ||
90 | fn concat(&self) -> String { | |
91 | self.join("") | |
92 | } | |
93 | ||
94 | fn join(&self, sep: &str) -> String { | |
95 | unsafe { | |
96 | String::from_utf8_unchecked( join_generic_copy(self, sep.as_bytes()) ) | |
97 | } | |
98 | } | |
99 | ||
100 | fn connect(&self, sep: &str) -> String { | |
101 | self.join(sep) | |
102 | } | |
103 | } | |
104 | ||
105 | macro_rules! spezialize_for_lengths { | |
106 | ($separator:expr, $target:expr, $iter:expr; $($num:expr),*) => { | |
107 | let mut target = $target; | |
108 | let iter = $iter; | |
109 | let sep_bytes = $separator; | |
110 | match $separator.len() { | |
111 | $( | |
112 | // loops with hardcoded sizes run much faster | |
113 | // specialize the cases with small separator lengths | |
114 | $num => { | |
115 | for s in iter { | |
116 | copy_slice_and_advance!(target, sep_bytes); | |
117 | copy_slice_and_advance!(target, s.borrow().as_ref()); | |
118 | } | |
119 | }, | |
120 | )* | |
121 | _ => { | |
122 | // arbitrary non-zero size fallback | |
123 | for s in iter { | |
124 | copy_slice_and_advance!(target, sep_bytes); | |
125 | copy_slice_and_advance!(target, s.borrow().as_ref()); | |
126 | } | |
127 | } | |
128 | } | |
129 | }; | |
130 | } | |
131 | ||
132 | macro_rules! copy_slice_and_advance { | |
133 | ($target:expr, $bytes:expr) => { | |
134 | let len = $bytes.len(); | |
135 | let (head, tail) = {$target}.split_at_mut(len); | |
136 | head.copy_from_slice($bytes); | |
137 | $target = tail; | |
138 | } | |
139 | } | |
140 | ||
141 | // Optimized join implementation that works for both Vec<T> (T: Copy) and String's inner vec | |
142 | // Currently (2018-05-13) there is a bug with type inference and specialization (see issue #36262) | |
143 | // For this reason SliceConcatExt<T> is not specialized for T: Copy and SliceConcatExt<str> is the | |
144 | // only user of this function. It is left in place for the time when that is fixed. | |
145 | // | |
146 | // the bounds for String-join are S: Borrow<str> and for Vec-join Borrow<[T]> | |
147 | // [T] and str both impl AsRef<[T]> for some T | |
148 | // => s.borrow().as_ref() and we always have slices | |
149 | fn join_generic_copy<B, T, S>(slice: &[S], sep: &[T]) -> Vec<T> | |
150 | where | |
151 | T: Copy, | |
152 | B: AsRef<[T]> + ?Sized, | |
153 | S: Borrow<B>, | |
154 | { | |
155 | let sep_len = sep.len(); | |
156 | let mut iter = slice.iter(); | |
157 | ||
158 | // the first slice is the only one without a separator preceding it | |
159 | let first = match iter.next() { | |
160 | Some(first) => first, | |
161 | None => return vec![], | |
162 | }; | |
163 | ||
164 | // compute the exact total length of the joined Vec | |
165 | // if the `len` calculation overflows, we'll panic | |
166 | // we would have run out of memory anyway and the rest of the function requires | |
167 | // the entire Vec pre-allocated for safety | |
168 | let len = sep_len.checked_mul(iter.len()).and_then(|n| { | |
169 | slice.iter() | |
170 | .map(|s| s.borrow().as_ref().len()) | |
171 | .try_fold(n, usize::checked_add) | |
172 | }).expect("attempt to join into collection with len > usize::MAX"); | |
173 | ||
174 | // crucial for safety | |
175 | let mut result = Vec::with_capacity(len); | |
176 | assert!(result.capacity() >= len); | |
177 | ||
178 | result.extend_from_slice(first.borrow().as_ref()); | |
179 | ||
180 | unsafe { | |
181 | { | |
182 | let pos = result.len(); | |
183 | let target = result.get_unchecked_mut(pos..len); | |
184 | ||
185 | // copy separator and slices over without bounds checks | |
186 | // generate loops with hardcoded offsets for small separators | |
187 | // massive improvements possible (~ x2) | |
188 | spezialize_for_lengths!(sep, target, iter; 0, 1, 2, 3, 4); | |
189 | } | |
190 | result.set_len(len); | |
191 | } | |
192 | result | |
193 | } | |
194 | ||
195 | #[stable(feature = "rust1", since = "1.0.0")] | |
196 | impl Borrow<str> for String { | |
197 | #[inline] | |
198 | fn borrow(&self) -> &str { | |
199 | &self[..] | |
200 | } | |
201 | } | |
202 | ||
203 | #[stable(feature = "rust1", since = "1.0.0")] | |
204 | impl ToOwned for str { | |
205 | type Owned = String; | |
206 | #[inline] | |
207 | fn to_owned(&self) -> String { | |
208 | unsafe { String::from_utf8_unchecked(self.as_bytes().to_owned()) } | |
209 | } | |
210 | ||
211 | fn clone_into(&self, target: &mut String) { | |
212 | let mut b = mem::replace(target, String::new()).into_bytes(); | |
213 | self.as_bytes().clone_into(&mut b); | |
214 | *target = unsafe { String::from_utf8_unchecked(b) } | |
215 | } | |
216 | } | |
217 | ||
218 | /// Methods for string slices. | |
219 | #[lang = "str_alloc"] | |
220 | #[cfg(not(test))] | |
221 | impl str { | |
222 | /// Converts a `Box<str>` into a `Box<[u8]>` without copying or allocating. | |
223 | /// | |
224 | /// # Examples | |
225 | /// | |
226 | /// Basic usage: | |
227 | /// | |
228 | /// ``` | |
229 | /// let s = "this is a string"; | |
230 | /// let boxed_str = s.to_owned().into_boxed_str(); | |
231 | /// let boxed_bytes = boxed_str.into_boxed_bytes(); | |
232 | /// assert_eq!(*boxed_bytes, *s.as_bytes()); | |
233 | /// ``` | |
234 | #[stable(feature = "str_box_extras", since = "1.20.0")] | |
235 | #[inline] | |
236 | pub fn into_boxed_bytes(self: Box<str>) -> Box<[u8]> { | |
237 | self.into() | |
238 | } | |
239 | ||
240 | /// Replaces all matches of a pattern with another string. | |
241 | /// | |
242 | /// `replace` creates a new [`String`], and copies the data from this string slice into it. | |
243 | /// While doing so, it attempts to find matches of a pattern. If it finds any, it | |
244 | /// replaces them with the replacement string slice. | |
245 | /// | |
246 | /// [`String`]: string/struct.String.html | |
247 | /// | |
248 | /// # Examples | |
249 | /// | |
250 | /// Basic usage: | |
251 | /// | |
252 | /// ``` | |
253 | /// let s = "this is old"; | |
254 | /// | |
255 | /// assert_eq!("this is new", s.replace("old", "new")); | |
256 | /// ``` | |
257 | /// | |
258 | /// When the pattern doesn't match: | |
259 | /// | |
260 | /// ``` | |
261 | /// let s = "this is old"; | |
262 | /// assert_eq!(s, s.replace("cookie monster", "little lamb")); | |
263 | /// ``` | |
264 | #[must_use = "this returns the replaced string as a new allocation, \ | |
265 | without modifying the original"] | |
266 | #[stable(feature = "rust1", since = "1.0.0")] | |
267 | #[inline] | |
268 | pub fn replace<'a, P: Pattern<'a>>(&'a self, from: P, to: &str) -> String { | |
269 | let mut result = String::new(); | |
270 | let mut last_end = 0; | |
271 | for (start, part) in self.match_indices(from) { | |
272 | result.push_str(unsafe { self.get_unchecked(last_end..start) }); | |
273 | result.push_str(to); | |
274 | last_end = start + part.len(); | |
275 | } | |
276 | result.push_str(unsafe { self.get_unchecked(last_end..self.len()) }); | |
277 | result | |
278 | } | |
279 | ||
280 | /// Replaces first N matches of a pattern with another string. | |
281 | /// | |
282 | /// `replacen` creates a new [`String`], and copies the data from this string slice into it. | |
283 | /// While doing so, it attempts to find matches of a pattern. If it finds any, it | |
284 | /// replaces them with the replacement string slice at most `count` times. | |
285 | /// | |
286 | /// [`String`]: string/struct.String.html | |
287 | /// | |
288 | /// # Examples | |
289 | /// | |
290 | /// Basic usage: | |
291 | /// | |
292 | /// ``` | |
293 | /// let s = "foo foo 123 foo"; | |
294 | /// assert_eq!("new new 123 foo", s.replacen("foo", "new", 2)); | |
295 | /// assert_eq!("faa fao 123 foo", s.replacen('o', "a", 3)); | |
296 | /// assert_eq!("foo foo new23 foo", s.replacen(char::is_numeric, "new", 1)); | |
297 | /// ``` | |
298 | /// | |
299 | /// When the pattern doesn't match: | |
300 | /// | |
301 | /// ``` | |
302 | /// let s = "this is old"; | |
303 | /// assert_eq!(s, s.replacen("cookie monster", "little lamb", 10)); | |
304 | /// ``` | |
305 | #[must_use = "this returns the replaced string as a new allocation, \ | |
306 | without modifying the original"] | |
307 | #[stable(feature = "str_replacen", since = "1.16.0")] | |
308 | pub fn replacen<'a, P: Pattern<'a>>(&'a self, pat: P, to: &str, count: usize) -> String { | |
309 | // Hope to reduce the times of re-allocation | |
310 | let mut result = String::with_capacity(32); | |
311 | let mut last_end = 0; | |
312 | for (start, part) in self.match_indices(pat).take(count) { | |
313 | result.push_str(unsafe { self.get_unchecked(last_end..start) }); | |
314 | result.push_str(to); | |
315 | last_end = start + part.len(); | |
316 | } | |
317 | result.push_str(unsafe { self.get_unchecked(last_end..self.len()) }); | |
318 | result | |
319 | } | |
320 | ||
321 | /// Returns the lowercase equivalent of this string slice, as a new [`String`]. | |
322 | /// | |
323 | /// 'Lowercase' is defined according to the terms of the Unicode Derived Core Property | |
324 | /// `Lowercase`. | |
325 | /// | |
326 | /// Since some characters can expand into multiple characters when changing | |
327 | /// the case, this function returns a [`String`] instead of modifying the | |
328 | /// parameter in-place. | |
329 | /// | |
330 | /// [`String`]: string/struct.String.html | |
331 | /// | |
332 | /// # Examples | |
333 | /// | |
334 | /// Basic usage: | |
335 | /// | |
336 | /// ``` | |
337 | /// let s = "HELLO"; | |
338 | /// | |
339 | /// assert_eq!("hello", s.to_lowercase()); | |
340 | /// ``` | |
341 | /// | |
342 | /// A tricky example, with sigma: | |
343 | /// | |
344 | /// ``` | |
345 | /// let sigma = "Σ"; | |
346 | /// | |
347 | /// assert_eq!("σ", sigma.to_lowercase()); | |
348 | /// | |
349 | /// // but at the end of a word, it's ς, not σ: | |
350 | /// let odysseus = "ὈΔΥΣΣΕΎΣ"; | |
351 | /// | |
352 | /// assert_eq!("ὀδυσσεύς", odysseus.to_lowercase()); | |
353 | /// ``` | |
354 | /// | |
355 | /// Languages without case are not changed: | |
356 | /// | |
357 | /// ``` | |
358 | /// let new_year = "农历新年"; | |
359 | /// | |
360 | /// assert_eq!(new_year, new_year.to_lowercase()); | |
361 | /// ``` | |
362 | #[stable(feature = "unicode_case_mapping", since = "1.2.0")] | |
363 | pub fn to_lowercase(&self) -> String { | |
364 | let mut s = String::with_capacity(self.len()); | |
365 | for (i, c) in self[..].char_indices() { | |
366 | if c == 'Σ' { | |
367 | // Σ maps to σ, except at the end of a word where it maps to ς. | |
368 | // This is the only conditional (contextual) but language-independent mapping | |
369 | // in `SpecialCasing.txt`, | |
370 | // so hard-code it rather than have a generic "condition" mechanism. | |
371 | // See https://github.com/rust-lang/rust/issues/26035 | |
372 | map_uppercase_sigma(self, i, &mut s) | |
373 | } else { | |
374 | match conversions::to_lower(c) { | |
375 | [a, '\0', _] => s.push(a), | |
376 | [a, b, '\0'] => { | |
377 | s.push(a); | |
378 | s.push(b); | |
379 | } | |
380 | [a, b, c] => { | |
381 | s.push(a); | |
382 | s.push(b); | |
383 | s.push(c); | |
384 | } | |
385 | } | |
386 | } | |
387 | } | |
388 | return s; | |
389 | ||
390 | fn map_uppercase_sigma(from: &str, i: usize, to: &mut String) { | |
391 | // See http://www.unicode.org/versions/Unicode7.0.0/ch03.pdf#G33992 | |
392 | // for the definition of `Final_Sigma`. | |
393 | debug_assert!('Σ'.len_utf8() == 2); | |
394 | let is_word_final = case_ignoreable_then_cased(from[..i].chars().rev()) && | |
395 | !case_ignoreable_then_cased(from[i + 2..].chars()); | |
396 | to.push_str(if is_word_final { "ς" } else { "σ" }); | |
397 | } | |
398 | ||
399 | fn case_ignoreable_then_cased<I: Iterator<Item = char>>(iter: I) -> bool { | |
400 | use core::unicode::derived_property::{Cased, Case_Ignorable}; | |
401 | match iter.skip_while(|&c| Case_Ignorable(c)).next() { | |
402 | Some(c) => Cased(c), | |
403 | None => false, | |
404 | } | |
405 | } | |
406 | } | |
407 | ||
408 | /// Returns the uppercase equivalent of this string slice, as a new [`String`]. | |
409 | /// | |
410 | /// 'Uppercase' is defined according to the terms of the Unicode Derived Core Property | |
411 | /// `Uppercase`. | |
412 | /// | |
413 | /// Since some characters can expand into multiple characters when changing | |
414 | /// the case, this function returns a [`String`] instead of modifying the | |
415 | /// parameter in-place. | |
416 | /// | |
417 | /// [`String`]: string/struct.String.html | |
418 | /// | |
419 | /// # Examples | |
420 | /// | |
421 | /// Basic usage: | |
422 | /// | |
423 | /// ``` | |
424 | /// let s = "hello"; | |
425 | /// | |
426 | /// assert_eq!("HELLO", s.to_uppercase()); | |
427 | /// ``` | |
428 | /// | |
429 | /// Scripts without case are not changed: | |
430 | /// | |
431 | /// ``` | |
432 | /// let new_year = "农历新年"; | |
433 | /// | |
434 | /// assert_eq!(new_year, new_year.to_uppercase()); | |
435 | /// ``` | |
436 | #[stable(feature = "unicode_case_mapping", since = "1.2.0")] | |
437 | pub fn to_uppercase(&self) -> String { | |
438 | let mut s = String::with_capacity(self.len()); | |
439 | for c in self[..].chars() { | |
440 | match conversions::to_upper(c) { | |
441 | [a, '\0', _] => s.push(a), | |
442 | [a, b, '\0'] => { | |
443 | s.push(a); | |
444 | s.push(b); | |
445 | } | |
446 | [a, b, c] => { | |
447 | s.push(a); | |
448 | s.push(b); | |
449 | s.push(c); | |
450 | } | |
451 | } | |
452 | } | |
453 | return s; | |
454 | } | |
455 | ||
456 | /// Escapes each char in `s` with [`char::escape_debug`]. | |
457 | /// | |
458 | /// Note: only extended grapheme codepoints that begin the string will be | |
459 | /// escaped. | |
460 | /// | |
461 | /// [`char::escape_debug`]: primitive.char.html#method.escape_debug | |
462 | #[unstable(feature = "str_escape", | |
463 | reason = "return type may change to be an iterator", | |
464 | issue = "27791")] | |
465 | pub fn escape_debug(&self) -> String { | |
466 | let mut string = String::with_capacity(self.len()); | |
467 | let mut chars = self.chars(); | |
468 | if let Some(first) = chars.next() { | |
469 | string.extend(first.escape_debug_ext(true)) | |
470 | } | |
471 | string.extend(chars.flat_map(|c| c.escape_debug_ext(false))); | |
472 | string | |
473 | } | |
474 | ||
475 | /// Escapes each char in `s` with [`char::escape_default`]. | |
476 | /// | |
477 | /// [`char::escape_default`]: primitive.char.html#method.escape_default | |
478 | #[unstable(feature = "str_escape", | |
479 | reason = "return type may change to be an iterator", | |
480 | issue = "27791")] | |
481 | pub fn escape_default(&self) -> String { | |
482 | self.chars().flat_map(|c| c.escape_default()).collect() | |
483 | } | |
484 | ||
485 | /// Escapes each char in `s` with [`char::escape_unicode`]. | |
486 | /// | |
487 | /// [`char::escape_unicode`]: primitive.char.html#method.escape_unicode | |
488 | #[unstable(feature = "str_escape", | |
489 | reason = "return type may change to be an iterator", | |
490 | issue = "27791")] | |
491 | pub fn escape_unicode(&self) -> String { | |
492 | self.chars().flat_map(|c| c.escape_unicode()).collect() | |
493 | } | |
494 | ||
495 | /// Converts a [`Box<str>`] into a [`String`] without copying or allocating. | |
496 | /// | |
497 | /// [`String`]: string/struct.String.html | |
498 | /// [`Box<str>`]: boxed/struct.Box.html | |
499 | /// | |
500 | /// # Examples | |
501 | /// | |
502 | /// Basic usage: | |
503 | /// | |
504 | /// ``` | |
505 | /// let string = String::from("birthday gift"); | |
506 | /// let boxed_str = string.clone().into_boxed_str(); | |
507 | /// | |
508 | /// assert_eq!(boxed_str.into_string(), string); | |
509 | /// ``` | |
510 | #[stable(feature = "box_str", since = "1.4.0")] | |
511 | #[inline] | |
512 | pub fn into_string(self: Box<str>) -> String { | |
513 | let slice = Box::<[u8]>::from(self); | |
514 | unsafe { String::from_utf8_unchecked(slice.into_vec()) } | |
515 | } | |
516 | ||
517 | /// Creates a new [`String`] by repeating a string `n` times. | |
518 | /// | |
519 | /// # Panics | |
520 | /// | |
521 | /// This function will panic if the capacity would overflow. | |
522 | /// | |
523 | /// [`String`]: string/struct.String.html | |
524 | /// | |
525 | /// # Examples | |
526 | /// | |
527 | /// Basic usage: | |
528 | /// | |
529 | /// ``` | |
530 | /// assert_eq!("abc".repeat(4), String::from("abcabcabcabc")); | |
531 | /// ``` | |
532 | /// | |
533 | /// A panic upon overflow: | |
534 | /// | |
535 | /// ```should_panic | |
536 | /// fn main() { | |
537 | /// // this will panic at runtime | |
538 | /// "0123456789abcdef".repeat(usize::max_value()); | |
539 | /// } | |
540 | /// ``` | |
541 | #[stable(feature = "repeat_str", since = "1.16.0")] | |
542 | pub fn repeat(&self, n: usize) -> String { | |
543 | unsafe { String::from_utf8_unchecked(self.as_bytes().repeat(n)) } | |
544 | } | |
545 | ||
546 | /// Returns a copy of this string where each character is mapped to its | |
547 | /// ASCII upper case equivalent. | |
548 | /// | |
549 | /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', | |
550 | /// but non-ASCII letters are unchanged. | |
551 | /// | |
552 | /// To uppercase the value in-place, use [`make_ascii_uppercase`]. | |
553 | /// | |
554 | /// To uppercase ASCII characters in addition to non-ASCII characters, use | |
555 | /// [`to_uppercase`]. | |
556 | /// | |
557 | /// # Examples | |
558 | /// | |
559 | /// ``` | |
560 | /// let s = "Grüße, Jürgen ❤"; | |
561 | /// | |
562 | /// assert_eq!("GRüßE, JüRGEN ❤", s.to_ascii_uppercase()); | |
563 | /// ``` | |
564 | /// | |
565 | /// [`make_ascii_uppercase`]: #method.make_ascii_uppercase | |
566 | /// [`to_uppercase`]: #method.to_uppercase | |
567 | #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] | |
568 | #[inline] | |
569 | pub fn to_ascii_uppercase(&self) -> String { | |
570 | let mut bytes = self.as_bytes().to_vec(); | |
571 | bytes.make_ascii_uppercase(); | |
572 | // make_ascii_uppercase() preserves the UTF-8 invariant. | |
573 | unsafe { String::from_utf8_unchecked(bytes) } | |
574 | } | |
575 | ||
576 | /// Returns a copy of this string where each character is mapped to its | |
577 | /// ASCII lower case equivalent. | |
578 | /// | |
579 | /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', | |
580 | /// but non-ASCII letters are unchanged. | |
581 | /// | |
582 | /// To lowercase the value in-place, use [`make_ascii_lowercase`]. | |
583 | /// | |
584 | /// To lowercase ASCII characters in addition to non-ASCII characters, use | |
585 | /// [`to_lowercase`]. | |
586 | /// | |
587 | /// # Examples | |
588 | /// | |
589 | /// ``` | |
590 | /// let s = "Grüße, Jürgen ❤"; | |
591 | /// | |
592 | /// assert_eq!("grüße, jürgen ❤", s.to_ascii_lowercase()); | |
593 | /// ``` | |
594 | /// | |
595 | /// [`make_ascii_lowercase`]: #method.make_ascii_lowercase | |
596 | /// [`to_lowercase`]: #method.to_lowercase | |
597 | #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] | |
598 | #[inline] | |
599 | pub fn to_ascii_lowercase(&self) -> String { | |
600 | let mut bytes = self.as_bytes().to_vec(); | |
601 | bytes.make_ascii_lowercase(); | |
602 | // make_ascii_lowercase() preserves the UTF-8 invariant. | |
603 | unsafe { String::from_utf8_unchecked(bytes) } | |
604 | } | |
605 | } | |
606 | ||
607 | /// Converts a boxed slice of bytes to a boxed string slice without checking | |
608 | /// that the string contains valid UTF-8. | |
609 | /// | |
610 | /// # Examples | |
611 | /// | |
612 | /// Basic usage: | |
613 | /// | |
614 | /// ``` | |
615 | /// let smile_utf8 = Box::new([226, 152, 186]); | |
616 | /// let smile = unsafe { std::str::from_boxed_utf8_unchecked(smile_utf8) }; | |
617 | /// | |
618 | /// assert_eq!("☺", &*smile); | |
619 | /// ``` | |
620 | #[stable(feature = "str_box_extras", since = "1.20.0")] | |
621 | #[inline] | |
622 | pub unsafe fn from_boxed_utf8_unchecked(v: Box<[u8]>) -> Box<str> { | |
623 | Box::from_raw(Box::into_raw(v) as *mut str) | |
624 | } |