Returns the length ofself.

This length is in bytes, notchars or graphemes. In other words,it might not be what a human considers the length of the string.

§Examples

letlen ="foo".len();assert_eq!(3, len);assert_eq!("ƒoo".len(),4);// fancy f!assert_eq!("ƒoo".chars().count(),3);

Returnstrue ifself has a length of zero bytes.

§Examples

lets ="";assert!(s.is_empty());lets ="not empty";assert!(!s.is_empty());

Converts a slice of bytes to a string slice.

A string slice (&str) is made of bytes (u8), and a byte slice(&[u8]) is made of bytes, so this function converts betweenthe two. Not all byte slices are valid string slices, however:&str requiresthat it is valid UTF-8.from_utf8() checks to ensure that the bytes are validUTF-8, and then does the conversion.

If you are sure that the byte slice is valid UTF-8, and you don’t want toincur the overhead of the validity check, there is an unsafe version ofthis function,from_utf8_unchecked, which has the samebehavior but skips the check.

If you need aString instead of a&str, considerString::from_utf8.

Because you can stack-allocate a[u8; N], and you can take a&[u8] of it, this function is one way to have astack-allocated string. There is an example of this in theexamples section below.

§Errors

ReturnsErr if the slice is not UTF-8 with a description as to why theprovided slice is not UTF-8.

§Examples

Basic usage:

// some bytes, in a vectorletsparkle_heart =vec![240,159,146,150];// We can use the ? (try) operator to check if the bytes are validletsparkle_heart = str::from_utf8(&sparkle_heart)?;assert_eq!("💖", sparkle_heart);

Incorrect bytes:

// some invalid bytes, in a vectorletsparkle_heart =vec![0,159,146,150];assert!(str::from_utf8(&sparkle_heart).is_err());

See the docs forUtf8Error for more details on the kinds oferrors that can be returned.

A “stack allocated string”:

// some bytes, in a stack-allocated arrayletsparkle_heart = [240,159,146,150];// We know these bytes are valid, so just use `unwrap()`.letsparkle_heart:&str = str::from_utf8(&sparkle_heart).unwrap();assert_eq!("💖", sparkle_heart);

Converts a mutable slice of bytes to a mutable string slice.

§Examples

Basic usage:

// "Hello, Rust!" as a mutable vectorletmuthellorust =vec![72,101,108,108,111,44,32,82,117,115,116,33];// As we know these bytes are valid, we can use `unwrap()`letoutstr = str::from_utf8_mut(&muthellorust).unwrap();assert_eq!("Hello, Rust!", outstr);

Incorrect bytes:

// Some invalid bytes in a mutable vectorletmutinvalid =vec![128,223];assert!(str::from_utf8_mut(&mutinvalid).is_err());

See the docs forUtf8Error for more details on the kinds oferrors that can be returned.

Converts a slice of bytes to a string slice without checkingthat the string contains valid UTF-8.

See the safe version,from_utf8, for more information.

§Safety

The bytes passed in must be valid UTF-8.

§Examples

Basic usage:

// some bytes, in a vectorletsparkle_heart =vec![240,159,146,150];letsparkle_heart =unsafe{    str::from_utf8_unchecked(&sparkle_heart)};assert_eq!("💖", sparkle_heart);

Converts a slice of bytes to a string slice without checkingthat the string contains valid UTF-8; mutable version.

See the immutable version,from_utf8_unchecked() for documentation and safety requirements.

§Examples

Basic usage:

letmutheart =vec![240,159,146,150];letheart =unsafe{ str::from_utf8_unchecked_mut(&mutheart) };assert_eq!("💖", heart);

Checks thatindex-th byte is the first byte in a UTF-8 code pointsequence or the end of the string.

The start and end of the string (whenindex == self.len()) areconsidered to be boundaries.

Returnsfalse ifindex is greater thanself.len().

§Examples

lets ="Löwe 老虎 Léopard";assert!(s.is_char_boundary(0));// start of `老`assert!(s.is_char_boundary(6));assert!(s.is_char_boundary(s.len()));// second byte of `ö`assert!(!s.is_char_boundary(2));// third byte of `老`assert!(!s.is_char_boundary(8));

Finds the closestx not exceedingindex whereis_char_boundary(x) istrue.

This method can help you truncate a string so that it’s still valid UTF-8, but doesn’texceed a given number of bytes. Note that this is done purely at the character leveland can still visually split graphemes, even though the underlying characters aren’tsplit. For example, the emoji 🧑‍🔬 (scientist) could be split so that the string onlyincludes 🧑 (person) instead.

§Examples

lets ="❤️🧡💛💚💙💜";assert_eq!(s.len(),26);assert!(!s.is_char_boundary(13));letclosest = s.floor_char_boundary(13);assert_eq!(closest,10);assert_eq!(&s[..closest],"❤️🧡");

Finds the closestx not belowindex whereis_char_boundary(x) istrue.

Ifindex is greater than the length of the string, this returns the length of the string.

This method is the natural complement tofloor_char_boundary. See that methodfor more details.

§Examples

lets ="❤️🧡💛💚💙💜";assert_eq!(s.len(),26);assert!(!s.is_char_boundary(13));letclosest = s.ceil_char_boundary(13);assert_eq!(closest,14);assert_eq!(&s[..closest],"❤️🧡💛");

Converts a string slice to a byte slice. To convert the byte slice backinto a string slice, use thefrom_utf8 function.

§Examples

letbytes ="bors".as_bytes();assert_eq!(b"bors", bytes);

Converts a mutable string slice to a mutable byte slice.

§Safety

The caller must ensure that the content of the slice is valid UTF-8before the borrow ends and the underlyingstr is used.

Use of astr whose contents are not valid UTF-8 is undefined behavior.

§Examples

Basic usage:

letmuts = String::from("Hello");letbytes =unsafe{ s.as_bytes_mut() };assert_eq!(b"Hello", bytes);

Mutability:

letmuts = String::from("🗻∈🌏");unsafe{letbytes = s.as_bytes_mut();    bytes[0] =0xF0;    bytes[1] =0x9F;    bytes[2] =0x8D;    bytes[3] =0x94;}assert_eq!("🍔∈🌏", s);

Converts a string slice to a raw pointer.

As string slices are a slice of bytes, the raw pointer points to au8. This pointer will be pointing to the first byte of the stringslice.

The caller must ensure that the returned pointer is never written to.If you need to mutate the contents of the string slice, useas_mut_ptr.

§Examples

lets ="Hello";letptr = s.as_ptr();

Converts a mutable string slice to a raw pointer.

As string slices are a slice of bytes, the raw pointer points to au8. This pointer will be pointing to the first byte of the stringslice.

It is your responsibility to make sure that the string slice only getsmodified in a way that it remains valid UTF-8.

Returns a subslice ofstr.

This is the non-panicking alternative to indexing thestr. ReturnsNone whenever equivalent indexing operation would panic.

§Examples

letv = String::from("🗻∈🌏");assert_eq!(Some("🗻"), v.get(0..4));// indices not on UTF-8 sequence boundariesassert!(v.get(1..).is_none());assert!(v.get(..8).is_none());// out of boundsassert!(v.get(..42).is_none());

Returns a mutable subslice ofstr.

