1 //! String manipulation.
3 //! For more details, see the [`std::str`] module.
5 //! [`std::str`]: ../../std/str/index.html
7 #![stable(feature = "rust1", since = "1.0.0")]
16 use self::pattern::Pattern;
17 use self::pattern::{DoubleEndedSearcher, ReverseSearcher, Searcher};
19 use crate::char::{self, EscapeDebugExtArgs};
21 use crate::slice::{self, SliceIndex};
25 #[unstable(feature = "str_internals", issue = "none")]
26 #[allow(missing_docs)]
29 #[stable(feature = "rust1", since = "1.0.0")]
30 pub use converts::{from_utf8, from_utf8_unchecked};
32 #[stable(feature = "str_mut_extras", since = "1.20.0")]
33 pub use converts::{from_utf8_mut, from_utf8_unchecked_mut};
35 #[stable(feature = "rust1", since = "1.0.0")]
36 pub use error::{ParseBoolError, Utf8Error};
38 #[stable(feature = "rust1", since = "1.0.0")]
39 pub use traits::FromStr;
41 #[stable(feature = "rust1", since = "1.0.0")]
42 pub use iter::{Bytes, CharIndices, Chars, Lines, SplitWhitespace};
44 #[stable(feature = "rust1", since = "1.0.0")]
46 pub use iter::LinesAny;
48 #[stable(feature = "rust1", since = "1.0.0")]
49 pub use iter::{RSplit, RSplitTerminator, Split, SplitTerminator};
51 #[stable(feature = "rust1", since = "1.0.0")]
52 pub use iter::{RSplitN, SplitN};
54 #[stable(feature = "str_matches", since = "1.2.0")]
55 pub use iter::{Matches, RMatches};
57 #[stable(feature = "str_match_indices", since = "1.5.0")]
58 pub use iter::{MatchIndices, RMatchIndices};
60 #[stable(feature = "encode_utf16", since = "1.8.0")]
61 pub use iter::EncodeUtf16;
63 #[stable(feature = "str_escape", since = "1.34.0")]
64 pub use iter::{EscapeDebug, EscapeDefault, EscapeUnicode};
66 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
67 pub use iter::SplitAsciiWhitespace;
69 #[stable(feature = "split_inclusive", since = "1.51.0")]
70 pub use iter::SplitInclusive;
72 #[unstable(feature = "str_internals", issue = "none")]
73 pub use validations::{next_code_point, utf8_char_width};
75 use iter::MatchIndicesInternal;
76 use iter::SplitInternal;
77 use iter::{MatchesInternal, SplitNInternal};
79 use validations::truncate_to_char_boundary;
84 fn slice_error_fail(s: &str, begin: usize, end: usize) -> ! {
85 const MAX_DISPLAY_LENGTH: usize = 256;
86 let (truncated, s_trunc) = truncate_to_char_boundary(s, MAX_DISPLAY_LENGTH);
87 let ellipsis = if truncated { "[...]" } else { "" };
90 if begin > s.len() || end > s.len() {
91 let oob_index = if begin > s.len() { begin } else { end };
92 panic!("byte index {} is out of bounds of `{}`{}", oob_index, s_trunc, ellipsis);
98 "begin <= end ({} <= {}) when slicing `{}`{}",
105 // 3. character boundary
106 let index = if !s.is_char_boundary(begin) { begin } else { end };
107 // find the character
108 let mut char_start = index;
109 while !s.is_char_boundary(char_start) {
112 // `char_start` must be less than len and a char boundary
113 let ch = s[char_start..].chars().next().unwrap();
114 let char_range = char_start..char_start + ch.len_utf8();
116 "byte index {} is not a char boundary; it is inside {:?} (bytes {:?}) of `{}`{}",
117 index, ch, char_range, s_trunc, ellipsis
124 /// Returns the length of `self`.
126 /// This length is in bytes, not [`char`]s or graphemes. In other words,
127 /// it might not be what a human considers the length of the string.
129 /// [`char`]: prim@char
136 /// let len = "foo".len();
137 /// assert_eq!(3, len);
139 /// assert_eq!("ƒoo".len(), 4); // fancy f!
140 /// assert_eq!("ƒoo".chars().count(), 3);
142 #[stable(feature = "rust1", since = "1.0.0")]
143 #[rustc_const_stable(feature = "const_str_len", since = "1.39.0")]
146 pub const fn len(&self) -> usize {
147 self.as_bytes().len()
150 /// Returns `true` if `self` has a length of zero bytes.
158 /// assert!(s.is_empty());
160 /// let s = "not empty";
161 /// assert!(!s.is_empty());
163 #[stable(feature = "rust1", since = "1.0.0")]
164 #[rustc_const_stable(feature = "const_str_is_empty", since = "1.39.0")]
167 pub const fn is_empty(&self) -> bool {
171 /// Checks that `index`-th byte is the first byte in a UTF-8 code point
172 /// sequence or the end of the string.
174 /// The start and end of the string (when `index == self.len()`) are
175 /// considered to be boundaries.
177 /// Returns `false` if `index` is greater than `self.len()`.
182 /// let s = "Löwe 老虎 Léopard";
183 /// assert!(s.is_char_boundary(0));
185 /// assert!(s.is_char_boundary(6));
186 /// assert!(s.is_char_boundary(s.len()));
188 /// // second byte of `ö`
189 /// assert!(!s.is_char_boundary(2));
191 /// // third byte of `老`
192 /// assert!(!s.is_char_boundary(8));
195 #[stable(feature = "is_char_boundary", since = "1.9.0")]
197 pub fn is_char_boundary(&self, index: usize) -> bool {
199 // Test for 0 explicitly so that it can optimize out the check
200 // easily and skip reading string data for that case.
201 // Note that optimizing `self.get(..index)` relies on this.
206 match self.as_bytes().get(index) {
207 // For `None` we have two options:
209 // - index == self.len()
210 // Empty strings are valid, so return true
211 // - index > self.len()
212 // In this case return false
214 // The check is placed exactly here, because it improves generated
215 // code on higher opt-levels. See PR #84751 for more details.
216 None => index == self.len(),
218 // This is bit magic equivalent to: b < 128 || b >= 192
219 Some(&b) => (b as i8) >= -0x40,
223 /// Converts a string slice to a byte slice. To convert the byte slice back
224 /// into a string slice, use the [`from_utf8`] function.
231 /// let bytes = "bors".as_bytes();
232 /// assert_eq!(b"bors", bytes);
234 #[stable(feature = "rust1", since = "1.0.0")]
235 #[rustc_const_stable(feature = "str_as_bytes", since = "1.39.0")]
238 #[allow(unused_attributes)]
239 pub const fn as_bytes(&self) -> &[u8] {
240 // SAFETY: const sound because we transmute two types with the same layout
241 unsafe { mem::transmute(self) }
244 /// Converts a mutable string slice to a mutable byte slice.
248 /// The caller must ensure that the content of the slice is valid UTF-8
249 /// before the borrow ends and the underlying `str` is used.
251 /// Use of a `str` whose contents are not valid UTF-8 is undefined behavior.
258 /// let mut s = String::from("Hello");
259 /// let bytes = unsafe { s.as_bytes_mut() };
261 /// assert_eq!(b"Hello", bytes);
267 /// let mut s = String::from("🗻∈🌏");
270 /// let bytes = s.as_bytes_mut();
278 /// assert_eq!("🍔∈🌏", s);
280 #[stable(feature = "str_mut_extras", since = "1.20.0")]
283 pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8] {
284 // SAFETY: the cast from `&str` to `&[u8]` is safe since `str`
285 // has the same layout as `&[u8]` (only libstd can make this guarantee).
286 // The pointer dereference is safe since it comes from a mutable reference which
287 // is guaranteed to be valid for writes.
288 unsafe { &mut *(self as *mut str as *mut [u8]) }
291 /// Converts a string slice to a raw pointer.
293 /// As string slices are a slice of bytes, the raw pointer points to a
294 /// [`u8`]. This pointer will be pointing to the first byte of the string
297 /// The caller must ensure that the returned pointer is never written to.
298 /// If you need to mutate the contents of the string slice, use [`as_mut_ptr`].
300 /// [`as_mut_ptr`]: str::as_mut_ptr
308 /// let ptr = s.as_ptr();
310 #[stable(feature = "rust1", since = "1.0.0")]
311 #[rustc_const_stable(feature = "rustc_str_as_ptr", since = "1.32.0")]
314 pub const fn as_ptr(&self) -> *const u8 {
315 self as *const str as *const u8
318 /// Converts a mutable string slice to a raw pointer.
320 /// As string slices are a slice of bytes, the raw pointer points to a
321 /// [`u8`]. This pointer will be pointing to the first byte of the string
324 /// It is your responsibility to make sure that the string slice only gets
325 /// modified in a way that it remains valid UTF-8.
326 #[stable(feature = "str_as_mut_ptr", since = "1.36.0")]
329 pub fn as_mut_ptr(&mut self) -> *mut u8 {
330 self as *mut str as *mut u8
333 /// Returns a subslice of `str`.
335 /// This is the non-panicking alternative to indexing the `str`. Returns
336 /// [`None`] whenever equivalent indexing operation would panic.
341 /// let v = String::from("🗻∈🌏");
343 /// assert_eq!(Some("🗻"), v.get(0..4));
345 /// // indices not on UTF-8 sequence boundaries
346 /// assert!(v.get(1..).is_none());
347 /// assert!(v.get(..8).is_none());
350 /// assert!(v.get(..42).is_none());
352 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
354 pub fn get<I: SliceIndex<str>>(&self, i: I) -> Option<&I::Output> {
358 /// Returns a mutable subslice of `str`.
360 /// This is the non-panicking alternative to indexing the `str`. Returns
361 /// [`None`] whenever equivalent indexing operation would panic.
366 /// let mut v = String::from("hello");
367 /// // correct length
368 /// assert!(v.get_mut(0..5).is_some());
370 /// assert!(v.get_mut(..42).is_none());
371 /// assert_eq!(Some("he"), v.get_mut(0..2).map(|v| &*v));
373 /// assert_eq!("hello", v);
375 /// let s = v.get_mut(0..2);
376 /// let s = s.map(|s| {
377 /// s.make_ascii_uppercase();
380 /// assert_eq!(Some("HE"), s);
382 /// assert_eq!("HEllo", v);
384 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
386 pub fn get_mut<I: SliceIndex<str>>(&mut self, i: I) -> Option<&mut I::Output> {
390 /// Returns an unchecked subslice of `str`.
392 /// This is the unchecked alternative to indexing the `str`.
396 /// Callers of this function are responsible that these preconditions are
399 /// * The starting index must not exceed the ending index;
400 /// * Indexes must be within bounds of the original slice;
401 /// * Indexes must lie on UTF-8 sequence boundaries.
403 /// Failing that, the returned string slice may reference invalid memory or
404 /// violate the invariants communicated by the `str` type.
411 /// assert_eq!("🗻", v.get_unchecked(0..4));
412 /// assert_eq!("∈", v.get_unchecked(4..7));
413 /// assert_eq!("🌏", v.get_unchecked(7..11));
416 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
418 pub unsafe fn get_unchecked<I: SliceIndex<str>>(&self, i: I) -> &I::Output {
419 // SAFETY: the caller must uphold the safety contract for `get_unchecked`;
420 // the slice is dereferenceable because `self` is a safe reference.
421 // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is.
422 unsafe { &*i.get_unchecked(self) }
425 /// Returns a mutable, unchecked subslice of `str`.
427 /// This is the unchecked alternative to indexing the `str`.
431 /// Callers of this function are responsible that these preconditions are
434 /// * The starting index must not exceed the ending index;
435 /// * Indexes must be within bounds of the original slice;
436 /// * Indexes must lie on UTF-8 sequence boundaries.
438 /// Failing that, the returned string slice may reference invalid memory or
439 /// violate the invariants communicated by the `str` type.
444 /// let mut v = String::from("🗻∈🌏");
446 /// assert_eq!("🗻", v.get_unchecked_mut(0..4));
447 /// assert_eq!("∈", v.get_unchecked_mut(4..7));
448 /// assert_eq!("🌏", v.get_unchecked_mut(7..11));
451 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
453 pub unsafe fn get_unchecked_mut<I: SliceIndex<str>>(&mut self, i: I) -> &mut I::Output {
454 // SAFETY: the caller must uphold the safety contract for `get_unchecked_mut`;
455 // the slice is dereferenceable because `self` is a safe reference.
456 // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is.
457 unsafe { &mut *i.get_unchecked_mut(self) }
460 /// Creates a string slice from another string slice, bypassing safety
463 /// This is generally not recommended, use with caution! For a safe
464 /// alternative see [`str`] and [`Index`].
466 /// [`Index`]: crate::ops::Index
468 /// This new slice goes from `begin` to `end`, including `begin` but
471 /// To get a mutable string slice instead, see the
472 /// [`slice_mut_unchecked`] method.
474 /// [`slice_mut_unchecked`]: str::slice_mut_unchecked
478 /// Callers of this function are responsible that three preconditions are
481 /// * `begin` must not exceed `end`.
482 /// * `begin` and `end` must be byte positions within the string slice.
483 /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
490 /// let s = "Löwe 老虎 Léopard";
493 /// assert_eq!("Löwe 老虎 Léopard", s.slice_unchecked(0, 21));
496 /// let s = "Hello, world!";
499 /// assert_eq!("world", s.slice_unchecked(7, 12));
502 #[stable(feature = "rust1", since = "1.0.0")]
503 #[rustc_deprecated(since = "1.29.0", reason = "use `get_unchecked(begin..end)` instead")]
506 pub unsafe fn slice_unchecked(&self, begin: usize, end: usize) -> &str {
507 // SAFETY: the caller must uphold the safety contract for `get_unchecked`;
508 // the slice is dereferenceable because `self` is a safe reference.
509 // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is.
510 unsafe { &*(begin..end).get_unchecked(self) }
513 /// Creates a string slice from another string slice, bypassing safety
515 /// This is generally not recommended, use with caution! For a safe
516 /// alternative see [`str`] and [`IndexMut`].
518 /// [`IndexMut`]: crate::ops::IndexMut
520 /// This new slice goes from `begin` to `end`, including `begin` but
523 /// To get an immutable string slice instead, see the
524 /// [`slice_unchecked`] method.
526 /// [`slice_unchecked`]: str::slice_unchecked
530 /// Callers of this function are responsible that three preconditions are
533 /// * `begin` must not exceed `end`.
534 /// * `begin` and `end` must be byte positions within the string slice.
535 /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
536 #[stable(feature = "str_slice_mut", since = "1.5.0")]
537 #[rustc_deprecated(since = "1.29.0", reason = "use `get_unchecked_mut(begin..end)` instead")]
539 pub unsafe fn slice_mut_unchecked(&mut self, begin: usize, end: usize) -> &mut str {
540 // SAFETY: the caller must uphold the safety contract for `get_unchecked_mut`;
541 // the slice is dereferenceable because `self` is a safe reference.
542 // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is.
543 unsafe { &mut *(begin..end).get_unchecked_mut(self) }
546 /// Divide one string slice into two at an index.
548 /// The argument, `mid`, should be a byte offset from the start of the
549 /// string. It must also be on the boundary of a UTF-8 code point.
551 /// The two slices returned go from the start of the string slice to `mid`,
552 /// and from `mid` to the end of the string slice.
554 /// To get mutable string slices instead, see the [`split_at_mut`]
557 /// [`split_at_mut`]: str::split_at_mut
561 /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
562 /// past the end of the last code point of the string slice.
569 /// let s = "Per Martin-Löf";
571 /// let (first, last) = s.split_at(3);
573 /// assert_eq!("Per", first);
574 /// assert_eq!(" Martin-Löf", last);
578 #[stable(feature = "str_split_at", since = "1.4.0")]
579 pub fn split_at(&self, mid: usize) -> (&str, &str) {
580 // is_char_boundary checks that the index is in [0, .len()]
581 if self.is_char_boundary(mid) {
582 // SAFETY: just checked that `mid` is on a char boundary.
583 unsafe { (self.get_unchecked(0..mid), self.get_unchecked(mid..self.len())) }
585 slice_error_fail(self, 0, mid)
589 /// Divide one mutable string slice into two at an index.
591 /// The argument, `mid`, should be a byte offset from the start of the
592 /// string. It must also be on the boundary of a UTF-8 code point.
594 /// The two slices returned go from the start of the string slice to `mid`,
595 /// and from `mid` to the end of the string slice.
597 /// To get immutable string slices instead, see the [`split_at`] method.
599 /// [`split_at`]: str::split_at
603 /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
604 /// past the end of the last code point of the string slice.
611 /// let mut s = "Per Martin-Löf".to_string();
613 /// let (first, last) = s.split_at_mut(3);
614 /// first.make_ascii_uppercase();
615 /// assert_eq!("PER", first);
616 /// assert_eq!(" Martin-Löf", last);
618 /// assert_eq!("PER Martin-Löf", s);
622 #[stable(feature = "str_split_at", since = "1.4.0")]
623 pub fn split_at_mut(&mut self, mid: usize) -> (&mut str, &mut str) {
624 // is_char_boundary checks that the index is in [0, .len()]
625 if self.is_char_boundary(mid) {
626 let len = self.len();
627 let ptr = self.as_mut_ptr();
628 // SAFETY: just checked that `mid` is on a char boundary.
631 from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, mid)),
632 from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr.add(mid), len - mid)),
636 slice_error_fail(self, 0, mid)
640 /// Returns an iterator over the [`char`]s of a string slice.
642 /// As a string slice consists of valid UTF-8, we can iterate through a
643 /// string slice by [`char`]. This method returns such an iterator.
645 /// It's important to remember that [`char`] represents a Unicode Scalar
646 /// Value, and might not match your idea of what a 'character' is. Iteration
647 /// over grapheme clusters may be what you actually want. This functionality
648 /// is not provided by Rust's standard library, check crates.io instead.
655 /// let word = "goodbye";
657 /// let count = word.chars().count();
658 /// assert_eq!(7, count);
660 /// let mut chars = word.chars();
662 /// assert_eq!(Some('g'), chars.next());
663 /// assert_eq!(Some('o'), chars.next());
664 /// assert_eq!(Some('o'), chars.next());
665 /// assert_eq!(Some('d'), chars.next());
666 /// assert_eq!(Some('b'), chars.next());
667 /// assert_eq!(Some('y'), chars.next());
668 /// assert_eq!(Some('e'), chars.next());
670 /// assert_eq!(None, chars.next());
673 /// Remember, [`char`]s might not match your intuition about characters:
675 /// [`char`]: prim@char
680 /// let mut chars = y.chars();
682 /// assert_eq!(Some('y'), chars.next()); // not 'y̆'
683 /// assert_eq!(Some('\u{0306}'), chars.next());
685 /// assert_eq!(None, chars.next());
687 #[stable(feature = "rust1", since = "1.0.0")]
689 pub fn chars(&self) -> Chars<'_> {
690 Chars { iter: self.as_bytes().iter() }
693 /// Returns an iterator over the [`char`]s of a string slice, and their
696 /// As a string slice consists of valid UTF-8, we can iterate through a
697 /// string slice by [`char`]. This method returns an iterator of both
698 /// these [`char`]s, as well as their byte positions.
700 /// The iterator yields tuples. The position is first, the [`char`] is
708 /// let word = "goodbye";
710 /// let count = word.char_indices().count();
711 /// assert_eq!(7, count);
713 /// let mut char_indices = word.char_indices();
715 /// assert_eq!(Some((0, 'g')), char_indices.next());
716 /// assert_eq!(Some((1, 'o')), char_indices.next());
717 /// assert_eq!(Some((2, 'o')), char_indices.next());
718 /// assert_eq!(Some((3, 'd')), char_indices.next());
719 /// assert_eq!(Some((4, 'b')), char_indices.next());
720 /// assert_eq!(Some((5, 'y')), char_indices.next());
721 /// assert_eq!(Some((6, 'e')), char_indices.next());
723 /// assert_eq!(None, char_indices.next());
726 /// Remember, [`char`]s might not match your intuition about characters:
728 /// [`char`]: prim@char
731 /// let yes = "y̆es";
733 /// let mut char_indices = yes.char_indices();
735 /// assert_eq!(Some((0, 'y')), char_indices.next()); // not (0, 'y̆')
736 /// assert_eq!(Some((1, '\u{0306}')), char_indices.next());
738 /// // note the 3 here - the last character took up two bytes
739 /// assert_eq!(Some((3, 'e')), char_indices.next());
740 /// assert_eq!(Some((4, 's')), char_indices.next());
742 /// assert_eq!(None, char_indices.next());
744 #[stable(feature = "rust1", since = "1.0.0")]
746 pub fn char_indices(&self) -> CharIndices<'_> {
747 CharIndices { front_offset: 0, iter: self.chars() }
750 /// An iterator over the bytes of a string slice.
752 /// As a string slice consists of a sequence of bytes, we can iterate
753 /// through a string slice by byte. This method returns such an iterator.
760 /// let mut bytes = "bors".bytes();
762 /// assert_eq!(Some(b'b'), bytes.next());
763 /// assert_eq!(Some(b'o'), bytes.next());
764 /// assert_eq!(Some(b'r'), bytes.next());
765 /// assert_eq!(Some(b's'), bytes.next());
767 /// assert_eq!(None, bytes.next());
769 #[stable(feature = "rust1", since = "1.0.0")]
771 pub fn bytes(&self) -> Bytes<'_> {
772 Bytes(self.as_bytes().iter().copied())
775 /// Splits a string slice by whitespace.
777 /// The iterator returned will return string slices that are sub-slices of
778 /// the original string slice, separated by any amount of whitespace.
780 /// 'Whitespace' is defined according to the terms of the Unicode Derived
781 /// Core Property `White_Space`. If you only want to split on ASCII whitespace
782 /// instead, use [`split_ascii_whitespace`].
784 /// [`split_ascii_whitespace`]: str::split_ascii_whitespace
791 /// let mut iter = "A few words".split_whitespace();
793 /// assert_eq!(Some("A"), iter.next());
794 /// assert_eq!(Some("few"), iter.next());
795 /// assert_eq!(Some("words"), iter.next());
797 /// assert_eq!(None, iter.next());
800 /// All kinds of whitespace are considered:
803 /// let mut iter = " Mary had\ta\u{2009}little \n\t lamb".split_whitespace();
804 /// assert_eq!(Some("Mary"), iter.next());
805 /// assert_eq!(Some("had"), iter.next());
806 /// assert_eq!(Some("a"), iter.next());
807 /// assert_eq!(Some("little"), iter.next());
808 /// assert_eq!(Some("lamb"), iter.next());
810 /// assert_eq!(None, iter.next());
812 #[must_use = "this returns the split string as an iterator, \
813 without modifying the original"]
814 #[stable(feature = "split_whitespace", since = "1.1.0")]
816 pub fn split_whitespace(&self) -> SplitWhitespace<'_> {
817 SplitWhitespace { inner: self.split(IsWhitespace).filter(IsNotEmpty) }
820 /// Splits a string slice by ASCII whitespace.
822 /// The iterator returned will return string slices that are sub-slices of
823 /// the original string slice, separated by any amount of ASCII whitespace.
825 /// To split by Unicode `Whitespace` instead, use [`split_whitespace`].
827 /// [`split_whitespace`]: str::split_whitespace
834 /// let mut iter = "A few words".split_ascii_whitespace();
836 /// assert_eq!(Some("A"), iter.next());
837 /// assert_eq!(Some("few"), iter.next());
838 /// assert_eq!(Some("words"), iter.next());
840 /// assert_eq!(None, iter.next());
843 /// All kinds of ASCII whitespace are considered:
846 /// let mut iter = " Mary had\ta little \n\t lamb".split_ascii_whitespace();
847 /// assert_eq!(Some("Mary"), iter.next());
848 /// assert_eq!(Some("had"), iter.next());
849 /// assert_eq!(Some("a"), iter.next());
850 /// assert_eq!(Some("little"), iter.next());
851 /// assert_eq!(Some("lamb"), iter.next());
853 /// assert_eq!(None, iter.next());
855 #[must_use = "this returns the split string as an iterator, \
856 without modifying the original"]
857 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
859 pub fn split_ascii_whitespace(&self) -> SplitAsciiWhitespace<'_> {
861 self.as_bytes().split(IsAsciiWhitespace).filter(BytesIsNotEmpty).map(UnsafeBytesToStr);
862 SplitAsciiWhitespace { inner }
865 /// An iterator over the lines of a string, as string slices.
867 /// Lines are ended with either a newline (`\n`) or a carriage return with
868 /// a line feed (`\r\n`).
870 /// The final line ending is optional. A string that ends with a final line
871 /// ending will return the same lines as an otherwise identical string
872 /// without a final line ending.
879 /// let text = "foo\r\nbar\n\nbaz\n";
880 /// let mut lines = text.lines();
882 /// assert_eq!(Some("foo"), lines.next());
883 /// assert_eq!(Some("bar"), lines.next());
884 /// assert_eq!(Some(""), lines.next());
885 /// assert_eq!(Some("baz"), lines.next());
887 /// assert_eq!(None, lines.next());
890 /// The final line ending isn't required:
893 /// let text = "foo\nbar\n\r\nbaz";
894 /// let mut lines = text.lines();
896 /// assert_eq!(Some("foo"), lines.next());
897 /// assert_eq!(Some("bar"), lines.next());
898 /// assert_eq!(Some(""), lines.next());
899 /// assert_eq!(Some("baz"), lines.next());
901 /// assert_eq!(None, lines.next());
903 #[stable(feature = "rust1", since = "1.0.0")]
905 pub fn lines(&self) -> Lines<'_> {
906 Lines(self.split_terminator('\n').map(LinesAnyMap))
909 /// An iterator over the lines of a string.
910 #[stable(feature = "rust1", since = "1.0.0")]
911 #[rustc_deprecated(since = "1.4.0", reason = "use lines() instead now")]
914 pub fn lines_any(&self) -> LinesAny<'_> {
915 LinesAny(self.lines())
918 /// Returns an iterator of `u16` over the string encoded as UTF-16.
925 /// let text = "Zażółć gęślą jaźń";
927 /// let utf8_len = text.len();
928 /// let utf16_len = text.encode_utf16().count();
930 /// assert!(utf16_len <= utf8_len);
932 #[must_use = "this returns the encoded string as an iterator, \
933 without modifying the original"]
934 #[stable(feature = "encode_utf16", since = "1.8.0")]
935 pub fn encode_utf16(&self) -> EncodeUtf16<'_> {
936 EncodeUtf16 { chars: self.chars(), extra: 0 }
939 /// Returns `true` if the given pattern matches a sub-slice of
940 /// this string slice.
942 /// Returns `false` if it does not.
944 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
945 /// function or closure that determines if a character matches.
947 /// [`char`]: prim@char
948 /// [pattern]: self::pattern
955 /// let bananas = "bananas";
957 /// assert!(bananas.contains("nana"));
958 /// assert!(!bananas.contains("apples"));
960 #[stable(feature = "rust1", since = "1.0.0")]
962 pub fn contains<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool {
963 pat.is_contained_in(self)
966 /// Returns `true` if the given pattern matches a prefix of this
969 /// Returns `false` if it does not.
971 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
972 /// function or closure that determines if a character matches.
974 /// [`char`]: prim@char
975 /// [pattern]: self::pattern
982 /// let bananas = "bananas";
984 /// assert!(bananas.starts_with("bana"));
985 /// assert!(!bananas.starts_with("nana"));
987 #[stable(feature = "rust1", since = "1.0.0")]
988 pub fn starts_with<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool {
989 pat.is_prefix_of(self)
992 /// Returns `true` if the given pattern matches a suffix of this
995 /// Returns `false` if it does not.
997 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
998 /// function or closure that determines if a character matches.
1000 /// [`char`]: prim@char
1001 /// [pattern]: self::pattern
1008 /// let bananas = "bananas";
1010 /// assert!(bananas.ends_with("anas"));
1011 /// assert!(!bananas.ends_with("nana"));
1013 #[stable(feature = "rust1", since = "1.0.0")]
1014 pub fn ends_with<'a, P>(&'a self, pat: P) -> bool
1016 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1018 pat.is_suffix_of(self)
1021 /// Returns the byte index of the first character of this string slice that
1022 /// matches the pattern.
1024 /// Returns [`None`] if the pattern doesn't match.
1026 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1027 /// function or closure that determines if a character matches.
1029 /// [`char`]: prim@char
1030 /// [pattern]: self::pattern
1034 /// Simple patterns:
1037 /// let s = "Löwe 老虎 Léopard Gepardi";
1039 /// assert_eq!(s.find('L'), Some(0));
1040 /// assert_eq!(s.find('é'), Some(14));
1041 /// assert_eq!(s.find("pard"), Some(17));
1044 /// More complex patterns using point-free style and closures:
1047 /// let s = "Löwe 老虎 Léopard";
1049 /// assert_eq!(s.find(char::is_whitespace), Some(5));
1050 /// assert_eq!(s.find(char::is_lowercase), Some(1));
1051 /// assert_eq!(s.find(|c: char| c.is_whitespace() || c.is_lowercase()), Some(1));
1052 /// assert_eq!(s.find(|c: char| (c < 'o') && (c > 'a')), Some(4));
1055 /// Not finding the pattern:
1058 /// let s = "Löwe 老虎 Léopard";
1059 /// let x: &[_] = &['1', '2'];
1061 /// assert_eq!(s.find(x), None);
1063 #[stable(feature = "rust1", since = "1.0.0")]
1065 pub fn find<'a, P: Pattern<'a>>(&'a self, pat: P) -> Option<usize> {
1066 pat.into_searcher(self).next_match().map(|(i, _)| i)
1069 /// Returns the byte index for the first character of the rightmost match of the pattern in
1070 /// this string slice.
1072 /// Returns [`None`] if the pattern doesn't match.
1074 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1075 /// function or closure that determines if a character matches.
1077 /// [`char`]: prim@char
1078 /// [pattern]: self::pattern
1082 /// Simple patterns:
1085 /// let s = "Löwe 老虎 Léopard Gepardi";
1087 /// assert_eq!(s.rfind('L'), Some(13));
1088 /// assert_eq!(s.rfind('é'), Some(14));
1089 /// assert_eq!(s.rfind("pard"), Some(24));
1092 /// More complex patterns with closures:
1095 /// let s = "Löwe 老虎 Léopard";
1097 /// assert_eq!(s.rfind(char::is_whitespace), Some(12));
1098 /// assert_eq!(s.rfind(char::is_lowercase), Some(20));
1101 /// Not finding the pattern:
1104 /// let s = "Löwe 老虎 Léopard";
1105 /// let x: &[_] = &['1', '2'];
1107 /// assert_eq!(s.rfind(x), None);
1109 #[stable(feature = "rust1", since = "1.0.0")]
1111 pub fn rfind<'a, P>(&'a self, pat: P) -> Option<usize>
1113 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1115 pat.into_searcher(self).next_match_back().map(|(i, _)| i)
1118 /// An iterator over substrings of this string slice, separated by
1119 /// characters matched by a pattern.
1121 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1122 /// function or closure that determines if a character matches.
1124 /// [`char`]: prim@char
1125 /// [pattern]: self::pattern
1127 /// # Iterator behavior
1129 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
1130 /// allows a reverse search and forward/reverse search yields the same
1131 /// elements. This is true for, e.g., [`char`], but not for `&str`.
1133 /// If the pattern allows a reverse search but its results might differ
1134 /// from a forward search, the [`rsplit`] method can be used.
1136 /// [`rsplit`]: str::rsplit
1140 /// Simple patterns:
1143 /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
1144 /// assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);
1146 /// let v: Vec<&str> = "".split('X').collect();
1147 /// assert_eq!(v, [""]);
1149 /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
1150 /// assert_eq!(v, ["lion", "", "tiger", "leopard"]);
1152 /// let v: Vec<&str> = "lion::tiger::leopard".split("::").collect();
1153 /// assert_eq!(v, ["lion", "tiger", "leopard"]);
1155 /// let v: Vec<&str> = "abc1def2ghi".split(char::is_numeric).collect();
1156 /// assert_eq!(v, ["abc", "def", "ghi"]);
1158 /// let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect();
1159 /// assert_eq!(v, ["lion", "tiger", "leopard"]);
1162 /// If the pattern is a slice of chars, split on each occurrence of any of the characters:
1165 /// let v: Vec<&str> = "2020-11-03 23:59".split(&['-', ' ', ':', '@'][..]).collect();
1166 /// assert_eq!(v, ["2020", "11", "03", "23", "59"]);
1169 /// A more complex pattern, using a closure:
1172 /// let v: Vec<&str> = "abc1defXghi".split(|c| c == '1' || c == 'X').collect();
1173 /// assert_eq!(v, ["abc", "def", "ghi"]);
1176 /// If a string contains multiple contiguous separators, you will end up
1177 /// with empty strings in the output:
1180 /// let x = "||||a||b|c".to_string();
1181 /// let d: Vec<_> = x.split('|').collect();
1183 /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
1186 /// Contiguous separators are separated by the empty string.
1189 /// let x = "(///)".to_string();
1190 /// let d: Vec<_> = x.split('/').collect();
1192 /// assert_eq!(d, &["(", "", "", ")"]);
1195 /// Separators at the start or end of a string are neighbored
1196 /// by empty strings.
1199 /// let d: Vec<_> = "010".split("0").collect();
1200 /// assert_eq!(d, &["", "1", ""]);
1203 /// When the empty string is used as a separator, it separates
1204 /// every character in the string, along with the beginning
1205 /// and end of the string.
1208 /// let f: Vec<_> = "rust".split("").collect();
1209 /// assert_eq!(f, &["", "r", "u", "s", "t", ""]);
1212 /// Contiguous separators can lead to possibly surprising behavior
1213 /// when whitespace is used as the separator. This code is correct:
1216 /// let x = " a b c".to_string();
1217 /// let d: Vec<_> = x.split(' ').collect();
1219 /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
1222 /// It does _not_ give you:
1225 /// assert_eq!(d, &["a", "b", "c"]);
1228 /// Use [`split_whitespace`] for this behavior.
1230 /// [`split_whitespace`]: str::split_whitespace
1231 #[stable(feature = "rust1", since = "1.0.0")]
1233 pub fn split<'a, P: Pattern<'a>>(&'a self, pat: P) -> Split<'a, P> {
1234 Split(SplitInternal {
1237 matcher: pat.into_searcher(self),
1238 allow_trailing_empty: true,
1243 /// An iterator over substrings of this string slice, separated by
1244 /// characters matched by a pattern. Differs from the iterator produced by
1245 /// `split` in that `split_inclusive` leaves the matched part as the
1246 /// terminator of the substring.
1248 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1249 /// function or closure that determines if a character matches.
1251 /// [`char`]: prim@char
1252 /// [pattern]: self::pattern
1257 /// let v: Vec<&str> = "Mary had a little lamb\nlittle lamb\nlittle lamb."
1258 /// .split_inclusive('\n').collect();
1259 /// assert_eq!(v, ["Mary had a little lamb\n", "little lamb\n", "little lamb."]);
1262 /// If the last element of the string is matched,
1263 /// that element will be considered the terminator of the preceding substring.
1264 /// That substring will be the last item returned by the iterator.
1267 /// let v: Vec<&str> = "Mary had a little lamb\nlittle lamb\nlittle lamb.\n"
1268 /// .split_inclusive('\n').collect();
1269 /// assert_eq!(v, ["Mary had a little lamb\n", "little lamb\n", "little lamb.\n"]);
1271 #[stable(feature = "split_inclusive", since = "1.51.0")]
1273 pub fn split_inclusive<'a, P: Pattern<'a>>(&'a self, pat: P) -> SplitInclusive<'a, P> {
1274 SplitInclusive(SplitInternal {
1277 matcher: pat.into_searcher(self),
1278 allow_trailing_empty: false,
1283 /// An iterator over substrings of the given string slice, separated by
1284 /// characters matched by a pattern and yielded in reverse order.
1286 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1287 /// function or closure that determines if a character matches.
1289 /// [`char`]: prim@char
1290 /// [pattern]: self::pattern
1292 /// # Iterator behavior
1294 /// The returned iterator requires that the pattern supports a reverse
1295 /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
1296 /// search yields the same elements.
1298 /// For iterating from the front, the [`split`] method can be used.
1300 /// [`split`]: str::split
1304 /// Simple patterns:
1307 /// let v: Vec<&str> = "Mary had a little lamb".rsplit(' ').collect();
1308 /// assert_eq!(v, ["lamb", "little", "a", "had", "Mary"]);
1310 /// let v: Vec<&str> = "".rsplit('X').collect();
1311 /// assert_eq!(v, [""]);
1313 /// let v: Vec<&str> = "lionXXtigerXleopard".rsplit('X').collect();
1314 /// assert_eq!(v, ["leopard", "tiger", "", "lion"]);
1316 /// let v: Vec<&str> = "lion::tiger::leopard".rsplit("::").collect();
1317 /// assert_eq!(v, ["leopard", "tiger", "lion"]);
1320 /// A more complex pattern, using a closure:
1323 /// let v: Vec<&str> = "abc1defXghi".rsplit(|c| c == '1' || c == 'X').collect();
1324 /// assert_eq!(v, ["ghi", "def", "abc"]);
1326 #[stable(feature = "rust1", since = "1.0.0")]
1328 pub fn rsplit<'a, P>(&'a self, pat: P) -> RSplit<'a, P>
1330 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1332 RSplit(self.split(pat).0)
1335 /// An iterator over substrings of the given string slice, separated by
1336 /// characters matched by a pattern.
1338 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1339 /// function or closure that determines if a character matches.
1341 /// [`char`]: prim@char
1342 /// [pattern]: self::pattern
1344 /// Equivalent to [`split`], except that the trailing substring
1345 /// is skipped if empty.
1347 /// [`split`]: str::split
1349 /// This method can be used for string data that is _terminated_,
1350 /// rather than _separated_ by a pattern.
1352 /// # Iterator behavior
1354 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
1355 /// allows a reverse search and forward/reverse search yields the same
1356 /// elements. This is true for, e.g., [`char`], but not for `&str`.
1358 /// If the pattern allows a reverse search but its results might differ
1359 /// from a forward search, the [`rsplit_terminator`] method can be used.
1361 /// [`rsplit_terminator`]: str::rsplit_terminator
1368 /// let v: Vec<&str> = "A.B.".split_terminator('.').collect();
1369 /// assert_eq!(v, ["A", "B"]);
1371 /// let v: Vec<&str> = "A..B..".split_terminator(".").collect();
1372 /// assert_eq!(v, ["A", "", "B", ""]);
1374 /// let v: Vec<&str> = "A.B:C.D".split_terminator(&['.', ':'][..]).collect();
1375 /// assert_eq!(v, ["A", "B", "C", "D"]);
1377 #[stable(feature = "rust1", since = "1.0.0")]
1379 pub fn split_terminator<'a, P: Pattern<'a>>(&'a self, pat: P) -> SplitTerminator<'a, P> {
1380 SplitTerminator(SplitInternal { allow_trailing_empty: false, ..self.split(pat).0 })
1383 /// An iterator over substrings of `self`, separated by characters
1384 /// matched by a pattern and yielded in reverse order.
1386 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1387 /// function or closure that determines if a character matches.
1389 /// [`char`]: prim@char
1390 /// [pattern]: self::pattern
1392 /// Equivalent to [`split`], except that the trailing substring is
1393 /// skipped if empty.
1395 /// [`split`]: str::split
1397 /// This method can be used for string data that is _terminated_,
1398 /// rather than _separated_ by a pattern.
1400 /// # Iterator behavior
1402 /// The returned iterator requires that the pattern supports a
1403 /// reverse search, and it will be double ended if a forward/reverse
1404 /// search yields the same elements.
1406 /// For iterating from the front, the [`split_terminator`] method can be
1409 /// [`split_terminator`]: str::split_terminator
1414 /// let v: Vec<&str> = "A.B.".rsplit_terminator('.').collect();
1415 /// assert_eq!(v, ["B", "A"]);
1417 /// let v: Vec<&str> = "A..B..".rsplit_terminator(".").collect();
1418 /// assert_eq!(v, ["", "B", "", "A"]);
1420 /// let v: Vec<&str> = "A.B:C.D".rsplit_terminator(&['.', ':'][..]).collect();
1421 /// assert_eq!(v, ["D", "C", "B", "A"]);
1423 #[stable(feature = "rust1", since = "1.0.0")]
1425 pub fn rsplit_terminator<'a, P>(&'a self, pat: P) -> RSplitTerminator<'a, P>
1427 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1429 RSplitTerminator(self.split_terminator(pat).0)
1432 /// An iterator over substrings of the given string slice, separated by a
1433 /// pattern, restricted to returning at most `n` items.
1435 /// If `n` substrings are returned, the last substring (the `n`th substring)
1436 /// will contain the remainder of the string.
1438 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1439 /// function or closure that determines if a character matches.
1441 /// [`char`]: prim@char
1442 /// [pattern]: self::pattern
1444 /// # Iterator behavior
1446 /// The returned iterator will not be double ended, because it is
1447 /// not efficient to support.
1449 /// If the pattern allows a reverse search, the [`rsplitn`] method can be
1452 /// [`rsplitn`]: str::rsplitn
1456 /// Simple patterns:
1459 /// let v: Vec<&str> = "Mary had a little lambda".splitn(3, ' ').collect();
1460 /// assert_eq!(v, ["Mary", "had", "a little lambda"]);
1462 /// let v: Vec<&str> = "lionXXtigerXleopard".splitn(3, "X").collect();
1463 /// assert_eq!(v, ["lion", "", "tigerXleopard"]);
1465 /// let v: Vec<&str> = "abcXdef".splitn(1, 'X').collect();
1466 /// assert_eq!(v, ["abcXdef"]);
1468 /// let v: Vec<&str> = "".splitn(1, 'X').collect();
1469 /// assert_eq!(v, [""]);
1472 /// A more complex pattern, using a closure:
1475 /// let v: Vec<&str> = "abc1defXghi".splitn(2, |c| c == '1' || c == 'X').collect();
1476 /// assert_eq!(v, ["abc", "defXghi"]);
1478 #[stable(feature = "rust1", since = "1.0.0")]
1480 pub fn splitn<'a, P: Pattern<'a>>(&'a self, n: usize, pat: P) -> SplitN<'a, P> {
1481 SplitN(SplitNInternal { iter: self.split(pat).0, count: n })
1484 /// An iterator over substrings of this string slice, separated by a
1485 /// pattern, starting from the end of the string, restricted to returning
1486 /// at most `n` items.
1488 /// If `n` substrings are returned, the last substring (the `n`th substring)
1489 /// will contain the remainder of the string.
1491 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1492 /// function or closure that determines if a character matches.
1494 /// [`char`]: prim@char
1495 /// [pattern]: self::pattern
1497 /// # Iterator behavior
1499 /// The returned iterator will not be double ended, because it is not
1500 /// efficient to support.
1502 /// For splitting from the front, the [`splitn`] method can be used.
1504 /// [`splitn`]: str::splitn
1508 /// Simple patterns:
1511 /// let v: Vec<&str> = "Mary had a little lamb".rsplitn(3, ' ').collect();
1512 /// assert_eq!(v, ["lamb", "little", "Mary had a"]);
1514 /// let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(3, 'X').collect();
1515 /// assert_eq!(v, ["leopard", "tiger", "lionX"]);
1517 /// let v: Vec<&str> = "lion::tiger::leopard".rsplitn(2, "::").collect();
1518 /// assert_eq!(v, ["leopard", "lion::tiger"]);
1521 /// A more complex pattern, using a closure:
1524 /// let v: Vec<&str> = "abc1defXghi".rsplitn(2, |c| c == '1' || c == 'X').collect();
1525 /// assert_eq!(v, ["ghi", "abc1def"]);
1527 #[stable(feature = "rust1", since = "1.0.0")]
1529 pub fn rsplitn<'a, P>(&'a self, n: usize, pat: P) -> RSplitN<'a, P>
1531 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1533 RSplitN(self.splitn(n, pat).0)
1536 /// Splits the string on the first occurrence of the specified delimiter and
1537 /// returns prefix before delimiter and suffix after delimiter.
1542 /// assert_eq!("cfg".split_once('='), None);
1543 /// assert_eq!("cfg=foo".split_once('='), Some(("cfg", "foo")));
1544 /// assert_eq!("cfg=foo=bar".split_once('='), Some(("cfg", "foo=bar")));
1546 #[stable(feature = "str_split_once", since = "1.52.0")]
1548 pub fn split_once<'a, P: Pattern<'a>>(&'a self, delimiter: P) -> Option<(&'a str, &'a str)> {
1549 let (start, end) = delimiter.into_searcher(self).next_match()?;
1550 // SAFETY: `Searcher` is known to return valid indices.
1551 unsafe { Some((self.get_unchecked(..start), self.get_unchecked(end..))) }
1554 /// Splits the string on the last occurrence of the specified delimiter and
1555 /// returns prefix before delimiter and suffix after delimiter.
1560 /// assert_eq!("cfg".rsplit_once('='), None);
1561 /// assert_eq!("cfg=foo".rsplit_once('='), Some(("cfg", "foo")));
1562 /// assert_eq!("cfg=foo=bar".rsplit_once('='), Some(("cfg=foo", "bar")));
1564 #[stable(feature = "str_split_once", since = "1.52.0")]
1566 pub fn rsplit_once<'a, P>(&'a self, delimiter: P) -> Option<(&'a str, &'a str)>
1568 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1570 let (start, end) = delimiter.into_searcher(self).next_match_back()?;
1571 // SAFETY: `Searcher` is known to return valid indices.
1572 unsafe { Some((self.get_unchecked(..start), self.get_unchecked(end..))) }
1575 /// An iterator over the disjoint matches of a pattern within the given string
1578 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1579 /// function or closure that determines if a character matches.
1581 /// [`char`]: prim@char
1582 /// [pattern]: self::pattern
1584 /// # Iterator behavior
1586 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
1587 /// allows a reverse search and forward/reverse search yields the same
1588 /// elements. This is true for, e.g., [`char`], but not for `&str`.
1590 /// If the pattern allows a reverse search but its results might differ
1591 /// from a forward search, the [`rmatches`] method can be used.
1593 /// [`rmatches`]: str::matches
1600 /// let v: Vec<&str> = "abcXXXabcYYYabc".matches("abc").collect();
1601 /// assert_eq!(v, ["abc", "abc", "abc"]);
1603 /// let v: Vec<&str> = "1abc2abc3".matches(char::is_numeric).collect();
1604 /// assert_eq!(v, ["1", "2", "3"]);
1606 #[stable(feature = "str_matches", since = "1.2.0")]
1608 pub fn matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> Matches<'a, P> {
1609 Matches(MatchesInternal(pat.into_searcher(self)))
1612 /// An iterator over the disjoint matches of a pattern within this string slice,
1613 /// yielded in reverse order.
1615 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1616 /// function or closure that determines if a character matches.
1618 /// [`char`]: prim@char
1619 /// [pattern]: self::pattern
1621 /// # Iterator behavior
1623 /// The returned iterator requires that the pattern supports a reverse
1624 /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
1625 /// search yields the same elements.
1627 /// For iterating from the front, the [`matches`] method can be used.
1629 /// [`matches`]: str::matches
1636 /// let v: Vec<&str> = "abcXXXabcYYYabc".rmatches("abc").collect();
1637 /// assert_eq!(v, ["abc", "abc", "abc"]);
1639 /// let v: Vec<&str> = "1abc2abc3".rmatches(char::is_numeric).collect();
1640 /// assert_eq!(v, ["3", "2", "1"]);
1642 #[stable(feature = "str_matches", since = "1.2.0")]
1644 pub fn rmatches<'a, P>(&'a self, pat: P) -> RMatches<'a, P>
1646 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1648 RMatches(self.matches(pat).0)
1651 /// An iterator over the disjoint matches of a pattern within this string
1652 /// slice as well as the index that the match starts at.
1654 /// For matches of `pat` within `self` that overlap, only the indices
1655 /// corresponding to the first match are returned.
1657 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1658 /// function or closure that determines if a character matches.
1660 /// [`char`]: prim@char
1661 /// [pattern]: self::pattern
1663 /// # Iterator behavior
1665 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
1666 /// allows a reverse search and forward/reverse search yields the same
1667 /// elements. This is true for, e.g., [`char`], but not for `&str`.
1669 /// If the pattern allows a reverse search but its results might differ
1670 /// from a forward search, the [`rmatch_indices`] method can be used.
1672 /// [`rmatch_indices`]: str::rmatch_indices
1679 /// let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
1680 /// assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
1682 /// let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
1683 /// assert_eq!(v, [(1, "abc"), (4, "abc")]);
1685 /// let v: Vec<_> = "ababa".match_indices("aba").collect();
1686 /// assert_eq!(v, [(0, "aba")]); // only the first `aba`
1688 #[stable(feature = "str_match_indices", since = "1.5.0")]
1690 pub fn match_indices<'a, P: Pattern<'a>>(&'a self, pat: P) -> MatchIndices<'a, P> {
1691 MatchIndices(MatchIndicesInternal(pat.into_searcher(self)))
1694 /// An iterator over the disjoint matches of a pattern within `self`,
1695 /// yielded in reverse order along with the index of the match.
1697 /// For matches of `pat` within `self` that overlap, only the indices
1698 /// corresponding to the last match are returned.
1700 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1701 /// function or closure that determines if a character matches.
1703 /// [`char`]: prim@char
1704 /// [pattern]: self::pattern
1706 /// # Iterator behavior
1708 /// The returned iterator requires that the pattern supports a reverse
1709 /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
1710 /// search yields the same elements.
1712 /// For iterating from the front, the [`match_indices`] method can be used.
1714 /// [`match_indices`]: str::match_indices
1721 /// let v: Vec<_> = "abcXXXabcYYYabc".rmatch_indices("abc").collect();
1722 /// assert_eq!(v, [(12, "abc"), (6, "abc"), (0, "abc")]);
1724 /// let v: Vec<_> = "1abcabc2".rmatch_indices("abc").collect();
1725 /// assert_eq!(v, [(4, "abc"), (1, "abc")]);
1727 /// let v: Vec<_> = "ababa".rmatch_indices("aba").collect();
1728 /// assert_eq!(v, [(2, "aba")]); // only the last `aba`
1730 #[stable(feature = "str_match_indices", since = "1.5.0")]
1732 pub fn rmatch_indices<'a, P>(&'a self, pat: P) -> RMatchIndices<'a, P>
1734 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1736 RMatchIndices(self.match_indices(pat).0)
1739 /// Returns a string slice with leading and trailing whitespace removed.
1741 /// 'Whitespace' is defined according to the terms of the Unicode Derived
1742 /// Core Property `White_Space`.
1749 /// let s = " Hello\tworld\t";
1751 /// assert_eq!("Hello\tworld", s.trim());
1754 #[must_use = "this returns the trimmed string as a slice, \
1755 without modifying the original"]
1756 #[stable(feature = "rust1", since = "1.0.0")]
1757 pub fn trim(&self) -> &str {
1758 self.trim_matches(|c: char| c.is_whitespace())
1761 /// Returns a string slice with leading whitespace removed.
1763 /// 'Whitespace' is defined according to the terms of the Unicode Derived
1764 /// Core Property `White_Space`.
1766 /// # Text directionality
1768 /// A string is a sequence of bytes. `start` in this context means the first
1769 /// position of that byte string; for a left-to-right language like English or
1770 /// Russian, this will be left side, and for right-to-left languages like
1771 /// Arabic or Hebrew, this will be the right side.
1778 /// let s = " Hello\tworld\t";
1779 /// assert_eq!("Hello\tworld\t", s.trim_start());
1785 /// let s = " English ";
1786 /// assert!(Some('E') == s.trim_start().chars().next());
1788 /// let s = " עברית ";
1789 /// assert!(Some('ע') == s.trim_start().chars().next());
1792 #[must_use = "this returns the trimmed string as a new slice, \
1793 without modifying the original"]
1794 #[stable(feature = "trim_direction", since = "1.30.0")]
1795 pub fn trim_start(&self) -> &str {
1796 self.trim_start_matches(|c: char| c.is_whitespace())
1799 /// Returns a string slice with trailing whitespace removed.
1801 /// 'Whitespace' is defined according to the terms of the Unicode Derived
1802 /// Core Property `White_Space`.
1804 /// # Text directionality
1806 /// A string is a sequence of bytes. `end` in this context means the last
1807 /// position of that byte string; for a left-to-right language like English or
1808 /// Russian, this will be right side, and for right-to-left languages like
1809 /// Arabic or Hebrew, this will be the left side.
1816 /// let s = " Hello\tworld\t";
1817 /// assert_eq!(" Hello\tworld", s.trim_end());
1823 /// let s = " English ";
1824 /// assert!(Some('h') == s.trim_end().chars().rev().next());
1826 /// let s = " עברית ";
1827 /// assert!(Some('ת') == s.trim_end().chars().rev().next());
1830 #[must_use = "this returns the trimmed string as a new slice, \
1831 without modifying the original"]
1832 #[stable(feature = "trim_direction", since = "1.30.0")]
1833 pub fn trim_end(&self) -> &str {
1834 self.trim_end_matches(|c: char| c.is_whitespace())
1837 /// Returns a string slice with leading whitespace removed.
1839 /// 'Whitespace' is defined according to the terms of the Unicode Derived
1840 /// Core Property `White_Space`.
1842 /// # Text directionality
1844 /// A string is a sequence of bytes. 'Left' in this context means the first
1845 /// position of that byte string; for a language like Arabic or Hebrew
1846 /// which are 'right to left' rather than 'left to right', this will be
1847 /// the _right_ side, not the left.
1854 /// let s = " Hello\tworld\t";
1856 /// assert_eq!("Hello\tworld\t", s.trim_left());
1862 /// let s = " English";
1863 /// assert!(Some('E') == s.trim_left().chars().next());
1865 /// let s = " עברית";
1866 /// assert!(Some('ע') == s.trim_left().chars().next());
1868 #[must_use = "this returns the trimmed string as a new slice, \
1869 without modifying the original"]
1871 #[stable(feature = "rust1", since = "1.0.0")]
1874 reason = "superseded by `trim_start`",
1875 suggestion = "trim_start"
1877 pub fn trim_left(&self) -> &str {
1881 /// Returns a string slice with trailing whitespace removed.
1883 /// 'Whitespace' is defined according to the terms of the Unicode Derived
1884 /// Core Property `White_Space`.
1886 /// # Text directionality
1888 /// A string is a sequence of bytes. 'Right' in this context means the last
1889 /// position of that byte string; for a language like Arabic or Hebrew
1890 /// which are 'right to left' rather than 'left to right', this will be
1891 /// the _left_ side, not the right.
1898 /// let s = " Hello\tworld\t";
1900 /// assert_eq!(" Hello\tworld", s.trim_right());
1906 /// let s = "English ";
1907 /// assert!(Some('h') == s.trim_right().chars().rev().next());
1909 /// let s = "עברית ";
1910 /// assert!(Some('ת') == s.trim_right().chars().rev().next());
1912 #[must_use = "this returns the trimmed string as a new slice, \
1913 without modifying the original"]
1915 #[stable(feature = "rust1", since = "1.0.0")]
1918 reason = "superseded by `trim_end`",
1919 suggestion = "trim_end"
1921 pub fn trim_right(&self) -> &str {
1925 /// Returns a string slice with all prefixes and suffixes that match a
1926 /// pattern repeatedly removed.
1928 /// The [pattern] can be a [`char`], a slice of [`char`]s, or a function
1929 /// or closure that determines if a character matches.
1931 /// [`char`]: prim@char
1932 /// [pattern]: self::pattern
1936 /// Simple patterns:
1939 /// assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar");
1940 /// assert_eq!("123foo1bar123".trim_matches(char::is_numeric), "foo1bar");
1942 /// let x: &[_] = &['1', '2'];
1943 /// assert_eq!("12foo1bar12".trim_matches(x), "foo1bar");
1946 /// A more complex pattern, using a closure:
1949 /// assert_eq!("1foo1barXX".trim_matches(|c| c == '1' || c == 'X'), "foo1bar");
1951 #[must_use = "this returns the trimmed string as a new slice, \
1952 without modifying the original"]
1953 #[stable(feature = "rust1", since = "1.0.0")]
1954 pub fn trim_matches<'a, P>(&'a self, pat: P) -> &'a str
1956 P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>,
1960 let mut matcher = pat.into_searcher(self);
1961 if let Some((a, b)) = matcher.next_reject() {
1963 j = b; // Remember earliest known match, correct it below if
1964 // last match is different
1966 if let Some((_, b)) = matcher.next_reject_back() {
1969 // SAFETY: `Searcher` is known to return valid indices.
1970 unsafe { self.get_unchecked(i..j) }
1973 /// Returns a string slice with all prefixes that match a pattern
1974 /// repeatedly removed.
1976 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1977 /// function or closure that determines if a character matches.
1979 /// [`char`]: prim@char
1980 /// [pattern]: self::pattern
1982 /// # Text directionality
1984 /// A string is a sequence of bytes. `start` in this context means the first
1985 /// position of that byte string; for a left-to-right language like English or
1986 /// Russian, this will be left side, and for right-to-left languages like
1987 /// Arabic or Hebrew, this will be the right side.
1994 /// assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11");
1995 /// assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric), "foo1bar123");
1997 /// let x: &[_] = &['1', '2'];
1998 /// assert_eq!("12foo1bar12".trim_start_matches(x), "foo1bar12");
2000 #[must_use = "this returns the trimmed string as a new slice, \
2001 without modifying the original"]
2002 #[stable(feature = "trim_direction", since = "1.30.0")]
2003 pub fn trim_start_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str {
2004 let mut i = self.len();
2005 let mut matcher = pat.into_searcher(self);
2006 if let Some((a, _)) = matcher.next_reject() {
2009 // SAFETY: `Searcher` is known to return valid indices.
2010 unsafe { self.get_unchecked(i..self.len()) }
2013 /// Returns a string slice with the prefix removed.
2015 /// If the string starts with the pattern `prefix`, returns substring after the prefix, wrapped
2016 /// in `Some`. Unlike `trim_start_matches`, this method removes the prefix exactly once.
2018 /// If the string does not start with `prefix`, returns `None`.
2020 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2021 /// function or closure that determines if a character matches.
2023 /// [`char`]: prim@char
2024 /// [pattern]: self::pattern
2029 /// assert_eq!("foo:bar".strip_prefix("foo:"), Some("bar"));
2030 /// assert_eq!("foo:bar".strip_prefix("bar"), None);
2031 /// assert_eq!("foofoo".strip_prefix("foo"), Some("foo"));
2033 #[must_use = "this returns the remaining substring as a new slice, \
2034 without modifying the original"]
2035 #[stable(feature = "str_strip", since = "1.45.0")]
2036 pub fn strip_prefix<'a, P: Pattern<'a>>(&'a self, prefix: P) -> Option<&'a str> {
2037 prefix.strip_prefix_of(self)
2040 /// Returns a string slice with the suffix removed.
2042 /// If the string ends with the pattern `suffix`, returns the substring before the suffix,
2043 /// wrapped in `Some`. Unlike `trim_end_matches`, this method removes the suffix exactly once.
2045 /// If the string does not end with `suffix`, returns `None`.
2047 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2048 /// function or closure that determines if a character matches.
2050 /// [`char`]: prim@char
2051 /// [pattern]: self::pattern
2056 /// assert_eq!("bar:foo".strip_suffix(":foo"), Some("bar"));
2057 /// assert_eq!("bar:foo".strip_suffix("bar"), None);
2058 /// assert_eq!("foofoo".strip_suffix("foo"), Some("foo"));
2060 #[must_use = "this returns the remaining substring as a new slice, \
2061 without modifying the original"]
2062 #[stable(feature = "str_strip", since = "1.45.0")]
2063 pub fn strip_suffix<'a, P>(&'a self, suffix: P) -> Option<&'a str>
2066 <P as Pattern<'a>>::Searcher: ReverseSearcher<'a>,
2068 suffix.strip_suffix_of(self)
2071 /// Returns a string slice with all suffixes that match a pattern
2072 /// repeatedly removed.
2074 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2075 /// function or closure that determines if a character matches.
2077 /// [`char`]: prim@char
2078 /// [pattern]: self::pattern
2080 /// # Text directionality
2082 /// A string is a sequence of bytes. `end` in this context means the last
2083 /// position of that byte string; for a left-to-right language like English or
2084 /// Russian, this will be right side, and for right-to-left languages like
2085 /// Arabic or Hebrew, this will be the left side.
2089 /// Simple patterns:
2092 /// assert_eq!("11foo1bar11".trim_end_matches('1'), "11foo1bar");
2093 /// assert_eq!("123foo1bar123".trim_end_matches(char::is_numeric), "123foo1bar");
2095 /// let x: &[_] = &['1', '2'];
2096 /// assert_eq!("12foo1bar12".trim_end_matches(x), "12foo1bar");
2099 /// A more complex pattern, using a closure:
2102 /// assert_eq!("1fooX".trim_end_matches(|c| c == '1' || c == 'X'), "1foo");
2104 #[must_use = "this returns the trimmed string as a new slice, \
2105 without modifying the original"]
2106 #[stable(feature = "trim_direction", since = "1.30.0")]
2107 pub fn trim_end_matches<'a, P>(&'a self, pat: P) -> &'a str
2109 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
2112 let mut matcher = pat.into_searcher(self);
2113 if let Some((_, b)) = matcher.next_reject_back() {
2116 // SAFETY: `Searcher` is known to return valid indices.
2117 unsafe { self.get_unchecked(0..j) }
2120 /// Returns a string slice with all prefixes that match a pattern
2121 /// repeatedly removed.
2123 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2124 /// function or closure that determines if a character matches.
2126 /// [`char`]: prim@char
2127 /// [pattern]: self::pattern
2129 /// # Text directionality
2131 /// A string is a sequence of bytes. 'Left' in this context means the first
2132 /// position of that byte string; for a language like Arabic or Hebrew
2133 /// which are 'right to left' rather than 'left to right', this will be
2134 /// the _right_ side, not the left.
2141 /// assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11");
2142 /// assert_eq!("123foo1bar123".trim_left_matches(char::is_numeric), "foo1bar123");
2144 /// let x: &[_] = &['1', '2'];
2145 /// assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12");
2147 #[stable(feature = "rust1", since = "1.0.0")]
2150 reason = "superseded by `trim_start_matches`",
2151 suggestion = "trim_start_matches"
2153 pub fn trim_left_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str {
2154 self.trim_start_matches(pat)
2157 /// Returns a string slice with all suffixes that match a pattern
2158 /// repeatedly removed.
2160 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2161 /// function or closure that determines if a character matches.
2163 /// [`char`]: prim@char
2164 /// [pattern]: self::pattern
2166 /// # Text directionality
2168 /// A string is a sequence of bytes. 'Right' in this context means the last
2169 /// position of that byte string; for a language like Arabic or Hebrew
2170 /// which are 'right to left' rather than 'left to right', this will be
2171 /// the _left_ side, not the right.
2175 /// Simple patterns:
2178 /// assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar");
2179 /// assert_eq!("123foo1bar123".trim_right_matches(char::is_numeric), "123foo1bar");
2181 /// let x: &[_] = &['1', '2'];
2182 /// assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar");
2185 /// A more complex pattern, using a closure:
2188 /// assert_eq!("1fooX".trim_right_matches(|c| c == '1' || c == 'X'), "1foo");
2190 #[stable(feature = "rust1", since = "1.0.0")]
2193 reason = "superseded by `trim_end_matches`",
2194 suggestion = "trim_end_matches"
2196 pub fn trim_right_matches<'a, P>(&'a self, pat: P) -> &'a str
2198 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
2200 self.trim_end_matches(pat)
2203 /// Parses this string slice into another type.
2205 /// Because `parse` is so general, it can cause problems with type
2206 /// inference. As such, `parse` is one of the few times you'll see
2207 /// the syntax affectionately known as the 'turbofish': `::<>`. This
2208 /// helps the inference algorithm understand specifically which type
2209 /// you're trying to parse into.
2211 /// `parse` can parse into any type that implements the [`FromStr`] trait.
2216 /// Will return [`Err`] if it's not possible to parse this string slice into
2217 /// the desired type.
2219 /// [`Err`]: FromStr::Err
2226 /// let four: u32 = "4".parse().unwrap();
2228 /// assert_eq!(4, four);
2231 /// Using the 'turbofish' instead of annotating `four`:
2234 /// let four = "4".parse::<u32>();
2236 /// assert_eq!(Ok(4), four);
2239 /// Failing to parse:
2242 /// let nope = "j".parse::<u32>();
2244 /// assert!(nope.is_err());
2247 #[stable(feature = "rust1", since = "1.0.0")]
2248 pub fn parse<F: FromStr>(&self) -> Result<F, F::Err> {
2249 FromStr::from_str(self)
2252 /// Checks if all characters in this string are within the ASCII range.
2257 /// let ascii = "hello!\n";
2258 /// let non_ascii = "Grüße, Jürgen ❤";
2260 /// assert!(ascii.is_ascii());
2261 /// assert!(!non_ascii.is_ascii());
2263 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
2266 pub fn is_ascii(&self) -> bool {
2267 // We can treat each byte as character here: all multibyte characters
2268 // start with a byte that is not in the ascii range, so we will stop
2270 self.as_bytes().is_ascii()
2273 /// Checks that two strings are an ASCII case-insensitive match.
2275 /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
2276 /// but without allocating and copying temporaries.
2281 /// assert!("Ferris".eq_ignore_ascii_case("FERRIS"));
2282 /// assert!("Ferrös".eq_ignore_ascii_case("FERRöS"));
2283 /// assert!(!"Ferrös".eq_ignore_ascii_case("FERRÖS"));
2285 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
2288 pub fn eq_ignore_ascii_case(&self, other: &str) -> bool {
2289 self.as_bytes().eq_ignore_ascii_case(other.as_bytes())
2292 /// Converts this string to its ASCII upper case equivalent in-place.
2294 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
2295 /// but non-ASCII letters are unchanged.
2297 /// To return a new uppercased value without modifying the existing one, use
2298 /// [`to_ascii_uppercase()`].
2300 /// [`to_ascii_uppercase()`]: #method.to_ascii_uppercase
2305 /// let mut s = String::from("Grüße, Jürgen ❤");
2307 /// s.make_ascii_uppercase();
2309 /// assert_eq!("GRüßE, JüRGEN ❤", s);
2311 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
2313 pub fn make_ascii_uppercase(&mut self) {
2314 // SAFETY: safe because we transmute two types with the same layout.
2315 let me = unsafe { self.as_bytes_mut() };
2316 me.make_ascii_uppercase()
2319 /// Converts this string to its ASCII lower case equivalent in-place.
2321 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
2322 /// but non-ASCII letters are unchanged.
2324 /// To return a new lowercased value without modifying the existing one, use
2325 /// [`to_ascii_lowercase()`].
2327 /// [`to_ascii_lowercase()`]: #method.to_ascii_lowercase
2332 /// let mut s = String::from("GRÜßE, JÜRGEN ❤");
2334 /// s.make_ascii_lowercase();
2336 /// assert_eq!("grÜße, jÜrgen ❤", s);
2338 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
2340 pub fn make_ascii_lowercase(&mut self) {
2341 // SAFETY: safe because we transmute two types with the same layout.
2342 let me = unsafe { self.as_bytes_mut() };
2343 me.make_ascii_lowercase()
2346 /// Return an iterator that escapes each char in `self` with [`char::escape_debug`].
2348 /// Note: only extended grapheme codepoints that begin the string will be
2356 /// for c in "❤\n!".escape_debug() {
2357 /// print!("{}", c);
2362 /// Using `println!` directly:
2365 /// println!("{}", "❤\n!".escape_debug());
2369 /// Both are equivalent to:
2372 /// println!("❤\\n!");
2375 /// Using `to_string`:
2378 /// assert_eq!("❤\n!".escape_debug().to_string(), "❤\\n!");
2380 #[must_use = "this returns the escaped string as an iterator, \
2381 without modifying the original"]
2382 #[stable(feature = "str_escape", since = "1.34.0")]
2383 pub fn escape_debug(&self) -> EscapeDebug<'_> {
2384 let mut chars = self.chars();
2388 .map(|first| first.escape_debug_ext(EscapeDebugExtArgs::ESCAPE_ALL))
2391 .chain(chars.flat_map(CharEscapeDebugContinue)),
2395 /// Return an iterator that escapes each char in `self` with [`char::escape_default`].
2402 /// for c in "❤\n!".escape_default() {
2403 /// print!("{}", c);
2408 /// Using `println!` directly:
2411 /// println!("{}", "❤\n!".escape_default());
2415 /// Both are equivalent to:
2418 /// println!("\\u{{2764}}\\n!");
2421 /// Using `to_string`:
2424 /// assert_eq!("❤\n!".escape_default().to_string(), "\\u{2764}\\n!");
2426 #[must_use = "this returns the escaped string as an iterator, \
2427 without modifying the original"]
2428 #[stable(feature = "str_escape", since = "1.34.0")]
2429 pub fn escape_default(&self) -> EscapeDefault<'_> {
2430 EscapeDefault { inner: self.chars().flat_map(CharEscapeDefault) }
2433 /// Return an iterator that escapes each char in `self` with [`char::escape_unicode`].
2440 /// for c in "❤\n!".escape_unicode() {
2441 /// print!("{}", c);
2446 /// Using `println!` directly:
2449 /// println!("{}", "❤\n!".escape_unicode());
2453 /// Both are equivalent to:
2456 /// println!("\\u{{2764}}\\u{{a}}\\u{{21}}");
2459 /// Using `to_string`:
2462 /// assert_eq!("❤\n!".escape_unicode().to_string(), "\\u{2764}\\u{a}\\u{21}");
2464 #[must_use = "this returns the escaped string as an iterator, \
2465 without modifying the original"]
2466 #[stable(feature = "str_escape", since = "1.34.0")]
2467 pub fn escape_unicode(&self) -> EscapeUnicode<'_> {
2468 EscapeUnicode { inner: self.chars().flat_map(CharEscapeUnicode) }
2472 #[stable(feature = "rust1", since = "1.0.0")]
2473 impl AsRef<[u8]> for str {
2475 fn as_ref(&self) -> &[u8] {
2480 #[stable(feature = "rust1", since = "1.0.0")]
2481 #[rustc_const_unstable(feature = "const_default_impls", issue = "87864")]
2482 impl const Default for &str {
2483 /// Creates an empty str
2485 fn default() -> Self {
2490 #[stable(feature = "default_mut_str", since = "1.28.0")]
2491 impl Default for &mut str {
2492 /// Creates an empty mutable str
2494 fn default() -> Self {
2495 // SAFETY: The empty string is valid UTF-8.
2496 unsafe { from_utf8_unchecked_mut(&mut []) }
2501 /// A nameable, cloneable fn type
2503 struct LinesAnyMap impl<'a> Fn = |line: &'a str| -> &'a str {
2505 if l > 0 && line.as_bytes()[l - 1] == b'\r' { &line[0 .. l - 1] }
2510 struct CharEscapeDebugContinue impl Fn = |c: char| -> char::EscapeDebug {
2511 c.escape_debug_ext(EscapeDebugExtArgs {
2512 escape_grapheme_extended: false,
2513 escape_single_quote: true,
2514 escape_double_quote: true
2519 struct CharEscapeUnicode impl Fn = |c: char| -> char::EscapeUnicode {
2523 struct CharEscapeDefault impl Fn = |c: char| -> char::EscapeDefault {
2528 struct IsWhitespace impl Fn = |c: char| -> bool {
2533 struct IsAsciiWhitespace impl Fn = |byte: &u8| -> bool {
2534 byte.is_ascii_whitespace()
2538 struct IsNotEmpty impl<'a, 'b> Fn = |s: &'a &'b str| -> bool {
2543 struct BytesIsNotEmpty impl<'a, 'b> Fn = |s: &'a &'b [u8]| -> bool {
2548 struct UnsafeBytesToStr impl<'a> Fn = |bytes: &'a [u8]| -> &'a str {
2550 unsafe { from_utf8_unchecked(bytes) }