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