This is the non-panicking alternative to indexing thestr. ReturnsNone whenever equivalent indexing operation would panic.

§Examples

letmutv = String::from("hello");// correct lengthassert!(v.get_mut(0..5).is_some());// out of boundsassert!(v.get_mut(..42).is_none());assert_eq!(Some("he"), v.get_mut(0..2).map(|v|&*v));assert_eq!("hello", v);{lets = v.get_mut(0..2);lets = s.map(|s| {        s.make_ascii_uppercase();&*s    });assert_eq!(Some("HE"), s);}assert_eq!("HEllo", v);

Returns an unchecked subslice ofstr.

This is the unchecked alternative to indexing thestr.

§Safety

Callers of this function are responsible that these preconditions aresatisfied:

• The starting index must not exceed the ending index;
• Indexes must be within bounds of the original slice;
• Indexes must lie on UTF-8 sequence boundaries.

Failing that, the returned string slice may reference invalid memory orviolate the invariants communicated by thestr type.

§Examples

letv ="🗻∈🌏";unsafe{assert_eq!("🗻", v.get_unchecked(0..4));assert_eq!("∈", v.get_unchecked(4..7));assert_eq!("🌏", v.get_unchecked(7..11));}

Returns a mutable, unchecked subslice ofstr.

This is the unchecked alternative to indexing thestr.

§Safety

Callers of this function are responsible that these preconditions aresatisfied:

• The starting index must not exceed the ending index;
• Indexes must be within bounds of the original slice;
• Indexes must lie on UTF-8 sequence boundaries.

Failing that, the returned string slice may reference invalid memory orviolate the invariants communicated by thestr type.

§Examples

letmutv = String::from("🗻∈🌏");unsafe{assert_eq!("🗻", v.get_unchecked_mut(0..4));assert_eq!("∈", v.get_unchecked_mut(4..7));assert_eq!("🌏", v.get_unchecked_mut(7..11));}

Creates a string slice from another string slice, bypassing safetychecks.

This is generally not recommended, use with caution! For a safealternative seestr andIndex.

This new slice goes frombegin toend, includingbegin butexcludingend.

To get a mutable string slice instead, see theslice_mut_unchecked method.

§Safety

Callers of this function are responsible that three preconditions aresatisfied:

• begin must not exceedend.
• begin andend must be byte positions within the string slice.
• begin andend must lie on UTF-8 sequence boundaries.

§Examples

lets ="Löwe 老虎 Léopard";unsafe{assert_eq!("Löwe 老虎 Léopard", s.slice_unchecked(0,21));}lets ="Hello, world!";unsafe{assert_eq!("world", s.slice_unchecked(7,12));}

Creates a string slice from another string slice, bypassing safetychecks.

This is generally not recommended, use with caution! For a safealternative seestr andIndexMut.

This new slice goes frombegin toend, includingbegin butexcludingend.

To get an immutable string slice instead, see theslice_unchecked method.

§Safety

Callers of this function are responsible that three preconditions aresatisfied:

• begin must not exceedend.
• begin andend must be byte positions within the string slice.
• begin andend must lie on UTF-8 sequence boundaries.

Divides one string slice into two at an index.

The argument,mid, should be a byte offset from the start of thestring. It must also be on the boundary of a UTF-8 code point.

The two slices returned go from the start of the string slice tomid,and frommid to the end of the string slice.

To get mutable string slices instead, see thesplit_at_mutmethod.

§Panics

Panics ifmid is not on a UTF-8 code point boundary, or if it is pastthe end of the last code point of the string slice. For a non-panickingalternative seesplit_at_checked.

§Examples

lets ="Per Martin-Löf";let(first, last) = s.split_at(3);assert_eq!("Per", first);assert_eq!(" Martin-Löf", last);

Divides one mutable string slice into two at an index.

The argument,mid, should be a byte offset from the start of thestring. It must also be on the boundary of a UTF-8 code point.

The two slices returned go from the start of the string slice tomid,and frommid to the end of the string slice.

To get immutable string slices instead, see thesplit_at method.

§Panics

Panics ifmid is not on a UTF-8 code point boundary, or if it is pastthe end of the last code point of the string slice. For a non-panickingalternative seesplit_at_mut_checked.

§Examples

letmuts ="Per Martin-Löf".to_string();{let(first, last) = s.split_at_mut(3);    first.make_ascii_uppercase();assert_eq!("PER", first);assert_eq!(" Martin-Löf", last);}assert_eq!("PER Martin-Löf", s);

Divides one string slice into two at an index.

The argument,mid, should be a valid byte offset from the start of thestring. It must also be on the boundary of a UTF-8 code point. Themethod returnsNone if that’s not the case.

The two slices returned go from the start of the string slice tomid,and frommid to the end of the string slice.

To get mutable string slices instead, see thesplit_at_mut_checkedmethod.

§Examples

lets ="Per Martin-Löf";let(first, last) = s.split_at_checked(3).unwrap();assert_eq!("Per", first);assert_eq!(" Martin-Löf", last);assert_eq!(None, s.split_at_checked(13));// Inside “ö”assert_eq!(None, s.split_at_checked(16));// Beyond the string length

Divides one mutable string slice into two at an index.

The argument,mid, should be a valid byte offset from the start of thestring. It must also be on the boundary of a UTF-8 code point. Themethod returnsNone if that’s not the case.

The two slices returned go from the start of the string slice tomid,and frommid to the end of the string slice.

To get immutable string slices instead, see thesplit_at_checked method.

§Examples

letmuts ="Per Martin-Löf".to_string();if letSome((first, last)) = s.split_at_mut_checked(3) {    first.make_ascii_uppercase();assert_eq!("PER", first);assert_eq!(" Martin-Löf", last);}assert_eq!("PER Martin-Löf", s);assert_eq!(None, s.split_at_mut_checked(13));// Inside “ö”assert_eq!(None, s.split_at_mut_checked(16));// Beyond the string length

Returns an iterator over thechars of a string slice.

As a string slice consists of valid UTF-8, we can iterate through astring slice bychar. This method returns such an iterator.

It’s important to remember thatchar represents a Unicode ScalarValue, and might not match your idea of what a ‘character’ is. Iterationover grapheme clusters may be what you actually want. This functionalityis not provided by Rust’s standard library, check crates.io instead.

§Examples

Basic usage:

letword ="goodbye";letcount = word.chars().count();assert_eq!(7, count);letmutchars = word.chars();assert_eq!(Some('g'), chars.next());assert_eq!(Some('o'), chars.next());assert_eq!(Some('o'), chars.next());assert_eq!(Some('d'), chars.next());assert_eq!(Some('b'), chars.next());assert_eq!(Some('y'), chars.next());assert_eq!(Some('e'), chars.next());assert_eq!(None, chars.next());

Remember,chars might not match your intuition about characters:

lety ="y̆";letmutchars = y.chars();assert_eq!(Some('y'), chars.next());// not 'y̆'assert_eq!(Some('\u{0306}'), chars.next());assert_eq!(None, chars.next());

Returns an iterator over thechars of a string slice, and theirpositions.

As a string slice consists of valid UTF-8, we can iterate through astring slice bychar. This method returns an iterator of boththesechars, as well as their byte positions.

