1 // ignore-tidy-filelength
2 // ignore-tidy-undocumented-unsafe
4 //! String manipulation.
6 //! For more details, see the `std::str` module.
8 #![stable(feature = "rust1", since = "1.0.0")]
10 use self::pattern::Pattern;
11 use self::pattern::{DoubleEndedSearcher, ReverseSearcher, SearchStep, Searcher};
14 use crate::fmt::{self, Write};
15 use crate::iter::{Chain, FlatMap, Flatten};
16 use crate::iter::{Cloned, Filter, FusedIterator, Map, TrustedLen, TrustedRandomAccess};
20 use crate::slice::{self, SliceIndex, Split as SliceSplit};
24 #[unstable(feature = "str_internals", issue = "none")]
25 #[allow(missing_docs)]
28 /// Parse a value from a string
30 /// `FromStr`'s [`from_str`] method is often used implicitly, through
31 /// [`str`]'s [`parse`] method. See [`parse`]'s documentation for examples.
33 /// [`from_str`]: #tymethod.from_str
34 /// [`str`]: ../../std/primitive.str.html
35 /// [`parse`]: ../../std/primitive.str.html#method.parse
37 /// `FromStr` does not have a lifetime parameter, and so you can only parse types
38 /// that do not contain a lifetime parameter themselves. In other words, you can
39 /// parse an `i32` with `FromStr`, but not a `&i32`. You can parse a struct that
40 /// contains an `i32`, but not one that contains an `&i32`.
44 /// Basic implementation of `FromStr` on an example `Point` type:
47 /// use std::str::FromStr;
48 /// use std::num::ParseIntError;
50 /// #[derive(Debug, PartialEq)]
56 /// impl FromStr for Point {
57 /// type Err = ParseIntError;
59 /// fn from_str(s: &str) -> Result<Self, Self::Err> {
60 /// let coords: Vec<&str> = s.trim_matches(|p| p == '(' || p == ')' )
64 /// let x_fromstr = coords[0].parse::<i32>()?;
65 /// let y_fromstr = coords[1].parse::<i32>()?;
67 /// Ok(Point { x: x_fromstr, y: y_fromstr })
71 /// let p = Point::from_str("(1,2)");
72 /// assert_eq!(p.unwrap(), Point{ x: 1, y: 2} )
74 #[stable(feature = "rust1", since = "1.0.0")]
75 pub trait FromStr: Sized {
76 /// The associated error which can be returned from parsing.
77 #[stable(feature = "rust1", since = "1.0.0")]
80 /// Parses a string `s` to return a value of this type.
82 /// If parsing succeeds, return the value inside [`Ok`], otherwise
83 /// when the string is ill-formatted return an error specific to the
84 /// inside [`Err`]. The error type is specific to implementation of the trait.
86 /// [`Ok`]: ../../std/result/enum.Result.html#variant.Ok
87 /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
91 /// Basic usage with [`i32`][ithirtytwo], a type that implements `FromStr`:
93 /// [ithirtytwo]: ../../std/primitive.i32.html
96 /// use std::str::FromStr;
99 /// let x = i32::from_str(s).unwrap();
101 /// assert_eq!(5, x);
103 #[stable(feature = "rust1", since = "1.0.0")]
104 fn from_str(s: &str) -> Result<Self, Self::Err>;
107 #[stable(feature = "rust1", since = "1.0.0")]
108 impl FromStr for bool {
109 type Err = ParseBoolError;
111 /// Parse a `bool` from a string.
113 /// Yields a `Result<bool, ParseBoolError>`, because `s` may or may not
114 /// actually be parseable.
119 /// use std::str::FromStr;
121 /// assert_eq!(FromStr::from_str("true"), Ok(true));
122 /// assert_eq!(FromStr::from_str("false"), Ok(false));
123 /// assert!(<bool as FromStr>::from_str("not even a boolean").is_err());
126 /// Note, in many cases, the `.parse()` method on `str` is more proper.
129 /// assert_eq!("true".parse(), Ok(true));
130 /// assert_eq!("false".parse(), Ok(false));
131 /// assert!("not even a boolean".parse::<bool>().is_err());
134 fn from_str(s: &str) -> Result<bool, ParseBoolError> {
137 "false" => Ok(false),
138 _ => Err(ParseBoolError { _priv: () }),
143 /// An error returned when parsing a `bool` using [`from_str`] fails
145 /// [`from_str`]: ../../std/primitive.bool.html#method.from_str
146 #[derive(Debug, Clone, PartialEq, Eq)]
147 #[stable(feature = "rust1", since = "1.0.0")]
148 pub struct ParseBoolError {
152 #[stable(feature = "rust1", since = "1.0.0")]
153 impl fmt::Display for ParseBoolError {
154 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
155 "provided string was not `true` or `false`".fmt(f)
160 Section: Creating a string
163 /// Errors which can occur when attempting to interpret a sequence of [`u8`]
166 /// [`u8`]: ../../std/primitive.u8.html
168 /// As such, the `from_utf8` family of functions and methods for both [`String`]s
169 /// and [`&str`]s make use of this error, for example.
171 /// [`String`]: ../../std/string/struct.String.html#method.from_utf8
172 /// [`&str`]: ../../std/str/fn.from_utf8.html
176 /// This error type’s methods can be used to create functionality
177 /// similar to `String::from_utf8_lossy` without allocating heap memory:
180 /// fn from_utf8_lossy<F>(mut input: &[u8], mut push: F) where F: FnMut(&str) {
182 /// match std::str::from_utf8(input) {
188 /// let (valid, after_valid) = input.split_at(error.valid_up_to());
190 /// push(std::str::from_utf8_unchecked(valid))
192 /// push("\u{FFFD}");
194 /// if let Some(invalid_sequence_length) = error.error_len() {
195 /// input = &after_valid[invalid_sequence_length..]
204 #[derive(Copy, Eq, PartialEq, Clone, Debug)]
205 #[stable(feature = "rust1", since = "1.0.0")]
206 pub struct Utf8Error {
208 error_len: Option<u8>,
212 /// Returns the index in the given string up to which valid UTF-8 was
215 /// It is the maximum index such that `from_utf8(&input[..index])`
216 /// would return `Ok(_)`.
225 /// // some invalid bytes, in a vector
226 /// let sparkle_heart = vec![0, 159, 146, 150];
228 /// // std::str::from_utf8 returns a Utf8Error
229 /// let error = str::from_utf8(&sparkle_heart).unwrap_err();
231 /// // the second byte is invalid here
232 /// assert_eq!(1, error.valid_up_to());
234 #[stable(feature = "utf8_error", since = "1.5.0")]
235 pub fn valid_up_to(&self) -> usize {
239 /// Provides more information about the failure:
241 /// * `None`: the end of the input was reached unexpectedly.
242 /// `self.valid_up_to()` is 1 to 3 bytes from the end of the input.
243 /// If a byte stream (such as a file or a network socket) is being decoded incrementally,
244 /// this could be a valid `char` whose UTF-8 byte sequence is spanning multiple chunks.
246 /// * `Some(len)`: an unexpected byte was encountered.
247 /// The length provided is that of the invalid byte sequence
248 /// that starts at the index given by `valid_up_to()`.
249 /// Decoding should resume after that sequence
250 /// (after inserting a [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD]) in case of
253 /// [U+FFFD]: ../../std/char/constant.REPLACEMENT_CHARACTER.html
254 #[stable(feature = "utf8_error_error_len", since = "1.20.0")]
255 pub fn error_len(&self) -> Option<usize> {
256 self.error_len.map(|len| len as usize)
260 /// Converts a slice of bytes to a string slice.
262 /// A string slice ([`&str`]) is made of bytes ([`u8`]), and a byte slice
263 /// ([`&[u8]`][byteslice]) is made of bytes, so this function converts between
264 /// the two. Not all byte slices are valid string slices, however: [`&str`] requires
265 /// that it is valid UTF-8. `from_utf8()` checks to ensure that the bytes are valid
266 /// UTF-8, and then does the conversion.
268 /// [`&str`]: ../../std/primitive.str.html
269 /// [`u8`]: ../../std/primitive.u8.html
270 /// [byteslice]: ../../std/primitive.slice.html
272 /// If you are sure that the byte slice is valid UTF-8, and you don't want to
273 /// incur the overhead of the validity check, there is an unsafe version of
274 /// this function, [`from_utf8_unchecked`][fromutf8u], which has the same
275 /// behavior but skips the check.
277 /// [fromutf8u]: fn.from_utf8_unchecked.html
279 /// If you need a `String` instead of a `&str`, consider
280 /// [`String::from_utf8`][string].
282 /// [string]: ../../std/string/struct.String.html#method.from_utf8
284 /// Because you can stack-allocate a `[u8; N]`, and you can take a
285 /// [`&[u8]`][byteslice] of it, this function is one way to have a
286 /// stack-allocated string. There is an example of this in the
287 /// examples section below.
289 /// [byteslice]: ../../std/primitive.slice.html
293 /// Returns `Err` if the slice is not UTF-8 with a description as to why the
294 /// provided slice is not UTF-8.
303 /// // some bytes, in a vector
304 /// let sparkle_heart = vec![240, 159, 146, 150];
306 /// // We know these bytes are valid, so just use `unwrap()`.
307 /// let sparkle_heart = str::from_utf8(&sparkle_heart).unwrap();
309 /// assert_eq!("💖", sparkle_heart);
317 /// // some invalid bytes, in a vector
318 /// let sparkle_heart = vec![0, 159, 146, 150];
320 /// assert!(str::from_utf8(&sparkle_heart).is_err());
323 /// See the docs for [`Utf8Error`][error] for more details on the kinds of
324 /// errors that can be returned.
326 /// [error]: struct.Utf8Error.html
328 /// A "stack allocated string":
333 /// // some bytes, in a stack-allocated array
334 /// let sparkle_heart = [240, 159, 146, 150];
336 /// // We know these bytes are valid, so just use `unwrap()`.
337 /// let sparkle_heart = str::from_utf8(&sparkle_heart).unwrap();
339 /// assert_eq!("💖", sparkle_heart);
341 #[stable(feature = "rust1", since = "1.0.0")]
342 pub fn from_utf8(v: &[u8]) -> Result<&str, Utf8Error> {
343 run_utf8_validation(v)?;
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 Ok(unsafe { from_utf8_unchecked_mut(v) })
385 /// Converts a slice of bytes to a string slice without checking
386 /// that the string contains valid UTF-8.
388 /// See the safe version, [`from_utf8`][fromutf8], for more information.
390 /// [fromutf8]: fn.from_utf8.html
394 /// This function is unsafe because it does not check that the bytes passed to
395 /// it are valid UTF-8. If this constraint is violated, undefined behavior
396 /// results, as the rest of Rust assumes that [`&str`]s are valid UTF-8.
398 /// [`&str`]: ../../std/primitive.str.html
407 /// // some bytes, in a vector
408 /// let sparkle_heart = vec![240, 159, 146, 150];
410 /// let sparkle_heart = unsafe {
411 /// str::from_utf8_unchecked(&sparkle_heart)
414 /// assert_eq!("💖", sparkle_heart);
417 #[stable(feature = "rust1", since = "1.0.0")]
418 pub unsafe fn from_utf8_unchecked(v: &[u8]) -> &str {
419 &*(v as *const [u8] as *const str)
422 /// Converts a slice of bytes to a string slice without checking
423 /// that the string contains valid UTF-8; mutable version.
425 /// See the immutable version, [`from_utf8_unchecked()`][fromutf8], for more information.
427 /// [fromutf8]: fn.from_utf8_unchecked.html
436 /// let mut heart = vec![240, 159, 146, 150];
437 /// let heart = unsafe { str::from_utf8_unchecked_mut(&mut heart) };
439 /// assert_eq!("💖", heart);
442 #[stable(feature = "str_mut_extras", since = "1.20.0")]
443 pub unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str {
444 &mut *(v as *mut [u8] as *mut str)
447 #[stable(feature = "rust1", since = "1.0.0")]
448 impl fmt::Display for Utf8Error {
449 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
450 if let Some(error_len) = self.error_len {
453 "invalid utf-8 sequence of {} bytes from index {}",
454 error_len, self.valid_up_to
457 write!(f, "incomplete utf-8 byte sequence from index {}", self.valid_up_to)
466 /// An iterator over the [`char`]s of a string slice.
468 /// [`char`]: ../../std/primitive.char.html
470 /// This struct is created by the [`chars`] method on [`str`].
471 /// See its documentation for more.
473 /// [`chars`]: ../../std/primitive.str.html#method.chars
474 /// [`str`]: ../../std/primitive.str.html
476 #[stable(feature = "rust1", since = "1.0.0")]
477 pub struct Chars<'a> {
478 iter: slice::Iter<'a, u8>,
481 /// Returns the initial codepoint accumulator for the first byte.
482 /// The first byte is special, only want bottom 5 bits for width 2, 4 bits
483 /// for width 3, and 3 bits for width 4.
485 fn utf8_first_byte(byte: u8, width: u32) -> u32 {
486 (byte & (0x7F >> width)) as u32
489 /// Returns the value of `ch` updated with continuation byte `byte`.
491 fn utf8_acc_cont_byte(ch: u32, byte: u8) -> u32 {
492 (ch << 6) | (byte & CONT_MASK) as u32
495 /// Checks whether the byte is a UTF-8 continuation byte (i.e., starts with the
498 fn utf8_is_cont_byte(byte: u8) -> bool {
499 (byte & !CONT_MASK) == TAG_CONT_U8
503 fn unwrap_or_0(opt: Option<&u8>) -> u8 {
510 /// Reads the next code point out of a byte iterator (assuming a
511 /// UTF-8-like encoding).
512 #[unstable(feature = "str_internals", issue = "none")]
514 pub fn next_code_point<'a, I: Iterator<Item = &'a u8>>(bytes: &mut I) -> Option<u32> {
516 let x = *bytes.next()?;
518 return Some(x as u32);
521 // Multibyte case follows
522 // Decode from a byte combination out of: [[[x y] z] w]
523 // NOTE: Performance is sensitive to the exact formulation here
524 let init = utf8_first_byte(x, 2);
525 let y = unwrap_or_0(bytes.next());
526 let mut ch = utf8_acc_cont_byte(init, y);
529 // 5th bit in 0xE0 .. 0xEF is always clear, so `init` is still valid
530 let z = unwrap_or_0(bytes.next());
531 let y_z = utf8_acc_cont_byte((y & CONT_MASK) as u32, z);
532 ch = init << 12 | y_z;
535 // use only the lower 3 bits of `init`
536 let w = unwrap_or_0(bytes.next());
537 ch = (init & 7) << 18 | utf8_acc_cont_byte(y_z, w);
544 /// Reads the last code point out of a byte iterator (assuming a
545 /// UTF-8-like encoding).
547 fn next_code_point_reverse<'a, I>(bytes: &mut I) -> Option<u32>
549 I: DoubleEndedIterator<Item = &'a u8>,
552 let w = match *bytes.next_back()? {
553 next_byte if next_byte < 128 => return Some(next_byte as u32),
554 back_byte => back_byte,
557 // Multibyte case follows
558 // Decode from a byte combination out of: [x [y [z w]]]
560 let z = unwrap_or_0(bytes.next_back());
561 ch = utf8_first_byte(z, 2);
562 if utf8_is_cont_byte(z) {
563 let y = unwrap_or_0(bytes.next_back());
564 ch = utf8_first_byte(y, 3);
565 if utf8_is_cont_byte(y) {
566 let x = unwrap_or_0(bytes.next_back());
567 ch = utf8_first_byte(x, 4);
568 ch = utf8_acc_cont_byte(ch, y);
570 ch = utf8_acc_cont_byte(ch, z);
572 ch = utf8_acc_cont_byte(ch, w);
577 #[stable(feature = "rust1", since = "1.0.0")]
578 impl<'a> Iterator for Chars<'a> {
582 fn next(&mut self) -> Option<char> {
583 next_code_point(&mut self.iter).map(|ch| {
584 // str invariant says `ch` is a valid Unicode Scalar Value
585 unsafe { char::from_u32_unchecked(ch) }
590 fn count(self) -> usize {
591 // length in `char` is equal to the number of non-continuation bytes
592 let bytes_len = self.iter.len();
593 let mut cont_bytes = 0;
594 for &byte in self.iter {
595 cont_bytes += utf8_is_cont_byte(byte) as usize;
597 bytes_len - cont_bytes
601 fn size_hint(&self) -> (usize, Option<usize>) {
602 let len = self.iter.len();
603 // `(len + 3)` can't overflow, because we know that the `slice::Iter`
604 // belongs to a slice in memory which has a maximum length of
605 // `isize::MAX` (that's well below `usize::MAX`).
606 ((len + 3) / 4, Some(len))
610 fn last(mut self) -> Option<char> {
611 // No need to go through the entire string.
616 #[stable(feature = "chars_debug_impl", since = "1.38.0")]
617 impl fmt::Debug for Chars<'_> {
618 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
619 write!(f, "Chars(")?;
620 f.debug_list().entries(self.clone()).finish()?;
626 #[stable(feature = "rust1", since = "1.0.0")]
627 impl<'a> DoubleEndedIterator for Chars<'a> {
629 fn next_back(&mut self) -> Option<char> {
630 next_code_point_reverse(&mut self.iter).map(|ch| {
631 // str invariant says `ch` is a valid Unicode Scalar Value
632 unsafe { char::from_u32_unchecked(ch) }
637 #[stable(feature = "fused", since = "1.26.0")]
638 impl FusedIterator for Chars<'_> {}
641 /// Views the underlying data as a subslice of the original data.
643 /// This has the same lifetime as the original slice, and so the
644 /// iterator can continue to be used while this exists.
649 /// let mut chars = "abc".chars();
651 /// assert_eq!(chars.as_str(), "abc");
653 /// assert_eq!(chars.as_str(), "bc");
656 /// assert_eq!(chars.as_str(), "");
658 #[stable(feature = "iter_to_slice", since = "1.4.0")]
660 pub fn as_str(&self) -> &'a str {
661 unsafe { from_utf8_unchecked(self.iter.as_slice()) }
665 /// An iterator over the [`char`]s of a string slice, and their positions.
667 /// [`char`]: ../../std/primitive.char.html
669 /// This struct is created by the [`char_indices`] method on [`str`].
670 /// See its documentation for more.
672 /// [`char_indices`]: ../../std/primitive.str.html#method.char_indices
673 /// [`str`]: ../../std/primitive.str.html
674 #[derive(Clone, Debug)]
675 #[stable(feature = "rust1", since = "1.0.0")]
676 pub struct CharIndices<'a> {
681 #[stable(feature = "rust1", since = "1.0.0")]
682 impl<'a> Iterator for CharIndices<'a> {
683 type Item = (usize, char);
686 fn next(&mut self) -> Option<(usize, char)> {
687 let pre_len = self.iter.iter.len();
688 match self.iter.next() {
691 let index = self.front_offset;
692 let len = self.iter.iter.len();
693 self.front_offset += pre_len - len;
700 fn count(self) -> usize {
705 fn size_hint(&self) -> (usize, Option<usize>) {
706 self.iter.size_hint()
710 fn last(mut self) -> Option<(usize, char)> {
711 // No need to go through the entire string.
716 #[stable(feature = "rust1", since = "1.0.0")]
717 impl<'a> DoubleEndedIterator for CharIndices<'a> {
719 fn next_back(&mut self) -> Option<(usize, char)> {
720 self.iter.next_back().map(|ch| {
721 let index = self.front_offset + self.iter.iter.len();
727 #[stable(feature = "fused", since = "1.26.0")]
728 impl FusedIterator for CharIndices<'_> {}
730 impl<'a> CharIndices<'a> {
731 /// Views the underlying data as a subslice of the original data.
733 /// This has the same lifetime as the original slice, and so the
734 /// iterator can continue to be used while this exists.
735 #[stable(feature = "iter_to_slice", since = "1.4.0")]
737 pub fn as_str(&self) -> &'a str {
742 /// An iterator over the bytes of a string slice.
744 /// This struct is created by the [`bytes`] method on [`str`].
745 /// See its documentation for more.
747 /// [`bytes`]: ../../std/primitive.str.html#method.bytes
748 /// [`str`]: ../../std/primitive.str.html
749 #[stable(feature = "rust1", since = "1.0.0")]
750 #[derive(Clone, Debug)]
751 pub struct Bytes<'a>(Cloned<slice::Iter<'a, u8>>);
753 #[stable(feature = "rust1", since = "1.0.0")]
754 impl Iterator for Bytes<'_> {
758 fn next(&mut self) -> Option<u8> {
763 fn size_hint(&self) -> (usize, Option<usize>) {
768 fn count(self) -> usize {
773 fn last(self) -> Option<Self::Item> {
778 fn nth(&mut self, n: usize) -> Option<Self::Item> {
783 fn all<F>(&mut self, f: F) -> bool
785 F: FnMut(Self::Item) -> bool,
791 fn any<F>(&mut self, f: F) -> bool
793 F: FnMut(Self::Item) -> bool,
799 fn find<P>(&mut self, predicate: P) -> Option<Self::Item>
801 P: FnMut(&Self::Item) -> bool,
803 self.0.find(predicate)
807 fn position<P>(&mut self, predicate: P) -> Option<usize>
809 P: FnMut(Self::Item) -> bool,
811 self.0.position(predicate)
815 fn rposition<P>(&mut self, predicate: P) -> Option<usize>
817 P: FnMut(Self::Item) -> bool,
819 self.0.rposition(predicate)
823 #[stable(feature = "rust1", since = "1.0.0")]
824 impl DoubleEndedIterator for Bytes<'_> {
826 fn next_back(&mut self) -> Option<u8> {
831 fn nth_back(&mut self, n: usize) -> Option<Self::Item> {
836 fn rfind<P>(&mut self, predicate: P) -> Option<Self::Item>
838 P: FnMut(&Self::Item) -> bool,
840 self.0.rfind(predicate)
844 #[stable(feature = "rust1", since = "1.0.0")]
845 impl ExactSizeIterator for Bytes<'_> {
847 fn len(&self) -> usize {
852 fn is_empty(&self) -> bool {
857 #[stable(feature = "fused", since = "1.26.0")]
858 impl FusedIterator for Bytes<'_> {}
860 #[unstable(feature = "trusted_len", issue = "37572")]
861 unsafe impl TrustedLen for Bytes<'_> {}
864 unsafe impl TrustedRandomAccess for Bytes<'_> {
865 unsafe fn get_unchecked(&mut self, i: usize) -> u8 {
866 self.0.get_unchecked(i)
868 fn may_have_side_effect() -> bool {
873 /// This macro generates a Clone impl for string pattern API
874 /// wrapper types of the form X<'a, P>
875 macro_rules! derive_pattern_clone {
876 (clone $t:ident with |$s:ident| $e:expr) => {
877 impl<'a, P> Clone for $t<'a, P>
879 P: Pattern<'a, Searcher: Clone>,
881 fn clone(&self) -> Self {
889 /// This macro generates two public iterator structs
890 /// wrapping a private internal one that makes use of the `Pattern` API.
892 /// For all patterns `P: Pattern<'a>` the following items will be
893 /// generated (generics omitted):
895 /// struct $forward_iterator($internal_iterator);
896 /// struct $reverse_iterator($internal_iterator);
898 /// impl Iterator for $forward_iterator
899 /// { /* internal ends up calling Searcher::next_match() */ }
901 /// impl DoubleEndedIterator for $forward_iterator
902 /// where P::Searcher: DoubleEndedSearcher
903 /// { /* internal ends up calling Searcher::next_match_back() */ }
905 /// impl Iterator for $reverse_iterator
906 /// where P::Searcher: ReverseSearcher
907 /// { /* internal ends up calling Searcher::next_match_back() */ }
909 /// impl DoubleEndedIterator for $reverse_iterator
910 /// where P::Searcher: DoubleEndedSearcher
911 /// { /* internal ends up calling Searcher::next_match() */ }
913 /// The internal one is defined outside the macro, and has almost the same
914 /// semantic as a DoubleEndedIterator by delegating to `pattern::Searcher` and
915 /// `pattern::ReverseSearcher` for both forward and reverse iteration.
917 /// "Almost", because a `Searcher` and a `ReverseSearcher` for a given
918 /// `Pattern` might not return the same elements, so actually implementing
919 /// `DoubleEndedIterator` for it would be incorrect.
920 /// (See the docs in `str::pattern` for more details)
922 /// However, the internal struct still represents a single ended iterator from
923 /// either end, and depending on pattern is also a valid double ended iterator,
924 /// so the two wrapper structs implement `Iterator`
925 /// and `DoubleEndedIterator` depending on the concrete pattern type, leading
926 /// to the complex impls seen above.
927 macro_rules! generate_pattern_iterators {
931 $(#[$forward_iterator_attribute:meta])*
932 struct $forward_iterator:ident;
936 $(#[$reverse_iterator_attribute:meta])*
937 struct $reverse_iterator:ident;
939 // Stability of all generated items
941 $(#[$common_stability_attribute:meta])*
943 // Internal almost-iterator that is being delegated to
945 $internal_iterator:ident yielding ($iterty:ty);
947 // Kind of delegation - either single ended or double ended
950 $(#[$forward_iterator_attribute])*
951 $(#[$common_stability_attribute])*
952 pub struct $forward_iterator<'a, P: Pattern<'a>>($internal_iterator<'a, P>);
954 $(#[$common_stability_attribute])*
955 impl<'a, P> fmt::Debug for $forward_iterator<'a, P>
957 P: Pattern<'a, Searcher: fmt::Debug>,
959 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
960 f.debug_tuple(stringify!($forward_iterator))
966 $(#[$common_stability_attribute])*
967 impl<'a, P: Pattern<'a>> Iterator for $forward_iterator<'a, P> {
971 fn next(&mut self) -> Option<$iterty> {
976 $(#[$common_stability_attribute])*
977 impl<'a, P> Clone for $forward_iterator<'a, P>
979 P: Pattern<'a, Searcher: Clone>,
981 fn clone(&self) -> Self {
982 $forward_iterator(self.0.clone())
986 $(#[$reverse_iterator_attribute])*
987 $(#[$common_stability_attribute])*
988 pub struct $reverse_iterator<'a, P: Pattern<'a>>($internal_iterator<'a, P>);
990 $(#[$common_stability_attribute])*
991 impl<'a, P> fmt::Debug for $reverse_iterator<'a, P>
993 P: Pattern<'a, Searcher: fmt::Debug>,
995 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
996 f.debug_tuple(stringify!($reverse_iterator))
1002 $(#[$common_stability_attribute])*
1003 impl<'a, P> Iterator for $reverse_iterator<'a, P>
1005 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1007 type Item = $iterty;
1010 fn next(&mut self) -> Option<$iterty> {
1015 $(#[$common_stability_attribute])*
1016 impl<'a, P> Clone for $reverse_iterator<'a, P>
1018 P: Pattern<'a, Searcher: Clone>,
1020 fn clone(&self) -> Self {
1021 $reverse_iterator(self.0.clone())
1025 #[stable(feature = "fused", since = "1.26.0")]
1026 impl<'a, P: Pattern<'a>> FusedIterator for $forward_iterator<'a, P> {}
1028 #[stable(feature = "fused", since = "1.26.0")]
1029 impl<'a, P> FusedIterator for $reverse_iterator<'a, P>
1031 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
1034 generate_pattern_iterators!($($t)* with $(#[$common_stability_attribute])*,
1036 $reverse_iterator, $iterty);
1039 double ended; with $(#[$common_stability_attribute:meta])*,
1040 $forward_iterator:ident,
1041 $reverse_iterator:ident, $iterty:ty
1043 $(#[$common_stability_attribute])*
1044 impl<'a, P> DoubleEndedIterator for $forward_iterator<'a, P>
1046 P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>,
1049 fn next_back(&mut self) -> Option<$iterty> {
1054 $(#[$common_stability_attribute])*
1055 impl<'a, P> DoubleEndedIterator for $reverse_iterator<'a, P>
1057 P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>,
1060 fn next_back(&mut self) -> Option<$iterty> {
1066 single ended; with $(#[$common_stability_attribute:meta])*,
1067 $forward_iterator:ident,
1068 $reverse_iterator:ident, $iterty:ty
1072 derive_pattern_clone! {
1074 with |s| SplitInternal { matcher: s.matcher.clone(), ..*s }
1077 struct SplitInternal<'a, P: Pattern<'a>> {
1080 matcher: P::Searcher,
1081 allow_trailing_empty: bool,
1085 impl<'a, P> fmt::Debug for SplitInternal<'a, P>
1087 P: Pattern<'a, Searcher: fmt::Debug>,
1089 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1090 f.debug_struct("SplitInternal")
1091 .field("start", &self.start)
1092 .field("end", &self.end)
1093 .field("matcher", &self.matcher)
1094 .field("allow_trailing_empty", &self.allow_trailing_empty)
1095 .field("finished", &self.finished)
1100 impl<'a, P: Pattern<'a>> SplitInternal<'a, P> {
1102 fn get_end(&mut self) -> Option<&'a str> {
1103 if !self.finished && (self.allow_trailing_empty || self.end - self.start > 0) {
1104 self.finished = true;
1106 let string = self.matcher.haystack().get_unchecked(self.start..self.end);
1115 fn next(&mut self) -> Option<&'a str> {
1120 let haystack = self.matcher.haystack();
1121 match self.matcher.next_match() {
1122 Some((a, b)) => unsafe {
1123 let elt = haystack.get_unchecked(self.start..a);
1127 None => self.get_end(),
1132 fn next_back(&mut self) -> Option<&'a str>
1134 P::Searcher: ReverseSearcher<'a>,
1140 if !self.allow_trailing_empty {
1141 self.allow_trailing_empty = true;
1142 match self.next_back() {
1143 Some(elt) if !elt.is_empty() => return Some(elt),
1152 let haystack = self.matcher.haystack();
1153 match self.matcher.next_match_back() {
1154 Some((a, b)) => unsafe {
1155 let elt = haystack.get_unchecked(b..self.end);
1160 self.finished = true;
1161 Some(haystack.get_unchecked(self.start..self.end))
1167 generate_pattern_iterators! {
1169 /// Created with the method [`split`].
1171 /// [`split`]: ../../std/primitive.str.html#method.split
1174 /// Created with the method [`rsplit`].
1176 /// [`rsplit`]: ../../std/primitive.str.html#method.rsplit
1179 #[stable(feature = "rust1", since = "1.0.0")]
1181 SplitInternal yielding (&'a str);
1182 delegate double ended;
1185 generate_pattern_iterators! {
1187 /// Created with the method [`split_terminator`].
1189 /// [`split_terminator`]: ../../std/primitive.str.html#method.split_terminator
1190 struct SplitTerminator;
1192 /// Created with the method [`rsplit_terminator`].
1194 /// [`rsplit_terminator`]: ../../std/primitive.str.html#method.rsplit_terminator
1195 struct RSplitTerminator;
1197 #[stable(feature = "rust1", since = "1.0.0")]
1199 SplitInternal yielding (&'a str);
1200 delegate double ended;
1203 derive_pattern_clone! {
1204 clone SplitNInternal
1205 with |s| SplitNInternal { iter: s.iter.clone(), ..*s }
1208 struct SplitNInternal<'a, P: Pattern<'a>> {
1209 iter: SplitInternal<'a, P>,
1210 /// The number of splits remaining
1214 impl<'a, P> fmt::Debug for SplitNInternal<'a, P>
1216 P: Pattern<'a, Searcher: fmt::Debug>,
1218 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1219 f.debug_struct("SplitNInternal")
1220 .field("iter", &self.iter)
1221 .field("count", &self.count)
1226 impl<'a, P: Pattern<'a>> SplitNInternal<'a, P> {
1228 fn next(&mut self) -> Option<&'a str> {
1243 fn next_back(&mut self) -> Option<&'a str>
1245 P::Searcher: ReverseSearcher<'a>,
1255 self.iter.next_back()
1261 generate_pattern_iterators! {
1263 /// Created with the method [`splitn`].
1265 /// [`splitn`]: ../../std/primitive.str.html#method.splitn
1268 /// Created with the method [`rsplitn`].
1270 /// [`rsplitn`]: ../../std/primitive.str.html#method.rsplitn
1273 #[stable(feature = "rust1", since = "1.0.0")]
1275 SplitNInternal yielding (&'a str);
1276 delegate single ended;
1279 derive_pattern_clone! {
1280 clone MatchIndicesInternal
1281 with |s| MatchIndicesInternal(s.0.clone())
1284 struct MatchIndicesInternal<'a, P: Pattern<'a>>(P::Searcher);
1286 impl<'a, P> fmt::Debug for MatchIndicesInternal<'a, P>
1288 P: Pattern<'a, Searcher: fmt::Debug>,
1290 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1291 f.debug_tuple("MatchIndicesInternal").field(&self.0).finish()
1295 impl<'a, P: Pattern<'a>> MatchIndicesInternal<'a, P> {
1297 fn next(&mut self) -> Option<(usize, &'a str)> {
1300 .map(|(start, end)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) })
1304 fn next_back(&mut self) -> Option<(usize, &'a str)>
1306 P::Searcher: ReverseSearcher<'a>,
1310 .map(|(start, end)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) })
1314 generate_pattern_iterators! {
1316 /// Created with the method [`match_indices`].
1318 /// [`match_indices`]: ../../std/primitive.str.html#method.match_indices
1319 struct MatchIndices;
1321 /// Created with the method [`rmatch_indices`].
1323 /// [`rmatch_indices`]: ../../std/primitive.str.html#method.rmatch_indices
1324 struct RMatchIndices;
1326 #[stable(feature = "str_match_indices", since = "1.5.0")]
1328 MatchIndicesInternal yielding ((usize, &'a str));
1329 delegate double ended;
1332 derive_pattern_clone! {
1333 clone MatchesInternal
1334 with |s| MatchesInternal(s.0.clone())
1337 struct MatchesInternal<'a, P: Pattern<'a>>(P::Searcher);
1339 impl<'a, P> fmt::Debug for MatchesInternal<'a, P>
1341 P: Pattern<'a, Searcher: fmt::Debug>,
1343 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1344 f.debug_tuple("MatchesInternal").field(&self.0).finish()
1348 impl<'a, P: Pattern<'a>> MatchesInternal<'a, P> {
1350 fn next(&mut self) -> Option<&'a str> {
1351 self.0.next_match().map(|(a, b)| unsafe {
1352 // Indices are known to be on utf8 boundaries
1353 self.0.haystack().get_unchecked(a..b)
1358 fn next_back(&mut self) -> Option<&'a str>
1360 P::Searcher: ReverseSearcher<'a>,
1362 self.0.next_match_back().map(|(a, b)| unsafe {
1363 // Indices are known to be on utf8 boundaries
1364 self.0.haystack().get_unchecked(a..b)
1369 generate_pattern_iterators! {
1371 /// Created with the method [`matches`].
1373 /// [`matches`]: ../../std/primitive.str.html#method.matches
1376 /// Created with the method [`rmatches`].
1378 /// [`rmatches`]: ../../std/primitive.str.html#method.rmatches
1381 #[stable(feature = "str_matches", since = "1.2.0")]
1383 MatchesInternal yielding (&'a str);
1384 delegate double ended;
1387 /// An iterator over the lines of a string, as string slices.
1389 /// This struct is created with the [`lines`] method on [`str`].
1390 /// See its documentation for more.
1392 /// [`lines`]: ../../std/primitive.str.html#method.lines
1393 /// [`str`]: ../../std/primitive.str.html
1394 #[stable(feature = "rust1", since = "1.0.0")]
1395 #[derive(Clone, Debug)]
1396 pub struct Lines<'a>(Map<SplitTerminator<'a, char>, LinesAnyMap>);
1398 #[stable(feature = "rust1", since = "1.0.0")]
1399 impl<'a> Iterator for Lines<'a> {
1400 type Item = &'a str;
1403 fn next(&mut self) -> Option<&'a str> {
1408 fn size_hint(&self) -> (usize, Option<usize>) {
1413 fn last(mut self) -> Option<&'a str> {
1418 #[stable(feature = "rust1", since = "1.0.0")]
1419 impl<'a> DoubleEndedIterator for Lines<'a> {
1421 fn next_back(&mut self) -> Option<&'a str> {
1426 #[stable(feature = "fused", since = "1.26.0")]
1427 impl FusedIterator for Lines<'_> {}
1429 /// Created with the method [`lines_any`].
1431 /// [`lines_any`]: ../../std/primitive.str.html#method.lines_any
1432 #[stable(feature = "rust1", since = "1.0.0")]
1433 #[rustc_deprecated(since = "1.4.0", reason = "use lines()/Lines instead now")]
1434 #[derive(Clone, Debug)]
1435 #[allow(deprecated)]
1436 pub struct LinesAny<'a>(Lines<'a>);
1439 /// A nameable, cloneable fn type
1441 struct LinesAnyMap impl<'a> Fn = |line: &'a str| -> &'a str {
1443 if l > 0 && line.as_bytes()[l - 1] == b'\r' { &line[0 .. l - 1] }
1448 #[stable(feature = "rust1", since = "1.0.0")]
1449 #[allow(deprecated)]
1450 impl<'a> Iterator for LinesAny<'a> {
1451 type Item = &'a str;
1454 fn next(&mut self) -> Option<&'a str> {
1459 fn size_hint(&self) -> (usize, Option<usize>) {
1464 #[stable(feature = "rust1", since = "1.0.0")]
1465 #[allow(deprecated)]
1466 impl<'a> DoubleEndedIterator for LinesAny<'a> {
1468 fn next_back(&mut self) -> Option<&'a str> {
1473 #[stable(feature = "fused", since = "1.26.0")]
1474 #[allow(deprecated)]
1475 impl FusedIterator for LinesAny<'_> {}
1478 Section: UTF-8 validation
1481 // use truncation to fit u64 into usize
1482 const NONASCII_MASK: usize = 0x80808080_80808080u64 as usize;
1484 /// Returns `true` if any byte in the word `x` is nonascii (>= 128).
1486 fn contains_nonascii(x: usize) -> bool {
1487 (x & NONASCII_MASK) != 0
1490 /// Walks through `v` checking that it's a valid UTF-8 sequence,
1491 /// returning `Ok(())` in that case, or, if it is invalid, `Err(err)`.
1493 fn run_utf8_validation(v: &[u8]) -> Result<(), Utf8Error> {
1497 let usize_bytes = mem::size_of::<usize>();
1498 let ascii_block_size = 2 * usize_bytes;
1499 let blocks_end = if len >= ascii_block_size { len - ascii_block_size + 1 } else { 0 };
1500 let align = v.as_ptr().align_offset(usize_bytes);
1503 let old_offset = index;
1505 ($error_len: expr) => {
1506 return Err(Utf8Error { valid_up_to: old_offset, error_len: $error_len });
1513 // we needed data, but there was none: error!
1521 let first = v[index];
1523 let w = UTF8_CHAR_WIDTH[first as usize];
1524 // 2-byte encoding is for codepoints \u{0080} to \u{07ff}
1525 // first C2 80 last DF BF
1526 // 3-byte encoding is for codepoints \u{0800} to \u{ffff}
1527 // first E0 A0 80 last EF BF BF
1528 // excluding surrogates codepoints \u{d800} to \u{dfff}
1529 // ED A0 80 to ED BF BF
1530 // 4-byte encoding is for codepoints \u{1000}0 to \u{10ff}ff
1531 // first F0 90 80 80 last F4 8F BF BF
1533 // Use the UTF-8 syntax from the RFC
1535 // https://tools.ietf.org/html/rfc3629
1537 // UTF8-2 = %xC2-DF UTF8-tail
1538 // UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2( UTF8-tail ) /
1539 // %xED %x80-9F UTF8-tail / %xEE-EF 2( UTF8-tail )
1540 // UTF8-4 = %xF0 %x90-BF 2( UTF8-tail ) / %xF1-F3 3( UTF8-tail ) /
1541 // %xF4 %x80-8F 2( UTF8-tail )
1544 if next!() & !CONT_MASK != TAG_CONT_U8 {
1549 match (first, next!()) {
1551 | (0xE1..=0xEC, 0x80..=0xBF)
1552 | (0xED, 0x80..=0x9F)
1553 | (0xEE..=0xEF, 0x80..=0xBF) => {}
1556 if next!() & !CONT_MASK != TAG_CONT_U8 {
1561 match (first, next!()) {
1562 (0xF0, 0x90..=0xBF) | (0xF1..=0xF3, 0x80..=0xBF) | (0xF4, 0x80..=0x8F) => {}
1565 if next!() & !CONT_MASK != TAG_CONT_U8 {
1568 if next!() & !CONT_MASK != TAG_CONT_U8 {
1576 // Ascii case, try to skip forward quickly.
1577 // When the pointer is aligned, read 2 words of data per iteration
1578 // until we find a word containing a non-ascii byte.
1579 if align != usize::max_value() && align.wrapping_sub(index) % usize_bytes == 0 {
1580 let ptr = v.as_ptr();
1581 while index < blocks_end {
1583 let block = ptr.add(index) as *const usize;
1584 // break if there is a nonascii byte
1585 let zu = contains_nonascii(*block);
1586 let zv = contains_nonascii(*block.offset(1));
1591 index += ascii_block_size;
1593 // step from the point where the wordwise loop stopped
1594 while index < len && v[index] < 128 {
1606 // https://tools.ietf.org/html/rfc3629
1607 static UTF8_CHAR_WIDTH: [u8; 256] = [
1608 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,
1610 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,
1612 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,
1614 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,
1616 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,
1618 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,
1620 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,
1622 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, // 0xEF
1623 4, 4, 4, 4, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0xFF
1626 /// Given a first byte, determines how many bytes are in this UTF-8 character.
1627 #[unstable(feature = "str_internals", issue = "none")]
1629 pub fn utf8_char_width(b: u8) -> usize {
1630 UTF8_CHAR_WIDTH[b as usize] as usize
1633 /// Mask of the value bits of a continuation byte.
1634 const CONT_MASK: u8 = 0b0011_1111;
1635 /// Value of the tag bits (tag mask is !CONT_MASK) of a continuation byte.
1636 const TAG_CONT_U8: u8 = 0b1000_0000;
1639 Section: Trait implementations
1643 use crate::cmp::Ordering;
1645 use crate::slice::{self, SliceIndex};
1647 /// Implements ordering of strings.
1649 /// Strings are ordered lexicographically by their byte values. This orders Unicode code
1650 /// points based on their positions in the code charts. This is not necessarily the same as
1651 /// "alphabetical" order, which varies by language and locale. Sorting strings according to
1652 /// culturally-accepted standards requires locale-specific data that is outside the scope of
1654 #[stable(feature = "rust1", since = "1.0.0")]
1657 fn cmp(&self, other: &str) -> Ordering {
1658 self.as_bytes().cmp(other.as_bytes())
1662 #[stable(feature = "rust1", since = "1.0.0")]
1663 impl PartialEq for str {
1665 fn eq(&self, other: &str) -> bool {
1666 self.as_bytes() == other.as_bytes()
1669 fn ne(&self, other: &str) -> bool {
1674 #[stable(feature = "rust1", since = "1.0.0")]
1677 /// Implements comparison operations on strings.
1679 /// Strings are compared lexicographically by their byte values. This compares Unicode code
1680 /// points based on their positions in the code charts. This is not necessarily the same as
1681 /// "alphabetical" order, which varies by language and locale. Comparing strings according to
1682 /// culturally-accepted standards requires locale-specific data that is outside the scope of
1684 #[stable(feature = "rust1", since = "1.0.0")]
1685 impl PartialOrd for str {
1687 fn partial_cmp(&self, other: &str) -> Option<Ordering> {
1688 Some(self.cmp(other))
1692 #[stable(feature = "rust1", since = "1.0.0")]
1693 impl<I> ops::Index<I> for str
1697 type Output = I::Output;
1700 fn index(&self, index: I) -> &I::Output {
1705 #[stable(feature = "rust1", since = "1.0.0")]
1706 impl<I> ops::IndexMut<I> for str
1711 fn index_mut(&mut self, index: I) -> &mut I::Output {
1712 index.index_mut(self)
1718 fn str_index_overflow_fail() -> ! {
1719 panic!("attempted to index str up to maximum usize");
1722 /// Implements substring slicing with syntax `&self[..]` or `&mut self[..]`.
1724 /// Returns a slice of the whole string, i.e., returns `&self` or `&mut
1725 /// self`. Equivalent to `&self[0 .. len]` or `&mut self[0 .. len]`. Unlike
1726 /// other indexing operations, this can never panic.
1728 /// This operation is `O(1)`.
1730 /// Prior to 1.20.0, these indexing operations were still supported by
1731 /// direct implementation of `Index` and `IndexMut`.
1733 /// Equivalent to `&self[0 .. len]` or `&mut self[0 .. len]`.
1734 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1735 impl SliceIndex<str> for ops::RangeFull {
1738 fn get(self, slice: &str) -> Option<&Self::Output> {
1742 fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
1746 unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
1750 unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
1754 fn index(self, slice: &str) -> &Self::Output {
1758 fn index_mut(self, slice: &mut str) -> &mut Self::Output {
1763 /// Implements substring slicing with syntax `&self[begin .. end]` or `&mut
1764 /// self[begin .. end]`.
1766 /// Returns a slice of the given string from the byte range
1767 /// [`begin`, `end`).
1769 /// This operation is `O(1)`.
1771 /// Prior to 1.20.0, these indexing operations were still supported by
1772 /// direct implementation of `Index` and `IndexMut`.
1776 /// Panics if `begin` or `end` does not point to the starting byte offset of
1777 /// a character (as defined by `is_char_boundary`), if `begin > end`, or if
1783 /// let s = "Löwe 老虎 Léopard";
1784 /// assert_eq!(&s[0 .. 1], "L");
1786 /// assert_eq!(&s[1 .. 9], "öwe 老");
1788 /// // these will panic:
1789 /// // byte 2 lies within `ö`:
1792 /// // byte 8 lies within `老`
1795 /// // byte 100 is outside the string
1796 /// // &s[3 .. 100];
1798 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1799 impl SliceIndex<str> for ops::Range<usize> {
1802 fn get(self, slice: &str) -> Option<&Self::Output> {
1803 if self.start <= self.end
1804 && slice.is_char_boundary(self.start)
1805 && slice.is_char_boundary(self.end)
1807 Some(unsafe { self.get_unchecked(slice) })
1813 fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
1814 if self.start <= self.end
1815 && slice.is_char_boundary(self.start)
1816 && slice.is_char_boundary(self.end)
1818 Some(unsafe { self.get_unchecked_mut(slice) })
1824 unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
1825 let ptr = slice.as_ptr().add(self.start);
1826 let len = self.end - self.start;
1827 super::from_utf8_unchecked(slice::from_raw_parts(ptr, len))
1830 unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
1831 let ptr = slice.as_mut_ptr().add(self.start);
1832 let len = self.end - self.start;
1833 super::from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, len))
1836 fn index(self, slice: &str) -> &Self::Output {
1837 let (start, end) = (self.start, self.end);
1838 self.get(slice).unwrap_or_else(|| super::slice_error_fail(slice, start, end))
1841 fn index_mut(self, slice: &mut str) -> &mut Self::Output {
1842 // is_char_boundary checks that the index is in [0, .len()]
1843 // cannot reuse `get` as above, because of NLL trouble
1844 if self.start <= self.end
1845 && slice.is_char_boundary(self.start)
1846 && slice.is_char_boundary(self.end)
1848 unsafe { self.get_unchecked_mut(slice) }
1850 super::slice_error_fail(slice, self.start, self.end)
1855 /// Implements substring slicing with syntax `&self[.. end]` or `&mut
1858 /// Returns a slice of the given string from the byte range [`0`, `end`).
1859 /// Equivalent to `&self[0 .. end]` or `&mut self[0 .. end]`.
1861 /// This operation is `O(1)`.
1863 /// Prior to 1.20.0, these indexing operations were still supported by
1864 /// direct implementation of `Index` and `IndexMut`.
1868 /// Panics if `end` does not point to the starting byte offset of a
1869 /// character (as defined by `is_char_boundary`), or if `end > len`.
1870 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1871 impl SliceIndex<str> for ops::RangeTo<usize> {
1874 fn get(self, slice: &str) -> Option<&Self::Output> {
1875 if slice.is_char_boundary(self.end) {
1876 Some(unsafe { self.get_unchecked(slice) })
1882 fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
1883 if slice.is_char_boundary(self.end) {
1884 Some(unsafe { self.get_unchecked_mut(slice) })
1890 unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
1891 let ptr = slice.as_ptr();
1892 super::from_utf8_unchecked(slice::from_raw_parts(ptr, self.end))
1895 unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
1896 let ptr = slice.as_mut_ptr();
1897 super::from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, self.end))
1900 fn index(self, slice: &str) -> &Self::Output {
1902 self.get(slice).unwrap_or_else(|| super::slice_error_fail(slice, 0, end))
1905 fn index_mut(self, slice: &mut str) -> &mut Self::Output {
1906 // is_char_boundary checks that the index is in [0, .len()]
1907 if slice.is_char_boundary(self.end) {
1908 unsafe { self.get_unchecked_mut(slice) }
1910 super::slice_error_fail(slice, 0, self.end)
1915 /// Implements substring slicing with syntax `&self[begin ..]` or `&mut
1916 /// self[begin ..]`.
1918 /// Returns a slice of the given string from the byte range [`begin`,
1919 /// `len`). Equivalent to `&self[begin .. len]` or `&mut self[begin ..
1922 /// This operation is `O(1)`.
1924 /// Prior to 1.20.0, these indexing operations were still supported by
1925 /// direct implementation of `Index` and `IndexMut`.
1929 /// Panics if `begin` does not point to the starting byte offset of
1930 /// a character (as defined by `is_char_boundary`), or if `begin >= len`.
1931 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1932 impl SliceIndex<str> for ops::RangeFrom<usize> {
1935 fn get(self, slice: &str) -> Option<&Self::Output> {
1936 if slice.is_char_boundary(self.start) {
1937 Some(unsafe { self.get_unchecked(slice) })
1943 fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
1944 if slice.is_char_boundary(self.start) {
1945 Some(unsafe { self.get_unchecked_mut(slice) })
1951 unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
1952 let ptr = slice.as_ptr().add(self.start);
1953 let len = slice.len() - self.start;
1954 super::from_utf8_unchecked(slice::from_raw_parts(ptr, len))
1957 unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
1958 let ptr = slice.as_mut_ptr().add(self.start);
1959 let len = slice.len() - self.start;
1960 super::from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, len))
1963 fn index(self, slice: &str) -> &Self::Output {
1964 let (start, end) = (self.start, slice.len());
1965 self.get(slice).unwrap_or_else(|| super::slice_error_fail(slice, start, end))
1968 fn index_mut(self, slice: &mut str) -> &mut Self::Output {
1969 // is_char_boundary checks that the index is in [0, .len()]
1970 if slice.is_char_boundary(self.start) {
1971 unsafe { self.get_unchecked_mut(slice) }
1973 super::slice_error_fail(slice, self.start, slice.len())
1978 /// Implements substring slicing with syntax `&self[begin ..= end]` or `&mut
1979 /// self[begin ..= end]`.
1981 /// Returns a slice of the given string from the byte range
1982 /// [`begin`, `end`]. Equivalent to `&self [begin .. end + 1]` or `&mut
1983 /// self[begin .. end + 1]`, except if `end` has the maximum value for
1986 /// This operation is `O(1)`.
1990 /// Panics if `begin` does not point to the starting byte offset of
1991 /// a character (as defined by `is_char_boundary`), if `end` does not point
1992 /// to the ending byte offset of a character (`end + 1` is either a starting
1993 /// byte offset or equal to `len`), if `begin > end`, or if `end >= len`.
1994 #[stable(feature = "inclusive_range", since = "1.26.0")]
1995 impl SliceIndex<str> for ops::RangeInclusive<usize> {
1998 fn get(self, slice: &str) -> Option<&Self::Output> {
1999 if *self.end() == usize::max_value() {
2002 (*self.start()..self.end() + 1).get(slice)
2006 fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
2007 if *self.end() == usize::max_value() {
2010 (*self.start()..self.end() + 1).get_mut(slice)
2014 unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
2015 (*self.start()..self.end() + 1).get_unchecked(slice)
2018 unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
2019 (*self.start()..self.end() + 1).get_unchecked_mut(slice)
2022 fn index(self, slice: &str) -> &Self::Output {
2023 if *self.end() == usize::max_value() {
2024 str_index_overflow_fail();
2026 (*self.start()..self.end() + 1).index(slice)
2029 fn index_mut(self, slice: &mut str) -> &mut Self::Output {
2030 if *self.end() == usize::max_value() {
2031 str_index_overflow_fail();
2033 (*self.start()..self.end() + 1).index_mut(slice)
2037 /// Implements substring slicing with syntax `&self[..= end]` or `&mut
2040 /// Returns a slice of the given string from the byte range [0, `end`].
2041 /// Equivalent to `&self [0 .. end + 1]`, except if `end` has the maximum
2042 /// value for `usize`.
2044 /// This operation is `O(1)`.
2048 /// Panics if `end` does not point to the ending byte offset of a character
2049 /// (`end + 1` is either a starting byte offset as defined by
2050 /// `is_char_boundary`, or equal to `len`), or if `end >= len`.
2051 #[stable(feature = "inclusive_range", since = "1.26.0")]
2052 impl SliceIndex<str> for ops::RangeToInclusive<usize> {
2055 fn get(self, slice: &str) -> Option<&Self::Output> {
2056 if self.end == usize::max_value() { None } else { (..self.end + 1).get(slice) }
2059 fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> {
2060 if self.end == usize::max_value() { None } else { (..self.end + 1).get_mut(slice) }
2063 unsafe fn get_unchecked(self, slice: &str) -> &Self::Output {
2064 (..self.end + 1).get_unchecked(slice)
2067 unsafe fn get_unchecked_mut(self, slice: &mut str) -> &mut Self::Output {
2068 (..self.end + 1).get_unchecked_mut(slice)
2071 fn index(self, slice: &str) -> &Self::Output {
2072 if self.end == usize::max_value() {
2073 str_index_overflow_fail();
2075 (..self.end + 1).index(slice)
2078 fn index_mut(self, slice: &mut str) -> &mut Self::Output {
2079 if self.end == usize::max_value() {
2080 str_index_overflow_fail();
2082 (..self.end + 1).index_mut(slice)
2087 // truncate `&str` to length at most equal to `max`
2088 // return `true` if it were truncated, and the new str.
2089 fn truncate_to_char_boundary(s: &str, mut max: usize) -> (bool, &str) {
2093 while !s.is_char_boundary(max) {
2102 fn slice_error_fail(s: &str, begin: usize, end: usize) -> ! {
2103 const MAX_DISPLAY_LENGTH: usize = 256;
2104 let (truncated, s_trunc) = truncate_to_char_boundary(s, MAX_DISPLAY_LENGTH);
2105 let ellipsis = if truncated { "[...]" } else { "" };
2108 if begin > s.len() || end > s.len() {
2109 let oob_index = if begin > s.len() { begin } else { end };
2110 panic!("byte index {} is out of bounds of `{}`{}", oob_index, s_trunc, ellipsis);
2116 "begin <= end ({} <= {}) when slicing `{}`{}",
2123 // 3. character boundary
2124 let index = if !s.is_char_boundary(begin) { begin } else { end };
2125 // find the character
2126 let mut char_start = index;
2127 while !s.is_char_boundary(char_start) {
2130 // `char_start` must be less than len and a char boundary
2131 let ch = s[char_start..].chars().next().unwrap();
2132 let char_range = char_start..char_start + ch.len_utf8();
2134 "byte index {} is not a char boundary; it is inside {:?} (bytes {:?}) of `{}`{}",
2135 index, ch, char_range, s_trunc, ellipsis
2142 /// Returns the length of `self`.
2144 /// This length is in bytes, not [`char`]s or graphemes. In other words,
2145 /// it may not be what a human considers the length of the string.
2152 /// let len = "foo".len();
2153 /// assert_eq!(3, len);
2155 /// assert_eq!("ƒoo".len(), 4); // fancy f!
2156 /// assert_eq!("ƒoo".chars().count(), 3);
2158 #[stable(feature = "rust1", since = "1.0.0")]
2159 #[rustc_const_stable(feature = "const_str_len", since = "1.32.0")]
2161 pub const fn len(&self) -> usize {
2162 self.as_bytes().len()
2165 /// Returns `true` if `self` has a length of zero bytes.
2173 /// assert!(s.is_empty());
2175 /// let s = "not empty";
2176 /// assert!(!s.is_empty());
2179 #[stable(feature = "rust1", since = "1.0.0")]
2180 #[rustc_const_stable(feature = "const_str_is_empty", since = "1.32.0")]
2181 pub const fn is_empty(&self) -> bool {
2185 /// Checks that `index`-th byte lies at the start and/or end of a
2186 /// UTF-8 code point sequence.
2188 /// The start and end of the string (when `index == self.len()`) are
2189 /// considered to be
2192 /// Returns `false` if `index` is greater than `self.len()`.
2197 /// let s = "Löwe 老虎 Léopard";
2198 /// assert!(s.is_char_boundary(0));
2200 /// assert!(s.is_char_boundary(6));
2201 /// assert!(s.is_char_boundary(s.len()));
2203 /// // second byte of `ö`
2204 /// assert!(!s.is_char_boundary(2));
2206 /// // third byte of `老`
2207 /// assert!(!s.is_char_boundary(8));
2209 #[stable(feature = "is_char_boundary", since = "1.9.0")]
2211 pub fn is_char_boundary(&self, index: usize) -> bool {
2212 // 0 and len are always ok.
2213 // Test for 0 explicitly so that it can optimize out the check
2214 // easily and skip reading string data for that case.
2215 if index == 0 || index == self.len() {
2218 match self.as_bytes().get(index) {
2220 // This is bit magic equivalent to: b < 128 || b >= 192
2221 Some(&b) => (b as i8) >= -0x40,
2225 /// Converts a string slice to a byte slice. To convert the byte slice back
2226 /// into a string slice, use the [`str::from_utf8`] function.
2228 /// [`str::from_utf8`]: ./str/fn.from_utf8.html
2235 /// let bytes = "bors".as_bytes();
2236 /// assert_eq!(b"bors", bytes);
2238 #[stable(feature = "rust1", since = "1.0.0")]
2239 #[rustc_const_stable(feature = "str_as_bytes", since = "1.32.0")]
2241 // SAFETY: const sound because we transmute two types with the same layout
2242 #[allow(unused_attributes)]
2243 #[allow_internal_unstable(const_fn_union)]
2244 pub const fn as_bytes(&self) -> &[u8] {
2250 unsafe { Slices { str: self }.slice }
2253 /// Converts a mutable string slice to a mutable byte slice. To convert the
2254 /// mutable byte slice back into a mutable string slice, use the
2255 /// [`str::from_utf8_mut`] function.
2257 /// [`str::from_utf8_mut`]: ./str/fn.from_utf8_mut.html
2264 /// let mut s = String::from("Hello");
2265 /// let bytes = unsafe { s.as_bytes_mut() };
2267 /// assert_eq!(b"Hello", bytes);
2273 /// let mut s = String::from("🗻∈🌏");
2276 /// let bytes = s.as_bytes_mut();
2278 /// bytes[0] = 0xF0;
2279 /// bytes[1] = 0x9F;
2280 /// bytes[2] = 0x8D;
2281 /// bytes[3] = 0x94;
2284 /// assert_eq!("🍔∈🌏", s);
2286 #[stable(feature = "str_mut_extras", since = "1.20.0")]
2288 pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8] {
2289 &mut *(self as *mut str as *mut [u8])
2292 /// Converts a string slice to a raw pointer.
2294 /// As string slices are a slice of bytes, the raw pointer points to a
2295 /// [`u8`]. This pointer will be pointing to the first byte of the string
2298 /// The caller must ensure that the returned pointer is never written to.
2299 /// If you need to mutate the contents of the string slice, use [`as_mut_ptr`].
2301 /// [`u8`]: primitive.u8.html
2302 /// [`as_mut_ptr`]: #method.as_mut_ptr
2309 /// let s = "Hello";
2310 /// let ptr = s.as_ptr();
2312 #[stable(feature = "rust1", since = "1.0.0")]
2313 #[rustc_const_stable(feature = "rustc_str_as_ptr", since = "1.32.0")]
2315 pub const fn as_ptr(&self) -> *const u8 {
2316 self as *const str as *const u8
2319 /// Converts a mutable string slice to a raw pointer.
2321 /// As string slices are a slice of bytes, the raw pointer points to a
2322 /// [`u8`]. This pointer will be pointing to the first byte of the string
2325 /// It is your responsibility to make sure that the string slice only gets
2326 /// modified in a way that it remains valid UTF-8.
2328 /// [`u8`]: primitive.u8.html
2329 #[stable(feature = "str_as_mut_ptr", since = "1.36.0")]
2331 pub fn as_mut_ptr(&mut self) -> *mut u8 {
2332 self as *mut str as *mut u8
2335 /// Returns a subslice of `str`.
2337 /// This is the non-panicking alternative to indexing the `str`. Returns
2338 /// [`None`] whenever equivalent indexing operation would panic.
2340 /// [`None`]: option/enum.Option.html#variant.None
2345 /// let v = String::from("🗻∈🌏");
2347 /// assert_eq!(Some("🗻"), v.get(0..4));
2349 /// // indices not on UTF-8 sequence boundaries
2350 /// assert!(v.get(1..).is_none());
2351 /// assert!(v.get(..8).is_none());
2353 /// // out of bounds
2354 /// assert!(v.get(..42).is_none());
2356 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2358 pub fn get<I: SliceIndex<str>>(&self, i: I) -> Option<&I::Output> {
2362 /// Returns a mutable subslice of `str`.
2364 /// This is the non-panicking alternative to indexing the `str`. Returns
2365 /// [`None`] whenever equivalent indexing operation would panic.
2367 /// [`None`]: option/enum.Option.html#variant.None
2372 /// let mut v = String::from("hello");
2373 /// // correct length
2374 /// assert!(v.get_mut(0..5).is_some());
2375 /// // out of bounds
2376 /// assert!(v.get_mut(..42).is_none());
2377 /// assert_eq!(Some("he"), v.get_mut(0..2).map(|v| &*v));
2379 /// assert_eq!("hello", v);
2381 /// let s = v.get_mut(0..2);
2382 /// let s = s.map(|s| {
2383 /// s.make_ascii_uppercase();
2386 /// assert_eq!(Some("HE"), s);
2388 /// assert_eq!("HEllo", v);
2390 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2392 pub fn get_mut<I: SliceIndex<str>>(&mut self, i: I) -> Option<&mut I::Output> {
2396 /// Returns an unchecked subslice of `str`.
2398 /// This is the unchecked alternative to indexing the `str`.
2402 /// Callers of this function are responsible that these preconditions are
2405 /// * The starting index must come before the ending index;
2406 /// * Indexes must be within bounds of the original slice;
2407 /// * Indexes must lie on UTF-8 sequence boundaries.
2409 /// Failing that, the returned string slice may reference invalid memory or
2410 /// violate the invariants communicated by the `str` type.
2417 /// assert_eq!("🗻", v.get_unchecked(0..4));
2418 /// assert_eq!("∈", v.get_unchecked(4..7));
2419 /// assert_eq!("🌏", v.get_unchecked(7..11));
2422 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2424 pub unsafe fn get_unchecked<I: SliceIndex<str>>(&self, i: I) -> &I::Output {
2425 i.get_unchecked(self)
2428 /// Returns a mutable, unchecked subslice of `str`.
2430 /// This is the unchecked alternative to indexing the `str`.
2434 /// Callers of this function are responsible that these preconditions are
2437 /// * The starting index must come before the ending index;
2438 /// * Indexes must be within bounds of the original slice;
2439 /// * Indexes must lie on UTF-8 sequence boundaries.
2441 /// Failing that, the returned string slice may reference invalid memory or
2442 /// violate the invariants communicated by the `str` type.
2447 /// let mut v = String::from("🗻∈🌏");
2449 /// assert_eq!("🗻", v.get_unchecked_mut(0..4));
2450 /// assert_eq!("∈", v.get_unchecked_mut(4..7));
2451 /// assert_eq!("🌏", v.get_unchecked_mut(7..11));
2454 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2456 pub unsafe fn get_unchecked_mut<I: SliceIndex<str>>(&mut self, i: I) -> &mut I::Output {
2457 i.get_unchecked_mut(self)
2460 /// Creates a string slice from another string slice, bypassing safety
2463 /// This is generally not recommended, use with caution! For a safe
2464 /// alternative see [`str`] and [`Index`].
2466 /// [`str`]: primitive.str.html
2467 /// [`Index`]: ops/trait.Index.html
2469 /// This new slice goes from `begin` to `end`, including `begin` but
2470 /// excluding `end`.
2472 /// To get a mutable string slice instead, see the
2473 /// [`slice_mut_unchecked`] method.
2475 /// [`slice_mut_unchecked`]: #method.slice_mut_unchecked
2479 /// Callers of this function are responsible that three preconditions are
2482 /// * `begin` must come before `end`.
2483 /// * `begin` and `end` must be byte positions within the string slice.
2484 /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
2491 /// let s = "Löwe 老虎 Léopard";
2494 /// assert_eq!("Löwe 老虎 Léopard", s.slice_unchecked(0, 21));
2497 /// let s = "Hello, world!";
2500 /// assert_eq!("world", s.slice_unchecked(7, 12));
2503 #[stable(feature = "rust1", since = "1.0.0")]
2504 #[rustc_deprecated(since = "1.29.0", reason = "use `get_unchecked(begin..end)` instead")]
2506 pub unsafe fn slice_unchecked(&self, begin: usize, end: usize) -> &str {
2507 (begin..end).get_unchecked(self)
2510 /// Creates a string slice from another string slice, bypassing safety
2512 /// This is generally not recommended, use with caution! For a safe
2513 /// alternative see [`str`] and [`IndexMut`].
2515 /// [`str`]: primitive.str.html
2516 /// [`IndexMut`]: ops/trait.IndexMut.html
2518 /// This new slice goes from `begin` to `end`, including `begin` but
2519 /// excluding `end`.
2521 /// To get an immutable string slice instead, see the
2522 /// [`slice_unchecked`] method.
2524 /// [`slice_unchecked`]: #method.slice_unchecked
2528 /// Callers of this function are responsible that three preconditions are
2531 /// * `begin` must come before `end`.
2532 /// * `begin` and `end` must be byte positions within the string slice.
2533 /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
2534 #[stable(feature = "str_slice_mut", since = "1.5.0")]
2535 #[rustc_deprecated(since = "1.29.0", reason = "use `get_unchecked_mut(begin..end)` instead")]
2537 pub unsafe fn slice_mut_unchecked(&mut self, begin: usize, end: usize) -> &mut str {
2538 (begin..end).get_unchecked_mut(self)
2541 /// Divide one string slice into two at an index.
2543 /// The argument, `mid`, should be a byte offset from the start of the
2544 /// string. It must also be on the boundary of a UTF-8 code point.
2546 /// The two slices returned go from the start of the string slice to `mid`,
2547 /// and from `mid` to the end of the string slice.
2549 /// To get mutable string slices instead, see the [`split_at_mut`]
2552 /// [`split_at_mut`]: #method.split_at_mut
2556 /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
2557 /// beyond the last code point of the string slice.
2564 /// let s = "Per Martin-Löf";
2566 /// let (first, last) = s.split_at(3);
2568 /// assert_eq!("Per", first);
2569 /// assert_eq!(" Martin-Löf", last);
2572 #[stable(feature = "str_split_at", since = "1.4.0")]
2573 pub fn split_at(&self, mid: usize) -> (&str, &str) {
2574 // is_char_boundary checks that the index is in [0, .len()]
2575 if self.is_char_boundary(mid) {
2576 unsafe { (self.get_unchecked(0..mid), self.get_unchecked(mid..self.len())) }
2578 slice_error_fail(self, 0, mid)
2582 /// Divide one mutable string slice into two at an index.
2584 /// The argument, `mid`, should be a byte offset from the start of the
2585 /// string. It must also be on the boundary of a UTF-8 code point.
2587 /// The two slices returned go from the start of the string slice to `mid`,
2588 /// and from `mid` to the end of the string slice.
2590 /// To get immutable string slices instead, see the [`split_at`] method.
2592 /// [`split_at`]: #method.split_at
2596 /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
2597 /// beyond the last code point of the string slice.
2604 /// let mut s = "Per Martin-Löf".to_string();
2606 /// let (first, last) = s.split_at_mut(3);
2607 /// first.make_ascii_uppercase();
2608 /// assert_eq!("PER", first);
2609 /// assert_eq!(" Martin-Löf", last);
2611 /// assert_eq!("PER Martin-Löf", s);
2614 #[stable(feature = "str_split_at", since = "1.4.0")]
2615 pub fn split_at_mut(&mut self, mid: usize) -> (&mut str, &mut str) {
2616 // is_char_boundary checks that the index is in [0, .len()]
2617 if self.is_char_boundary(mid) {
2618 let len = self.len();
2619 let ptr = self.as_mut_ptr();
2622 from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, mid)),
2623 from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr.add(mid), len - mid)),
2627 slice_error_fail(self, 0, mid)
2631 /// Returns an iterator over the [`char`]s of a string slice.
2633 /// As a string slice consists of valid UTF-8, we can iterate through a
2634 /// string slice by [`char`]. This method returns such an iterator.
2636 /// It's important to remember that [`char`] represents a Unicode Scalar
2637 /// Value, and may not match your idea of what a 'character' is. Iteration
2638 /// over grapheme clusters may be what you actually want.
2645 /// let word = "goodbye";
2647 /// let count = word.chars().count();
2648 /// assert_eq!(7, count);
2650 /// let mut chars = word.chars();
2652 /// assert_eq!(Some('g'), chars.next());
2653 /// assert_eq!(Some('o'), chars.next());
2654 /// assert_eq!(Some('o'), chars.next());
2655 /// assert_eq!(Some('d'), chars.next());
2656 /// assert_eq!(Some('b'), chars.next());
2657 /// assert_eq!(Some('y'), chars.next());
2658 /// assert_eq!(Some('e'), chars.next());
2660 /// assert_eq!(None, chars.next());
2663 /// Remember, [`char`]s may not match your human intuition about characters:
2668 /// let mut chars = y.chars();
2670 /// assert_eq!(Some('y'), chars.next()); // not 'y̆'
2671 /// assert_eq!(Some('\u{0306}'), chars.next());
2673 /// assert_eq!(None, chars.next());
2675 #[stable(feature = "rust1", since = "1.0.0")]
2677 pub fn chars(&self) -> Chars<'_> {
2678 Chars { iter: self.as_bytes().iter() }
2681 /// Returns an iterator over the [`char`]s of a string slice, and their
2684 /// As a string slice consists of valid UTF-8, we can iterate through a
2685 /// string slice by [`char`]. This method returns an iterator of both
2686 /// these [`char`]s, as well as their byte positions.
2688 /// The iterator yields tuples. The position is first, the [`char`] is
2696 /// let word = "goodbye";
2698 /// let count = word.char_indices().count();
2699 /// assert_eq!(7, count);
2701 /// let mut char_indices = word.char_indices();
2703 /// assert_eq!(Some((0, 'g')), char_indices.next());
2704 /// assert_eq!(Some((1, 'o')), char_indices.next());
2705 /// assert_eq!(Some((2, 'o')), char_indices.next());
2706 /// assert_eq!(Some((3, 'd')), char_indices.next());
2707 /// assert_eq!(Some((4, 'b')), char_indices.next());
2708 /// assert_eq!(Some((5, 'y')), char_indices.next());
2709 /// assert_eq!(Some((6, 'e')), char_indices.next());
2711 /// assert_eq!(None, char_indices.next());
2714 /// Remember, [`char`]s may not match your human intuition about characters:
2717 /// let yes = "y̆es";
2719 /// let mut char_indices = yes.char_indices();
2721 /// assert_eq!(Some((0, 'y')), char_indices.next()); // not (0, 'y̆')
2722 /// assert_eq!(Some((1, '\u{0306}')), char_indices.next());
2724 /// // note the 3 here - the last character took up two bytes
2725 /// assert_eq!(Some((3, 'e')), char_indices.next());
2726 /// assert_eq!(Some((4, 's')), char_indices.next());
2728 /// assert_eq!(None, char_indices.next());
2730 #[stable(feature = "rust1", since = "1.0.0")]
2732 pub fn char_indices(&self) -> CharIndices<'_> {
2733 CharIndices { front_offset: 0, iter: self.chars() }
2736 /// An iterator over the bytes of a string slice.
2738 /// As a string slice consists of a sequence of bytes, we can iterate
2739 /// through a string slice by byte. This method returns such an iterator.
2746 /// let mut bytes = "bors".bytes();
2748 /// assert_eq!(Some(b'b'), bytes.next());
2749 /// assert_eq!(Some(b'o'), bytes.next());
2750 /// assert_eq!(Some(b'r'), bytes.next());
2751 /// assert_eq!(Some(b's'), bytes.next());
2753 /// assert_eq!(None, bytes.next());
2755 #[stable(feature = "rust1", since = "1.0.0")]
2757 pub fn bytes(&self) -> Bytes<'_> {
2758 Bytes(self.as_bytes().iter().cloned())
2761 /// Splits a string slice by whitespace.
2763 /// The iterator returned will return string slices that are sub-slices of
2764 /// the original string slice, separated by any amount of whitespace.
2766 /// 'Whitespace' is defined according to the terms of the Unicode Derived
2767 /// Core Property `White_Space`. If you only want to split on ASCII whitespace
2768 /// instead, use [`split_ascii_whitespace`].
2770 /// [`split_ascii_whitespace`]: #method.split_ascii_whitespace
2777 /// let mut iter = "A few words".split_whitespace();
2779 /// assert_eq!(Some("A"), iter.next());
2780 /// assert_eq!(Some("few"), iter.next());
2781 /// assert_eq!(Some("words"), iter.next());
2783 /// assert_eq!(None, iter.next());
2786 /// All kinds of whitespace are considered:
2789 /// let mut iter = " Mary had\ta\u{2009}little \n\t lamb".split_whitespace();
2790 /// assert_eq!(Some("Mary"), iter.next());
2791 /// assert_eq!(Some("had"), iter.next());
2792 /// assert_eq!(Some("a"), iter.next());
2793 /// assert_eq!(Some("little"), iter.next());
2794 /// assert_eq!(Some("lamb"), iter.next());
2796 /// assert_eq!(None, iter.next());
2798 #[stable(feature = "split_whitespace", since = "1.1.0")]
2800 pub fn split_whitespace(&self) -> SplitWhitespace<'_> {
2801 SplitWhitespace { inner: self.split(IsWhitespace).filter(IsNotEmpty) }
2804 /// Splits a string slice by ASCII whitespace.
2806 /// The iterator returned will return string slices that are sub-slices of
2807 /// the original string slice, separated by any amount of ASCII whitespace.
2809 /// To split by Unicode `Whitespace` instead, use [`split_whitespace`].
2811 /// [`split_whitespace`]: #method.split_whitespace
2818 /// let mut iter = "A few words".split_ascii_whitespace();
2820 /// assert_eq!(Some("A"), iter.next());
2821 /// assert_eq!(Some("few"), iter.next());
2822 /// assert_eq!(Some("words"), iter.next());
2824 /// assert_eq!(None, iter.next());
2827 /// All kinds of ASCII whitespace are considered:
2830 /// let mut iter = " Mary had\ta little \n\t lamb".split_ascii_whitespace();
2831 /// assert_eq!(Some("Mary"), iter.next());
2832 /// assert_eq!(Some("had"), iter.next());
2833 /// assert_eq!(Some("a"), iter.next());
2834 /// assert_eq!(Some("little"), iter.next());
2835 /// assert_eq!(Some("lamb"), iter.next());
2837 /// assert_eq!(None, iter.next());
2839 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
2841 pub fn split_ascii_whitespace(&self) -> SplitAsciiWhitespace<'_> {
2843 self.as_bytes().split(IsAsciiWhitespace).filter(BytesIsNotEmpty).map(UnsafeBytesToStr);
2844 SplitAsciiWhitespace { inner }
2847 /// An iterator over the lines of a string, as string slices.
2849 /// Lines are ended with either a newline (`\n`) or a carriage return with
2850 /// a line feed (`\r\n`).
2852 /// The final line ending is optional.
2859 /// let text = "foo\r\nbar\n\nbaz\n";
2860 /// let mut lines = text.lines();
2862 /// assert_eq!(Some("foo"), lines.next());
2863 /// assert_eq!(Some("bar"), lines.next());
2864 /// assert_eq!(Some(""), lines.next());
2865 /// assert_eq!(Some("baz"), lines.next());
2867 /// assert_eq!(None, lines.next());
2870 /// The final line ending isn't required:
2873 /// let text = "foo\nbar\n\r\nbaz";
2874 /// let mut lines = text.lines();
2876 /// assert_eq!(Some("foo"), lines.next());
2877 /// assert_eq!(Some("bar"), lines.next());
2878 /// assert_eq!(Some(""), lines.next());
2879 /// assert_eq!(Some("baz"), lines.next());
2881 /// assert_eq!(None, lines.next());
2883 #[stable(feature = "rust1", since = "1.0.0")]
2885 pub fn lines(&self) -> Lines<'_> {
2886 Lines(self.split_terminator('\n').map(LinesAnyMap))
2889 /// An iterator over the lines of a string.
2890 #[stable(feature = "rust1", since = "1.0.0")]
2891 #[rustc_deprecated(since = "1.4.0", reason = "use lines() instead now")]
2893 #[allow(deprecated)]
2894 pub fn lines_any(&self) -> LinesAny<'_> {
2895 LinesAny(self.lines())
2898 /// Returns an iterator of `u16` over the string encoded as UTF-16.
2905 /// let text = "Zażółć gęślą jaźń";
2907 /// let utf8_len = text.len();
2908 /// let utf16_len = text.encode_utf16().count();
2910 /// assert!(utf16_len <= utf8_len);
2912 #[stable(feature = "encode_utf16", since = "1.8.0")]
2913 pub fn encode_utf16(&self) -> EncodeUtf16<'_> {
2914 EncodeUtf16 { chars: self.chars(), extra: 0 }
2917 /// Returns `true` if the given pattern matches a sub-slice of
2918 /// this string slice.
2920 /// Returns `false` if it does not.
2927 /// let bananas = "bananas";
2929 /// assert!(bananas.contains("nana"));
2930 /// assert!(!bananas.contains("apples"));
2932 #[stable(feature = "rust1", since = "1.0.0")]
2934 pub fn contains<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool {
2935 pat.is_contained_in(self)
2938 /// Returns `true` if the given pattern matches a prefix of this
2941 /// Returns `false` if it does not.
2948 /// let bananas = "bananas";
2950 /// assert!(bananas.starts_with("bana"));
2951 /// assert!(!bananas.starts_with("nana"));
2953 #[stable(feature = "rust1", since = "1.0.0")]
2954 pub fn starts_with<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool {
2955 pat.is_prefix_of(self)
2958 /// Returns `true` if the given pattern matches a suffix of this
2961 /// Returns `false` if it does not.
2968 /// let bananas = "bananas";
2970 /// assert!(bananas.ends_with("anas"));
2971 /// assert!(!bananas.ends_with("nana"));
2973 #[stable(feature = "rust1", since = "1.0.0")]
2974 pub fn ends_with<'a, P>(&'a self, pat: P) -> bool
2976 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
2978 pat.is_suffix_of(self)
2981 /// Returns the byte index of the first character of this string slice that
2982 /// matches the pattern.
2984 /// Returns [`None`] if the pattern doesn't match.
2986 /// The pattern can be a `&str`, [`char`], or a closure that determines if
2987 /// a character matches.
2989 /// [`None`]: option/enum.Option.html#variant.None
2993 /// Simple patterns:
2996 /// let s = "Löwe 老虎 Léopard";
2998 /// assert_eq!(s.find('L'), Some(0));
2999 /// assert_eq!(s.find('é'), Some(14));
3000 /// assert_eq!(s.find("Léopard"), Some(13));
3003 /// More complex patterns using point-free style and closures:
3006 /// let s = "Löwe 老虎 Léopard";
3008 /// assert_eq!(s.find(char::is_whitespace), Some(5));
3009 /// assert_eq!(s.find(char::is_lowercase), Some(1));
3010 /// assert_eq!(s.find(|c: char| c.is_whitespace() || c.is_lowercase()), Some(1));
3011 /// assert_eq!(s.find(|c: char| (c < 'o') && (c > 'a')), Some(4));
3014 /// Not finding the pattern:
3017 /// let s = "Löwe 老虎 Léopard";
3018 /// let x: &[_] = &['1', '2'];
3020 /// assert_eq!(s.find(x), None);
3022 #[stable(feature = "rust1", since = "1.0.0")]
3024 pub fn find<'a, P: Pattern<'a>>(&'a self, pat: P) -> Option<usize> {
3025 pat.into_searcher(self).next_match().map(|(i, _)| i)
3028 /// Returns the byte index of the last character of this string slice that
3029 /// matches the pattern.
3031 /// Returns [`None`] if the pattern doesn't match.
3033 /// The pattern can be a `&str`, [`char`], or a closure that determines if
3034 /// a character matches.
3036 /// [`None`]: option/enum.Option.html#variant.None
3040 /// Simple patterns:
3043 /// let s = "Löwe 老虎 Léopard";
3045 /// assert_eq!(s.rfind('L'), Some(13));
3046 /// assert_eq!(s.rfind('é'), Some(14));
3049 /// More complex patterns with closures:
3052 /// let s = "Löwe 老虎 Léopard";
3054 /// assert_eq!(s.rfind(char::is_whitespace), Some(12));
3055 /// assert_eq!(s.rfind(char::is_lowercase), Some(20));
3058 /// Not finding the pattern:
3061 /// let s = "Löwe 老虎 Léopard";
3062 /// let x: &[_] = &['1', '2'];
3064 /// assert_eq!(s.rfind(x), None);
3066 #[stable(feature = "rust1", since = "1.0.0")]
3068 pub fn rfind<'a, P>(&'a self, pat: P) -> Option<usize>
3070 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3072 pat.into_searcher(self).next_match_back().map(|(i, _)| i)
3075 /// An iterator over substrings of this string slice, separated by
3076 /// characters matched by a pattern.
3078 /// The pattern can be any type that implements the Pattern trait. Notable
3079 /// examples are `&str`, [`char`], and closures that determines the split.
3081 /// # Iterator behavior
3083 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3084 /// allows a reverse search and forward/reverse search yields the same
3085 /// elements. This is true for, e.g., [`char`], but not for `&str`.
3087 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3089 /// If the pattern allows a reverse search but its results might differ
3090 /// from a forward search, the [`rsplit`] method can be used.
3092 /// [`rsplit`]: #method.rsplit
3096 /// Simple patterns:
3099 /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
3100 /// assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);
3102 /// let v: Vec<&str> = "".split('X').collect();
3103 /// assert_eq!(v, [""]);
3105 /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
3106 /// assert_eq!(v, ["lion", "", "tiger", "leopard"]);
3108 /// let v: Vec<&str> = "lion::tiger::leopard".split("::").collect();
3109 /// assert_eq!(v, ["lion", "tiger", "leopard"]);
3111 /// let v: Vec<&str> = "abc1def2ghi".split(char::is_numeric).collect();
3112 /// assert_eq!(v, ["abc", "def", "ghi"]);
3114 /// let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect();
3115 /// assert_eq!(v, ["lion", "tiger", "leopard"]);
3118 /// A more complex pattern, using a closure:
3121 /// let v: Vec<&str> = "abc1defXghi".split(|c| c == '1' || c == 'X').collect();
3122 /// assert_eq!(v, ["abc", "def", "ghi"]);
3125 /// If a string contains multiple contiguous separators, you will end up
3126 /// with empty strings in the output:
3129 /// let x = "||||a||b|c".to_string();
3130 /// let d: Vec<_> = x.split('|').collect();
3132 /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
3135 /// Contiguous separators are separated by the empty string.
3138 /// let x = "(///)".to_string();
3139 /// let d: Vec<_> = x.split('/').collect();
3141 /// assert_eq!(d, &["(", "", "", ")"]);
3144 /// Separators at the start or end of a string are neighbored
3145 /// by empty strings.
3148 /// let d: Vec<_> = "010".split("0").collect();
3149 /// assert_eq!(d, &["", "1", ""]);
3152 /// When the empty string is used as a separator, it separates
3153 /// every character in the string, along with the beginning
3154 /// and end of the string.
3157 /// let f: Vec<_> = "rust".split("").collect();
3158 /// assert_eq!(f, &["", "r", "u", "s", "t", ""]);
3161 /// Contiguous separators can lead to possibly surprising behavior
3162 /// when whitespace is used as the separator. This code is correct:
3165 /// let x = " a b c".to_string();
3166 /// let d: Vec<_> = x.split(' ').collect();
3168 /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
3171 /// It does _not_ give you:
3174 /// assert_eq!(d, &["a", "b", "c"]);
3177 /// Use [`split_whitespace`] for this behavior.
3179 /// [`split_whitespace`]: #method.split_whitespace
3180 #[stable(feature = "rust1", since = "1.0.0")]
3182 pub fn split<'a, P: Pattern<'a>>(&'a self, pat: P) -> Split<'a, P> {
3183 Split(SplitInternal {
3186 matcher: pat.into_searcher(self),
3187 allow_trailing_empty: true,
3192 /// An iterator over substrings of the given string slice, separated by
3193 /// characters matched by a pattern and yielded in reverse order.
3195 /// The pattern can be any type that implements the Pattern trait. Notable
3196 /// examples are `&str`, [`char`], and closures that determines the split.
3198 /// # Iterator behavior
3200 /// The returned iterator requires that the pattern supports a reverse
3201 /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
3202 /// search yields the same elements.
3204 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3206 /// For iterating from the front, the [`split`] method can be used.
3208 /// [`split`]: #method.split
3212 /// Simple patterns:
3215 /// let v: Vec<&str> = "Mary had a little lamb".rsplit(' ').collect();
3216 /// assert_eq!(v, ["lamb", "little", "a", "had", "Mary"]);
3218 /// let v: Vec<&str> = "".rsplit('X').collect();
3219 /// assert_eq!(v, [""]);
3221 /// let v: Vec<&str> = "lionXXtigerXleopard".rsplit('X').collect();
3222 /// assert_eq!(v, ["leopard", "tiger", "", "lion"]);
3224 /// let v: Vec<&str> = "lion::tiger::leopard".rsplit("::").collect();
3225 /// assert_eq!(v, ["leopard", "tiger", "lion"]);
3228 /// A more complex pattern, using a closure:
3231 /// let v: Vec<&str> = "abc1defXghi".rsplit(|c| c == '1' || c == 'X').collect();
3232 /// assert_eq!(v, ["ghi", "def", "abc"]);
3234 #[stable(feature = "rust1", since = "1.0.0")]
3236 pub fn rsplit<'a, P>(&'a self, pat: P) -> RSplit<'a, P>
3238 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3240 RSplit(self.split(pat).0)
3243 /// An iterator over substrings of the given string slice, separated by
3244 /// characters matched by a pattern.
3246 /// The pattern can be any type that implements the Pattern trait. Notable
3247 /// examples are `&str`, [`char`], and closures that determines the split.
3249 /// Equivalent to [`split`], except that the trailing substring
3250 /// is skipped if empty.
3252 /// [`split`]: #method.split
3254 /// This method can be used for string data that is _terminated_,
3255 /// rather than _separated_ by a pattern.
3257 /// # Iterator behavior
3259 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3260 /// allows a reverse search and forward/reverse search yields the same
3261 /// elements. This is true for, e.g., [`char`], but not for `&str`.
3263 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3265 /// If the pattern allows a reverse search but its results might differ
3266 /// from a forward search, the [`rsplit_terminator`] method can be used.
3268 /// [`rsplit_terminator`]: #method.rsplit_terminator
3275 /// let v: Vec<&str> = "A.B.".split_terminator('.').collect();
3276 /// assert_eq!(v, ["A", "B"]);
3278 /// let v: Vec<&str> = "A..B..".split_terminator(".").collect();
3279 /// assert_eq!(v, ["A", "", "B", ""]);
3281 #[stable(feature = "rust1", since = "1.0.0")]
3283 pub fn split_terminator<'a, P: Pattern<'a>>(&'a self, pat: P) -> SplitTerminator<'a, P> {
3284 SplitTerminator(SplitInternal { allow_trailing_empty: false, ..self.split(pat).0 })
3287 /// An iterator over substrings of `self`, separated by characters
3288 /// matched by a pattern and yielded in reverse order.
3290 /// The pattern can be any type that implements the Pattern trait. Notable
3291 /// examples are `&str`, [`char`], and closures that determines the split.
3292 /// Additional libraries might provide more complex patterns like
3293 /// regular expressions.
3295 /// Equivalent to [`split`], except that the trailing substring is
3296 /// skipped if empty.
3298 /// [`split`]: #method.split
3300 /// This method can be used for string data that is _terminated_,
3301 /// rather than _separated_ by a pattern.
3303 /// # Iterator behavior
3305 /// The returned iterator requires that the pattern supports a
3306 /// reverse search, and it will be double ended if a forward/reverse
3307 /// search yields the same elements.
3309 /// For iterating from the front, the [`split_terminator`] method can be
3312 /// [`split_terminator`]: #method.split_terminator
3317 /// let v: Vec<&str> = "A.B.".rsplit_terminator('.').collect();
3318 /// assert_eq!(v, ["B", "A"]);
3320 /// let v: Vec<&str> = "A..B..".rsplit_terminator(".").collect();
3321 /// assert_eq!(v, ["", "B", "", "A"]);
3323 #[stable(feature = "rust1", since = "1.0.0")]
3325 pub fn rsplit_terminator<'a, P>(&'a self, pat: P) -> RSplitTerminator<'a, P>
3327 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3329 RSplitTerminator(self.split_terminator(pat).0)
3332 /// An iterator over substrings of the given string slice, separated by a
3333 /// pattern, restricted to returning at most `n` items.
3335 /// If `n` substrings are returned, the last substring (the `n`th substring)
3336 /// will contain the remainder of the string.
3338 /// The pattern can be any type that implements the Pattern trait. Notable
3339 /// examples are `&str`, [`char`], and closures that determines the split.
3341 /// # Iterator behavior
3343 /// The returned iterator will not be double ended, because it is
3344 /// not efficient to support.
3346 /// If the pattern allows a reverse search, the [`rsplitn`] method can be
3349 /// [`rsplitn`]: #method.rsplitn
3353 /// Simple patterns:
3356 /// let v: Vec<&str> = "Mary had a little lambda".splitn(3, ' ').collect();
3357 /// assert_eq!(v, ["Mary", "had", "a little lambda"]);
3359 /// let v: Vec<&str> = "lionXXtigerXleopard".splitn(3, "X").collect();
3360 /// assert_eq!(v, ["lion", "", "tigerXleopard"]);
3362 /// let v: Vec<&str> = "abcXdef".splitn(1, 'X').collect();
3363 /// assert_eq!(v, ["abcXdef"]);
3365 /// let v: Vec<&str> = "".splitn(1, 'X').collect();
3366 /// assert_eq!(v, [""]);
3369 /// A more complex pattern, using a closure:
3372 /// let v: Vec<&str> = "abc1defXghi".splitn(2, |c| c == '1' || c == 'X').collect();
3373 /// assert_eq!(v, ["abc", "defXghi"]);
3375 #[stable(feature = "rust1", since = "1.0.0")]
3377 pub fn splitn<'a, P: Pattern<'a>>(&'a self, n: usize, pat: P) -> SplitN<'a, P> {
3378 SplitN(SplitNInternal { iter: self.split(pat).0, count: n })
3381 /// An iterator over substrings of this string slice, separated by a
3382 /// pattern, starting from the end of the string, restricted to returning
3383 /// at most `n` items.
3385 /// If `n` substrings are returned, the last substring (the `n`th substring)
3386 /// will contain the remainder of the string.
3388 /// The pattern can be any type that implements the Pattern trait. Notable
3389 /// examples are `&str`, [`char`], and closures that determines the split.
3391 /// # Iterator behavior
3393 /// The returned iterator will not be double ended, because it is not
3394 /// efficient to support.
3396 /// For splitting from the front, the [`splitn`] method can be used.
3398 /// [`splitn`]: #method.splitn
3402 /// Simple patterns:
3405 /// let v: Vec<&str> = "Mary had a little lamb".rsplitn(3, ' ').collect();
3406 /// assert_eq!(v, ["lamb", "little", "Mary had a"]);
3408 /// let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(3, 'X').collect();
3409 /// assert_eq!(v, ["leopard", "tiger", "lionX"]);
3411 /// let v: Vec<&str> = "lion::tiger::leopard".rsplitn(2, "::").collect();
3412 /// assert_eq!(v, ["leopard", "lion::tiger"]);
3415 /// A more complex pattern, using a closure:
3418 /// let v: Vec<&str> = "abc1defXghi".rsplitn(2, |c| c == '1' || c == 'X').collect();
3419 /// assert_eq!(v, ["ghi", "abc1def"]);
3421 #[stable(feature = "rust1", since = "1.0.0")]
3423 pub fn rsplitn<'a, P>(&'a self, n: usize, pat: P) -> RSplitN<'a, P>
3425 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3427 RSplitN(self.splitn(n, pat).0)
3430 /// An iterator over the disjoint matches of a pattern within the given string
3433 /// The pattern can be a `&str`, [`char`], or a closure that determines if
3434 /// a character matches.
3436 /// # Iterator behavior
3438 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3439 /// allows a reverse search and forward/reverse search yields the same
3440 /// elements. This is true for, e.g., [`char`], but not for `&str`.
3442 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3444 /// If the pattern allows a reverse search but its results might differ
3445 /// from a forward search, the [`rmatches`] method can be used.
3447 /// [`rmatches`]: #method.rmatches
3454 /// let v: Vec<&str> = "abcXXXabcYYYabc".matches("abc").collect();
3455 /// assert_eq!(v, ["abc", "abc", "abc"]);
3457 /// let v: Vec<&str> = "1abc2abc3".matches(char::is_numeric).collect();
3458 /// assert_eq!(v, ["1", "2", "3"]);
3460 #[stable(feature = "str_matches", since = "1.2.0")]
3462 pub fn matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> Matches<'a, P> {
3463 Matches(MatchesInternal(pat.into_searcher(self)))
3466 /// An iterator over the disjoint matches of a pattern within this string slice,
3467 /// yielded in reverse order.
3469 /// The pattern can be a `&str`, [`char`], or a closure that determines if
3470 /// a character matches.
3472 /// # Iterator behavior
3474 /// The returned iterator requires that the pattern supports a reverse
3475 /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
3476 /// search yields the same elements.
3478 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3480 /// For iterating from the front, the [`matches`] method can be used.
3482 /// [`matches`]: #method.matches
3489 /// let v: Vec<&str> = "abcXXXabcYYYabc".rmatches("abc").collect();
3490 /// assert_eq!(v, ["abc", "abc", "abc"]);
3492 /// let v: Vec<&str> = "1abc2abc3".rmatches(char::is_numeric).collect();
3493 /// assert_eq!(v, ["3", "2", "1"]);
3495 #[stable(feature = "str_matches", since = "1.2.0")]
3497 pub fn rmatches<'a, P>(&'a self, pat: P) -> RMatches<'a, P>
3499 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3501 RMatches(self.matches(pat).0)
3504 /// An iterator over the disjoint matches of a pattern within this string
3505 /// slice as well as the index that the match starts at.
3507 /// For matches of `pat` within `self` that overlap, only the indices
3508 /// corresponding to the first match are returned.
3510 /// The pattern can be a `&str`, [`char`], or a closure that determines
3511 /// if a character matches.
3513 /// # Iterator behavior
3515 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3516 /// allows a reverse search and forward/reverse search yields the same
3517 /// elements. This is true for, e.g., [`char`], but not for `&str`.
3519 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3521 /// If the pattern allows a reverse search but its results might differ
3522 /// from a forward search, the [`rmatch_indices`] method can be used.
3524 /// [`rmatch_indices`]: #method.rmatch_indices
3531 /// let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
3532 /// assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
3534 /// let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
3535 /// assert_eq!(v, [(1, "abc"), (4, "abc")]);
3537 /// let v: Vec<_> = "ababa".match_indices("aba").collect();
3538 /// assert_eq!(v, [(0, "aba")]); // only the first `aba`
3540 #[stable(feature = "str_match_indices", since = "1.5.0")]
3542 pub fn match_indices<'a, P: Pattern<'a>>(&'a self, pat: P) -> MatchIndices<'a, P> {
3543 MatchIndices(MatchIndicesInternal(pat.into_searcher(self)))
3546 /// An iterator over the disjoint matches of a pattern within `self`,
3547 /// yielded in reverse order along with the index of the match.
3549 /// For matches of `pat` within `self` that overlap, only the indices
3550 /// corresponding to the last match are returned.
3552 /// The pattern can be a `&str`, [`char`], or a closure that determines if a
3553 /// character matches.
3555 /// # Iterator behavior
3557 /// The returned iterator requires that the pattern supports a reverse
3558 /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
3559 /// search yields the same elements.
3561 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3563 /// For iterating from the front, the [`match_indices`] method can be used.
3565 /// [`match_indices`]: #method.match_indices
3572 /// let v: Vec<_> = "abcXXXabcYYYabc".rmatch_indices("abc").collect();
3573 /// assert_eq!(v, [(12, "abc"), (6, "abc"), (0, "abc")]);
3575 /// let v: Vec<_> = "1abcabc2".rmatch_indices("abc").collect();
3576 /// assert_eq!(v, [(4, "abc"), (1, "abc")]);
3578 /// let v: Vec<_> = "ababa".rmatch_indices("aba").collect();
3579 /// assert_eq!(v, [(2, "aba")]); // only the last `aba`
3581 #[stable(feature = "str_match_indices", since = "1.5.0")]
3583 pub fn rmatch_indices<'a, P>(&'a self, pat: P) -> RMatchIndices<'a, P>
3585 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3587 RMatchIndices(self.match_indices(pat).0)
3590 /// Returns a string slice with leading and trailing whitespace removed.
3592 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3593 /// Core Property `White_Space`.
3600 /// let s = " Hello\tworld\t";
3602 /// assert_eq!("Hello\tworld", s.trim());
3604 #[must_use = "this returns the trimmed string as a slice, \
3605 without modifying the original"]
3606 #[stable(feature = "rust1", since = "1.0.0")]
3607 pub fn trim(&self) -> &str {
3608 self.trim_matches(|c: char| c.is_whitespace())
3611 /// Returns a string slice with leading whitespace removed.
3613 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3614 /// Core Property `White_Space`.
3616 /// # Text directionality
3618 /// A string is a sequence of bytes. `start` in this context means the first
3619 /// position of that byte string; for a left-to-right language like English or
3620 /// Russian, this will be left side, and for right-to-left languages like
3621 /// Arabic or Hebrew, this will be the right side.
3628 /// let s = " Hello\tworld\t";
3629 /// assert_eq!("Hello\tworld\t", s.trim_start());
3635 /// let s = " English ";
3636 /// assert!(Some('E') == s.trim_start().chars().next());
3638 /// let s = " עברית ";
3639 /// assert!(Some('ע') == s.trim_start().chars().next());
3641 #[must_use = "this returns the trimmed string as a new slice, \
3642 without modifying the original"]
3643 #[stable(feature = "trim_direction", since = "1.30.0")]
3644 pub fn trim_start(&self) -> &str {
3645 self.trim_start_matches(|c: char| c.is_whitespace())
3648 /// Returns a string slice with trailing whitespace removed.
3650 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3651 /// Core Property `White_Space`.
3653 /// # Text directionality
3655 /// A string is a sequence of bytes. `end` in this context means the last
3656 /// position of that byte string; for a left-to-right language like English or
3657 /// Russian, this will be right side, and for right-to-left languages like
3658 /// Arabic or Hebrew, this will be the left side.
3665 /// let s = " Hello\tworld\t";
3666 /// assert_eq!(" Hello\tworld", s.trim_end());
3672 /// let s = " English ";
3673 /// assert!(Some('h') == s.trim_end().chars().rev().next());
3675 /// let s = " עברית ";
3676 /// assert!(Some('ת') == s.trim_end().chars().rev().next());
3678 #[must_use = "this returns the trimmed string as a new slice, \
3679 without modifying the original"]
3680 #[stable(feature = "trim_direction", since = "1.30.0")]
3681 pub fn trim_end(&self) -> &str {
3682 self.trim_end_matches(|c: char| c.is_whitespace())
3685 /// Returns a string slice with leading whitespace removed.
3687 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3688 /// Core Property `White_Space`.
3690 /// # Text directionality
3692 /// A string is a sequence of bytes. 'Left' in this context means the first
3693 /// position of that byte string; for a language like Arabic or Hebrew
3694 /// which are 'right to left' rather than 'left to right', this will be
3695 /// the _right_ side, not the left.
3702 /// let s = " Hello\tworld\t";
3704 /// assert_eq!("Hello\tworld\t", s.trim_left());
3710 /// let s = " English";
3711 /// assert!(Some('E') == s.trim_left().chars().next());
3713 /// let s = " עברית";
3714 /// assert!(Some('ע') == s.trim_left().chars().next());
3716 #[stable(feature = "rust1", since = "1.0.0")]
3719 reason = "superseded by `trim_start`",
3720 suggestion = "trim_start"
3722 pub fn trim_left(&self) -> &str {
3726 /// Returns a string slice with trailing whitespace removed.
3728 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3729 /// Core Property `White_Space`.
3731 /// # Text directionality
3733 /// A string is a sequence of bytes. 'Right' in this context means the last
3734 /// position of that byte string; for a language like Arabic or Hebrew
3735 /// which are 'right to left' rather than 'left to right', this will be
3736 /// the _left_ side, not the right.
3743 /// let s = " Hello\tworld\t";
3745 /// assert_eq!(" Hello\tworld", s.trim_right());
3751 /// let s = "English ";
3752 /// assert!(Some('h') == s.trim_right().chars().rev().next());
3754 /// let s = "עברית ";
3755 /// assert!(Some('ת') == s.trim_right().chars().rev().next());
3757 #[stable(feature = "rust1", since = "1.0.0")]
3760 reason = "superseded by `trim_end`",
3761 suggestion = "trim_end"
3763 pub fn trim_right(&self) -> &str {
3767 /// Returns a string slice with all prefixes and suffixes that match a
3768 /// pattern repeatedly removed.
3770 /// The pattern can be a [`char`] or a closure that determines if a
3771 /// character matches.
3775 /// Simple patterns:
3778 /// assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar");
3779 /// assert_eq!("123foo1bar123".trim_matches(char::is_numeric), "foo1bar");
3781 /// let x: &[_] = &['1', '2'];
3782 /// assert_eq!("12foo1bar12".trim_matches(x), "foo1bar");
3785 /// A more complex pattern, using a closure:
3788 /// assert_eq!("1foo1barXX".trim_matches(|c| c == '1' || c == 'X'), "foo1bar");
3790 #[must_use = "this returns the trimmed string as a new slice, \
3791 without modifying the original"]
3792 #[stable(feature = "rust1", since = "1.0.0")]
3793 pub fn trim_matches<'a, P>(&'a self, pat: P) -> &'a str
3795 P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>,
3799 let mut matcher = pat.into_searcher(self);
3800 if let Some((a, b)) = matcher.next_reject() {
3802 j = b; // Remember earliest known match, correct it below if
3803 // last match is different
3805 if let Some((_, b)) = matcher.next_reject_back() {
3809 // Searcher is known to return valid indices
3810 self.get_unchecked(i..j)
3814 /// Returns a string slice with all prefixes that match a pattern
3815 /// repeatedly removed.
3817 /// The pattern can be a `&str`, [`char`], or a closure that determines if
3818 /// a character matches.
3820 /// # Text directionality
3822 /// A string is a sequence of bytes. `start` in this context means the first
3823 /// position of that byte string; for a left-to-right language like English or
3824 /// Russian, this will be left side, and for right-to-left languages like
3825 /// Arabic or Hebrew, this will be the right side.
3832 /// assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11");
3833 /// assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric), "foo1bar123");
3835 /// let x: &[_] = &['1', '2'];
3836 /// assert_eq!("12foo1bar12".trim_start_matches(x), "foo1bar12");
3838 #[must_use = "this returns the trimmed string as a new slice, \
3839 without modifying the original"]
3840 #[stable(feature = "trim_direction", since = "1.30.0")]
3841 pub fn trim_start_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str {
3842 let mut i = self.len();
3843 let mut matcher = pat.into_searcher(self);
3844 if let Some((a, _)) = matcher.next_reject() {
3848 // Searcher is known to return valid indices
3849 self.get_unchecked(i..self.len())
3853 /// Returns a string slice with the prefix removed.
3855 /// If the string starts with the pattern `prefix`, `Some` is returned with the substring where
3856 /// the prefix is removed. Unlike `trim_start_matches`, this method removes the prefix exactly
3859 /// If the string does not start with `prefix`, `None` is returned.
3864 /// #![feature(str_strip)]
3866 /// assert_eq!("foobar".strip_prefix("foo"), Some("bar"));
3867 /// assert_eq!("foobar".strip_prefix("bar"), None);
3868 /// assert_eq!("foofoo".strip_prefix("foo"), Some("foo"));
3870 #[must_use = "this returns the remaining substring as a new slice, \
3871 without modifying the original"]
3872 #[unstable(feature = "str_strip", reason = "newly added", issue = "67302")]
3873 pub fn strip_prefix<'a, P: Pattern<'a>>(&'a self, prefix: P) -> Option<&'a str> {
3874 let mut matcher = prefix.into_searcher(self);
3875 if let SearchStep::Match(start, len) = matcher.next() {
3878 "The first search step from Searcher \
3879 must include the first character"
3882 // Searcher is known to return valid indices.
3883 Some(self.get_unchecked(len..))
3890 /// Returns a string slice with the suffix removed.
3892 /// If the string ends with the pattern `suffix`, `Some` is returned with the substring where
3893 /// the suffix is removed. Unlike `trim_end_matches`, this method removes the suffix exactly
3896 /// If the string does not end with `suffix`, `None` is returned.
3901 /// #![feature(str_strip)]
3902 /// assert_eq!("barfoo".strip_suffix("foo"), Some("bar"));
3903 /// assert_eq!("barfoo".strip_suffix("bar"), None);
3904 /// assert_eq!("foofoo".strip_suffix("foo"), Some("foo"));
3906 #[must_use = "this returns the remaining substring as a new slice, \
3907 without modifying the original"]
3908 #[unstable(feature = "str_strip", reason = "newly added", issue = "67302")]
3909 pub fn strip_suffix<'a, P>(&'a self, suffix: P) -> Option<&'a str>
3912 <P as Pattern<'a>>::Searcher: ReverseSearcher<'a>,
3914 let mut matcher = suffix.into_searcher(self);
3915 if let SearchStep::Match(start, end) = matcher.next_back() {
3919 "The first search step from ReverseSearcher \
3920 must include the last character"
3923 // Searcher is known to return valid indices.
3924 Some(self.get_unchecked(..start))
3931 /// Returns a string slice with all suffixes that match a pattern
3932 /// repeatedly removed.
3934 /// The pattern can be a `&str`, [`char`], or a closure that
3935 /// determines if a character matches.
3937 /// # Text directionality
3939 /// A string is a sequence of bytes. `end` in this context means the last
3940 /// position of that byte string; for a left-to-right language like English or
3941 /// Russian, this will be right side, and for right-to-left languages like
3942 /// Arabic or Hebrew, this will be the left side.
3946 /// Simple patterns:
3949 /// assert_eq!("11foo1bar11".trim_end_matches('1'), "11foo1bar");
3950 /// assert_eq!("123foo1bar123".trim_end_matches(char::is_numeric), "123foo1bar");
3952 /// let x: &[_] = &['1', '2'];
3953 /// assert_eq!("12foo1bar12".trim_end_matches(x), "12foo1bar");
3956 /// A more complex pattern, using a closure:
3959 /// assert_eq!("1fooX".trim_end_matches(|c| c == '1' || c == 'X'), "1foo");
3961 #[must_use = "this returns the trimmed string as a new slice, \
3962 without modifying the original"]
3963 #[stable(feature = "trim_direction", since = "1.30.0")]
3964 pub fn trim_end_matches<'a, P>(&'a self, pat: P) -> &'a str
3966 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
3969 let mut matcher = pat.into_searcher(self);
3970 if let Some((_, b)) = matcher.next_reject_back() {
3974 // Searcher is known to return valid indices
3975 self.get_unchecked(0..j)
3979 /// Returns a string slice with all prefixes that match a pattern
3980 /// repeatedly removed.
3982 /// The pattern can be a `&str`, [`char`], or a closure that determines if
3983 /// a character matches.
3985 /// [`char`]: primitive.char.html
3987 /// # Text directionality
3989 /// A string is a sequence of bytes. 'Left' in this context means the first
3990 /// position of that byte string; for a language like Arabic or Hebrew
3991 /// which are 'right to left' rather than 'left to right', this will be
3992 /// the _right_ side, not the left.
3999 /// assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11");
4000 /// assert_eq!("123foo1bar123".trim_left_matches(char::is_numeric), "foo1bar123");
4002 /// let x: &[_] = &['1', '2'];
4003 /// assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12");
4005 #[stable(feature = "rust1", since = "1.0.0")]
4008 reason = "superseded by `trim_start_matches`",
4009 suggestion = "trim_start_matches"
4011 pub fn trim_left_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str {
4012 self.trim_start_matches(pat)
4015 /// Returns a string slice with all suffixes that match a pattern
4016 /// repeatedly removed.
4018 /// The pattern can be a `&str`, [`char`], or a closure that
4019 /// determines if a character matches.
4021 /// [`char`]: primitive.char.html
4023 /// # Text directionality
4025 /// A string is a sequence of bytes. 'Right' in this context means the last
4026 /// position of that byte string; for a language like Arabic or Hebrew
4027 /// which are 'right to left' rather than 'left to right', this will be
4028 /// the _left_ side, not the right.
4032 /// Simple patterns:
4035 /// assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar");
4036 /// assert_eq!("123foo1bar123".trim_right_matches(char::is_numeric), "123foo1bar");
4038 /// let x: &[_] = &['1', '2'];
4039 /// assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar");
4042 /// A more complex pattern, using a closure:
4045 /// assert_eq!("1fooX".trim_right_matches(|c| c == '1' || c == 'X'), "1foo");
4047 #[stable(feature = "rust1", since = "1.0.0")]
4050 reason = "superseded by `trim_end_matches`",
4051 suggestion = "trim_end_matches"
4053 pub fn trim_right_matches<'a, P>(&'a self, pat: P) -> &'a str
4055 P: Pattern<'a, Searcher: ReverseSearcher<'a>>,
4057 self.trim_end_matches(pat)
4060 /// Parses this string slice into another type.
4062 /// Because `parse` is so general, it can cause problems with type
4063 /// inference. As such, `parse` is one of the few times you'll see
4064 /// the syntax affectionately known as the 'turbofish': `::<>`. This
4065 /// helps the inference algorithm understand specifically which type
4066 /// you're trying to parse into.
4068 /// `parse` can parse any type that implements the [`FromStr`] trait.
4070 /// [`FromStr`]: str/trait.FromStr.html
4074 /// Will return [`Err`] if it's not possible to parse this string slice into
4075 /// the desired type.
4077 /// [`Err`]: str/trait.FromStr.html#associatedtype.Err
4084 /// let four: u32 = "4".parse().unwrap();
4086 /// assert_eq!(4, four);
4089 /// Using the 'turbofish' instead of annotating `four`:
4092 /// let four = "4".parse::<u32>();
4094 /// assert_eq!(Ok(4), four);
4097 /// Failing to parse:
4100 /// let nope = "j".parse::<u32>();
4102 /// assert!(nope.is_err());
4105 #[stable(feature = "rust1", since = "1.0.0")]
4106 pub fn parse<F: FromStr>(&self) -> Result<F, F::Err> {
4107 FromStr::from_str(self)
4110 /// Checks if all characters in this string are within the ASCII range.
4115 /// let ascii = "hello!\n";
4116 /// let non_ascii = "Grüße, Jürgen ❤";
4118 /// assert!(ascii.is_ascii());
4119 /// assert!(!non_ascii.is_ascii());
4121 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4123 pub fn is_ascii(&self) -> bool {
4124 // We can treat each byte as character here: all multibyte characters
4125 // start with a byte that is not in the ascii range, so we will stop
4127 self.bytes().all(|b| b.is_ascii())
4130 /// Checks that two strings are an ASCII case-insensitive match.
4132 /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
4133 /// but without allocating and copying temporaries.
4138 /// assert!("Ferris".eq_ignore_ascii_case("FERRIS"));
4139 /// assert!("Ferrös".eq_ignore_ascii_case("FERRöS"));
4140 /// assert!(!"Ferrös".eq_ignore_ascii_case("FERRÖS"));
4142 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4144 pub fn eq_ignore_ascii_case(&self, other: &str) -> bool {
4145 self.as_bytes().eq_ignore_ascii_case(other.as_bytes())
4148 /// Converts this string to its ASCII upper case equivalent in-place.
4150 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
4151 /// but non-ASCII letters are unchanged.
4153 /// To return a new uppercased value without modifying the existing one, use
4154 /// [`to_ascii_uppercase`].
4156 /// [`to_ascii_uppercase`]: #method.to_ascii_uppercase
4161 /// let mut s = String::from("Grüße, Jürgen ❤");
4163 /// s.make_ascii_uppercase();
4165 /// assert_eq!("GRüßE, JüRGEN ❤", s);
4167 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4168 pub fn make_ascii_uppercase(&mut self) {
4169 let me = unsafe { self.as_bytes_mut() };
4170 me.make_ascii_uppercase()
4173 /// Converts this string to its ASCII lower case equivalent in-place.
4175 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
4176 /// but non-ASCII letters are unchanged.
4178 /// To return a new lowercased value without modifying the existing one, use
4179 /// [`to_ascii_lowercase`].
4181 /// [`to_ascii_lowercase`]: #method.to_ascii_lowercase
4186 /// let mut s = String::from("GRÜßE, JÜRGEN ❤");
4188 /// s.make_ascii_lowercase();
4190 /// assert_eq!("grÜße, jÜrgen ❤", s);
4192 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4193 pub fn make_ascii_lowercase(&mut self) {
4194 let me = unsafe { self.as_bytes_mut() };
4195 me.make_ascii_lowercase()
4198 /// Return an iterator that escapes each char in `self` with [`char::escape_debug`].
4200 /// Note: only extended grapheme codepoints that begin the string will be
4203 /// [`char::escape_debug`]: ../std/primitive.char.html#method.escape_debug
4210 /// for c in "❤\n!".escape_debug() {
4211 /// print!("{}", c);
4216 /// Using `println!` directly:
4219 /// println!("{}", "❤\n!".escape_debug());
4223 /// Both are equivalent to:
4226 /// println!("❤\\n!");
4229 /// Using `to_string`:
4232 /// assert_eq!("❤\n!".escape_debug().to_string(), "❤\\n!");
4234 #[stable(feature = "str_escape", since = "1.34.0")]
4235 pub fn escape_debug(&self) -> EscapeDebug<'_> {
4236 let mut chars = self.chars();
4240 .map(|first| first.escape_debug_ext(true))
4243 .chain(chars.flat_map(CharEscapeDebugContinue)),
4247 /// Return an iterator that escapes each char in `self` with [`char::escape_default`].
4249 /// [`char::escape_default`]: ../std/primitive.char.html#method.escape_default
4256 /// for c in "❤\n!".escape_default() {
4257 /// print!("{}", c);
4262 /// Using `println!` directly:
4265 /// println!("{}", "❤\n!".escape_default());
4269 /// Both are equivalent to:
4272 /// println!("\\u{{2764}}\\n!");
4275 /// Using `to_string`:
4278 /// assert_eq!("❤\n!".escape_default().to_string(), "\\u{2764}\\n!");
4280 #[stable(feature = "str_escape", since = "1.34.0")]
4281 pub fn escape_default(&self) -> EscapeDefault<'_> {
4282 EscapeDefault { inner: self.chars().flat_map(CharEscapeDefault) }
4285 /// Return an iterator that escapes each char in `self` with [`char::escape_unicode`].
4287 /// [`char::escape_unicode`]: ../std/primitive.char.html#method.escape_unicode
4294 /// for c in "❤\n!".escape_unicode() {
4295 /// print!("{}", c);
4300 /// Using `println!` directly:
4303 /// println!("{}", "❤\n!".escape_unicode());
4307 /// Both are equivalent to:
4310 /// println!("\\u{{2764}}\\u{{a}}\\u{{21}}");
4313 /// Using `to_string`:
4316 /// assert_eq!("❤\n!".escape_unicode().to_string(), "\\u{2764}\\u{a}\\u{21}");
4318 #[stable(feature = "str_escape", since = "1.34.0")]
4319 pub fn escape_unicode(&self) -> EscapeUnicode<'_> {
4320 EscapeUnicode { inner: self.chars().flat_map(CharEscapeUnicode) }
4326 struct CharEscapeDebugContinue impl Fn = |c: char| -> char::EscapeDebug {
4327 c.escape_debug_ext(false)
4331 struct CharEscapeUnicode impl Fn = |c: char| -> char::EscapeUnicode {
4335 struct CharEscapeDefault impl Fn = |c: char| -> char::EscapeDefault {
4340 #[stable(feature = "rust1", since = "1.0.0")]
4341 impl AsRef<[u8]> for str {
4343 fn as_ref(&self) -> &[u8] {
4348 #[stable(feature = "rust1", since = "1.0.0")]
4349 impl Default for &str {
4350 /// Creates an empty str
4351 fn default() -> Self {
4356 #[stable(feature = "default_mut_str", since = "1.28.0")]
4357 impl Default for &mut str {
4358 /// Creates an empty mutable str
4359 fn default() -> Self {
4360 unsafe { from_utf8_unchecked_mut(&mut []) }
4364 /// An iterator over the non-whitespace substrings of a string,
4365 /// separated by any amount of whitespace.
4367 /// This struct is created by the [`split_whitespace`] method on [`str`].
4368 /// See its documentation for more.
4370 /// [`split_whitespace`]: ../../std/primitive.str.html#method.split_whitespace
4371 /// [`str`]: ../../std/primitive.str.html
4372 #[stable(feature = "split_whitespace", since = "1.1.0")]
4373 #[derive(Clone, Debug)]
4374 pub struct SplitWhitespace<'a> {
4375 inner: Filter<Split<'a, IsWhitespace>, IsNotEmpty>,
4378 /// An iterator over the non-ASCII-whitespace substrings of a string,
4379 /// separated by any amount of ASCII whitespace.
4381 /// This struct is created by the [`split_ascii_whitespace`] method on [`str`].
4382 /// See its documentation for more.
4384 /// [`split_ascii_whitespace`]: ../../std/primitive.str.html#method.split_ascii_whitespace
4385 /// [`str`]: ../../std/primitive.str.html
4386 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4387 #[derive(Clone, Debug)]
4388 pub struct SplitAsciiWhitespace<'a> {
4389 inner: Map<Filter<SliceSplit<'a, u8, IsAsciiWhitespace>, BytesIsNotEmpty>, UnsafeBytesToStr>,
4394 struct IsWhitespace impl Fn = |c: char| -> bool {
4399 struct IsAsciiWhitespace impl Fn = |byte: &u8| -> bool {
4400 byte.is_ascii_whitespace()
4404 struct IsNotEmpty impl<'a, 'b> Fn = |s: &'a &'b str| -> bool {
4409 struct BytesIsNotEmpty impl<'a, 'b> Fn = |s: &'a &'b [u8]| -> bool {
4414 struct UnsafeBytesToStr impl<'a> Fn = |bytes: &'a [u8]| -> &'a str {
4415 unsafe { from_utf8_unchecked(bytes) }
4419 #[stable(feature = "split_whitespace", since = "1.1.0")]
4420 impl<'a> Iterator for SplitWhitespace<'a> {
4421 type Item = &'a str;
4424 fn next(&mut self) -> Option<&'a str> {
4429 fn size_hint(&self) -> (usize, Option<usize>) {
4430 self.inner.size_hint()
4434 fn last(mut self) -> Option<&'a str> {
4439 #[stable(feature = "split_whitespace", since = "1.1.0")]
4440 impl<'a> DoubleEndedIterator for SplitWhitespace<'a> {
4442 fn next_back(&mut self) -> Option<&'a str> {
4443 self.inner.next_back()
4447 #[stable(feature = "fused", since = "1.26.0")]
4448 impl FusedIterator for SplitWhitespace<'_> {}
4450 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4451 impl<'a> Iterator for SplitAsciiWhitespace<'a> {
4452 type Item = &'a str;
4455 fn next(&mut self) -> Option<&'a str> {
4460 fn size_hint(&self) -> (usize, Option<usize>) {
4461 self.inner.size_hint()
4465 fn last(mut self) -> Option<&'a str> {
4470 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4471 impl<'a> DoubleEndedIterator for SplitAsciiWhitespace<'a> {
4473 fn next_back(&mut self) -> Option<&'a str> {
4474 self.inner.next_back()
4478 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4479 impl FusedIterator for SplitAsciiWhitespace<'_> {}
4481 /// An iterator of [`u16`] over the string encoded as UTF-16.
4483 /// [`u16`]: ../../std/primitive.u16.html
4485 /// This struct is created by the [`encode_utf16`] method on [`str`].
4486 /// See its documentation for more.
4488 /// [`encode_utf16`]: ../../std/primitive.str.html#method.encode_utf16
4489 /// [`str`]: ../../std/primitive.str.html
4491 #[stable(feature = "encode_utf16", since = "1.8.0")]
4492 pub struct EncodeUtf16<'a> {
4497 #[stable(feature = "collection_debug", since = "1.17.0")]
4498 impl fmt::Debug for EncodeUtf16<'_> {
4499 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
4500 f.pad("EncodeUtf16 { .. }")
4504 #[stable(feature = "encode_utf16", since = "1.8.0")]
4505 impl<'a> Iterator for EncodeUtf16<'a> {
4509 fn next(&mut self) -> Option<u16> {
4510 if self.extra != 0 {
4511 let tmp = self.extra;
4516 let mut buf = [0; 2];
4517 self.chars.next().map(|ch| {
4518 let n = ch.encode_utf16(&mut buf).len();
4520 self.extra = buf[1];
4527 fn size_hint(&self) -> (usize, Option<usize>) {
4528 let (low, high) = self.chars.size_hint();
4529 // every char gets either one u16 or two u16,
4530 // so this iterator is between 1 or 2 times as
4531 // long as the underlying iterator.
4532 (low, high.and_then(|n| n.checked_mul(2)))
4536 #[stable(feature = "fused", since = "1.26.0")]
4537 impl FusedIterator for EncodeUtf16<'_> {}
4539 /// The return type of [`str::escape_debug`].
4541 /// [`str::escape_debug`]: ../../std/primitive.str.html#method.escape_debug
4542 #[stable(feature = "str_escape", since = "1.34.0")]
4543 #[derive(Clone, Debug)]
4544 pub struct EscapeDebug<'a> {
4546 Flatten<option::IntoIter<char::EscapeDebug>>,
4547 FlatMap<Chars<'a>, char::EscapeDebug, CharEscapeDebugContinue>,
4551 /// The return type of [`str::escape_default`].
4553 /// [`str::escape_default`]: ../../std/primitive.str.html#method.escape_default
4554 #[stable(feature = "str_escape", since = "1.34.0")]
4555 #[derive(Clone, Debug)]
4556 pub struct EscapeDefault<'a> {
4557 inner: FlatMap<Chars<'a>, char::EscapeDefault, CharEscapeDefault>,
4560 /// The return type of [`str::escape_unicode`].
4562 /// [`str::escape_unicode`]: ../../std/primitive.str.html#method.escape_unicode
4563 #[stable(feature = "str_escape", since = "1.34.0")]
4564 #[derive(Clone, Debug)]
4565 pub struct EscapeUnicode<'a> {
4566 inner: FlatMap<Chars<'a>, char::EscapeUnicode, CharEscapeUnicode>,
4569 macro_rules! escape_types_impls {
4570 ($( $Name: ident ),+) => {$(
4571 #[stable(feature = "str_escape", since = "1.34.0")]
4572 impl<'a> fmt::Display for $Name<'a> {
4573 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
4574 self.clone().try_for_each(|c| f.write_char(c))
4578 #[stable(feature = "str_escape", since = "1.34.0")]
4579 impl<'a> Iterator for $Name<'a> {
4583 fn next(&mut self) -> Option<char> { self.inner.next() }
4586 fn size_hint(&self) -> (usize, Option<usize>) { self.inner.size_hint() }
4589 fn try_fold<Acc, Fold, R>(&mut self, init: Acc, fold: Fold) -> R where
4590 Self: Sized, Fold: FnMut(Acc, Self::Item) -> R, R: Try<Ok=Acc>
4592 self.inner.try_fold(init, fold)
4596 fn fold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc
4597 where Fold: FnMut(Acc, Self::Item) -> Acc,
4599 self.inner.fold(init, fold)
4603 #[stable(feature = "str_escape", since = "1.34.0")]
4604 impl<'a> FusedIterator for $Name<'a> {}
4608 escape_types_impls!(EscapeDebug, EscapeDefault, EscapeUnicode);