core/str/
mod.rs

1//! String manipulation.
2//!
3//! For more details, see the [`std::str`] module.
4//!
5//! [`std::str`]: ../../std/str/index.html
6
7#![stable(feature = "rust1", since = "1.0.0")]
8
9mod converts;
10mod count;
11mod error;
12mod iter;
13mod traits;
14mod validations;
15
16use self::pattern::{DoubleEndedSearcher, Pattern, ReverseSearcher, Searcher};
17use crate::char::{self, EscapeDebugExtArgs};
18use crate::ops::Range;
19use crate::slice::{self, SliceIndex};
20use crate::{ascii, mem};
21
22pub mod pattern;
23
24mod lossy;
25#[unstable(feature = "str_from_raw_parts", issue = "119206")]
26pub use converts::{from_raw_parts, from_raw_parts_mut};
27#[stable(feature = "rust1", since = "1.0.0")]
28pub use converts::{from_utf8, from_utf8_unchecked};
29#[stable(feature = "str_mut_extras", since = "1.20.0")]
30pub use converts::{from_utf8_mut, from_utf8_unchecked_mut};
31#[stable(feature = "rust1", since = "1.0.0")]
32pub use error::{ParseBoolError, Utf8Error};
33#[stable(feature = "encode_utf16", since = "1.8.0")]
34pub use iter::EncodeUtf16;
35#[stable(feature = "rust1", since = "1.0.0")]
36#[allow(deprecated)]
37pub use iter::LinesAny;
38#[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
39pub use iter::SplitAsciiWhitespace;
40#[stable(feature = "split_inclusive", since = "1.51.0")]
41pub use iter::SplitInclusive;
42#[stable(feature = "rust1", since = "1.0.0")]
43pub use iter::{Bytes, CharIndices, Chars, Lines, SplitWhitespace};
44#[stable(feature = "str_escape", since = "1.34.0")]
45pub use iter::{EscapeDebug, EscapeDefault, EscapeUnicode};
46#[stable(feature = "str_match_indices", since = "1.5.0")]
47pub use iter::{MatchIndices, RMatchIndices};
48use iter::{MatchIndicesInternal, MatchesInternal, SplitInternal, SplitNInternal};
49#[stable(feature = "str_matches", since = "1.2.0")]
50pub use iter::{Matches, RMatches};
51#[stable(feature = "rust1", since = "1.0.0")]
52pub use iter::{RSplit, RSplitTerminator, Split, SplitTerminator};
53#[stable(feature = "rust1", since = "1.0.0")]
54pub use iter::{RSplitN, SplitN};
55#[stable(feature = "utf8_chunks", since = "1.79.0")]
56pub use lossy::{Utf8Chunk, Utf8Chunks};
57#[stable(feature = "rust1", since = "1.0.0")]
58pub use traits::FromStr;
59#[unstable(feature = "str_internals", issue = "none")]
60pub use validations::{next_code_point, utf8_char_width};
61
62#[inline(never)]
63#[cold]
64#[track_caller]
65#[rustc_allow_const_fn_unstable(const_eval_select)]
66#[cfg(not(feature = "panic_immediate_abort"))]
67const fn slice_error_fail(s: &str, begin: usize, end: usize) -> ! {
68    crate::intrinsics::const_eval_select((s, begin, end), slice_error_fail_ct, slice_error_fail_rt)
69}
70
71#[cfg(feature = "panic_immediate_abort")]
72const fn slice_error_fail(s: &str, begin: usize, end: usize) -> ! {
73    slice_error_fail_ct(s, begin, end)
74}
75
76#[track_caller]
77const fn slice_error_fail_ct(_: &str, _: usize, _: usize) -> ! {
78    panic!("failed to slice string");
79}
80
81#[track_caller]
82fn slice_error_fail_rt(s: &str, begin: usize, end: usize) -> ! {
83    const MAX_DISPLAY_LENGTH: usize = 256;
84    let trunc_len = s.floor_char_boundary(MAX_DISPLAY_LENGTH);
85    let s_trunc = &s[..trunc_len];
86    let ellipsis = if trunc_len < s.len() { "[...]" } else { "" };
87
88    // 1. out of bounds
89    if begin > s.len() || end > s.len() {
90        let oob_index = if begin > s.len() { begin } else { end };
91        panic!("byte index {oob_index} is out of bounds of `{s_trunc}`{ellipsis}");
92    }
93
94    // 2. begin <= end
95    assert!(
96        begin <= end,
97        "begin <= end ({} <= {}) when slicing `{}`{}",
98        begin,
99        end,
100        s_trunc,
101        ellipsis
102    );
103
104    // 3. character boundary
105    let index = if !s.is_char_boundary(begin) { begin } else { end };
106    // find the character
107    let char_start = s.floor_char_boundary(index);
108    // `char_start` must be less than len and a char boundary
109    let ch = s[char_start..].chars().next().unwrap();
110    let char_range = char_start..char_start + ch.len_utf8();
111    panic!(
112        "byte index {} is not a char boundary; it is inside {:?} (bytes {:?}) of `{}`{}",
113        index, ch, char_range, s_trunc, ellipsis
114    );
115}
116
117#[cfg(not(test))]
118impl str {
119    /// Returns the length of `self`.
120    ///
121    /// This length is in bytes, not [`char`]s or graphemes. In other words,
122    /// it might not be what a human considers the length of the string.
123    ///
124    /// [`char`]: prim@char
125    ///
126    /// # Examples
127    ///
128    /// ```
129    /// let len = "foo".len();
130    /// assert_eq!(3, len);
131    ///
132    /// assert_eq!("ƒoo".len(), 4); // fancy f!
133    /// assert_eq!("ƒoo".chars().count(), 3);
134    /// ```
135    #[stable(feature = "rust1", since = "1.0.0")]
136    #[rustc_const_stable(feature = "const_str_len", since = "1.39.0")]
137    #[cfg_attr(not(test), rustc_diagnostic_item = "str_len")]
138    #[must_use]
139    #[inline]
140    pub const fn len(&self) -> usize {
141        self.as_bytes().len()
142    }
143
144    /// Returns `true` if `self` has a length of zero bytes.
145    ///
146    /// # Examples
147    ///
148    /// ```
149    /// let s = "";
150    /// assert!(s.is_empty());
151    ///
152    /// let s = "not empty";
153    /// assert!(!s.is_empty());
154    /// ```
155    #[stable(feature = "rust1", since = "1.0.0")]
156    #[rustc_const_stable(feature = "const_str_is_empty", since = "1.39.0")]
157    #[must_use]
158    #[inline]
159    pub const fn is_empty(&self) -> bool {
160        self.len() == 0
161    }
162
163    /// Converts a slice of bytes to a string slice.
164    ///
165    /// A string slice ([`&str`]) is made of bytes ([`u8`]), and a byte slice
166    /// ([`&[u8]`][byteslice]) is made of bytes, so this function converts between
167    /// the two. Not all byte slices are valid string slices, however: [`&str`] requires
168    /// that it is valid UTF-8. `from_utf8()` checks to ensure that the bytes are valid
169    /// UTF-8, and then does the conversion.
170    ///
171    /// [`&str`]: str
172    /// [byteslice]: prim@slice
173    ///
174    /// If you are sure that the byte slice is valid UTF-8, and you don't want to
175    /// incur the overhead of the validity check, there is an unsafe version of
176    /// this function, [`from_utf8_unchecked`], which has the same
177    /// behavior but skips the check.
178    ///
179    /// If you need a `String` instead of a `&str`, consider
180    /// [`String::from_utf8`][string].
181    ///
182    /// [string]: ../std/string/struct.String.html#method.from_utf8
183    ///
184    /// Because you can stack-allocate a `[u8; N]`, and you can take a
185    /// [`&[u8]`][byteslice] of it, this function is one way to have a
186    /// stack-allocated string. There is an example of this in the
187    /// examples section below.
188    ///
189    /// [byteslice]: slice
190    ///
191    /// # Errors
192    ///
193    /// Returns `Err` if the slice is not UTF-8 with a description as to why the
194    /// provided slice is not UTF-8.
195    ///
196    /// # Examples
197    ///
198    /// Basic usage:
199    ///
200    /// ```
201    /// use std::str;
202    ///
203    /// // some bytes, in a vector
204    /// let sparkle_heart = vec![240, 159, 146, 150];
205    ///
206    /// // We can use the ? (try) operator to check if the bytes are valid
207    /// let sparkle_heart = str::from_utf8(&sparkle_heart)?;
208    ///
209    /// assert_eq!("💖", sparkle_heart);
210    /// # Ok::<_, str::Utf8Error>(())
211    /// ```
212    ///
213    /// Incorrect bytes:
214    ///
215    /// ```
216    /// use std::str;
217    ///
218    /// // some invalid bytes, in a vector
219    /// let sparkle_heart = vec![0, 159, 146, 150];
220    ///
221    /// assert!(str::from_utf8(&sparkle_heart).is_err());
222    /// ```
223    ///
224    /// See the docs for [`Utf8Error`] for more details on the kinds of
225    /// errors that can be returned.
226    ///
227    /// A "stack allocated string":
228    ///
229    /// ```
230    /// use std::str;
231    ///
232    /// // some bytes, in a stack-allocated array
233    /// let sparkle_heart = [240, 159, 146, 150];
234    ///
235    /// // We know these bytes are valid, so just use `unwrap()`.
236    /// let sparkle_heart: &str = str::from_utf8(&sparkle_heart).unwrap();
237    ///
238    /// assert_eq!("💖", sparkle_heart);
239    /// ```
240    #[unstable(feature = "inherent_str_constructors", issue = "131114")]
241    pub const fn from_utf8(v: &[u8]) -> Result<&str, Utf8Error> {
242        converts::from_utf8(v)
243    }
244
245    /// Converts a mutable slice of bytes to a mutable string slice.
246    ///
247    /// # Examples
248    ///
249    /// Basic usage:
250    ///
251    /// ```
252    /// use std::str;
253    ///
254    /// // "Hello, Rust!" as a mutable vector
255    /// let mut hellorust = vec![72, 101, 108, 108, 111, 44, 32, 82, 117, 115, 116, 33];
256    ///
257    /// // As we know these bytes are valid, we can use `unwrap()`
258    /// let outstr = str::from_utf8_mut(&mut hellorust).unwrap();
259    ///
260    /// assert_eq!("Hello, Rust!", outstr);
261    /// ```
262    ///
263    /// Incorrect bytes:
264    ///
265    /// ```
266    /// use std::str;
267    ///
268    /// // Some invalid bytes in a mutable vector
269    /// let mut invalid = vec![128, 223];
270    ///
271    /// assert!(str::from_utf8_mut(&mut invalid).is_err());
272    /// ```
273    /// See the docs for [`Utf8Error`] for more details on the kinds of
274    /// errors that can be returned.
275    #[unstable(feature = "inherent_str_constructors", issue = "131114")]
276    #[rustc_const_unstable(feature = "const_str_from_utf8", issue = "91006")]
277    pub const fn from_utf8_mut(v: &mut [u8]) -> Result<&mut str, Utf8Error> {
278        converts::from_utf8_mut(v)
279    }
280
281    /// Converts a slice of bytes to a string slice without checking
282    /// that the string contains valid UTF-8.
283    ///
284    /// See the safe version, [`from_utf8`], for more information.
285    ///
286    /// # Safety
287    ///
288    /// The bytes passed in must be valid UTF-8.
289    ///
290    /// # Examples
291    ///
292    /// Basic usage:
293    ///
294    /// ```
295    /// use std::str;
296    ///
297    /// // some bytes, in a vector
298    /// let sparkle_heart = vec![240, 159, 146, 150];
299    ///
300    /// let sparkle_heart = unsafe {
301    ///     str::from_utf8_unchecked(&sparkle_heart)
302    /// };
303    ///
304    /// assert_eq!("💖", sparkle_heart);
305    /// ```
306    #[inline]
307    #[must_use]
308    #[unstable(feature = "inherent_str_constructors", issue = "131114")]
309    pub const unsafe fn from_utf8_unchecked(v: &[u8]) -> &str {
310        // SAFETY: converts::from_utf8_unchecked has the same safety requirements as this function.
311        unsafe { converts::from_utf8_unchecked(v) }
312    }
313
314    /// Converts a slice of bytes to a string slice without checking
315    /// that the string contains valid UTF-8; mutable version.
316    ///
317    /// See the immutable version, [`from_utf8_unchecked()`] for more information.
318    ///
319    /// # Examples
320    ///
321    /// Basic usage:
322    ///
323    /// ```
324    /// use std::str;
325    ///
326    /// let mut heart = vec![240, 159, 146, 150];
327    /// let heart = unsafe { str::from_utf8_unchecked_mut(&mut heart) };
328    ///
329    /// assert_eq!("💖", heart);
330    /// ```
331    #[inline]
332    #[must_use]
333    #[unstable(feature = "inherent_str_constructors", issue = "131114")]
334    pub const unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str {
335        // SAFETY: converts::from_utf8_unchecked_mut has the same safety requirements as this function.
336        unsafe { converts::from_utf8_unchecked_mut(v) }
337    }
338
339    /// Checks that `index`-th byte is the first byte in a UTF-8 code point
340    /// sequence or the end of the string.
341    ///
342    /// The start and end of the string (when `index == self.len()`) are
343    /// considered to be boundaries.
344    ///
345    /// Returns `false` if `index` is greater than `self.len()`.
346    ///
347    /// # Examples
348    ///
349    /// ```
350    /// let s = "Löwe 老虎 Léopard";
351    /// assert!(s.is_char_boundary(0));
352    /// // start of `老`
353    /// assert!(s.is_char_boundary(6));
354    /// assert!(s.is_char_boundary(s.len()));
355    ///
356    /// // second byte of `ö`
357    /// assert!(!s.is_char_boundary(2));
358    ///
359    /// // third byte of `老`
360    /// assert!(!s.is_char_boundary(8));
361    /// ```
362    #[must_use]
363    #[stable(feature = "is_char_boundary", since = "1.9.0")]
364    #[rustc_const_stable(feature = "const_is_char_boundary", since = "1.86.0")]
365    #[inline]
366    pub const fn is_char_boundary(&self, index: usize) -> bool {
367        // 0 is always ok.
368        // Test for 0 explicitly so that it can optimize out the check
369        // easily and skip reading string data for that case.
370        // Note that optimizing `self.get(..index)` relies on this.
371        if index == 0 {
372            return true;
373        }
374
375        if index >= self.len() {
376            // For `true` we have two options:
377            //
378            // - index == self.len()
379            //   Empty strings are valid, so return true
380            // - index > self.len()
381            //   In this case return false
382            //
383            // The check is placed exactly here, because it improves generated
384            // code on higher opt-levels. See PR #84751 for more details.
385            index == self.len()
386        } else {
387            self.as_bytes()[index].is_utf8_char_boundary()
388        }
389    }
390
391    /// Finds the closest `x` not exceeding `index` where [`is_char_boundary(x)`] is `true`.
392    ///
393    /// This method can help you truncate a string so that it's still valid UTF-8, but doesn't
394    /// exceed a given number of bytes. Note that this is done purely at the character level
395    /// and can still visually split graphemes, even though the underlying characters aren't
396    /// split. For example, the emoji 🧑‍🔬 (scientist) could be split so that the string only
397    /// includes 🧑 (person) instead.
398    ///
399    /// [`is_char_boundary(x)`]: Self::is_char_boundary
400    ///
401    /// # Examples
402    ///
403    /// ```
404    /// #![feature(round_char_boundary)]
405    /// let s = "❤️🧡💛💚💙💜";
406    /// assert_eq!(s.len(), 26);
407    /// assert!(!s.is_char_boundary(13));
408    ///
409    /// let closest = s.floor_char_boundary(13);
410    /// assert_eq!(closest, 10);
411    /// assert_eq!(&s[..closest], "❤️🧡");
412    /// ```
413    #[unstable(feature = "round_char_boundary", issue = "93743")]
414    #[inline]
415    pub fn floor_char_boundary(&self, index: usize) -> usize {
416        if index >= self.len() {
417            self.len()
418        } else {
419            let lower_bound = index.saturating_sub(3);
420            let new_index = self.as_bytes()[lower_bound..=index]
421                .iter()
422                .rposition(|b| b.is_utf8_char_boundary());
423
424            // SAFETY: we know that the character boundary will be within four bytes
425            unsafe { lower_bound + new_index.unwrap_unchecked() }
426        }
427    }
428
429    /// Finds the closest `x` not below `index` where [`is_char_boundary(x)`] is `true`.
430    ///
431    /// If `index` is greater than the length of the string, this returns the length of the string.
432    ///
433    /// This method is the natural complement to [`floor_char_boundary`]. See that method
434    /// for more details.
435    ///
436    /// [`floor_char_boundary`]: str::floor_char_boundary
437    /// [`is_char_boundary(x)`]: Self::is_char_boundary
438    ///
439    /// # Examples
440    ///
441    /// ```
442    /// #![feature(round_char_boundary)]
443    /// let s = "❤️🧡💛💚💙💜";
444    /// assert_eq!(s.len(), 26);
445    /// assert!(!s.is_char_boundary(13));
446    ///
447    /// let closest = s.ceil_char_boundary(13);
448    /// assert_eq!(closest, 14);
449    /// assert_eq!(&s[..closest], "❤️🧡💛");
450    /// ```
451    #[unstable(feature = "round_char_boundary", issue = "93743")]
452    #[inline]
453    pub fn ceil_char_boundary(&self, index: usize) -> usize {
454        if index > self.len() {
455            self.len()
456        } else {
457            let upper_bound = Ord::min(index + 4, self.len());
458            self.as_bytes()[index..upper_bound]
459                .iter()
460                .position(|b| b.is_utf8_char_boundary())
461                .map_or(upper_bound, |pos| pos + index)
462        }
463    }
464
465    /// Converts a string slice to a byte slice. To convert the byte slice back
466    /// into a string slice, use the [`from_utf8`] function.
467    ///
468    /// # Examples
469    ///
470    /// ```
471    /// let bytes = "bors".as_bytes();
472    /// assert_eq!(b"bors", bytes);
473    /// ```
474    #[stable(feature = "rust1", since = "1.0.0")]
475    #[rustc_const_stable(feature = "str_as_bytes", since = "1.39.0")]
476    #[must_use]
477    #[inline(always)]
478    #[allow(unused_attributes)]
479    pub const fn as_bytes(&self) -> &[u8] {
480        // SAFETY: const sound because we transmute two types with the same layout
481        unsafe { mem::transmute(self) }
482    }
483
484    /// Converts a mutable string slice to a mutable byte slice.
485    ///
486    /// # Safety
487    ///
488    /// The caller must ensure that the content of the slice is valid UTF-8
489    /// before the borrow ends and the underlying `str` is used.
490    ///
491    /// Use of a `str` whose contents are not valid UTF-8 is undefined behavior.
492    ///
493    /// # Examples
494    ///
495    /// Basic usage:
496    ///
497    /// ```
498    /// let mut s = String::from("Hello");
499    /// let bytes = unsafe { s.as_bytes_mut() };
500    ///
501    /// assert_eq!(b"Hello", bytes);
502    /// ```
503    ///
504    /// Mutability:
505    ///
506    /// ```
507    /// let mut s = String::from("🗻∈🌏");
508    ///
509    /// unsafe {
510    ///     let bytes = s.as_bytes_mut();
511    ///
512    ///     bytes[0] = 0xF0;
513    ///     bytes[1] = 0x9F;
514    ///     bytes[2] = 0x8D;
515    ///     bytes[3] = 0x94;
516    /// }
517    ///
518    /// assert_eq!("🍔∈🌏", s);
519    /// ```
520    #[stable(feature = "str_mut_extras", since = "1.20.0")]
521    #[rustc_const_stable(feature = "const_str_as_mut", since = "1.83.0")]
522    #[must_use]
523    #[inline(always)]
524    pub const unsafe fn as_bytes_mut(&mut self) -> &mut [u8] {
525        // SAFETY: the cast from `&str` to `&[u8]` is safe since `str`
526        // has the same layout as `&[u8]` (only std can make this guarantee).
527        // The pointer dereference is safe since it comes from a mutable reference which
528        // is guaranteed to be valid for writes.
529        unsafe { &mut *(self as *mut str as *mut [u8]) }
530    }
531
532    /// Converts a string slice to a raw pointer.
533    ///
534    /// As string slices are a slice of bytes, the raw pointer points to a
535    /// [`u8`]. This pointer will be pointing to the first byte of the string
536    /// slice.
537    ///
538    /// The caller must ensure that the returned pointer is never written to.
539    /// If you need to mutate the contents of the string slice, use [`as_mut_ptr`].
540    ///
541    /// [`as_mut_ptr`]: str::as_mut_ptr
542    ///
543    /// # Examples
544    ///
545    /// ```
546    /// let s = "Hello";
547    /// let ptr = s.as_ptr();
548    /// ```
549    #[stable(feature = "rust1", since = "1.0.0")]
550    #[rustc_const_stable(feature = "rustc_str_as_ptr", since = "1.32.0")]
551    #[rustc_never_returns_null_ptr]
552    #[rustc_as_ptr]
553    #[must_use]
554    #[inline(always)]
555    pub const fn as_ptr(&self) -> *const u8 {
556        self as *const str as *const u8
557    }
558
559    /// Converts a mutable string slice to a raw pointer.
560    ///
561    /// As string slices are a slice of bytes, the raw pointer points to a
562    /// [`u8`]. This pointer will be pointing to the first byte of the string
563    /// slice.
564    ///
565    /// It is your responsibility to make sure that the string slice only gets
566    /// modified in a way that it remains valid UTF-8.
567    #[stable(feature = "str_as_mut_ptr", since = "1.36.0")]
568    #[rustc_const_stable(feature = "const_str_as_mut", since = "1.83.0")]
569    #[rustc_never_returns_null_ptr]
570    #[rustc_as_ptr]
571    #[must_use]
572    #[inline(always)]
573    pub const fn as_mut_ptr(&mut self) -> *mut u8 {
574        self as *mut str as *mut u8
575    }
576
577    /// Returns a subslice of `str`.
578    ///
579    /// This is the non-panicking alternative to indexing the `str`. Returns
580    /// [`None`] whenever equivalent indexing operation would panic.
581    ///
582    /// # Examples
583    ///
584    /// ```
585    /// let v = String::from("🗻∈🌏");
586    ///
587    /// assert_eq!(Some("🗻"), v.get(0..4));
588    ///
589    /// // indices not on UTF-8 sequence boundaries
590    /// assert!(v.get(1..).is_none());
591    /// assert!(v.get(..8).is_none());
592    ///
593    /// // out of bounds
594    /// assert!(v.get(..42).is_none());
595    /// ```
596    #[stable(feature = "str_checked_slicing", since = "1.20.0")]
597    #[inline]
598    pub fn get<I: SliceIndex<str>>(&self, i: I) -> Option<&I::Output> {
599        i.get(self)
600    }
601
602    /// Returns a mutable subslice of `str`.
603    ///
604    /// This is the non-panicking alternative to indexing the `str`. Returns
605    /// [`None`] whenever equivalent indexing operation would panic.
606    ///
607    /// # Examples
608    ///
609    /// ```
610    /// let mut v = String::from("hello");
611    /// // correct length
612    /// assert!(v.get_mut(0..5).is_some());
613    /// // out of bounds
614    /// assert!(v.get_mut(..42).is_none());
615    /// assert_eq!(Some("he"), v.get_mut(0..2).map(|v| &*v));
616    ///
617    /// assert_eq!("hello", v);
618    /// {
619    ///     let s = v.get_mut(0..2);
620    ///     let s = s.map(|s| {
621    ///         s.make_ascii_uppercase();
622    ///         &*s
623    ///     });
624    ///     assert_eq!(Some("HE"), s);
625    /// }
626    /// assert_eq!("HEllo", v);
627    /// ```
628    #[stable(feature = "str_checked_slicing", since = "1.20.0")]
629    #[inline]
630    pub fn get_mut<I: SliceIndex<str>>(&mut self, i: I) -> Option<&mut I::Output> {
631        i.get_mut(self)
632    }
633
634    /// Returns an unchecked subslice of `str`.
635    ///
636    /// This is the unchecked alternative to indexing the `str`.
637    ///
638    /// # Safety
639    ///
640    /// Callers of this function are responsible that these preconditions are
641    /// satisfied:
642    ///
643    /// * The starting index must not exceed the ending index;
644    /// * Indexes must be within bounds of the original slice;
645    /// * Indexes must lie on UTF-8 sequence boundaries.
646    ///
647    /// Failing that, the returned string slice may reference invalid memory or
648    /// violate the invariants communicated by the `str` type.
649    ///
650    /// # Examples
651    ///
652    /// ```
653    /// let v = "🗻∈🌏";
654    /// unsafe {
655    ///     assert_eq!("🗻", v.get_unchecked(0..4));
656    ///     assert_eq!("∈", v.get_unchecked(4..7));
657    ///     assert_eq!("🌏", v.get_unchecked(7..11));
658    /// }
659    /// ```
660    #[stable(feature = "str_checked_slicing", since = "1.20.0")]
661    #[inline]
662    pub unsafe fn get_unchecked<I: SliceIndex<str>>(&self, i: I) -> &I::Output {
663        // SAFETY: the caller must uphold the safety contract for `get_unchecked`;
664        // the slice is dereferenceable because `self` is a safe reference.
665        // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is.
666        unsafe { &*i.get_unchecked(self) }
667    }
668
669    /// Returns a mutable, unchecked subslice of `str`.
670    ///
671    /// This is the unchecked alternative to indexing the `str`.
672    ///
673    /// # Safety
674    ///
675    /// Callers of this function are responsible that these preconditions are
676    /// satisfied:
677    ///
678    /// * The starting index must not exceed the ending index;
679    /// * Indexes must be within bounds of the original slice;
680    /// * Indexes must lie on UTF-8 sequence boundaries.
681    ///
682    /// Failing that, the returned string slice may reference invalid memory or
683    /// violate the invariants communicated by the `str` type.
684    ///
685    /// # Examples
686    ///
687    /// ```
688    /// let mut v = String::from("🗻∈🌏");
689    /// unsafe {
690    ///     assert_eq!("🗻", v.get_unchecked_mut(0..4));
691    ///     assert_eq!("∈", v.get_unchecked_mut(4..7));
692    ///     assert_eq!("🌏", v.get_unchecked_mut(7..11));
693    /// }
694    /// ```
695    #[stable(feature = "str_checked_slicing", since = "1.20.0")]
696    #[inline]
697    pub unsafe fn get_unchecked_mut<I: SliceIndex<str>>(&mut self, i: I) -> &mut I::Output {
698        // SAFETY: the caller must uphold the safety contract for `get_unchecked_mut`;
699        // the slice is dereferenceable because `self` is a safe reference.
700        // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is.
701        unsafe { &mut *i.get_unchecked_mut(self) }
702    }
703
704    /// Creates a string slice from another string slice, bypassing safety
705    /// checks.
706    ///
707    /// This is generally not recommended, use with caution! For a safe
708    /// alternative see [`str`] and [`Index`].
709    ///
710    /// [`Index`]: crate::ops::Index
711    ///
712    /// This new slice goes from `begin` to `end`, including `begin` but
713    /// excluding `end`.
714    ///
715    /// To get a mutable string slice instead, see the
716    /// [`slice_mut_unchecked`] method.
717    ///
718    /// [`slice_mut_unchecked`]: str::slice_mut_unchecked
719    ///
720    /// # Safety
721    ///
722    /// Callers of this function are responsible that three preconditions are
723    /// satisfied:
724    ///
725    /// * `begin` must not exceed `end`.
726    /// * `begin` and `end` must be byte positions within the string slice.
727    /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
728    ///
729    /// # Examples
730    ///
731    /// ```
732    /// let s = "Löwe 老虎 Léopard";
733    ///
734    /// unsafe {
735    ///     assert_eq!("Löwe 老虎 Léopard", s.slice_unchecked(0, 21));
736    /// }
737    ///
738    /// let s = "Hello, world!";
739    ///
740    /// unsafe {
741    ///     assert_eq!("world", s.slice_unchecked(7, 12));
742    /// }
743    /// ```
744    #[stable(feature = "rust1", since = "1.0.0")]
745    #[deprecated(since = "1.29.0", note = "use `get_unchecked(begin..end)` instead")]
746    #[must_use]
747    #[inline]
748    pub unsafe fn slice_unchecked(&self, begin: usize, end: usize) -> &str {
749        // SAFETY: the caller must uphold the safety contract for `get_unchecked`;
750        // the slice is dereferenceable because `self` is a safe reference.
751        // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is.
752        unsafe { &*(begin..end).get_unchecked(self) }
753    }
754
755    /// Creates a string slice from another string slice, bypassing safety
756    /// checks.
757    ///
758    /// This is generally not recommended, use with caution! For a safe
759    /// alternative see [`str`] and [`IndexMut`].
760    ///
761    /// [`IndexMut`]: crate::ops::IndexMut
762    ///
763    /// This new slice goes from `begin` to `end`, including `begin` but
764    /// excluding `end`.
765    ///
766    /// To get an immutable string slice instead, see the
767    /// [`slice_unchecked`] method.
768    ///
769    /// [`slice_unchecked`]: str::slice_unchecked
770    ///
771    /// # Safety
772    ///
773    /// Callers of this function are responsible that three preconditions are
774    /// satisfied:
775    ///
776    /// * `begin` must not exceed `end`.
777    /// * `begin` and `end` must be byte positions within the string slice.
778    /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
779    #[stable(feature = "str_slice_mut", since = "1.5.0")]
780    #[deprecated(since = "1.29.0", note = "use `get_unchecked_mut(begin..end)` instead")]
781    #[inline]
782    pub unsafe fn slice_mut_unchecked(&mut self, begin: usize, end: usize) -> &mut str {
783        // SAFETY: the caller must uphold the safety contract for `get_unchecked_mut`;
784        // the slice is dereferenceable because `self` is a safe reference.
785        // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is.
786        unsafe { &mut *(begin..end).get_unchecked_mut(self) }
787    }
788
789    /// Divides one string slice into two at an index.
790    ///
791    /// The argument, `mid`, should be a byte offset from the start of the
792    /// string. It must also be on the boundary of a UTF-8 code point.
793    ///
794    /// The two slices returned go from the start of the string slice to `mid`,
795    /// and from `mid` to the end of the string slice.
796    ///
797    /// To get mutable string slices instead, see the [`split_at_mut`]
798    /// method.
799    ///
800    /// [`split_at_mut`]: str::split_at_mut
801    ///
802    /// # Panics
803    ///
804    /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is past
805    /// the end of the last code point of the string slice.  For a non-panicking
806    /// alternative see [`split_at_checked`](str::split_at_checked).
807    ///
808    /// # Examples
809    ///
810    /// ```
811    /// let s = "Per Martin-Löf";
812    ///
813    /// let (first, last) = s.split_at(3);
814    ///
815    /// assert_eq!("Per", first);
816    /// assert_eq!(" Martin-Löf", last);
817    /// ```
818    #[inline]
819    #[must_use]
820    #[stable(feature = "str_split_at", since = "1.4.0")]
821    #[rustc_const_stable(feature = "const_str_split_at", since = "1.86.0")]
822    pub const fn split_at(&self, mid: usize) -> (&str, &str) {
823        match self.split_at_checked(mid) {
824            None => slice_error_fail(self, 0, mid),
825            Some(pair) => pair,
826        }
827    }
828
829    /// Divides one mutable string slice into two at an index.
830    ///
831    /// The argument, `mid`, should be a byte offset from the start of the
832    /// string. It must also be on the boundary of a UTF-8 code point.
833    ///
834    /// The two slices returned go from the start of the string slice to `mid`,
835    /// and from `mid` to the end of the string slice.
836    ///
837    /// To get immutable string slices instead, see the [`split_at`] method.
838    ///
839    /// [`split_at`]: str::split_at
840    ///
841    /// # Panics
842    ///
843    /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is past
844    /// the end of the last code point of the string slice.  For a non-panicking
845    /// alternative see [`split_at_mut_checked`](str::split_at_mut_checked).
846    ///
847    /// # Examples
848    ///
849    /// ```
850    /// let mut s = "Per Martin-Löf".to_string();
851    /// {
852    ///     let (first, last) = s.split_at_mut(3);
853    ///     first.make_ascii_uppercase();
854    ///     assert_eq!("PER", first);
855    ///     assert_eq!(" Martin-Löf", last);
856    /// }
857    /// assert_eq!("PER Martin-Löf", s);
858    /// ```
859    #[inline]
860    #[must_use]
861    #[stable(feature = "str_split_at", since = "1.4.0")]
862    #[rustc_const_stable(feature = "const_str_split_at", since = "1.86.0")]
863    pub const fn split_at_mut(&mut self, mid: usize) -> (&mut str, &mut str) {
864        // is_char_boundary checks that the index is in [0, .len()]
865        if self.is_char_boundary(mid) {
866            // SAFETY: just checked that `mid` is on a char boundary.
867            unsafe { self.split_at_mut_unchecked(mid) }
868        } else {
869            slice_error_fail(self, 0, mid)
870        }
871    }
872
873    /// Divides one string slice into two at an index.
874    ///
875    /// The argument, `mid`, should be a valid byte offset from the start of the
876    /// string. It must also be on the boundary of a UTF-8 code point. The
877    /// method returns `None` if that’s not the case.
878    ///
879    /// The two slices returned go from the start of the string slice to `mid`,
880    /// and from `mid` to the end of the string slice.
881    ///
882    /// To get mutable string slices instead, see the [`split_at_mut_checked`]
883    /// method.
884    ///
885    /// [`split_at_mut_checked`]: str::split_at_mut_checked
886    ///
887    /// # Examples
888    ///
889    /// ```
890    /// let s = "Per Martin-Löf";
891    ///
892    /// let (first, last) = s.split_at_checked(3).unwrap();
893    /// assert_eq!("Per", first);
894    /// assert_eq!(" Martin-Löf", last);
895    ///
896    /// assert_eq!(None, s.split_at_checked(13));  // Inside “ö”
897    /// assert_eq!(None, s.split_at_checked(16));  // Beyond the string length
898    /// ```
899    #[inline]
900    #[must_use]
901    #[stable(feature = "split_at_checked", since = "1.80.0")]
902    #[rustc_const_stable(feature = "const_str_split_at", since = "1.86.0")]
903    pub const fn split_at_checked(&self, mid: usize) -> Option<(&str, &str)> {
904        // is_char_boundary checks that the index is in [0, .len()]
905        if self.is_char_boundary(mid) {
906            // SAFETY: just checked that `mid` is on a char boundary.
907            Some(unsafe { self.split_at_unchecked(mid) })
908        } else {
909            None
910        }
911    }
912
913    /// Divides one mutable string slice into two at an index.
914    ///
915    /// The argument, `mid`, should be a valid byte offset from the start of the
916    /// string. It must also be on the boundary of a UTF-8 code point. The
917    /// method returns `None` if that’s not the case.
918    ///
919    /// The two slices returned go from the start of the string slice to `mid`,
920    /// and from `mid` to the end of the string slice.
921    ///
922    /// To get immutable string slices instead, see the [`split_at_checked`] method.
923    ///
924    /// [`split_at_checked`]: str::split_at_checked
925    ///
926    /// # Examples
927    ///
928    /// ```
929    /// let mut s = "Per Martin-Löf".to_string();
930    /// if let Some((first, last)) = s.split_at_mut_checked(3) {
931    ///     first.make_ascii_uppercase();
932    ///     assert_eq!("PER", first);
933    ///     assert_eq!(" Martin-Löf", last);
934    /// }
935    /// assert_eq!("PER Martin-Löf", s);
936    ///
937    /// assert_eq!(None, s.split_at_mut_checked(13));  // Inside “ö”
938    /// assert_eq!(None, s.split_at_mut_checked(16));  // Beyond the string length
939    /// ```
940    #[inline]
941    #[must_use]
942    #[stable(feature = "split_at_checked", since = "1.80.0")]
943    #[rustc_const_stable(feature = "const_str_split_at", since = "1.86.0")]
944    pub const fn split_at_mut_checked(&mut self, mid: usize) -> Option<(&mut str, &mut str)> {
945        // is_char_boundary checks that the index is in [0, .len()]
946        if self.is_char_boundary(mid) {
947            // SAFETY: just checked that `mid` is on a char boundary.
948            Some(unsafe { self.split_at_mut_unchecked(mid) })
949        } else {
950            None
951        }
952    }
953
954    /// Divides one string slice into two at an index.
955    ///
956    /// # Safety
957    ///
958    /// The caller must ensure that `mid` is a valid byte offset from the start
959    /// of the string and falls on the boundary of a UTF-8 code point.
960    const unsafe fn split_at_unchecked(&self, mid: usize) -> (&str, &str) {
961        let len = self.len();
962        let ptr = self.as_ptr();
963        // SAFETY: caller guarantees `mid` is on a char boundary.
964        unsafe {
965            (
966                from_utf8_unchecked(slice::from_raw_parts(ptr, mid)),
967                from_utf8_unchecked(slice::from_raw_parts(ptr.add(mid), len - mid)),
968            )
969        }
970    }
971
972    /// Divides one string slice into two at an index.
973    ///
974    /// # Safety
975    ///
976    /// The caller must ensure that `mid` is a valid byte offset from the start
977    /// of the string and falls on the boundary of a UTF-8 code point.
978    const unsafe fn split_at_mut_unchecked(&mut self, mid: usize) -> (&mut str, &mut str) {
979        let len = self.len();
980        let ptr = self.as_mut_ptr();
981        // SAFETY: caller guarantees `mid` is on a char boundary.
982        unsafe {
983            (
984                from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, mid)),
985                from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr.add(mid), len - mid)),
986            )
987        }
988    }
989
990    /// Returns an iterator over the [`char`]s of a string slice.
991    ///
992    /// As a string slice consists of valid UTF-8, we can iterate through a
993    /// string slice by [`char`]. This method returns such an iterator.
994    ///
995    /// It's important to remember that [`char`] represents a Unicode Scalar
996    /// Value, and might not match your idea of what a 'character' is. Iteration
997    /// over grapheme clusters may be what you actually want. This functionality
998    /// is not provided by Rust's standard library, check crates.io instead.
999    ///
1000    /// # Examples
1001    ///
1002    /// Basic usage:
1003    ///
1004    /// ```
1005    /// let word = "goodbye";
1006    ///
1007    /// let count = word.chars().count();
1008    /// assert_eq!(7, count);
1009    ///
1010    /// let mut chars = word.chars();
1011    ///
1012    /// assert_eq!(Some('g'), chars.next());
1013    /// assert_eq!(Some('o'), chars.next());
1014    /// assert_eq!(Some('o'), chars.next());
1015    /// assert_eq!(Some('d'), chars.next());
1016    /// assert_eq!(Some('b'), chars.next());
1017    /// assert_eq!(Some('y'), chars.next());
1018    /// assert_eq!(Some('e'), chars.next());
1019    ///
1020    /// assert_eq!(None, chars.next());
1021    /// ```
1022    ///
1023    /// Remember, [`char`]s might not match your intuition about characters:
1024    ///
1025    /// [`char`]: prim@char
1026    ///
1027    /// ```
1028    /// let y = "y̆";
1029    ///
1030    /// let mut chars = y.chars();
1031    ///
1032    /// assert_eq!(Some('y'), chars.next()); // not 'y̆'
1033    /// assert_eq!(Some('\u{0306}'), chars.next());
1034    ///
1035    /// assert_eq!(None, chars.next());
1036    /// ```
1037    #[stable(feature = "rust1", since = "1.0.0")]
1038    #[inline]
1039    #[cfg_attr(not(test), rustc_diagnostic_item = "str_chars")]
1040    pub fn chars(&self) -> Chars<'_> {
1041        Chars { iter: self.as_bytes().iter() }
1042    }
1043
1044    /// Returns an iterator over the [`char`]s of a string slice, and their
1045    /// positions.
1046    ///
1047    /// As a string slice consists of valid UTF-8, we can iterate through a
1048    /// string slice by [`char`]. This method returns an iterator of both
1049    /// these [`char`]s, as well as their byte positions.
1050    ///
1051    /// The iterator yields tuples. The position is first, the [`char`] is
1052    /// second.
1053    ///
1054    /// # Examples
1055    ///
1056    /// Basic usage:
1057    ///
1058    /// ```
1059    /// let word = "goodbye";
1060    ///
1061    /// let count = word.char_indices().count();
1062    /// assert_eq!(7, count);
1063    ///
1064    /// let mut char_indices = word.char_indices();
1065    ///
1066    /// assert_eq!(Some((0, 'g')), char_indices.next());
1067    /// assert_eq!(Some((1, 'o')), char_indices.next());
1068    /// assert_eq!(Some((2, 'o')), char_indices.next());
1069    /// assert_eq!(Some((3, 'd')), char_indices.next());
1070    /// assert_eq!(Some((4, 'b')), char_indices.next());
1071    /// assert_eq!(Some((5, 'y')), char_indices.next());
1072    /// assert_eq!(Some((6, 'e')), char_indices.next());
1073    ///
1074    /// assert_eq!(None, char_indices.next());
1075    /// ```
1076    ///
1077    /// Remember, [`char`]s might not match your intuition about characters:
1078    ///
1079    /// [`char`]: prim@char
1080    ///
1081    /// ```
1082    /// let yes = "y̆es";
1083    ///
1084    /// let mut char_indices = yes.char_indices();
1085    ///
1086    /// assert_eq!(Some((0, 'y')), char_indices.next()); // not (0, 'y̆')
1087    /// assert_eq!(Some((1, '\u{0306}')), char_indices.next());
1088    ///
1089    /// // note the 3 here - the previous character took up two bytes
1090    /// assert_eq!(Some((3, 'e')), char_indices.next());
1091    /// assert_eq!(Some((4, 's')), char_indices.next());
1092    ///
1093    /// assert_eq!(None, char_indices.next());
1094    /// ```
1095    #[stable(feature = "rust1", since = "1.0.0")]
1096    #[inline]
1097    pub fn char_indices(&self) -> CharIndices<'_> {
1098        CharIndices { front_offset: 0, iter: self.chars() }
1099    }
1100
1101    /// Returns an iterator over the bytes of a string slice.
1102    ///
1103    /// As a string slice consists of a sequence of bytes, we can iterate
1104    /// through a string slice by byte. This method returns such an iterator.
1105    ///
1106    /// # Examples
1107    ///
1108    /// ```
1109    /// let mut bytes = "bors".bytes();
1110    ///
1111    /// assert_eq!(Some(b'b'), bytes.next());
1112    /// assert_eq!(Some(b'o'), bytes.next());
1113    /// assert_eq!(Some(b'r'), bytes.next());
1114    /// assert_eq!(Some(b's'), bytes.next());
1115    ///
1116    /// assert_eq!(None, bytes.next());
1117    /// ```
1118    #[stable(feature = "rust1", since = "1.0.0")]
1119    #[inline]
1120    pub fn bytes(&self) -> Bytes<'_> {
1121        Bytes(self.as_bytes().iter().copied())
1122    }
1123
1124    /// Splits a string slice by whitespace.
1125    ///
1126    /// The iterator returned will return string slices that are sub-slices of
1127    /// the original string slice, separated by any amount of whitespace.
1128    ///
1129    /// 'Whitespace' is defined according to the terms of the Unicode Derived
1130    /// Core Property `White_Space`. If you only want to split on ASCII whitespace
1131    /// instead, use [`split_ascii_whitespace`].
1132    ///
1133    /// [`split_ascii_whitespace`]: str::split_ascii_whitespace
1134    ///
1135    /// # Examples
1136    ///
1137    /// Basic usage:
1138    ///
1139    /// ```
1140    /// let mut iter = "A few words".split_whitespace();
1141    ///
1142    /// assert_eq!(Some("A"), iter.next());
1143    /// assert_eq!(Some("few"), iter.next());
1144    /// assert_eq!(Some("words"), iter.next());
1145    ///
1146    /// assert_eq!(None, iter.next());
1147    /// ```
1148    ///
1149    /// All kinds of whitespace are considered:
1150    ///
1151    /// ```
1152    /// let mut iter = " Mary   had\ta\u{2009}little  \n\t lamb".split_whitespace();
1153    /// assert_eq!(Some("Mary"), iter.next());
1154    /// assert_eq!(Some("had"), iter.next());
1155    /// assert_eq!(Some("a"), iter.next());
1156    /// assert_eq!(Some("little"), iter.next());
1157    /// assert_eq!(Some("lamb"), iter.next());
1158    ///
1159    /// assert_eq!(None, iter.next());
1160    /// ```
1161    ///
1162    /// If the string is empty or all whitespace, the iterator yields no string slices:
1163    /// ```
1164    /// assert_eq!("".split_whitespace().next(), None);
1165    /// assert_eq!("   ".split_whitespace().next(), None);
1166    /// ```
1167    #[must_use = "this returns the split string as an iterator, \
1168                  without modifying the original"]
1169    #[stable(feature = "split_whitespace", since = "1.1.0")]
1170    #[cfg_attr(not(test), rustc_diagnostic_item = "str_split_whitespace")]
1171    #[inline]
1172    pub fn split_whitespace(&self) -> SplitWhitespace<'_> {
1173        SplitWhitespace { inner: self.split(IsWhitespace).filter(IsNotEmpty) }
1174    }
1175
1176    /// Splits a string slice by ASCII whitespace.
1177    ///
1178    /// The iterator returned will return string slices that are sub-slices of
1179    /// the original string slice, separated by any amount of ASCII whitespace.
1180    ///
1181    /// To split by Unicode `Whitespace` instead, use [`split_whitespace`].
1182    ///
1183    /// [`split_whitespace`]: str::split_whitespace
1184    ///
1185    /// # Examples
1186    ///
1187    /// Basic usage:
1188    ///
1189    /// ```
1190    /// let mut iter = "A few words".split_ascii_whitespace();
1191    ///
1192    /// assert_eq!(Some("A"), iter.next());
1193    /// assert_eq!(Some("few"), iter.next());
1194    /// assert_eq!(Some("words"), iter.next());
1195    ///
1196    /// assert_eq!(None, iter.next());
1197    /// ```
1198    ///
1199    /// All kinds of ASCII whitespace are considered:
1200    ///
1201    /// ```
1202    /// let mut iter = " Mary   had\ta little  \n\t lamb".split_ascii_whitespace();
1203    /// assert_eq!(Some("Mary"), iter.next());
1204    /// assert_eq!(Some("had"), iter.next());
1205    /// assert_eq!(Some("a"), iter.next());
1206    /// assert_eq!(Some("little"), iter.next());
1207    /// assert_eq!(Some("lamb"), iter.next());
1208    ///
1209    /// assert_eq!(None, iter.next());
1210    /// ```
1211    ///
1212    /// If the string is empty or all ASCII whitespace, the iterator yields no string slices:
1213    /// ```
1214    /// assert_eq!("".split_ascii_whitespace().next(), None);
1215    /// assert_eq!("   ".split_ascii_whitespace().next(), None);
1216    /// ```
1217    #[must_use = "this returns the split string as an iterator, \
1218                  without modifying the original"]
1219    #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
1220    #[inline]
1221    pub fn split_ascii_whitespace(&self) -> SplitAsciiWhitespace<'_> {
1222        let inner =
1223            self.as_bytes().split(IsAsciiWhitespace).filter(BytesIsNotEmpty).map(UnsafeBytesToStr);
1224        SplitAsciiWhitespace { inner }
1225    }
1226
1227    /// Returns an iterator over the lines of a string, as string slices.
1228    ///
1229    /// Lines are split at line endings that are either newlines (`\n`) or
1230    /// sequences of a carriage return followed by a line feed (`\r\n`).
1231    ///
1232    /// Line terminators are not included in the lines returned by the iterator.
1233    ///
1234    /// Note that any carriage return (`\r`) not immediately followed by a
1235    /// line feed (`\n`) does not split a line. These carriage returns are
1236    /// thereby included in the produced lines.
1237    ///
1238    /// The final line ending is optional. A string that ends with a final line
1239    /// ending will return the same lines as an otherwise identical string
1240    /// without a final line ending.
1241    ///
1242    /// # Examples
1243    ///
1244    /// Basic usage:
1245    ///
1246    /// ```
1247    /// let text = "foo\r\nbar\n\nbaz\r";
1248    /// let mut lines = text.lines();
1249    ///
1250    /// assert_eq!(Some("foo"), lines.next());
1251    /// assert_eq!(Some("bar"), lines.next());
1252    /// assert_eq!(Some(""), lines.next());
1253    /// // Trailing carriage return is included in the last line
1254    /// assert_eq!(Some("baz\r"), lines.next());
1255    ///
1256    /// assert_eq!(None, lines.next());
1257    /// ```
1258    ///
1259    /// The final line does not require any ending:
1260    ///
1261    /// ```
1262    /// let text = "foo\nbar\n\r\nbaz";
1263    /// let mut lines = text.lines();
1264    ///
1265    /// assert_eq!(Some("foo"), lines.next());
1266    /// assert_eq!(Some("bar"), lines.next());
1267    /// assert_eq!(Some(""), lines.next());
1268    /// assert_eq!(Some("baz"), lines.next());
1269    ///
1270    /// assert_eq!(None, lines.next());
1271    /// ```
1272    #[stable(feature = "rust1", since = "1.0.0")]
1273    #[inline]
1274    pub fn lines(&self) -> Lines<'_> {
1275        Lines(self.split_inclusive('\n').map(LinesMap))
1276    }
1277
1278    /// Returns an iterator over the lines of a string.
1279    #[stable(feature = "rust1", since = "1.0.0")]
1280    #[deprecated(since = "1.4.0", note = "use lines() instead now", suggestion = "lines")]
1281    #[inline]
1282    #[allow(deprecated)]
1283    pub fn lines_any(&self) -> LinesAny<'_> {
1284        LinesAny(self.lines())
1285    }
1286
1287    /// Returns an iterator of `u16` over the string encoded
1288    /// as native endian UTF-16 (without byte-order mark).
1289    ///
1290    /// # Examples
1291    ///
1292    /// ```
1293    /// let text = "Zażółć gęślą jaźń";
1294    ///
1295    /// let utf8_len = text.len();
1296    /// let utf16_len = text.encode_utf16().count();
1297    ///
1298    /// assert!(utf16_len <= utf8_len);
1299    /// ```
1300    #[must_use = "this returns the encoded string as an iterator, \
1301                  without modifying the original"]
1302    #[stable(feature = "encode_utf16", since = "1.8.0")]
1303    pub fn encode_utf16(&self) -> EncodeUtf16<'_> {
1304        EncodeUtf16 { chars: self.chars(), extra: 0 }
1305    }
1306
1307    /// Returns `true` if the given pattern matches a sub-slice of
1308    /// this string slice.
1309    ///
1310    /// Returns `false` if it does not.
1311    ///
1312    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1313    /// function or closure that determines if a character matches.
1314    ///
1315    /// [`char`]: prim@char
1316    /// [pattern]: self::pattern
1317    ///
1318    /// # Examples
1319    ///
1320    /// ```
1321    /// let bananas = "bananas";
1322    ///
1323    /// assert!(bananas.contains("nana"));
1324    /// assert!(!bananas.contains("apples"));
1325    /// ```
1326    #[stable(feature = "rust1", since = "1.0.0")]
1327    #[inline]
1328    pub fn contains<P: Pattern>(&self, pat: P) -> bool {
1329        pat.is_contained_in(self)
1330    }
1331
1332    /// Returns `true` if the given pattern matches a prefix of this
1333    /// string slice.
1334    ///
1335    /// Returns `false` if it does not.
1336    ///
1337    /// The [pattern] can be a `&str`, in which case this function will return true if
1338    /// the `&str` is a prefix of this string slice.
1339    ///
1340    /// The [pattern] can also be a [`char`], a slice of [`char`]s, or a
1341    /// function or closure that determines if a character matches.
1342    /// These will only be checked against the first character of this string slice.
1343    /// Look at the second example below regarding behavior for slices of [`char`]s.
1344    ///
1345    /// [`char`]: prim@char
1346    /// [pattern]: self::pattern
1347    ///
1348    /// # Examples
1349    ///
1350    /// ```
1351    /// let bananas = "bananas";
1352    ///
1353    /// assert!(bananas.starts_with("bana"));
1354    /// assert!(!bananas.starts_with("nana"));
1355    /// ```
1356    ///
1357    /// ```
1358    /// let bananas = "bananas";
1359    ///
1360    /// // Note that both of these assert successfully.
1361    /// assert!(bananas.starts_with(&['b', 'a', 'n', 'a']));
1362    /// assert!(bananas.starts_with(&['a', 'b', 'c', 'd']));
1363    /// ```
1364    #[stable(feature = "rust1", since = "1.0.0")]
1365    #[cfg_attr(not(test), rustc_diagnostic_item = "str_starts_with")]
1366    pub fn starts_with<P: Pattern>(&self, pat: P) -> bool {
1367        pat.is_prefix_of(self)
1368    }
1369
1370    /// Returns `true` if the given pattern matches a suffix of this
1371    /// string slice.
1372    ///
1373    /// Returns `false` if it does not.
1374    ///
1375    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1376    /// function or closure that determines if a character matches.
1377    ///
1378    /// [`char`]: prim@char
1379    /// [pattern]: self::pattern
1380    ///
1381    /// # Examples
1382    ///
1383    /// ```
1384    /// let bananas = "bananas";
1385    ///
1386    /// assert!(bananas.ends_with("anas"));
1387    /// assert!(!bananas.ends_with("nana"));
1388    /// ```
1389    #[stable(feature = "rust1", since = "1.0.0")]
1390    #[cfg_attr(not(test), rustc_diagnostic_item = "str_ends_with")]
1391    pub fn ends_with<P: Pattern>(&self, pat: P) -> bool
1392    where
1393        for<'a> P::Searcher<'a>: ReverseSearcher<'a>,
1394    {
1395        pat.is_suffix_of(self)
1396    }
1397
1398    /// Returns the byte index of the first character of this string slice that
1399    /// matches the pattern.
1400    ///
1401    /// Returns [`None`] if the pattern doesn't match.
1402    ///
1403    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1404    /// function or closure that determines if a character matches.
1405    ///
1406    /// [`char`]: prim@char
1407    /// [pattern]: self::pattern
1408    ///
1409    /// # Examples
1410    ///
1411    /// Simple patterns:
1412    ///
1413    /// ```
1414    /// let s = "Löwe 老虎 Léopard Gepardi";
1415    ///
1416    /// assert_eq!(s.find('L'), Some(0));
1417    /// assert_eq!(s.find('é'), Some(14));
1418    /// assert_eq!(s.find("pard"), Some(17));
1419    /// ```
1420    ///
1421    /// More complex patterns using point-free style and closures:
1422    ///
1423    /// ```
1424    /// let s = "Löwe 老虎 Léopard";
1425    ///
1426    /// assert_eq!(s.find(char::is_whitespace), Some(5));
1427    /// assert_eq!(s.find(char::is_lowercase), Some(1));
1428    /// assert_eq!(s.find(|c: char| c.is_whitespace() || c.is_lowercase()), Some(1));
1429    /// assert_eq!(s.find(|c: char| (c < 'o') && (c > 'a')), Some(4));
1430    /// ```
1431    ///
1432    /// Not finding the pattern:
1433    ///
1434    /// ```
1435    /// let s = "Löwe 老虎 Léopard";
1436    /// let x: &[_] = &['1', '2'];
1437    ///
1438    /// assert_eq!(s.find(x), None);
1439    /// ```
1440    #[stable(feature = "rust1", since = "1.0.0")]
1441    #[inline]
1442    pub fn find<P: Pattern>(&self, pat: P) -> Option<usize> {
1443        pat.into_searcher(self).next_match().map(|(i, _)| i)
1444    }
1445
1446    /// Returns the byte index for the first character of the last match of the pattern in
1447    /// this string slice.
1448    ///
1449    /// Returns [`None`] if the pattern doesn't match.
1450    ///
1451    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1452    /// function or closure that determines if a character matches.
1453    ///
1454    /// [`char`]: prim@char
1455    /// [pattern]: self::pattern
1456    ///
1457    /// # Examples
1458    ///
1459    /// Simple patterns:
1460    ///
1461    /// ```
1462    /// let s = "Löwe 老虎 Léopard Gepardi";
1463    ///
1464    /// assert_eq!(s.rfind('L'), Some(13));
1465    /// assert_eq!(s.rfind('é'), Some(14));
1466    /// assert_eq!(s.rfind("pard"), Some(24));
1467    /// ```
1468    ///
1469    /// More complex patterns with closures:
1470    ///
1471    /// ```
1472    /// let s = "Löwe 老虎 Léopard";
1473    ///
1474    /// assert_eq!(s.rfind(char::is_whitespace), Some(12));
1475    /// assert_eq!(s.rfind(char::is_lowercase), Some(20));
1476    /// ```
1477    ///
1478    /// Not finding the pattern:
1479    ///
1480    /// ```
1481    /// let s = "Löwe 老虎 Léopard";
1482    /// let x: &[_] = &['1', '2'];
1483    ///
1484    /// assert_eq!(s.rfind(x), None);
1485    /// ```
1486    #[stable(feature = "rust1", since = "1.0.0")]
1487    #[inline]
1488    pub fn rfind<P: Pattern>(&self, pat: P) -> Option<usize>
1489    where
1490        for<'a> P::Searcher<'a>: ReverseSearcher<'a>,
1491    {
1492        pat.into_searcher(self).next_match_back().map(|(i, _)| i)
1493    }
1494
1495    /// Returns an iterator over substrings of this string slice, separated by
1496    /// characters matched by a pattern.
1497    ///
1498    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1499    /// function or closure that determines if a character matches.
1500    ///
1501    /// [`char`]: prim@char
1502    /// [pattern]: self::pattern
1503    ///
1504    /// # Iterator behavior
1505    ///
1506    /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
1507    /// allows a reverse search and forward/reverse search yields the same
1508    /// elements. This is true for, e.g., [`char`], but not for `&str`.
1509    ///
1510    /// If the pattern allows a reverse search but its results might differ
1511    /// from a forward search, the [`rsplit`] method can be used.
1512    ///
1513    /// [`rsplit`]: str::rsplit
1514    ///
1515    /// # Examples
1516    ///
1517    /// Simple patterns:
1518    ///
1519    /// ```
1520    /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
1521    /// assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);
1522    ///
1523    /// let v: Vec<&str> = "".split('X').collect();
1524    /// assert_eq!(v, [""]);
1525    ///
1526    /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
1527    /// assert_eq!(v, ["lion", "", "tiger", "leopard"]);
1528    ///
1529    /// let v: Vec<&str> = "lion::tiger::leopard".split("::").collect();
1530    /// assert_eq!(v, ["lion", "tiger", "leopard"]);
1531    ///
1532    /// let v: Vec<&str> = "abc1def2ghi".split(char::is_numeric).collect();
1533    /// assert_eq!(v, ["abc", "def", "ghi"]);
1534    ///
1535    /// let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect();
1536    /// assert_eq!(v, ["lion", "tiger", "leopard"]);
1537    /// ```
1538    ///
1539    /// If the pattern is a slice of chars, split on each occurrence of any of the characters:
1540    ///
1541    /// ```
1542    /// let v: Vec<&str> = "2020-11-03 23:59".split(&['-', ' ', ':', '@'][..]).collect();
1543    /// assert_eq!(v, ["2020", "11", "03", "23", "59"]);
1544    /// ```
1545    ///
1546    /// A more complex pattern, using a closure:
1547    ///
1548    /// ```
1549    /// let v: Vec<&str> = "abc1defXghi".split(|c| c == '1' || c == 'X').collect();
1550    /// assert_eq!(v, ["abc", "def", "ghi"]);
1551    /// ```
1552    ///
1553    /// If a string contains multiple contiguous separators, you will end up
1554    /// with empty strings in the output:
1555    ///
1556    /// ```
1557    /// let x = "||||a||b|c".to_string();
1558    /// let d: Vec<_> = x.split('|').collect();
1559    ///
1560    /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
1561    /// ```
1562    ///
1563    /// Contiguous separators are separated by the empty string.
1564    ///
1565    /// ```
1566    /// let x = "(///)".to_string();
1567    /// let d: Vec<_> = x.split('/').collect();
1568    ///
1569    /// assert_eq!(d, &["(", "", "", ")"]);
1570    /// ```
1571    ///
1572    /// Separators at the start or end of a string are neighbored
1573    /// by empty strings.
1574    ///
1575    /// ```
1576    /// let d: Vec<_> = "010".split("0").collect();
1577    /// assert_eq!(d, &["", "1", ""]);
1578    /// ```
1579    ///
1580    /// When the empty string is used as a separator, it separates
1581    /// every character in the string, along with the beginning
1582    /// and end of the string.
1583    ///
1584    /// ```
1585    /// let f: Vec<_> = "rust".split("").collect();
1586    /// assert_eq!(f, &["", "r", "u", "s", "t", ""]);
1587    /// ```
1588    ///
1589    /// Contiguous separators can lead to possibly surprising behavior
1590    /// when whitespace is used as the separator. This code is correct:
1591    ///
1592    /// ```
1593    /// let x = "    a  b c".to_string();
1594    /// let d: Vec<_> = x.split(' ').collect();
1595    ///
1596    /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
1597    /// ```
1598    ///
1599    /// It does _not_ give you:
1600    ///
1601    /// ```,ignore
1602    /// assert_eq!(d, &["a", "b", "c"]);
1603    /// ```
1604    ///
1605    /// Use [`split_whitespace`] for this behavior.
1606    ///
1607    /// [`split_whitespace`]: str::split_whitespace
1608    #[stable(feature = "rust1", since = "1.0.0")]
1609    #[inline]
1610    pub fn split<P: Pattern>(&self, pat: P) -> Split<'_, P> {
1611        Split(SplitInternal {
1612            start: 0,
1613            end: self.len(),
1614            matcher: pat.into_searcher(self),
1615            allow_trailing_empty: true,
1616            finished: false,
1617        })
1618    }
1619
1620    /// Returns an iterator over substrings of this string slice, separated by
1621    /// characters matched by a pattern.
1622    ///
1623    /// Differs from the iterator produced by `split` in that `split_inclusive`
1624    /// leaves the matched part as the terminator of the substring.
1625    ///
1626    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1627    /// function or closure that determines if a character matches.
1628    ///
1629    /// [`char`]: prim@char
1630    /// [pattern]: self::pattern
1631    ///
1632    /// # Examples
1633    ///
1634    /// ```
1635    /// let v: Vec<&str> = "Mary had a little lamb\nlittle lamb\nlittle lamb."
1636    ///     .split_inclusive('\n').collect();
1637    /// assert_eq!(v, ["Mary had a little lamb\n", "little lamb\n", "little lamb."]);
1638    /// ```
1639    ///
1640    /// If the last element of the string is matched,
1641    /// that element will be considered the terminator of the preceding substring.
1642    /// That substring will be the last item returned by the iterator.
1643    ///
1644    /// ```
1645    /// let v: Vec<&str> = "Mary had a little lamb\nlittle lamb\nlittle lamb.\n"
1646    ///     .split_inclusive('\n').collect();
1647    /// assert_eq!(v, ["Mary had a little lamb\n", "little lamb\n", "little lamb.\n"]);
1648    /// ```
1649    #[stable(feature = "split_inclusive", since = "1.51.0")]
1650    #[inline]
1651    pub fn split_inclusive<P: Pattern>(&self, pat: P) -> SplitInclusive<'_, P> {
1652        SplitInclusive(SplitInternal {
1653            start: 0,
1654            end: self.len(),
1655            matcher: pat.into_searcher(self),
1656            allow_trailing_empty: false,
1657            finished: false,
1658        })
1659    }
1660
1661    /// Returns an iterator over substrings of the given string slice, separated
1662    /// by characters matched by a pattern and yielded in reverse order.
1663    ///
1664    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1665    /// function or closure that determines if a character matches.
1666    ///
1667    /// [`char`]: prim@char
1668    /// [pattern]: self::pattern
1669    ///
1670    /// # Iterator behavior
1671    ///
1672    /// The returned iterator requires that the pattern supports a reverse
1673    /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
1674    /// search yields the same elements.
1675    ///
1676    /// For iterating from the front, the [`split`] method can be used.
1677    ///
1678    /// [`split`]: str::split
1679    ///
1680    /// # Examples
1681    ///
1682    /// Simple patterns:
1683    ///
1684    /// ```
1685    /// let v: Vec<&str> = "Mary had a little lamb".rsplit(' ').collect();
1686    /// assert_eq!(v, ["lamb", "little", "a", "had", "Mary"]);
1687    ///
1688    /// let v: Vec<&str> = "".rsplit('X').collect();
1689    /// assert_eq!(v, [""]);
1690    ///
1691    /// let v: Vec<&str> = "lionXXtigerXleopard".rsplit('X').collect();
1692    /// assert_eq!(v, ["leopard", "tiger", "", "lion"]);
1693    ///
1694    /// let v: Vec<&str> = "lion::tiger::leopard".rsplit("::").collect();
1695    /// assert_eq!(v, ["leopard", "tiger", "lion"]);
1696    /// ```
1697    ///
1698    /// A more complex pattern, using a closure:
1699    ///
1700    /// ```
1701    /// let v: Vec<&str> = "abc1defXghi".rsplit(|c| c == '1' || c == 'X').collect();
1702    /// assert_eq!(v, ["ghi", "def", "abc"]);
1703    /// ```
1704    #[stable(feature = "rust1", since = "1.0.0")]
1705    #[inline]
1706    pub fn rsplit<P: Pattern>(&self, pat: P) -> RSplit<'_, P>
1707    where
1708        for<'a> P::Searcher<'a>: ReverseSearcher<'a>,
1709    {
1710        RSplit(self.split(pat).0)
1711    }
1712
1713    /// Returns an iterator over substrings of the given string slice, separated
1714    /// by characters matched by a pattern.
1715    ///
1716    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1717    /// function or closure that determines if a character matches.
1718    ///
1719    /// [`char`]: prim@char
1720    /// [pattern]: self::pattern
1721    ///
1722    /// Equivalent to [`split`], except that the trailing substring
1723    /// is skipped if empty.
1724    ///
1725    /// [`split`]: str::split
1726    ///
1727    /// This method can be used for string data that is _terminated_,
1728    /// rather than _separated_ by a pattern.
1729    ///
1730    /// # Iterator behavior
1731    ///
1732    /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
1733    /// allows a reverse search and forward/reverse search yields the same
1734    /// elements. This is true for, e.g., [`char`], but not for `&str`.
1735    ///
1736    /// If the pattern allows a reverse search but its results might differ
1737    /// from a forward search, the [`rsplit_terminator`] method can be used.
1738    ///
1739    /// [`rsplit_terminator`]: str::rsplit_terminator
1740    ///
1741    /// # Examples
1742    ///
1743    /// ```
1744    /// let v: Vec<&str> = "A.B.".split_terminator('.').collect();
1745    /// assert_eq!(v, ["A", "B"]);
1746    ///
1747    /// let v: Vec<&str> = "A..B..".split_terminator(".").collect();
1748    /// assert_eq!(v, ["A", "", "B", ""]);
1749    ///
1750    /// let v: Vec<&str> = "A.B:C.D".split_terminator(&['.', ':'][..]).collect();
1751    /// assert_eq!(v, ["A", "B", "C", "D"]);
1752    /// ```
1753    #[stable(feature = "rust1", since = "1.0.0")]
1754    #[inline]
1755    pub fn split_terminator<P: Pattern>(&self, pat: P) -> SplitTerminator<'_, P> {
1756        SplitTerminator(SplitInternal { allow_trailing_empty: false, ..self.split(pat).0 })
1757    }
1758
1759    /// Returns an iterator over substrings of `self`, separated by characters
1760    /// matched by a pattern and yielded in reverse order.
1761    ///
1762    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1763    /// function or closure that determines if a character matches.
1764    ///
1765    /// [`char`]: prim@char
1766    /// [pattern]: self::pattern
1767    ///
1768    /// Equivalent to [`split`], except that the trailing substring is
1769    /// skipped if empty.
1770    ///
1771    /// [`split`]: str::split
1772    ///
1773    /// This method can be used for string data that is _terminated_,
1774    /// rather than _separated_ by a pattern.
1775    ///
1776    /// # Iterator behavior
1777    ///
1778    /// The returned iterator requires that the pattern supports a
1779    /// reverse search, and it will be double ended if a forward/reverse
1780    /// search yields the same elements.
1781    ///
1782    /// For iterating from the front, the [`split_terminator`] method can be
1783    /// used.
1784    ///
1785    /// [`split_terminator`]: str::split_terminator
1786    ///
1787    /// # Examples
1788    ///
1789    /// ```
1790    /// let v: Vec<&str> = "A.B.".rsplit_terminator('.').collect();
1791    /// assert_eq!(v, ["B", "A"]);
1792    ///
1793    /// let v: Vec<&str> = "A..B..".rsplit_terminator(".").collect();
1794    /// assert_eq!(v, ["", "B", "", "A"]);
1795    ///
1796    /// let v: Vec<&str> = "A.B:C.D".rsplit_terminator(&['.', ':'][..]).collect();
1797    /// assert_eq!(v, ["D", "C", "B", "A"]);
1798    /// ```
1799    #[stable(feature = "rust1", since = "1.0.0")]
1800    #[inline]
1801    pub fn rsplit_terminator<P: Pattern>(&self, pat: P) -> RSplitTerminator<'_, P>
1802    where
1803        for<'a> P::Searcher<'a>: ReverseSearcher<'a>,
1804    {
1805        RSplitTerminator(self.split_terminator(pat).0)
1806    }
1807
1808    /// Returns an iterator over substrings of the given string slice, separated
1809    /// by a pattern, restricted to returning at most `n` items.
1810    ///
1811    /// If `n` substrings are returned, the last substring (the `n`th substring)
1812    /// will contain the remainder of the string.
1813    ///
1814    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1815    /// function or closure that determines if a character matches.
1816    ///
1817    /// [`char`]: prim@char
1818    /// [pattern]: self::pattern
1819    ///
1820    /// # Iterator behavior
1821    ///
1822    /// The returned iterator will not be double ended, because it is
1823    /// not efficient to support.
1824    ///
1825    /// If the pattern allows a reverse search, the [`rsplitn`] method can be
1826    /// used.
1827    ///
1828    /// [`rsplitn`]: str::rsplitn
1829    ///
1830    /// # Examples
1831    ///
1832    /// Simple patterns:
1833    ///
1834    /// ```
1835    /// let v: Vec<&str> = "Mary had a little lambda".splitn(3, ' ').collect();
1836    /// assert_eq!(v, ["Mary", "had", "a little lambda"]);
1837    ///
1838    /// let v: Vec<&str> = "lionXXtigerXleopard".splitn(3, "X").collect();
1839    /// assert_eq!(v, ["lion", "", "tigerXleopard"]);
1840    ///
1841    /// let v: Vec<&str> = "abcXdef".splitn(1, 'X').collect();
1842    /// assert_eq!(v, ["abcXdef"]);
1843    ///
1844    /// let v: Vec<&str> = "".splitn(1, 'X').collect();
1845    /// assert_eq!(v, [""]);
1846    /// ```
1847    ///
1848    /// A more complex pattern, using a closure:
1849    ///
1850    /// ```
1851    /// let v: Vec<&str> = "abc1defXghi".splitn(2, |c| c == '1' || c == 'X').collect();
1852    /// assert_eq!(v, ["abc", "defXghi"]);
1853    /// ```
1854    #[stable(feature = "rust1", since = "1.0.0")]
1855    #[inline]
1856    pub fn splitn<P: Pattern>(&self, n: usize, pat: P) -> SplitN<'_, P> {
1857        SplitN(SplitNInternal { iter: self.split(pat).0, count: n })
1858    }
1859
1860    /// Returns an iterator over substrings of this string slice, separated by a
1861    /// pattern, starting from the end of the string, restricted to returning at
1862    /// most `n` items.
1863    ///
1864    /// If `n` substrings are returned, the last substring (the `n`th substring)
1865    /// will contain the remainder of the string.
1866    ///
1867    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1868    /// function or closure that determines if a character matches.
1869    ///
1870    /// [`char`]: prim@char
1871    /// [pattern]: self::pattern
1872    ///
1873    /// # Iterator behavior
1874    ///
1875    /// The returned iterator will not be double ended, because it is not
1876    /// efficient to support.
1877    ///
1878    /// For splitting from the front, the [`splitn`] method can be used.
1879    ///
1880    /// [`splitn`]: str::splitn
1881    ///
1882    /// # Examples
1883    ///
1884    /// Simple patterns:
1885    ///
1886    /// ```
1887    /// let v: Vec<&str> = "Mary had a little lamb".rsplitn(3, ' ').collect();
1888    /// assert_eq!(v, ["lamb", "little", "Mary had a"]);
1889    ///
1890    /// let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(3, 'X').collect();
1891    /// assert_eq!(v, ["leopard", "tiger", "lionX"]);
1892    ///
1893    /// let v: Vec<&str> = "lion::tiger::leopard".rsplitn(2, "::").collect();
1894    /// assert_eq!(v, ["leopard", "lion::tiger"]);
1895    /// ```
1896    ///
1897    /// A more complex pattern, using a closure:
1898    ///
1899    /// ```
1900    /// let v: Vec<&str> = "abc1defXghi".rsplitn(2, |c| c == '1' || c == 'X').collect();
1901    /// assert_eq!(v, ["ghi", "abc1def"]);
1902    /// ```
1903    #[stable(feature = "rust1", since = "1.0.0")]
1904    #[inline]
1905    pub fn rsplitn<P: Pattern>(&self, n: usize, pat: P) -> RSplitN<'_, P>
1906    where
1907        for<'a> P::Searcher<'a>: ReverseSearcher<'a>,
1908    {
1909        RSplitN(self.splitn(n, pat).0)
1910    }
1911
1912    /// Splits the string on the first occurrence of the specified delimiter and
1913    /// returns prefix before delimiter and suffix after delimiter.
1914    ///
1915    /// # Examples
1916    ///
1917    /// ```
1918    /// assert_eq!("cfg".split_once('='), None);
1919    /// assert_eq!("cfg=".split_once('='), Some(("cfg", "")));
1920    /// assert_eq!("cfg=foo".split_once('='), Some(("cfg", "foo")));
1921    /// assert_eq!("cfg=foo=bar".split_once('='), Some(("cfg", "foo=bar")));
1922    /// ```
1923    #[stable(feature = "str_split_once", since = "1.52.0")]
1924    #[inline]
1925    pub fn split_once<P: Pattern>(&self, delimiter: P) -> Option<(&'_ str, &'_ str)> {
1926        let (start, end) = delimiter.into_searcher(self).next_match()?;
1927        // SAFETY: `Searcher` is known to return valid indices.
1928        unsafe { Some((self.get_unchecked(..start), self.get_unchecked(end..))) }
1929    }
1930
1931    /// Splits the string on the last occurrence of the specified delimiter and
1932    /// returns prefix before delimiter and suffix after delimiter.
1933    ///
1934    /// # Examples
1935    ///
1936    /// ```
1937    /// assert_eq!("cfg".rsplit_once('='), None);
1938    /// assert_eq!("cfg=foo".rsplit_once('='), Some(("cfg", "foo")));
1939    /// assert_eq!("cfg=foo=bar".rsplit_once('='), Some(("cfg=foo", "bar")));
1940    /// ```
1941    #[stable(feature = "str_split_once", since = "1.52.0")]
1942    #[inline]
1943    pub fn rsplit_once<P: Pattern>(&self, delimiter: P) -> Option<(&'_ str, &'_ str)>
1944    where
1945        for<'a> P::Searcher<'a>: ReverseSearcher<'a>,
1946    {
1947        let (start, end) = delimiter.into_searcher(self).next_match_back()?;
1948        // SAFETY: `Searcher` is known to return valid indices.
1949        unsafe { Some((self.get_unchecked(..start), self.get_unchecked(end..))) }
1950    }
1951
1952    /// Returns an iterator over the disjoint matches of a pattern within the
1953    /// given string slice.
1954    ///
1955    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1956    /// function or closure that determines if a character matches.
1957    ///
1958    /// [`char`]: prim@char
1959    /// [pattern]: self::pattern
1960    ///
1961    /// # Iterator behavior
1962    ///
1963    /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
1964    /// allows a reverse search and forward/reverse search yields the same
1965    /// elements. This is true for, e.g., [`char`], but not for `&str`.
1966    ///
1967    /// If the pattern allows a reverse search but its results might differ
1968    /// from a forward search, the [`rmatches`] method can be used.
1969    ///
1970    /// [`rmatches`]: str::rmatches
1971    ///
1972    /// # Examples
1973    ///
1974    /// ```
1975    /// let v: Vec<&str> = "abcXXXabcYYYabc".matches("abc").collect();
1976    /// assert_eq!(v, ["abc", "abc", "abc"]);
1977    ///
1978    /// let v: Vec<&str> = "1abc2abc3".matches(char::is_numeric).collect();
1979    /// assert_eq!(v, ["1", "2", "3"]);
1980    /// ```
1981    #[stable(feature = "str_matches", since = "1.2.0")]
1982    #[inline]
1983    pub fn matches<P: Pattern>(&self, pat: P) -> Matches<'_, P> {
1984        Matches(MatchesInternal(pat.into_searcher(self)))
1985    }
1986
1987    /// Returns an iterator over the disjoint matches of a pattern within this
1988    /// string slice, yielded in reverse order.
1989    ///
1990    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
1991    /// function or closure that determines if a character matches.
1992    ///
1993    /// [`char`]: prim@char
1994    /// [pattern]: self::pattern
1995    ///
1996    /// # Iterator behavior
1997    ///
1998    /// The returned iterator requires that the pattern supports a reverse
1999    /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
2000    /// search yields the same elements.
2001    ///
2002    /// For iterating from the front, the [`matches`] method can be used.
2003    ///
2004    /// [`matches`]: str::matches
2005    ///
2006    /// # Examples
2007    ///
2008    /// ```
2009    /// let v: Vec<&str> = "abcXXXabcYYYabc".rmatches("abc").collect();
2010    /// assert_eq!(v, ["abc", "abc", "abc"]);
2011    ///
2012    /// let v: Vec<&str> = "1abc2abc3".rmatches(char::is_numeric).collect();
2013    /// assert_eq!(v, ["3", "2", "1"]);
2014    /// ```
2015    #[stable(feature = "str_matches", since = "1.2.0")]
2016    #[inline]
2017    pub fn rmatches<P: Pattern>(&self, pat: P) -> RMatches<'_, P>
2018    where
2019        for<'a> P::Searcher<'a>: ReverseSearcher<'a>,
2020    {
2021        RMatches(self.matches(pat).0)
2022    }
2023
2024    /// Returns an iterator over the disjoint matches of a pattern within this string
2025    /// slice as well as the index that the match starts at.
2026    ///
2027    /// For matches of `pat` within `self` that overlap, only the indices
2028    /// corresponding to the first match are returned.
2029    ///
2030    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2031    /// function or closure that determines if a character matches.
2032    ///
2033    /// [`char`]: prim@char
2034    /// [pattern]: self::pattern
2035    ///
2036    /// # Iterator behavior
2037    ///
2038    /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
2039    /// allows a reverse search and forward/reverse search yields the same
2040    /// elements. This is true for, e.g., [`char`], but not for `&str`.
2041    ///
2042    /// If the pattern allows a reverse search but its results might differ
2043    /// from a forward search, the [`rmatch_indices`] method can be used.
2044    ///
2045    /// [`rmatch_indices`]: str::rmatch_indices
2046    ///
2047    /// # Examples
2048    ///
2049    /// ```
2050    /// let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
2051    /// assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
2052    ///
2053    /// let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
2054    /// assert_eq!(v, [(1, "abc"), (4, "abc")]);
2055    ///
2056    /// let v: Vec<_> = "ababa".match_indices("aba").collect();
2057    /// assert_eq!(v, [(0, "aba")]); // only the first `aba`
2058    /// ```
2059    #[stable(feature = "str_match_indices", since = "1.5.0")]
2060    #[inline]
2061    pub fn match_indices<P: Pattern>(&self, pat: P) -> MatchIndices<'_, P> {
2062        MatchIndices(MatchIndicesInternal(pat.into_searcher(self)))
2063    }
2064
2065    /// Returns an iterator over the disjoint matches of a pattern within `self`,
2066    /// yielded in reverse order along with the index of the match.
2067    ///
2068    /// For matches of `pat` within `self` that overlap, only the indices
2069    /// corresponding to the last match are returned.
2070    ///
2071    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2072    /// function or closure that determines if a character matches.
2073    ///
2074    /// [`char`]: prim@char
2075    /// [pattern]: self::pattern
2076    ///
2077    /// # Iterator behavior
2078    ///
2079    /// The returned iterator requires that the pattern supports a reverse
2080    /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
2081    /// search yields the same elements.
2082    ///
2083    /// For iterating from the front, the [`match_indices`] method can be used.
2084    ///
2085    /// [`match_indices`]: str::match_indices
2086    ///
2087    /// # Examples
2088    ///
2089    /// ```
2090    /// let v: Vec<_> = "abcXXXabcYYYabc".rmatch_indices("abc").collect();
2091    /// assert_eq!(v, [(12, "abc"), (6, "abc"), (0, "abc")]);
2092    ///
2093    /// let v: Vec<_> = "1abcabc2".rmatch_indices("abc").collect();
2094    /// assert_eq!(v, [(4, "abc"), (1, "abc")]);
2095    ///
2096    /// let v: Vec<_> = "ababa".rmatch_indices("aba").collect();
2097    /// assert_eq!(v, [(2, "aba")]); // only the last `aba`
2098    /// ```
2099    #[stable(feature = "str_match_indices", since = "1.5.0")]
2100    #[inline]
2101    pub fn rmatch_indices<P: Pattern>(&self, pat: P) -> RMatchIndices<'_, P>
2102    where
2103        for<'a> P::Searcher<'a>: ReverseSearcher<'a>,
2104    {
2105        RMatchIndices(self.match_indices(pat).0)
2106    }
2107
2108    /// Returns a string slice with leading and trailing whitespace removed.
2109    ///
2110    /// 'Whitespace' is defined according to the terms of the Unicode Derived
2111    /// Core Property `White_Space`, which includes newlines.
2112    ///
2113    /// # Examples
2114    ///
2115    /// ```
2116    /// let s = "\n Hello\tworld\t\n";
2117    ///
2118    /// assert_eq!("Hello\tworld", s.trim());
2119    /// ```
2120    #[inline]
2121    #[must_use = "this returns the trimmed string as a slice, \
2122                  without modifying the original"]
2123    #[stable(feature = "rust1", since = "1.0.0")]
2124    #[cfg_attr(not(test), rustc_diagnostic_item = "str_trim")]
2125    pub fn trim(&self) -> &str {
2126        self.trim_matches(|c: char| c.is_whitespace())
2127    }
2128
2129    /// Returns a string slice with leading whitespace removed.
2130    ///
2131    /// 'Whitespace' is defined according to the terms of the Unicode Derived
2132    /// Core Property `White_Space`, which includes newlines.
2133    ///
2134    /// # Text directionality
2135    ///
2136    /// A string is a sequence of bytes. `start` in this context means the first
2137    /// position of that byte string; for a left-to-right language like English or
2138    /// Russian, this will be left side, and for right-to-left languages like
2139    /// Arabic or Hebrew, this will be the right side.
2140    ///
2141    /// # Examples
2142    ///
2143    /// Basic usage:
2144    ///
2145    /// ```
2146    /// let s = "\n Hello\tworld\t\n";
2147    /// assert_eq!("Hello\tworld\t\n", s.trim_start());
2148    /// ```
2149    ///
2150    /// Directionality:
2151    ///
2152    /// ```
2153    /// let s = "  English  ";
2154    /// assert!(Some('E') == s.trim_start().chars().next());
2155    ///
2156    /// let s = "  עברית  ";
2157    /// assert!(Some('ע') == s.trim_start().chars().next());
2158    /// ```
2159    #[inline]
2160    #[must_use = "this returns the trimmed string as a new slice, \
2161                  without modifying the original"]
2162    #[stable(feature = "trim_direction", since = "1.30.0")]
2163    #[cfg_attr(not(test), rustc_diagnostic_item = "str_trim_start")]
2164    pub fn trim_start(&self) -> &str {
2165        self.trim_start_matches(|c: char| c.is_whitespace())
2166    }
2167
2168    /// Returns a string slice with trailing whitespace removed.
2169    ///
2170    /// 'Whitespace' is defined according to the terms of the Unicode Derived
2171    /// Core Property `White_Space`, which includes newlines.
2172    ///
2173    /// # Text directionality
2174    ///
2175    /// A string is a sequence of bytes. `end` in this context means the last
2176    /// position of that byte string; for a left-to-right language like English or
2177    /// Russian, this will be right side, and for right-to-left languages like
2178    /// Arabic or Hebrew, this will be the left side.
2179    ///
2180    /// # Examples
2181    ///
2182    /// Basic usage:
2183    ///
2184    /// ```
2185    /// let s = "\n Hello\tworld\t\n";
2186    /// assert_eq!("\n Hello\tworld", s.trim_end());
2187    /// ```
2188    ///
2189    /// Directionality:
2190    ///
2191    /// ```
2192    /// let s = "  English  ";
2193    /// assert!(Some('h') == s.trim_end().chars().rev().next());
2194    ///
2195    /// let s = "  עברית  ";
2196    /// assert!(Some('ת') == s.trim_end().chars().rev().next());
2197    /// ```
2198    #[inline]
2199    #[must_use = "this returns the trimmed string as a new slice, \
2200                  without modifying the original"]
2201    #[stable(feature = "trim_direction", since = "1.30.0")]
2202    #[cfg_attr(not(test), rustc_diagnostic_item = "str_trim_end")]
2203    pub fn trim_end(&self) -> &str {
2204        self.trim_end_matches(|c: char| c.is_whitespace())
2205    }
2206
2207    /// Returns a string slice with leading whitespace removed.
2208    ///
2209    /// 'Whitespace' is defined according to the terms of the Unicode Derived
2210    /// Core Property `White_Space`.
2211    ///
2212    /// # Text directionality
2213    ///
2214    /// A string is a sequence of bytes. 'Left' in this context means the first
2215    /// position of that byte string; for a language like Arabic or Hebrew
2216    /// which are 'right to left' rather than 'left to right', this will be
2217    /// the _right_ side, not the left.
2218    ///
2219    /// # Examples
2220    ///
2221    /// Basic usage:
2222    ///
2223    /// ```
2224    /// let s = " Hello\tworld\t";
2225    ///
2226    /// assert_eq!("Hello\tworld\t", s.trim_left());
2227    /// ```
2228    ///
2229    /// Directionality:
2230    ///
2231    /// ```
2232    /// let s = "  English";
2233    /// assert!(Some('E') == s.trim_left().chars().next());
2234    ///
2235    /// let s = "  עברית";
2236    /// assert!(Some('ע') == s.trim_left().chars().next());
2237    /// ```
2238    #[must_use = "this returns the trimmed string as a new slice, \
2239                  without modifying the original"]
2240    #[inline]
2241    #[stable(feature = "rust1", since = "1.0.0")]
2242    #[deprecated(since = "1.33.0", note = "superseded by `trim_start`", suggestion = "trim_start")]
2243    pub fn trim_left(&self) -> &str {
2244        self.trim_start()
2245    }
2246
2247    /// Returns a string slice with trailing whitespace removed.
2248    ///
2249    /// 'Whitespace' is defined according to the terms of the Unicode Derived
2250    /// Core Property `White_Space`.
2251    ///
2252    /// # Text directionality
2253    ///
2254    /// A string is a sequence of bytes. 'Right' in this context means the last
2255    /// position of that byte string; for a language like Arabic or Hebrew
2256    /// which are 'right to left' rather than 'left to right', this will be
2257    /// the _left_ side, not the right.
2258    ///
2259    /// # Examples
2260    ///
2261    /// Basic usage:
2262    ///
2263    /// ```
2264    /// let s = " Hello\tworld\t";
2265    ///
2266    /// assert_eq!(" Hello\tworld", s.trim_right());
2267    /// ```
2268    ///
2269    /// Directionality:
2270    ///
2271    /// ```
2272    /// let s = "English  ";
2273    /// assert!(Some('h') == s.trim_right().chars().rev().next());
2274    ///
2275    /// let s = "עברית  ";
2276    /// assert!(Some('ת') == s.trim_right().chars().rev().next());
2277    /// ```
2278    #[must_use = "this returns the trimmed string as a new slice, \
2279                  without modifying the original"]
2280    #[inline]
2281    #[stable(feature = "rust1", since = "1.0.0")]
2282    #[deprecated(since = "1.33.0", note = "superseded by `trim_end`", suggestion = "trim_end")]
2283    pub fn trim_right(&self) -> &str {
2284        self.trim_end()
2285    }
2286
2287    /// Returns a string slice with all prefixes and suffixes that match a
2288    /// pattern repeatedly removed.
2289    ///
2290    /// The [pattern] can be a [`char`], a slice of [`char`]s, or a function
2291    /// or closure that determines if a character matches.
2292    ///
2293    /// [`char`]: prim@char
2294    /// [pattern]: self::pattern
2295    ///
2296    /// # Examples
2297    ///
2298    /// Simple patterns:
2299    ///
2300    /// ```
2301    /// assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar");
2302    /// assert_eq!("123foo1bar123".trim_matches(char::is_numeric), "foo1bar");
2303    ///
2304    /// let x: &[_] = &['1', '2'];
2305    /// assert_eq!("12foo1bar12".trim_matches(x), "foo1bar");
2306    /// ```
2307    ///
2308    /// A more complex pattern, using a closure:
2309    ///
2310    /// ```
2311    /// assert_eq!("1foo1barXX".trim_matches(|c| c == '1' || c == 'X'), "foo1bar");
2312    /// ```
2313    #[must_use = "this returns the trimmed string as a new slice, \
2314                  without modifying the original"]
2315    #[stable(feature = "rust1", since = "1.0.0")]
2316    pub fn trim_matches<P: Pattern>(&self, pat: P) -> &str
2317    where
2318        for<'a> P::Searcher<'a>: DoubleEndedSearcher<'a>,
2319    {
2320        let mut i = 0;
2321        let mut j = 0;
2322        let mut matcher = pat.into_searcher(self);
2323        if let Some((a, b)) = matcher.next_reject() {
2324            i = a;
2325            j = b; // Remember earliest known match, correct it below if
2326            // last match is different
2327        }
2328        if let Some((_, b)) = matcher.next_reject_back() {
2329            j = b;
2330        }
2331        // SAFETY: `Searcher` is known to return valid indices.
2332        unsafe { self.get_unchecked(i..j) }
2333    }
2334
2335    /// Returns a string slice with all prefixes that match a pattern
2336    /// repeatedly removed.
2337    ///
2338    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2339    /// function or closure that determines if a character matches.
2340    ///
2341    /// [`char`]: prim@char
2342    /// [pattern]: self::pattern
2343    ///
2344    /// # Text directionality
2345    ///
2346    /// A string is a sequence of bytes. `start` in this context means the first
2347    /// position of that byte string; for a left-to-right language like English or
2348    /// Russian, this will be left side, and for right-to-left languages like
2349    /// Arabic or Hebrew, this will be the right side.
2350    ///
2351    /// # Examples
2352    ///
2353    /// ```
2354    /// assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11");
2355    /// assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric), "foo1bar123");
2356    ///
2357    /// let x: &[_] = &['1', '2'];
2358    /// assert_eq!("12foo1bar12".trim_start_matches(x), "foo1bar12");
2359    /// ```
2360    #[must_use = "this returns the trimmed string as a new slice, \
2361                  without modifying the original"]
2362    #[stable(feature = "trim_direction", since = "1.30.0")]
2363    pub fn trim_start_matches<P: Pattern>(&self, pat: P) -> &str {
2364        let mut i = self.len();
2365        let mut matcher = pat.into_searcher(self);
2366        if let Some((a, _)) = matcher.next_reject() {
2367            i = a;
2368        }
2369        // SAFETY: `Searcher` is known to return valid indices.
2370        unsafe { self.get_unchecked(i..self.len()) }
2371    }
2372
2373    /// Returns a string slice with the prefix removed.
2374    ///
2375    /// If the string starts with the pattern `prefix`, returns the substring after the prefix,
2376    /// wrapped in `Some`. Unlike [`trim_start_matches`], this method removes the prefix exactly once.
2377    ///
2378    /// If the string does not start with `prefix`, returns `None`.
2379    ///
2380    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2381    /// function or closure that determines if a character matches.
2382    ///
2383    /// [`char`]: prim@char
2384    /// [pattern]: self::pattern
2385    /// [`trim_start_matches`]: Self::trim_start_matches
2386    ///
2387    /// # Examples
2388    ///
2389    /// ```
2390    /// assert_eq!("foo:bar".strip_prefix("foo:"), Some("bar"));
2391    /// assert_eq!("foo:bar".strip_prefix("bar"), None);
2392    /// assert_eq!("foofoo".strip_prefix("foo"), Some("foo"));
2393    /// ```
2394    #[must_use = "this returns the remaining substring as a new slice, \
2395                  without modifying the original"]
2396    #[stable(feature = "str_strip", since = "1.45.0")]
2397    pub fn strip_prefix<P: Pattern>(&self, prefix: P) -> Option<&str> {
2398        prefix.strip_prefix_of(self)
2399    }
2400
2401    /// Returns a string slice with the suffix removed.
2402    ///
2403    /// If the string ends with the pattern `suffix`, returns the substring before the suffix,
2404    /// wrapped in `Some`.  Unlike [`trim_end_matches`], this method removes the suffix exactly once.
2405    ///
2406    /// If the string does not end with `suffix`, returns `None`.
2407    ///
2408    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2409    /// function or closure that determines if a character matches.
2410    ///
2411    /// [`char`]: prim@char
2412    /// [pattern]: self::pattern
2413    /// [`trim_end_matches`]: Self::trim_end_matches
2414    ///
2415    /// # Examples
2416    ///
2417    /// ```
2418    /// assert_eq!("bar:foo".strip_suffix(":foo"), Some("bar"));
2419    /// assert_eq!("bar:foo".strip_suffix("bar"), None);
2420    /// assert_eq!("foofoo".strip_suffix("foo"), Some("foo"));
2421    /// ```
2422    #[must_use = "this returns the remaining substring as a new slice, \
2423                  without modifying the original"]
2424    #[stable(feature = "str_strip", since = "1.45.0")]
2425    pub fn strip_suffix<P: Pattern>(&self, suffix: P) -> Option<&str>
2426    where
2427        for<'a> P::Searcher<'a>: ReverseSearcher<'a>,
2428    {
2429        suffix.strip_suffix_of(self)
2430    }
2431
2432    /// Returns a string slice with all suffixes that match a pattern
2433    /// repeatedly removed.
2434    ///
2435    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2436    /// function or closure that determines if a character matches.
2437    ///
2438    /// [`char`]: prim@char
2439    /// [pattern]: self::pattern
2440    ///
2441    /// # Text directionality
2442    ///
2443    /// A string is a sequence of bytes. `end` in this context means the last
2444    /// position of that byte string; for a left-to-right language like English or
2445    /// Russian, this will be right side, and for right-to-left languages like
2446    /// Arabic or Hebrew, this will be the left side.
2447    ///
2448    /// # Examples
2449    ///
2450    /// Simple patterns:
2451    ///
2452    /// ```
2453    /// assert_eq!("11foo1bar11".trim_end_matches('1'), "11foo1bar");
2454    /// assert_eq!("123foo1bar123".trim_end_matches(char::is_numeric), "123foo1bar");
2455    ///
2456    /// let x: &[_] = &['1', '2'];
2457    /// assert_eq!("12foo1bar12".trim_end_matches(x), "12foo1bar");
2458    /// ```
2459    ///
2460    /// A more complex pattern, using a closure:
2461    ///
2462    /// ```
2463    /// assert_eq!("1fooX".trim_end_matches(|c| c == '1' || c == 'X'), "1foo");
2464    /// ```
2465    #[must_use = "this returns the trimmed string as a new slice, \
2466                  without modifying the original"]
2467    #[stable(feature = "trim_direction", since = "1.30.0")]
2468    pub fn trim_end_matches<P: Pattern>(&self, pat: P) -> &str
2469    where
2470        for<'a> P::Searcher<'a>: ReverseSearcher<'a>,
2471    {
2472        let mut j = 0;
2473        let mut matcher = pat.into_searcher(self);
2474        if let Some((_, b)) = matcher.next_reject_back() {
2475            j = b;
2476        }
2477        // SAFETY: `Searcher` is known to return valid indices.
2478        unsafe { self.get_unchecked(0..j) }
2479    }
2480
2481    /// Returns a string slice with all prefixes that match a pattern
2482    /// repeatedly removed.
2483    ///
2484    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2485    /// function or closure that determines if a character matches.
2486    ///
2487    /// [`char`]: prim@char
2488    /// [pattern]: self::pattern
2489    ///
2490    /// # Text directionality
2491    ///
2492    /// A string is a sequence of bytes. 'Left' in this context means the first
2493    /// position of that byte string; for a language like Arabic or Hebrew
2494    /// which are 'right to left' rather than 'left to right', this will be
2495    /// the _right_ side, not the left.
2496    ///
2497    /// # Examples
2498    ///
2499    /// ```
2500    /// assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11");
2501    /// assert_eq!("123foo1bar123".trim_left_matches(char::is_numeric), "foo1bar123");
2502    ///
2503    /// let x: &[_] = &['1', '2'];
2504    /// assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12");
2505    /// ```
2506    #[stable(feature = "rust1", since = "1.0.0")]
2507    #[deprecated(
2508        since = "1.33.0",
2509        note = "superseded by `trim_start_matches`",
2510        suggestion = "trim_start_matches"
2511    )]
2512    pub fn trim_left_matches<P: Pattern>(&self, pat: P) -> &str {
2513        self.trim_start_matches(pat)
2514    }
2515
2516    /// Returns a string slice with all suffixes that match a pattern
2517    /// repeatedly removed.
2518    ///
2519    /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
2520    /// function or closure that determines if a character matches.
2521    ///
2522    /// [`char`]: prim@char
2523    /// [pattern]: self::pattern
2524    ///
2525    /// # Text directionality
2526    ///
2527    /// A string is a sequence of bytes. 'Right' in this context means the last
2528    /// position of that byte string; for a language like Arabic or Hebrew
2529    /// which are 'right to left' rather than 'left to right', this will be
2530    /// the _left_ side, not the right.
2531    ///
2532    /// # Examples
2533    ///
2534    /// Simple patterns:
2535    ///
2536    /// ```
2537    /// assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar");
2538    /// assert_eq!("123foo1bar123".trim_right_matches(char::is_numeric), "123foo1bar");
2539    ///
2540    /// let x: &[_] = &['1', '2'];
2541    /// assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar");
2542    /// ```
2543    ///
2544    /// A more complex pattern, using a closure:
2545    ///
2546    /// ```
2547    /// assert_eq!("1fooX".trim_right_matches(|c| c == '1' || c == 'X'), "1foo");
2548    /// ```
2549    #[stable(feature = "rust1", since = "1.0.0")]
2550    #[deprecated(
2551        since = "1.33.0",
2552        note = "superseded by `trim_end_matches`",
2553        suggestion = "trim_end_matches"
2554    )]
2555    pub fn trim_right_matches<P: Pattern>(&self, pat: P) -> &str
2556    where
2557        for<'a> P::Searcher<'a>: ReverseSearcher<'a>,
2558    {
2559        self.trim_end_matches(pat)
2560    }
2561
2562    /// Parses this string slice into another type.
2563    ///
2564    /// Because `parse` is so general, it can cause problems with type
2565    /// inference. As such, `parse` is one of the few times you'll see
2566    /// the syntax affectionately known as the 'turbofish': `::<>`. This
2567    /// helps the inference algorithm understand specifically which type
2568    /// you're trying to parse into.
2569    ///
2570    /// `parse` can parse into any type that implements the [`FromStr`] trait.
2571
2572    ///
2573    /// # Errors
2574    ///
2575    /// Will return [`Err`] if it's not possible to parse this string slice into
2576    /// the desired type.
2577    ///
2578    /// [`Err`]: FromStr::Err
2579    ///
2580    /// # Examples
2581    ///
2582    /// Basic usage:
2583    ///
2584    /// ```
2585    /// let four: u32 = "4".parse().unwrap();
2586    ///
2587    /// assert_eq!(4, four);
2588    /// ```
2589    ///
2590    /// Using the 'turbofish' instead of annotating `four`:
2591    ///
2592    /// ```
2593    /// let four = "4".parse::<u32>();
2594    ///
2595    /// assert_eq!(Ok(4), four);
2596    /// ```
2597    ///
2598    /// Failing to parse:
2599    ///
2600    /// ```
2601    /// let nope = "j".parse::<u32>();
2602    ///
2603    /// assert!(nope.is_err());
2604    /// ```
2605    #[inline]
2606    #[stable(feature = "rust1", since = "1.0.0")]
2607    pub fn parse<F: FromStr>(&self) -> Result<F, F::Err> {
2608        FromStr::from_str(self)
2609    }
2610
2611    /// Checks if all characters in this string are within the ASCII range.
2612    ///
2613    /// # Examples
2614    ///
2615    /// ```
2616    /// let ascii = "hello!\n";
2617    /// let non_ascii = "Grüße, Jürgen ❤";
2618    ///
2619    /// assert!(ascii.is_ascii());
2620    /// assert!(!non_ascii.is_ascii());
2621    /// ```
2622    #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
2623    #[rustc_const_stable(feature = "const_slice_is_ascii", since = "1.74.0")]
2624    #[must_use]
2625    #[inline]
2626    pub const fn is_ascii(&self) -> bool {
2627        // We can treat each byte as character here: all multibyte characters
2628        // start with a byte that is not in the ASCII range, so we will stop
2629        // there already.
2630        self.as_bytes().is_ascii()
2631    }
2632
2633    /// If this string slice [`is_ascii`](Self::is_ascii), returns it as a slice
2634    /// of [ASCII characters](`ascii::Char`), otherwise returns `None`.
2635    #[unstable(feature = "ascii_char", issue = "110998")]
2636    #[must_use]
2637    #[inline]
2638    pub const fn as_ascii(&self) -> Option<&[ascii::Char]> {
2639        // Like in `is_ascii`, we can work on the bytes directly.
2640        self.as_bytes().as_ascii()
2641    }
2642
2643    /// Checks that two strings are an ASCII case-insensitive match.
2644    ///
2645    /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
2646    /// but without allocating and copying temporaries.
2647    ///
2648    /// # Examples
2649    ///
2650    /// ```
2651    /// assert!("Ferris".eq_ignore_ascii_case("FERRIS"));
2652    /// assert!("Ferrös".eq_ignore_ascii_case("FERRöS"));
2653    /// assert!(!"Ferrös".eq_ignore_ascii_case("FERRÖS"));
2654    /// ```
2655    #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
2656    #[rustc_const_unstable(feature = "const_eq_ignore_ascii_case", issue = "131719")]
2657    #[must_use]
2658    #[inline]
2659    pub const fn eq_ignore_ascii_case(&self, other: &str) -> bool {
2660        self.as_bytes().eq_ignore_ascii_case(other.as_bytes())
2661    }
2662
2663    /// Converts this string to its ASCII upper case equivalent in-place.
2664    ///
2665    /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
2666    /// but non-ASCII letters are unchanged.
2667    ///
2668    /// To return a new uppercased value without modifying the existing one, use
2669    /// [`to_ascii_uppercase()`].
2670    ///
2671    /// [`to_ascii_uppercase()`]: #method.to_ascii_uppercase
2672    ///
2673    /// # Examples
2674    ///
2675    /// ```
2676    /// let mut s = String::from("Grüße, Jürgen ❤");
2677    ///
2678    /// s.make_ascii_uppercase();
2679    ///
2680    /// assert_eq!("GRüßE, JüRGEN ❤", s);
2681    /// ```
2682    #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
2683    #[rustc_const_stable(feature = "const_make_ascii", since = "1.84.0")]
2684    #[inline]
2685    pub const fn make_ascii_uppercase(&mut self) {
2686        // SAFETY: changing ASCII letters only does not invalidate UTF-8.
2687        let me = unsafe { self.as_bytes_mut() };
2688        me.make_ascii_uppercase()
2689    }
2690
2691    /// Converts this string to its ASCII lower case equivalent in-place.
2692    ///
2693    /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
2694    /// but non-ASCII letters are unchanged.
2695    ///
2696    /// To return a new lowercased value without modifying the existing one, use
2697    /// [`to_ascii_lowercase()`].
2698    ///
2699    /// [`to_ascii_lowercase()`]: #method.to_ascii_lowercase
2700    ///
2701    /// # Examples
2702    ///
2703    /// ```
2704    /// let mut s = String::from("GRÜßE, JÜRGEN ❤");
2705    ///
2706    /// s.make_ascii_lowercase();
2707    ///
2708    /// assert_eq!("grÜße, jÜrgen ❤", s);
2709    /// ```
2710    #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
2711    #[rustc_const_stable(feature = "const_make_ascii", since = "1.84.0")]
2712    #[inline]
2713    pub const fn make_ascii_lowercase(&mut self) {
2714        // SAFETY: changing ASCII letters only does not invalidate UTF-8.
2715        let me = unsafe { self.as_bytes_mut() };
2716        me.make_ascii_lowercase()
2717    }
2718
2719    /// Returns a string slice with leading ASCII whitespace removed.
2720    ///
2721    /// 'Whitespace' refers to the definition used by
2722    /// [`u8::is_ascii_whitespace`].
2723    ///
2724    /// [`u8::is_ascii_whitespace`]: u8::is_ascii_whitespace
2725    ///
2726    /// # Examples
2727    ///
2728    /// ```
2729    /// assert_eq!(" \t \u{3000}hello world\n".trim_ascii_start(), "\u{3000}hello world\n");
2730    /// assert_eq!("  ".trim_ascii_start(), "");
2731    /// assert_eq!("".trim_ascii_start(), "");
2732    /// ```
2733    #[must_use = "this returns the trimmed string as a new slice, \
2734                  without modifying the original"]
2735    #[stable(feature = "byte_slice_trim_ascii", since = "1.80.0")]
2736    #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "1.80.0")]
2737    #[inline]
2738    pub const fn trim_ascii_start(&self) -> &str {
2739        // SAFETY: Removing ASCII characters from a `&str` does not invalidate
2740        // UTF-8.
2741        unsafe { core::str::from_utf8_unchecked(self.as_bytes().trim_ascii_start()) }
2742    }
2743
2744    /// Returns a string slice with trailing ASCII whitespace removed.
2745    ///
2746    /// 'Whitespace' refers to the definition used by
2747    /// [`u8::is_ascii_whitespace`].
2748    ///
2749    /// [`u8::is_ascii_whitespace`]: u8::is_ascii_whitespace
2750    ///
2751    /// # Examples
2752    ///
2753    /// ```
2754    /// assert_eq!("\r hello world\u{3000}\n ".trim_ascii_end(), "\r hello world\u{3000}");
2755    /// assert_eq!("  ".trim_ascii_end(), "");
2756    /// assert_eq!("".trim_ascii_end(), "");
2757    /// ```
2758    #[must_use = "this returns the trimmed string as a new slice, \
2759                  without modifying the original"]
2760    #[stable(feature = "byte_slice_trim_ascii", since = "1.80.0")]
2761    #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "1.80.0")]
2762    #[inline]
2763    pub const fn trim_ascii_end(&self) -> &str {
2764        // SAFETY: Removing ASCII characters from a `&str` does not invalidate
2765        // UTF-8.
2766        unsafe { core::str::from_utf8_unchecked(self.as_bytes().trim_ascii_end()) }
2767    }
2768
2769    /// Returns a string slice with leading and trailing ASCII whitespace
2770    /// removed.
2771    ///
2772    /// 'Whitespace' refers to the definition used by
2773    /// [`u8::is_ascii_whitespace`].
2774    ///
2775    /// [`u8::is_ascii_whitespace`]: u8::is_ascii_whitespace
2776    ///
2777    /// # Examples
2778    ///
2779    /// ```
2780    /// assert_eq!("\r hello world\n ".trim_ascii(), "hello world");
2781    /// assert_eq!("  ".trim_ascii(), "");
2782    /// assert_eq!("".trim_ascii(), "");
2783    /// ```
2784    #[must_use = "this returns the trimmed string as a new slice, \
2785                  without modifying the original"]
2786    #[stable(feature = "byte_slice_trim_ascii", since = "1.80.0")]
2787    #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "1.80.0")]
2788    #[inline]
2789    pub const fn trim_ascii(&self) -> &str {
2790        // SAFETY: Removing ASCII characters from a `&str` does not invalidate
2791        // UTF-8.
2792        unsafe { core::str::from_utf8_unchecked(self.as_bytes().trim_ascii()) }
2793    }
2794
2795    /// Returns an iterator that escapes each char in `self` with [`char::escape_debug`].
2796    ///
2797    /// Note: only extended grapheme codepoints that begin the string will be
2798    /// escaped.
2799    ///
2800    /// # Examples
2801    ///
2802    /// As an iterator:
2803    ///
2804    /// ```
2805    /// for c in "❤\n!".escape_debug() {
2806    ///     print!("{c}");
2807    /// }
2808    /// println!();
2809    /// ```
2810    ///
2811    /// Using `println!` directly:
2812    ///
2813    /// ```
2814    /// println!("{}", "❤\n!".escape_debug());
2815    /// ```
2816    ///
2817    ///
2818    /// Both are equivalent to:
2819    ///
2820    /// ```
2821    /// println!("❤\\n!");
2822    /// ```
2823    ///
2824    /// Using `to_string`:
2825    ///
2826    /// ```
2827    /// assert_eq!("❤\n!".escape_debug().to_string(), "❤\\n!");
2828    /// ```
2829    #[must_use = "this returns the escaped string as an iterator, \
2830                  without modifying the original"]
2831    #[stable(feature = "str_escape", since = "1.34.0")]
2832    pub fn escape_debug(&self) -> EscapeDebug<'_> {
2833        let mut chars = self.chars();
2834        EscapeDebug {
2835            inner: chars
2836                .next()
2837                .map(|first| first.escape_debug_ext(EscapeDebugExtArgs::ESCAPE_ALL))
2838                .into_iter()
2839                .flatten()
2840                .chain(chars.flat_map(CharEscapeDebugContinue)),
2841        }
2842    }
2843
2844    /// Returns an iterator that escapes each char in `self` with [`char::escape_default`].
2845    ///
2846    /// # Examples
2847    ///
2848    /// As an iterator:
2849    ///
2850    /// ```
2851    /// for c in "❤\n!".escape_default() {
2852    ///     print!("{c}");
2853    /// }
2854    /// println!();
2855    /// ```
2856    ///
2857    /// Using `println!` directly:
2858    ///
2859    /// ```
2860    /// println!("{}", "❤\n!".escape_default());
2861    /// ```
2862    ///
2863    ///
2864    /// Both are equivalent to:
2865    ///
2866    /// ```
2867    /// println!("\\u{{2764}}\\n!");
2868    /// ```
2869    ///
2870    /// Using `to_string`:
2871    ///
2872    /// ```
2873    /// assert_eq!("❤\n!".escape_default().to_string(), "\\u{2764}\\n!");
2874    /// ```
2875    #[must_use = "this returns the escaped string as an iterator, \
2876                  without modifying the original"]
2877    #[stable(feature = "str_escape", since = "1.34.0")]
2878    pub fn escape_default(&self) -> EscapeDefault<'_> {
2879        EscapeDefault { inner: self.chars().flat_map(CharEscapeDefault) }
2880    }
2881
2882    /// Returns an iterator that escapes each char in `self` with [`char::escape_unicode`].
2883    ///
2884    /// # Examples
2885    ///
2886    /// As an iterator:
2887    ///
2888    /// ```
2889    /// for c in "❤\n!".escape_unicode() {
2890    ///     print!("{c}");
2891    /// }
2892    /// println!();
2893    /// ```
2894    ///
2895    /// Using `println!` directly:
2896    ///
2897    /// ```
2898    /// println!("{}", "❤\n!".escape_unicode());
2899    /// ```
2900    ///
2901    ///
2902    /// Both are equivalent to:
2903    ///
2904    /// ```
2905    /// println!("\\u{{2764}}\\u{{a}}\\u{{21}}");
2906    /// ```
2907    ///
2908    /// Using `to_string`:
2909    ///
2910    /// ```
2911    /// assert_eq!("❤\n!".escape_unicode().to_string(), "\\u{2764}\\u{a}\\u{21}");
2912    /// ```
2913    #[must_use = "this returns the escaped string as an iterator, \
2914                  without modifying the original"]
2915    #[stable(feature = "str_escape", since = "1.34.0")]
2916    pub fn escape_unicode(&self) -> EscapeUnicode<'_> {
2917        EscapeUnicode { inner: self.chars().flat_map(CharEscapeUnicode) }
2918    }
2919
2920    /// Returns the range that a substring points to.
2921    ///
2922    /// Returns `None` if `substr` does not point within `self`.
2923    ///
2924    /// Unlike [`str::find`], **this does not search through the string**.
2925    /// Instead, it uses pointer arithmetic to find where in the string
2926    /// `substr` is derived from.
2927    ///
2928    /// This is useful for extending [`str::split`] and similar methods.
2929    ///
2930    /// Note that this method may return false positives (typically either
2931    /// `Some(0..0)` or `Some(self.len()..self.len())`) if `substr` is a
2932    /// zero-length `str` that points at the beginning or end of another,
2933    /// independent, `str`.
2934    ///
2935    /// # Examples
2936    /// ```
2937    /// #![feature(substr_range)]
2938    ///
2939    /// let data = "a, b, b, a";
2940    /// let mut iter = data.split(", ").map(|s| data.substr_range(s).unwrap());
2941    ///
2942    /// assert_eq!(iter.next(), Some(0..1));
2943    /// assert_eq!(iter.next(), Some(3..4));
2944    /// assert_eq!(iter.next(), Some(6..7));
2945    /// assert_eq!(iter.next(), Some(9..10));
2946    /// ```
2947    #[must_use]
2948    #[unstable(feature = "substr_range", issue = "126769")]
2949    pub fn substr_range(&self, substr: &str) -> Option<Range<usize>> {
2950        self.as_bytes().subslice_range(substr.as_bytes())
2951    }
2952
2953    /// Returns the same string as a string slice `&str`.
2954    ///
2955    /// This method is redundant when used directly on `&str`, but
2956    /// it helps dereferencing other string-like types to string slices,
2957    /// for example references to `Box<str>` or `Arc<str>`.
2958    #[inline]
2959    #[unstable(feature = "str_as_str", issue = "130366")]
2960    pub fn as_str(&self) -> &str {
2961        self
2962    }
2963}
2964
2965#[stable(feature = "rust1", since = "1.0.0")]
2966impl AsRef<[u8]> for str {
2967    #[inline]
2968    fn as_ref(&self) -> &[u8] {
2969        self.as_bytes()
2970    }
2971}
2972
2973#[stable(feature = "rust1", since = "1.0.0")]
2974impl Default for &str {
2975    /// Creates an empty str
2976    #[inline]
2977    fn default() -> Self {
2978        ""
2979    }
2980}
2981
2982#[stable(feature = "default_mut_str", since = "1.28.0")]
2983impl Default for &mut str {
2984    /// Creates an empty mutable str
2985    #[inline]
2986    fn default() -> Self {
2987        // SAFETY: The empty string is valid UTF-8.
2988        unsafe { from_utf8_unchecked_mut(&mut []) }
2989    }
2990}
2991
2992impl_fn_for_zst! {
2993    /// A nameable, cloneable fn type
2994    #[derive(Clone)]
2995    struct LinesMap impl<'a> Fn = |line: &'a str| -> &'a str {
2996        let Some(line) = line.strip_suffix('\n') else { return line };
2997        let Some(line) = line.strip_suffix('\r') else { return line };
2998        line
2999    };
3000
3001    #[derive(Clone)]
3002    struct CharEscapeDebugContinue impl Fn = |c: char| -> char::EscapeDebug {
3003        c.escape_debug_ext(EscapeDebugExtArgs {
3004            escape_grapheme_extended: false,
3005            escape_single_quote: true,
3006            escape_double_quote: true
3007        })
3008    };
3009
3010    #[derive(Clone)]
3011    struct CharEscapeUnicode impl Fn = |c: char| -> char::EscapeUnicode {
3012        c.escape_unicode()
3013    };
3014    #[derive(Clone)]
3015    struct CharEscapeDefault impl Fn = |c: char| -> char::EscapeDefault {
3016        c.escape_default()
3017    };
3018
3019    #[derive(Clone)]
3020    struct IsWhitespace impl Fn = |c: char| -> bool {
3021        c.is_whitespace()
3022    };
3023
3024    #[derive(Clone)]
3025    struct IsAsciiWhitespace impl Fn = |byte: &u8| -> bool {
3026        byte.is_ascii_whitespace()
3027    };
3028
3029    #[derive(Clone)]
3030    struct IsNotEmpty impl<'a, 'b> Fn = |s: &'a &'b str| -> bool {
3031        !s.is_empty()
3032    };
3033
3034    #[derive(Clone)]
3035    struct BytesIsNotEmpty impl<'a, 'b> Fn = |s: &'a &'b [u8]| -> bool {
3036        !s.is_empty()
3037    };
3038
3039    #[derive(Clone)]
3040    struct UnsafeBytesToStr impl<'a> Fn = |bytes: &'a [u8]| -> &'a str {
3041        // SAFETY: not safe
3042        unsafe { from_utf8_unchecked(bytes) }
3043    };
3044}
3045
3046// This is required to make `impl From<&str> for Box<dyn Error>` and `impl<E> From<E> for Box<dyn Error>` not overlap.
3047#[stable(feature = "error_in_core_neg_impl", since = "1.65.0")]
3048impl !crate::error::Error for &str {}