The iterator yields tuples. The position is first, thechar issecond.

§Examples

Basic usage:

letword ="goodbye";letcount = word.char_indices().count();assert_eq!(7, count);letmutchar_indices = word.char_indices();assert_eq!(Some((0,'g')), char_indices.next());assert_eq!(Some((1,'o')), char_indices.next());assert_eq!(Some((2,'o')), char_indices.next());assert_eq!(Some((3,'d')), char_indices.next());assert_eq!(Some((4,'b')), char_indices.next());assert_eq!(Some((5,'y')), char_indices.next());assert_eq!(Some((6,'e')), char_indices.next());assert_eq!(None, char_indices.next());

Remember,chars might not match your intuition about characters:

letyes ="y̆es";letmutchar_indices = yes.char_indices();assert_eq!(Some((0,'y')), char_indices.next());// not (0, 'y̆')assert_eq!(Some((1,'\u{0306}')), char_indices.next());// note the 3 here - the previous character took up two bytesassert_eq!(Some((3,'e')), char_indices.next());assert_eq!(Some((4,'s')), char_indices.next());assert_eq!(None, char_indices.next());

Returns an iterator over the bytes of a string slice.

As a string slice consists of a sequence of bytes, we can iteratethrough a string slice by byte. This method returns such an iterator.

§Examples

letmutbytes ="bors".bytes();assert_eq!(Some(b'b'), bytes.next());assert_eq!(Some(b'o'), bytes.next());assert_eq!(Some(b'r'), bytes.next());assert_eq!(Some(b's'), bytes.next());assert_eq!(None, bytes.next());

Splits a string slice by whitespace.

The iterator returned will return string slices that are sub-slices ofthe original string slice, separated by any amount of whitespace.

‘Whitespace’ is defined according to the terms of the Unicode DerivedCore PropertyWhite_Space. If you only want to split on ASCII whitespaceinstead, usesplit_ascii_whitespace.

§Examples

Basic usage:

letmutiter ="A few words".split_whitespace();assert_eq!(Some("A"), iter.next());assert_eq!(Some("few"), iter.next());assert_eq!(Some("words"), iter.next());assert_eq!(None, iter.next());

All kinds of whitespace are considered:

letmutiter =" Mary   had\ta\u{2009}little  \n\t lamb".split_whitespace();assert_eq!(Some("Mary"), iter.next());assert_eq!(Some("had"), iter.next());assert_eq!(Some("a"), iter.next());assert_eq!(Some("little"), iter.next());assert_eq!(Some("lamb"), iter.next());assert_eq!(None, iter.next());

If the string is empty or all whitespace, the iterator yields no string slices:

assert_eq!("".split_whitespace().next(),None);assert_eq!("   ".split_whitespace().next(),None);

Splits a string slice by ASCII whitespace.

The iterator returned will return string slices that are sub-slices ofthe original string slice, separated by any amount of ASCII whitespace.

This uses the same definition aschar::is_ascii_whitespace.To split by UnicodeWhitespace instead, usesplit_whitespace.

§Examples

Basic usage:

letmutiter ="A few words".split_ascii_whitespace();assert_eq!(Some("A"), iter.next());assert_eq!(Some("few"), iter.next());assert_eq!(Some("words"), iter.next());assert_eq!(None, iter.next());

Various kinds of ASCII whitespace are considered(seechar::is_ascii_whitespace):

letmutiter =" Mary   had\ta little  \n\t lamb".split_ascii_whitespace();assert_eq!(Some("Mary"), iter.next());assert_eq!(Some("had"), iter.next());assert_eq!(Some("a"), iter.next());assert_eq!(Some("little"), iter.next());assert_eq!(Some("lamb"), iter.next());assert_eq!(None, iter.next());

If the string is empty or all ASCII whitespace, the iterator yields no string slices:

assert_eq!("".split_ascii_whitespace().next(),None);assert_eq!("   ".split_ascii_whitespace().next(),None);

Returns an iterator over the lines of a string, as string slices.

Lines are split at line endings that are either newlines (\n) orsequences of a carriage return followed by a line feed (\r\n).

Line terminators are not included in the lines returned by the iterator.

Note that any carriage return (\r) not immediately followed by aline feed (\n) does not split a line. These carriage returns arethereby included in the produced lines.

The final line ending is optional. A string that ends with a final lineending will return the same lines as an otherwise identical stringwithout a final line ending.

An empty string returns an empty iterator.

§Examples

Basic usage:

lettext ="foo\r\nbar\n\nbaz\r";letmutlines = text.lines();assert_eq!(Some("foo"), lines.next());assert_eq!(Some("bar"), lines.next());assert_eq!(Some(""), lines.next());// Trailing carriage return is included in the last lineassert_eq!(Some("baz\r"), lines.next());assert_eq!(None, lines.next());

The final line does not require any ending:

lettext ="foo\nbar\n\r\nbaz";letmutlines = text.lines();assert_eq!(Some("foo"), lines.next());assert_eq!(Some("bar"), lines.next());assert_eq!(Some(""), lines.next());assert_eq!(Some("baz"), lines.next());assert_eq!(None, lines.next());

An empty string returns an empty iterator:

lettext ="";letmutlines = text.lines();assert_eq!(lines.next(),None);

Returns an iterator over the lines of a string.

Returns an iterator ofu16 over the string encodedas native endian UTF-16 (without byte-order mark).

§Examples

lettext ="Zażółć gęślą jaźń";letutf8_len = text.len();letutf16_len = text.encode_utf16().count();assert!(utf16_len <= utf8_len);

Returnstrue if the given pattern matches a sub-slice ofthis string slice.

Returnsfalse if it does not.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Examples

letbananas ="bananas";assert!(bananas.contains("nana"));assert!(!bananas.contains("apples"));

Returnstrue if the given pattern matches a prefix of thisstring slice.

Returnsfalse if it does not.

Thepattern can be a&str, in which case this function will return true ifthe&str is a prefix of this string slice.

Thepattern can also be achar, a slice ofchars, or afunction or closure that determines if a character matches.These will only be checked against the first character of this string slice.Look at the second example below regarding behavior for slices ofchars.

§Examples

letbananas ="bananas";assert!(bananas.starts_with("bana"));assert!(!bananas.starts_with("nana"));

letbananas ="bananas";// Note that both of these assert successfully.assert!(bananas.starts_with(&['b','a','n','a']));assert!(bananas.starts_with(&['a','b','c','d']));

Returnstrue if the given pattern matches a suffix of thisstring slice.

Returnsfalse if it does not.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Examples

letbananas ="bananas";assert!(bananas.ends_with("anas"));assert!(!bananas.ends_with("nana"));

Returns the byte index of the first character of this string slice thatmatches the pattern.

ReturnsNone if the pattern doesn’t match.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Examples

Simple patterns:

lets ="Löwe 老虎 Léopard Gepardi";assert_eq!(s.find('L'),Some(0));assert_eq!(s.find('é'),Some(14));assert_eq!(s.find("pard"),Some(17));

More complex patterns using point-free style and closures:

lets ="Löwe 老虎 Léopard";assert_eq!(s.find(char::is_whitespace),Some(5));assert_eq!(s.find(char::is_lowercase),Some(1));assert_eq!(s.find(|c: char| c.is_whitespace() || c.is_lowercase()),Some(1));assert_eq!(s.find(|c: char| (c <'o') && (c >'a')),Some(4));

