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