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