Not finding the pattern:

lets ="Löwe 老虎 Léopard";letx:&[_] =&['1','2'];assert_eq!(s.find(x),None);

Returns the byte index for the first character of the last match of the pattern inthis string slice.

ReturnsNone if the pattern doesn’t match.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Examples

Simple patterns:

lets ="Löwe 老虎 Léopard Gepardi";assert_eq!(s.rfind('L'),Some(13));assert_eq!(s.rfind('é'),Some(14));assert_eq!(s.rfind("pard"),Some(24));

More complex patterns with closures:

lets ="Löwe 老虎 Léopard";assert_eq!(s.rfind(char::is_whitespace),Some(12));assert_eq!(s.rfind(char::is_lowercase),Some(20));

Not finding the pattern:

lets ="Löwe 老虎 Léopard";letx:&[_] =&['1','2'];assert_eq!(s.rfind(x),None);

Returns an iterator over substrings of this string slice, separated bycharacters matched by a pattern.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

If there are no matches the full string slice is returned as the onlyitem in the iterator.

§Iterator behavior

The returned iterator will be aDoubleEndedIterator if the patternallows a reverse search and forward/reverse search yields the sameelements. This is true for, e.g.,char, but not for&str.

If the pattern allows a reverse search but its results might differfrom a forward search, thersplit method can be used.

§Examples

Simple patterns:

letv: Vec<&str> ="Mary had a little lamb".split(' ').collect();assert_eq!(v, ["Mary","had","a","little","lamb"]);letv: Vec<&str> ="".split('X').collect();assert_eq!(v, [""]);letv: Vec<&str> ="lionXXtigerXleopard".split('X').collect();assert_eq!(v, ["lion","","tiger","leopard"]);letv: Vec<&str> ="lion::tiger::leopard".split("::").collect();assert_eq!(v, ["lion","tiger","leopard"]);letv: Vec<&str> ="AABBCC".split("DD").collect();assert_eq!(v, ["AABBCC"]);letv: Vec<&str> ="abc1def2ghi".split(char::is_numeric).collect();assert_eq!(v, ["abc","def","ghi"]);letv: Vec<&str> ="lionXtigerXleopard".split(char::is_uppercase).collect();assert_eq!(v, ["lion","tiger","leopard"]);

If the pattern is a slice of chars, split on each occurrence of any of the characters:

letv: Vec<&str> ="2020-11-03 23:59".split(&['-',' ',':','@'][..]).collect();assert_eq!(v, ["2020","11","03","23","59"]);

A more complex pattern, using a closure:

letv: Vec<&str> ="abc1defXghi".split(|c| c =='1'|| c =='X').collect();assert_eq!(v, ["abc","def","ghi"]);

If a string contains multiple contiguous separators, you will end upwith empty strings in the output:

letx ="||||a||b|c".to_string();letd: Vec<_> = x.split('|').collect();assert_eq!(d,&["","","","","a","","b","c"]);

Contiguous separators are separated by the empty string.

letx ="(///)".to_string();letd: Vec<_> = x.split('/').collect();assert_eq!(d,&["(","","",")"]);

Separators at the start or end of a string are neighboredby empty strings.

letd: Vec<_> ="010".split("0").collect();assert_eq!(d,&["","1",""]);

When the empty string is used as a separator, it separatesevery character in the string, along with the beginningand end of the string.

letf: Vec<_> ="rust".split("").collect();assert_eq!(f,&["","r","u","s","t",""]);

Contiguous separators can lead to possibly surprising behaviorwhen whitespace is used as the separator. This code is correct:

letx ="    a  b c".to_string();letd: Vec<_> = x.split(' ').collect();assert_eq!(d,&["","","","","a","","b","c"]);

It doesnot give you:

assert_eq!(d,&["a","b","c"]);

Usesplit_whitespace for this behavior.

Returns an iterator over substrings of this string slice, separated bycharacters matched by a pattern.

Differs from the iterator produced bysplit in thatsplit_inclusiveleaves the matched part as the terminator of the substring.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Examples

letv: Vec<&str> ="Mary had a little lamb\nlittle lamb\nlittle lamb.".split_inclusive('\n').collect();assert_eq!(v, ["Mary had a little lamb\n","little lamb\n","little lamb."]);

If the last element of the string is matched,that element will be considered the terminator of the preceding substring.That substring will be the last item returned by the iterator.

letv: Vec<&str> ="Mary had a little lamb\nlittle lamb\nlittle lamb.\n".split_inclusive('\n').collect();assert_eq!(v, ["Mary had a little lamb\n","little lamb\n","little lamb.\n"]);

Returns an iterator over substrings of the given string slice, separatedby characters matched by a pattern and yielded in reverse order.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Iterator behavior

The returned iterator requires that the pattern supports a reversesearch, and it will be aDoubleEndedIterator if a forward/reversesearch yields the same elements.

For iterating from the front, thesplit method can be used.

§Examples

Simple patterns:

letv: Vec<&str> ="Mary had a little lamb".rsplit(' ').collect();assert_eq!(v, ["lamb","little","a","had","Mary"]);letv: Vec<&str> ="".rsplit('X').collect();assert_eq!(v, [""]);letv: Vec<&str> ="lionXXtigerXleopard".rsplit('X').collect();assert_eq!(v, ["leopard","tiger","","lion"]);letv: Vec<&str> ="lion::tiger::leopard".rsplit("::").collect();assert_eq!(v, ["leopard","tiger","lion"]);

A more complex pattern, using a closure:

letv: Vec<&str> ="abc1defXghi".rsplit(|c| c =='1'|| c =='X').collect();assert_eq!(v, ["ghi","def","abc"]);

Returns an iterator over substrings of the given string slice, separatedby characters matched by a pattern.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

Equivalent tosplit, except that the trailing substringis skipped if empty.

This method can be used for string data that isterminated,rather thanseparated by a pattern.

§Iterator behavior

The returned iterator will be aDoubleEndedIterator if the patternallows a reverse search and forward/reverse search yields the sameelements. This is true for, e.g.,char, but not for&str.

If the pattern allows a reverse search but its results might differfrom a forward search, thersplit_terminator method can be used.

§Examples

letv: Vec<&str> ="A.B.".split_terminator('.').collect();assert_eq!(v, ["A","B"]);letv: Vec<&str> ="A..B..".split_terminator(".").collect();assert_eq!(v, ["A","","B",""]);letv: Vec<&str> ="A.B:C.D".split_terminator(&['.',':'][..]).collect();assert_eq!(v, ["A","B","C","D"]);

Returns an iterator over substrings ofself, separated by charactersmatched by a pattern and yielded in reverse order.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

Equivalent tosplit, except that the trailing substring isskipped if empty.

This method can be used for string data that isterminated,rather thanseparated by a pattern.

§Iterator behavior

The returned iterator requires that the pattern supports areverse search, and it will be double ended if a forward/reversesearch yields the same elements.

For iterating from the front, thesplit_terminator method can beused.

§Examples

