1 // ignore-tidy-filelength
3 //! String manipulation.
5 //! For more details, see the `std::str` module.
7 #![stable(feature = "rust1", since = "1.0.0")]
9 use self::pattern::Pattern;
10 use self::pattern::{DoubleEndedSearcher, ReverseSearcher, SearchStep, Searcher};
13 use crate::fmt::{self, Write};
14 use crate::iter::{Chain, FlatMap, Flatten};
15 use crate::iter::{Cloned, Filter, FusedIterator, Map, TrustedLen, TrustedRandomAccess};
19 use crate::slice::{self, SliceIndex, Split as SliceSplit};
23 #[unstable(feature = "str_internals", issue = "none")]
24 #[allow(missing_docs)]
27 /// Parse a value from a string
29 /// `FromStr`'s [`from_str`] method is often used implicitly, through
30 /// [`str`]'s [`parse`] method. See [`parse`]'s documentation for examples.
32 /// [`from_str`]: #tymethod.from_str
33 /// [`str`]: ../../std/primitive.str.html
34 /// [`parse`]: ../../std/primitive.str.html#method.parse
36 /// `FromStr` does not have a lifetime parameter, and so you can only parse types
37 /// that do not contain a lifetime parameter themselves. In other words, you can
38 /// parse an `i32` with `FromStr`, but not a `&i32`. You can parse a struct that
39 /// contains an `i32`, but not one that contains an `&i32`.
43 /// Basic implementation of `FromStr` on an example `Point` type:
46 /// use std::str::FromStr;
47 /// use std::num::ParseIntError;
49 /// #[derive(Debug, PartialEq)]
55 /// impl FromStr for Point {
56 /// type Err = ParseIntError;
58 /// fn from_str(s: &str) -> Result<Self, Self::Err> {
59 /// let coords: Vec<&str> = s.trim_matches(|p| p == '(' || p == ')' )
63 /// let x_fromstr = coords[0].parse::<i32>()?;
64 /// let y_fromstr = coords[1].parse::<i32>()?;
66 /// Ok(Point { x: x_fromstr, y: y_fromstr })
70 /// let p = Point::from_str("(1,2)");
71 /// assert_eq!(p.unwrap(), Point{ x: 1, y: 2} )
73 #[stable(feature = "rust1", since = "1.0.0")]
74 pub trait FromStr: Sized {
75 /// The associated error which can be returned from parsing.
76 #[stable(feature = "rust1", since = "1.0.0")]
79 /// Parses a string `s` to return a value of this type.
81 /// If parsing succeeds, return the value inside [`Ok`], otherwise
82 /// when the string is ill-formatted return an error specific to the
83 /// inside [`Err`]. The error type is specific to implementation of the trait.
85 /// [`Ok`]: ../../std/result/enum.Result.html#variant.Ok
86 /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
90 /// Basic usage with [`i32`][ithirtytwo], a type that implements `FromStr`:
92 /// [ithirtytwo]: ../../std/primitive.i32.html
95 /// use std::str::FromStr;
98 /// let x = i32::from_str(s).unwrap();
100 /// assert_eq!(5, x);
102 #[stable(feature = "rust1", since = "1.0.0")]
103 fn from_str(s: &str) -> Result<Self, Self::Err>;
106 #[stable(feature = "rust1", since = "1.0.0")]
107 impl FromStr for bool {
108 type Err = ParseBoolError;
110 /// Parse a `bool` from a string.
112 /// Yields a `Result<bool, ParseBoolError>`, because `s` may or may not
113 /// actually be parseable.
118 /// use std::str::FromStr;
120 /// assert_eq!(FromStr::from_str("true"), Ok(true));
121 /// assert_eq!(FromStr::from_str("false"), Ok(false));
122 /// assert!(<bool as FromStr>::from_str("not even a boolean").is_err());
125 /// Note, in many cases, the `.parse()` method on `str` is more proper.
128 /// assert_eq!("true".parse(), Ok(true));
129 /// assert_eq!("false".parse(), Ok(false));
130 /// assert!("not even a boolean".parse::<bool>().is_err());
133 fn from_str(s: &str) -> Result<bool, ParseBoolError> {
136 "false" => Ok(false),
137 _ => Err(ParseBoolError { _priv: () }),
142 /// An error returned when parsing a `bool` using [`from_str`] fails
144 /// [`from_str`]: ../../std/primitive.bool.html#method.from_str
145 #[derive(Debug, Clone, PartialEq, Eq)]
146 #[stable(feature = "rust1", since = "1.0.0")]
147 pub struct ParseBoolError {
151 #[stable(feature = "rust1", since = "1.0.0")]
152 impl fmt::Display for ParseBoolError {
153 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
154 "provided string was not `true` or `false`".fmt(f)
159 Section: Creating a string
162 /// Errors which can occur when attempting to interpret a sequence of [`u8`]
165 /// [`u8`]: ../../std/primitive.u8.html
167 /// As such, the `from_utf8` family of functions and methods for both [`String`]s
168 /// and [`&str`]s make use of this error, for example.
170 /// [`String`]: ../../std/string/struct.String.html#method.from_utf8
171 /// [`&str`]: ../../std/str/fn.from_utf8.html
175 /// This error type’s methods can be used to create functionality
176 /// similar to `String::from_utf8_lossy` without allocating heap memory:
179 /// fn from_utf8_lossy<F>(mut input: &[u8], mut push: F) where F: FnMut(&str) {
181 /// match std::str::from_utf8(input) {
187 /// let (valid, after_valid) = input.split_at(error.valid_up_to());
189 /// push(std::str::from_utf8_unchecked(valid))
191 /// push("\u{FFFD}");
193 /// if let Some(invalid_sequence_length) = error.error_len() {
194 /// input = &after_valid[invalid_sequence_length..]
203 #[derive(Copy, Eq, PartialEq, Clone, Debug)]
204 #[stable(feature = "rust1", since = "1.0.0")]
205 pub struct Utf8Error {
207 error_len: Option<u8>,
211 /// Returns the index in the given string up to which valid UTF-8 was
214 /// It is the maximum index such that `from_utf8(&input[..index])`
215 /// would return `Ok(_)`.
224 /// // some invalid bytes, in a vector
225 /// let sparkle_heart = vec![0, 159, 146, 150];
227 /// // std::str::from_utf8 returns a Utf8Error
228 /// let error = str::from_utf8(&sparkle_heart).unwrap_err();
230 /// // the second byte is invalid here
231 /// assert_eq!(1, error.valid_up_to());
233 #[stable(feature = "utf8_error", since = "1.5.0")]
234 pub fn valid_up_to(&self) -> usize {
238 /// Provides more information about the failure:
240 /// * `None`: the end of the input was reached unexpectedly.
241 /// `self.valid_up_to()` is 1 to 3 bytes from the end of the input.
242 /// If a byte stream (such as a file or a network socket) is being decoded incrementally,
243 /// this could be a valid `char` whose UTF-8 byte sequence is spanning multiple chunks.
245 /// * `Some(len)`: an unexpected byte was encountered.
246 /// The length provided is that of the invalid byte sequence
247 /// that starts at the index given by `valid_up_to()`.
248 /// Decoding should resume after that sequence
249 /// (after inserting a [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD]) in case of
252 /// [U+FFFD]: ../../std/char/constant.REPLACEMENT_CHARACTER.html
253 #[stable(feature = "utf8_error_error_len", since = "1.20.0")]
254 pub fn error_len(&self) -> Option<usize> {
255 self.error_len.map(|len| len as usize)
259 /// Converts a slice of bytes to a string slice.
261 /// A string slice ([`&str`]) is made of bytes ([`u8`]), and a byte slice
262 /// ([`&[u8]`][byteslice]) is made of bytes, so this function converts between
263 /// the two. Not all byte slices are valid string slices, however: [`&str`] requires
264 /// that it is valid UTF-8. `from_utf8()` checks to ensure that the bytes are valid
265 /// UTF-8, and then does the conversion.
267 /// [`&str`]: ../../std/primitive.str.html
268 /// [`u8`]: ../../std/primitive.u8.html
269 /// [byteslice]: ../../std/primitive.slice.html
271 /// If you are sure that the byte slice is valid UTF-8, and you don't want to
272 /// incur the overhead of the validity check, there is an unsafe version of
273 /// this function, [`from_utf8_unchecked`][fromutf8u], which has the same
274 /// behavior but skips the check.
276 /// [fromutf8u]: fn.from_utf8_unchecked.html
278 /// If you need a `String` instead of a `&str`, consider
279 /// [`String::from_utf8`][string].
281 /// [string]: ../../std/string/struct.String.html#method.from_utf8
283 /// Because you can stack-allocate a `[u8; N]`, and you can take a
284 /// [`&[u8]`][byteslice] of it, this function is one way to have a
285 /// stack-allocated string. There is an example of this in the
286 /// examples section below.
288 /// [byteslice]: ../../std/primitive.slice.html
292 /// Returns `Err` if the slice is not UTF-8 with a description as to why the
293 /// provided slice is not UTF-8.
302 /// // some bytes, in a vector
303 /// let sparkle_heart = vec![240, 159, 146, 150];
305 /// // We know these bytes are valid, so just use `unwrap()`.
306 /// let sparkle_heart = str::from_utf8(&sparkle_heart).unwrap();
308 /// assert_eq!("💖", sparkle_heart);
316 /// // some invalid bytes, in a vector
317 /// let sparkle_heart = vec![0, 159, 146, 150];
319 /// assert!(str::from_utf8(&sparkle_heart).is_err());
322 /// See the docs for [`Utf8Error`][error] for more details on the kinds of
323 /// errors that can be returned.
325 /// [error]: struct.Utf8Error.html
327 /// A "stack allocated string":
332 /// // some bytes, in a stack-allocated array
333 /// let sparkle_heart = [240, 159, 146, 150];
335 /// // We know these bytes are valid, so just use `unwrap()`.
336 /// let sparkle_heart = str::from_utf8(&sparkle_heart).unwrap();
338 /// assert_eq!("💖", sparkle_heart);
340 #[stable(feature = "rust1", since = "1.0.0")]
341 pub fn from_utf8(v: &[u8]) -> Result<&str, Utf8Error> {
342 run_utf8_validation(v)?;
343 // SAFETY: just ran validation
344 Ok(unsafe { from_utf8_unchecked(v) })
347 /// Converts a mutable slice of bytes to a mutable string slice.
356 /// // "Hello, Rust!" as a mutable vector
357 /// let mut hellorust = vec![72, 101, 108, 108, 111, 44, 32, 82, 117, 115, 116, 33];
359 /// // As we know these bytes are valid, we can use `unwrap()`
360 /// let outstr = str::from_utf8_mut(&mut hellorust).unwrap();
362 /// assert_eq!("Hello, Rust!", outstr);
370 /// // Some invalid bytes in a mutable vector
371 /// let mut invalid = vec![128, 223];
373 /// assert!(str::from_utf8_mut(&mut invalid).is_err());
375 /// See the docs for [`Utf8Error`][error] for more details on the kinds of
376 /// errors that can be returned.
378 /// [error]: struct.Utf8Error.html
379 #[stable(feature = "str_mut_extras", since = "1.20.0")]
380 pub fn from_utf8_mut(v: &mut [u8]) -> Result<&mut str, Utf8Error> {
381 run_utf8_validation(v)?;
382 // SAFETY: just ran validation
383 Ok(unsafe { from_utf8_unchecked_mut(v) })
386 /// Converts a slice of bytes to a string slice without checking
387 /// that the string contains valid UTF-8.
389 /// See the safe version, [`from_utf8`][fromutf8], for more information.
391 /// [fromutf8]: fn.from_utf8.html
395 /// This function is unsafe because it does not check that the bytes passed to
396 /// it are valid UTF-8. If this constraint is violated, undefined behavior
397 /// results, as the rest of Rust assumes that [`&str`]s are valid UTF-8.
399 /// [`&str`]: ../../std/primitive.str.html
408 /// // some bytes, in a vector
409 /// let sparkle_heart = vec![240, 159, 146, 150];
411 /// let sparkle_heart = unsafe {
412 /// str::from_utf8_unchecked(&sparkle_heart)
415 /// assert_eq!("💖", sparkle_heart);
418 #[stable(feature = "rust1", since = "1.0.0")]
419 pub unsafe fn from_utf8_unchecked(v: &[u8]) -> &str {
420 &*(v as *const [u8] as *const str)
423 /// Converts a slice of bytes to a string slice without checking
424 /// that the string contains valid UTF-8; mutable version.
426 /// See the immutable version, [`from_utf8_unchecked()`][fromutf8], for more information.
428 /// [fromutf8]: fn.from_utf8_unchecked.html
437 /// let mut heart = vec![240, 159, 146, 150];
438 /// let heart = unsafe { str::from_utf8_unchecked_mut(&mut heart) };
440 /// assert_eq!("💖", heart);
443 #[stable(feature = "str_mut_extras", since = "1.20.0")]
444 pub unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str {
445 &mut *(v as *mut [u8] as *mut str)
448 #[stable(feature = "rust1", since = "1.0.0")]
449 impl fmt::Display for Utf8Error {
450 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
451 if let Some(error_len) = self.error_len {
454 "invalid utf-8 sequence of {} bytes from index {}",
455 error_len, self.valid_up_to
458 write!(f, "incomplete utf-8 byte sequence from index {}", self.valid_up_to)
467 /// An iterator over the [`char`]s of a string slice.
469 /// [`char`]: ../../std/primitive.char.html
471 /// This struct is created by the [`chars`] method on [`str`].
472 /// See its documentation for more.
474 /// [`chars`]: ../../std/primitive.str.html#method.chars
475 /// [`str`]: ../../std/primitive.str.html
477 #[stable(feature = "rust1", since = "1.0.0")]
478 pub struct Chars<'a> {
479 iter: slice::Iter<'a, u8>,
482 /// Returns the initial codepoint accumulator for the first byte.
483 /// The first byte is special, only want bottom 5 bits for width 2, 4 bits
484 /// for width 3, and 3 bits for width 4.
486 fn utf8_first_byte(byte: u8, width: u32) -> u32 {
487 (byte & (0x7F >> width)) as u32
490 /// Returns the value of `ch` updated with continuation byte `byte`.
492 fn utf8_acc_cont_byte(ch: u32, byte: u8) -> u32 {
493 (ch << 6) | (byte & CONT_MASK) as u32
496 /// Checks whether the byte is a UTF-8 continuation byte (i.e., starts with the
499 fn utf8_is_cont_byte(byte: u8) -> bool {
500 (byte & !CONT_MASK) == TAG_CONT_U8
504 fn unwrap_or_0(opt: Option<&u8>) -> u8 {
511 /// Reads the next code point out of a byte iterator (assuming a
512 /// UTF-8-like encoding).
513 #[unstable(feature = "str_internals", issue = "none")]
515 pub fn next_code_point<'a, I: Iterator<Item = &'a u8>>(bytes: &mut I) -> Option<u32> {
517 let x = *bytes.next()?;
519 return Some(x as u32);
522 // Multibyte case follows
523 // Decode from a byte combination out of: [[[x y] z] w]
524 // NOTE: Performance is sensitive to the exact formulation here
525 let init = utf8_first_byte(x, 2);
526 let y = unwrap_or_0(bytes.next());
527 let mut ch = utf8_acc_cont_byte(init, y);
530 // 5th bit in 0xE0 .. 0xEF is always clear, so `init` is still valid
531 let z = unwrap_or_0(bytes.next());
532 let y_z = utf8_acc_cont_byte((y & CONT_MASK) as u32, z);
533 ch = init << 12 | y_z;
536 // use only the lower 3 bits of `init`
537 let w = unwrap_or_0(bytes.next());
538 ch = (init & 7) << 18 | utf8_acc_cont_byte(y_z, w);
545 /// Reads the last code point out of a byte iterator (assuming a
546 /// UTF-8-like encoding).
548 fn next_code_point_reverse<'a, I>(bytes: &mut I) -> Option<u32>
550 I: DoubleEndedIterator<Item = &'a u8>,
553 let w = match *bytes.next_back()? {
554 next_byte if next_byte < 128 => return Some(next_byte as u32),
555 back_byte => back_byte,
558 // Multibyte case follows
559 // Decode from a byte combination out of: [x [y [z w]]]
561 let z = unwrap_or_0(bytes.next_back());
562 ch = utf8_first_byte(z, 2);
563 if utf8_is_cont_byte(z) {
564 let y = unwrap_or_0(bytes.next_back());
565 ch = utf8_first_byte(y, 3);
566 if utf8_is_cont_byte(y) {
567 let x = unwrap_or_0(bytes.next_back());
568 ch = utf8_first_byte(x, 4);
569 ch = utf8_acc_cont_byte(ch, y);
571 ch = utf8_acc_cont_byte(ch, z);
573 ch = utf8_acc_cont_byte(ch, w);
578 #[stable(feature = "rust1", since = "1.0.0")]
579 impl<'a> Iterator for Chars<'a> {
583 fn next(&mut self) -> Option<char> {
584 next_code_point(&mut self.iter).map(|ch| {
585 // SAFETY: str invariant says `ch` is a valid Unicode Scalar Value
586 unsafe { char::from_u32_unchecked(ch) }
591 fn count(self) -> usize {
592 // length in `char` is equal to the number of non-continuation bytes
593 let bytes_len = self.iter.len();
594 let mut cont_bytes = 0;
595 for &byte in self.iter {
596 cont_bytes += utf8_is_cont_byte(byte) as usize;
598 bytes_len - cont_bytes
602 fn size_hint(&self) -> (usize, Option<usize>) {
603 let len = self.iter.len();
604 // `(len + 3)` can't overflow, because we know that the `slice::Iter`
605 // belongs to a slice in memory which has a maximum length of
606 // `isize::MAX` (that's well below `usize::MAX`).
607 ((len + 3) / 4, Some(len))
611 fn last(mut self) -> Option<char> {
612 // No need to go through the entire string.
617 #[stable(feature = "chars_debug_impl", since = "1.38.0")]
618 impl fmt::Debug for Chars<'_> {
619 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
620 write!(f, "Chars(")?;
621 f.debug_list().entries(self.clone()).finish()?;
627 #[stable(feature = "rust1", since = "1.0.0")]
628 impl<'a> DoubleEndedIterator for Chars<'a> {
630 fn next_back(&mut self) -> Option<char> {
631 next_code_point_reverse(&mut self.iter).map(|ch| {
632 // SAFETY: str invariant says `ch` is a valid Unicode Scalar Value
633 unsafe { char::from_u32_unchecked(ch) }
638 #[stable(feature = "fused", since = "1.26.0")]
639 impl FusedIterator for Chars<'_> {}
642 /// Views the underlying data as a subslice of the original data.
644 /// This has the same lifetime as the original slice, and so the
645 /// iterator can continue to be used while this exists.
650 /// let mut chars = "abc".chars();
652 /// assert_eq!(chars.as_str(), "abc");
654 /// assert_eq!(chars.as_str(), "bc");
657 /// assert_eq!(chars.as_str(), "");
659 #[stable(feature = "iter_to_slice", since = "1.4.0")]
661 pub fn as_str(&self) -> &'a str {
662 // SAFETY: Chars is only made from a str, which guarantees the iter is valid utf8
663 unsafe { from_utf8_unchecked(self.iter.as_slice()) }
667 /// An iterator over the [`char`]s of a string slice, and their positions.
669 /// [`char`]: ../../std/primitive.char.html
671 /// This struct is created by the [`char_indices`] method on [`str`].
672 /// See its documentation for more.
674 /// [`char_indices`]: ../../std/primitive.str.html#method.char_indices
675 /// [`str`]: ../../std/primitive.str.html
676 #[derive(Clone, Debug)]
677 #[stable(feature = "rust1", since = "1.0.0")]
678 pub struct CharIndices<'a> {
683 #[stable(feature = "rust1", since = "1.0.0")]
684 impl<'a> Iterator for CharIndices<'a> {
685 type Item = (usize, char);
688 fn next(&mut self) -> Option<(usize, char)> {
689 let pre_len = self.iter.iter.len();
690 match self.iter.next() {
693 let index = self.front_offset;
694 let len = self.iter.iter.len();
695 self.front_offset += pre_len - len;
702 fn count(self) -> usize {
707 fn size_hint(&self) -> (usize, Option<usize>) {
708 self.iter.size_hint()
712 fn last(mut self) -> Option<(usize, char)> {
713 // No need to go through the entire string.
718 #[stable(feature = "rust1", since = "1.0.0")]
719 impl<'a> DoubleEndedIterator for CharIndices<'a> {
721 fn next_back(&mut self) -> Option<(usize, char)> {
722 self.iter.next_back().map(|ch| {
723 let index = self.front_offset + self.iter.iter.len();
729 #[stable(feature = "fused", since = "1.26.0")]
730 impl FusedIterator for CharIndices<'_> {}
732 impl<'a> CharIndices<'a> {
733 /// Views the underlying data as a subslice of the original data.
735 /// This has the same lifetime as the original slice, and so the
736 /// iterator can continue to be used while this exists.
737 #[stable(feature = "iter_to_slice", since = "1.4.0")]
739 pub fn as_str(&self) -> &'a str {
744 /// An iterator over the bytes of a string slice.
746 /// This struct is created by the [`bytes`] method on [`str`].
747 /// See its documentation for more.
749 /// [`bytes`]: ../../std/primitive.str.html#method.bytes
750 /// [`str`]: ../../std/primitive.str.html
751 #[stable(feature = "rust1", since = "1.0.0")]
752 #[derive(Clone, Debug)]
753 pub struct Bytes<'a>(Cloned<slice::Iter<'a, u8>>);
755 #[stable(feature = "rust1", since = "1.0.0")]
756 impl Iterator for Bytes<'_> {
760 fn next(&mut self) -> Option<u8> {
765 fn size_hint(&self) -> (usize, Option<usize>) {
770 fn count(self) -> usize {
775 fn last(self) -> Option<Self::Item> {
780 fn nth(&mut self, n: usize) -> Option<Self::Item> {
785 fn all<F>(&mut self, f: F) -> bool
787 F: FnMut(Self::Item) -> bool,
793 fn any<F>(&mut self, f: F) -> bool
795 F: FnMut(Self::Item) -> bool,
801 fn find<P>(&mut self, predicate: P) -> Option<Self::Item>
803 P: FnMut(&Self::Item) -> bool,
805 self.0.find(predicate)
809 fn position<P>(&mut self, predicate: P) -> Option<usize>
811 P: FnMut(Self::Item) -> bool,
813 self.0.position(predicate)
817 fn rposition<P>(&mut self, predicate: P) -> Option<usize>
819 P: FnMut(Self::Item) -> bool,
821 self.0.rposition(predicate)
825 #[stable(feature = "rust1", since = "1.0.0")]
826 impl DoubleEndedIterator for Bytes<'_> {
828 fn next_back(&mut self) -> Option<u8> {
833 fn nth_back(&mut self, n: usize) -> Option<Self::Item> {
838 fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item>
840 P: FnMut(&Self::Item) -> bool,
842 self.0.rfind(predicate)
846 #[stable(feature = "rust1", since = "1.0.0")]
847 impl ExactSizeIterator for Bytes<'_> {
849 fn len(&self) -> usize {
854 fn is_empty(&self) -> bool {
859 #[stable(feature = "fused", since = "1.26.0")]
860 impl FusedIterator for Bytes<'_> {}
862 #[unstable(feature = "trusted_len", issue = "37572")]
863 unsafe impl TrustedLen for Bytes<'_> {}
866 unsafe impl TrustedRandomAccess for Bytes<'_> {
867 unsafe fn get_unchecked(&mut self, i: usize) -> u8 {
868 self.0.get_unchecked(i)
870 fn may_have_side_effect() -> bool {
875 /// This macro generates a Clone impl for string pattern API
876 /// wrapper types of the form X<'a, P>
877 macro_rules! derive_pattern_clone {
878 (clone $t:ident with |$s:ident| $e:expr) => {
879 impl<'a, P> Clone for $t<'a, P>
881 P: Pattern<'a, Searcher: Clone>,
883 fn clone(&self) -> Self {
891 /// This macro generates two public iterator structs
892 /// wrapping a private internal one that makes use of the `Pattern` API.
894 /// For all patterns `P: Pattern<'a>` the following items will be
895 /// generated (generics omitted):
897 /// struct $forward_iterator($internal_iterator);
898 /// struct $reverse_iterator($internal_iterator);
900 /// impl Iterator for $forward_iterator
901 /// { /* internal ends up calling Searcher::next_match() */ }
903 /// impl DoubleEndedIterator for $forward_iterator
904 /// where P::Searcher: DoubleEndedSearcher
905 /// { /* internal ends up calling Searcher::next_match_back() */ }
907 /// impl Iterator for $reverse_iterator
908 /// where P::Searcher: ReverseSearcher
909 /// { /* internal ends up calling Searcher::next_match_back() */ }
911 /// impl DoubleEndedIterator for $reverse_iterator
912 /// where P::Searcher: DoubleEndedSearcher
913 /// { /* internal ends up calling Searcher::next_match() */ }
915 /// The internal one is defined outside the macro, and has almost the same
916 /// semantic as a DoubleEndedIterator by delegating to `pattern::Searcher` and
917 /// `pattern::ReverseSearcher` for both forward and reverse iteration.
919 /// "Almost", because a `Searcher` and a `ReverseSearcher` for a given
920 /// `Pattern` might not return the same elements, so actually implementing
921 /// `DoubleEndedIterator` for it would be incorrect.
922 /// (See the docs in `str::pattern` for more details)
924 /// However, the internal struct still represents a single ended iterator from
925 /// either end, and depending on pattern is also a valid double ended iterator,
926 /// so the two wrapper structs implement `Iterator`
927 /// and `DoubleEndedIterator` depending on the concrete pattern type, leading
928 /// to the complex impls seen above.
929 macro_rules! generate_pattern_iterators {
933 $(#[$forward_iterator_attribute:meta])*
934 struct $forward_iterator:ident;
938 $(#[$reverse_iterator_attribute:meta])*
939 struct $reverse_iterator:ident;
941 // Stability of all generated items
943 $(#[$common_stability_attribute:meta])*
945 // Internal almost-iterator that is being delegated to
947 $internal_iterator:ident yielding ($iterty:ty);
949 // Kind of delegation - either single ended or double ended
952 $(#[$forward_iterator_attribute])*
953 $(#[$common_stability_attribute])*
954 pub struct $forward_iterator<'a, P: Pattern<'a>>($internal_iterator<'a, P>);
956 $(#[$common_stability_attribute])*
957 impl<'a, P> fmt::Debug for $forward_iterator<'a, P>
959 P: Pattern<'a, Searcher: fmt::Debug>,
961 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
962 f.debug_tuple(stringify!($forward_iterator))
968 $(#[$common_stability_attribute])*
969 impl<'a, P: Pattern<'a>> Iterator for $forward_iterator<'a, P> {
973 fn next(&mut self) -> Option<$iterty> {
978 $(#[$common_stability_attribute])*
979 impl<'a, P> Clone for $forward_iterator<'a, P>
981 P: Pattern<'a, Searcher: Clone>,
983 fn clone(&self) -> Self {
984 $forward_iterator(self.0.clone())
988 $(#[$reverse_iterator_attribute])*
989 $(#[$common_stability_attribute])*
990 pub struct $reverse_iterator<'a, P: Pattern<'a>>($internal_iterator<'a, P>);
992 $(#[$common_stability_attribute])*
993 impl<'a, P> fmt::Debug for $reverse_iterator<'a, P>
995 P: Pattern<'a, Searcher: fmt::Debug>,
997 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
998 f.debug_tuple(stringify!($reverse_iterator))
1004 $(#[$common_stability_attribute])*
1005 impl<'a, P> Iterator for $reverse_iterator<'a, P>
1007 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1009 type Item = $iterty;
1012 fn next(&mut self) -> Option<$iterty> {
1017 $(#[$common_stability_attribute])*
1018 impl<'a, P> Clone for $reverse_iterator<'a, P>
1020 P: Pattern<'a, Searcher: Clone>,
1022 fn clone(&self) -> Self {
1023 $reverse_iterator(self.0.clone())
1027 #[stable(feature = "fused", since = "1.26.0")]
1028 impl<'a, P: Pattern<'a>> FusedIterator for $forward_iterator<'a, P> {}
1030 #[stable(feature = "fused", since = "1.26.0")]
1031 impl<'a, P> FusedIterator for $reverse_iterator<'a, P>
1033 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1036 generate_pattern_iterators!($($t)* with $(#[$common_stability_attribute])*,
1038 $reverse_iterator, $iterty);
1041 double ended; with $(#[$common_stability_attribute:meta])*,
1042 $forward_iterator:ident,
1043 $reverse_iterator:ident, $iterty:ty
1045 $(#[$common_stability_attribute])*
1046 impl<'a, P> DoubleEndedIterator for $forward_iterator<'a, P>
1048 P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>,
1051 fn next_back(&mut self) -> Option<$iterty> {
1056 $(#[$common_stability_attribute])*
1057 impl<'a, P> DoubleEndedIterator for $reverse_iterator<'a, P>
1059 P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>,
1062 fn next_back(&mut self) -> Option<$iterty> {
1068 single ended; with $(#[$common_stability_attribute:meta])*,
1069 $forward_iterator:ident,
1070 $reverse_iterator:ident, $iterty:ty
1074 derive_pattern_clone! {
1076 with |s| SplitInternal { matcher: s.matcher.clone(), ..*s }
1079 struct SplitInternal<'a, P: Pattern<'a>> {
1082 matcher: P::Searcher,
1083 allow_trailing_empty: bool,
1087 impl<'a, P> fmt::Debug for SplitInternal<'a, P>
1089 P: Pattern<'a, Searcher: fmt::Debug>,
1091 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1092 f.debug_struct("SplitInternal")
1093 .field("start", &self.start)
1094 .field("end", &self.end)
1095 .field("matcher", &self.matcher)
1096 .field("allow_trailing_empty", &self.allow_trailing_empty)
1097 .field("finished", &self.finished)
1102 impl<'a, P: Pattern<'a>> SplitInternal<'a, P> {
1104 fn get_end(&mut self) -> Option<&'a str> {
1105 if !self.finished && (self.allow_trailing_empty || self.end - self.start > 0) {
1106 self.finished = true;
1107 // SAFETY: `self.start` and `self.end` always lie on unicode boundaries
1109 let string = self.matcher.haystack().get_unchecked(self.start..self.end);
1118 fn next(&mut self) -> Option<&'a str> {
1123 let haystack = self.matcher.haystack();
1124 match self.matcher.next_match() {
1125 // SAFETY: `Searcher` guarantees that `a` and `b` lie on unicode boundaries
1126 Some((a, b)) => unsafe {
1127 let elt = haystack.get_unchecked(self.start..a);
1131 None => self.get_end(),
1136 fn next_back(&mut self) -> Option<&'a str>
1138 P::Searcher: ReverseSearcher<'a>,
1144 if !self.allow_trailing_empty {
1145 self.allow_trailing_empty = true;
1146 match self.next_back() {
1147 Some(elt) if !elt.is_empty() => return Some(elt),
1156 let haystack = self.matcher.haystack();
1157 match self.matcher.next_match_back() {
1158 // SAFETY: `Searcher` guarantees that `a` and `b` lie on unicode boundaries
1159 Some((a, b)) => unsafe {
1160 let elt = haystack.get_unchecked(b..self.end);
1164 // SAFETY: `self.start` and `self.end` always lie on unicode boundaries
1166 self.finished = true;
1167 Some(haystack.get_unchecked(self.start..self.end))
1173 generate_pattern_iterators! {
1175 /// Created with the method [`split`].
1177 /// [`split`]: ../../std/primitive.str.html#method.split
1180 /// Created with the method [`rsplit`].
1182 /// [`rsplit`]: ../../std/primitive.str.html#method.rsplit
1185 #[stable(feature = "rust1", since = "1.0.0")]
1187 SplitInternal yielding (&'a str);
1188 delegate double ended;
1191 generate_pattern_iterators! {
1193 /// Created with the method [`split_terminator`].
1195 /// [`split_terminator`]: ../../std/primitive.str.html#method.split_terminator
1196 struct SplitTerminator;
1198 /// Created with the method [`rsplit_terminator`].
1200 /// [`rsplit_terminator`]: ../../std/primitive.str.html#method.rsplit_terminator
1201 struct RSplitTerminator;
1203 #[stable(feature = "rust1", since = "1.0.0")]
1205 SplitInternal yielding (&'a str);
1206 delegate double ended;
1209 derive_pattern_clone! {
1210 clone SplitNInternal
1211 with |s| SplitNInternal { iter: s.iter.clone(), ..*s }
1214 struct SplitNInternal<'a, P: Pattern<'a>> {
1215 iter: SplitInternal<'a, P>,
1216 /// The number of splits remaining
1220 impl<'a, P> fmt::Debug for SplitNInternal<'a, P>
1222 P: Pattern<'a, Searcher: fmt::Debug>,
1224 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1225 f.debug_struct("SplitNInternal")
1226 .field("iter", &self.iter)
1227 .field("count", &self.count)
1232 impl<'a, P: Pattern<'a>> SplitNInternal<'a, P> {
1234 fn next(&mut self) -> Option<&'a str> {
1249 fn next_back(&mut self) -> Option<&'a str>
1251 P::Searcher: ReverseSearcher<'a>,
1261 self.iter.next_back()
1267 generate_pattern_iterators! {
1269 /// Created with the method [`splitn`].
1271 /// [`splitn`]: ../../std/primitive.str.html#method.splitn
1274 /// Created with the method [`rsplitn`].
1276 /// [`rsplitn`]: ../../std/primitive.str.html#method.rsplitn
1279 #[stable(feature = "rust1", since = "1.0.0")]
1281 SplitNInternal yielding (&'a str);
1282 delegate single ended;
1285 derive_pattern_clone! {
1286 clone MatchIndicesInternal
1287 with |s| MatchIndicesInternal(s.0.clone())
1290 struct MatchIndicesInternal<'a, P: Pattern<'a>>(P::Searcher);
1292 impl<'a, P> fmt::Debug for MatchIndicesInternal<'a, P>
1294 P: Pattern<'a, Searcher: fmt::Debug>,
1296 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1297 f.debug_tuple("MatchIndicesInternal").field(&self.0).finish()
1301 impl<'a, P: Pattern<'a>> MatchIndicesInternal<'a, P> {
1303 fn next(&mut self) -> Option<(usize, &'a str)> {
1304 // SAFETY: `Searcher` guaratees that `start` and `end` lie on unicode boundaries
1307 .map(|(start, end)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) })
1311 fn next_back(&mut self) -> Option<(usize, &'a str)>
1313 P::Searcher: ReverseSearcher<'a>,
1315 // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries
1318 .map(|(start, end)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) })
1322 generate_pattern_iterators! {
1324 /// Created with the method [`match_indices`].
1326 /// [`match_indices`]: ../../std/primitive.str.html#method.match_indices
1327 struct MatchIndices;
1329 /// Created with the method [`rmatch_indices`].
1331 /// [`rmatch_indices`]: ../../std/primitive.str.html#method.rmatch_indices
1332 struct RMatchIndices;
1334 #[stable(feature = "str_match_indices", since = "1.5.0")]
1336 MatchIndicesInternal yielding ((usize, &'a str));
1337 delegate double ended;
1340 derive_pattern_clone! {
1341 clone MatchesInternal
1342 with |s| MatchesInternal(s.0.clone())
1345 struct MatchesInternal<'a, P: Pattern<'a>>(P::Searcher);
1347 impl<'a, P> fmt::Debug for MatchesInternal<'a, P>
1349 P: Pattern<'a, Searcher: fmt::Debug>,
1351 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1352 f.debug_tuple("MatchesInternal").field(&self.0).finish()
1356 impl<'a, P: Pattern<'a>> MatchesInternal<'a, P> {
1358 fn next(&mut self) -> Option<&'a str> {
1359 // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries
1360 self.0.next_match().map(|(a, b)| unsafe {
1361 // Indices are known to be on utf8 boundaries
1362 self.0.haystack().get_unchecked(a..b)
1367 fn next_back(&mut self) -> Option<&'a str>
1369 P::Searcher: ReverseSearcher<'a>,
1371 // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries
1372 self.0.next_match_back().map(|(a, b)| unsafe {
1373 // Indices are known to be on utf8 boundaries
1374 self.0.haystack().get_unchecked(a..b)
1379 generate_pattern_iterators! {
1381 /// Created with the method [`matches`].
1383 /// [`matches`]: ../../std/primitive.str.html#method.matches
1386 /// Created with the method [`rmatches`].
1388 /// [`rmatches`]: ../../std/primitive.str.html#method.rmatches
1391 #[stable(feature = "str_matches", since = "1.2.0")]
1393 MatchesInternal yielding (&'a str);
1394 delegate double ended;
1397 /// An iterator over the lines of a string, as string slices.
1399 /// This struct is created with the [`lines`] method on [`str`].
1400 /// See its documentation for more.
1402 /// [`lines`]: ../../std/primitive.str.html#method.lines
1403 /// [`str`]: ../../std/primitive.str.html
1404 #[stable(feature = "rust1", since = "1.0.0")]
1405 #[derive(Clone, Debug)]
1406 pub struct Lines<'a>(Map<SplitTerminator<'a, char>, LinesAnyMap>);
1408 #[stable(feature = "rust1", since = "1.0.0")]
1409 impl<'a> Iterator for Lines<'a> {
1410 type Item = &'a str;
1413 fn next(&mut self) -> Option<&'a str> {
1418 fn size_hint(&self) -> (usize, Option<usize>) {
1423 fn last(mut self) -> Option<&'a str> {
1428 #[stable(feature = "rust1", since = "1.0.0")]
1429 impl<'a> DoubleEndedIterator for Lines<'a> {
1431 fn next_back(&mut self) -> Option<&'a str> {
1436 #[stable(feature = "fused", since = "1.26.0")]
1437 impl FusedIterator for Lines<'_> {}
1439 /// Created with the method [`lines_any`].
1441 /// [`lines_any`]: ../../std/primitive.str.html#method.lines_any
1442 #[stable(feature = "rust1", since = "1.0.0")]
1443 #[rustc_deprecated(since = "1.4.0", reason = "use lines()/Lines instead now")]
1444 #[derive(Clone, Debug)]
1445 #[allow(deprecated)]
1446 pub struct LinesAny<'a>(Lines<'a>);
1449 /// A nameable, cloneable fn type
1451 struct LinesAnyMap impl<'a> Fn = |line: &'a str| -> &'a str {
1453 if l > 0 && line.as_bytes()[l - 1] == b'\r' { &line[0 .. l - 1] }
1458 #[stable(feature = "rust1", since = "1.0.0")]
1459 #[allow(deprecated)]
1460 impl<'a> Iterator for LinesAny<'a> {
1461 type Item = &'a str;
1464 fn next(&mut self) -> Option<&'a str> {
1469 fn size_hint(&self) -> (usize, Option<usize>) {
1474 #[stable(feature = "rust1", since = "1.0.0")]
1475 #[allow(deprecated)]
1476 impl<'a> DoubleEndedIterator for LinesAny<'a> {
1478 fn next_back(&mut self) -> Option<&'a str> {
1483 #[stable(feature = "fused", since = "1.26.0")]
1484 #[allow(deprecated)]
1485 impl FusedIterator for LinesAny<'_> {}
1488 Section: UTF-8 validation
1491 // use truncation to fit u64 into usize
1492 const NONASCII_MASK: usize = 0x80808080_80808080u64 as usize;
1494 /// Returns `true` if any byte in the word `x` is nonascii (>= 128).
1496 fn contains_nonascii(x: usize) -> bool {
1497 (x & NONASCII_MASK) != 0
1500 /// Walks through `v` checking that it's a valid UTF-8 sequence,
1501 /// returning `Ok(())` in that case, or, if it is invalid, `Err(err)`.
1503 fn run_utf8_validation(v: &[u8]) -> Result<(), Utf8Error> {
1507 let usize_bytes = mem::size_of::<usize>();
1508 let ascii_block_size = 2 * usize_bytes;
1509 let blocks_end = if len >= ascii_block_size { len - ascii_block_size + 1 } else { 0 };
1510 let align = v.as_ptr().align_offset(usize_bytes);
1513 let old_offset = index;
1515 ($error_len: expr) => {
1516 return Err(Utf8Error { valid_up_to: old_offset, error_len: $error_len });
1523 // we needed data, but there was none: error!
1531 let first = v[index];
1533 let w = UTF8_CHAR_WIDTH[first as usize];
1534 // 2-byte encoding is for codepoints \u{0080} to \u{07ff}
1535 // first C2 80 last DF BF
1536 // 3-byte encoding is for codepoints \u{0800} to \u{ffff}
1537 // first E0 A0 80 last EF BF BF
1538 // excluding surrogates codepoints \u{d800} to \u{dfff}
1539 // ED A0 80 to ED BF BF
1540 // 4-byte encoding is for codepoints \u{1000}0 to \u{10ff}ff
1541 // first F0 90 80 80 last F4 8F BF BF
1543 // Use the UTF-8 syntax from the RFC
1545 // https://tools.ietf.org/html/rfc3629
1547 // UTF8-2 = %xC2-DF UTF8-tail
1548 // UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2( UTF8-tail ) /
1549 // %xED %x80-9F UTF8-tail / %xEE-EF 2( UTF8-tail )
1550 // UTF8-4 = %xF0 %x90-BF 2( UTF8-tail ) / %xF1-F3 3( UTF8-tail ) /
1551 // %xF4 %x80-8F 2( UTF8-tail )
1554 if next!() & !CONT_MASK != TAG_CONT_U8 {
1559 match (first, next!()) {
1561 | (0xE1..=0xEC, 0x80..=0xBF)
1562 | (0xED, 0x80..=0x9F)
1563 | (0xEE..=0xEF, 0x80..=0xBF) => {}
1566 if next!() & !CONT_MASK != TAG_CONT_U8 {
1571 match (first, next!()) {
1572 (0xF0, 0x90..=0xBF) | (0xF1..=0xF3, 0x80..=0xBF) | (0xF4, 0x80..=0x8F) => {}
1575 if next!() & !CONT_MASK != TAG_CONT_U8 {
1578 if next!() & !CONT_MASK != TAG_CONT_U8 {
1586 // Ascii case, try to skip forward quickly.
1587 // When the pointer is aligned, read 2 words of data per iteration
1588 // until we find a word containing a non-ascii byte.
1589 if align != usize::max_value() && align.wrapping_sub(index) % usize_bytes == 0 {
1590 let ptr = v.as_ptr();
1591 while index < blocks_end {
1592 // SAFETY: since `align - index` and `ascii_block_size` are multiples of
1593 // `usize_bytes`, `ptr.add(index)` is always aligned with a `usize` so we
1594 // may cast directly to a `const` pointer.
1596 let block = ptr.add(index) as *const usize;
1597 // break if there is a nonascii byte
1598 let zu = contains_nonascii(*block);
1599 let zv = contains_nonascii(*block.offset(1));
1604 index += ascii_block_size;
1606 // step from the point where the wordwise loop stopped
1607 while index < len && v[index] < 128 {
1619 // https://tools.ietf.org/html/rfc3629
1620 static UTF8_CHAR_WIDTH: [u8; 256] = [
1621 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
1623 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
1625 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
1627 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,
1629 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
1631 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
1633 0, 0, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2,
1635 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, // 0xEF
1636 4, 4, 4, 4, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0xFF
1639 /// Given a first byte, determines how many bytes are in this UTF-8 character.
1640 #[unstable(feature = "str_internals", issue = "none")]
1642 pub fn utf8_char_width(b: u8) -> usize {
1643 UTF8_CHAR_WIDTH[b as usize] as usize
1646 /// Mask of the value bits of a continuation byte.
1647 const CONT_MASK: u8 = 0b0011_1111;
1648 /// Value of the tag bits (tag mask is !CONT_MASK) of a continuation byte.
1649 const TAG_CONT_U8: u8 = 0b1000_0000;
1652 Section: Trait implementations
1656 use crate::cmp::Ordering;
1658 use crate::slice::{self, SliceIndex};
1660 /// Implements ordering of strings.
1662 /// Strings are ordered lexicographically by their byte values. This orders Unicode code
1663 /// points based on their positions in the code charts. This is not necessarily the same as
1664 /// "alphabetical" order, which varies by language and locale. Sorting strings according to
1665 /// culturally-accepted standards requires locale-specific data that is outside the scope of
1667 #[stable(feature = "rust1", since = "1.0.0")]
1670 fn cmp(&self, other: &str) -> Ordering {
1671 self.as_bytes().cmp(other.as_bytes())
1675 #[stable(feature = "rust1", since = "1.0.0")]
1676 impl PartialEq for str {
1678 fn eq(&self, other: &str) -> bool {
1679 self.as_bytes() == other.as_bytes()
1682 fn ne(&self, other: &str) -> bool {
1687 #[stable(feature = "rust1", since = "1.0.0")]
1690 /// Implements comparison operations on strings.
1692 /// Strings are compared lexicographically by their byte values. This compares Unicode code
1693 /// points based on their positions in the code charts. This is not necessarily the same as
1694 /// "alphabetical" order, which varies by language and locale. Comparing strings according to
1695 /// culturally-accepted standards requires locale-specific data that is outside the scope of
1697 #[stable(feature = "rust1", since = "1.0.0")]
1698 impl PartialOrd for str {
1700 fn partial_cmp(&self, other: &str) -> Option<Ordering> {
1701 Some(self.cmp(other))
1705 #[stable(feature = "rust1", since = "1.0.0")]
1706 impl<I> ops::Index<I> for str
1710 type Output = I::Output;
1713 fn index(&self, index: I) -> &I::Output {
1718 #[stable(feature = "rust1", since = "1.0.0")]
1719 impl<I> ops::IndexMut<I> for str
1724 fn index_mut(&mut self, index: I) -> &mut I::Output {
1725 index.index_mut(self)
1731 fn str_index_overflow_fail() -> ! {
1732 panic!("attempted to index str up to maximum usize");
1735 /// Implements substring slicing with syntax `&self[..]` or `&mut self[..]`.
1737 /// Returns a slice of the whole string, i.e., returns `&self` or `&mut
1738 /// self`. Equivalent to `&self[0 .. len]` or `&mut self[0 .. len]`. Unlike
1739 /// other indexing operations, this can never panic.
1741 /// This operation is `O(1)`.
1743 /// Prior to 1.20.0, these indexing operations were still supported by
1744 /// direct implementation of `Index` and `IndexMut`.
1746 /// Equivalent to `&self[0 .. len]` or `&mut self[0 .. len]`.
1747 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1748 impl SliceIndex<str> for ops::RangeFull {
1751 fn get(self, slice: &str) -> Option<&Self::Output> {
1755 fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
1759 unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
1763 unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
1767 fn index(self, slice: &str) -> &Self::Output {
1771 fn index_mut(self, slice: &mut str) -> &mut Self::Output {
1776 /// Implements substring slicing with syntax `&self[begin .. end]` or `&mut
1777 /// self[begin .. end]`.
1779 /// Returns a slice of the given string from the byte range
1780 /// [`begin`, `end`).
1782 /// This operation is `O(1)`.
1784 /// Prior to 1.20.0, these indexing operations were still supported by
1785 /// direct implementation of `Index` and `IndexMut`.
1789 /// Panics if `begin` or `end` does not point to the starting byte offset of
1790 /// a character (as defined by `is_char_boundary`), if `begin > end`, or if
1796 /// let s = "Löwe 老虎 Léopard";
1797 /// assert_eq!(&s[0 .. 1], "L");
1799 /// assert_eq!(&s[1 .. 9], "öwe 老");
1801 /// // these will panic:
1802 /// // byte 2 lies within `ö`:
1805 /// // byte 8 lies within `老`
1808 /// // byte 100 is outside the string
1809 /// // &s[3 .. 100];
1811 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1812 impl SliceIndex<str> for ops::Range<usize> {
1815 fn get(self, slice: &str) -> Option<&Self::Output> {
1816 if self.start <= self.end
1817 && slice.is_char_boundary(self.start)
1818 && slice.is_char_boundary(self.end)
1820 // SAFETY: just checked that `start` and `end` are on a char boundary
1821 Some(unsafe { self.get_unchecked(slice) })
1827 fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
1828 if self.start <= self.end
1829 && slice.is_char_boundary(self.start)
1830 && slice.is_char_boundary(self.end)
1832 // SAFETY: just checked that `start` and `end` are on a char boundary
1833 Some(unsafe { self.get_unchecked_mut(slice) })
1839 unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
1840 let ptr = slice.as_ptr().add(self.start);
1841 let len = self.end - self.start;
1842 super::from_utf8_unchecked(slice::from_raw_parts(ptr, len))
1845 unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
1846 let ptr = slice.as_mut_ptr().add(self.start);
1847 let len = self.end - self.start;
1848 super::from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, len))
1851 fn index(self, slice: &str) -> &Self::Output {
1852 let (start, end) = (self.start, self.end);
1853 self.get(slice).unwrap_or_else(|| super::slice_error_fail(slice, start, end))
1856 fn index_mut(self, slice: &mut str) -> &mut Self::Output {
1857 // is_char_boundary checks that the index is in [0, .len()]
1858 // cannot reuse `get` as above, because of NLL trouble
1859 if self.start <= self.end
1860 && slice.is_char_boundary(self.start)
1861 && slice.is_char_boundary(self.end)
1863 // SAFETY: just checked that `start` and `end` are on a char boundary
1864 unsafe { self.get_unchecked_mut(slice) }
1866 super::slice_error_fail(slice, self.start, self.end)
1871 /// Implements substring slicing with syntax `&self[.. end]` or `&mut
1874 /// Returns a slice of the given string from the byte range [`0`, `end`).
1875 /// Equivalent to `&self[0 .. end]` or `&mut self[0 .. end]`.
1877 /// This operation is `O(1)`.
1879 /// Prior to 1.20.0, these indexing operations were still supported by
1880 /// direct implementation of `Index` and `IndexMut`.
1884 /// Panics if `end` does not point to the starting byte offset of a
1885 /// character (as defined by `is_char_boundary`), or if `end > len`.
1886 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1887 impl SliceIndex<str> for ops::RangeTo<usize> {
1890 fn get(self, slice: &str) -> Option<&Self::Output> {
1891 if slice.is_char_boundary(self.end) {
1892 // SAFETY: just checked that `end` is on a char boundary
1893 Some(unsafe { self.get_unchecked(slice) })
1899 fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
1900 if slice.is_char_boundary(self.end) {
1901 // SAFETY: just checked that `end` is on a char boundary
1902 Some(unsafe { self.get_unchecked_mut(slice) })
1908 unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
1909 let ptr = slice.as_ptr();
1910 super::from_utf8_unchecked(slice::from_raw_parts(ptr, self.end))
1913 unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
1914 let ptr = slice.as_mut_ptr();
1915 super::from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, self.end))
1918 fn index(self, slice: &str) -> &Self::Output {
1920 self.get(slice).unwrap_or_else(|| super::slice_error_fail(slice, 0, end))
1923 fn index_mut(self, slice: &mut str) -> &mut Self::Output {
1924 if slice.is_char_boundary(self.end) {
1925 // SAFETY: just checked that `end` is on a char boundary
1926 unsafe { self.get_unchecked_mut(slice) }
1928 super::slice_error_fail(slice, 0, self.end)
1933 /// Implements substring slicing with syntax `&self[begin ..]` or `&mut
1934 /// self[begin ..]`.
1936 /// Returns a slice of the given string from the byte range [`begin`,
1937 /// `len`). Equivalent to `&self[begin .. len]` or `&mut self[begin ..
1940 /// This operation is `O(1)`.
1942 /// Prior to 1.20.0, these indexing operations were still supported by
1943 /// direct implementation of `Index` and `IndexMut`.
1947 /// Panics if `begin` does not point to the starting byte offset of
1948 /// a character (as defined by `is_char_boundary`), or if `begin >= len`.
1949 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1950 impl SliceIndex<str> for ops::RangeFrom<usize> {
1953 fn get(self, slice: &str) -> Option<&Self::Output> {
1954 if slice.is_char_boundary(self.start) {
1955 // SAFETY: just checked that `start` is on a char boundary
1956 Some(unsafe { self.get_unchecked(slice) })
1962 fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
1963 if slice.is_char_boundary(self.start) {
1964 // SAFETY: just checked that `start` is on a char boundary
1965 Some(unsafe { self.get_unchecked_mut(slice) })
1971 unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
1972 let ptr = slice.as_ptr().add(self.start);
1973 let len = slice.len() - self.start;
1974 super::from_utf8_unchecked(slice::from_raw_parts(ptr, len))
1977 unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
1978 let ptr = slice.as_mut_ptr().add(self.start);
1979 let len = slice.len() - self.start;
1980 super::from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, len))
1983 fn index(self, slice: &str) -> &Self::Output {
1984 let (start, end) = (self.start, slice.len());
1985 self.get(slice).unwrap_or_else(|| super::slice_error_fail(slice, start, end))
1988 fn index_mut(self, slice: &mut str) -> &mut Self::Output {
1989 if slice.is_char_boundary(self.start) {
1990 // SAFETY: just checked that `start` is on a char boundary
1991 unsafe { self.get_unchecked_mut(slice) }
1993 super::slice_error_fail(slice, self.start, slice.len())
1998 /// Implements substring slicing with syntax `&self[begin ..= end]` or `&mut
1999 /// self[begin ..= end]`.
2001 /// Returns a slice of the given string from the byte range
2002 /// [`begin`, `end`]. Equivalent to `&self [begin .. end + 1]` or `&mut
2003 /// self[begin .. end + 1]`, except if `end` has the maximum value for
2006 /// This operation is `O(1)`.
2010 /// Panics if `begin` does not point to the starting byte offset of
2011 /// a character (as defined by `is_char_boundary`), if `end` does not point
2012 /// to the ending byte offset of a character (`end + 1` is either a starting
2013 /// byte offset or equal to `len`), if `begin > end`, or if `end >= len`.
2014 #[stable(feature = "inclusive_range", since = "1.26.0")]
2015 impl SliceIndex<str> for ops::RangeInclusive<usize> {
2018 fn get(self, slice: &str) -> Option<&Self::Output> {
2019 if *self.end() == usize::max_value() {
2022 (*self.start()..self.end() + 1).get(slice)
2026 fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
2027 if *self.end() == usize::max_value() {
2030 (*self.start()..self.end() + 1).get_mut(slice)
2034 unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
2035 (*self.start()..self.end() + 1).get_unchecked(slice)
2038 unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
2039 (*self.start()..self.end() + 1).get_unchecked_mut(slice)
2042 fn index(self, slice: &str) -> &Self::Output {
2043 if *self.end() == usize::max_value() {
2044 str_index_overflow_fail();
2046 (*self.start()..self.end() + 1).index(slice)
2049 fn index_mut(self, slice: &mut str) -> &mut Self::Output {
2050 if *self.end() == usize::max_value() {
2051 str_index_overflow_fail();
2053 (*self.start()..self.end() + 1).index_mut(slice)
2057 /// Implements substring slicing with syntax `&self[..= end]` or `&mut
2060 /// Returns a slice of the given string from the byte range [0, `end`].
2061 /// Equivalent to `&self [0 .. end + 1]`, except if `end` has the maximum
2062 /// value for `usize`.
2064 /// This operation is `O(1)`.
2068 /// Panics if `end` does not point to the ending byte offset of a character
2069 /// (`end + 1` is either a starting byte offset as defined by
2070 /// `is_char_boundary`, or equal to `len`), or if `end >= len`.
2071 #[stable(feature = "inclusive_range", since = "1.26.0")]
2072 impl SliceIndex<str> for ops::RangeToInclusive<usize> {
2075 fn get(self, slice: &str) -> Option<&Self::Output> {
2076 if self.end == usize::max_value() { None } else { (..self.end + 1).get(slice) }
2079 fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
2080 if self.end == usize::max_value() { None } else { (..self.end + 1).get_mut(slice) }
2083 unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
2084 (..self.end + 1).get_unchecked(slice)
2087 unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
2088 (..self.end + 1).get_unchecked_mut(slice)
2091 fn index(self, slice: &str) -> &Self::Output {
2092 if self.end == usize::max_value() {
2093 str_index_overflow_fail();
2095 (..self.end + 1).index(slice)
2098 fn index_mut(self, slice: &mut str) -> &mut Self::Output {
2099 if self.end == usize::max_value() {
2100 str_index_overflow_fail();
2102 (..self.end + 1).index_mut(slice)
2107 // truncate `&str` to length at most equal to `max`
2108 // return `true` if it were truncated, and the new str.
2109 fn truncate_to_char_boundary(s: &str, mut max: usize) -> (bool, &str) {
2113 while !s.is_char_boundary(max) {
2122 fn slice_error_fail(s: &str, begin: usize, end: usize) -> ! {
2123 const MAX_DISPLAY_LENGTH: usize = 256;
2124 let (truncated, s_trunc) = truncate_to_char_boundary(s, MAX_DISPLAY_LENGTH);
2125 let ellipsis = if truncated { "[...]" } else { "" };
2128 if begin > s.len() || end > s.len() {
2129 let oob_index = if begin > s.len() { begin } else { end };
2130 panic!("byte index {} is out of bounds of `{}`{}", oob_index, s_trunc, ellipsis);
2136 "begin <= end ({} <= {}) when slicing `{}`{}",
2143 // 3. character boundary
2144 let index = if !s.is_char_boundary(begin) { begin } else { end };
2145 // find the character
2146 let mut char_start = index;
2147 while !s.is_char_boundary(char_start) {
2150 // `char_start` must be less than len and a char boundary
2151 let ch = s[char_start..].chars().next().unwrap();
2152 let char_range = char_start..char_start + ch.len_utf8();
2154 "byte index {} is not a char boundary; it is inside {:?} (bytes {:?}) of `{}`{}",
2155 index, ch, char_range, s_trunc, ellipsis
2162 /// Returns the length of `self`.
2164 /// This length is in bytes, not [`char`]s or graphemes. In other words,
2165 /// it may not be what a human considers the length of the string.
2172 /// let len = "foo".len();
2173 /// assert_eq!(3, len);
2175 /// assert_eq!("ƒoo".len(), 4); // fancy f!
2176 /// assert_eq!("ƒoo".chars().count(), 3);
2178 #[stable(feature = "rust1", since = "1.0.0")]
2179 #[rustc_const_stable(feature = "const_str_len", since = "1.32.0")]
2181 pub const fn len(&self) -> usize {
2182 self.as_bytes().len()
2185 /// Returns `true` if `self` has a length of zero bytes.
2193 /// assert!(s.is_empty());
2195 /// let s = "not empty";
2196 /// assert!(!s.is_empty());
2199 #[stable(feature = "rust1", since = "1.0.0")]
2200 #[rustc_const_stable(feature = "const_str_is_empty", since = "1.32.0")]
2201 pub const fn is_empty(&self) -> bool {
2205 /// Checks that `index`-th byte lies at the start and/or end of a
2206 /// UTF-8 code point sequence.
2208 /// The start and end of the string (when `index == self.len()`) are
2209 /// considered to be
2212 /// Returns `false` if `index` is greater than `self.len()`.
2217 /// let s = "Löwe 老虎 Léopard";
2218 /// assert!(s.is_char_boundary(0));
2220 /// assert!(s.is_char_boundary(6));
2221 /// assert!(s.is_char_boundary(s.len()));
2223 /// // second byte of `ö`
2224 /// assert!(!s.is_char_boundary(2));
2226 /// // third byte of `老`
2227 /// assert!(!s.is_char_boundary(8));
2229 #[stable(feature = "is_char_boundary", since = "1.9.0")]
2231 pub fn is_char_boundary(&self, index: usize) -> bool {
2232 // 0 and len are always ok.
2233 // Test for 0 explicitly so that it can optimize out the check
2234 // easily and skip reading string data for that case.
2235 if index == 0 || index == self.len() {
2238 match self.as_bytes().get(index) {
2240 // This is bit magic equivalent to: b < 128 || b >= 192
2241 Some(&b) => (b as i8) >= -0x40,
2245 /// Converts a string slice to a byte slice. To convert the byte slice back
2246 /// into a string slice, use the [`str::from_utf8`] function.
2248 /// [`str::from_utf8`]: ./str/fn.from_utf8.html
2255 /// let bytes = "bors".as_bytes();
2256 /// assert_eq!(b"bors", bytes);
2258 #[stable(feature = "rust1", since = "1.0.0")]
2259 #[rustc_const_stable(feature = "str_as_bytes", since = "1.32.0")]
2261 #[allow(unused_attributes)]
2262 #[allow_internal_unstable(const_fn_union)]
2263 pub const fn as_bytes(&self) -> &[u8] {
2269 // SAFETY: const sound because we transmute two types with the same layout
2270 unsafe { Slices { str: self }.slice }
2273 /// Converts a mutable string slice to a mutable byte slice. To convert the
2274 /// mutable byte slice back into a mutable string slice, use the
2275 /// [`str::from_utf8_mut`] function.
2277 /// [`str::from_utf8_mut`]: ./str/fn.from_utf8_mut.html
2284 /// let mut s = String::from("Hello");
2285 /// let bytes = unsafe { s.as_bytes_mut() };
2287 /// assert_eq!(b"Hello", bytes);
2293 /// let mut s = String::from("🗻∈🌏");
2296 /// let bytes = s.as_bytes_mut();
2298 /// bytes[0] = 0xF0;
2299 /// bytes[1] = 0x9F;
2300 /// bytes[2] = 0x8D;
2301 /// bytes[3] = 0x94;
2304 /// assert_eq!("🍔∈🌏", s);
2306 #[stable(feature = "str_mut_extras", since = "1.20.0")]
2308 pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8] {
2309 &mut *(self as *mut str as *mut [u8])
2312 /// Converts a string slice to a raw pointer.
2314 /// As string slices are a slice of bytes, the raw pointer points to a
2315 /// [`u8`]. This pointer will be pointing to the first byte of the string
2318 /// The caller must ensure that the returned pointer is never written to.
2319 /// If you need to mutate the contents of the string slice, use [`as_mut_ptr`].
2321 /// [`u8`]: primitive.u8.html
2322 /// [`as_mut_ptr`]: #method.as_mut_ptr
2329 /// let s = "Hello";
2330 /// let ptr = s.as_ptr();
2332 #[stable(feature = "rust1", since = "1.0.0")]
2333 #[rustc_const_stable(feature = "rustc_str_as_ptr", since = "1.32.0")]
2335 pub const fn as_ptr(&self) -> *const u8 {
2336 self as *const str as *const u8
2339 /// Converts a mutable string slice to a raw pointer.
2341 /// As string slices are a slice of bytes, the raw pointer points to a
2342 /// [`u8`]. This pointer will be pointing to the first byte of the string
2345 /// It is your responsibility to make sure that the string slice only gets
2346 /// modified in a way that it remains valid UTF-8.
2348 /// [`u8`]: primitive.u8.html
2349 #[stable(feature = "str_as_mut_ptr", since = "1.36.0")]
2351 pub fn as_mut_ptr(&mut self) -> *mut u8 {
2352 self as *mut str as *mut u8
2355 /// Returns a subslice of `str`.
2357 /// This is the non-panicking alternative to indexing the `str`. Returns
2358 /// [`None`] whenever equivalent indexing operation would panic.
2360 /// [`None`]: option/enum.Option.html#variant.None
2365 /// let v = String::from("🗻∈🌏");
2367 /// assert_eq!(Some("🗻"), v.get(0..4));
2369 /// // indices not on UTF-8 sequence boundaries
2370 /// assert!(v.get(1..).is_none());
2371 /// assert!(v.get(..8).is_none());
2373 /// // out of bounds
2374 /// assert!(v.get(..42).is_none());
2376 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2378 pub fn get<I: SliceIndex<str>>(&self, i: I) -> Option<&I::Output> {
2382 /// Returns a mutable subslice of `str`.
2384 /// This is the non-panicking alternative to indexing the `str`. Returns
2385 /// [`None`] whenever equivalent indexing operation would panic.
2387 /// [`None`]: option/enum.Option.html#variant.None
2392 /// let mut v = String::from("hello");
2393 /// // correct length
2394 /// assert!(v.get_mut(0..5).is_some());
2395 /// // out of bounds
2396 /// assert!(v.get_mut(..42).is_none());
2397 /// assert_eq!(Some("he"), v.get_mut(0..2).map(|v| &*v));
2399 /// assert_eq!("hello", v);
2401 /// let s = v.get_mut(0..2);
2402 /// let s = s.map(|s| {
2403 /// s.make_ascii_uppercase();
2406 /// assert_eq!(Some("HE"), s);
2408 /// assert_eq!("HEllo", v);
2410 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2412 pub fn get_mut<I: SliceIndex<str>>(&mut self, i: I) -> Option<&mut I::Output> {
2416 /// Returns an unchecked subslice of `str`.
2418 /// This is the unchecked alternative to indexing the `str`.
2422 /// Callers of this function are responsible that these preconditions are
2425 /// * The starting index must come before the ending index;
2426 /// * Indexes must be within bounds of the original slice;
2427 /// * Indexes must lie on UTF-8 sequence boundaries.
2429 /// Failing that, the returned string slice may reference invalid memory or
2430 /// violate the invariants communicated by the `str` type.
2437 /// assert_eq!("🗻", v.get_unchecked(0..4));
2438 /// assert_eq!("∈", v.get_unchecked(4..7));
2439 /// assert_eq!("🌏", v.get_unchecked(7..11));
2442 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2444 pub unsafe fn get_unchecked<I: SliceIndex<str>>(&self, i: I) -> &I::Output {
2445 i.get_unchecked(self)
2448 /// Returns a mutable, unchecked subslice of `str`.
2450 /// This is the unchecked alternative to indexing the `str`.
2454 /// Callers of this function are responsible that these preconditions are
2457 /// * The starting index must come before the ending index;
2458 /// * Indexes must be within bounds of the original slice;
2459 /// * Indexes must lie on UTF-8 sequence boundaries.
2461 /// Failing that, the returned string slice may reference invalid memory or
2462 /// violate the invariants communicated by the `str` type.
2467 /// let mut v = String::from("🗻∈🌏");
2469 /// assert_eq!("🗻", v.get_unchecked_mut(0..4));
2470 /// assert_eq!("∈", v.get_unchecked_mut(4..7));
2471 /// assert_eq!("🌏", v.get_unchecked_mut(7..11));
2474 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2476 pub unsafe fn get_unchecked_mut<I: SliceIndex<str>>(&mut self, i: I) -> &mut I::Output {
2477 i.get_unchecked_mut(self)
2480 /// Creates a string slice from another string slice, bypassing safety
2483 /// This is generally not recommended, use with caution! For a safe
2484 /// alternative see [`str`] and [`Index`].
2486 /// [`str`]: primitive.str.html
2487 /// [`Index`]: ops/trait.Index.html
2489 /// This new slice goes from `begin` to `end`, including `begin` but
2490 /// excluding `end`.
2492 /// To get a mutable string slice instead, see the
2493 /// [`slice_mut_unchecked`] method.
2495 /// [`slice_mut_unchecked`]: #method.slice_mut_unchecked
2499 /// Callers of this function are responsible that three preconditions are
2502 /// * `begin` must come before `end`.
2503 /// * `begin` and `end` must be byte positions within the string slice.
2504 /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
2511 /// let s = "Löwe 老虎 Léopard";
2514 /// assert_eq!("Löwe 老虎 Léopard", s.slice_unchecked(0, 21));
2517 /// let s = "Hello, world!";
2520 /// assert_eq!("world", s.slice_unchecked(7, 12));
2523 #[stable(feature = "rust1", since = "1.0.0")]
2524 #[rustc_deprecated(since = "1.29.0", reason = "use `get_unchecked(begin..end)` instead")]
2526 pub unsafe fn slice_unchecked(&self, begin: usize, end: usize) -> &str {
2527 (begin..end).get_unchecked(self)
2530 /// Creates a string slice from another string slice, bypassing safety
2532 /// This is generally not recommended, use with caution! For a safe
2533 /// alternative see [`str`] and [`IndexMut`].
2535 /// [`str`]: primitive.str.html
2536 /// [`IndexMut`]: ops/trait.IndexMut.html
2538 /// This new slice goes from `begin` to `end`, including `begin` but
2539 /// excluding `end`.
2541 /// To get an immutable string slice instead, see the
2542 /// [`slice_unchecked`] method.
2544 /// [`slice_unchecked`]: #method.slice_unchecked
2548 /// Callers of this function are responsible that three preconditions are
2551 /// * `begin` must come before `end`.
2552 /// * `begin` and `end` must be byte positions within the string slice.
2553 /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
2554 #[stable(feature = "str_slice_mut", since = "1.5.0")]
2555 #[rustc_deprecated(since = "1.29.0", reason = "use `get_unchecked_mut(begin..end)` instead")]
2557 pub unsafe fn slice_mut_unchecked(&mut self, begin: usize, end: usize) -> &mut str {
2558 (begin..end).get_unchecked_mut(self)
2561 /// Divide one string slice into two at an index.
2563 /// The argument, `mid`, should be a byte offset from the start of the
2564 /// string. It must also be on the boundary of a UTF-8 code point.
2566 /// The two slices returned go from the start of the string slice to `mid`,
2567 /// and from `mid` to the end of the string slice.
2569 /// To get mutable string slices instead, see the [`split_at_mut`]
2572 /// [`split_at_mut`]: #method.split_at_mut
2576 /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
2577 /// beyond the last code point of the string slice.
2584 /// let s = "Per Martin-Löf";
2586 /// let (first, last) = s.split_at(3);
2588 /// assert_eq!("Per", first);
2589 /// assert_eq!(" Martin-Löf", last);
2592 #[stable(feature = "str_split_at", since = "1.4.0")]
2593 pub fn split_at(&self, mid: usize) -> (&str, &str) {
2594 // is_char_boundary checks that the index is in [0, .len()]
2595 if self.is_char_boundary(mid) {
2596 // SAFETY: just checked that `mid` is on a char boundary
2597 unsafe { (self.get_unchecked(0..mid), self.get_unchecked(mid..self.len())) }
2599 slice_error_fail(self, 0, mid)
2603 /// Divide one mutable string slice into two at an index.
2605 /// The argument, `mid`, should be a byte offset from the start of the
2606 /// string. It must also be on the boundary of a UTF-8 code point.
2608 /// The two slices returned go from the start of the string slice to `mid`,
2609 /// and from `mid` to the end of the string slice.
2611 /// To get immutable string slices instead, see the [`split_at`] method.
2613 /// [`split_at`]: #method.split_at
2617 /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
2618 /// beyond the last code point of the string slice.
2625 /// let mut s = "Per Martin-Löf".to_string();
2627 /// let (first, last) = s.split_at_mut(3);
2628 /// first.make_ascii_uppercase();
2629 /// assert_eq!("PER", first);
2630 /// assert_eq!(" Martin-Löf", last);
2632 /// assert_eq!("PER Martin-Löf", s);
2635 #[stable(feature = "str_split_at", since = "1.4.0")]
2636 pub fn split_at_mut(&mut self, mid: usize) -> (&mut str, &mut str) {
2637 // is_char_boundary checks that the index is in [0, .len()]
2638 if self.is_char_boundary(mid) {
2639 let len = self.len();
2640 let ptr = self.as_mut_ptr();
2641 // SAFETY: just checked that `mid` is on a char boundary
2644 from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, mid)),
2645 from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr.add(mid), len - mid)),
2649 slice_error_fail(self, 0, mid)
2653 /// Returns an iterator over the [`char`]s of a string slice.
2655 /// As a string slice consists of valid UTF-8, we can iterate through a
2656 /// string slice by [`char`]. This method returns such an iterator.
2658 /// It's important to remember that [`char`] represents a Unicode Scalar
2659 /// Value, and may not match your idea of what a 'character' is. Iteration
2660 /// over grapheme clusters may be what you actually want.
2667 /// let word = "goodbye";
2669 /// let count = word.chars().count();
2670 /// assert_eq!(7, count);
2672 /// let mut chars = word.chars();
2674 /// assert_eq!(Some('g'), chars.next());
2675 /// assert_eq!(Some('o'), chars.next());
2676 /// assert_eq!(Some('o'), chars.next());
2677 /// assert_eq!(Some('d'), chars.next());
2678 /// assert_eq!(Some('b'), chars.next());
2679 /// assert_eq!(Some('y'), chars.next());
2680 /// assert_eq!(Some('e'), chars.next());
2682 /// assert_eq!(None, chars.next());
2685 /// Remember, [`char`]s may not match your human intuition about characters:
2690 /// let mut chars = y.chars();
2692 /// assert_eq!(Some('y'), chars.next()); // not 'y̆'
2693 /// assert_eq!(Some('\u{0306}'), chars.next());
2695 /// assert_eq!(None, chars.next());
2697 #[stable(feature = "rust1", since = "1.0.0")]
2699 pub fn chars(&self) -> Chars<'_> {
2700 Chars { iter: self.as_bytes().iter() }
2703 /// Returns an iterator over the [`char`]s of a string slice, and their
2706 /// As a string slice consists of valid UTF-8, we can iterate through a
2707 /// string slice by [`char`]. This method returns an iterator of both
2708 /// these [`char`]s, as well as their byte positions.
2710 /// The iterator yields tuples. The position is first, the [`char`] is
2718 /// let word = "goodbye";
2720 /// let count = word.char_indices().count();
2721 /// assert_eq!(7, count);
2723 /// let mut char_indices = word.char_indices();
2725 /// assert_eq!(Some((0, 'g')), char_indices.next());
2726 /// assert_eq!(Some((1, 'o')), char_indices.next());
2727 /// assert_eq!(Some((2, 'o')), char_indices.next());
2728 /// assert_eq!(Some((3, 'd')), char_indices.next());
2729 /// assert_eq!(Some((4, 'b')), char_indices.next());
2730 /// assert_eq!(Some((5, 'y')), char_indices.next());
2731 /// assert_eq!(Some((6, 'e')), char_indices.next());
2733 /// assert_eq!(None, char_indices.next());
2736 /// Remember, [`char`]s may not match your human intuition about characters:
2739 /// let yes = "y̆es";
2741 /// let mut char_indices = yes.char_indices();
2743 /// assert_eq!(Some((0, 'y')), char_indices.next()); // not (0, 'y̆')
2744 /// assert_eq!(Some((1, '\u{0306}')), char_indices.next());
2746 /// // note the 3 here - the last character took up two bytes
2747 /// assert_eq!(Some((3, 'e')), char_indices.next());
2748 /// assert_eq!(Some((4, 's')), char_indices.next());
2750 /// assert_eq!(None, char_indices.next());
2752 #[stable(feature = "rust1", since = "1.0.0")]
2754 pub fn char_indices(&self) -> CharIndices<'_> {
2755 CharIndices { front_offset: 0, iter: self.chars() }
2758 /// An iterator over the bytes of a string slice.
2760 /// As a string slice consists of a sequence of bytes, we can iterate
2761 /// through a string slice by byte. This method returns such an iterator.
2768 /// let mut bytes = "bors".bytes();
2770 /// assert_eq!(Some(b'b'), bytes.next());
2771 /// assert_eq!(Some(b'o'), bytes.next());
2772 /// assert_eq!(Some(b'r'), bytes.next());
2773 /// assert_eq!(Some(b's'), bytes.next());
2775 /// assert_eq!(None, bytes.next());
2777 #[stable(feature = "rust1", since = "1.0.0")]
2779 pub fn bytes(&self) -> Bytes<'_> {
2780 Bytes(self.as_bytes().iter().cloned())
2783 /// Splits a string slice by whitespace.
2785 /// The iterator returned will return string slices that are sub-slices of
2786 /// the original string slice, separated by any amount of whitespace.
2788 /// 'Whitespace' is defined according to the terms of the Unicode Derived
2789 /// Core Property `White_Space`. If you only want to split on ASCII whitespace
2790 /// instead, use [`split_ascii_whitespace`].
2792 /// [`split_ascii_whitespace`]: #method.split_ascii_whitespace
2799 /// let mut iter = "A few words".split_whitespace();
2801 /// assert_eq!(Some("A"), iter.next());
2802 /// assert_eq!(Some("few"), iter.next());
2803 /// assert_eq!(Some("words"), iter.next());
2805 /// assert_eq!(None, iter.next());
2808 /// All kinds of whitespace are considered:
2811 /// let mut iter = " Mary had\ta\u{2009}little \n\t lamb".split_whitespace();
2812 /// assert_eq!(Some("Mary"), iter.next());
2813 /// assert_eq!(Some("had"), iter.next());
2814 /// assert_eq!(Some("a"), iter.next());
2815 /// assert_eq!(Some("little"), iter.next());
2816 /// assert_eq!(Some("lamb"), iter.next());
2818 /// assert_eq!(None, iter.next());
2820 #[stable(feature = "split_whitespace", since = "1.1.0")]
2822 pub fn split_whitespace(&self) -> SplitWhitespace<'_> {
2823 SplitWhitespace { inner: self.split(IsWhitespace).filter(IsNotEmpty) }
2826 /// Splits a string slice by ASCII whitespace.
2828 /// The iterator returned will return string slices that are sub-slices of
2829 /// the original string slice, separated by any amount of ASCII whitespace.
2831 /// To split by Unicode `Whitespace` instead, use [`split_whitespace`].
2833 /// [`split_whitespace`]: #method.split_whitespace
2840 /// let mut iter = "A few words".split_ascii_whitespace();
2842 /// assert_eq!(Some("A"), iter.next());
2843 /// assert_eq!(Some("few"), iter.next());
2844 /// assert_eq!(Some("words"), iter.next());
2846 /// assert_eq!(None, iter.next());
2849 /// All kinds of ASCII whitespace are considered:
2852 /// let mut iter = " Mary had\ta little \n\t lamb".split_ascii_whitespace();
2853 /// assert_eq!(Some("Mary"), iter.next());
2854 /// assert_eq!(Some("had"), iter.next());
2855 /// assert_eq!(Some("a"), iter.next());
2856 /// assert_eq!(Some("little"), iter.next());
2857 /// assert_eq!(Some("lamb"), iter.next());
2859 /// assert_eq!(None, iter.next());
2861 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
2863 pub fn split_ascii_whitespace(&self) -> SplitAsciiWhitespace<'_> {
2865 self.as_bytes().split(IsAsciiWhitespace).filter(BytesIsNotEmpty).map(UnsafeBytesToStr);
2866 SplitAsciiWhitespace { inner }
2869 /// An iterator over the lines of a string, as string slices.
2871 /// Lines are ended with either a newline (`\n`) or a carriage return with
2872 /// a line feed (`\r\n`).
2874 /// The final line ending is optional.
2881 /// let text = "foo\r\nbar\n\nbaz\n";
2882 /// let mut lines = text.lines();
2884 /// assert_eq!(Some("foo"), lines.next());
2885 /// assert_eq!(Some("bar"), lines.next());
2886 /// assert_eq!(Some(""), lines.next());
2887 /// assert_eq!(Some("baz"), lines.next());
2889 /// assert_eq!(None, lines.next());
2892 /// The final line ending isn't required:
2895 /// let text = "foo\nbar\n\r\nbaz";
2896 /// let mut lines = text.lines();
2898 /// assert_eq!(Some("foo"), lines.next());
2899 /// assert_eq!(Some("bar"), lines.next());
2900 /// assert_eq!(Some(""), lines.next());
2901 /// assert_eq!(Some("baz"), lines.next());
2903 /// assert_eq!(None, lines.next());
2905 #[stable(feature = "rust1", since = "1.0.0")]
2907 pub fn lines(&self) -> Lines<'_> {
2908 Lines(self.split_terminator('\n').map(LinesAnyMap))
2911 /// An iterator over the lines of a string.
2912 #[stable(feature = "rust1", since = "1.0.0")]
2913 #[rustc_deprecated(since = "1.4.0", reason = "use lines() instead now")]
2915 #[allow(deprecated)]
2916 pub fn lines_any(&self) -> LinesAny<'_> {
2917 LinesAny(self.lines())
2920 /// Returns an iterator of `u16` over the string encoded as UTF-16.
2927 /// let text = "Zażółć gęślą jaźń";
2929 /// let utf8_len = text.len();
2930 /// let utf16_len = text.encode_utf16().count();
2932 /// assert!(utf16_len <= utf8_len);
2934 #[stable(feature = "encode_utf16", since = "1.8.0")]
2935 pub fn encode_utf16(&self) -> EncodeUtf16<'_> {
2936 EncodeUtf16 { chars: self.chars(), extra: 0 }
2939 /// Returns `true` if the given pattern matches a sub-slice of
2940 /// this string slice.
2942 /// Returns `false` if it does not.
2949 /// let bananas = "bananas";
2951 /// assert!(bananas.contains("nana"));
2952 /// assert!(!bananas.contains("apples"));
2954 #[stable(feature = "rust1", since = "1.0.0")]
2956 pub fn contains<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool {
2957 pat.is_contained_in(self)
2960 /// Returns `true` if the given pattern matches a prefix of this
2963 /// Returns `false` if it does not.
2970 /// let bananas = "bananas";
2972 /// assert!(bananas.starts_with("bana"));
2973 /// assert!(!bananas.starts_with("nana"));
2975 #[stable(feature = "rust1", since = "1.0.0")]
2976 pub fn starts_with<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool {
2977 pat.is_prefix_of(self)
2980 /// Returns `true` if the given pattern matches a suffix of this
2983 /// Returns `false` if it does not.
2990 /// let bananas = "bananas";
2992 /// assert!(bananas.ends_with("anas"));
2993 /// assert!(!bananas.ends_with("nana"));
2995 #[stable(feature = "rust1", since = "1.0.0")]
2996 pub fn ends_with<'a, P>(&'a self, pat: P) -> bool
2998 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3000 pat.is_suffix_of(self)
3003 /// Returns the byte index of the first character of this string slice that
3004 /// matches the pattern.
3006 /// Returns [`None`] if the pattern doesn't match.
3008 /// The pattern can be a `&str`, [`char`], or a closure that determines if
3009 /// a character matches.
3011 /// [`None`]: option/enum.Option.html#variant.None
3015 /// Simple patterns:
3018 /// let s = "Löwe 老虎 Léopard";
3020 /// assert_eq!(s.find('L'), Some(0));
3021 /// assert_eq!(s.find('é'), Some(14));
3022 /// assert_eq!(s.find("Léopard"), Some(13));
3025 /// More complex patterns using point-free style and closures:
3028 /// let s = "Löwe 老虎 Léopard";
3030 /// assert_eq!(s.find(char::is_whitespace), Some(5));
3031 /// assert_eq!(s.find(char::is_lowercase), Some(1));
3032 /// assert_eq!(s.find(|c: char| c.is_whitespace() || c.is_lowercase()), Some(1));
3033 /// assert_eq!(s.find(|c: char| (c < 'o') && (c > 'a')), Some(4));
3036 /// Not finding the pattern:
3039 /// let s = "Löwe 老虎 Léopard";
3040 /// let x: &[_] = &['1', '2'];
3042 /// assert_eq!(s.find(x), None);
3044 #[stable(feature = "rust1", since = "1.0.0")]
3046 pub fn find<'a, P: Pattern<'a>>(&'a self, pat: P) -> Option<usize> {
3047 pat.into_searcher(self).next_match().map(|(i, _)| i)
3050 /// Returns the byte index of the last character of this string slice that
3051 /// matches the pattern.
3053 /// Returns [`None`] if the pattern doesn't match.
3055 /// The pattern can be a `&str`, [`char`], or a closure that determines if
3056 /// a character matches.
3058 /// [`None`]: option/enum.Option.html#variant.None
3062 /// Simple patterns:
3065 /// let s = "Löwe 老虎 Léopard";
3067 /// assert_eq!(s.rfind('L'), Some(13));
3068 /// assert_eq!(s.rfind('é'), Some(14));
3071 /// More complex patterns with closures:
3074 /// let s = "Löwe 老虎 Léopard";
3076 /// assert_eq!(s.rfind(char::is_whitespace), Some(12));
3077 /// assert_eq!(s.rfind(char::is_lowercase), Some(20));
3080 /// Not finding the pattern:
3083 /// let s = "Löwe 老虎 Léopard";
3084 /// let x: &[_] = &['1', '2'];
3086 /// assert_eq!(s.rfind(x), None);
3088 #[stable(feature = "rust1", since = "1.0.0")]
3090 pub fn rfind<'a, P>(&'a self, pat: P) -> Option<usize>
3092 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3094 pat.into_searcher(self).next_match_back().map(|(i, _)| i)
3097 /// An iterator over substrings of this string slice, separated by
3098 /// characters matched by a pattern.
3100 /// The pattern can be any type that implements the Pattern trait. Notable
3101 /// examples are `&str`, [`char`], and closures that determines the split.
3103 /// # Iterator behavior
3105 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3106 /// allows a reverse search and forward/reverse search yields the same
3107 /// elements. This is true for, e.g., [`char`], but not for `&str`.
3109 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3111 /// If the pattern allows a reverse search but its results might differ
3112 /// from a forward search, the [`rsplit`] method can be used.
3114 /// [`rsplit`]: #method.rsplit
3118 /// Simple patterns:
3121 /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
3122 /// assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);
3124 /// let v: Vec<&str> = "".split('X').collect();
3125 /// assert_eq!(v, [""]);
3127 /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
3128 /// assert_eq!(v, ["lion", "", "tiger", "leopard"]);
3130 /// let v: Vec<&str> = "lion::tiger::leopard".split("::").collect();
3131 /// assert_eq!(v, ["lion", "tiger", "leopard"]);
3133 /// let v: Vec<&str> = "abc1def2ghi".split(char::is_numeric).collect();
3134 /// assert_eq!(v, ["abc", "def", "ghi"]);
3136 /// let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect();
3137 /// assert_eq!(v, ["lion", "tiger", "leopard"]);
3140 /// A more complex pattern, using a closure:
3143 /// let v: Vec<&str> = "abc1defXghi".split(|c| c == '1' || c == 'X').collect();
3144 /// assert_eq!(v, ["abc", "def", "ghi"]);
3147 /// If a string contains multiple contiguous separators, you will end up
3148 /// with empty strings in the output:
3151 /// let x = "||||a||b|c".to_string();
3152 /// let d: Vec<_> = x.split('|').collect();
3154 /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
3157 /// Contiguous separators are separated by the empty string.
3160 /// let x = "(///)".to_string();
3161 /// let d: Vec<_> = x.split('/').collect();
3163 /// assert_eq!(d, &["(", "", "", ")"]);
3166 /// Separators at the start or end of a string are neighbored
3167 /// by empty strings.
3170 /// let d: Vec<_> = "010".split("0").collect();
3171 /// assert_eq!(d, &["", "1", ""]);
3174 /// When the empty string is used as a separator, it separates
3175 /// every character in the string, along with the beginning
3176 /// and end of the string.
3179 /// let f: Vec<_> = "rust".split("").collect();
3180 /// assert_eq!(f, &["", "r", "u", "s", "t", ""]);
3183 /// Contiguous separators can lead to possibly surprising behavior
3184 /// when whitespace is used as the separator. This code is correct:
3187 /// let x = " a b c".to_string();
3188 /// let d: Vec<_> = x.split(' ').collect();
3190 /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
3193 /// It does _not_ give you:
3196 /// assert_eq!(d, &["a", "b", "c"]);
3199 /// Use [`split_whitespace`] for this behavior.
3201 /// [`split_whitespace`]: #method.split_whitespace
3202 #[stable(feature = "rust1", since = "1.0.0")]
3204 pub fn split<'a, P: Pattern<'a>>(&'a self, pat: P) -> Split<'a, P> {
3205 Split(SplitInternal {
3208 matcher: pat.into_searcher(self),
3209 allow_trailing_empty: true,
3214 /// An iterator over substrings of the given string slice, separated by
3215 /// characters matched by a pattern and yielded in reverse order.
3217 /// The pattern can be any type that implements the Pattern trait. Notable
3218 /// examples are `&str`, [`char`], and closures that determines the split.
3220 /// # Iterator behavior
3222 /// The returned iterator requires that the pattern supports a reverse
3223 /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
3224 /// search yields the same elements.
3226 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3228 /// For iterating from the front, the [`split`] method can be used.
3230 /// [`split`]: #method.split
3234 /// Simple patterns:
3237 /// let v: Vec<&str> = "Mary had a little lamb".rsplit(' ').collect();
3238 /// assert_eq!(v, ["lamb", "little", "a", "had", "Mary"]);
3240 /// let v: Vec<&str> = "".rsplit('X').collect();
3241 /// assert_eq!(v, [""]);
3243 /// let v: Vec<&str> = "lionXXtigerXleopard".rsplit('X').collect();
3244 /// assert_eq!(v, ["leopard", "tiger", "", "lion"]);
3246 /// let v: Vec<&str> = "lion::tiger::leopard".rsplit("::").collect();
3247 /// assert_eq!(v, ["leopard", "tiger", "lion"]);
3250 /// A more complex pattern, using a closure:
3253 /// let v: Vec<&str> = "abc1defXghi".rsplit(|c| c == '1' || c == 'X').collect();
3254 /// assert_eq!(v, ["ghi", "def", "abc"]);
3256 #[stable(feature = "rust1", since = "1.0.0")]
3258 pub fn rsplit<'a, P>(&'a self, pat: P) -> RSplit<'a, P>
3260 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3262 RSplit(self.split(pat).0)
3265 /// An iterator over substrings of the given string slice, separated by
3266 /// characters matched by a pattern.
3268 /// The pattern can be any type that implements the Pattern trait. Notable
3269 /// examples are `&str`, [`char`], and closures that determines the split.
3271 /// Equivalent to [`split`], except that the trailing substring
3272 /// is skipped if empty.
3274 /// [`split`]: #method.split
3276 /// This method can be used for string data that is _terminated_,
3277 /// rather than _separated_ by a pattern.
3279 /// # Iterator behavior
3281 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3282 /// allows a reverse search and forward/reverse search yields the same
3283 /// elements. This is true for, e.g., [`char`], but not for `&str`.
3285 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3287 /// If the pattern allows a reverse search but its results might differ
3288 /// from a forward search, the [`rsplit_terminator`] method can be used.
3290 /// [`rsplit_terminator`]: #method.rsplit_terminator
3297 /// let v: Vec<&str> = "A.B.".split_terminator('.').collect();
3298 /// assert_eq!(v, ["A", "B"]);
3300 /// let v: Vec<&str> = "A..B..".split_terminator(".").collect();
3301 /// assert_eq!(v, ["A", "", "B", ""]);
3303 #[stable(feature = "rust1", since = "1.0.0")]
3305 pub fn split_terminator<'a, P: Pattern<'a>>(&'a self, pat: P) -> SplitTerminator<'a, P> {
3306 SplitTerminator(SplitInternal { allow_trailing_empty: false, ..self.split(pat).0 })
3309 /// An iterator over substrings of `self`, separated by characters
3310 /// matched by a pattern and yielded in reverse order.
3312 /// The pattern can be any type that implements the Pattern trait. Notable
3313 /// examples are `&str`, [`char`], and closures that determines the split.
3314 /// Additional libraries might provide more complex patterns like
3315 /// regular expressions.
3317 /// Equivalent to [`split`], except that the trailing substring is
3318 /// skipped if empty.
3320 /// [`split`]: #method.split
3322 /// This method can be used for string data that is _terminated_,
3323 /// rather than _separated_ by a pattern.
3325 /// # Iterator behavior
3327 /// The returned iterator requires that the pattern supports a
3328 /// reverse search, and it will be double ended if a forward/reverse
3329 /// search yields the same elements.
3331 /// For iterating from the front, the [`split_terminator`] method can be
3334 /// [`split_terminator`]: #method.split_terminator
3339 /// let v: Vec<&str> = "A.B.".rsplit_terminator('.').collect();
3340 /// assert_eq!(v, ["B", "A"]);
3342 /// let v: Vec<&str> = "A..B..".rsplit_terminator(".").collect();
3343 /// assert_eq!(v, ["", "B", "", "A"]);
3345 #[stable(feature = "rust1", since = "1.0.0")]
3347 pub fn rsplit_terminator<'a, P>(&'a self, pat: P) -> RSplitTerminator<'a, P>
3349 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3351 RSplitTerminator(self.split_terminator(pat).0)
3354 /// An iterator over substrings of the given string slice, separated by a
3355 /// pattern, restricted to returning at most `n` items.
3357 /// If `n` substrings are returned, the last substring (the `n`th substring)
3358 /// will contain the remainder of the string.
3360 /// The pattern can be any type that implements the Pattern trait. Notable
3361 /// examples are `&str`, [`char`], and closures that determines the split.
3363 /// # Iterator behavior
3365 /// The returned iterator will not be double ended, because it is
3366 /// not efficient to support.
3368 /// If the pattern allows a reverse search, the [`rsplitn`] method can be
3371 /// [`rsplitn`]: #method.rsplitn
3375 /// Simple patterns:
3378 /// let v: Vec<&str> = "Mary had a little lambda".splitn(3, ' ').collect();
3379 /// assert_eq!(v, ["Mary", "had", "a little lambda"]);
3381 /// let v: Vec<&str> = "lionXXtigerXleopard".splitn(3, "X").collect();
3382 /// assert_eq!(v, ["lion", "", "tigerXleopard"]);
3384 /// let v: Vec<&str> = "abcXdef".splitn(1, 'X').collect();
3385 /// assert_eq!(v, ["abcXdef"]);
3387 /// let v: Vec<&str> = "".splitn(1, 'X').collect();
3388 /// assert_eq!(v, [""]);
3391 /// A more complex pattern, using a closure:
3394 /// let v: Vec<&str> = "abc1defXghi".splitn(2, |c| c == '1' || c == 'X').collect();
3395 /// assert_eq!(v, ["abc", "defXghi"]);
3397 #[stable(feature = "rust1", since = "1.0.0")]
3399 pub fn splitn<'a, P: Pattern<'a>>(&'a self, n: usize, pat: P) -> SplitN<'a, P> {
3400 SplitN(SplitNInternal { iter: self.split(pat).0, count: n })
3403 /// An iterator over substrings of this string slice, separated by a
3404 /// pattern, starting from the end of the string, restricted to returning
3405 /// at most `n` items.
3407 /// If `n` substrings are returned, the last substring (the `n`th substring)
3408 /// will contain the remainder of the string.
3410 /// The pattern can be any type that implements the Pattern trait. Notable
3411 /// examples are `&str`, [`char`], and closures that determines the split.
3413 /// # Iterator behavior
3415 /// The returned iterator will not be double ended, because it is not
3416 /// efficient to support.
3418 /// For splitting from the front, the [`splitn`] method can be used.
3420 /// [`splitn`]: #method.splitn
3424 /// Simple patterns:
3427 /// let v: Vec<&str> = "Mary had a little lamb".rsplitn(3, ' ').collect();
3428 /// assert_eq!(v, ["lamb", "little", "Mary had a"]);
3430 /// let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(3, 'X').collect();
3431 /// assert_eq!(v, ["leopard", "tiger", "lionX"]);
3433 /// let v: Vec<&str> = "lion::tiger::leopard".rsplitn(2, "::").collect();
3434 /// assert_eq!(v, ["leopard", "lion::tiger"]);
3437 /// A more complex pattern, using a closure:
3440 /// let v: Vec<&str> = "abc1defXghi".rsplitn(2, |c| c == '1' || c == 'X').collect();
3441 /// assert_eq!(v, ["ghi", "abc1def"]);
3443 #[stable(feature = "rust1", since = "1.0.0")]
3445 pub fn rsplitn<'a, P>(&'a self, n: usize, pat: P) -> RSplitN<'a, P>
3447 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3449 RSplitN(self.splitn(n, pat).0)
3452 /// An iterator over the disjoint matches of a pattern within the given string
3455 /// The pattern can be a `&str`, [`char`], or a closure that determines if
3456 /// a character matches.
3458 /// # Iterator behavior
3460 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3461 /// allows a reverse search and forward/reverse search yields the same
3462 /// elements. This is true for, e.g., [`char`], but not for `&str`.
3464 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3466 /// If the pattern allows a reverse search but its results might differ
3467 /// from a forward search, the [`rmatches`] method can be used.
3469 /// [`rmatches`]: #method.rmatches
3476 /// let v: Vec<&str> = "abcXXXabcYYYabc".matches("abc").collect();
3477 /// assert_eq!(v, ["abc", "abc", "abc"]);
3479 /// let v: Vec<&str> = "1abc2abc3".matches(char::is_numeric).collect();
3480 /// assert_eq!(v, ["1", "2", "3"]);
3482 #[stable(feature = "str_matches", since = "1.2.0")]
3484 pub fn matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> Matches<'a, P> {
3485 Matches(MatchesInternal(pat.into_searcher(self)))
3488 /// An iterator over the disjoint matches of a pattern within this string slice,
3489 /// yielded in reverse order.
3491 /// The pattern can be a `&str`, [`char`], or a closure that determines if
3492 /// a character matches.
3494 /// # Iterator behavior
3496 /// The returned iterator requires that the pattern supports a reverse
3497 /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
3498 /// search yields the same elements.
3500 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3502 /// For iterating from the front, the [`matches`] method can be used.
3504 /// [`matches`]: #method.matches
3511 /// let v: Vec<&str> = "abcXXXabcYYYabc".rmatches("abc").collect();
3512 /// assert_eq!(v, ["abc", "abc", "abc"]);
3514 /// let v: Vec<&str> = "1abc2abc3".rmatches(char::is_numeric).collect();
3515 /// assert_eq!(v, ["3", "2", "1"]);
3517 #[stable(feature = "str_matches", since = "1.2.0")]
3519 pub fn rmatches<'a, P>(&'a self, pat: P) -> RMatches<'a, P>
3521 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3523 RMatches(self.matches(pat).0)
3526 /// An iterator over the disjoint matches of a pattern within this string
3527 /// slice as well as the index that the match starts at.
3529 /// For matches of `pat` within `self` that overlap, only the indices
3530 /// corresponding to the first match are returned.
3532 /// The pattern can be a `&str`, [`char`], or a closure that determines
3533 /// if a character matches.
3535 /// # Iterator behavior
3537 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3538 /// allows a reverse search and forward/reverse search yields the same
3539 /// elements. This is true for, e.g., [`char`], but not for `&str`.
3541 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3543 /// If the pattern allows a reverse search but its results might differ
3544 /// from a forward search, the [`rmatch_indices`] method can be used.
3546 /// [`rmatch_indices`]: #method.rmatch_indices
3553 /// let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
3554 /// assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
3556 /// let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
3557 /// assert_eq!(v, [(1, "abc"), (4, "abc")]);
3559 /// let v: Vec<_> = "ababa".match_indices("aba").collect();
3560 /// assert_eq!(v, [(0, "aba")]); // only the first `aba`
3562 #[stable(feature = "str_match_indices", since = "1.5.0")]
3564 pub fn match_indices<'a, P: Pattern<'a>>(&'a self, pat: P) -> MatchIndices<'a, P> {
3565 MatchIndices(MatchIndicesInternal(pat.into_searcher(self)))
3568 /// An iterator over the disjoint matches of a pattern within `self`,
3569 /// yielded in reverse order along with the index of the match.
3571 /// For matches of `pat` within `self` that overlap, only the indices
3572 /// corresponding to the last match are returned.
3574 /// The pattern can be a `&str`, [`char`], or a closure that determines if a
3575 /// character matches.
3577 /// # Iterator behavior
3579 /// The returned iterator requires that the pattern supports a reverse
3580 /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
3581 /// search yields the same elements.
3583 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3585 /// For iterating from the front, the [`match_indices`] method can be used.
3587 /// [`match_indices`]: #method.match_indices
3594 /// let v: Vec<_> = "abcXXXabcYYYabc".rmatch_indices("abc").collect();
3595 /// assert_eq!(v, [(12, "abc"), (6, "abc"), (0, "abc")]);
3597 /// let v: Vec<_> = "1abcabc2".rmatch_indices("abc").collect();
3598 /// assert_eq!(v, [(4, "abc"), (1, "abc")]);
3600 /// let v: Vec<_> = "ababa".rmatch_indices("aba").collect();
3601 /// assert_eq!(v, [(2, "aba")]); // only the last `aba`
3603 #[stable(feature = "str_match_indices", since = "1.5.0")]
3605 pub fn rmatch_indices<'a, P>(&'a self, pat: P) -> RMatchIndices<'a, P>
3607 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3609 RMatchIndices(self.match_indices(pat).0)
3612 /// Returns a string slice with leading and trailing whitespace removed.
3614 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3615 /// Core Property `White_Space`.
3622 /// let s = " Hello\tworld\t";
3624 /// assert_eq!("Hello\tworld", s.trim());
3626 #[must_use = "this returns the trimmed string as a slice, \
3627 without modifying the original"]
3628 #[stable(feature = "rust1", since = "1.0.0")]
3629 pub fn trim(&self) -> &str {
3630 self.trim_matches(|c: char| c.is_whitespace())
3633 /// Returns a string slice with leading whitespace removed.
3635 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3636 /// Core Property `White_Space`.
3638 /// # Text directionality
3640 /// A string is a sequence of bytes. `start` in this context means the first
3641 /// position of that byte string; for a left-to-right language like English or
3642 /// Russian, this will be left side, and for right-to-left languages like
3643 /// Arabic or Hebrew, this will be the right side.
3650 /// let s = " Hello\tworld\t";
3651 /// assert_eq!("Hello\tworld\t", s.trim_start());
3657 /// let s = " English ";
3658 /// assert!(Some('E') == s.trim_start().chars().next());
3660 /// let s = " עברית ";
3661 /// assert!(Some('ע') == s.trim_start().chars().next());
3663 #[must_use = "this returns the trimmed string as a new slice, \
3664 without modifying the original"]
3665 #[stable(feature = "trim_direction", since = "1.30.0")]
3666 pub fn trim_start(&self) -> &str {
3667 self.trim_start_matches(|c: char| c.is_whitespace())
3670 /// Returns a string slice with trailing whitespace removed.
3672 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3673 /// Core Property `White_Space`.
3675 /// # Text directionality
3677 /// A string is a sequence of bytes. `end` in this context means the last
3678 /// position of that byte string; for a left-to-right language like English or
3679 /// Russian, this will be right side, and for right-to-left languages like
3680 /// Arabic or Hebrew, this will be the left side.
3687 /// let s = " Hello\tworld\t";
3688 /// assert_eq!(" Hello\tworld", s.trim_end());
3694 /// let s = " English ";
3695 /// assert!(Some('h') == s.trim_end().chars().rev().next());
3697 /// let s = " עברית ";
3698 /// assert!(Some('ת') == s.trim_end().chars().rev().next());
3700 #[must_use = "this returns the trimmed string as a new slice, \
3701 without modifying the original"]
3702 #[stable(feature = "trim_direction", since = "1.30.0")]
3703 pub fn trim_end(&self) -> &str {
3704 self.trim_end_matches(|c: char| c.is_whitespace())
3707 /// Returns a string slice with leading whitespace removed.
3709 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3710 /// Core Property `White_Space`.
3712 /// # Text directionality
3714 /// A string is a sequence of bytes. 'Left' in this context means the first
3715 /// position of that byte string; for a language like Arabic or Hebrew
3716 /// which are 'right to left' rather than 'left to right', this will be
3717 /// the _right_ side, not the left.
3724 /// let s = " Hello\tworld\t";
3726 /// assert_eq!("Hello\tworld\t", s.trim_left());
3732 /// let s = " English";
3733 /// assert!(Some('E') == s.trim_left().chars().next());
3735 /// let s = " עברית";
3736 /// assert!(Some('ע') == s.trim_left().chars().next());
3738 #[stable(feature = "rust1", since = "1.0.0")]
3741 reason = "superseded by `trim_start`",
3742 suggestion = "trim_start"
3744 pub fn trim_left(&self) -> &str {
3748 /// Returns a string slice with trailing whitespace removed.
3750 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3751 /// Core Property `White_Space`.
3753 /// # Text directionality
3755 /// A string is a sequence of bytes. 'Right' in this context means the last
3756 /// position of that byte string; for a language like Arabic or Hebrew
3757 /// which are 'right to left' rather than 'left to right', this will be
3758 /// the _left_ side, not the right.
3765 /// let s = " Hello\tworld\t";
3767 /// assert_eq!(" Hello\tworld", s.trim_right());
3773 /// let s = "English ";
3774 /// assert!(Some('h') == s.trim_right().chars().rev().next());
3776 /// let s = "עברית ";
3777 /// assert!(Some('ת') == s.trim_right().chars().rev().next());
3779 #[stable(feature = "rust1", since = "1.0.0")]
3782 reason = "superseded by `trim_end`",
3783 suggestion = "trim_end"
3785 pub fn trim_right(&self) -> &str {
3789 /// Returns a string slice with all prefixes and suffixes that match a
3790 /// pattern repeatedly removed.
3792 /// The pattern can be a [`char`] or a closure that determines if a
3793 /// character matches.
3797 /// Simple patterns:
3800 /// assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar");
3801 /// assert_eq!("123foo1bar123".trim_matches(char::is_numeric), "foo1bar");
3803 /// let x: &[_] = &['1', '2'];
3804 /// assert_eq!("12foo1bar12".trim_matches(x), "foo1bar");
3807 /// A more complex pattern, using a closure:
3810 /// assert_eq!("1foo1barXX".trim_matches(|c| c == '1' || c == 'X'), "foo1bar");
3812 #[must_use = "this returns the trimmed string as a new slice, \
3813 without modifying the original"]
3814 #[stable(feature = "rust1", since = "1.0.0")]
3815 pub fn trim_matches<'a, P>(&'a self, pat: P) -> &'a str
3817 P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>,
3821 let mut matcher = pat.into_searcher(self);
3822 if let Some((a, b)) = matcher.next_reject() {
3824 j = b; // Remember earliest known match, correct it below if
3825 // last match is different
3827 if let Some((_, b)) = matcher.next_reject_back() {
3830 // SAFETY: `Searcher` is known to return valid indices
3832 self.get_unchecked(i..j)
3836 /// Returns a string slice with all prefixes that match a pattern
3837 /// repeatedly removed.
3839 /// The pattern can be a `&str`, [`char`], or a closure that determines if
3840 /// a character matches.
3842 /// # Text directionality
3844 /// A string is a sequence of bytes. `start` in this context means the first
3845 /// position of that byte string; for a left-to-right language like English or
3846 /// Russian, this will be left side, and for right-to-left languages like
3847 /// Arabic or Hebrew, this will be the right side.
3854 /// assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11");
3855 /// assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric), "foo1bar123");
3857 /// let x: &[_] = &['1', '2'];
3858 /// assert_eq!("12foo1bar12".trim_start_matches(x), "foo1bar12");
3860 #[must_use = "this returns the trimmed string as a new slice, \
3861 without modifying the original"]
3862 #[stable(feature = "trim_direction", since = "1.30.0")]
3863 pub fn trim_start_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str {
3864 let mut i = self.len();
3865 let mut matcher = pat.into_searcher(self);
3866 if let Some((a, _)) = matcher.next_reject() {
3869 // SAFETY: `Searcher` is known to return valid indices
3871 self.get_unchecked(i..self.len())
3875 /// Returns a string slice with the prefix removed.
3877 /// If the string starts with the pattern `prefix`, `Some` is returned with the substring where
3878 /// the prefix is removed. Unlike `trim_start_matches`, this method removes the prefix exactly
3881 /// If the string does not start with `prefix`, `None` is returned.
3886 /// #![feature(str_strip)]
3888 /// assert_eq!("foobar".strip_prefix("foo"), Some("bar"));
3889 /// assert_eq!("foobar".strip_prefix("bar"), None);
3890 /// assert_eq!("foofoo".strip_prefix("foo"), Some("foo"));
3892 #[must_use = "this returns the remaining substring as a new slice, \
3893 without modifying the original"]
3894 #[unstable(feature = "str_strip", reason = "newly added", issue = "67302")]
3895 pub fn strip_prefix<'a, P: Pattern<'a>>(&'a self, prefix: P) -> Option<&'a str> {
3896 let mut matcher = prefix.into_searcher(self);
3897 if let SearchStep::Match(start, len) = matcher.next() {
3900 "The first search step from Searcher \
3901 must include the first character"
3904 // Searcher is known to return valid indices.
3905 Some(self.get_unchecked(len..))
3912 /// Returns a string slice with the suffix removed.
3914 /// If the string ends with the pattern `suffix`, `Some` is returned with the substring where
3915 /// the suffix is removed. Unlike `trim_end_matches`, this method removes the suffix exactly
3918 /// If the string does not end with `suffix`, `None` is returned.
3923 /// #![feature(str_strip)]
3924 /// assert_eq!("barfoo".strip_suffix("foo"), Some("bar"));
3925 /// assert_eq!("barfoo".strip_suffix("bar"), None);
3926 /// assert_eq!("foofoo".strip_suffix("foo"), Some("foo"));
3928 #[must_use = "this returns the remaining substring as a new slice, \
3929 without modifying the original"]
3930 #[unstable(feature = "str_strip", reason = "newly added", issue = "67302")]
3931 pub fn strip_suffix<'a, P>(&'a self, suffix: P) -> Option<&'a str>
3934 <P as Pattern<'a>>::Searcher: ReverseSearcher<'a>,
3936 let mut matcher = suffix.into_searcher(self);
3937 if let SearchStep::Match(start, end) = matcher.next_back() {
3941 "The first search step from ReverseSearcher \
3942 must include the last character"
3945 // Searcher is known to return valid indices.
3946 Some(self.get_unchecked(..start))
3953 /// Returns a string slice with all suffixes that match a pattern
3954 /// repeatedly removed.
3956 /// The pattern can be a `&str`, [`char`], or a closure that
3957 /// determines if a character matches.
3959 /// # Text directionality
3961 /// A string is a sequence of bytes. `end` in this context means the last
3962 /// position of that byte string; for a left-to-right language like English or
3963 /// Russian, this will be right side, and for right-to-left languages like
3964 /// Arabic or Hebrew, this will be the left side.
3968 /// Simple patterns:
3971 /// assert_eq!("11foo1bar11".trim_end_matches('1'), "11foo1bar");
3972 /// assert_eq!("123foo1bar123".trim_end_matches(char::is_numeric), "123foo1bar");
3974 /// let x: &[_] = &['1', '2'];
3975 /// assert_eq!("12foo1bar12".trim_end_matches(x), "12foo1bar");
3978 /// A more complex pattern, using a closure:
3981 /// assert_eq!("1fooX".trim_end_matches(|c| c == '1' || c == 'X'), "1foo");
3983 #[must_use = "this returns the trimmed string as a new slice, \
3984 without modifying the original"]
3985 #[stable(feature = "trim_direction", since = "1.30.0")]
3986 pub fn trim_end_matches<'a, P>(&'a self, pat: P) -> &'a str
3988 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3991 let mut matcher = pat.into_searcher(self);
3992 if let Some((_, b)) = matcher.next_reject_back() {
3995 // SAFETY: `Searcher` is known to return valid indices
3997 self.get_unchecked(0..j)
4001 /// Returns a string slice with all prefixes that match a pattern
4002 /// repeatedly removed.
4004 /// The pattern can be a `&str`, [`char`], or a closure that determines if
4005 /// a character matches.
4007 /// [`char`]: primitive.char.html
4009 /// # Text directionality
4011 /// A string is a sequence of bytes. 'Left' in this context means the first
4012 /// position of that byte string; for a language like Arabic or Hebrew
4013 /// which are 'right to left' rather than 'left to right', this will be
4014 /// the _right_ side, not the left.
4021 /// assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11");
4022 /// assert_eq!("123foo1bar123".trim_left_matches(char::is_numeric), "foo1bar123");
4024 /// let x: &[_] = &['1', '2'];
4025 /// assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12");
4027 #[stable(feature = "rust1", since = "1.0.0")]
4030 reason = "superseded by `trim_start_matches`",
4031 suggestion = "trim_start_matches"
4033 pub fn trim_left_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str {
4034 self.trim_start_matches(pat)
4037 /// Returns a string slice with all suffixes that match a pattern
4038 /// repeatedly removed.
4040 /// The pattern can be a `&str`, [`char`], or a closure that
4041 /// determines if a character matches.
4043 /// [`char`]: primitive.char.html
4045 /// # Text directionality
4047 /// A string is a sequence of bytes. 'Right' in this context means the last
4048 /// position of that byte string; for a language like Arabic or Hebrew
4049 /// which are 'right to left' rather than 'left to right', this will be
4050 /// the _left_ side, not the right.
4054 /// Simple patterns:
4057 /// assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar");
4058 /// assert_eq!("123foo1bar123".trim_right_matches(char::is_numeric), "123foo1bar");
4060 /// let x: &[_] = &['1', '2'];
4061 /// assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar");
4064 /// A more complex pattern, using a closure:
4067 /// assert_eq!("1fooX".trim_right_matches(|c| c == '1' || c == 'X'), "1foo");
4069 #[stable(feature = "rust1", since = "1.0.0")]
4072 reason = "superseded by `trim_end_matches`",
4073 suggestion = "trim_end_matches"
4075 pub fn trim_right_matches<'a, P>(&'a self, pat: P) -> &'a str
4077 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
4079 self.trim_end_matches(pat)
4082 /// Parses this string slice into another type.
4084 /// Because `parse` is so general, it can cause problems with type
4085 /// inference. As such, `parse` is one of the few times you'll see
4086 /// the syntax affectionately known as the 'turbofish': `::<>`. This
4087 /// helps the inference algorithm understand specifically which type
4088 /// you're trying to parse into.
4090 /// `parse` can parse any type that implements the [`FromStr`] trait.
4092 /// [`FromStr`]: str/trait.FromStr.html
4096 /// Will return [`Err`] if it's not possible to parse this string slice into
4097 /// the desired type.
4099 /// [`Err`]: str/trait.FromStr.html#associatedtype.Err
4106 /// let four: u32 = "4".parse().unwrap();
4108 /// assert_eq!(4, four);
4111 /// Using the 'turbofish' instead of annotating `four`:
4114 /// let four = "4".parse::<u32>();
4116 /// assert_eq!(Ok(4), four);
4119 /// Failing to parse:
4122 /// let nope = "j".parse::<u32>();
4124 /// assert!(nope.is_err());
4127 #[stable(feature = "rust1", since = "1.0.0")]
4128 pub fn parse<F: FromStr>(&self) -> Result<F, F::Err> {
4129 FromStr::from_str(self)
4132 /// Checks if all characters in this string are within the ASCII range.
4137 /// let ascii = "hello!\n";
4138 /// let non_ascii = "Grüße, Jürgen ❤";
4140 /// assert!(ascii.is_ascii());
4141 /// assert!(!non_ascii.is_ascii());
4143 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4145 pub fn is_ascii(&self) -> bool {
4146 // We can treat each byte as character here: all multibyte characters
4147 // start with a byte that is not in the ascii range, so we will stop
4149 self.bytes().all(|b| b.is_ascii())
4152 /// Checks that two strings are an ASCII case-insensitive match.
4154 /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
4155 /// but without allocating and copying temporaries.
4160 /// assert!("Ferris".eq_ignore_ascii_case("FERRIS"));
4161 /// assert!("Ferrös".eq_ignore_ascii_case("FERRöS"));
4162 /// assert!(!"Ferrös".eq_ignore_ascii_case("FERRÖS"));
4164 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4166 pub fn eq_ignore_ascii_case(&self, other: &str) -> bool {
4167 self.as_bytes().eq_ignore_ascii_case(other.as_bytes())
4170 /// Converts this string to its ASCII upper case equivalent in-place.
4172 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
4173 /// but non-ASCII letters are unchanged.
4175 /// To return a new uppercased value without modifying the existing one, use
4176 /// [`to_ascii_uppercase`].
4178 /// [`to_ascii_uppercase`]: #method.to_ascii_uppercase
4183 /// let mut s = String::from("Grüße, Jürgen ❤");
4185 /// s.make_ascii_uppercase();
4187 /// assert_eq!("GRüßE, JüRGEN ❤", s);
4189 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4190 pub fn make_ascii_uppercase(&mut self) {
4191 // SAFETY: safe because we transmute two types with the same layout
4192 let me = unsafe { self.as_bytes_mut() };
4193 me.make_ascii_uppercase()
4196 /// Converts this string to its ASCII lower case equivalent in-place.
4198 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
4199 /// but non-ASCII letters are unchanged.
4201 /// To return a new lowercased value without modifying the existing one, use
4202 /// [`to_ascii_lowercase`].
4204 /// [`to_ascii_lowercase`]: #method.to_ascii_lowercase
4209 /// let mut s = String::from("GRÜßE, JÜRGEN ❤");
4211 /// s.make_ascii_lowercase();
4213 /// assert_eq!("grÜße, jÜrgen ❤", s);
4215 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4216 pub fn make_ascii_lowercase(&mut self) {
4217 // SAFETY: safe because we transmute two types with the same layout
4218 let me = unsafe { self.as_bytes_mut() };
4219 me.make_ascii_lowercase()
4222 /// Return an iterator that escapes each char in `self` with [`char::escape_debug`].
4224 /// Note: only extended grapheme codepoints that begin the string will be
4227 /// [`char::escape_debug`]: ../std/primitive.char.html#method.escape_debug
4234 /// for c in "❤\n!".escape_debug() {
4235 /// print!("{}", c);
4240 /// Using `println!` directly:
4243 /// println!("{}", "❤\n!".escape_debug());
4247 /// Both are equivalent to:
4250 /// println!("❤\\n!");
4253 /// Using `to_string`:
4256 /// assert_eq!("❤\n!".escape_debug().to_string(), "❤\\n!");
4258 #[stable(feature = "str_escape", since = "1.34.0")]
4259 pub fn escape_debug(&self) -> EscapeDebug<'_> {
4260 let mut chars = self.chars();
4264 .map(|first| first.escape_debug_ext(true))
4267 .chain(chars.flat_map(CharEscapeDebugContinue)),
4271 /// Return an iterator that escapes each char in `self` with [`char::escape_default`].
4273 /// [`char::escape_default`]: ../std/primitive.char.html#method.escape_default
4280 /// for c in "❤\n!".escape_default() {
4281 /// print!("{}", c);
4286 /// Using `println!` directly:
4289 /// println!("{}", "❤\n!".escape_default());
4293 /// Both are equivalent to:
4296 /// println!("\\u{{2764}}\\n!");
4299 /// Using `to_string`:
4302 /// assert_eq!("❤\n!".escape_default().to_string(), "\\u{2764}\\n!");
4304 #[stable(feature = "str_escape", since = "1.34.0")]
4305 pub fn escape_default(&self) -> EscapeDefault<'_> {
4306 EscapeDefault { inner: self.chars().flat_map(CharEscapeDefault) }
4309 /// Return an iterator that escapes each char in `self` with [`char::escape_unicode`].
4311 /// [`char::escape_unicode`]: ../std/primitive.char.html#method.escape_unicode
4318 /// for c in "❤\n!".escape_unicode() {
4319 /// print!("{}", c);
4324 /// Using `println!` directly:
4327 /// println!("{}", "❤\n!".escape_unicode());
4331 /// Both are equivalent to:
4334 /// println!("\\u{{2764}}\\u{{a}}\\u{{21}}");
4337 /// Using `to_string`:
4340 /// assert_eq!("❤\n!".escape_unicode().to_string(), "\\u{2764}\\u{a}\\u{21}");
4342 #[stable(feature = "str_escape", since = "1.34.0")]
4343 pub fn escape_unicode(&self) -> EscapeUnicode<'_> {
4344 EscapeUnicode { inner: self.chars().flat_map(CharEscapeUnicode) }
4350 struct CharEscapeDebugContinue impl Fn = |c: char| -> char::EscapeDebug {
4351 c.escape_debug_ext(false)
4355 struct CharEscapeUnicode impl Fn = |c: char| -> char::EscapeUnicode {
4359 struct CharEscapeDefault impl Fn = |c: char| -> char::EscapeDefault {
4364 #[stable(feature = "rust1", since = "1.0.0")]
4365 impl AsRef<[u8]> for str {
4367 fn as_ref(&self) -> &[u8] {
4372 #[stable(feature = "rust1", since = "1.0.0")]
4373 impl Default for &str {
4374 /// Creates an empty str
4375 fn default() -> Self {
4380 #[stable(feature = "default_mut_str", since = "1.28.0")]
4381 impl Default for &mut str {
4382 /// Creates an empty mutable str
4383 // SAFETY: `str` is guranteed to be UTF-8
4384 fn default() -> Self {
4385 unsafe { from_utf8_unchecked_mut(&mut []) }
4389 /// An iterator over the non-whitespace substrings of a string,
4390 /// separated by any amount of whitespace.
4392 /// This struct is created by the [`split_whitespace`] method on [`str`].
4393 /// See its documentation for more.
4395 /// [`split_whitespace`]: ../../std/primitive.str.html#method.split_whitespace
4396 /// [`str`]: ../../std/primitive.str.html
4397 #[stable(feature = "split_whitespace", since = "1.1.0")]
4398 #[derive(Clone, Debug)]
4399 pub struct SplitWhitespace<'a> {
4400 inner: Filter<Split<'a, IsWhitespace>, IsNotEmpty>,
4403 /// An iterator over the non-ASCII-whitespace substrings of a string,
4404 /// separated by any amount of ASCII whitespace.
4406 /// This struct is created by the [`split_ascii_whitespace`] method on [`str`].
4407 /// See its documentation for more.
4409 /// [`split_ascii_whitespace`]: ../../std/primitive.str.html#method.split_ascii_whitespace
4410 /// [`str`]: ../../std/primitive.str.html
4411 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4412 #[derive(Clone, Debug)]
4413 pub struct SplitAsciiWhitespace<'a> {
4414 inner: Map<Filter<SliceSplit<'a, u8, IsAsciiWhitespace>, BytesIsNotEmpty>, UnsafeBytesToStr>,
4419 struct IsWhitespace impl Fn = |c: char| -> bool {
4424 struct IsAsciiWhitespace impl Fn = |byte: &u8| -> bool {
4425 byte.is_ascii_whitespace()
4429 struct IsNotEmpty impl<'a, 'b> Fn = |s: &'a &'b str| -> bool {
4434 struct BytesIsNotEmpty impl<'a, 'b> Fn = |s: &'a &'b [u8]| -> bool {
4439 struct UnsafeBytesToStr impl<'a> Fn = |bytes: &'a [u8]| -> &'a str {
4441 unsafe { from_utf8_unchecked(bytes) }
4445 #[stable(feature = "split_whitespace", since = "1.1.0")]
4446 impl<'a> Iterator for SplitWhitespace<'a> {
4447 type Item = &'a str;
4450 fn next(&mut self) -> Option<&'a str> {
4455 fn size_hint(&self) -> (usize, Option<usize>) {
4456 self.inner.size_hint()
4460 fn last(mut self) -> Option<&'a str> {
4465 #[stable(feature = "split_whitespace", since = "1.1.0")]
4466 impl<'a> DoubleEndedIterator for SplitWhitespace<'a> {
4468 fn next_back(&mut self) -> Option<&'a str> {
4469 self.inner.next_back()
4473 #[stable(feature = "fused", since = "1.26.0")]
4474 impl FusedIterator for SplitWhitespace<'_> {}
4476 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4477 impl<'a> Iterator for SplitAsciiWhitespace<'a> {
4478 type Item = &'a str;
4481 fn next(&mut self) -> Option<&'a str> {
4486 fn size_hint(&self) -> (usize, Option<usize>) {
4487 self.inner.size_hint()
4491 fn last(mut self) -> Option<&'a str> {
4496 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4497 impl<'a> DoubleEndedIterator for SplitAsciiWhitespace<'a> {
4499 fn next_back(&mut self) -> Option<&'a str> {
4500 self.inner.next_back()
4504 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4505 impl FusedIterator for SplitAsciiWhitespace<'_> {}
4507 /// An iterator of [`u16`] over the string encoded as UTF-16.
4509 /// [`u16`]: ../../std/primitive.u16.html
4511 /// This struct is created by the [`encode_utf16`] method on [`str`].
4512 /// See its documentation for more.
4514 /// [`encode_utf16`]: ../../std/primitive.str.html#method.encode_utf16
4515 /// [`str`]: ../../std/primitive.str.html
4517 #[stable(feature = "encode_utf16", since = "1.8.0")]
4518 pub struct EncodeUtf16<'a> {
4523 #[stable(feature = "collection_debug", since = "1.17.0")]
4524 impl fmt::Debug for EncodeUtf16<'_> {
4525 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
4526 f.pad("EncodeUtf16 { .. }")
4530 #[stable(feature = "encode_utf16", since = "1.8.0")]
4531 impl<'a> Iterator for EncodeUtf16<'a> {
4535 fn next(&mut self) -> Option<u16> {
4536 if self.extra != 0 {
4537 let tmp = self.extra;
4542 let mut buf = [0; 2];
4543 self.chars.next().map(|ch| {
4544 let n = ch.encode_utf16(&mut buf).len();
4546 self.extra = buf[1];
4553 fn size_hint(&self) -> (usize, Option<usize>) {
4554 let (low, high) = self.chars.size_hint();
4555 // every char gets either one u16 or two u16,
4556 // so this iterator is between 1 or 2 times as
4557 // long as the underlying iterator.
4558 (low, high.and_then(|n| n.checked_mul(2)))
4562 #[stable(feature = "fused", since = "1.26.0")]
4563 impl FusedIterator for EncodeUtf16<'_> {}
4565 /// The return type of [`str::escape_debug`].
4567 /// [`str::escape_debug`]: ../../std/primitive.str.html#method.escape_debug
4568 #[stable(feature = "str_escape", since = "1.34.0")]
4569 #[derive(Clone, Debug)]
4570 pub struct EscapeDebug<'a> {
4572 Flatten<option::IntoIter<char::EscapeDebug>>,
4573 FlatMap<Chars<'a>, char::EscapeDebug, CharEscapeDebugContinue>,
4577 /// The return type of [`str::escape_default`].
4579 /// [`str::escape_default`]: ../../std/primitive.str.html#method.escape_default
4580 #[stable(feature = "str_escape", since = "1.34.0")]
4581 #[derive(Clone, Debug)]
4582 pub struct EscapeDefault<'a> {
4583 inner: FlatMap<Chars<'a>, char::EscapeDefault, CharEscapeDefault>,
4586 /// The return type of [`str::escape_unicode`].
4588 /// [`str::escape_unicode`]: ../../std/primitive.str.html#method.escape_unicode
4589 #[stable(feature = "str_escape", since = "1.34.0")]
4590 #[derive(Clone, Debug)]
4591 pub struct EscapeUnicode<'a> {
4592 inner: FlatMap<Chars<'a>, char::EscapeUnicode, CharEscapeUnicode>,
4595 macro_rules! escape_types_impls {
4596 ($( $Name: ident ),+) => {$(
4597 #[stable(feature = "str_escape", since = "1.34.0")]
4598 impl<'a> fmt::Display for $Name<'a> {
4599 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
4600 self.clone().try_for_each(|c| f.write_char(c))
4604 #[stable(feature = "str_escape", since = "1.34.0")]
4605 impl<'a> Iterator for $Name<'a> {
4609 fn next(&mut self) -> Option<char> { self.inner.next() }
4612 fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
4615 fn try_fold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R where
4616 Self: Sized, Fold: FnMut(Acc, Self::Item) -> R, R: Try<Ok=Acc>
4618 self.inner.try_fold(init, fold)
4622 fn fold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc
4623 where Fold: FnMut(Acc, Self::Item) -> Acc,
4625 self.inner.fold(init, fold)
4629 #[stable(feature = "str_escape", since = "1.34.0")]
4630 impl<'a> FusedIterator for $Name<'a> {}
4634 escape_types_impls!(EscapeDebug, EscapeDefault, EscapeUnicode);