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