letv: Vec<&str> ="A.B.".rsplit_terminator('.').collect();assert_eq!(v, ["B","A"]);letv: Vec<&str> ="A..B..".rsplit_terminator(".").collect();assert_eq!(v, ["","B","","A"]);letv: Vec<&str> ="A.B:C.D".rsplit_terminator(&['.',':'][..]).collect();assert_eq!(v, ["D","C","B","A"]);

Returns an iterator over substrings of the given string slice, separatedby a pattern, restricted to returning at mostn items.

Ifn substrings are returned, the last substring (thenth substring)will contain the remainder of the string.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Iterator behavior

The returned iterator will not be double ended, because it isnot efficient to support.

If the pattern allows a reverse search, thersplitn method can beused.

§Examples

Simple patterns:

letv: Vec<&str> ="Mary had a little lambda".splitn(3,' ').collect();assert_eq!(v, ["Mary","had","a little lambda"]);letv: Vec<&str> ="lionXXtigerXleopard".splitn(3,"X").collect();assert_eq!(v, ["lion","","tigerXleopard"]);letv: Vec<&str> ="abcXdef".splitn(1,'X').collect();assert_eq!(v, ["abcXdef"]);letv: Vec<&str> ="".splitn(1,'X').collect();assert_eq!(v, [""]);

A more complex pattern, using a closure:

letv: Vec<&str> ="abc1defXghi".splitn(2, |c| c =='1'|| c =='X').collect();assert_eq!(v, ["abc","defXghi"]);

Returns an iterator over substrings of this string slice, separated by apattern, starting from the end of the string, restricted to returning atmostn items.

Ifn substrings are returned, the last substring (thenth substring)will contain the remainder of the string.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Iterator behavior

The returned iterator will not be double ended, because it is notefficient to support.

For splitting from the front, thesplitn method can be used.

§Examples

Simple patterns:

letv: Vec<&str> ="Mary had a little lamb".rsplitn(3,' ').collect();assert_eq!(v, ["lamb","little","Mary had a"]);letv: Vec<&str> ="lionXXtigerXleopard".rsplitn(3,'X').collect();assert_eq!(v, ["leopard","tiger","lionX"]);letv: Vec<&str> ="lion::tiger::leopard".rsplitn(2,"::").collect();assert_eq!(v, ["leopard","lion::tiger"]);

A more complex pattern, using a closure:

letv: Vec<&str> ="abc1defXghi".rsplitn(2, |c| c =='1'|| c =='X').collect();assert_eq!(v, ["ghi","abc1def"]);

Splits the string on the first occurrence of the specified delimiter andreturns prefix before delimiter and suffix after delimiter.

§Examples

assert_eq!("cfg".split_once('='),None);assert_eq!("cfg=".split_once('='),Some(("cfg","")));assert_eq!("cfg=foo".split_once('='),Some(("cfg","foo")));assert_eq!("cfg=foo=bar".split_once('='),Some(("cfg","foo=bar")));

Splits the string on the last occurrence of the specified delimiter andreturns prefix before delimiter and suffix after delimiter.

§Examples

assert_eq!("cfg".rsplit_once('='),None);assert_eq!("cfg=".rsplit_once('='),Some(("cfg","")));assert_eq!("cfg=foo".rsplit_once('='),Some(("cfg","foo")));assert_eq!("cfg=foo=bar".rsplit_once('='),Some(("cfg=foo","bar")));

Returns an iterator over the disjoint matches of a pattern within thegiven string slice.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Iterator behavior

The returned iterator will be aDoubleEndedIterator if the patternallows a reverse search and forward/reverse search yields the sameelements. This is true for, e.g.,char, but not for&str.

If the pattern allows a reverse search but its results might differfrom a forward search, thermatches method can be used.

§Examples

letv: Vec<&str> ="abcXXXabcYYYabc".matches("abc").collect();assert_eq!(v, ["abc","abc","abc"]);letv: Vec<&str> ="1abc2abc3".matches(char::is_numeric).collect();assert_eq!(v, ["1","2","3"]);

Returns an iterator over the disjoint matches of a pattern within thisstring slice, yielded in reverse order.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Iterator behavior

The returned iterator requires that the pattern supports a reversesearch, and it will be aDoubleEndedIterator if a forward/reversesearch yields the same elements.

For iterating from the front, thematches method can be used.

§Examples

letv: Vec<&str> ="abcXXXabcYYYabc".rmatches("abc").collect();assert_eq!(v, ["abc","abc","abc"]);letv: Vec<&str> ="1abc2abc3".rmatches(char::is_numeric).collect();assert_eq!(v, ["3","2","1"]);

Returns an iterator over the disjoint matches of a pattern within this stringslice as well as the index that the match starts at.

For matches ofpat withinself that overlap, only the indicescorresponding to the first match are returned.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Iterator behavior

The returned iterator will be aDoubleEndedIterator if the patternallows a reverse search and forward/reverse search yields the sameelements. This is true for, e.g.,char, but not for&str.

If the pattern allows a reverse search but its results might differfrom a forward search, thermatch_indices method can be used.

§Examples

letv: Vec<_> ="abcXXXabcYYYabc".match_indices("abc").collect();assert_eq!(v, [(0,"abc"), (6,"abc"), (12,"abc")]);letv: Vec<_> ="1abcabc2".match_indices("abc").collect();assert_eq!(v, [(1,"abc"), (4,"abc")]);letv: Vec<_> ="ababa".match_indices("aba").collect();assert_eq!(v, [(0,"aba")]);// only the first `aba`

Returns an iterator over the disjoint matches of a pattern withinself,yielded in reverse order along with the index of the match.

For matches ofpat withinself that overlap, only the indicescorresponding to the last match are returned.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Iterator behavior

The returned iterator requires that the pattern supports a reversesearch, and it will be aDoubleEndedIterator if a forward/reversesearch yields the same elements.

For iterating from the front, thematch_indices method can be used.

§Examples

letv: Vec<_> ="abcXXXabcYYYabc".rmatch_indices("abc").collect();assert_eq!(v, [(12,"abc"), (6,"abc"), (0,"abc")]);letv: Vec<_> ="1abcabc2".rmatch_indices("abc").collect();assert_eq!(v, [(4,"abc"), (1,"abc")]);letv: Vec<_> ="ababa".rmatch_indices("aba").collect();assert_eq!(v, [(2,"aba")]);// only the last `aba`

Returns a string slice with leading and trailing whitespace removed.

‘Whitespace’ is defined according to the terms of the Unicode DerivedCore PropertyWhite_Space, which includes newlines.

§Examples

lets ="\n Hello\tworld\t\n";assert_eq!("Hello\tworld", s.trim());

Returns a string slice with leading whitespace removed.

‘Whitespace’ is defined according to the terms of the Unicode DerivedCore PropertyWhite_Space, which includes newlines.

§Text directionality

A string is a sequence of bytes.start in this context means the firstposition of that byte string; for a left-to-right language like English orRussian, this will be left side, and for right-to-left languages likeArabic or Hebrew, this will be the right side.

§Examples

Basic usage:

lets ="\n Hello\tworld\t\n";assert_eq!("Hello\tworld\t\n", s.trim_start());

Directionality:

lets ="  English  ";assert!(Some('E') == s.trim_start().chars().next());lets ="  עברית  ";assert!(Some('ע') == s.trim_start().chars().next());

