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