1 // ignore-tidy-filelength
3 //! String manipulation.
5 //! For more details, see the [`std::str`] module.
7 //! [`std::str`]: ../../std/str/index.html
9 #![stable(feature = "rust1", since = "1.0.0")]
11 use self::pattern
::Pattern
;
12 use self::pattern
::{DoubleEndedSearcher, ReverseSearcher, Searcher}
;
15 use crate::fmt
::{self, Write}
;
16 use crate::iter
::{Chain, FlatMap, Flatten}
;
17 use crate::iter
::{Copied, Filter, FusedIterator, Map, TrustedLen, TrustedRandomAccess}
;
21 use crate::slice
::{self, SliceIndex, Split as SliceSplit}
;
25 #[unstable(feature = "str_internals", issue = "none")]
26 #[allow(missing_docs)]
29 /// Parse a value from a string
31 /// `FromStr`'s [`from_str`] method is often used implicitly, through
32 /// [`str`]'s [`parse`] method. See [`parse`]'s documentation for examples.
34 /// [`from_str`]: #tymethod.from_str
35 /// [`str`]: ../../std/primitive.str.html
36 /// [`parse`]: ../../std/primitive.str.html#method.parse
38 /// `FromStr` does not have a lifetime parameter, and so you can only parse types
39 /// that do not contain a lifetime parameter themselves. In other words, you can
40 /// parse an `i32` with `FromStr`, but not a `&i32`. You can parse a struct that
41 /// contains an `i32`, but not one that contains an `&i32`.
45 /// Basic implementation of `FromStr` on an example `Point` type:
48 /// use std::str::FromStr;
49 /// use std::num::ParseIntError;
51 /// #[derive(Debug, PartialEq)]
57 /// impl FromStr for Point {
58 /// type Err = ParseIntError;
60 /// fn from_str(s: &str) -> Result<Self, Self::Err> {
61 /// let coords: Vec<&str> = s.trim_matches(|p| p == '(' || p == ')' )
65 /// let x_fromstr = coords[0].parse::<i32>()?;
66 /// let y_fromstr = coords[1].parse::<i32>()?;
68 /// Ok(Point { x: x_fromstr, y: y_fromstr })
72 /// let p = Point::from_str("(1,2)");
73 /// assert_eq!(p.unwrap(), Point{ x: 1, y: 2} )
75 #[stable(feature = "rust1", since = "1.0.0")]
76 pub trait FromStr
: Sized
{
77 /// The associated error which can be returned from parsing.
78 #[stable(feature = "rust1", since = "1.0.0")]
81 /// Parses a string `s` to return a value of this type.
83 /// If parsing succeeds, return the value inside [`Ok`], otherwise
84 /// when the string is ill-formatted return an error specific to the
85 /// inside [`Err`]. The error type is specific to implementation of the trait.
87 /// [`Ok`]: ../../std/result/enum.Result.html#variant.Ok
88 /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
92 /// Basic usage with [`i32`][ithirtytwo], a type that implements `FromStr`:
94 /// [ithirtytwo]: ../../std/primitive.i32.html
97 /// use std::str::FromStr;
100 /// let x = i32::from_str(s).unwrap();
102 /// assert_eq!(5, x);
104 #[stable(feature = "rust1", since = "1.0.0")]
105 fn from_str(s
: &str) -> Result
<Self, Self::Err
>;
108 #[stable(feature = "rust1", since = "1.0.0")]
109 impl FromStr
for bool
{
110 type Err
= ParseBoolError
;
112 /// Parse a `bool` from a string.
114 /// Yields a `Result<bool, ParseBoolError>`, because `s` may or may not
115 /// actually be parseable.
120 /// use std::str::FromStr;
122 /// assert_eq!(FromStr::from_str("true"), Ok(true));
123 /// assert_eq!(FromStr::from_str("false"), Ok(false));
124 /// assert!(<bool as FromStr>::from_str("not even a boolean").is_err());
127 /// Note, in many cases, the `.parse()` method on `str` is more proper.
130 /// assert_eq!("true".parse(), Ok(true));
131 /// assert_eq!("false".parse(), Ok(false));
132 /// assert!("not even a boolean".parse::<bool>().is_err());
135 fn from_str(s
: &str) -> Result
<bool
, ParseBoolError
> {
138 "false" => Ok(false),
139 _
=> Err(ParseBoolError { _priv: () }
),
144 /// An error returned when parsing a `bool` using [`from_str`] fails
146 /// [`from_str`]: ../../std/primitive.bool.html#method.from_str
147 #[derive(Debug, Clone, PartialEq, Eq)]
148 #[stable(feature = "rust1", since = "1.0.0")]
149 pub struct ParseBoolError
{
153 #[stable(feature = "rust1", since = "1.0.0")]
154 impl fmt
::Display
for ParseBoolError
{
155 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
156 "provided string was not `true` or `false`".fmt(f
)
161 Section: Creating a string
164 /// Errors which can occur when attempting to interpret a sequence of [`u8`]
167 /// [`u8`]: ../../std/primitive.u8.html
169 /// As such, the `from_utf8` family of functions and methods for both [`String`]s
170 /// and [`&str`]s make use of this error, for example.
172 /// [`String`]: ../../std/string/struct.String.html#method.from_utf8
173 /// [`&str`]: ../../std/str/fn.from_utf8.html
177 /// This error type’s methods can be used to create functionality
178 /// similar to `String::from_utf8_lossy` without allocating heap memory:
181 /// fn from_utf8_lossy<F>(mut input: &[u8], mut push: F) where F: FnMut(&str) {
183 /// match std::str::from_utf8(input) {
189 /// let (valid, after_valid) = input.split_at(error.valid_up_to());
191 /// push(std::str::from_utf8_unchecked(valid))
193 /// push("\u{FFFD}");
195 /// if let Some(invalid_sequence_length) = error.error_len() {
196 /// input = &after_valid[invalid_sequence_length..]
205 #[derive(Copy, Eq, PartialEq, Clone, Debug)]
206 #[stable(feature = "rust1", since = "1.0.0")]
207 pub struct Utf8Error
{
209 error_len
: Option
<u8>,
213 /// Returns the index in the given string up to which valid UTF-8 was
216 /// It is the maximum index such that `from_utf8(&input[..index])`
217 /// would return `Ok(_)`.
226 /// // some invalid bytes, in a vector
227 /// let sparkle_heart = vec![0, 159, 146, 150];
229 /// // std::str::from_utf8 returns a Utf8Error
230 /// let error = str::from_utf8(&sparkle_heart).unwrap_err();
232 /// // the second byte is invalid here
233 /// assert_eq!(1, error.valid_up_to());
235 #[stable(feature = "utf8_error", since = "1.5.0")]
236 pub fn valid_up_to(&self) -> usize {
240 /// Provides more information about the failure:
242 /// * `None`: the end of the input was reached unexpectedly.
243 /// `self.valid_up_to()` is 1 to 3 bytes from the end of the input.
244 /// If a byte stream (such as a file or a network socket) is being decoded incrementally,
245 /// this could be a valid `char` whose UTF-8 byte sequence is spanning multiple chunks.
247 /// * `Some(len)`: an unexpected byte was encountered.
248 /// The length provided is that of the invalid byte sequence
249 /// that starts at the index given by `valid_up_to()`.
250 /// Decoding should resume after that sequence
251 /// (after inserting a [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD]) in case of
254 /// [U+FFFD]: ../../std/char/constant.REPLACEMENT_CHARACTER.html
255 #[stable(feature = "utf8_error_error_len", since = "1.20.0")]
256 pub fn error_len(&self) -> Option
<usize> {
257 self.error_len
.map(|len
| len
as usize)
261 /// Converts a slice of bytes to a string slice.
263 /// A string slice ([`&str`]) is made of bytes ([`u8`]), and a byte slice
264 /// ([`&[u8]`][byteslice]) is made of bytes, so this function converts between
265 /// the two. Not all byte slices are valid string slices, however: [`&str`] requires
266 /// that it is valid UTF-8. `from_utf8()` checks to ensure that the bytes are valid
267 /// UTF-8, and then does the conversion.
269 /// [`&str`]: ../../std/primitive.str.html
270 /// [`u8`]: ../../std/primitive.u8.html
271 /// [byteslice]: ../../std/primitive.slice.html
273 /// If you are sure that the byte slice is valid UTF-8, and you don't want to
274 /// incur the overhead of the validity check, there is an unsafe version of
275 /// this function, [`from_utf8_unchecked`][fromutf8u], which has the same
276 /// behavior but skips the check.
278 /// [fromutf8u]: fn.from_utf8_unchecked.html
280 /// If you need a `String` instead of a `&str`, consider
281 /// [`String::from_utf8`][string].
283 /// [string]: ../../std/string/struct.String.html#method.from_utf8
285 /// Because you can stack-allocate a `[u8; N]`, and you can take a
286 /// [`&[u8]`][byteslice] of it, this function is one way to have a
287 /// stack-allocated string. There is an example of this in the
288 /// examples section below.
290 /// [byteslice]: ../../std/primitive.slice.html
294 /// Returns `Err` if the slice is not UTF-8 with a description as to why the
295 /// provided slice is not UTF-8.
304 /// // some bytes, in a vector
305 /// let sparkle_heart = vec![240, 159, 146, 150];
307 /// // We know these bytes are valid, so just use `unwrap()`.
308 /// let sparkle_heart = str::from_utf8(&sparkle_heart).unwrap();
310 /// assert_eq!("💖", sparkle_heart);
318 /// // some invalid bytes, in a vector
319 /// let sparkle_heart = vec![0, 159, 146, 150];
321 /// assert!(str::from_utf8(&sparkle_heart).is_err());
324 /// See the docs for [`Utf8Error`][error] for more details on the kinds of
325 /// errors that can be returned.
327 /// [error]: struct.Utf8Error.html
329 /// A "stack allocated string":
334 /// // some bytes, in a stack-allocated array
335 /// let sparkle_heart = [240, 159, 146, 150];
337 /// // We know these bytes are valid, so just use `unwrap()`.
338 /// let sparkle_heart = str::from_utf8(&sparkle_heart).unwrap();
340 /// assert_eq!("💖", sparkle_heart);
342 #[stable(feature = "rust1", since = "1.0.0")]
343 pub fn from_utf8(v
: &[u8]) -> Result
<&str, Utf8Error
> {
344 run_utf8_validation(v
)?
;
345 // SAFETY: Just ran validation.
346 Ok(unsafe { from_utf8_unchecked(v) }
)
349 /// Converts a mutable slice of bytes to a mutable string slice.
358 /// // "Hello, Rust!" as a mutable vector
359 /// let mut hellorust = vec![72, 101, 108, 108, 111, 44, 32, 82, 117, 115, 116, 33];
361 /// // As we know these bytes are valid, we can use `unwrap()`
362 /// let outstr = str::from_utf8_mut(&mut hellorust).unwrap();
364 /// assert_eq!("Hello, Rust!", outstr);
372 /// // Some invalid bytes in a mutable vector
373 /// let mut invalid = vec![128, 223];
375 /// assert!(str::from_utf8_mut(&mut invalid).is_err());
377 /// See the docs for [`Utf8Error`][error] for more details on the kinds of
378 /// errors that can be returned.
380 /// [error]: struct.Utf8Error.html
381 #[stable(feature = "str_mut_extras", since = "1.20.0")]
382 pub fn from_utf8_mut(v
: &mut [u8]) -> Result
<&mut str, Utf8Error
> {
383 run_utf8_validation(v
)?
;
384 // SAFETY: Just ran validation.
385 Ok(unsafe { from_utf8_unchecked_mut(v) }
)
388 /// Converts a slice of bytes to a string slice without checking
389 /// that the string contains valid UTF-8.
391 /// See the safe version, [`from_utf8`][fromutf8], for more information.
393 /// [fromutf8]: fn.from_utf8.html
397 /// This function is unsafe because it does not check that the bytes passed to
398 /// it are valid UTF-8. If this constraint is violated, undefined behavior
399 /// results, as the rest of Rust assumes that [`&str`]s are valid UTF-8.
401 /// [`&str`]: ../../std/primitive.str.html
410 /// // some bytes, in a vector
411 /// let sparkle_heart = vec![240, 159, 146, 150];
413 /// let sparkle_heart = unsafe {
414 /// str::from_utf8_unchecked(&sparkle_heart)
417 /// assert_eq!("💖", sparkle_heart);
420 #[stable(feature = "rust1", since = "1.0.0")]
421 pub unsafe fn from_utf8_unchecked(v
: &[u8]) -> &str {
422 // SAFETY: the caller must guarantee that the bytes `v`
423 // are valid UTF-8, thus the cast to `*const str` is safe.
424 // Also, the pointer dereference is safe because that pointer
425 // comes from a reference which is guaranteed to be valid for reads.
426 unsafe { &*(v as *const [u8] as *const str) }
429 /// Converts a slice of bytes to a string slice without checking
430 /// that the string contains valid UTF-8; mutable version.
432 /// See the immutable version, [`from_utf8_unchecked()`][fromutf8], for more information.
434 /// [fromutf8]: fn.from_utf8_unchecked.html
443 /// let mut heart = vec![240, 159, 146, 150];
444 /// let heart = unsafe { str::from_utf8_unchecked_mut(&mut heart) };
446 /// assert_eq!("💖", heart);
449 #[stable(feature = "str_mut_extras", since = "1.20.0")]
450 pub unsafe fn from_utf8_unchecked_mut(v
: &mut [u8]) -> &mut str {
451 // SAFETY: the caller must guarantee that the bytes `v`
452 // are valid UTF-8, thus the cast to `*mut str` is safe.
453 // Also, the pointer dereference is safe because that pointer
454 // comes from a reference which is guaranteed to be valid for writes.
455 unsafe { &mut *(v as *mut [u8] as *mut str) }
458 #[stable(feature = "rust1", since = "1.0.0")]
459 impl fmt
::Display
for Utf8Error
{
460 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
461 if let Some(error_len
) = self.error_len
{
464 "invalid utf-8 sequence of {} bytes from index {}",
465 error_len
, self.valid_up_to
468 write
!(f
, "incomplete utf-8 byte sequence from index {}", self.valid_up_to
)
477 /// An iterator over the [`char`]s of a string slice.
479 /// [`char`]: ../../std/primitive.char.html
481 /// This struct is created by the [`chars`] method on [`str`].
482 /// See its documentation for more.
484 /// [`chars`]: ../../std/primitive.str.html#method.chars
485 /// [`str`]: ../../std/primitive.str.html
487 #[stable(feature = "rust1", since = "1.0.0")]
488 pub struct Chars
<'a
> {
489 iter
: slice
::Iter
<'a
, u8>,
492 /// Returns the initial codepoint accumulator for the first byte.
493 /// The first byte is special, only want bottom 5 bits for width 2, 4 bits
494 /// for width 3, and 3 bits for width 4.
496 fn utf8_first_byte(byte
: u8, width
: u32) -> u32 {
497 (byte
& (0x7F >> width
)) as u32
500 /// Returns the value of `ch` updated with continuation byte `byte`.
502 fn utf8_acc_cont_byte(ch
: u32, byte
: u8) -> u32 {
503 (ch
<< 6) | (byte
& CONT_MASK
) as u32
506 /// Checks whether the byte is a UTF-8 continuation byte (i.e., starts with the
509 fn utf8_is_cont_byte(byte
: u8) -> bool
{
510 (byte
& !CONT_MASK
) == TAG_CONT_U8
514 fn unwrap_or_0(opt
: Option
<&u8>) -> u8 {
521 /// Reads the next code point out of a byte iterator (assuming a
522 /// UTF-8-like encoding).
523 #[unstable(feature = "str_internals", issue = "none")]
525 pub fn next_code_point
<'a
, I
: Iterator
<Item
= &'a
u8>>(bytes
: &mut I
) -> Option
<u32> {
527 let x
= *bytes
.next()?
;
529 return Some(x
as u32);
532 // Multibyte case follows
533 // Decode from a byte combination out of: [[[x y] z] w]
534 // NOTE: Performance is sensitive to the exact formulation here
535 let init
= utf8_first_byte(x
, 2);
536 let y
= unwrap_or_0(bytes
.next());
537 let mut ch
= utf8_acc_cont_byte(init
, y
);
540 // 5th bit in 0xE0 .. 0xEF is always clear, so `init` is still valid
541 let z
= unwrap_or_0(bytes
.next());
542 let y_z
= utf8_acc_cont_byte((y
& CONT_MASK
) as u32, z
);
543 ch
= init
<< 12 | y_z
;
546 // use only the lower 3 bits of `init`
547 let w
= unwrap_or_0(bytes
.next());
548 ch
= (init
& 7) << 18 | utf8_acc_cont_byte(y_z
, w
);
555 /// Reads the last code point out of a byte iterator (assuming a
556 /// UTF-8-like encoding).
558 fn next_code_point_reverse
<'a
, I
>(bytes
: &mut I
) -> Option
<u32>
560 I
: DoubleEndedIterator
<Item
= &'a
u8>,
563 let w
= match *bytes
.next_back()?
{
564 next_byte
if next_byte
< 128 => return Some(next_byte
as u32),
565 back_byte
=> back_byte
,
568 // Multibyte case follows
569 // Decode from a byte combination out of: [x [y [z w]]]
571 let z
= unwrap_or_0(bytes
.next_back());
572 ch
= utf8_first_byte(z
, 2);
573 if utf8_is_cont_byte(z
) {
574 let y
= unwrap_or_0(bytes
.next_back());
575 ch
= utf8_first_byte(y
, 3);
576 if utf8_is_cont_byte(y
) {
577 let x
= unwrap_or_0(bytes
.next_back());
578 ch
= utf8_first_byte(x
, 4);
579 ch
= utf8_acc_cont_byte(ch
, y
);
581 ch
= utf8_acc_cont_byte(ch
, z
);
583 ch
= utf8_acc_cont_byte(ch
, w
);
588 #[stable(feature = "rust1", since = "1.0.0")]
589 impl<'a
> Iterator
for Chars
<'a
> {
593 fn next(&mut self) -> Option
<char> {
594 next_code_point(&mut self.iter
).map(|ch
| {
595 // SAFETY: `str` invariant says `ch` is a valid Unicode Scalar Value.
596 unsafe { char::from_u32_unchecked(ch) }
601 fn count(self) -> usize {
602 // length in `char` is equal to the number of non-continuation bytes
603 let bytes_len
= self.iter
.len();
604 let mut cont_bytes
= 0;
605 for &byte
in self.iter
{
606 cont_bytes
+= utf8_is_cont_byte(byte
) as usize;
608 bytes_len
- cont_bytes
612 fn size_hint(&self) -> (usize, Option
<usize>) {
613 let len
= self.iter
.len();
614 // `(len + 3)` can't overflow, because we know that the `slice::Iter`
615 // belongs to a slice in memory which has a maximum length of
616 // `isize::MAX` (that's well below `usize::MAX`).
617 ((len
+ 3) / 4, Some(len
))
621 fn last(mut self) -> Option
<char> {
622 // No need to go through the entire string.
627 #[stable(feature = "chars_debug_impl", since = "1.38.0")]
628 impl fmt
::Debug
for Chars
<'_
> {
629 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
630 write
!(f
, "Chars(")?
;
631 f
.debug_list().entries(self.clone()).finish()?
;
637 #[stable(feature = "rust1", since = "1.0.0")]
638 impl<'a
> DoubleEndedIterator
for Chars
<'a
> {
640 fn next_back(&mut self) -> Option
<char> {
641 next_code_point_reverse(&mut self.iter
).map(|ch
| {
642 // SAFETY: `str` invariant says `ch` is a valid Unicode Scalar Value.
643 unsafe { char::from_u32_unchecked(ch) }
648 #[stable(feature = "fused", since = "1.26.0")]
649 impl FusedIterator
for Chars
<'_
> {}
652 /// Views the underlying data as a subslice of the original data.
654 /// This has the same lifetime as the original slice, and so the
655 /// iterator can continue to be used while this exists.
660 /// let mut chars = "abc".chars();
662 /// assert_eq!(chars.as_str(), "abc");
664 /// assert_eq!(chars.as_str(), "bc");
667 /// assert_eq!(chars.as_str(), "");
669 #[stable(feature = "iter_to_slice", since = "1.4.0")]
671 pub fn as_str(&self) -> &'a
str {
672 // SAFETY: `Chars` is only made from a str, which guarantees the iter is valid UTF-8.
673 unsafe { from_utf8_unchecked(self.iter.as_slice()) }
677 /// An iterator over the [`char`]s of a string slice, and their positions.
679 /// [`char`]: ../../std/primitive.char.html
681 /// This struct is created by the [`char_indices`] method on [`str`].
682 /// See its documentation for more.
684 /// [`char_indices`]: ../../std/primitive.str.html#method.char_indices
685 /// [`str`]: ../../std/primitive.str.html
686 #[derive(Clone, Debug)]
687 #[stable(feature = "rust1", since = "1.0.0")]
688 pub struct CharIndices
<'a
> {
693 #[stable(feature = "rust1", since = "1.0.0")]
694 impl<'a
> Iterator
for CharIndices
<'a
> {
695 type Item
= (usize, char);
698 fn next(&mut self) -> Option
<(usize, char)> {
699 let pre_len
= self.iter
.iter
.len();
700 match self.iter
.next() {
703 let index
= self.front_offset
;
704 let len
= self.iter
.iter
.len();
705 self.front_offset
+= pre_len
- len
;
712 fn count(self) -> usize {
717 fn size_hint(&self) -> (usize, Option
<usize>) {
718 self.iter
.size_hint()
722 fn last(mut self) -> Option
<(usize, char)> {
723 // No need to go through the entire string.
728 #[stable(feature = "rust1", since = "1.0.0")]
729 impl<'a
> DoubleEndedIterator
for CharIndices
<'a
> {
731 fn next_back(&mut self) -> Option
<(usize, char)> {
732 self.iter
.next_back().map(|ch
| {
733 let index
= self.front_offset
+ self.iter
.iter
.len();
739 #[stable(feature = "fused", since = "1.26.0")]
740 impl FusedIterator
for CharIndices
<'_
> {}
742 impl<'a
> CharIndices
<'a
> {
743 /// Views the underlying data as a subslice of the original data.
745 /// This has the same lifetime as the original slice, and so the
746 /// iterator can continue to be used while this exists.
747 #[stable(feature = "iter_to_slice", since = "1.4.0")]
749 pub fn as_str(&self) -> &'a
str {
754 /// An iterator over the bytes of a string slice.
756 /// This struct is created by the [`bytes`] method on [`str`].
757 /// See its documentation for more.
759 /// [`bytes`]: ../../std/primitive.str.html#method.bytes
760 /// [`str`]: ../../std/primitive.str.html
761 #[stable(feature = "rust1", since = "1.0.0")]
762 #[derive(Clone, Debug)]
763 pub struct Bytes
<'a
>(Copied
<slice
::Iter
<'a
, u8>>);
765 #[stable(feature = "rust1", since = "1.0.0")]
766 impl Iterator
for Bytes
<'_
> {
770 fn next(&mut self) -> Option
<u8> {
775 fn size_hint(&self) -> (usize, Option
<usize>) {
780 fn count(self) -> usize {
785 fn last(self) -> Option
<Self::Item
> {
790 fn nth(&mut self, n
: usize) -> Option
<Self::Item
> {
795 fn all
<F
>(&mut self, f
: F
) -> bool
797 F
: FnMut(Self::Item
) -> bool
,
803 fn any
<F
>(&mut self, f
: F
) -> bool
805 F
: FnMut(Self::Item
) -> bool
,
811 fn find
<P
>(&mut self, predicate
: P
) -> Option
<Self::Item
>
813 P
: FnMut(&Self::Item
) -> bool
,
815 self.0.find
(predicate
)
819 fn position
<P
>(&mut self, predicate
: P
) -> Option
<usize>
821 P
: FnMut(Self::Item
) -> bool
,
823 self.0.position(predicate
)
827 fn rposition
<P
>(&mut self, predicate
: P
) -> Option
<usize>
829 P
: FnMut(Self::Item
) -> bool
,
831 self.0.rposition(predicate
)
835 #[stable(feature = "rust1", since = "1.0.0")]
836 impl DoubleEndedIterator
for Bytes
<'_
> {
838 fn next_back(&mut self) -> Option
<u8> {
843 fn nth_back(&mut self, n
: usize) -> Option
<Self::Item
> {
848 fn rfind
<P
>(&mut self, predicate
: P
) -> Option
<Self::Item
>
850 P
: FnMut(&Self::Item
) -> bool
,
852 self.0.rfind(predicate
)
856 #[stable(feature = "rust1", since = "1.0.0")]
857 impl ExactSizeIterator
for Bytes
<'_
> {
859 fn len(&self) -> usize {
864 fn is_empty(&self) -> bool
{
869 #[stable(feature = "fused", since = "1.26.0")]
870 impl FusedIterator
for Bytes
<'_
> {}
872 #[unstable(feature = "trusted_len", issue = "37572")]
873 unsafe impl TrustedLen
for Bytes
<'_
> {}
876 unsafe impl TrustedRandomAccess
for Bytes
<'_
> {
877 unsafe fn get_unchecked(&mut self, i
: usize) -> u8 {
878 // SAFETY: the caller must uphold the safety contract
879 // for `TrustedRandomAccess::get_unchecked`.
880 unsafe { self.0.get_unchecked(i) }
882 fn may_have_side_effect() -> bool
{
887 /// This macro generates a Clone impl for string pattern API
888 /// wrapper types of the form X<'a, P>
889 macro_rules
! derive_pattern_clone
{
890 (clone $t
:ident with
|$s
:ident
| $e
:expr
) => {
891 impl<'a
, P
> Clone
for $t
<'a
, P
>
893 P
: Pattern
<'a
, Searcher
: Clone
>,
895 fn clone(&self) -> Self {
903 /// This macro generates two public iterator structs
904 /// wrapping a private internal one that makes use of the `Pattern` API.
906 /// For all patterns `P: Pattern<'a>` the following items will be
907 /// generated (generics omitted):
909 /// struct $forward_iterator($internal_iterator);
910 /// struct $reverse_iterator($internal_iterator);
912 /// impl Iterator for $forward_iterator
913 /// { /* internal ends up calling Searcher::next_match() */ }
915 /// impl DoubleEndedIterator for $forward_iterator
916 /// where P::Searcher: DoubleEndedSearcher
917 /// { /* internal ends up calling Searcher::next_match_back() */ }
919 /// impl Iterator for $reverse_iterator
920 /// where P::Searcher: ReverseSearcher
921 /// { /* internal ends up calling Searcher::next_match_back() */ }
923 /// impl DoubleEndedIterator for $reverse_iterator
924 /// where P::Searcher: DoubleEndedSearcher
925 /// { /* internal ends up calling Searcher::next_match() */ }
927 /// The internal one is defined outside the macro, and has almost the same
928 /// semantic as a DoubleEndedIterator by delegating to `pattern::Searcher` and
929 /// `pattern::ReverseSearcher` for both forward and reverse iteration.
931 /// "Almost", because a `Searcher` and a `ReverseSearcher` for a given
932 /// `Pattern` might not return the same elements, so actually implementing
933 /// `DoubleEndedIterator` for it would be incorrect.
934 /// (See the docs in `str::pattern` for more details)
936 /// However, the internal struct still represents a single ended iterator from
937 /// either end, and depending on pattern is also a valid double ended iterator,
938 /// so the two wrapper structs implement `Iterator`
939 /// and `DoubleEndedIterator` depending on the concrete pattern type, leading
940 /// to the complex impls seen above.
941 macro_rules
! generate_pattern_iterators
{
945 $
(#[$forward_iterator_attribute:meta])*
946 struct $forward_iterator
:ident
;
950 $
(#[$reverse_iterator_attribute:meta])*
951 struct $reverse_iterator
:ident
;
953 // Stability of all generated items
955 $
(#[$common_stability_attribute:meta])*
957 // Internal almost-iterator that is being delegated to
959 $internal_iterator
:ident
yielding ($iterty
:ty
);
961 // Kind of delegation - either single ended or double ended
964 $
(#[$forward_iterator_attribute])*
965 $
(#[$common_stability_attribute])*
966 pub struct $forward_iterator
<'a
, P
: Pattern
<'a
>>($internal_iterator
<'a
, P
>);
968 $
(#[$common_stability_attribute])*
969 impl<'a
, P
> fmt
::Debug
for $forward_iterator
<'a
, P
>
971 P
: Pattern
<'a
, Searcher
: fmt
::Debug
>,
973 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
974 f
.debug_tuple(stringify
!($forward_iterator
))
980 $
(#[$common_stability_attribute])*
981 impl<'a
, P
: Pattern
<'a
>> Iterator
for $forward_iterator
<'a
, P
> {
985 fn next(&mut self) -> Option
<$iterty
> {
990 $
(#[$common_stability_attribute])*
991 impl<'a
, P
> Clone
for $forward_iterator
<'a
, P
>
993 P
: Pattern
<'a
, Searcher
: Clone
>,
995 fn clone(&self) -> Self {
996 $
forward_iterator(self.0.clone())
1000 $
(#[$reverse_iterator_attribute])*
1001 $
(#[$common_stability_attribute])*
1002 pub struct $reverse_iterator
<'a
, P
: Pattern
<'a
>>($internal_iterator
<'a
, P
>);
1004 $
(#[$common_stability_attribute])*
1005 impl<'a
, P
> fmt
::Debug
for $reverse_iterator
<'a
, P
>
1007 P
: Pattern
<'a
, Searcher
: fmt
::Debug
>,
1009 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
1010 f
.debug_tuple(stringify
!($reverse_iterator
))
1016 $
(#[$common_stability_attribute])*
1017 impl<'a
, P
> Iterator
for $reverse_iterator
<'a
, P
>
1019 P
: Pattern
<'a
, Searcher
: ReverseSearcher
<'a
>>,
1021 type Item
= $iterty
;
1024 fn next(&mut self) -> Option
<$iterty
> {
1029 $
(#[$common_stability_attribute])*
1030 impl<'a
, P
> Clone
for $reverse_iterator
<'a
, P
>
1032 P
: Pattern
<'a
, Searcher
: Clone
>,
1034 fn clone(&self) -> Self {
1035 $
reverse_iterator(self.0.clone())
1039 #[stable(feature = "fused", since = "1.26.0")]
1040 impl<'a
, P
: Pattern
<'a
>> FusedIterator
for $forward_iterator
<'a
, P
> {}
1042 #[stable(feature = "fused", since = "1.26.0")]
1043 impl<'a
, P
> FusedIterator
for $reverse_iterator
<'a
, P
>
1045 P
: Pattern
<'a
, Searcher
: ReverseSearcher
<'a
>>,
1048 generate_pattern_iterators
!($
($t
)* with $
(#[$common_stability_attribute])*,
1050 $reverse_iterator
, $iterty
);
1053 double ended
; with $
(#[$common_stability_attribute:meta])*,
1054 $forward_iterator
:ident
,
1055 $reverse_iterator
:ident
, $iterty
:ty
1057 $
(#[$common_stability_attribute])*
1058 impl<'a
, P
> DoubleEndedIterator
for $forward_iterator
<'a
, P
>
1060 P
: Pattern
<'a
, Searcher
: DoubleEndedSearcher
<'a
>>,
1063 fn next_back(&mut self) -> Option
<$iterty
> {
1068 $
(#[$common_stability_attribute])*
1069 impl<'a
, P
> DoubleEndedIterator
for $reverse_iterator
<'a
, P
>
1071 P
: Pattern
<'a
, Searcher
: DoubleEndedSearcher
<'a
>>,
1074 fn next_back(&mut self) -> Option
<$iterty
> {
1080 single ended
; with $
(#[$common_stability_attribute:meta])*,
1081 $forward_iterator
:ident
,
1082 $reverse_iterator
:ident
, $iterty
:ty
1086 derive_pattern_clone
! {
1088 with
|s
| SplitInternal { matcher: s.matcher.clone(), ..*s }
1091 struct SplitInternal
<'a
, P
: Pattern
<'a
>> {
1094 matcher
: P
::Searcher
,
1095 allow_trailing_empty
: bool
,
1099 impl<'a
, P
> fmt
::Debug
for SplitInternal
<'a
, P
>
1101 P
: Pattern
<'a
, Searcher
: fmt
::Debug
>,
1103 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
1104 f
.debug_struct("SplitInternal")
1105 .field("start", &self.start
)
1106 .field("end", &self.end
)
1107 .field("matcher", &self.matcher
)
1108 .field("allow_trailing_empty", &self.allow_trailing_empty
)
1109 .field("finished", &self.finished
)
1114 impl<'a
, P
: Pattern
<'a
>> SplitInternal
<'a
, P
> {
1116 fn get_end(&mut self) -> Option
<&'a
str> {
1117 if !self.finished
&& (self.allow_trailing_empty
|| self.end
- self.start
> 0) {
1118 self.finished
= true;
1119 // SAFETY: `self.start` and `self.end` always lie on unicode boundaries.
1121 let string
= self.matcher
.haystack().get_unchecked(self.start
..self.end
);
1130 fn next(&mut self) -> Option
<&'a
str> {
1135 let haystack
= self.matcher
.haystack();
1136 match self.matcher
.next_match() {
1137 // SAFETY: `Searcher` guarantees that `a` and `b` lie on unicode boundaries.
1138 Some((a
, b
)) => unsafe {
1139 let elt
= haystack
.get_unchecked(self.start
..a
);
1143 None
=> self.get_end(),
1148 fn next_inclusive(&mut self) -> Option
<&'a
str> {
1153 let haystack
= self.matcher
.haystack();
1154 match self.matcher
.next_match() {
1155 // SAFETY: `Searcher` guarantees that `b` lies on unicode boundary,
1156 // and self.start is either the start of the original string,
1157 // or `b` was assigned to it, so it also lies on unicode boundary.
1158 Some((_
, b
)) => unsafe {
1159 let elt
= haystack
.get_unchecked(self.start
..b
);
1163 None
=> self.get_end(),
1168 fn next_back(&mut self) -> Option
<&'a
str>
1170 P
::Searcher
: ReverseSearcher
<'a
>,
1176 if !self.allow_trailing_empty
{
1177 self.allow_trailing_empty
= true;
1178 match self.next_back() {
1179 Some(elt
) if !elt
.is_empty() => return Some(elt
),
1188 let haystack
= self.matcher
.haystack();
1189 match self.matcher
.next_match_back() {
1190 // SAFETY: `Searcher` guarantees that `a` and `b` lie on unicode boundaries.
1191 Some((a
, b
)) => unsafe {
1192 let elt
= haystack
.get_unchecked(b
..self.end
);
1196 // SAFETY: `self.start` and `self.end` always lie on unicode boundaries.
1198 self.finished
= true;
1199 Some(haystack
.get_unchecked(self.start
..self.end
))
1205 fn next_back_inclusive(&mut self) -> Option
<&'a
str>
1207 P
::Searcher
: ReverseSearcher
<'a
>,
1213 if !self.allow_trailing_empty
{
1214 self.allow_trailing_empty
= true;
1215 match self.next_back_inclusive() {
1216 Some(elt
) if !elt
.is_empty() => return Some(elt
),
1225 let haystack
= self.matcher
.haystack();
1226 match self.matcher
.next_match_back() {
1227 // SAFETY: `Searcher` guarantees that `b` lies on unicode boundary,
1228 // and self.end is either the end of the original string,
1229 // or `b` was assigned to it, so it also lies on unicode boundary.
1230 Some((_
, b
)) => unsafe {
1231 let elt
= haystack
.get_unchecked(b
..self.end
);
1235 // SAFETY: self.start is either the start of the original string,
1236 // or start of a substring that represents the part of the string that hasn't
1237 // iterated yet. Either way, it is guaranteed to lie on unicode boundary.
1238 // self.end is either the end of the original string,
1239 // or `b` was assigned to it, so it also lies on unicode boundary.
1241 self.finished
= true;
1242 Some(haystack
.get_unchecked(self.start
..self.end
))
1248 generate_pattern_iterators
! {
1250 /// Created with the method [`split`].
1252 /// [`split`]: ../../std/primitive.str.html#method.split
1255 /// Created with the method [`rsplit`].
1257 /// [`rsplit`]: ../../std/primitive.str.html#method.rsplit
1260 #[stable(feature = "rust1", since = "1.0.0")]
1262 SplitInternal
yielding (&'a
str);
1263 delegate double ended
;
1266 generate_pattern_iterators
! {
1268 /// Created with the method [`split_terminator`].
1270 /// [`split_terminator`]: ../../std/primitive.str.html#method.split_terminator
1271 struct SplitTerminator
;
1273 /// Created with the method [`rsplit_terminator`].
1275 /// [`rsplit_terminator`]: ../../std/primitive.str.html#method.rsplit_terminator
1276 struct RSplitTerminator
;
1278 #[stable(feature = "rust1", since = "1.0.0")]
1280 SplitInternal
yielding (&'a
str);
1281 delegate double ended
;
1284 derive_pattern_clone
! {
1285 clone SplitNInternal
1286 with
|s
| SplitNInternal { iter: s.iter.clone(), ..*s }
1289 struct SplitNInternal
<'a
, P
: Pattern
<'a
>> {
1290 iter
: SplitInternal
<'a
, P
>,
1291 /// The number of splits remaining
1295 impl<'a
, P
> fmt
::Debug
for SplitNInternal
<'a
, P
>
1297 P
: Pattern
<'a
, Searcher
: fmt
::Debug
>,
1299 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
1300 f
.debug_struct("SplitNInternal")
1301 .field("iter", &self.iter
)
1302 .field("count", &self.count
)
1307 impl<'a
, P
: Pattern
<'a
>> SplitNInternal
<'a
, P
> {
1309 fn next(&mut self) -> Option
<&'a
str> {
1324 fn next_back(&mut self) -> Option
<&'a
str>
1326 P
::Searcher
: ReverseSearcher
<'a
>,
1336 self.iter
.next_back()
1342 generate_pattern_iterators
! {
1344 /// Created with the method [`splitn`].
1346 /// [`splitn`]: ../../std/primitive.str.html#method.splitn
1349 /// Created with the method [`rsplitn`].
1351 /// [`rsplitn`]: ../../std/primitive.str.html#method.rsplitn
1354 #[stable(feature = "rust1", since = "1.0.0")]
1356 SplitNInternal
yielding (&'a
str);
1357 delegate single ended
;
1360 derive_pattern_clone
! {
1361 clone MatchIndicesInternal
1362 with
|s
| MatchIndicesInternal(s
.0.clone())
1365 struct MatchIndicesInternal
<'a
, P
: Pattern
<'a
>>(P
::Searcher
);
1367 impl<'a
, P
> fmt
::Debug
for MatchIndicesInternal
<'a
, P
>
1369 P
: Pattern
<'a
, Searcher
: fmt
::Debug
>,
1371 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
1372 f
.debug_tuple("MatchIndicesInternal").field(&self.0).finish()
1376 impl<'a
, P
: Pattern
<'a
>> MatchIndicesInternal
<'a
, P
> {
1378 fn next(&mut self) -> Option
<(usize, &'a
str)> {
1381 // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries.
1382 .map(|(start
, end
)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) }
)
1386 fn next_back(&mut self) -> Option
<(usize, &'a
str)>
1388 P
::Searcher
: ReverseSearcher
<'a
>,
1392 // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries.
1393 .map(|(start
, end
)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) }
)
1397 generate_pattern_iterators
! {
1399 /// Created with the method [`match_indices`].
1401 /// [`match_indices`]: ../../std/primitive.str.html#method.match_indices
1402 struct MatchIndices
;
1404 /// Created with the method [`rmatch_indices`].
1406 /// [`rmatch_indices`]: ../../std/primitive.str.html#method.rmatch_indices
1407 struct RMatchIndices
;
1409 #[stable(feature = "str_match_indices", since = "1.5.0")]
1411 MatchIndicesInternal
yielding ((usize, &'a
str));
1412 delegate double ended
;
1415 derive_pattern_clone
! {
1416 clone MatchesInternal
1417 with
|s
| MatchesInternal(s
.0.clone())
1420 struct MatchesInternal
<'a
, P
: Pattern
<'a
>>(P
::Searcher
);
1422 impl<'a
, P
> fmt
::Debug
for MatchesInternal
<'a
, P
>
1424 P
: Pattern
<'a
, Searcher
: fmt
::Debug
>,
1426 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
1427 f
.debug_tuple("MatchesInternal").field(&self.0).finish()
1431 impl<'a
, P
: Pattern
<'a
>> MatchesInternal
<'a
, P
> {
1433 fn next(&mut self) -> Option
<&'a
str> {
1434 // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries.
1435 self.0.next_match().map(|(a
, b
)| unsafe {
1436 // Indices are known to be on utf8 boundaries
1437 self.0.haystack().get_unchecked(a
..b
)
1442 fn next_back(&mut self) -> Option
<&'a
str>
1444 P
::Searcher
: ReverseSearcher
<'a
>,
1446 // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries.
1447 self.0.next_match_back().map(|(a
, b
)| unsafe {
1448 // Indices are known to be on utf8 boundaries
1449 self.0.haystack().get_unchecked(a
..b
)
1454 generate_pattern_iterators
! {
1456 /// Created with the method [`matches`].
1458 /// [`matches`]: ../../std/primitive.str.html#method.matches
1461 /// Created with the method [`rmatches`].
1463 /// [`rmatches`]: ../../std/primitive.str.html#method.rmatches
1466 #[stable(feature = "str_matches", since = "1.2.0")]
1468 MatchesInternal
yielding (&'a
str);
1469 delegate double ended
;
1472 /// An iterator over the lines of a string, as string slices.
1474 /// This struct is created with the [`lines`] method on [`str`].
1475 /// See its documentation for more.
1477 /// [`lines`]: ../../std/primitive.str.html#method.lines
1478 /// [`str`]: ../../std/primitive.str.html
1479 #[stable(feature = "rust1", since = "1.0.0")]
1480 #[derive(Clone, Debug)]
1481 pub struct Lines
<'a
>(Map
<SplitTerminator
<'a
, char>, LinesAnyMap
>);
1483 #[stable(feature = "rust1", since = "1.0.0")]
1484 impl<'a
> Iterator
for Lines
<'a
> {
1485 type Item
= &'a
str;
1488 fn next(&mut self) -> Option
<&'a
str> {
1493 fn size_hint(&self) -> (usize, Option
<usize>) {
1498 fn last(mut self) -> Option
<&'a
str> {
1503 #[stable(feature = "rust1", since = "1.0.0")]
1504 impl<'a
> DoubleEndedIterator
for Lines
<'a
> {
1506 fn next_back(&mut self) -> Option
<&'a
str> {
1511 #[stable(feature = "fused", since = "1.26.0")]
1512 impl FusedIterator
for Lines
<'_
> {}
1514 /// Created with the method [`lines_any`].
1516 /// [`lines_any`]: ../../std/primitive.str.html#method.lines_any
1517 #[stable(feature = "rust1", since = "1.0.0")]
1518 #[rustc_deprecated(since = "1.4.0", reason = "use lines()/Lines instead now")]
1519 #[derive(Clone, Debug)]
1520 #[allow(deprecated)]
1521 pub struct LinesAny
<'a
>(Lines
<'a
>);
1524 /// A nameable, cloneable fn type
1526 struct LinesAnyMap
impl<'a
> Fn
= |line
: &'a
str| -> &'a
str {
1528 if l
> 0 && line
.as_bytes()[l
- 1] == b'
\r' { &line[0 .. l - 1] }
1533 #[stable(feature = "rust1", since = "1.0.0")]
1534 #[allow(deprecated)]
1535 impl<'a
> Iterator
for LinesAny
<'a
> {
1536 type Item
= &'a
str;
1539 fn next(&mut self) -> Option
<&'a
str> {
1544 fn size_hint(&self) -> (usize, Option
<usize>) {
1549 #[stable(feature = "rust1", since = "1.0.0")]
1550 #[allow(deprecated)]
1551 impl<'a
> DoubleEndedIterator
for LinesAny
<'a
> {
1553 fn next_back(&mut self) -> Option
<&'a
str> {
1558 #[stable(feature = "fused", since = "1.26.0")]
1559 #[allow(deprecated)]
1560 impl FusedIterator
for LinesAny
<'_
> {}
1563 Section: UTF-8 validation
1566 // use truncation to fit u64 into usize
1567 const NONASCII_MASK
: usize = 0x80808080_80808080u64 as usize;
1569 /// Returns `true` if any byte in the word `x` is nonascii (>= 128).
1571 fn contains_nonascii(x
: usize) -> bool
{
1572 (x
& NONASCII_MASK
) != 0
1575 /// Walks through `v` checking that it's a valid UTF-8 sequence,
1576 /// returning `Ok(())` in that case, or, if it is invalid, `Err(err)`.
1578 fn run_utf8_validation(v
: &[u8]) -> Result
<(), Utf8Error
> {
1582 let usize_bytes
= mem
::size_of
::<usize>();
1583 let ascii_block_size
= 2 * usize_bytes
;
1584 let blocks_end
= if len
>= ascii_block_size { len - ascii_block_size + 1 }
else { 0 }
;
1585 let align
= v
.as_ptr().align_offset(usize_bytes
);
1588 let old_offset
= index
;
1590 ($error_len
: expr
) => {
1591 return Err(Utf8Error { valid_up_to: old_offset, error_len: $error_len }
);
1598 // we needed data, but there was none: error!
1606 let first
= v
[index
];
1608 let w
= UTF8_CHAR_WIDTH
[first
as usize];
1609 // 2-byte encoding is for codepoints \u{0080} to \u{07ff}
1610 // first C2 80 last DF BF
1611 // 3-byte encoding is for codepoints \u{0800} to \u{ffff}
1612 // first E0 A0 80 last EF BF BF
1613 // excluding surrogates codepoints \u{d800} to \u{dfff}
1614 // ED A0 80 to ED BF BF
1615 // 4-byte encoding is for codepoints \u{1000}0 to \u{10ff}ff
1616 // first F0 90 80 80 last F4 8F BF BF
1618 // Use the UTF-8 syntax from the RFC
1620 // https://tools.ietf.org/html/rfc3629
1622 // UTF8-2 = %xC2-DF UTF8-tail
1623 // UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2( UTF8-tail ) /
1624 // %xED %x80-9F UTF8-tail / %xEE-EF 2( UTF8-tail )
1625 // UTF8-4 = %xF0 %x90-BF 2( UTF8-tail ) / %xF1-F3 3( UTF8-tail ) /
1626 // %xF4 %x80-8F 2( UTF8-tail )
1629 if next
!() & !CONT_MASK
!= TAG_CONT_U8
{
1634 match (first
, next
!()) {
1636 | (0xE1..=0xEC, 0x80..=0xBF)
1637 | (0xED, 0x80..=0x9F)
1638 | (0xEE..=0xEF, 0x80..=0xBF) => {}
1641 if next
!() & !CONT_MASK
!= TAG_CONT_U8
{
1646 match (first
, next
!()) {
1647 (0xF0, 0x90..=0xBF) | (0xF1..=0xF3, 0x80..=0xBF) | (0xF4, 0x80..=0x8F) => {}
1650 if next
!() & !CONT_MASK
!= TAG_CONT_U8
{
1653 if next
!() & !CONT_MASK
!= TAG_CONT_U8
{
1661 // Ascii case, try to skip forward quickly.
1662 // When the pointer is aligned, read 2 words of data per iteration
1663 // until we find a word containing a non-ascii byte.
1664 if align
!= usize::MAX
&& align
.wrapping_sub(index
) % usize_bytes
== 0 {
1665 let ptr
= v
.as_ptr();
1666 while index
< blocks_end
{
1667 // SAFETY: since `align - index` and `ascii_block_size` are
1668 // multiples of `usize_bytes`, `block = ptr.add(index)` is
1669 // always aligned with a `usize` so it's safe to dereference
1670 // both `block` and `block.offset(1)`.
1672 let block
= ptr
.add(index
) as *const usize;
1673 // break if there is a nonascii byte
1674 let zu
= contains_nonascii(*block
);
1675 let zv
= contains_nonascii(*block
.offset(1));
1680 index
+= ascii_block_size
;
1682 // step from the point where the wordwise loop stopped
1683 while index
< len
&& v
[index
] < 128 {
1695 // https://tools.ietf.org/html/rfc3629
1696 static UTF8_CHAR_WIDTH
: [u8; 256] = [
1697 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,
1699 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,
1701 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,
1703 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,
1705 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,
1707 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,
1709 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,
1711 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, // 0xEF
1712 4, 4, 4, 4, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 0xFF
1715 /// Given a first byte, determines how many bytes are in this UTF-8 character.
1716 #[unstable(feature = "str_internals", issue = "none")]
1718 pub fn utf8_char_width(b
: u8) -> usize {
1719 UTF8_CHAR_WIDTH
[b
as usize] as usize
1722 /// Mask of the value bits of a continuation byte.
1723 const CONT_MASK
: u8 = 0b0011_1111;
1724 /// Value of the tag bits (tag mask is !CONT_MASK) of a continuation byte.
1725 const TAG_CONT_U8
: u8 = 0b1000_0000;
1728 Section: Trait implementations
1732 use crate::cmp
::Ordering
;
1734 use crate::slice
::{self, SliceIndex}
;
1736 /// Implements ordering of strings.
1738 /// Strings are ordered lexicographically by their byte values. This orders Unicode code
1739 /// points based on their positions in the code charts. This is not necessarily the same as
1740 /// "alphabetical" order, which varies by language and locale. Sorting strings according to
1741 /// culturally-accepted standards requires locale-specific data that is outside the scope of
1743 #[stable(feature = "rust1", since = "1.0.0")]
1746 fn cmp(&self, other
: &str) -> Ordering
{
1747 self.as_bytes().cmp(other
.as_bytes())
1751 #[stable(feature = "rust1", since = "1.0.0")]
1752 impl PartialEq
for str {
1754 fn eq(&self, other
: &str) -> bool
{
1755 self.as_bytes() == other
.as_bytes()
1758 fn ne(&self, other
: &str) -> bool
{
1763 #[stable(feature = "rust1", since = "1.0.0")]
1766 /// Implements comparison operations on strings.
1768 /// Strings are compared lexicographically by their byte values. This compares Unicode code
1769 /// points based on their positions in the code charts. This is not necessarily the same as
1770 /// "alphabetical" order, which varies by language and locale. Comparing strings according to
1771 /// culturally-accepted standards requires locale-specific data that is outside the scope of
1773 #[stable(feature = "rust1", since = "1.0.0")]
1774 impl PartialOrd
for str {
1776 fn partial_cmp(&self, other
: &str) -> Option
<Ordering
> {
1777 Some(self.cmp(other
))
1781 #[stable(feature = "rust1", since = "1.0.0")]
1782 impl<I
> ops
::Index
<I
> for str
1786 type Output
= I
::Output
;
1789 fn index(&self, index
: I
) -> &I
::Output
{
1794 #[stable(feature = "rust1", since = "1.0.0")]
1795 impl<I
> ops
::IndexMut
<I
> for str
1800 fn index_mut(&mut self, index
: I
) -> &mut I
::Output
{
1801 index
.index_mut(self)
1808 fn str_index_overflow_fail() -> ! {
1809 panic
!("attempted to index str up to maximum usize");
1812 /// Implements substring slicing with syntax `&self[..]` or `&mut self[..]`.
1814 /// Returns a slice of the whole string, i.e., returns `&self` or `&mut
1815 /// self`. Equivalent to `&self[0 .. len]` or `&mut self[0 .. len]`. Unlike
1816 /// other indexing operations, this can never panic.
1818 /// This operation is `O(1)`.
1820 /// Prior to 1.20.0, these indexing operations were still supported by
1821 /// direct implementation of `Index` and `IndexMut`.
1823 /// Equivalent to `&self[0 .. len]` or `&mut self[0 .. len]`.
1824 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1825 impl SliceIndex
<str> for ops
::RangeFull
{
1828 fn get(self, slice
: &str) -> Option
<&Self::Output
> {
1832 fn get_mut(self, slice
: &mut str) -> Option
<&mut Self::Output
> {
1836 unsafe fn get_unchecked(self, slice
: &str) -> &Self::Output
{
1840 unsafe fn get_unchecked_mut(self, slice
: &mut str) -> &mut Self::Output
{
1844 fn index(self, slice
: &str) -> &Self::Output
{
1848 fn index_mut(self, slice
: &mut str) -> &mut Self::Output
{
1853 /// Implements substring slicing with syntax `&self[begin .. end]` or `&mut
1854 /// self[begin .. end]`.
1856 /// Returns a slice of the given string from the byte range
1857 /// [`begin`, `end`).
1859 /// This operation is `O(1)`.
1861 /// Prior to 1.20.0, these indexing operations were still supported by
1862 /// direct implementation of `Index` and `IndexMut`.
1866 /// Panics if `begin` or `end` does not point to the starting byte offset of
1867 /// a character (as defined by `is_char_boundary`), if `begin > end`, or if
1873 /// let s = "Löwe 老虎 Léopard";
1874 /// assert_eq!(&s[0 .. 1], "L");
1876 /// assert_eq!(&s[1 .. 9], "öwe 老");
1878 /// // these will panic:
1879 /// // byte 2 lies within `ö`:
1882 /// // byte 8 lies within `老`
1885 /// // byte 100 is outside the string
1886 /// // &s[3 .. 100];
1888 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1889 impl SliceIndex
<str> for ops
::Range
<usize> {
1892 fn get(self, slice
: &str) -> Option
<&Self::Output
> {
1893 if self.start
<= self.end
1894 && slice
.is_char_boundary(self.start
)
1895 && slice
.is_char_boundary(self.end
)
1897 // SAFETY: just checked that `start` and `end` are on a char boundary.
1898 Some(unsafe { self.get_unchecked(slice) }
)
1904 fn get_mut(self, slice
: &mut str) -> Option
<&mut Self::Output
> {
1905 if self.start
<= self.end
1906 && slice
.is_char_boundary(self.start
)
1907 && slice
.is_char_boundary(self.end
)
1909 // SAFETY: just checked that `start` and `end` are on a char boundary.
1910 Some(unsafe { self.get_unchecked_mut(slice) }
)
1916 unsafe fn get_unchecked(self, slice
: &str) -> &Self::Output
{
1917 // SAFETY: the caller guarantees that `self` is in bounds of `slice`
1918 // which satisfies all the conditions for `add`.
1919 let ptr
= unsafe { slice.as_ptr().add(self.start) }
;
1920 let len
= self.end
- self.start
;
1921 // SAFETY: as the caller guarantees that `self` is in bounds of `slice`,
1922 // we can safely construct a subslice with `from_raw_parts` and use it
1923 // since we return a shared thus immutable reference.
1924 // The call to `from_utf8_unchecked` is safe since the data comes from
1925 // a `str` which is guaranteed to be valid utf8, since the caller
1926 // must guarantee that `self.start` and `self.end` are char boundaries.
1927 unsafe { super::from_utf8_unchecked(slice::from_raw_parts(ptr, len)) }
1930 unsafe fn get_unchecked_mut(self, slice
: &mut str) -> &mut Self::Output
{
1931 // SAFETY: see comments for `get_unchecked`.
1932 let ptr
= unsafe { slice.as_mut_ptr().add(self.start) }
;
1933 let len
= self.end
- self.start
;
1934 // SAFETY: mostly identical to the comments for `get_unchecked`, except that we
1935 // can return a mutable reference since the caller passed a mutable reference
1936 // and is thus guaranteed to have exclusive write access to `slice`.
1937 unsafe { super::from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, len)) }
1940 fn index(self, slice
: &str) -> &Self::Output
{
1941 let (start
, end
) = (self.start
, self.end
);
1942 self.get(slice
).unwrap_or_else(|| super::slice_error_fail(slice
, start
, end
))
1945 fn index_mut(self, slice
: &mut str) -> &mut Self::Output
{
1946 // is_char_boundary checks that the index is in [0, .len()]
1947 // cannot reuse `get` as above, because of NLL trouble
1948 if self.start
<= self.end
1949 && slice
.is_char_boundary(self.start
)
1950 && slice
.is_char_boundary(self.end
)
1952 // SAFETY: just checked that `start` and `end` are on a char boundary.
1953 unsafe { self.get_unchecked_mut(slice) }
1955 super::slice_error_fail(slice
, self.start
, self.end
)
1960 /// Implements substring slicing with syntax `&self[.. end]` or `&mut
1963 /// Returns a slice of the given string from the byte range [`0`, `end`).
1964 /// Equivalent to `&self[0 .. end]` or `&mut self[0 .. end]`.
1966 /// This operation is `O(1)`.
1968 /// Prior to 1.20.0, these indexing operations were still supported by
1969 /// direct implementation of `Index` and `IndexMut`.
1973 /// Panics if `end` does not point to the starting byte offset of a
1974 /// character (as defined by `is_char_boundary`), or if `end > len`.
1975 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
1976 impl SliceIndex
<str> for ops
::RangeTo
<usize> {
1979 fn get(self, slice
: &str) -> Option
<&Self::Output
> {
1980 if slice
.is_char_boundary(self.end
) {
1981 // SAFETY: just checked that `end` is on a char boundary.
1982 Some(unsafe { self.get_unchecked(slice) }
)
1988 fn get_mut(self, slice
: &mut str) -> Option
<&mut Self::Output
> {
1989 if slice
.is_char_boundary(self.end
) {
1990 // SAFETY: just checked that `end` is on a char boundary.
1991 Some(unsafe { self.get_unchecked_mut(slice) }
)
1997 unsafe fn get_unchecked(self, slice
: &str) -> &Self::Output
{
1998 let ptr
= slice
.as_ptr();
1999 // SAFETY: as the caller guarantees that `self` is in bounds of `slice`,
2000 // we can safely construct a subslice with `from_raw_parts` and use it
2001 // since we return a shared thus immutable reference.
2002 // The call to `from_utf8_unchecked` is safe since the data comes from
2003 // a `str` which is guaranteed to be valid utf8, since the caller
2004 // must guarantee that `self.end` is a char boundary.
2005 unsafe { super::from_utf8_unchecked(slice::from_raw_parts(ptr, self.end)) }
2008 unsafe fn get_unchecked_mut(self, slice
: &mut str) -> &mut Self::Output
{
2009 let ptr
= slice
.as_mut_ptr();
2010 // SAFETY: mostly identical to `get_unchecked`, except that we can safely
2011 // return a mutable reference since the caller passed a mutable reference
2012 // and is thus guaranteed to have exclusive write access to `slice`.
2013 unsafe { super::from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, self.end)) }
2016 fn index(self, slice
: &str) -> &Self::Output
{
2018 self.get(slice
).unwrap_or_else(|| super::slice_error_fail(slice
, 0, end
))
2021 fn index_mut(self, slice
: &mut str) -> &mut Self::Output
{
2022 if slice
.is_char_boundary(self.end
) {
2023 // SAFETY: just checked that `end` is on a char boundary.
2024 unsafe { self.get_unchecked_mut(slice) }
2026 super::slice_error_fail(slice
, 0, self.end
)
2031 /// Implements substring slicing with syntax `&self[begin ..]` or `&mut
2032 /// self[begin ..]`.
2034 /// Returns a slice of the given string from the byte range [`begin`,
2035 /// `len`). Equivalent to `&self[begin .. len]` or `&mut self[begin ..
2038 /// This operation is `O(1)`.
2040 /// Prior to 1.20.0, these indexing operations were still supported by
2041 /// direct implementation of `Index` and `IndexMut`.
2045 /// Panics if `begin` does not point to the starting byte offset of
2046 /// a character (as defined by `is_char_boundary`), or if `begin >= len`.
2047 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2048 impl SliceIndex
<str> for ops
::RangeFrom
<usize> {
2051 fn get(self, slice
: &str) -> Option
<&Self::Output
> {
2052 if slice
.is_char_boundary(self.start
) {
2053 // SAFETY: just checked that `start` is on a char boundary.
2054 Some(unsafe { self.get_unchecked(slice) }
)
2060 fn get_mut(self, slice
: &mut str) -> Option
<&mut Self::Output
> {
2061 if slice
.is_char_boundary(self.start
) {
2062 // SAFETY: just checked that `start` is on a char boundary.
2063 Some(unsafe { self.get_unchecked_mut(slice) }
)
2069 unsafe fn get_unchecked(self, slice
: &str) -> &Self::Output
{
2070 // SAFETY: the caller guarantees that `self` is in bounds of `slice`
2071 // which satisfies all the conditions for `add`.
2072 let ptr
= unsafe { slice.as_ptr().add(self.start) }
;
2073 let len
= slice
.len() - self.start
;
2074 // SAFETY: as the caller guarantees that `self` is in bounds of `slice`,
2075 // we can safely construct a subslice with `from_raw_parts` and use it
2076 // since we return a shared thus immutable reference.
2077 // The call to `from_utf8_unchecked` is safe since the data comes from
2078 // a `str` which is guaranteed to be valid utf8, since the caller
2079 // must guarantee that `self.start` is a char boundary.
2080 unsafe { super::from_utf8_unchecked(slice::from_raw_parts(ptr, len)) }
2083 unsafe fn get_unchecked_mut(self, slice
: &mut str) -> &mut Self::Output
{
2084 // SAFETY: identical to `get_unchecked`.
2085 let ptr
= unsafe { slice.as_mut_ptr().add(self.start) }
;
2086 let len
= slice
.len() - self.start
;
2087 // SAFETY: mostly identical to `get_unchecked`, except that we can safely
2088 // return a mutable reference since the caller passed a mutable reference
2089 // and is thus guaranteed to have exclusive write access to `slice`.
2090 unsafe { super::from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, len)) }
2093 fn index(self, slice
: &str) -> &Self::Output
{
2094 let (start
, end
) = (self.start
, slice
.len());
2095 self.get(slice
).unwrap_or_else(|| super::slice_error_fail(slice
, start
, end
))
2098 fn index_mut(self, slice
: &mut str) -> &mut Self::Output
{
2099 if slice
.is_char_boundary(self.start
) {
2100 // SAFETY: just checked that `start` is on a char boundary.
2101 unsafe { self.get_unchecked_mut(slice) }
2103 super::slice_error_fail(slice
, self.start
, slice
.len())
2108 /// Implements substring slicing with syntax `&self[begin ..= end]` or `&mut
2109 /// self[begin ..= end]`.
2111 /// Returns a slice of the given string from the byte range
2112 /// [`begin`, `end`]. Equivalent to `&self [begin .. end + 1]` or `&mut
2113 /// self[begin .. end + 1]`, except if `end` has the maximum value for
2116 /// This operation is `O(1)`.
2120 /// Panics if `begin` does not point to the starting byte offset of
2121 /// a character (as defined by `is_char_boundary`), if `end` does not point
2122 /// to the ending byte offset of a character (`end + 1` is either a starting
2123 /// byte offset or equal to `len`), if `begin > end`, or if `end >= len`.
2124 #[stable(feature = "inclusive_range", since = "1.26.0")]
2125 impl SliceIndex
<str> for ops
::RangeInclusive
<usize> {
2128 fn get(self, slice
: &str) -> Option
<&Self::Output
> {
2129 if *self.end() == usize::MAX
{
2132 (*self.start()..self.end() + 1).get(slice
)
2136 fn get_mut(self, slice
: &mut str) -> Option
<&mut Self::Output
> {
2137 if *self.end() == usize::MAX
{
2140 (*self.start()..self.end() + 1).get_mut(slice
)
2144 unsafe fn get_unchecked(self, slice
: &str) -> &Self::Output
{
2145 // SAFETY: the caller must uphold the safety contract for `get_unchecked`.
2146 unsafe { (*self.start()..self.end() + 1).get_unchecked(slice) }
2149 unsafe fn get_unchecked_mut(self, slice
: &mut str) -> &mut Self::Output
{
2150 // SAFETY: the caller must uphold the safety contract for `get_unchecked_mut`.
2151 unsafe { (*self.start()..self.end() + 1).get_unchecked_mut(slice) }
2154 fn index(self, slice
: &str) -> &Self::Output
{
2155 if *self.end() == usize::MAX
{
2156 str_index_overflow_fail();
2158 (*self.start()..self.end() + 1).index(slice
)
2161 fn index_mut(self, slice
: &mut str) -> &mut Self::Output
{
2162 if *self.end() == usize::MAX
{
2163 str_index_overflow_fail();
2165 (*self.start()..self.end() + 1).index_mut(slice
)
2169 /// Implements substring slicing with syntax `&self[..= end]` or `&mut
2172 /// Returns a slice of the given string from the byte range [0, `end`].
2173 /// Equivalent to `&self [0 .. end + 1]`, except if `end` has the maximum
2174 /// value for `usize`.
2176 /// This operation is `O(1)`.
2180 /// Panics if `end` does not point to the ending byte offset of a character
2181 /// (`end + 1` is either a starting byte offset as defined by
2182 /// `is_char_boundary`, or equal to `len`), or if `end >= len`.
2183 #[stable(feature = "inclusive_range", since = "1.26.0")]
2184 impl SliceIndex
<str> for ops
::RangeToInclusive
<usize> {
2187 fn get(self, slice
: &str) -> Option
<&Self::Output
> {
2188 if self.end
== usize::MAX { None }
else { (..self.end + 1).get(slice) }
2191 fn get_mut(self, slice
: &mut str) -> Option
<&mut Self::Output
> {
2192 if self.end
== usize::MAX { None }
else { (..self.end + 1).get_mut(slice) }
2195 unsafe fn get_unchecked(self, slice
: &str) -> &Self::Output
{
2196 // SAFETY: the caller must uphold the safety contract for `get_unchecked`.
2197 unsafe { (..self.end + 1).get_unchecked(slice) }
2200 unsafe fn get_unchecked_mut(self, slice
: &mut str) -> &mut Self::Output
{
2201 // SAFETY: the caller must uphold the safety contract for `get_unchecked_mut`.
2202 unsafe { (..self.end + 1).get_unchecked_mut(slice) }
2205 fn index(self, slice
: &str) -> &Self::Output
{
2206 if self.end
== usize::MAX
{
2207 str_index_overflow_fail();
2209 (..self.end
+ 1).index(slice
)
2212 fn index_mut(self, slice
: &mut str) -> &mut Self::Output
{
2213 if self.end
== usize::MAX
{
2214 str_index_overflow_fail();
2216 (..self.end
+ 1).index_mut(slice
)
2221 // truncate `&str` to length at most equal to `max`
2222 // return `true` if it were truncated, and the new str.
2223 fn truncate_to_char_boundary(s
: &str, mut max
: usize) -> (bool
, &str) {
2227 while !s
.is_char_boundary(max
) {
2237 fn slice_error_fail(s
: &str, begin
: usize, end
: usize) -> ! {
2238 const MAX_DISPLAY_LENGTH
: usize = 256;
2239 let (truncated
, s_trunc
) = truncate_to_char_boundary(s
, MAX_DISPLAY_LENGTH
);
2240 let ellipsis
= if truncated { "[...]" }
else { "" }
;
2243 if begin
> s
.len() || end
> s
.len() {
2244 let oob_index
= if begin
> s
.len() { begin }
else { end }
;
2245 panic
!("byte index {} is out of bounds of `{}`{}", oob_index
, s_trunc
, ellipsis
);
2251 "begin <= end ({} <= {}) when slicing `{}`{}",
2258 // 3. character boundary
2259 let index
= if !s
.is_char_boundary(begin
) { begin }
else { end }
;
2260 // find the character
2261 let mut char_start
= index
;
2262 while !s
.is_char_boundary(char_start
) {
2265 // `char_start` must be less than len and a char boundary
2266 let ch
= s
[char_start
..].chars().next().unwrap();
2267 let char_range
= char_start
..char_start
+ ch
.len_utf8();
2269 "byte index {} is not a char boundary; it is inside {:?} (bytes {:?}) of `{}`{}",
2270 index
, ch
, char_range
, s_trunc
, ellipsis
2277 /// Returns the length of `self`.
2279 /// This length is in bytes, not [`char`]s or graphemes. In other words,
2280 /// it may not be what a human considers the length of the string.
2287 /// let len = "foo".len();
2288 /// assert_eq!(3, len);
2290 /// assert_eq!("ƒoo".len(), 4); // fancy f!
2291 /// assert_eq!("ƒoo".chars().count(), 3);
2293 #[stable(feature = "rust1", since = "1.0.0")]
2294 #[rustc_const_stable(feature = "const_str_len", since = "1.32.0")]
2296 pub const fn len(&self) -> usize {
2297 self.as_bytes().len()
2300 /// Returns `true` if `self` has a length of zero bytes.
2308 /// assert!(s.is_empty());
2310 /// let s = "not empty";
2311 /// assert!(!s.is_empty());
2314 #[stable(feature = "rust1", since = "1.0.0")]
2315 #[rustc_const_stable(feature = "const_str_is_empty", since = "1.32.0")]
2316 pub const fn is_empty(&self) -> bool
{
2320 /// Checks that `index`-th byte is the first byte in a UTF-8 code point
2321 /// sequence or the end of the string.
2323 /// The start and end of the string (when `index == self.len()`) are
2324 /// considered to be boundaries.
2326 /// Returns `false` if `index` is greater than `self.len()`.
2331 /// let s = "Löwe 老虎 Léopard";
2332 /// assert!(s.is_char_boundary(0));
2334 /// assert!(s.is_char_boundary(6));
2335 /// assert!(s.is_char_boundary(s.len()));
2337 /// // second byte of `ö`
2338 /// assert!(!s.is_char_boundary(2));
2340 /// // third byte of `老`
2341 /// assert!(!s.is_char_boundary(8));
2343 #[stable(feature = "is_char_boundary", since = "1.9.0")]
2345 pub fn is_char_boundary(&self, index
: usize) -> bool
{
2346 // 0 and len are always ok.
2347 // Test for 0 explicitly so that it can optimize out the check
2348 // easily and skip reading string data for that case.
2349 if index
== 0 || index
== self.len() {
2352 match self.as_bytes().get(index
) {
2354 // This is bit magic equivalent to: b < 128 || b >= 192
2355 Some(&b
) => (b
as i8) >= -0x40,
2359 /// Converts a string slice to a byte slice. To convert the byte slice back
2360 /// into a string slice, use the [`str::from_utf8`] function.
2362 /// [`str::from_utf8`]: ./str/fn.from_utf8.html
2369 /// let bytes = "bors".as_bytes();
2370 /// assert_eq!(b"bors", bytes);
2372 #[stable(feature = "rust1", since = "1.0.0")]
2373 #[rustc_const_stable(feature = "str_as_bytes", since = "1.32.0")]
2375 #[allow(unused_attributes)]
2376 #[allow_internal_unstable(const_fn_union)]
2377 pub const fn as_bytes(&self) -> &[u8] {
2383 // SAFETY: const sound because we transmute two types with the same layout
2384 unsafe { Slices { str: self }
.slice
}
2387 /// Converts a mutable string slice to a mutable byte slice. To convert the
2388 /// mutable byte slice back into a mutable string slice, use the
2389 /// [`str::from_utf8_mut`] function.
2391 /// [`str::from_utf8_mut`]: ./str/fn.from_utf8_mut.html
2398 /// let mut s = String::from("Hello");
2399 /// let bytes = unsafe { s.as_bytes_mut() };
2401 /// assert_eq!(b"Hello", bytes);
2407 /// let mut s = String::from("🗻∈🌏");
2410 /// let bytes = s.as_bytes_mut();
2412 /// bytes[0] = 0xF0;
2413 /// bytes[1] = 0x9F;
2414 /// bytes[2] = 0x8D;
2415 /// bytes[3] = 0x94;
2418 /// assert_eq!("🍔∈🌏", s);
2420 #[stable(feature = "str_mut_extras", since = "1.20.0")]
2422 pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8] {
2423 // SAFETY: the cast from `&str` to `&[u8]` is safe since `str`
2424 // has the same layout as `&[u8]` (only libstd can make this guarantee).
2425 // The pointer dereference is safe since it comes from a mutable reference which
2426 // is guaranteed to be valid for writes.
2427 unsafe { &mut *(self as *mut str as *mut [u8]) }
2430 /// Converts a string slice to a raw pointer.
2432 /// As string slices are a slice of bytes, the raw pointer points to a
2433 /// [`u8`]. This pointer will be pointing to the first byte of the string
2436 /// The caller must ensure that the returned pointer is never written to.
2437 /// If you need to mutate the contents of the string slice, use [`as_mut_ptr`].
2439 /// [`u8`]: primitive.u8.html
2440 /// [`as_mut_ptr`]: #method.as_mut_ptr
2447 /// let s = "Hello";
2448 /// let ptr = s.as_ptr();
2450 #[stable(feature = "rust1", since = "1.0.0")]
2451 #[rustc_const_stable(feature = "rustc_str_as_ptr", since = "1.32.0")]
2453 pub const fn as_ptr(&self) -> *const u8 {
2454 self as *const str as *const u8
2457 /// Converts a mutable string slice to a raw pointer.
2459 /// As string slices are a slice of bytes, the raw pointer points to a
2460 /// [`u8`]. This pointer will be pointing to the first byte of the string
2463 /// It is your responsibility to make sure that the string slice only gets
2464 /// modified in a way that it remains valid UTF-8.
2466 /// [`u8`]: primitive.u8.html
2467 #[stable(feature = "str_as_mut_ptr", since = "1.36.0")]
2469 pub fn as_mut_ptr(&mut self) -> *mut u8 {
2470 self as *mut str as *mut u8
2473 /// Returns a subslice of `str`.
2475 /// This is the non-panicking alternative to indexing the `str`. Returns
2476 /// [`None`] whenever equivalent indexing operation would panic.
2478 /// [`None`]: option/enum.Option.html#variant.None
2483 /// let v = String::from("🗻∈🌏");
2485 /// assert_eq!(Some("🗻"), v.get(0..4));
2487 /// // indices not on UTF-8 sequence boundaries
2488 /// assert!(v.get(1..).is_none());
2489 /// assert!(v.get(..8).is_none());
2491 /// // out of bounds
2492 /// assert!(v.get(..42).is_none());
2494 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2496 pub fn get
<I
: SliceIndex
<str>>(&self, i
: I
) -> Option
<&I
::Output
> {
2500 /// Returns a mutable subslice of `str`.
2502 /// This is the non-panicking alternative to indexing the `str`. Returns
2503 /// [`None`] whenever equivalent indexing operation would panic.
2505 /// [`None`]: option/enum.Option.html#variant.None
2510 /// let mut v = String::from("hello");
2511 /// // correct length
2512 /// assert!(v.get_mut(0..5).is_some());
2513 /// // out of bounds
2514 /// assert!(v.get_mut(..42).is_none());
2515 /// assert_eq!(Some("he"), v.get_mut(0..2).map(|v| &*v));
2517 /// assert_eq!("hello", v);
2519 /// let s = v.get_mut(0..2);
2520 /// let s = s.map(|s| {
2521 /// s.make_ascii_uppercase();
2524 /// assert_eq!(Some("HE"), s);
2526 /// assert_eq!("HEllo", v);
2528 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2530 pub fn get_mut
<I
: SliceIndex
<str>>(&mut self, i
: I
) -> Option
<&mut I
::Output
> {
2534 /// Returns an unchecked subslice of `str`.
2536 /// This is the unchecked alternative to indexing the `str`.
2540 /// Callers of this function are responsible that these preconditions are
2543 /// * The starting index must not exceed the ending index;
2544 /// * Indexes must be within bounds of the original slice;
2545 /// * Indexes must lie on UTF-8 sequence boundaries.
2547 /// Failing that, the returned string slice may reference invalid memory or
2548 /// violate the invariants communicated by the `str` type.
2555 /// assert_eq!("🗻", v.get_unchecked(0..4));
2556 /// assert_eq!("∈", v.get_unchecked(4..7));
2557 /// assert_eq!("🌏", v.get_unchecked(7..11));
2560 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2562 pub unsafe fn get_unchecked
<I
: SliceIndex
<str>>(&self, i
: I
) -> &I
::Output
{
2563 // SAFETY: the caller must uphold the safety contract for `get_unchecked`.
2564 unsafe { i.get_unchecked(self) }
2567 /// Returns a mutable, unchecked subslice of `str`.
2569 /// This is the unchecked alternative to indexing the `str`.
2573 /// Callers of this function are responsible that these preconditions are
2576 /// * The starting index must not exceed the ending index;
2577 /// * Indexes must be within bounds of the original slice;
2578 /// * Indexes must lie on UTF-8 sequence boundaries.
2580 /// Failing that, the returned string slice may reference invalid memory or
2581 /// violate the invariants communicated by the `str` type.
2586 /// let mut v = String::from("🗻∈🌏");
2588 /// assert_eq!("🗻", v.get_unchecked_mut(0..4));
2589 /// assert_eq!("∈", v.get_unchecked_mut(4..7));
2590 /// assert_eq!("🌏", v.get_unchecked_mut(7..11));
2593 #[stable(feature = "str_checked_slicing", since = "1.20.0")]
2595 pub unsafe fn get_unchecked_mut
<I
: SliceIndex
<str>>(&mut self, i
: I
) -> &mut I
::Output
{
2596 // SAFETY: the caller must uphold the safety contract for `get_unchecked_mut`.
2597 unsafe { i.get_unchecked_mut(self) }
2600 /// Creates a string slice from another string slice, bypassing safety
2603 /// This is generally not recommended, use with caution! For a safe
2604 /// alternative see [`str`] and [`Index`].
2606 /// [`str`]: primitive.str.html
2607 /// [`Index`]: ops/trait.Index.html
2609 /// This new slice goes from `begin` to `end`, including `begin` but
2610 /// excluding `end`.
2612 /// To get a mutable string slice instead, see the
2613 /// [`slice_mut_unchecked`] method.
2615 /// [`slice_mut_unchecked`]: #method.slice_mut_unchecked
2619 /// Callers of this function are responsible that three preconditions are
2622 /// * `begin` must not exceed `end`.
2623 /// * `begin` and `end` must be byte positions within the string slice.
2624 /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
2631 /// let s = "Löwe 老虎 Léopard";
2634 /// assert_eq!("Löwe 老虎 Léopard", s.slice_unchecked(0, 21));
2637 /// let s = "Hello, world!";
2640 /// assert_eq!("world", s.slice_unchecked(7, 12));
2643 #[stable(feature = "rust1", since = "1.0.0")]
2644 #[rustc_deprecated(since = "1.29.0", reason = "use `get_unchecked(begin..end)` instead")]
2646 pub unsafe fn slice_unchecked(&self, begin
: usize, end
: usize) -> &str {
2647 // SAFETY: the caller must uphold the safety contract for `get_unchecked`.
2648 unsafe { (begin..end).get_unchecked(self) }
2651 /// Creates a string slice from another string slice, bypassing safety
2653 /// This is generally not recommended, use with caution! For a safe
2654 /// alternative see [`str`] and [`IndexMut`].
2656 /// [`str`]: primitive.str.html
2657 /// [`IndexMut`]: ops/trait.IndexMut.html
2659 /// This new slice goes from `begin` to `end`, including `begin` but
2660 /// excluding `end`.
2662 /// To get an immutable string slice instead, see the
2663 /// [`slice_unchecked`] method.
2665 /// [`slice_unchecked`]: #method.slice_unchecked
2669 /// Callers of this function are responsible that three preconditions are
2672 /// * `begin` must not exceed `end`.
2673 /// * `begin` and `end` must be byte positions within the string slice.
2674 /// * `begin` and `end` must lie on UTF-8 sequence boundaries.
2675 #[stable(feature = "str_slice_mut", since = "1.5.0")]
2676 #[rustc_deprecated(since = "1.29.0", reason = "use `get_unchecked_mut(begin..end)` instead")]
2678 pub unsafe fn slice_mut_unchecked(&mut self, begin
: usize, end
: usize) -> &mut str {
2679 // SAFETY: the caller must uphold the safety contract for `get_unchecked_mut`.
2680 unsafe { (begin..end).get_unchecked_mut(self) }
2683 /// Divide one string slice into two at an index.
2685 /// The argument, `mid`, should be a byte offset from the start of the
2686 /// string. It must also be on the boundary of a UTF-8 code point.
2688 /// The two slices returned go from the start of the string slice to `mid`,
2689 /// and from `mid` to the end of the string slice.
2691 /// To get mutable string slices instead, see the [`split_at_mut`]
2694 /// [`split_at_mut`]: #method.split_at_mut
2698 /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
2699 /// past the end of the last code point of the string slice.
2706 /// let s = "Per Martin-Löf";
2708 /// let (first, last) = s.split_at(3);
2710 /// assert_eq!("Per", first);
2711 /// assert_eq!(" Martin-Löf", last);
2714 #[stable(feature = "str_split_at", since = "1.4.0")]
2715 pub fn split_at(&self, mid
: usize) -> (&str, &str) {
2716 // is_char_boundary checks that the index is in [0, .len()]
2717 if self.is_char_boundary(mid
) {
2718 // SAFETY: just checked that `mid` is on a char boundary.
2719 unsafe { (self.get_unchecked(0..mid), self.get_unchecked(mid..self.len())) }
2721 slice_error_fail(self, 0, mid
)
2725 /// Divide one mutable string slice into two at an index.
2727 /// The argument, `mid`, should be a byte offset from the start of the
2728 /// string. It must also be on the boundary of a UTF-8 code point.
2730 /// The two slices returned go from the start of the string slice to `mid`,
2731 /// and from `mid` to the end of the string slice.
2733 /// To get immutable string slices instead, see the [`split_at`] method.
2735 /// [`split_at`]: #method.split_at
2739 /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is
2740 /// past the end of the last code point of the string slice.
2747 /// let mut s = "Per Martin-Löf".to_string();
2749 /// let (first, last) = s.split_at_mut(3);
2750 /// first.make_ascii_uppercase();
2751 /// assert_eq!("PER", first);
2752 /// assert_eq!(" Martin-Löf", last);
2754 /// assert_eq!("PER Martin-Löf", s);
2757 #[stable(feature = "str_split_at", since = "1.4.0")]
2758 pub fn split_at_mut(&mut self, mid
: usize) -> (&mut str, &mut str) {
2759 // is_char_boundary checks that the index is in [0, .len()]
2760 if self.is_char_boundary(mid
) {
2761 let len
= self.len();
2762 let ptr
= self.as_mut_ptr();
2763 // SAFETY: just checked that `mid` is on a char boundary.
2766 from_utf8_unchecked_mut(slice
::from_raw_parts_mut(ptr
, mid
)),
2767 from_utf8_unchecked_mut(slice
::from_raw_parts_mut(ptr
.add(mid
), len
- mid
)),
2771 slice_error_fail(self, 0, mid
)
2775 /// Returns an iterator over the [`char`]s of a string slice.
2777 /// As a string slice consists of valid UTF-8, we can iterate through a
2778 /// string slice by [`char`]. This method returns such an iterator.
2780 /// It's important to remember that [`char`] represents a Unicode Scalar
2781 /// Value, and may not match your idea of what a 'character' is. Iteration
2782 /// over grapheme clusters may be what you actually want. This functionality
2783 /// is not provided by Rust's standard library, check crates.io instead.
2790 /// let word = "goodbye";
2792 /// let count = word.chars().count();
2793 /// assert_eq!(7, count);
2795 /// let mut chars = word.chars();
2797 /// assert_eq!(Some('g'), chars.next());
2798 /// assert_eq!(Some('o'), chars.next());
2799 /// assert_eq!(Some('o'), chars.next());
2800 /// assert_eq!(Some('d'), chars.next());
2801 /// assert_eq!(Some('b'), chars.next());
2802 /// assert_eq!(Some('y'), chars.next());
2803 /// assert_eq!(Some('e'), chars.next());
2805 /// assert_eq!(None, chars.next());
2808 /// Remember, [`char`]s may not match your human intuition about characters:
2813 /// let mut chars = y.chars();
2815 /// assert_eq!(Some('y'), chars.next()); // not 'y̆'
2816 /// assert_eq!(Some('\u{0306}'), chars.next());
2818 /// assert_eq!(None, chars.next());
2820 #[stable(feature = "rust1", since = "1.0.0")]
2822 pub fn chars(&self) -> Chars
<'_
> {
2823 Chars { iter: self.as_bytes().iter() }
2826 /// Returns an iterator over the [`char`]s of a string slice, and their
2829 /// As a string slice consists of valid UTF-8, we can iterate through a
2830 /// string slice by [`char`]. This method returns an iterator of both
2831 /// these [`char`]s, as well as their byte positions.
2833 /// The iterator yields tuples. The position is first, the [`char`] is
2841 /// let word = "goodbye";
2843 /// let count = word.char_indices().count();
2844 /// assert_eq!(7, count);
2846 /// let mut char_indices = word.char_indices();
2848 /// assert_eq!(Some((0, 'g')), char_indices.next());
2849 /// assert_eq!(Some((1, 'o')), char_indices.next());
2850 /// assert_eq!(Some((2, 'o')), char_indices.next());
2851 /// assert_eq!(Some((3, 'd')), char_indices.next());
2852 /// assert_eq!(Some((4, 'b')), char_indices.next());
2853 /// assert_eq!(Some((5, 'y')), char_indices.next());
2854 /// assert_eq!(Some((6, 'e')), char_indices.next());
2856 /// assert_eq!(None, char_indices.next());
2859 /// Remember, [`char`]s may not match your human intuition about characters:
2862 /// let yes = "y̆es";
2864 /// let mut char_indices = yes.char_indices();
2866 /// assert_eq!(Some((0, 'y')), char_indices.next()); // not (0, 'y̆')
2867 /// assert_eq!(Some((1, '\u{0306}')), char_indices.next());
2869 /// // note the 3 here - the last character took up two bytes
2870 /// assert_eq!(Some((3, 'e')), char_indices.next());
2871 /// assert_eq!(Some((4, 's')), char_indices.next());
2873 /// assert_eq!(None, char_indices.next());
2875 #[stable(feature = "rust1", since = "1.0.0")]
2877 pub fn char_indices(&self) -> CharIndices
<'_
> {
2878 CharIndices { front_offset: 0, iter: self.chars() }
2881 /// An iterator over the bytes of a string slice.
2883 /// As a string slice consists of a sequence of bytes, we can iterate
2884 /// through a string slice by byte. This method returns such an iterator.
2891 /// let mut bytes = "bors".bytes();
2893 /// assert_eq!(Some(b'b'), bytes.next());
2894 /// assert_eq!(Some(b'o'), bytes.next());
2895 /// assert_eq!(Some(b'r'), bytes.next());
2896 /// assert_eq!(Some(b's'), bytes.next());
2898 /// assert_eq!(None, bytes.next());
2900 #[stable(feature = "rust1", since = "1.0.0")]
2902 pub fn bytes(&self) -> Bytes
<'_
> {
2903 Bytes(self.as_bytes().iter().copied())
2906 /// Splits a string slice by whitespace.
2908 /// The iterator returned will return string slices that are sub-slices of
2909 /// the original string slice, separated by any amount of whitespace.
2911 /// 'Whitespace' is defined according to the terms of the Unicode Derived
2912 /// Core Property `White_Space`. If you only want to split on ASCII whitespace
2913 /// instead, use [`split_ascii_whitespace`].
2915 /// [`split_ascii_whitespace`]: #method.split_ascii_whitespace
2922 /// let mut iter = "A few words".split_whitespace();
2924 /// assert_eq!(Some("A"), iter.next());
2925 /// assert_eq!(Some("few"), iter.next());
2926 /// assert_eq!(Some("words"), iter.next());
2928 /// assert_eq!(None, iter.next());
2931 /// All kinds of whitespace are considered:
2934 /// let mut iter = " Mary had\ta\u{2009}little \n\t lamb".split_whitespace();
2935 /// assert_eq!(Some("Mary"), iter.next());
2936 /// assert_eq!(Some("had"), iter.next());
2937 /// assert_eq!(Some("a"), iter.next());
2938 /// assert_eq!(Some("little"), iter.next());
2939 /// assert_eq!(Some("lamb"), iter.next());
2941 /// assert_eq!(None, iter.next());
2943 #[stable(feature = "split_whitespace", since = "1.1.0")]
2945 pub fn split_whitespace(&self) -> SplitWhitespace
<'_
> {
2946 SplitWhitespace { inner: self.split(IsWhitespace).filter(IsNotEmpty) }
2949 /// Splits a string slice by ASCII whitespace.
2951 /// The iterator returned will return string slices that are sub-slices of
2952 /// the original string slice, separated by any amount of ASCII whitespace.
2954 /// To split by Unicode `Whitespace` instead, use [`split_whitespace`].
2956 /// [`split_whitespace`]: #method.split_whitespace
2963 /// let mut iter = "A few words".split_ascii_whitespace();
2965 /// assert_eq!(Some("A"), iter.next());
2966 /// assert_eq!(Some("few"), iter.next());
2967 /// assert_eq!(Some("words"), iter.next());
2969 /// assert_eq!(None, iter.next());
2972 /// All kinds of ASCII whitespace are considered:
2975 /// let mut iter = " Mary had\ta little \n\t lamb".split_ascii_whitespace();
2976 /// assert_eq!(Some("Mary"), iter.next());
2977 /// assert_eq!(Some("had"), iter.next());
2978 /// assert_eq!(Some("a"), iter.next());
2979 /// assert_eq!(Some("little"), iter.next());
2980 /// assert_eq!(Some("lamb"), iter.next());
2982 /// assert_eq!(None, iter.next());
2984 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
2986 pub fn split_ascii_whitespace(&self) -> SplitAsciiWhitespace
<'_
> {
2988 self.as_bytes().split(IsAsciiWhitespace
).filter(BytesIsNotEmpty
).map(UnsafeBytesToStr
);
2989 SplitAsciiWhitespace { inner }
2992 /// An iterator over the lines of a string, as string slices.
2994 /// Lines are ended with either a newline (`\n`) or a carriage return with
2995 /// a line feed (`\r\n`).
2997 /// The final line ending is optional.
3004 /// let text = "foo\r\nbar\n\nbaz\n";
3005 /// let mut lines = text.lines();
3007 /// assert_eq!(Some("foo"), lines.next());
3008 /// assert_eq!(Some("bar"), lines.next());
3009 /// assert_eq!(Some(""), lines.next());
3010 /// assert_eq!(Some("baz"), lines.next());
3012 /// assert_eq!(None, lines.next());
3015 /// The final line ending isn't required:
3018 /// let text = "foo\nbar\n\r\nbaz";
3019 /// let mut lines = text.lines();
3021 /// assert_eq!(Some("foo"), lines.next());
3022 /// assert_eq!(Some("bar"), lines.next());
3023 /// assert_eq!(Some(""), lines.next());
3024 /// assert_eq!(Some("baz"), lines.next());
3026 /// assert_eq!(None, lines.next());
3028 #[stable(feature = "rust1", since = "1.0.0")]
3030 pub fn lines(&self) -> Lines
<'_
> {
3031 Lines(self.split_terminator('
\n'
).map(LinesAnyMap
))
3034 /// An iterator over the lines of a string.
3035 #[stable(feature = "rust1", since = "1.0.0")]
3036 #[rustc_deprecated(since = "1.4.0", reason = "use lines() instead now")]
3038 #[allow(deprecated)]
3039 pub fn lines_any(&self) -> LinesAny
<'_
> {
3040 LinesAny(self.lines())
3043 /// Returns an iterator of `u16` over the string encoded as UTF-16.
3050 /// let text = "Zażółć gęślą jaźń";
3052 /// let utf8_len = text.len();
3053 /// let utf16_len = text.encode_utf16().count();
3055 /// assert!(utf16_len <= utf8_len);
3057 #[stable(feature = "encode_utf16", since = "1.8.0")]
3058 pub fn encode_utf16(&self) -> EncodeUtf16
<'_
> {
3059 EncodeUtf16 { chars: self.chars(), extra: 0 }
3062 /// Returns `true` if the given pattern matches a sub-slice of
3063 /// this string slice.
3065 /// Returns `false` if it does not.
3067 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3068 /// function or closure that determines if a character matches.
3070 /// [`char`]: primitive.char.html
3071 /// [pattern]: str/pattern/index.html
3078 /// let bananas = "bananas";
3080 /// assert!(bananas.contains("nana"));
3081 /// assert!(!bananas.contains("apples"));
3083 #[stable(feature = "rust1", since = "1.0.0")]
3085 pub fn contains
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> bool
{
3086 pat
.is_contained_in(self)
3089 /// Returns `true` if the given pattern matches a prefix of this
3092 /// Returns `false` if it does not.
3094 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3095 /// function or closure that determines if a character matches.
3097 /// [`char`]: primitive.char.html
3098 /// [pattern]: str/pattern/index.html
3105 /// let bananas = "bananas";
3107 /// assert!(bananas.starts_with("bana"));
3108 /// assert!(!bananas.starts_with("nana"));
3110 #[stable(feature = "rust1", since = "1.0.0")]
3111 pub fn starts_with
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> bool
{
3112 pat
.is_prefix_of(self)
3115 /// Returns `true` if the given pattern matches a suffix of this
3118 /// Returns `false` if it does not.
3120 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3121 /// function or closure that determines if a character matches.
3123 /// [`char`]: primitive.char.html
3124 /// [pattern]: str/pattern/index.html
3131 /// let bananas = "bananas";
3133 /// assert!(bananas.ends_with("anas"));
3134 /// assert!(!bananas.ends_with("nana"));
3136 #[stable(feature = "rust1", since = "1.0.0")]
3137 pub fn ends_with
<'a
, P
>(&'a
self, pat
: P
) -> bool
3139 P
: Pattern
<'a
, Searcher
: ReverseSearcher
<'a
>>,
3141 pat
.is_suffix_of(self)
3144 /// Returns the byte index of the first character of this string slice that
3145 /// matches the pattern.
3147 /// Returns [`None`] if the pattern doesn't match.
3149 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3150 /// function or closure that determines if a character matches.
3152 /// [`None`]: option/enum.Option.html#variant.None
3153 /// [`char`]: primitive.char.html
3154 /// [pattern]: str/pattern/index.html
3158 /// Simple patterns:
3161 /// let s = "Löwe 老虎 Léopard";
3163 /// assert_eq!(s.find('L'), Some(0));
3164 /// assert_eq!(s.find('é'), Some(14));
3165 /// assert_eq!(s.find("Léopard"), Some(13));
3168 /// More complex patterns using point-free style and closures:
3171 /// let s = "Löwe 老虎 Léopard";
3173 /// assert_eq!(s.find(char::is_whitespace), Some(5));
3174 /// assert_eq!(s.find(char::is_lowercase), Some(1));
3175 /// assert_eq!(s.find(|c: char| c.is_whitespace() || c.is_lowercase()), Some(1));
3176 /// assert_eq!(s.find(|c: char| (c < 'o') && (c > 'a')), Some(4));
3179 /// Not finding the pattern:
3182 /// let s = "Löwe 老虎 Léopard";
3183 /// let x: &[_] = &['1', '2'];
3185 /// assert_eq!(s.find(x), None);
3187 #[stable(feature = "rust1", since = "1.0.0")]
3189 pub fn find
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> Option
<usize> {
3190 pat
.into_searcher(self).next_match().map(|(i
, _
)| i
)
3193 /// Returns the byte index of the last character of this string slice that
3194 /// matches the pattern.
3196 /// Returns [`None`] if the pattern doesn't match.
3198 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3199 /// function or closure that determines if a character matches.
3201 /// [`None`]: option/enum.Option.html#variant.None
3202 /// [`char`]: primitive.char.html
3203 /// [pattern]: str/pattern/index.html
3207 /// Simple patterns:
3210 /// let s = "Löwe 老虎 Léopard";
3212 /// assert_eq!(s.rfind('L'), Some(13));
3213 /// assert_eq!(s.rfind('é'), Some(14));
3216 /// More complex patterns with closures:
3219 /// let s = "Löwe 老虎 Léopard";
3221 /// assert_eq!(s.rfind(char::is_whitespace), Some(12));
3222 /// assert_eq!(s.rfind(char::is_lowercase), Some(20));
3225 /// Not finding the pattern:
3228 /// let s = "Löwe 老虎 Léopard";
3229 /// let x: &[_] = &['1', '2'];
3231 /// assert_eq!(s.rfind(x), None);
3233 #[stable(feature = "rust1", since = "1.0.0")]
3235 pub fn rfind
<'a
, P
>(&'a
self, pat
: P
) -> Option
<usize>
3237 P
: Pattern
<'a
, Searcher
: ReverseSearcher
<'a
>>,
3239 pat
.into_searcher(self).next_match_back().map(|(i
, _
)| i
)
3242 /// An iterator over substrings of this string slice, separated by
3243 /// characters matched by a pattern.
3245 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3246 /// function or closure that determines if a character matches.
3248 /// [`char`]: primitive.char.html
3249 /// [pattern]: str/pattern/index.html
3251 /// # Iterator behavior
3253 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3254 /// allows a reverse search and forward/reverse search yields the same
3255 /// elements. This is true for, e.g., [`char`], but not for `&str`.
3257 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3259 /// If the pattern allows a reverse search but its results might differ
3260 /// from a forward search, the [`rsplit`] method can be used.
3262 /// [`rsplit`]: #method.rsplit
3266 /// Simple patterns:
3269 /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
3270 /// assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);
3272 /// let v: Vec<&str> = "".split('X').collect();
3273 /// assert_eq!(v, [""]);
3275 /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
3276 /// assert_eq!(v, ["lion", "", "tiger", "leopard"]);
3278 /// let v: Vec<&str> = "lion::tiger::leopard".split("::").collect();
3279 /// assert_eq!(v, ["lion", "tiger", "leopard"]);
3281 /// let v: Vec<&str> = "abc1def2ghi".split(char::is_numeric).collect();
3282 /// assert_eq!(v, ["abc", "def", "ghi"]);
3284 /// let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect();
3285 /// assert_eq!(v, ["lion", "tiger", "leopard"]);
3288 /// A more complex pattern, using a closure:
3291 /// let v: Vec<&str> = "abc1defXghi".split(|c| c == '1' || c == 'X').collect();
3292 /// assert_eq!(v, ["abc", "def", "ghi"]);
3295 /// If a string contains multiple contiguous separators, you will end up
3296 /// with empty strings in the output:
3299 /// let x = "||||a||b|c".to_string();
3300 /// let d: Vec<_> = x.split('|').collect();
3302 /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
3305 /// Contiguous separators are separated by the empty string.
3308 /// let x = "(///)".to_string();
3309 /// let d: Vec<_> = x.split('/').collect();
3311 /// assert_eq!(d, &["(", "", "", ")"]);
3314 /// Separators at the start or end of a string are neighbored
3315 /// by empty strings.
3318 /// let d: Vec<_> = "010".split("0").collect();
3319 /// assert_eq!(d, &["", "1", ""]);
3322 /// When the empty string is used as a separator, it separates
3323 /// every character in the string, along with the beginning
3324 /// and end of the string.
3327 /// let f: Vec<_> = "rust".split("").collect();
3328 /// assert_eq!(f, &["", "r", "u", "s", "t", ""]);
3331 /// Contiguous separators can lead to possibly surprising behavior
3332 /// when whitespace is used as the separator. This code is correct:
3335 /// let x = " a b c".to_string();
3336 /// let d: Vec<_> = x.split(' ').collect();
3338 /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);
3341 /// It does _not_ give you:
3344 /// assert_eq!(d, &["a", "b", "c"]);
3347 /// Use [`split_whitespace`] for this behavior.
3349 /// [`split_whitespace`]: #method.split_whitespace
3350 #[stable(feature = "rust1", since = "1.0.0")]
3352 pub fn split
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> Split
<'a
, P
> {
3353 Split(SplitInternal
{
3356 matcher
: pat
.into_searcher(self),
3357 allow_trailing_empty
: true,
3362 /// An iterator over substrings of this string slice, separated by
3363 /// characters matched by a pattern. Differs from the iterator produced by
3364 /// `split` in that `split_inclusive` leaves the matched part as the
3365 /// terminator of the substring.
3367 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3368 /// function or closure that determines if a character matches.
3370 /// [`char`]: primitive.char.html
3371 /// [pattern]: str/pattern/index.html
3376 /// #![feature(split_inclusive)]
3377 /// let v: Vec<&str> = "Mary had a little lamb\nlittle lamb\nlittle lamb."
3378 /// .split_inclusive('\n').collect();
3379 /// assert_eq!(v, ["Mary had a little lamb\n", "little lamb\n", "little lamb."]);
3382 /// If the last element of the string is matched,
3383 /// that element will be considered the terminator of the preceding substring.
3384 /// That substring will be the last item returned by the iterator.
3387 /// #![feature(split_inclusive)]
3388 /// let v: Vec<&str> = "Mary had a little lamb\nlittle lamb\nlittle lamb.\n"
3389 /// .split_inclusive('\n').collect();
3390 /// assert_eq!(v, ["Mary had a little lamb\n", "little lamb\n", "little lamb.\n"]);
3392 #[unstable(feature = "split_inclusive", issue = "72360")]
3394 pub fn split_inclusive
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> SplitInclusive
<'a
, P
> {
3395 SplitInclusive(SplitInternal
{
3398 matcher
: pat
.into_searcher(self),
3399 allow_trailing_empty
: false,
3404 /// An iterator over substrings of the given string slice, separated by
3405 /// characters matched by a pattern and yielded in reverse order.
3407 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3408 /// function or closure that determines if a character matches.
3410 /// [`char`]: primitive.char.html
3411 /// [pattern]: str/pattern/index.html
3413 /// # Iterator behavior
3415 /// The returned iterator requires that the pattern supports a reverse
3416 /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
3417 /// search yields the same elements.
3419 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3421 /// For iterating from the front, the [`split`] method can be used.
3423 /// [`split`]: #method.split
3427 /// Simple patterns:
3430 /// let v: Vec<&str> = "Mary had a little lamb".rsplit(' ').collect();
3431 /// assert_eq!(v, ["lamb", "little", "a", "had", "Mary"]);
3433 /// let v: Vec<&str> = "".rsplit('X').collect();
3434 /// assert_eq!(v, [""]);
3436 /// let v: Vec<&str> = "lionXXtigerXleopard".rsplit('X').collect();
3437 /// assert_eq!(v, ["leopard", "tiger", "", "lion"]);
3439 /// let v: Vec<&str> = "lion::tiger::leopard".rsplit("::").collect();
3440 /// assert_eq!(v, ["leopard", "tiger", "lion"]);
3443 /// A more complex pattern, using a closure:
3446 /// let v: Vec<&str> = "abc1defXghi".rsplit(|c| c == '1' || c == 'X').collect();
3447 /// assert_eq!(v, ["ghi", "def", "abc"]);
3449 #[stable(feature = "rust1", since = "1.0.0")]
3451 pub fn rsplit
<'a
, P
>(&'a
self, pat
: P
) -> RSplit
<'a
, P
>
3453 P
: Pattern
<'a
, Searcher
: ReverseSearcher
<'a
>>,
3455 RSplit(self.split(pat
).0)
3458 /// An iterator over substrings of the given string slice, separated by
3459 /// characters matched by a pattern.
3461 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3462 /// function or closure that determines if a character matches.
3464 /// [`char`]: primitive.char.html
3465 /// [pattern]: str/pattern/index.html
3467 /// Equivalent to [`split`], except that the trailing substring
3468 /// is skipped if empty.
3470 /// [`split`]: #method.split
3472 /// This method can be used for string data that is _terminated_,
3473 /// rather than _separated_ by a pattern.
3475 /// # Iterator behavior
3477 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3478 /// allows a reverse search and forward/reverse search yields the same
3479 /// elements. This is true for, e.g., [`char`], but not for `&str`.
3481 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3483 /// If the pattern allows a reverse search but its results might differ
3484 /// from a forward search, the [`rsplit_terminator`] method can be used.
3486 /// [`rsplit_terminator`]: #method.rsplit_terminator
3493 /// let v: Vec<&str> = "A.B.".split_terminator('.').collect();
3494 /// assert_eq!(v, ["A", "B"]);
3496 /// let v: Vec<&str> = "A..B..".split_terminator(".").collect();
3497 /// assert_eq!(v, ["A", "", "B", ""]);
3499 #[stable(feature = "rust1", since = "1.0.0")]
3501 pub fn split_terminator
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> SplitTerminator
<'a
, P
> {
3502 SplitTerminator(SplitInternal { allow_trailing_empty: false, ..self.split(pat).0 }
)
3505 /// An iterator over substrings of `self`, separated by characters
3506 /// matched by a pattern and yielded in reverse order.
3508 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3509 /// function or closure that determines if a character matches.
3511 /// [`char`]: primitive.char.html
3512 /// [pattern]: str/pattern/index.html
3514 /// Equivalent to [`split`], except that the trailing substring is
3515 /// skipped if empty.
3517 /// [`split`]: #method.split
3519 /// This method can be used for string data that is _terminated_,
3520 /// rather than _separated_ by a pattern.
3522 /// # Iterator behavior
3524 /// The returned iterator requires that the pattern supports a
3525 /// reverse search, and it will be double ended if a forward/reverse
3526 /// search yields the same elements.
3528 /// For iterating from the front, the [`split_terminator`] method can be
3531 /// [`split_terminator`]: #method.split_terminator
3536 /// let v: Vec<&str> = "A.B.".rsplit_terminator('.').collect();
3537 /// assert_eq!(v, ["B", "A"]);
3539 /// let v: Vec<&str> = "A..B..".rsplit_terminator(".").collect();
3540 /// assert_eq!(v, ["", "B", "", "A"]);
3542 #[stable(feature = "rust1", since = "1.0.0")]
3544 pub fn rsplit_terminator
<'a
, P
>(&'a
self, pat
: P
) -> RSplitTerminator
<'a
, P
>
3546 P
: Pattern
<'a
, Searcher
: ReverseSearcher
<'a
>>,
3548 RSplitTerminator(self.split_terminator(pat
).0)
3551 /// An iterator over substrings of the given string slice, separated by a
3552 /// pattern, restricted to returning at most `n` items.
3554 /// If `n` substrings are returned, the last substring (the `n`th substring)
3555 /// will contain the remainder of the string.
3557 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3558 /// function or closure that determines if a character matches.
3560 /// [`char`]: primitive.char.html
3561 /// [pattern]: str/pattern/index.html
3563 /// # Iterator behavior
3565 /// The returned iterator will not be double ended, because it is
3566 /// not efficient to support.
3568 /// If the pattern allows a reverse search, the [`rsplitn`] method can be
3571 /// [`rsplitn`]: #method.rsplitn
3575 /// Simple patterns:
3578 /// let v: Vec<&str> = "Mary had a little lambda".splitn(3, ' ').collect();
3579 /// assert_eq!(v, ["Mary", "had", "a little lambda"]);
3581 /// let v: Vec<&str> = "lionXXtigerXleopard".splitn(3, "X").collect();
3582 /// assert_eq!(v, ["lion", "", "tigerXleopard"]);
3584 /// let v: Vec<&str> = "abcXdef".splitn(1, 'X').collect();
3585 /// assert_eq!(v, ["abcXdef"]);
3587 /// let v: Vec<&str> = "".splitn(1, 'X').collect();
3588 /// assert_eq!(v, [""]);
3591 /// A more complex pattern, using a closure:
3594 /// let v: Vec<&str> = "abc1defXghi".splitn(2, |c| c == '1' || c == 'X').collect();
3595 /// assert_eq!(v, ["abc", "defXghi"]);
3597 #[stable(feature = "rust1", since = "1.0.0")]
3599 pub fn splitn
<'a
, P
: Pattern
<'a
>>(&'a
self, n
: usize, pat
: P
) -> SplitN
<'a
, P
> {
3600 SplitN(SplitNInternal { iter: self.split(pat).0, count: n }
)
3603 /// An iterator over substrings of this string slice, separated by a
3604 /// pattern, starting from the end of the string, restricted to returning
3605 /// at most `n` items.
3607 /// If `n` substrings are returned, the last substring (the `n`th substring)
3608 /// will contain the remainder of the string.
3610 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3611 /// function or closure that determines if a character matches.
3613 /// [`char`]: primitive.char.html
3614 /// [pattern]: str/pattern/index.html
3616 /// # Iterator behavior
3618 /// The returned iterator will not be double ended, because it is not
3619 /// efficient to support.
3621 /// For splitting from the front, the [`splitn`] method can be used.
3623 /// [`splitn`]: #method.splitn
3627 /// Simple patterns:
3630 /// let v: Vec<&str> = "Mary had a little lamb".rsplitn(3, ' ').collect();
3631 /// assert_eq!(v, ["lamb", "little", "Mary had a"]);
3633 /// let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(3, 'X').collect();
3634 /// assert_eq!(v, ["leopard", "tiger", "lionX"]);
3636 /// let v: Vec<&str> = "lion::tiger::leopard".rsplitn(2, "::").collect();
3637 /// assert_eq!(v, ["leopard", "lion::tiger"]);
3640 /// A more complex pattern, using a closure:
3643 /// let v: Vec<&str> = "abc1defXghi".rsplitn(2, |c| c == '1' || c == 'X').collect();
3644 /// assert_eq!(v, ["ghi", "abc1def"]);
3646 #[stable(feature = "rust1", since = "1.0.0")]
3648 pub fn rsplitn
<'a
, P
>(&'a
self, n
: usize, pat
: P
) -> RSplitN
<'a
, P
>
3650 P
: Pattern
<'a
, Searcher
: ReverseSearcher
<'a
>>,
3652 RSplitN(self.splitn(n
, pat
).0)
3655 /// An iterator over the disjoint matches of a pattern within the given string
3658 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3659 /// function or closure that determines if a character matches.
3661 /// [`char`]: primitive.char.html
3662 /// [pattern]: str/pattern/index.html
3664 /// # Iterator behavior
3666 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3667 /// allows a reverse search and forward/reverse search yields the same
3668 /// elements. This is true for, e.g., [`char`], but not for `&str`.
3670 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3672 /// If the pattern allows a reverse search but its results might differ
3673 /// from a forward search, the [`rmatches`] method can be used.
3675 /// [`rmatches`]: #method.rmatches
3682 /// let v: Vec<&str> = "abcXXXabcYYYabc".matches("abc").collect();
3683 /// assert_eq!(v, ["abc", "abc", "abc"]);
3685 /// let v: Vec<&str> = "1abc2abc3".matches(char::is_numeric).collect();
3686 /// assert_eq!(v, ["1", "2", "3"]);
3688 #[stable(feature = "str_matches", since = "1.2.0")]
3690 pub fn matches
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> Matches
<'a
, P
> {
3691 Matches(MatchesInternal(pat
.into_searcher(self)))
3694 /// An iterator over the disjoint matches of a pattern within this string slice,
3695 /// yielded in reverse order.
3697 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3698 /// function or closure that determines if a character matches.
3700 /// [`char`]: primitive.char.html
3701 /// [pattern]: str/pattern/index.html
3703 /// # Iterator behavior
3705 /// The returned iterator requires that the pattern supports a reverse
3706 /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
3707 /// search yields the same elements.
3709 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3711 /// For iterating from the front, the [`matches`] method can be used.
3713 /// [`matches`]: #method.matches
3720 /// let v: Vec<&str> = "abcXXXabcYYYabc".rmatches("abc").collect();
3721 /// assert_eq!(v, ["abc", "abc", "abc"]);
3723 /// let v: Vec<&str> = "1abc2abc3".rmatches(char::is_numeric).collect();
3724 /// assert_eq!(v, ["3", "2", "1"]);
3726 #[stable(feature = "str_matches", since = "1.2.0")]
3728 pub fn rmatches
<'a
, P
>(&'a
self, pat
: P
) -> RMatches
<'a
, P
>
3730 P
: Pattern
<'a
, Searcher
: ReverseSearcher
<'a
>>,
3732 RMatches(self.matches(pat
).0)
3735 /// An iterator over the disjoint matches of a pattern within this string
3736 /// slice as well as the index that the match starts at.
3738 /// For matches of `pat` within `self` that overlap, only the indices
3739 /// corresponding to the first match are returned.
3741 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3742 /// function or closure that determines if a character matches.
3744 /// [`char`]: primitive.char.html
3745 /// [pattern]: str/pattern/index.html
3747 /// # Iterator behavior
3749 /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern
3750 /// allows a reverse search and forward/reverse search yields the same
3751 /// elements. This is true for, e.g., [`char`], but not for `&str`.
3753 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3755 /// If the pattern allows a reverse search but its results might differ
3756 /// from a forward search, the [`rmatch_indices`] method can be used.
3758 /// [`rmatch_indices`]: #method.rmatch_indices
3765 /// let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
3766 /// assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
3768 /// let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
3769 /// assert_eq!(v, [(1, "abc"), (4, "abc")]);
3771 /// let v: Vec<_> = "ababa".match_indices("aba").collect();
3772 /// assert_eq!(v, [(0, "aba")]); // only the first `aba`
3774 #[stable(feature = "str_match_indices", since = "1.5.0")]
3776 pub fn match_indices
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> MatchIndices
<'a
, P
> {
3777 MatchIndices(MatchIndicesInternal(pat
.into_searcher(self)))
3780 /// An iterator over the disjoint matches of a pattern within `self`,
3781 /// yielded in reverse order along with the index of the match.
3783 /// For matches of `pat` within `self` that overlap, only the indices
3784 /// corresponding to the last match are returned.
3786 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
3787 /// function or closure that determines if a character matches.
3789 /// [`char`]: primitive.char.html
3790 /// [pattern]: str/pattern/index.html
3792 /// # Iterator behavior
3794 /// The returned iterator requires that the pattern supports a reverse
3795 /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse
3796 /// search yields the same elements.
3798 /// [`DoubleEndedIterator`]: iter/trait.DoubleEndedIterator.html
3800 /// For iterating from the front, the [`match_indices`] method can be used.
3802 /// [`match_indices`]: #method.match_indices
3809 /// let v: Vec<_> = "abcXXXabcYYYabc".rmatch_indices("abc").collect();
3810 /// assert_eq!(v, [(12, "abc"), (6, "abc"), (0, "abc")]);
3812 /// let v: Vec<_> = "1abcabc2".rmatch_indices("abc").collect();
3813 /// assert_eq!(v, [(4, "abc"), (1, "abc")]);
3815 /// let v: Vec<_> = "ababa".rmatch_indices("aba").collect();
3816 /// assert_eq!(v, [(2, "aba")]); // only the last `aba`
3818 #[stable(feature = "str_match_indices", since = "1.5.0")]
3820 pub fn rmatch_indices
<'a
, P
>(&'a
self, pat
: P
) -> RMatchIndices
<'a
, P
>
3822 P
: Pattern
<'a
, Searcher
: ReverseSearcher
<'a
>>,
3824 RMatchIndices(self.match_indices(pat
).0)
3827 /// Returns a string slice with leading and trailing whitespace removed.
3829 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3830 /// Core Property `White_Space`.
3837 /// let s = " Hello\tworld\t";
3839 /// assert_eq!("Hello\tworld", s.trim());
3841 #[must_use = "this returns the trimmed string as a slice, \
3842 without modifying the original"]
3843 #[stable(feature = "rust1", since = "1.0.0")]
3844 pub fn trim(&self) -> &str {
3845 self.trim_matches(|c
: char| c
.is_whitespace())
3848 /// Returns a string slice with leading whitespace removed.
3850 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3851 /// Core Property `White_Space`.
3853 /// # Text directionality
3855 /// A string is a sequence of bytes. `start` in this context means the first
3856 /// position of that byte string; for a left-to-right language like English or
3857 /// Russian, this will be left side, and for right-to-left languages like
3858 /// Arabic or Hebrew, this will be the right side.
3865 /// let s = " Hello\tworld\t";
3866 /// assert_eq!("Hello\tworld\t", s.trim_start());
3872 /// let s = " English ";
3873 /// assert!(Some('E') == s.trim_start().chars().next());
3875 /// let s = " עברית ";
3876 /// assert!(Some('ע') == s.trim_start().chars().next());
3878 #[must_use = "this returns the trimmed string as a new slice, \
3879 without modifying the original"]
3880 #[stable(feature = "trim_direction", since = "1.30.0")]
3881 pub fn trim_start(&self) -> &str {
3882 self.trim_start_matches(|c
: char| c
.is_whitespace())
3885 /// Returns a string slice with trailing whitespace removed.
3887 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3888 /// Core Property `White_Space`.
3890 /// # Text directionality
3892 /// A string is a sequence of bytes. `end` in this context means the last
3893 /// position of that byte string; for a left-to-right language like English or
3894 /// Russian, this will be right side, and for right-to-left languages like
3895 /// Arabic or Hebrew, this will be the left side.
3902 /// let s = " Hello\tworld\t";
3903 /// assert_eq!(" Hello\tworld", s.trim_end());
3909 /// let s = " English ";
3910 /// assert!(Some('h') == s.trim_end().chars().rev().next());
3912 /// let s = " עברית ";
3913 /// assert!(Some('ת') == s.trim_end().chars().rev().next());
3915 #[must_use = "this returns the trimmed string as a new slice, \
3916 without modifying the original"]
3917 #[stable(feature = "trim_direction", since = "1.30.0")]
3918 pub fn trim_end(&self) -> &str {
3919 self.trim_end_matches(|c
: char| c
.is_whitespace())
3922 /// Returns a string slice with leading whitespace removed.
3924 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3925 /// Core Property `White_Space`.
3927 /// # Text directionality
3929 /// A string is a sequence of bytes. 'Left' in this context means the first
3930 /// position of that byte string; for a language like Arabic or Hebrew
3931 /// which are 'right to left' rather than 'left to right', this will be
3932 /// the _right_ side, not the left.
3939 /// let s = " Hello\tworld\t";
3941 /// assert_eq!("Hello\tworld\t", s.trim_left());
3947 /// let s = " English";
3948 /// assert!(Some('E') == s.trim_left().chars().next());
3950 /// let s = " עברית";
3951 /// assert!(Some('ע') == s.trim_left().chars().next());
3953 #[stable(feature = "rust1", since = "1.0.0")]
3956 reason
= "superseded by `trim_start`",
3957 suggestion
= "trim_start"
3959 pub fn trim_left(&self) -> &str {
3963 /// Returns a string slice with trailing whitespace removed.
3965 /// 'Whitespace' is defined according to the terms of the Unicode Derived
3966 /// Core Property `White_Space`.
3968 /// # Text directionality
3970 /// A string is a sequence of bytes. 'Right' in this context means the last
3971 /// position of that byte string; for a language like Arabic or Hebrew
3972 /// which are 'right to left' rather than 'left to right', this will be
3973 /// the _left_ side, not the right.
3980 /// let s = " Hello\tworld\t";
3982 /// assert_eq!(" Hello\tworld", s.trim_right());
3988 /// let s = "English ";
3989 /// assert!(Some('h') == s.trim_right().chars().rev().next());
3991 /// let s = "עברית ";
3992 /// assert!(Some('ת') == s.trim_right().chars().rev().next());
3994 #[stable(feature = "rust1", since = "1.0.0")]
3997 reason
= "superseded by `trim_end`",
3998 suggestion
= "trim_end"
4000 pub fn trim_right(&self) -> &str {
4004 /// Returns a string slice with all prefixes and suffixes that match a
4005 /// pattern repeatedly removed.
4007 /// The [pattern] can be a [`char`], a slice of [`char`]s, or a function
4008 /// or closure that determines if a character matches.
4010 /// [`char`]: primitive.char.html
4011 /// [pattern]: str/pattern/index.html
4015 /// Simple patterns:
4018 /// assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar");
4019 /// assert_eq!("123foo1bar123".trim_matches(char::is_numeric), "foo1bar");
4021 /// let x: &[_] = &['1', '2'];
4022 /// assert_eq!("12foo1bar12".trim_matches(x), "foo1bar");
4025 /// A more complex pattern, using a closure:
4028 /// assert_eq!("1foo1barXX".trim_matches(|c| c == '1' || c == 'X'), "foo1bar");
4030 #[must_use = "this returns the trimmed string as a new slice, \
4031 without modifying the original"]
4032 #[stable(feature = "rust1", since = "1.0.0")]
4033 pub fn trim_matches
<'a
, P
>(&'a
self, pat
: P
) -> &'a
str
4035 P
: Pattern
<'a
, Searcher
: DoubleEndedSearcher
<'a
>>,
4039 let mut matcher
= pat
.into_searcher(self);
4040 if let Some((a
, b
)) = matcher
.next_reject() {
4042 j
= b
; // Remember earliest known match, correct it below if
4043 // last match is different
4045 if let Some((_
, b
)) = matcher
.next_reject_back() {
4048 // SAFETY: `Searcher` is known to return valid indices.
4049 unsafe { self.get_unchecked(i..j) }
4052 /// Returns a string slice with all prefixes that match a pattern
4053 /// repeatedly removed.
4055 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
4056 /// function or closure that determines if a character matches.
4058 /// [`char`]: primitive.char.html
4059 /// [pattern]: str/pattern/index.html
4061 /// # Text directionality
4063 /// A string is a sequence of bytes. `start` in this context means the first
4064 /// position of that byte string; for a left-to-right language like English or
4065 /// Russian, this will be left side, and for right-to-left languages like
4066 /// Arabic or Hebrew, this will be the right side.
4073 /// assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11");
4074 /// assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric), "foo1bar123");
4076 /// let x: &[_] = &['1', '2'];
4077 /// assert_eq!("12foo1bar12".trim_start_matches(x), "foo1bar12");
4079 #[must_use = "this returns the trimmed string as a new slice, \
4080 without modifying the original"]
4081 #[stable(feature = "trim_direction", since = "1.30.0")]
4082 pub fn trim_start_matches
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> &'a
str {
4083 let mut i
= self.len();
4084 let mut matcher
= pat
.into_searcher(self);
4085 if let Some((a
, _
)) = matcher
.next_reject() {
4088 // SAFETY: `Searcher` is known to return valid indices.
4089 unsafe { self.get_unchecked(i..self.len()) }
4092 /// Returns a string slice with the prefix removed.
4094 /// If the string starts with the pattern `prefix`, `Some` is returned with the substring where
4095 /// the prefix is removed. Unlike `trim_start_matches`, this method removes the prefix exactly
4098 /// If the string does not start with `prefix`, `None` is returned.
4100 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
4101 /// function or closure that determines if a character matches.
4103 /// [`char`]: primitive.char.html
4104 /// [pattern]: str/pattern/index.html
4109 /// assert_eq!("foo:bar".strip_prefix("foo:"), Some("bar"));
4110 /// assert_eq!("foo:bar".strip_prefix("bar"), None);
4111 /// assert_eq!("foofoo".strip_prefix("foo"), Some("foo"));
4113 #[must_use = "this returns the remaining substring as a new slice, \
4114 without modifying the original"]
4115 #[stable(feature = "str_strip", since = "1.45.0")]
4116 pub fn strip_prefix
<'a
, P
: Pattern
<'a
>>(&'a
self, prefix
: P
) -> Option
<&'a
str> {
4117 prefix
.strip_prefix_of(self)
4120 /// Returns a string slice with the suffix removed.
4122 /// If the string ends with the pattern `suffix`, `Some` is returned with the substring where
4123 /// the suffix is removed. Unlike `trim_end_matches`, this method removes the suffix exactly
4126 /// If the string does not end with `suffix`, `None` is returned.
4128 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
4129 /// function or closure that determines if a character matches.
4131 /// [`char`]: primitive.char.html
4132 /// [pattern]: str/pattern/index.html
4137 /// assert_eq!("bar:foo".strip_suffix(":foo"), Some("bar"));
4138 /// assert_eq!("bar:foo".strip_suffix("bar"), None);
4139 /// assert_eq!("foofoo".strip_suffix("foo"), Some("foo"));
4141 #[must_use = "this returns the remaining substring as a new slice, \
4142 without modifying the original"]
4143 #[stable(feature = "str_strip", since = "1.45.0")]
4144 pub fn strip_suffix
<'a
, P
>(&'a
self, suffix
: P
) -> Option
<&'a
str>
4147 <P
as Pattern
<'a
>>::Searcher
: ReverseSearcher
<'a
>,
4149 suffix
.strip_suffix_of(self)
4152 /// Returns a string slice with all suffixes that match a pattern
4153 /// repeatedly removed.
4155 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
4156 /// function or closure that determines if a character matches.
4158 /// [`char`]: primitive.char.html
4159 /// [pattern]: str/pattern/index.html
4161 /// # Text directionality
4163 /// A string is a sequence of bytes. `end` in this context means the last
4164 /// position of that byte string; for a left-to-right language like English or
4165 /// Russian, this will be right side, and for right-to-left languages like
4166 /// Arabic or Hebrew, this will be the left side.
4170 /// Simple patterns:
4173 /// assert_eq!("11foo1bar11".trim_end_matches('1'), "11foo1bar");
4174 /// assert_eq!("123foo1bar123".trim_end_matches(char::is_numeric), "123foo1bar");
4176 /// let x: &[_] = &['1', '2'];
4177 /// assert_eq!("12foo1bar12".trim_end_matches(x), "12foo1bar");
4180 /// A more complex pattern, using a closure:
4183 /// assert_eq!("1fooX".trim_end_matches(|c| c == '1' || c == 'X'), "1foo");
4185 #[must_use = "this returns the trimmed string as a new slice, \
4186 without modifying the original"]
4187 #[stable(feature = "trim_direction", since = "1.30.0")]
4188 pub fn trim_end_matches
<'a
, P
>(&'a
self, pat
: P
) -> &'a
str
4190 P
: Pattern
<'a
, Searcher
: ReverseSearcher
<'a
>>,
4193 let mut matcher
= pat
.into_searcher(self);
4194 if let Some((_
, b
)) = matcher
.next_reject_back() {
4197 // SAFETY: `Searcher` is known to return valid indices.
4198 unsafe { self.get_unchecked(0..j) }
4201 /// Returns a string slice with all prefixes that match a pattern
4202 /// repeatedly removed.
4204 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
4205 /// function or closure that determines if a character matches.
4207 /// [`char`]: primitive.char.html
4208 /// [pattern]: str/pattern/index.html
4210 /// # Text directionality
4212 /// A string is a sequence of bytes. 'Left' in this context means the first
4213 /// position of that byte string; for a language like Arabic or Hebrew
4214 /// which are 'right to left' rather than 'left to right', this will be
4215 /// the _right_ side, not the left.
4222 /// assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11");
4223 /// assert_eq!("123foo1bar123".trim_left_matches(char::is_numeric), "foo1bar123");
4225 /// let x: &[_] = &['1', '2'];
4226 /// assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12");
4228 #[stable(feature = "rust1", since = "1.0.0")]
4231 reason
= "superseded by `trim_start_matches`",
4232 suggestion
= "trim_start_matches"
4234 pub fn trim_left_matches
<'a
, P
: Pattern
<'a
>>(&'a
self, pat
: P
) -> &'a
str {
4235 self.trim_start_matches(pat
)
4238 /// Returns a string slice with all suffixes that match a pattern
4239 /// repeatedly removed.
4241 /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a
4242 /// function or closure that determines if a character matches.
4244 /// [`char`]: primitive.char.html
4245 /// [pattern]: str/pattern/index.html
4247 /// # Text directionality
4249 /// A string is a sequence of bytes. 'Right' in this context means the last
4250 /// position of that byte string; for a language like Arabic or Hebrew
4251 /// which are 'right to left' rather than 'left to right', this will be
4252 /// the _left_ side, not the right.
4256 /// Simple patterns:
4259 /// assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar");
4260 /// assert_eq!("123foo1bar123".trim_right_matches(char::is_numeric), "123foo1bar");
4262 /// let x: &[_] = &['1', '2'];
4263 /// assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar");
4266 /// A more complex pattern, using a closure:
4269 /// assert_eq!("1fooX".trim_right_matches(|c| c == '1' || c == 'X'), "1foo");
4271 #[stable(feature = "rust1", since = "1.0.0")]
4274 reason
= "superseded by `trim_end_matches`",
4275 suggestion
= "trim_end_matches"
4277 pub fn trim_right_matches
<'a
, P
>(&'a
self, pat
: P
) -> &'a
str
4279 P
: Pattern
<'a
, Searcher
: ReverseSearcher
<'a
>>,
4281 self.trim_end_matches(pat
)
4284 /// Parses this string slice into another type.
4286 /// Because `parse` is so general, it can cause problems with type
4287 /// inference. As such, `parse` is one of the few times you'll see
4288 /// the syntax affectionately known as the 'turbofish': `::<>`. This
4289 /// helps the inference algorithm understand specifically which type
4290 /// you're trying to parse into.
4292 /// `parse` can parse any type that implements the [`FromStr`] trait.
4294 /// [`FromStr`]: str/trait.FromStr.html
4298 /// Will return [`Err`] if it's not possible to parse this string slice into
4299 /// the desired type.
4301 /// [`Err`]: str/trait.FromStr.html#associatedtype.Err
4308 /// let four: u32 = "4".parse().unwrap();
4310 /// assert_eq!(4, four);
4313 /// Using the 'turbofish' instead of annotating `four`:
4316 /// let four = "4".parse::<u32>();
4318 /// assert_eq!(Ok(4), four);
4321 /// Failing to parse:
4324 /// let nope = "j".parse::<u32>();
4326 /// assert!(nope.is_err());
4329 #[stable(feature = "rust1", since = "1.0.0")]
4330 pub fn parse
<F
: FromStr
>(&self) -> Result
<F
, F
::Err
> {
4331 FromStr
::from_str(self)
4334 /// Checks if all characters in this string are within the ASCII range.
4339 /// let ascii = "hello!\n";
4340 /// let non_ascii = "Grüße, Jürgen ❤";
4342 /// assert!(ascii.is_ascii());
4343 /// assert!(!non_ascii.is_ascii());
4345 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4347 pub fn is_ascii(&self) -> bool
{
4348 // We can treat each byte as character here: all multibyte characters
4349 // start with a byte that is not in the ascii range, so we will stop
4351 self.as_bytes().is_ascii()
4354 /// Checks that two strings are an ASCII case-insensitive match.
4356 /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`,
4357 /// but without allocating and copying temporaries.
4362 /// assert!("Ferris".eq_ignore_ascii_case("FERRIS"));
4363 /// assert!("Ferrös".eq_ignore_ascii_case("FERRöS"));
4364 /// assert!(!"Ferrös".eq_ignore_ascii_case("FERRÖS"));
4366 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4368 pub fn eq_ignore_ascii_case(&self, other
: &str) -> bool
{
4369 self.as_bytes().eq_ignore_ascii_case(other
.as_bytes())
4372 /// Converts this string to its ASCII upper case equivalent in-place.
4374 /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z',
4375 /// but non-ASCII letters are unchanged.
4377 /// To return a new uppercased value without modifying the existing one, use
4378 /// [`to_ascii_uppercase`].
4380 /// [`to_ascii_uppercase`]: #method.to_ascii_uppercase
4385 /// let mut s = String::from("Grüße, Jürgen ❤");
4387 /// s.make_ascii_uppercase();
4389 /// assert_eq!("GRüßE, JüRGEN ❤", s);
4391 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4392 pub fn make_ascii_uppercase(&mut self) {
4393 // SAFETY: safe because we transmute two types with the same layout.
4394 let me
= unsafe { self.as_bytes_mut() }
;
4395 me
.make_ascii_uppercase()
4398 /// Converts this string to its ASCII lower case equivalent in-place.
4400 /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z',
4401 /// but non-ASCII letters are unchanged.
4403 /// To return a new lowercased value without modifying the existing one, use
4404 /// [`to_ascii_lowercase`].
4406 /// [`to_ascii_lowercase`]: #method.to_ascii_lowercase
4411 /// let mut s = String::from("GRÜßE, JÜRGEN ❤");
4413 /// s.make_ascii_lowercase();
4415 /// assert_eq!("grÜße, jÜrgen ❤", s);
4417 #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")]
4418 pub fn make_ascii_lowercase(&mut self) {
4419 // SAFETY: safe because we transmute two types with the same layout.
4420 let me
= unsafe { self.as_bytes_mut() }
;
4421 me
.make_ascii_lowercase()
4424 /// Return an iterator that escapes each char in `self` with [`char::escape_debug`].
4426 /// Note: only extended grapheme codepoints that begin the string will be
4429 /// [`char::escape_debug`]: ../std/primitive.char.html#method.escape_debug
4436 /// for c in "❤\n!".escape_debug() {
4437 /// print!("{}", c);
4442 /// Using `println!` directly:
4445 /// println!("{}", "❤\n!".escape_debug());
4449 /// Both are equivalent to:
4452 /// println!("❤\\n!");
4455 /// Using `to_string`:
4458 /// assert_eq!("❤\n!".escape_debug().to_string(), "❤\\n!");
4460 #[stable(feature = "str_escape", since = "1.34.0")]
4461 pub fn escape_debug(&self) -> EscapeDebug
<'_
> {
4462 let mut chars
= self.chars();
4466 .map(|first
| first
.escape_debug_ext(true))
4469 .chain(chars
.flat_map(CharEscapeDebugContinue
)),
4473 /// Return an iterator that escapes each char in `self` with [`char::escape_default`].
4475 /// [`char::escape_default`]: ../std/primitive.char.html#method.escape_default
4482 /// for c in "❤\n!".escape_default() {
4483 /// print!("{}", c);
4488 /// Using `println!` directly:
4491 /// println!("{}", "❤\n!".escape_default());
4495 /// Both are equivalent to:
4498 /// println!("\\u{{2764}}\\n!");
4501 /// Using `to_string`:
4504 /// assert_eq!("❤\n!".escape_default().to_string(), "\\u{2764}\\n!");
4506 #[stable(feature = "str_escape", since = "1.34.0")]
4507 pub fn escape_default(&self) -> EscapeDefault
<'_
> {
4508 EscapeDefault { inner: self.chars().flat_map(CharEscapeDefault) }
4511 /// Return an iterator that escapes each char in `self` with [`char::escape_unicode`].
4513 /// [`char::escape_unicode`]: ../std/primitive.char.html#method.escape_unicode
4520 /// for c in "❤\n!".escape_unicode() {
4521 /// print!("{}", c);
4526 /// Using `println!` directly:
4529 /// println!("{}", "❤\n!".escape_unicode());
4533 /// Both are equivalent to:
4536 /// println!("\\u{{2764}}\\u{{a}}\\u{{21}}");
4539 /// Using `to_string`:
4542 /// assert_eq!("❤\n!".escape_unicode().to_string(), "\\u{2764}\\u{a}\\u{21}");
4544 #[stable(feature = "str_escape", since = "1.34.0")]
4545 pub fn escape_unicode(&self) -> EscapeUnicode
<'_
> {
4546 EscapeUnicode { inner: self.chars().flat_map(CharEscapeUnicode) }
4552 struct CharEscapeDebugContinue
impl Fn
= |c
: char| -> char::EscapeDebug
{
4553 c
.escape_debug_ext(false)
4557 struct CharEscapeUnicode
impl Fn
= |c
: char| -> char::EscapeUnicode
{
4561 struct CharEscapeDefault
impl Fn
= |c
: char| -> char::EscapeDefault
{
4566 #[stable(feature = "rust1", since = "1.0.0")]
4567 impl AsRef
<[u8]> for str {
4569 fn as_ref(&self) -> &[u8] {
4574 #[stable(feature = "rust1", since = "1.0.0")]
4575 impl Default
for &str {
4576 /// Creates an empty str
4577 fn default() -> Self {
4582 #[stable(feature = "default_mut_str", since = "1.28.0")]
4583 impl Default
for &mut str {
4584 /// Creates an empty mutable str
4585 fn default() -> Self {
4586 // SAFETY: The empty string is valid UTF-8.
4587 unsafe { from_utf8_unchecked_mut(&mut []) }
4591 /// An iterator over the non-whitespace substrings of a string,
4592 /// separated by any amount of whitespace.
4594 /// This struct is created by the [`split_whitespace`] method on [`str`].
4595 /// See its documentation for more.
4597 /// [`split_whitespace`]: ../../std/primitive.str.html#method.split_whitespace
4598 /// [`str`]: ../../std/primitive.str.html
4599 #[stable(feature = "split_whitespace", since = "1.1.0")]
4600 #[derive(Clone, Debug)]
4601 pub struct SplitWhitespace
<'a
> {
4602 inner
: Filter
<Split
<'a
, IsWhitespace
>, IsNotEmpty
>,
4605 /// An iterator over the non-ASCII-whitespace substrings of a string,
4606 /// separated by any amount of ASCII whitespace.
4608 /// This struct is created by the [`split_ascii_whitespace`] method on [`str`].
4609 /// See its documentation for more.
4611 /// [`split_ascii_whitespace`]: ../../std/primitive.str.html#method.split_ascii_whitespace
4612 /// [`str`]: ../../std/primitive.str.html
4613 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4614 #[derive(Clone, Debug)]
4615 pub struct SplitAsciiWhitespace
<'a
> {
4616 inner
: Map
<Filter
<SliceSplit
<'a
, u8, IsAsciiWhitespace
>, BytesIsNotEmpty
>, UnsafeBytesToStr
>,
4619 /// An iterator over the substrings of a string,
4620 /// terminated by a substring matching to a predicate function
4621 /// Unlike `Split`, it contains the matched part as a terminator
4622 /// of the subslice.
4624 /// This struct is created by the [`split_inclusive`] method on [`str`].
4625 /// See its documentation for more.
4627 /// [`split_inclusive`]: ../../std/primitive.str.html#method.split_inclusive
4628 /// [`str`]: ../../std/primitive.str.html
4629 #[unstable(feature = "split_inclusive", issue = "72360")]
4630 pub struct SplitInclusive
<'a
, P
: Pattern
<'a
>>(SplitInternal
<'a
, P
>);
4634 struct IsWhitespace
impl Fn
= |c
: char| -> bool
{
4639 struct IsAsciiWhitespace
impl Fn
= |byte
: &u8| -> bool
{
4640 byte
.is_ascii_whitespace()
4644 struct IsNotEmpty
impl<'a
, 'b
> Fn
= |s
: &'a
&'b
str| -> bool
{
4649 struct BytesIsNotEmpty
impl<'a
, 'b
> Fn
= |s
: &'a
&'b
[u8]| -> bool
{
4654 struct UnsafeBytesToStr
impl<'a
> Fn
= |bytes
: &'a
[u8]| -> &'a
str {
4656 unsafe { from_utf8_unchecked(bytes) }
4660 #[stable(feature = "split_whitespace", since = "1.1.0")]
4661 impl<'a
> Iterator
for SplitWhitespace
<'a
> {
4662 type Item
= &'a
str;
4665 fn next(&mut self) -> Option
<&'a
str> {
4670 fn size_hint(&self) -> (usize, Option
<usize>) {
4671 self.inner
.size_hint()
4675 fn last(mut self) -> Option
<&'a
str> {
4680 #[stable(feature = "split_whitespace", since = "1.1.0")]
4681 impl<'a
> DoubleEndedIterator
for SplitWhitespace
<'a
> {
4683 fn next_back(&mut self) -> Option
<&'a
str> {
4684 self.inner
.next_back()
4688 #[stable(feature = "fused", since = "1.26.0")]
4689 impl FusedIterator
for SplitWhitespace
<'_
> {}
4691 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4692 impl<'a
> Iterator
for SplitAsciiWhitespace
<'a
> {
4693 type Item
= &'a
str;
4696 fn next(&mut self) -> Option
<&'a
str> {
4701 fn size_hint(&self) -> (usize, Option
<usize>) {
4702 self.inner
.size_hint()
4706 fn last(mut self) -> Option
<&'a
str> {
4711 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4712 impl<'a
> DoubleEndedIterator
for SplitAsciiWhitespace
<'a
> {
4714 fn next_back(&mut self) -> Option
<&'a
str> {
4715 self.inner
.next_back()
4719 #[stable(feature = "split_ascii_whitespace", since = "1.34.0")]
4720 impl FusedIterator
for SplitAsciiWhitespace
<'_
> {}
4722 #[unstable(feature = "split_inclusive", issue = "72360")]
4723 impl<'a
, P
: Pattern
<'a
>> Iterator
for SplitInclusive
<'a
, P
> {
4724 type Item
= &'a
str;
4727 fn next(&mut self) -> Option
<&'a
str> {
4728 self.0.next_inclusive()
4732 #[unstable(feature = "split_inclusive", issue = "72360")]
4733 impl<'a
, P
: Pattern
<'a
, Searcher
: fmt
::Debug
>> fmt
::Debug
for SplitInclusive
<'a
, P
> {
4734 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
4735 f
.debug_struct("SplitInclusive").field("0", &self.0).finish()
4739 // FIXME(#26925) Remove in favor of `#[derive(Clone)]`
4740 #[unstable(feature = "split_inclusive", issue = "72360")]
4741 impl<'a
, P
: Pattern
<'a
, Searcher
: Clone
>> Clone
for SplitInclusive
<'a
, P
> {
4742 fn clone(&self) -> Self {
4743 SplitInclusive(self.0.clone())
4747 #[unstable(feature = "split_inclusive", issue = "72360")]
4748 impl<'a
, P
: Pattern
<'a
, Searcher
: ReverseSearcher
<'a
>>> DoubleEndedIterator
4749 for SplitInclusive
<'a
, P
>
4752 fn next_back(&mut self) -> Option
<&'a
str> {
4753 self.0.next_back_inclusive()
4757 #[unstable(feature = "split_inclusive", issue = "72360")]
4758 impl<'a
, P
: Pattern
<'a
>> FusedIterator
for SplitInclusive
<'a
, P
> {}
4760 /// An iterator of [`u16`] over the string encoded as UTF-16.
4762 /// [`u16`]: ../../std/primitive.u16.html
4764 /// This struct is created by the [`encode_utf16`] method on [`str`].
4765 /// See its documentation for more.
4767 /// [`encode_utf16`]: ../../std/primitive.str.html#method.encode_utf16
4768 /// [`str`]: ../../std/primitive.str.html
4770 #[stable(feature = "encode_utf16", since = "1.8.0")]
4771 pub struct EncodeUtf16
<'a
> {
4776 #[stable(feature = "collection_debug", since = "1.17.0")]
4777 impl fmt
::Debug
for EncodeUtf16
<'_
> {
4778 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
4779 f
.pad("EncodeUtf16 { .. }")
4783 #[stable(feature = "encode_utf16", since = "1.8.0")]
4784 impl<'a
> Iterator
for EncodeUtf16
<'a
> {
4788 fn next(&mut self) -> Option
<u16> {
4789 if self.extra
!= 0 {
4790 let tmp
= self.extra
;
4795 let mut buf
= [0; 2];
4796 self.chars
.next().map(|ch
| {
4797 let n
= ch
.encode_utf16(&mut buf
).len();
4799 self.extra
= buf
[1];
4806 fn size_hint(&self) -> (usize, Option
<usize>) {
4807 let (low
, high
) = self.chars
.size_hint();
4808 // every char gets either one u16 or two u16,
4809 // so this iterator is between 1 or 2 times as
4810 // long as the underlying iterator.
4811 (low
, high
.and_then(|n
| n
.checked_mul(2)))
4815 #[stable(feature = "fused", since = "1.26.0")]
4816 impl FusedIterator
for EncodeUtf16
<'_
> {}
4818 /// The return type of [`str::escape_debug`].
4820 /// [`str::escape_debug`]: ../../std/primitive.str.html#method.escape_debug
4821 #[stable(feature = "str_escape", since = "1.34.0")]
4822 #[derive(Clone, Debug)]
4823 pub struct EscapeDebug
<'a
> {
4825 Flatten
<option
::IntoIter
<char::EscapeDebug
>>,
4826 FlatMap
<Chars
<'a
>, char::EscapeDebug
, CharEscapeDebugContinue
>,
4830 /// The return type of [`str::escape_default`].
4832 /// [`str::escape_default`]: ../../std/primitive.str.html#method.escape_default
4833 #[stable(feature = "str_escape", since = "1.34.0")]
4834 #[derive(Clone, Debug)]
4835 pub struct EscapeDefault
<'a
> {
4836 inner
: FlatMap
<Chars
<'a
>, char::EscapeDefault
, CharEscapeDefault
>,
4839 /// The return type of [`str::escape_unicode`].
4841 /// [`str::escape_unicode`]: ../../std/primitive.str.html#method.escape_unicode
4842 #[stable(feature = "str_escape", since = "1.34.0")]
4843 #[derive(Clone, Debug)]
4844 pub struct EscapeUnicode
<'a
> {
4845 inner
: FlatMap
<Chars
<'a
>, char::EscapeUnicode
, CharEscapeUnicode
>,
4848 macro_rules
! escape_types_impls
{
4849 ($
( $Name
: ident
),+) => {$
(
4850 #[stable(feature = "str_escape", since = "1.34.0")]
4851 impl<'a
> fmt
::Display
for $Name
<'a
> {
4852 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
4853 self.clone().try_for_each(|c
| f
.write_char(c
))
4857 #[stable(feature = "str_escape", since = "1.34.0")]
4858 impl<'a
> Iterator
for $Name
<'a
> {
4862 fn next(&mut self) -> Option
<char> { self.inner.next() }
4865 fn size_hint(&self) -> (usize, Option
<usize>) { self.inner.size_hint() }
4868 fn try_fold
<Acc
, Fold
, R
>(&mut self, init
: Acc
, fold
: Fold
) -> R
where
4869 Self: Sized
, Fold
: FnMut(Acc
, Self::Item
) -> R
, R
: Try
<Ok
=Acc
>
4871 self.inner
.try_fold(init
, fold
)
4875 fn fold
<Acc
, Fold
>(self, init
: Acc
, fold
: Fold
) -> Acc
4876 where Fold
: FnMut(Acc
, Self::Item
) -> Acc
,
4878 self.inner
.fold(init
, fold
)
4882 #[stable(feature = "str_escape", since = "1.34.0")]
4883 impl<'a
> FusedIterator
for $Name
<'a
> {}
4887 escape_types_impls
!(EscapeDebug
, EscapeDefault
, EscapeUnicode
);