Returns a string slice with trailing whitespace removed.

‘Whitespace’ is defined according to the terms of the Unicode DerivedCore PropertyWhite_Space, which includes newlines.

§Text directionality

A string is a sequence of bytes.end in this context means the lastposition of that byte string; for a left-to-right language like English orRussian, this will be right side, and for right-to-left languages likeArabic or Hebrew, this will be the left side.

§Examples

Basic usage:

lets ="\n Hello\tworld\t\n";assert_eq!("\n Hello\tworld", s.trim_end());

Directionality:

lets ="  English  ";assert!(Some('h') == s.trim_end().chars().rev().next());lets ="  עברית  ";assert!(Some('ת') == s.trim_end().chars().rev().next());

Returns a string slice with leading whitespace removed.

‘Whitespace’ is defined according to the terms of the Unicode DerivedCore PropertyWhite_Space.

§Text directionality

A string is a sequence of bytes. ‘Left’ in this context means the firstposition of that byte string; for a language like Arabic or Hebrewwhich are ‘right to left’ rather than ‘left to right’, this will betheright side, not the left.

§Examples

Basic usage:

lets =" Hello\tworld\t";assert_eq!("Hello\tworld\t", s.trim_left());

Directionality:

lets ="  English";assert!(Some('E') == s.trim_left().chars().next());lets ="  עברית";assert!(Some('ע') == s.trim_left().chars().next());

Returns a string slice with trailing whitespace removed.

‘Whitespace’ is defined according to the terms of the Unicode DerivedCore PropertyWhite_Space.

§Text directionality

A string is a sequence of bytes. ‘Right’ in this context means the lastposition of that byte string; for a language like Arabic or Hebrewwhich are ‘right to left’ rather than ‘left to right’, this will betheleft side, not the right.

§Examples

Basic usage:

lets =" Hello\tworld\t";assert_eq!(" Hello\tworld", s.trim_right());

Directionality:

lets ="English  ";assert!(Some('h') == s.trim_right().chars().rev().next());lets ="עברית  ";assert!(Some('ת') == s.trim_right().chars().rev().next());

Returns a string slice with all prefixes and suffixes that match apattern repeatedly removed.

Thepattern can be achar, a slice ofchars, or a functionor closure that determines if a character matches.

§Examples

Simple patterns:

assert_eq!("11foo1bar11".trim_matches('1'),"foo1bar");assert_eq!("123foo1bar123".trim_matches(char::is_numeric),"foo1bar");letx:&[_] =&['1','2'];assert_eq!("12foo1bar12".trim_matches(x),"foo1bar");

A more complex pattern, using a closure:

assert_eq!("1foo1barXX".trim_matches(|c| c =='1'|| c =='X'),"foo1bar");

Returns a string slice with all prefixes that match a patternrepeatedly removed.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Text directionality

A string is a sequence of bytes.start in this context means the firstposition of that byte string; for a left-to-right language like English orRussian, this will be left side, and for right-to-left languages likeArabic or Hebrew, this will be the right side.

§Examples

assert_eq!("11foo1bar11".trim_start_matches('1'),"foo1bar11");assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric),"foo1bar123");letx:&[_] =&['1','2'];assert_eq!("12foo1bar12".trim_start_matches(x),"foo1bar12");

Returns a string slice with the prefix removed.

If the string starts with the patternprefix, returns the substring after the prefix,wrapped inSome. Unliketrim_start_matches, this method removes the prefix exactly once.

If the string does not start withprefix, returnsNone.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Examples

assert_eq!("foo:bar".strip_prefix("foo:"),Some("bar"));assert_eq!("foo:bar".strip_prefix("bar"),None);assert_eq!("foofoo".strip_prefix("foo"),Some("foo"));

Returns a string slice with the suffix removed.

If the string ends with the patternsuffix, returns the substring before the suffix,wrapped inSome. Unliketrim_end_matches, this method removes the suffix exactly once.

If the string does not end withsuffix, returnsNone.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Examples

assert_eq!("bar:foo".strip_suffix(":foo"),Some("bar"));assert_eq!("bar:foo".strip_suffix("bar"),None);assert_eq!("foofoo".strip_suffix("foo"),Some("foo"));

Returns a string slice with the prefix and suffix removed.

If the string starts with the patternprefix and ends with the patternsuffix, returnsthe substring after the prefix and before the suffix, wrapped inSome.Unliketrim_start_matches andtrim_end_matches, this method removes both the prefixand suffix exactly once.

If the string does not start withprefix or does not end withsuffix, returnsNone.

Eachpattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Examples

#![feature(strip_circumfix)]assert_eq!("bar:hello:foo".strip_circumfix("bar:",":foo"),Some("hello"));assert_eq!("bar:foo".strip_circumfix("foo","foo"),None);assert_eq!("foo:bar;".strip_circumfix("foo:",';'),Some("bar"));

Returns a string slice with the optional prefix removed.

If the string starts with the patternprefix, returns the substring after the prefix.Unlikestrip_prefix, this method always returns&str for easy method chaining,instead of returningOption<&str>.

If the string does not start withprefix, returns the original string unchanged.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Examples

#![feature(trim_prefix_suffix)]// Prefix present - removes itassert_eq!("foo:bar".trim_prefix("foo:"),"bar");assert_eq!("foofoo".trim_prefix("foo"),"foo");// Prefix absent - returns original stringassert_eq!("foo:bar".trim_prefix("bar"),"foo:bar");// Method chaining exampleassert_eq!("<https://example.com/>".trim_prefix('<').trim_suffix('>'),"https://example.com/");

Returns a string slice with the optional suffix removed.

If the string ends with the patternsuffix, returns the substring before the suffix.Unlikestrip_suffix, this method always returns&str for easy method chaining,instead of returningOption<&str>.

If the string does not end withsuffix, returns the original string unchanged.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Examples

#![feature(trim_prefix_suffix)]// Suffix present - removes itassert_eq!("bar:foo".trim_suffix(":foo"),"bar");assert_eq!("foofoo".trim_suffix("foo"),"foo");// Suffix absent - returns original stringassert_eq!("bar:foo".trim_suffix("bar"),"bar:foo");// Method chaining exampleassert_eq!("<https://example.com/>".trim_prefix('<').trim_suffix('>'),"https://example.com/");

Returns a string slice with all suffixes that match a patternrepeatedly removed.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Text directionality

A string is a sequence of bytes.end in this context means the lastposition of that byte string; for a left-to-right language like English orRussian, this will be right side, and for right-to-left languages likeArabic or Hebrew, this will be the left side.

§Examples

Simple patterns:

assert_eq!("11foo1bar11".trim_end_matches('1'),"11foo1bar");assert_eq!("123foo1bar123".trim_end_matches(char::is_numeric),"123foo1bar");letx:&[_] =&['1','2'];assert_eq!("12foo1bar12".trim_end_matches(x),"12foo1bar");

A more complex pattern, using a closure:

assert_eq!("1fooX".trim_end_matches(|c| c =='1'|| c =='X'),"1foo");

Returns a string slice with all prefixes that match a patternrepeatedly removed.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Text directionality

