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