A string is a sequence of bytes. ‘Left’ in this context means the firstposition of that byte string; for a language like Arabic or Hebrewwhich are ‘right to left’ rather than ‘left to right’, this will betheright side, not the left.

§Examples

assert_eq!("11foo1bar11".trim_left_matches('1'),"foo1bar11");assert_eq!("123foo1bar123".trim_left_matches(char::is_numeric),"foo1bar123");letx:&[_] =&['1','2'];assert_eq!("12foo1bar12".trim_left_matches(x),"foo1bar12");

Returns a string slice with all suffixes that match a patternrepeatedly removed.

Thepattern can be a&str,char, a slice ofchars, or afunction or closure that determines if a character matches.

§Text directionality

A string is a sequence of bytes. ‘Right’ in this context means the lastposition of that byte string; for a language like Arabic or Hebrewwhich are ‘right to left’ rather than ‘left to right’, this will betheleft side, not the right.

§Examples

Simple patterns:

assert_eq!("11foo1bar11".trim_right_matches('1'),"11foo1bar");assert_eq!("123foo1bar123".trim_right_matches(char::is_numeric),"123foo1bar");letx:&[_] =&['1','2'];assert_eq!("12foo1bar12".trim_right_matches(x),"12foo1bar");

A more complex pattern, using a closure:

assert_eq!("1fooX".trim_right_matches(|c| c =='1'|| c =='X'),"1foo");

Parses this string slice into another type.

Becauseparse is so general, it can cause problems with typeinference. As such,parse is one of the few times you’ll seethe syntax affectionately known as the ‘turbofish’:::<>. Thishelps the inference algorithm understand specifically which typeyou’re trying to parse into.

parse can parse into any type that implements theFromStr trait.

§Errors

Will returnErr if it’s not possible to parse this string slice intothe desired type.

§Examples

Basic usage:

letfour: u32 ="4".parse().unwrap();assert_eq!(4, four);

Using the ‘turbofish’ instead of annotatingfour:

letfour ="4".parse::<u32>();assert_eq!(Ok(4), four);

Failing to parse:

letnope ="j".parse::<u32>();assert!(nope.is_err());

Checks if all characters in this string are within the ASCII range.

An empty string returnstrue.

§Examples

letascii ="hello!\n";letnon_ascii ="Grüße, Jürgen ❤";assert!(ascii.is_ascii());assert!(!non_ascii.is_ascii());

If this string sliceis_ascii, returns it as a sliceofASCII characters, otherwise returnsNone.

Converts this string slice into a slice ofASCII characters,without checking whether they are valid.

§Safety

Every character in this string must be ASCII, or else this is UB.

Checks that two strings are an ASCII case-insensitive match.

Same asto_ascii_lowercase(a) == to_ascii_lowercase(b),but without allocating and copying temporaries.

§Examples

assert!("Ferris".eq_ignore_ascii_case("FERRIS"));assert!("Ferrös".eq_ignore_ascii_case("FERRöS"));assert!(!"Ferrös".eq_ignore_ascii_case("FERRÖS"));

Converts this string to its ASCII upper case equivalent in-place.

ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’,but non-ASCII letters are unchanged.

To return a new uppercased value without modifying the existing one, useto_ascii_uppercase().

§Examples

letmuts = String::from("Grüße, Jürgen ❤");s.make_ascii_uppercase();assert_eq!("GRüßE, JüRGEN ❤", s);

Converts this string to its ASCII lower case equivalent in-place.

ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’,but non-ASCII letters are unchanged.

To return a new lowercased value without modifying the existing one, useto_ascii_lowercase().

§Examples

letmuts = String::from("GRÜßE, JÜRGEN ❤");s.make_ascii_lowercase();assert_eq!("grÜße, jÜrgen ❤", s);

Returns a string slice with leading ASCII whitespace removed.

‘Whitespace’ refers to the definition used byu8::is_ascii_whitespace.

§Examples

assert_eq!(" \t \u{3000}hello world\n".trim_ascii_start(),"\u{3000}hello world\n");assert_eq!("  ".trim_ascii_start(),"");assert_eq!("".trim_ascii_start(),"");

Returns a string slice with trailing ASCII whitespace removed.

‘Whitespace’ refers to the definition used byu8::is_ascii_whitespace.

§Examples

assert_eq!("\r hello world\u{3000}\n ".trim_ascii_end(),"\r hello world\u{3000}");assert_eq!("  ".trim_ascii_end(),"");assert_eq!("".trim_ascii_end(),"");

Returns a string slice with leading and trailing ASCII whitespaceremoved.

‘Whitespace’ refers to the definition used byu8::is_ascii_whitespace.

§Examples

assert_eq!("\r hello world\n ".trim_ascii(),"hello world");assert_eq!("  ".trim_ascii(),"");assert_eq!("".trim_ascii(),"");

Returns an iterator that escapes each char inself withchar::escape_debug.

Note: only extended grapheme codepoints that begin the string will beescaped.

§Examples

As an iterator:

forcin"❤\n!".escape_debug() {print!("{c}");}println!();

Usingprintln! directly:

println!("{}","❤\n!".escape_debug());

Both are equivalent to:

println!("❤\\n!");

Usingto_string:

assert_eq!("❤\n!".escape_debug().to_string(),"❤\\n!");

Returns an iterator that escapes each char inself withchar::escape_default.

§Examples

As an iterator:

forcin"❤\n!".escape_default() {print!("{c}");}println!();

Usingprintln! directly:

println!("{}","❤\n!".escape_default());

Both are equivalent to:

println!("\\u{{2764}}\\n!");

Usingto_string:

assert_eq!("❤\n!".escape_default().to_string(),"\\u{2764}\\n!");

Returns an iterator that escapes each char inself withchar::escape_unicode.

§Examples

As an iterator:

forcin"❤\n!".escape_unicode() {print!("{c}");}println!();

Usingprintln! directly:

println!("{}","❤\n!".escape_unicode());

Both are equivalent to:

println!("\\u{{2764}}\\u{{a}}\\u{{21}}");

Usingto_string:

assert_eq!("❤\n!".escape_unicode().to_string(),"\\u{2764}\\u{a}\\u{21}");

Returns the range that a substring points to.

ReturnsNone ifsubstr does not point withinself.

Unlikestr::find,this does not search through the string.Instead, it uses pointer arithmetic to find where in the stringsubstr is derived from.

This is useful for extendingstr::split and similar methods.

Note that this method may return false positives (typically eitherSome(0..0) orSome(self.len()..self.len())) ifsubstr is azero-lengthstr that points at the beginning or end of another,independent,str.

§Examples

#![feature(substr_range)]letdata ="a, b, b, a";letmutiter = data.split(", ").map(|s| data.substr_range(s).unwrap());assert_eq!(iter.next(),Some(0..1));assert_eq!(iter.next(),Some(3..4));assert_eq!(iter.next(),Some(6..7));assert_eq!(iter.next(),Some(9..10));

Returns the same string as a string slice&str.

This method is redundant when used directly on&str, butit helps dereferencing other string-like types to string slices,for example references toBox<str> orArc<str>.

Converts aBox<str> into aBox<[u8]> without copying or allocating.

§Examples

lets ="this is a string";letboxed_str = s.to_owned().into_boxed_str();letboxed_bytes = boxed_str.into_boxed_bytes();assert_eq!(*boxed_bytes,*s.as_bytes());

Replaces all matches of a pattern with another string.

replace creates a newString, and copies the data from this string slice into it.While doing so, it attempts to find matches of a pattern. If it finds any, itreplaces them with the replacement string slice.

§Examples

lets ="this is old";assert_eq!("this is new", s.replace("old","new"));assert_eq!("than an old", s.replace("is","an"));

When the pattern doesn’t match, it returns this string slice asString:

lets ="this is old";assert_eq!(s, s.replace("cookie monster","little lamb"));

Replaces first N matches of a pattern with another string.

replacen creates a newString, and copies the data from this string slice into it.While doing so, it attempts to find matches of a pattern. If it finds any, itreplaces them with the replacement string slice at mostcount times.

§Examples

lets ="foo foo 123 foo";assert_eq!("new new 123 foo", s.replacen("foo","new",2));assert_eq!("faa fao 123 foo", s.replacen('o',"a",3));assert_eq!("foo foo new23 foo", s.replacen(char::is_numeric,"new",1));

When the pattern doesn’t match, it returns this string slice asString:

lets ="this is old";assert_eq!(s, s.replacen("cookie monster","little lamb",10));

Returns the lowercase equivalent of this string slice, as a newString.

‘Lowercase’ is defined according to the terms of the Unicode Derived Core PropertyLowercase.

Since some characters can expand into multiple characters when changingthe case, this function returns aString instead of modifying theparameter in-place.

§Examples

Basic usage:

lets ="HELLO";assert_eq!("hello", s.to_lowercase());

A tricky example, with sigma:

letsigma ="Σ";assert_eq!("σ", sigma.to_lowercase());// but at the end of a word, it's ς, not σ:letodysseus ="ὈΔΥΣΣΕΎΣ";assert_eq!("ὀδυσσεύς", odysseus.to_lowercase());

Languages without case are not changed:

letnew_year ="农历新年";assert_eq!(new_year, new_year.to_lowercase());

Returns the uppercase equivalent of this string slice, as a newString.

‘Uppercase’ is defined according to the terms of the Unicode Derived Core PropertyUppercase.

Since some characters can expand into multiple characters when changingthe case, this function returns aString instead of modifying theparameter in-place.

§Examples

Basic usage:

lets ="hello";assert_eq!("HELLO", s.to_uppercase());

Scripts without case are not changed:

letnew_year ="农历新年";assert_eq!(new_year, new_year.to_uppercase());

One character can become multiple:

lets ="tschüß";assert_eq!("TSCHÜSS", s.to_uppercase());

Converts aBox<str> into aString without copying or allocating.

§Examples

letstring = String::from("birthday gift");letboxed_str = string.clone().into_boxed_str();assert_eq!(boxed_str.into_string(), string);

Creates a newString by repeating a stringn times.

§Panics

This function will panic if the capacity would overflow.

§Examples

Basic usage:

assert_eq!("abc".repeat(4), String::from("abcabcabcabc"));

A panic upon overflow:

// this will panic at runtimelethuge ="0123456789abcdef".repeat(usize::MAX);

Returns a copy of this string where each character is mapped to itsASCII upper case equivalent.

ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’,but non-ASCII letters are unchanged.

To uppercase the value in-place, usemake_ascii_uppercase.

To uppercase ASCII characters in addition to non-ASCII characters, useto_uppercase.

§Examples

lets ="Grüße, Jürgen ❤";assert_eq!("GRüßE, JüRGEN ❤", s.to_ascii_uppercase());

Returns a copy of this string where each character is mapped to itsASCII lower case equivalent.

ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’,but non-ASCII letters are unchanged.

To lowercase the value in-place, usemake_ascii_lowercase.

To lowercase ASCII characters in addition to non-ASCII characters, useto_lowercase.

§Examples

lets ="Grüße, Jürgen ❤";assert_eq!("grüße, jürgen ❤", s.to_ascii_lowercase());

Creates an empty mutable str

Creates an empty str

Allocates a reference-countedstr and copiesv into it.

§Example

letmutoriginal = String::from("eggplant");letoriginal:&mutstr =&mutoriginal;letshared: Arc<str> = Arc::from(original);assert_eq!("eggplant",&shared[..]);

Converts a&mut str into aBox<str>

This conversion allocates on the heapand performs a copy ofs.

§Examples

letmutoriginal = String::from("hello");letoriginal:&mutstr =&mutoriginal;letboxed: Box<str> = Box::from(original);println!("{boxed}");

Allocates a reference-counted string slice and copiesv into it.

§Example

letmutoriginal = String::from("statue");letoriginal:&mutstr =&mutoriginal;letshared: Rc<str> = Rc::from(original);assert_eq!("statue",&shared[..]);

Converts a&mut str into aString.

The result is allocated on the heap.

Allocates a reference-countedstr and copiesv into it.

§Example

letshared: Arc<str> = Arc::from("eggplant");assert_eq!("eggplant",&shared[..]);

Converts astr into a box of dynError.

§Examples

usestd::error::Error;leta_str_error ="a str error";leta_boxed_error = Box::<dynError>::from(a_str_error);assert!(size_of::<Box<dynError>>() == size_of_val(&a_boxed_error))

Converts astr into a box of dynError +Send +Sync.

§Examples

usestd::error::Error;leta_str_error ="a str error";leta_boxed_error = Box::<dynError + Send + Sync>::from(a_str_error);assert!(    size_of::<Box<dynError + Send + Sync>>() == size_of_val(&a_boxed_error))

Converts a&str into aBox<str>

This conversion allocates on the heapand performs a copy ofs.

§Examples

letboxed: Box<str> = Box::from("hello");println!("{boxed}");

Converts a string slice into aBorrowed variant.No heap allocation is performed, and the stringis not copied.

§Example

assert_eq!(Cow::from("eggplant"), Cow::Borrowed("eggplant"));

Allocates a reference-counted string slice and copiesv into it.

§Example

letshared: Rc<str> = Rc::from("statue");assert_eq!("statue",&shared[..]);

Converts a&str into aString.

The result is allocated on the heap.

Allocates aVec<u8> and fills it with a UTF-8 string.

§Examples

assert_eq!(Vec::from("123"),vec![b'1',b'2',b'3']);

Converts aCow<'_, str> into aBox<str>

Whencow is theCow::Borrowed variant, thisconversion allocates on the heap and copies theunderlyingstr. Otherwise, it will try to reuse the ownedString’s allocation.

§Examples

usestd::borrow::Cow;letunboxed = Cow::Borrowed("hello");letboxed: Box<str> = Box::from(unboxed);println!("{boxed}");

letunboxed = Cow::Owned("hello".to_string());letboxed: Box<str> = Box::from(unboxed);println!("{boxed}");

Converts the givenString to a boxedstr slice that is owned.

§Examples

lets1: String = String::from("hello world");lets2: Box<str> = Box::from(s1);lets3: String = String::from(s2);assert_eq!("hello world", s3)

Checks whether the pattern matches at the front of the haystack.

Checks whether the pattern matches anywhere in the haystack

Removes the pattern from the front of haystack, if it matches.

Checks whether the pattern matches at the back of the haystack.

Removes the pattern from the back of haystack, if it matches.