[logo]| [ Web Proxy ] |
| Viewing: https://doc.rust-lang.org/std/string/struct.String.html#method.as_str | [Back] [Original] |
![[logo]](https://doc.rust-lang.org/std/string/../../static.files/rust-logo-9a9549ea.svg){kind=link}
pub struct String { /* private fields */ }A UTF-8encoded, growable string.
String is the most common string type. It has ownership over the contents
of the string, stored in a heap-allocated buffer (see Representation).
It is closely related to its borrowed counterpart, the primitive str.
You can create a String from a literal string with String::from:
You can append a char to a String with the push method, and
append a &str with the push_str method:
If you have a vector of UTF-8 bytes, you can create a String from it with
the from_utf8 method:
// some bytes, in a vector
let sparkle_heart = vec![240, 159, 146, 150];
// We know these bytes are valid, so we'll use `unwrap()`.
let sparkle_heart = String::from_utf8(sparkle_heart).unwrap();
assert_eq!("", sparkle_heart);Strings are always valid UTF-8. If you need a non-UTF-8 string, consider
OsString. It is similar, but without the UTF-8 constraint. Because UTF-8
is a variable width encoding, Strings are typically smaller than an array of
the same chars:
// `s` is ASCII which represents each `char` as one byte
let s = "hello";
assert_eq!(s.len(), 5);
// A `char` array with the same contents would be longer because
// every `char` is four bytes
let s = ['h', 'e', 'l', 'l', 'o'];
let size: usize = s.into_iter().map(|c| size_of_val(&c)).sum();
assert_eq!(size, 20);
// However, for non-ASCII strings, the difference will be smaller
// and sometimes they are the same
let s = "";
assert_eq!(s.len(), 20);
let s = ['', '', '', '', ''];
let size: usize = s.into_iter().map(|c| size_of_val(&c)).sum();
assert_eq!(size, 20);This raises interesting questions as to how s[i] should work.
What should i be here? Several options include byte indices and
char indices but, because of UTF-8 encoding, only byte indices
would provide constant time indexing. Getting the ith char, for
example, is available using chars:
let s = "hello";
let third_character = s.chars().nth(2);
assert_eq!(third_character, Some('l'));
let s = "";
let third_character = s.chars().nth(2);
assert_eq!(third_character, Some(''));Next, what should s[i] return? Because indexing returns a reference
to underlying data it could be &u8, &[u8], or something similar.
Since were only providing one index, &u8 makes the most sense but that
might not be what the user expects and can be explicitly achieved with
as_bytes():
// The first byte is 104 - the byte value of `'h'`
let s = "hello";
assert_eq!(s.as_bytes()[0], 104);
// or
assert_eq!(s.as_bytes()[0], b'h');
// The first byte is 240 which isn't obviously useful
let s = "";
assert_eq!(s.as_bytes()[0], 240);Due to these ambiguities/restrictions, indexing with a usize is simply
forbidden:
It is more clear, however, how &s[i..j] should work (that is,
indexing with a range). It should accept byte indices (to be constant-time)
and return a &str which is UTF-8 encoded. This is also called string slicing.
Note this will panic if the byte indices provided are not character
boundaries - see is_char_boundary for more details. See the implementations
for SliceIndex<str> for more details on string slicing. For a non-panicking
version of string slicing, see get.
The bytes and chars methods return iterators over the bytes and
codepoints of the string, respectively. To iterate over codepoints along
with byte indices, use char_indices.
String implements Deref<Target = str>, and so inherits all of strs
methods. In addition, this means that you can pass a String to a
function which takes a &str by using an ampersand (&):
This will create a &str from the String and pass it in. This
conversion is very inexpensive, and so generally, functions will accept
&strs as arguments unless they need a String for some specific
reason.
In certain cases Rust doesnt have enough information to make this
conversion, known as Deref coercion. In the following example a string
slice &'a str implements the trait TraitExample, and the function
example_func takes anything that implements the trait. In this case Rust
would need to make two implicit conversions, which Rust doesnt have the
means to do. For that reason, the following example will not compile.
trait TraitExample {}
impl<'a> TraitExample for &'a str {}
fn example_func<A: TraitExample>(example_arg: A) {}
let example_string = String::from("example_string");
example_func(&example_string);There are two options that would work instead. The first would be to
change the line example_func(&example_string); to
example_func(example_string.as_str());, using the method as_str()
to explicitly extract the string slice containing the string. The second
way changes example_func(&example_string); to
example_func(&*example_string);. In this case we are dereferencing a
String to a str, then referencing the str back to
&str. The second way is more idiomatic, however both work to do the
conversion explicitly rather than relying on the implicit conversion.
A String is made up of three components: a pointer to some bytes, a
length, and a capacity. The pointer points to the internal buffer which String
uses to store its data. The length is the number of bytes currently stored
in the buffer, and the capacity is the size of the buffer in bytes. As such,
the length will always be less than or equal to the capacity.
This buffer is always stored on the heap.
You can look at these with the as_ptr, len, and capacity
methods:
let story = String::from("Once upon a time...");
// Deconstruct the String into parts.
let (ptr, len, capacity) = story.into_raw_parts();
// story has nineteen bytes
assert_eq!(19, len);
// We can re-build a String out of ptr, len, and capacity. This is all
// unsafe because we are responsible for making sure the components are
// valid:
let s = unsafe { String::from_raw_parts(ptr, len, capacity) } ;
assert_eq!(String::from("Once upon a time..."), s);If a String has enough capacity, adding elements to it will not
re-allocate. For example, consider this program:
let mut s = String::new();
println!("{}", s.capacity());
for _ in 0..5 {
s.push_str("hello");
println!("{}", s.capacity());
}This will output the following:
0
8
16
16
32
32At first, we have no memory allocated at all, but as we append to the
string, it increases its capacity appropriately. If we instead use the
with_capacity method to allocate the correct capacity initially:
let mut s = String::with_capacity(25);
println!("{}", s.capacity());
for _ in 0..5 {
s.push_str("hello");
println!("{}", s.capacity());
}We end up with a different output:
25
25
25
25
25
25Here, theres no need to allocate more memory inside the loop.
Creates a new empty String.
Given that the String is empty, this will not allocate any initial
buffer. While that means that this initial operation is very
inexpensive, it may cause excessive allocation later when you add
data. If you have an idea of how much data the String will hold,
consider the with_capacity method to prevent excessive
re-allocation.
Creates a new empty String with at least the specified capacity.
Strings have an internal buffer to hold their data. The capacity is
the length of that buffer, and can be queried with the capacity
method. This method creates an empty String, but one with an initial
buffer that can hold at least capacity bytes. This is useful when you
may be appending a bunch of data to the String, reducing the number of
reallocations it needs to do.
If the given capacity is 0, no allocation will occur, and this method
is identical to the new method.
Panics if the capacity exceeds isize::MAX bytes.
let mut s = String::with_capacity(10);
// The String contains no chars, even though it has capacity for more
assert_eq!(s.len(), 0);
// These are all done without reallocating...
let cap = s.capacity();
for _ in 0..10 {
s.push('a');
}
assert_eq!(s.capacity(), cap);
// ...but this may make the string reallocate
s.push('a');try_with_capacity #91913)Creates a new empty String with at least the specified capacity.
Returns Err if the capacity exceeds isize::MAX bytes,
or if the memory allocator reports failure.
Converts a vector of bytes to a String.
A string (String) is made of bytes (u8), and a vector of bytes
(Vec<u8>) is made of bytes, so this function converts between the
two. Not all byte slices are valid Strings, however: String
requires that it is valid UTF-8. from_utf8() checks to ensure that
the bytes are valid UTF-8, and then does the conversion.
If you are sure that the byte slice is valid UTF-8, and you dont want
to incur the overhead of the validity check, there is an unsafe version
of this function, from_utf8_unchecked, which has the same behavior
but skips the check.
This method will take care to not copy the vector, for efficiencys sake.
If you need a &str instead of a String, consider
str::from_utf8.
The inverse of this method is into_bytes.
Returns Err if the slice is not UTF-8 with a description as to why the
provided bytes are not UTF-8. The vector you moved in is also included.
Basic usage:
// some bytes, in a vector
let sparkle_heart = vec![240, 159, 146, 150];
// We know these bytes are valid, so we'll use `unwrap()`.
let sparkle_heart = String::from_utf8(sparkle_heart).unwrap();
assert_eq!("", sparkle_heart);Incorrect bytes:
// some invalid bytes, in a vector
let sparkle_heart = vec![0, 159, 146, 150];
assert!(String::from_utf8(sparkle_heart).is_err());See the docs for FromUtf8Error for more details on what you can do
with this error.
Converts a slice of bytes to a string, including invalid characters.
Strings are made of bytes (u8), and a slice of bytes
(&[u8]) is made of bytes, so this function converts
between the two. Not all byte slices are valid strings, however: strings
are required to be valid UTF-8. During this conversion,
from_utf8_lossy() will replace any invalid UTF-8 sequences with
U+FFFD REPLACEMENT CHARACTER, which looks like this:
If you are sure that the byte slice is valid UTF-8, and you dont want
to incur the overhead of the conversion, there is an unsafe version
of this function, from_utf8_unchecked, which has the same behavior
but skips the checks.
This function returns a Cow<'a, str>. If our byte slice is invalid
UTF-8, then we need to insert the replacement characters, which will
change the size of the string, and hence, require a String. But if
its already valid UTF-8, we dont need a new allocation. This return
type allows us to handle both cases.
Basic usage:
// some bytes, in a vector
let sparkle_heart = vec![240, 159, 146, 150];
let sparkle_heart = String::from_utf8_lossy(&sparkle_heart);
assert_eq!("", sparkle_heart);Incorrect bytes:
string_from_utf8_lossy_owned #129436)Converts a Vec<u8> to a String, substituting invalid UTF-8
sequences with replacement characters.
See from_utf8_lossy for more details.
Note that this function does not guarantee reuse of the original Vec
allocation.
Basic usage:
#![feature(string_from_utf8_lossy_owned)]
// some bytes, in a vector
let sparkle_heart = vec![240, 159, 146, 150];
let sparkle_heart = String::from_utf8_lossy_owned(sparkle_heart);
assert_eq!(String::from(""), sparkle_heart);Incorrect bytes:
Decode a native endian UTF-16encoded vector v into a String,
returning Err if v contains any invalid data.
Decode a native endian UTF-16encoded slice v into a String,
replacing invalid data with the replacement character (U+FFFD).
Unlike from_utf8_lossy which returns a Cow<'a, str>,
from_utf16_lossy returns a String since the UTF-16 to UTF-8
conversion requires a memory allocation.
Decode a UTF-16LEencoded vector v into a String,
returning Err if v contains any invalid data.
Basic usage:
// music
let v = &[0x34, 0xD8, 0x1E, 0xDD, 0x6d, 0x00, 0x75, 0x00,
0x73, 0x00, 0x69, 0x00, 0x63, 0x00];
assert_eq!(String::from("music"),
String::from_utf16le(v).unwrap());
// mu<invalid>ic
let v = &[0x34, 0xD8, 0x1E, 0xDD, 0x6d, 0x00, 0x75, 0x00,
0x00, 0xD8, 0x69, 0x00, 0x63, 0x00];
assert!(String::from_utf16le(v).is_err());Decode a UTF-16LEencoded slice v into a String, replacing
invalid data with the replacement character (U+FFFD).
Unlike from_utf8_lossy which returns a Cow<'a, str>,
from_utf16le_lossy returns a String since the UTF-16 to UTF-8
conversion requires a memory allocation.
Basic usage:
Decode a UTF-16BEencoded vector v into a String,
returning Err if v contains any invalid data.
Basic usage:
// music
let v = &[0xD8, 0x34, 0xDD, 0x1E, 0x00, 0x6d, 0x00, 0x75,
0x00, 0x73, 0x00, 0x69, 0x00, 0x63];
assert_eq!(String::from("music"),
String::from_utf16be(v).unwrap());
// mu<invalid>ic
let v = &[0xD8, 0x34, 0xDD, 0x1E, 0x00, 0x6d, 0x00, 0x75,
0xD8, 0x00, 0x00, 0x69, 0x00, 0x63];
assert!(String::from_utf16be(v).is_err());Decode a UTF-16BEencoded slice v into a String, replacing
invalid data with the replacement character (U+FFFD).
Unlike from_utf8_lossy which returns a Cow<'a, str>,
from_utf16le_lossy returns a String since the UTF-16 to UTF-8
conversion requires a memory allocation.
Basic usage:
Decomposes a String into its raw components: (pointer, length, capacity).
Returns the raw pointer to the underlying data, the length of
the string (in bytes), and the allocated capacity of the data
(in bytes). These are the same arguments in the same order as
the arguments to from_raw_parts.
After calling this function, the caller is responsible for the
memory previously managed by the String. The only way to do
this is to convert the raw pointer, length, and capacity back
into a String with the from_raw_parts function, allowing
the destructor to perform the cleanup.
Creates a new String from a pointer, a length and a capacity.
This is highly unsafe, due to the number of invariants that arent checked:
Vec::<u8>::from_raw_parts.String::from_utf8_unchecked.Violating these may cause problems like corrupting the allocators
internal data structures. For example, it is normally not safe to
build a String from a pointer to a C char array containing UTF-8
unless you are certain that array was originally allocated by the
Rust standard librarys allocator.
The ownership of buf is effectively transferred to the
String which may then deallocate, reallocate or change the
contents of memory pointed to by the pointer at will. Ensure
that nothing else uses the pointer after calling this
function.
Converts a vector of bytes to a String without checking that the
string contains valid UTF-8.
See the safe version, from_utf8, for more details.
This function is unsafe because it does not check that the bytes passed
to it are valid UTF-8. If this constraint is violated, it may cause
memory unsafety issues with future users of the String, as the rest of
the standard library assumes that Strings are valid UTF-8.
Converts a String into a byte vector.
This consumes the String, so we do not need to copy its contents.
Appends a given string slice onto the end of this String.
Panics if the new capacity exceeds isize::MAX bytes.
Copies elements from src range to the end of the string.
Panics if the range has start_bound > end_bound, if the range is
bounded on either end and does not lie on a char boundary, or if the
new capacity exceeds isize::MAX bytes.
Reserves capacity for at least additional bytes more than the
current length. The allocator may reserve more space to speculatively
avoid frequent allocations. After calling reserve,
capacity will be greater than or equal to self.len() + additional.
Does nothing if capacity is already sufficient.
Panics if the new capacity exceeds isize::MAX bytes.
Basic usage:
This might not actually increase the capacity:
let mut s = String::with_capacity(10);
s.push('a');
s.push('b');
// s now has a length of 2 and a capacity of at least 10
let capacity = s.capacity();
assert_eq!(2, s.len());
assert!(capacity >= 10);
// Since we already have at least an extra 8 capacity, calling this...
s.reserve(8);
// ... doesn't actually increase.
assert_eq!(capacity, s.capacity());Reserves the minimum capacity for at least additional bytes more than
the current length. Unlike reserve, this will not
deliberately over-allocate to speculatively avoid frequent allocations.
After calling reserve_exact, capacity will be greater than or equal to
self.len() + additional. Does nothing if the capacity is already
sufficient.
Panics if the new capacity exceeds isize::MAX bytes.
Basic usage:
This might not actually increase the capacity:
let mut s = String::with_capacity(10);
s.push('a');
s.push('b');
// s now has a length of 2 and a capacity of at least 10
let capacity = s.capacity();
assert_eq!(2, s.len());
assert!(capacity >= 10);
// Since we already have at least an extra 8 capacity, calling this...
s.reserve_exact(8);
// ... doesn't actually increase.
assert_eq!(capacity, s.capacity());Tries to reserve capacity for at least additional bytes more than the
current length. The allocator may reserve more space to speculatively
avoid frequent allocations. After calling try_reserve, capacity will be
greater than or equal to self.len() + additional if it returns
Ok(()). Does nothing if capacity is already sufficient. This method
preserves the contents even if an error occurs.
If the capacity overflows, or the allocator reports a failure, then an error is returned.
use std::collections::TryReserveError;
fn process_data(data: &str) -> Result<String, TryReserveError> {
let mut output = String::new();
// Pre-reserve the memory, exiting if we can't
output.try_reserve(data.len())?;
// Now we know this can't OOM in the middle of our complex work
output.push_str(data);
Ok(output)
}Tries to reserve the minimum capacity for at least additional bytes
more than the current length. Unlike try_reserve, this will not
deliberately over-allocate to speculatively avoid frequent allocations.
After calling try_reserve_exact, capacity will be greater than or
equal to self.len() + additional if it returns Ok(()).
Does nothing if the capacity is already sufficient.
Note that the allocator may give the collection more space than it
requests. Therefore, capacity can not be relied upon to be precisely
minimal. Prefer try_reserve if future insertions are expected.
If the capacity overflows, or the allocator reports a failure, then an error is returned.
use std::collections::TryReserveError;
fn process_data(data: &str) -> Result<String, TryReserveError> {
let mut output = String::new();
// Pre-reserve the memory, exiting if we can't
output.try_reserve_exact(data.len())?;
// Now we know this can't OOM in the middle of our complex work
output.push_str(data);
Ok(output)
}Shrinks the capacity of this String with a lower bound.
The capacity will remain at least as large as both the length and the supplied value.
If the current capacity is less than the lower limit, this is a no-op.
Appends the given char to the end of this String.
Panics if the new capacity exceeds isize::MAX bytes.
Shortens this String to the specified length.
If new_len is greater than or equal to the strings current length, this has no
effect.
Note that this method has no effect on the allocated capacity of the string
Panics if new_len does not lie on a char boundary.
Removes the last character from the string buffer and returns it.
Returns None if this String is empty.
Removes a char from this String at byte position idx and returns it.
Copies all bytes after the removed char to new positions.
Note that calling this in a loop can result in quadratic behavior.
Panics if idx is larger than or equal to the Strings length,
or if it does not lie on a char boundary.
string_remove_matches #72826)Remove all matches of pattern pat in the String.
#![feature(string_remove_matches)]
let mut s = String::from("Trees are not green, the sky is not blue.");
s.remove_matches("not ");
assert_eq!("Trees are green, the sky is blue.", s);Matches will be detected and removed iteratively, so in cases where patterns overlap, only the first pattern will be removed:
Retains only the characters specified by the predicate.
In other words, remove all characters c such that f(c) returns false.
This method operates in place, visiting each character exactly once in the
original order, and preserves the order of the retained characters.
Because the elements are visited exactly once in the original order, external state may be used to decide which elements to keep.
Inserts a character into this String at byte position idx.
Reallocates if self.capacity() is insufficient, which may involve copying all
self.capacity() bytes. Makes space for the insertion by copying all bytes of
&self[idx..] to new positions.
Note that calling this in a loop can result in quadratic behavior.
Panics if idx is larger than the Strings length, or if it does not
lie on a char boundary.
Inserts a string slice into this String at byte position idx.
Reallocates if self.capacity() is insufficient, which may involve copying all
self.capacity() bytes. Makes space for the insertion by copying all bytes of
&self[idx..] to new positions.
Note that calling this in a loop can result in quadratic behavior.
Panics if idx is larger than the Strings length, or if it does not
lie on a char boundary.
Returns a mutable reference to the contents of this String.
This function is unsafe because the returned &mut Vec allows writing
bytes which are not valid UTF-8. If this constraint is violated, using
the original String after dropping the &mut Vec may violate memory
safety, as the rest of the standard library assumes that Strings are
valid UTF-8.
Returns the length of this String, in bytes, not chars or
graphemes. In other words, it might not be what a human considers the
length of the string.
Splits the string into two at the given byte index.
Returns a newly allocated String. self contains bytes [0, at), and
the returned String contains bytes [at, len). at must be on the
boundary of a UTF-8 code point.
Note that the capacity of self does not change.
Panics if at is not on a UTF-8 code point boundary, or if it is beyond the last
code point of the string.
Truncates this String, removing all contents.
While this means the String will have a length of zero, it does not
touch its capacity.
Removes the specified range from the string in bulk, returning all removed characters as an iterator.
The returned iterator keeps a mutable borrow on the string to optimize its implementation.
Panics if the range has start_bound > end_bound, or, if the range is
bounded on either end and does not lie on a char boundary.
If the returned iterator goes out of scope without being dropped (due to
core::mem::forget, for example), the string may still contain a copy
of any drained characters, or may have lost characters arbitrarily,
including characters outside the range.
let mut s = String::from(" is alpha, is beta");
let beta_offset = s.find('').unwrap_or(s.len());
// Remove the range up until the from the string
let t: String = s.drain(..beta_offset).collect();
assert_eq!(t, " is alpha, ");
assert_eq!(s, " is beta");
// A full range clears the string, like `clear()` does
s.drain(..);
assert_eq!(s, "");string_into_chars #133125)Converts a String into an iterator over the chars of the string.
As a string consists of valid UTF-8, we can iterate through a string
by char. This method returns such an iterator.
Its important to remember that char represents a Unicode Scalar
Value, and might not match your idea of what a character is. Iteration
over grapheme clusters may be what you actually want. That functionality
is not provided by Rusts standard library, check crates.io instead.
Basic usage:
#![feature(string_into_chars)]
let word = String::from("goodbye");
let mut chars = word.into_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:
Removes the specified range in the string, and replaces it with the given string. The given string doesnt need to be the same length as the range.
Panics if the range has start_bound > end_bound, or, if the range is
bounded on either end and does not lie on a char boundary.
string_replace_in_place #147949)Replaces the leftmost occurrence of a pattern with another string, in-place.
This method can be preferred over string = string.replacen(..., 1);,
as it can use the Strings existing capacity to prevent a reallocation if
sufficient space is available.
Basic usage:
string_replace_in_place #147949)Converts this String into a Box<str>.
Before doing the conversion, this method discards excess capacity like shrink_to_fit.
Note that this call may reallocate and copy the bytes of the string.
Consumes and leaks the String, returning a mutable reference to the contents,
&'a mut str.
The caller has free choice over the returned lifetime, including 'static. Indeed,
this function is ideally used for data that lives for the remainder of the programs life,
as dropping the returned reference will cause a memory leak.
It does not reallocate or shrink the String, so the leaked allocation may include unused
capacity that is not part of the returned slice. If you want to discard excess capacity,
call into_boxed_str, and then Box::leak instead. However, keep in mind that
trimming the capacity may result in a reallocation and copy.
Returns the length of self.
This length is in bytes, not chars or graphemes. In other words,
it might not be what a human considers the length of the string.
Checks that index-th byte is the first byte in a UTF-8 code point
sequence or the end of the string.
The start and end of the string (when index == self.len()) are
considered to be boundaries.
Returns false if index is greater than self.len().
Finds the closest x not exceeding index where is_char_boundary(x) is true.
This method can help you truncate a string so that its still valid UTF-8, but doesnt exceed a given number of bytes. Note that this is done purely at the character level and can still visually split graphemes, even though the underlying characters arent split. For example, the emoji (scientist) could be split so that the string only includes (person) instead.
Finds the closest x not below index where is_char_boundary(x) is true.
If index is greater than the length of the string, this returns the length of the string.
This method is the natural complement to floor_char_boundary. See that method
for more details.
Converts a string slice to a byte slice. To convert the byte slice back
into a string slice, use the from_utf8 function.
Converts a mutable string slice to a mutable byte slice.
The caller must ensure that the content of the slice is valid UTF-8
before the borrow ends and the underlying str is used.
Use of a str whose contents are not valid UTF-8 is undefined behavior.
Basic usage:
let mut s = String::from("Hello");
let bytes = unsafe { s.as_bytes_mut() };
assert_eq!(b"Hello", bytes);Mutability:
Converts a string slice to a raw pointer.
As string slices are a slice of bytes, the raw pointer points to a
u8. This pointer will be pointing to the first byte of the string
slice.
The caller must ensure that the returned pointer is never written to.
If you need to mutate the contents of the string slice, use as_mut_ptr.
Converts a mutable string slice to a raw pointer.
As string slices are a slice of bytes, the raw pointer points to a
u8. This pointer will be pointing to the first byte of the string
slice.
It is your responsibility to make sure that the string slice only gets modified in a way that it remains valid UTF-8.
Returns a subslice of str.
This is the non-panicking alternative to indexing the str. Returns
None whenever equivalent indexing operation would panic.
Returns a mutable subslice of str.
This is the non-panicking alternative to indexing the str. Returns
None whenever equivalent indexing operation would panic.
let mut v = String::from("hello");
// correct length
assert!(v.get_mut(0..5).is_some());
// out of bounds
assert!(v.get_mut(..42).is_none());
assert_eq!(Some("he"), v.get_mut(0..2).map(|v| &*v));
assert_eq!("hello", v);
{
let s = v.get_mut(0..2);
let s = s.map(|s| {
s.make_ascii_uppercase();
&*s
});
assert_eq!(Some("HE"), s);
}
assert_eq!("HEllo", v);Returns an unchecked subslice of str.
This is the unchecked alternative to indexing the str.
Callers of this function are responsible that these preconditions are satisfied:
Failing that, the returned string slice may reference invalid memory or
violate the invariants communicated by the str type.
Returns a mutable, unchecked subslice of str.
This is the unchecked alternative to indexing the str.
Callers of this function are responsible that these preconditions are satisfied:
Failing that, the returned string slice may reference invalid memory or
violate the invariants communicated by the str type.
use get_unchecked(begin..end) instead
Creates a string slice from another string slice, bypassing safety checks.
This is generally not recommended, use with caution! For a safe
alternative see str and Index.
This new slice goes from begin to end, including begin but
excluding end.
To get a mutable string slice instead, see the
slice_mut_unchecked method.
Callers of this function are responsible that three preconditions are satisfied:
begin must not exceed end.begin and end must be byte positions within the string slice.begin and end must lie on UTF-8 sequence boundaries.use get_unchecked_mut(begin..end) instead
Creates a string slice from another string slice, bypassing safety checks.
This is generally not recommended, use with caution! For a safe
alternative see str and IndexMut.
This new slice goes from begin to end, including begin but
excluding end.
To get an immutable string slice instead, see the
slice_unchecked method.
Callers of this function are responsible that three preconditions are satisfied:
begin must not exceed end.begin and end must be byte positions within the string slice.begin and end 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 the
string. 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 to mid,
and from mid to the end of the string slice.
To get mutable string slices instead, see the split_at_mut
method.
Panics if mid is not on a UTF-8 code point boundary, or if it is past
the end of the last code point of the string slice. For a non-panicking
alternative see split_at_checked.
Divides one mutable string slice into two at an index.
The argument, mid, should be a byte offset from the start of the
string. 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 to mid,
and from mid to the end of the string slice.
To get immutable string slices instead, see the split_at method.
Panics if mid is not on a UTF-8 code point boundary, or if it is past
the end of the last code point of the string slice. For a non-panicking
alternative see split_at_mut_checked.
Divides one string slice into two at an index.
The argument, mid, should be a valid byte offset from the start of the
string. It must also be on the boundary of a UTF-8 code point. The
method returns None if thats not the case.
The two slices returned go from the start of the string slice to mid,
and from mid to the end of the string slice.
To get mutable string slices instead, see the split_at_mut_checked
method.
Divides one mutable string slice into two at an index.
The argument, mid, should be a valid byte offset from the start of the
string. It must also be on the boundary of a UTF-8 code point. The
method returns None if thats not the case.
The two slices returned go from the start of the string slice to mid,
and from mid to the end of the string slice.
To get immutable string slices instead, see the split_at_checked method.
let mut s = "Per Martin-Lf".to_string();
if let Some((first, last)) = s.split_at_mut_checked(3) {
first.make_ascii_uppercase();
assert_eq!("PER", first);
assert_eq!(" Martin-Lf", last);
}
assert_eq!("PER Martin-Lf", s);
assert_eq!(None, s.split_at_mut_checked(13)); // Inside
assert_eq!(None, s.split_at_mut_checked(16)); // Beyond the string lengthReturns an iterator over the chars of a string slice.
As a string slice consists of valid UTF-8, we can iterate through a
string slice by char. This method returns such an iterator.
Its important to remember that char represents a Unicode Scalar
Value, and might not match your idea of what a character is. Iteration
over grapheme clusters may be what you actually want. This functionality
is not provided by Rusts standard library, check crates.io instead.
Basic usage:
let word = "goodbye";
let count = word.chars().count();
assert_eq!(7, count);
let mut chars = 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:
Returns an iterator over the chars of a string slice, and their
positions.
As a string slice consists of valid UTF-8, we can iterate through a
string slice by char. This method returns an iterator of both
these chars, as well as their byte positions.
The iterator yields tuples. The position is first, the char is
second.
Basic usage:
let word = "goodbye";
let count = word.char_indices().count();
assert_eq!(7, count);
let mut char_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:
let yes = "yes";
let mut char_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 bytes
assert_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 iterate through a string slice by byte. This method returns such an iterator.
Splits a string slice by whitespace.
The iterator returned will return string slices that are sub-slices of the original string slice, separated by any amount of whitespace.
Whitespace is defined according to the terms of the Unicode Derived
Core Property White_Space. If you only want to split on ASCII whitespace
instead, use split_ascii_whitespace.
Basic usage:
let mut iter = "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:
let mut iter = " 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:
Splits a string slice by ASCII whitespace.
The iterator returned will return string slices that are sub-slices of the original string slice, separated by any amount of ASCII whitespace.
This uses the same definition as char::is_ascii_whitespace.
To split by Unicode Whitespace instead, use split_whitespace.
Note that because of this difference in definition, even if s.is_ascii()
is true, s.split_ascii_whitespace() behavior will differ from s.split_whitespace()
if s contains U+000B VERTICAL TAB.
Basic usage:
let mut iter = "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
(see char::is_ascii_whitespace):
let mut iter = " 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:
Returns an iterator over the lines of a string, as string slices.
Lines are split at line endings that are either newlines (\n) or
sequences 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 a
line feed (\n) does not split a line. These carriage returns are
thereby included in the produced lines.
The final line ending is optional. A string that ends with a final line ending will return the same lines as an otherwise identical string without a final line ending.
An empty string returns an empty iterator.
Basic usage:
let text = "foo\r\nbar\n\nbaz\r";
let mut lines = 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 line
assert_eq!(Some("baz\r"), lines.next());
assert_eq!(None, lines.next());The final line does not require any ending:
let text = "foo\nbar\n\r\nbaz";
let mut lines = 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:
use lines() instead now
Returns an iterator over the lines of a string.
Returns an iterator of u16 over the string encoded
as native endian UTF-16 (without byte-order mark).
Returns true if the given pattern matches a sub-slice of
this string slice.
Returns false if it does not.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
Returns true if the given pattern matches a prefix of this
string slice.
Returns false if it does not.
The pattern can be a &str, in which case this function will return true if
the &str is a prefix of this string slice.
The pattern can also be a char, a slice of chars, or a
function 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 of chars.
Returns true if the given pattern matches a suffix of this
string slice.
Returns false if it does not.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
Returns the byte index of the first character of this string slice that matches the pattern.
Returns None if the pattern doesnt match.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
Simple patterns:
let s = "Lwe Lopard 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:
let s = "Lwe Lopard";
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:
Returns the byte index for the first character of the last match of the pattern in this string slice.
Returns None if the pattern doesnt match.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
Simple patterns:
let s = "Lwe Lopard 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:
let s = "Lwe Lopard";
assert_eq!(s.rfind(char::is_whitespace), Some(12));
assert_eq!(s.rfind(char::is_lowercase), Some(20));Not finding the pattern:
Returns an iterator over substrings of this string slice, separated by characters matched by a pattern.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
If there are no matches the full string slice is returned as the only item in the iterator.
The returned iterator will be a DoubleEndedIterator if the pattern
allows a reverse search and forward/reverse search yields the same
elements. This is true for, e.g., char, but not for &str.
If the pattern allows a reverse search but its results might differ
from a forward search, the rsplit method can be used.
Simple patterns:
let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]);
let v: Vec<&str> = "".split('X').collect();
assert_eq!(v, [""]);
let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect();
assert_eq!(v, ["lion", "", "tiger", "leopard"]);
let v: Vec<&str> = "lion::tiger::leopard".split("::").collect();
assert_eq!(v, ["lion", "tiger", "leopard"]);
let v: Vec<&str> = "AABBCC".split("DD").collect();
assert_eq!(v, ["AABBCC"]);
let v: Vec<&str> = "abc1def2ghi".split(char::is_numeric).collect();
assert_eq!(v, ["abc", "def", "ghi"]);
let v: 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:
let v: Vec<&str> = "2020-11-03 23:59".split(&['-', ' ', ':', '@'][..]).collect();
assert_eq!(v, ["2020", "11", "03", "23", "59"]);A more complex pattern, using a closure:
let v: 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 up with empty strings in the output:
let x = "||||a||b|c".to_string();
let d: Vec<_> = x.split('|').collect();
assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);Contiguous separators are separated by the empty string.
let x = "(///)".to_string();
let d: Vec<_> = x.split('/').collect();
assert_eq!(d, &["(", "", "", ")"]);Separators at the start or end of a string are neighbored by empty strings.
When the empty string is used as a separator, it separates every character in the string, along with the beginning and end of the string.
Contiguous separators can lead to possibly surprising behavior when whitespace is used as the separator. This code is correct:
let x = " a b c".to_string();
let d: Vec<_> = x.split(' ').collect();
assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]);It does not give you:
Use split_whitespace for this behavior.
Returns an iterator over substrings of this string slice, separated by characters matched by a pattern.
Differs from the iterator produced by split in that split_inclusive
leaves the matched part as the terminator of the substring.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
let v: 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.
Returns an iterator over substrings of the given string slice, separated by characters matched by a pattern and yielded in reverse order.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
The returned iterator requires that the pattern supports a reverse
search, and it will be a DoubleEndedIterator if a forward/reverse
search yields the same elements.
For iterating from the front, the split method can be used.
Simple patterns:
let v: Vec<&str> = "Mary had a little lamb".rsplit(' ').collect();
assert_eq!(v, ["lamb", "little", "a", "had", "Mary"]);
let v: Vec<&str> = "".rsplit('X').collect();
assert_eq!(v, [""]);
let v: Vec<&str> = "lionXXtigerXleopard".rsplit('X').collect();
assert_eq!(v, ["leopard", "tiger", "", "lion"]);
let v: Vec<&str> = "lion::tiger::leopard".rsplit("::").collect();
assert_eq!(v, ["leopard", "tiger", "lion"]);A more complex pattern, using a closure:
Returns an iterator over substrings of the given string slice, separated by characters matched by a pattern.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
Equivalent to split, except that the trailing substring
is skipped if empty.
This method can be used for string data that is terminated, rather than separated by a pattern.
The returned iterator will be a DoubleEndedIterator if the pattern
allows a reverse search and forward/reverse search yields the same
elements. This is true for, e.g., char, but not for &str.
If the pattern allows a reverse search but its results might differ
from a forward search, the rsplit_terminator method can be used.
Returns an iterator over substrings of self, separated by characters
matched by a pattern and yielded in reverse order.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
Equivalent to split, except that the trailing substring is
skipped if empty.
This method can be used for string data that is terminated, rather than separated by a pattern.
The returned iterator requires that the pattern supports a reverse search, and it will be double ended if a forward/reverse search yields the same elements.
For iterating from the front, the split_terminator method can be
used.
Returns an iterator over substrings of the given string slice, separated
by a pattern, restricted to returning at most n items.
If n substrings are returned, the last substring (the nth substring)
will contain the remainder of the string.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
The returned iterator will not be double ended, because it is not efficient to support.
If the pattern allows a reverse search, the rsplitn method can be
used.
Simple patterns:
let v: Vec<&str> = "Mary had a little lambda".splitn(3, ' ').collect();
assert_eq!(v, ["Mary", "had", "a little lambda"]);
let v: Vec<&str> = "lionXXtigerXleopard".splitn(3, "X").collect();
assert_eq!(v, ["lion", "", "tigerXleopard"]);
let v: Vec<&str> = "abcXdef".splitn(1, 'X').collect();
assert_eq!(v, ["abcXdef"]);
let v: Vec<&str> = "".splitn(1, 'X').collect();
assert_eq!(v, [""]);A more complex pattern, using a closure:
Returns an iterator over substrings of this string slice, separated by a
pattern, starting from the end of the string, restricted to returning at
most n items.
If n substrings are returned, the last substring (the nth substring)
will contain the remainder of the string.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
The returned iterator will not be double ended, because it is not efficient to support.
For splitting from the front, the splitn method can be used.
Simple patterns:
let v: Vec<&str> = "Mary had a little lamb".rsplitn(3, ' ').collect();
assert_eq!(v, ["lamb", "little", "Mary had a"]);
let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(3, 'X').collect();
assert_eq!(v, ["leopard", "tiger", "lionX"]);
let v: Vec<&str> = "lion::tiger::leopard".rsplitn(2, "::").collect();
assert_eq!(v, ["leopard", "lion::tiger"]);A more complex pattern, using a closure:
Splits the string on the first occurrence of the specified delimiter and returns prefix before delimiter and suffix after delimiter.
Splits the string on the last occurrence of the specified delimiter and returns prefix before delimiter and suffix after delimiter.
Returns an iterator over the disjoint matches of a pattern within the given string slice.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
The returned iterator will be a DoubleEndedIterator if the pattern
allows a reverse search and forward/reverse search yields the same
elements. This is true for, e.g., char, but not for &str.
If the pattern allows a reverse search but its results might differ
from a forward search, the rmatches method can be used.
Returns an iterator over the disjoint matches of a pattern within this string slice, yielded in reverse order.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
The returned iterator requires that the pattern supports a reverse
search, and it will be a DoubleEndedIterator if a forward/reverse
search yields the same elements.
For iterating from the front, the matches method can be used.
Returns an iterator over the disjoint matches of a pattern within this string slice as well as the index that the match starts at.
For matches of pat within self that overlap, only the indices
corresponding to the first match are returned.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
The returned iterator will be a DoubleEndedIterator if the pattern
allows a reverse search and forward/reverse search yields the same
elements. This is true for, e.g., char, but not for &str.
If the pattern allows a reverse search but its results might differ
from a forward search, the rmatch_indices method can be used.
let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);
let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
assert_eq!(v, [(1, "abc"), (4, "abc")]);
let v: 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 within self,
yielded in reverse order along with the index of the match.
For matches of pat within self that overlap, only the indices
corresponding to the last match are returned.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
The returned iterator requires that the pattern supports a reverse
search, and it will be a DoubleEndedIterator if a forward/reverse
search yields the same elements.
For iterating from the front, the match_indices method can be used.
let v: Vec<_> = "abcXXXabcYYYabc".rmatch_indices("abc").collect();
assert_eq!(v, [(12, "abc"), (6, "abc"), (0, "abc")]);
let v: Vec<_> = "1abcabc2".rmatch_indices("abc").collect();
assert_eq!(v, [(4, "abc"), (1, "abc")]);
let v: 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 Derived
Core Property White_Space, which includes newlines.
Returns a string slice with leading whitespace removed.
Whitespace is defined according to the terms of the Unicode Derived
Core Property White_Space, which includes newlines.
A string is a sequence of bytes. start in this context means the first
position of that byte string; for a left-to-right language like English or
Russian, this will be left side, and for right-to-left languages like
Arabic or Hebrew, this will be the right side.
Basic usage:
Directionality:
Returns a string slice with trailing whitespace removed.
Whitespace is defined according to the terms of the Unicode Derived
Core Property White_Space, which includes newlines.
A string is a sequence of bytes. end in this context means the last
position of that byte string; for a left-to-right language like English or
Russian, this will be right side, and for right-to-left languages like
Arabic or Hebrew, this will be the left side.
Basic usage:
Directionality:
superseded by trim_start
Returns a string slice with leading whitespace removed.
Whitespace is defined according to the terms of the Unicode Derived
Core Property White_Space.
A string is a sequence of bytes. Left in this context means the first position of that byte string; for a language like Arabic or Hebrew which are right to left rather than left to right, this will be the right side, not the left.
Basic usage:
Directionality:
superseded by trim_end
Returns a string slice with trailing whitespace removed.
Whitespace is defined according to the terms of the Unicode Derived
Core Property White_Space.
A string is a sequence of bytes. Right in this context means the last position of that byte string; for a language like Arabic or Hebrew which are right to left rather than left to right, this will be the left side, not the right.
Basic usage:
Directionality:
Returns a string slice with all prefixes and suffixes that match a pattern repeatedly removed.
The pattern can be a char, a slice of chars, or a function
or closure that determines if a character matches.
Simple patterns:
assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar");
assert_eq!("123foo1bar123".trim_matches(char::is_numeric), "foo1bar");
let x: &[_] = &['1', '2'];
assert_eq!("12foo1bar12".trim_matches(x), "foo1bar");A more complex pattern, using a closure:
Returns a string slice with all prefixes that match a pattern repeatedly removed.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
A string is a sequence of bytes. start in this context means the first
position of that byte string; for a left-to-right language like English or
Russian, this will be left side, and for right-to-left languages like
Arabic or Hebrew, this will be the right side.
Returns a string slice with the prefix removed.
If the string starts with the pattern prefix, returns the substring after the prefix,
wrapped in Some. Unlike trim_start_matches, this method removes the prefix exactly once.
If the string does not start with prefix, returns None.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
Returns a string slice with the suffix removed.
If the string ends with the pattern suffix, returns the substring before the suffix,
wrapped in Some. Unlike trim_end_matches, this method removes the suffix exactly once.
If the string does not end with suffix, returns None.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
Returns a string slice with the prefix and suffix removed.
If the string starts with the pattern prefix and ends with
the pattern suffix, and the prefix and suffix dont overlap, returns
the substring after the prefix and before the suffix, wrapped in Some.
Unlike trim_start_matches and trim_end_matches, this method removes both the prefix
and suffix exactly once.
If the string does not start with prefix, does not end with suffix,
or the prefix and suffix overlap in the string, returns None.
Each pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
trim_prefix_suffix #142312)Returns a string slice with the optional prefix removed.
If the string starts with the pattern prefix, returns the substring after the prefix.
Unlike strip_prefix, this method always returns &str for easy method chaining,
instead of returning Option<&str>.
If the string does not start with prefix, returns the original string unchanged.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
#![feature(trim_prefix_suffix)]
// Prefix present - removes it
assert_eq!("foo:bar".trim_prefix("foo:"), "bar");
assert_eq!("foofoo".trim_prefix("foo"), "foo");
// Prefix absent - returns original string
assert_eq!("foo:bar".trim_prefix("bar"), "foo:bar");
// Method chaining example
assert_eq!("<https://example.com/>".trim_prefix('<').trim_suffix('>'), "https://example.com/");trim_prefix_suffix #142312)Returns a string slice with the optional suffix removed.
If the string ends with the pattern suffix, returns the substring before the suffix.
Unlike strip_suffix, this method always returns &str for easy method chaining,
instead of returning Option<&str>.
If the string does not end with suffix, returns the original string unchanged.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
#![feature(trim_prefix_suffix)]
// Suffix present - removes it
assert_eq!("bar:foo".trim_suffix(":foo"), "bar");
assert_eq!("foofoo".trim_suffix("foo"), "foo");
// Suffix absent - returns original string
assert_eq!("bar:foo".trim_suffix("bar"), "bar:foo");
// Method chaining example
assert_eq!("<https://example.com/>".trim_prefix('<').trim_suffix('>'), "https://example.com/");Returns a string slice with all suffixes that match a pattern repeatedly removed.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
A string is a sequence of bytes. end in this context means the last
position of that byte string; for a left-to-right language like English or
Russian, this will be right side, and for right-to-left languages like
Arabic or Hebrew, this will be the left side.
Simple patterns:
assert_eq!("11foo1bar11".trim_end_matches('1'), "11foo1bar");
assert_eq!("123foo1bar123".trim_end_matches(char::is_numeric), "123foo1bar");
let x: &[_] = &['1', '2'];
assert_eq!("12foo1bar12".trim_end_matches(x), "12foo1bar");A more complex pattern, using a closure:
superseded by trim_start_matches
Returns a string slice with all prefixes that match a pattern repeatedly removed.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
A string is a sequence of bytes. Left in this context means the first position of that byte string; for a language like Arabic or Hebrew which are right to left rather than left to right, this will be the right side, not the left.
superseded by trim_end_matches
Returns a string slice with all suffixes that match a pattern repeatedly removed.
The pattern can be a &str, char, a slice of chars, or a
function or closure that determines if a character matches.
A string is a sequence of bytes. Right in this context means the last position of that byte string; for a language like Arabic or Hebrew which are right to left rather than left to right, this will be the left side, not the right.
Simple patterns:
assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar");
assert_eq!("123foo1bar123".trim_right_matches(char::is_numeric), "123foo1bar");
let x: &[_] = &['1', '2'];
assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar");A more complex pattern, using a closure:
Parses this string slice into another type.
Because parse is so general, it can cause problems with type
inference. As such, parse is one of the few times youll see
the syntax affectionately known as the turbofish: ::<>. This
helps the inference algorithm understand specifically which type
youre trying to parse into.
parse can parse into any type that implements the FromStr trait.
Will return Err if its not possible to parse this string slice into
the desired type.
Basic usage:
Using the turbofish instead of annotating four:
Failing to parse:
Checks if all characters in this string are within the ASCII range.
An empty string returns true.
ascii_char #110998)If this string slice is_ascii, returns it as a slice
of ASCII characters, otherwise returns None.
ascii_char #110998)Converts this string slice into a slice of ASCII characters, without checking whether they are valid.
Every character in this string must be ASCII, or else this is UB.
Checks that two strings are an ASCII case-insensitive match.
Same as to_ascii_lowercase(a) == to_ascii_lowercase(b),
but without allocating and copying temporaries.
For Unicode-aware case-insensitive matching, consider
str::eq_ignore_case_unnormalized.
casefold #154742)Checks that two strings are a caseless match, according to Definition 144 in Chapter 3 of the Unicode Standard.
Same as a.to_casefold_unnormalized() == b.to_casefold_unnormalized(),
but without allocating. See that methods documentation,
as well as char::to_casefold_unnormalized(),
for more information about case folding.
No normalization (e.g. NFC) is performed, so visually and semantically identical strings
might still compare unequal. For example, "" (U+00C5 LATIN CAPITAL LETTER A WITH RING ABOVE)
is considered distinct from "A" (A followed by U+030A COMBINING RING ABOVE),
even though Unicode considers them canonically equivalent.
In addition, this method is independent of language/locale, so the special behavior of I///i in Turkish and Azeri is not handled.
#![feature(casefold)]
assert!("Ferris".eq_ignore_case_unnormalized("FERRIS"));
assert!("Ferrs".eq_ignore_case_unnormalized("FERRS"));
assert!("".eq_ignore_case_unnormalized("ss"));No NFC normalization is performed:
#![feature(casefold)]
// These two strings are visually and semantically identical...
let comp = "";
let decomp = "A";
// ... but not codepoint-for-codepoint equal.
assert_eq!(comp, "\u{C5}");
assert_eq!(decomp, "A\u{030A}");
// Their case-foldings are likewise unequal:
assert!(!comp.eq_ignore_case_unnormalized(decomp));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, use
to_ascii_uppercase().
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, use
to_ascii_lowercase().
Returns a string slice with leading ASCII whitespace removed.
Whitespace refers to the definition used by
u8::is_ascii_whitespace. Importantly, this definition excludes
the U+000B code point even though it has the Unicode White_Space property
and is removed by str::trim_start.
Returns a string slice with trailing ASCII whitespace removed.
Whitespace refers to the definition used by
u8::is_ascii_whitespace. Importantly, this definition excludes
the U+000B code point even though it has the Unicode White_Space property
and is removed by str::trim_end.
Returns a string slice with leading and trailing ASCII whitespace removed.
Whitespace refers to the definition used by
u8::is_ascii_whitespace. Importantly, this definition excludes
the U+000B code point even though it has the Unicode White_Space property
and is removed by str::trim.
Returns an iterator that escapes each char in self with char::escape_debug.
Note: only extended grapheme codepoints that begin the string will be escaped.
As an iterator:
Using println! directly:
Both are equivalent to:
Using to_string:
Returns an iterator that escapes each char in self with char::escape_default.
As an iterator:
Using println! directly:
Both are equivalent to:
Using to_string:
Returns an iterator that escapes each char in self with char::escape_unicode.
As an iterator:
Using println! directly:
Both are equivalent to:
Using to_string:
Returns the range that a substring points to.
Returns None if substr does not point within self.
Unlike str::find, this does not search through the string.
Instead, it uses pointer arithmetic to find where in the string
substr is derived from.
This is useful for extending str::split and similar methods.
Note that this method may return false positives (typically either
Some(0..0) or Some(self.len()..self.len())) if substr is a
zero-length str that points at the beginning or end of another,
independent, str.
use core::range::Range;
let data = "a, b, b, a";
let mut iter = data.split(", ").map(|s| data.substr_range(s).unwrap());
assert_eq!(iter.next(), Some(Range { start: 0, end: 1 }));
assert_eq!(iter.next(), Some(Range { start: 3, end: 4 }));
assert_eq!(iter.next(), Some(Range { start: 6, end: 7 }));
assert_eq!(iter.next(), Some(Range { start: 9, end: 10 }));str_as_str #130366)Returns the same string as a string slice &str.
This method is redundant when used directly on &str, but
it helps dereferencing other string-like types to string slices,
for example references to Box<str> or Arc<str>.
Replaces all matches of a pattern with another string.
replace creates a new String, 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, it
replaces them with the replacement string slice.
let s = "this is old";
assert_eq!("this is new", s.replace("old", "new"));
assert_eq!("than an old", s.replace("is", "an"));When the pattern doesnt match, it returns this string slice as String:
Replaces first N matches of a pattern with another string.
replacen creates a new String, 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, it
replaces them with the replacement string slice at most count times.
let s = "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 doesnt match, it returns this string slice as String:
Returns the lowercase equivalent of this string slice, as a new String.
Lowercase is defined according to the terms of Chapter 3 (Conformance) of the Unicode standard.
Since some characters can expand into multiple characters when changing
the case, this function returns a String instead of modifying the
parameter in-place.
Unlike char::to_lowercase(), this method fully handles the context-dependent
casing of Greek sigma. However, like that method, it does not handle locale-specific
casing, like Turkish and Azeri I///i. See its documentation
for more information.
Basic usage:
Tricky examples, with sigma:
let sigma = "";
assert_eq!("", sigma.to_lowercase());
// but at the end of a word, it's , not :
let odysseus = "";
assert_eq!("", odysseus.to_lowercase());
let odysseus_king_of_ithaca = " ";
assert_eq!(" ", odysseus_king_of_ithaca.to_lowercase());Languages without case are not changed:
titlecase #153892)Returns the titlecase equivalent of this string slice,
which is assumed to represent a single word,
as a new String.
Essentially, this consists of uppercasing the first cased letter
(with char::to_titlecase()), and lowercasing everything that follows.
Titlecase is defined according to the terms of Chapter 3 (Conformance) of the Unicode standard.
Since some characters can expand into multiple characters when changing
the case, this function returns a String instead of modifying the
parameter in-place.
Unlike char::to_lowercase(), this method fully handles the context-dependent
casing of Greek sigma. However, like that method, it does not handle locale-specific
casing, like Turkish and Azeri I///i. See its documentation
for more information.
This method does not perform any kind of word segmentation.
Basic usage:
The first cased letter is uppercased:
#![feature(titlecase)]
let the_night_before_christmas = "'twas";
assert_eq!("'Twas", the_night_before_christmas.word_to_titlecase());Languages without case are not changed:
Georgian uppercase (Mtavruli) letters are not used in titlecase:
No word segmentation is performed, so only the first cased letter in the whole string gets uppercased:
#![feature(titlecase)]
let blazingly_fast = "ferris and I";
assert_eq!("Ferris and i", blazingly_fast.word_to_titlecase());Tricky examples, with sigma:
Returns the uppercase equivalent of this string slice, as a new String.
Uppercase is defined according to the terms of Chapter 3 (Conformance) of the Unicode standard.
Since some characters can expand into multiple characters when changing
the case, this function returns a String instead of modifying the
parameter in-place.
Like char::to_uppercase() this method does not handle language-specific
casing, like Turkish and Azeri I///i. See that methods documentation
for more information.
Basic usage:
Scripts without case are not changed:
One character can become multiple:
casefold #154742)Returns the case-folded equivalent of this string slice, as a new String.
Case folding is a transformation, mostly matching lowercase, that is meant to be used for case-insensitive string comparisons. Case-folded strings should not usually be exposed directly to users.
For the precise specification of case folding, see Chapter 3 (Conformance) of the Unicode standard.
Since some characters can expand into multiple characters when case folding,
this function returns a String instead of modifying the parameter in-place.
No normalization (e.g. NFC) is performed, so visually and semantically identical strings
might still casefold differently. For example, "" (U+00C5 LATIN CAPITAL LETTER A WITH RING ABOVE)
is considered distinct from "A" (A followed by U+030A COMBINING RING ABOVE),
even though Unicode considers them canonically equivalent.
Like char::to_casefold_unnormalized() this method does not handle language-specific
casing, like Turkish and Azeri I///i. See that methods documentation
for more information.
Basic usage:
#![feature(casefold)]
let s0 = "HELLO";
let s1 = "Hello";
assert_eq!(s0.to_casefold_unnormalized(), s1.to_casefold_unnormalized());
assert_eq!(s0.to_casefold_unnormalized(), "hello")Scripts without case are not changed:
One character can become multiple:
#![feature(casefold)]
let s0 = "TSCH";
let s1 = "TSCHSS";
let s2 = "tsch";
assert_eq!(s0.to_casefold_unnormalized(), s1.to_casefold_unnormalized());
assert_eq!(s0.to_casefold_unnormalized(), s2.to_casefold_unnormalized());
assert_eq!(s0.to_casefold_unnormalized(), "tschss");No NFC normalization is performed:
#![feature(casefold)]
// These two strings are visually and semantically identical...
let comp = "";
let decomp = "A";
// ... but not codepoint-for-codepoint equal.
assert_eq!(comp, "\u{C5}");
assert_eq!(decomp, "A\u{030A}");
// Their case-foldings are likewise unequal:
assert_eq!(comp.to_casefold_unnormalized(), "\u{E5}");
assert_eq!(decomp.to_casefold_unnormalized(), "a\u{030A}");Creates a new String by repeating a string n times.
This function will panic if the capacity would overflow.
Basic usage:
A panic upon overflow:
Returns a copy of this string where each character is mapped to its ASCII 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, use make_ascii_uppercase.
To uppercase ASCII characters in addition to non-ASCII characters, use
to_uppercase.
Returns a copy of this string where each character is mapped to its ASCII 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, use make_ascii_lowercase.
To lowercase ASCII characters in addition to non-ASCII characters, use
to_lowercase.
Implements the + operator for concatenating two strings.
This consumes the String on the left-hand side and re-uses its buffer (growing it if
necessary). This is done to avoid allocating a new String and copying the entire contents on
every operation, which would lead to O(n^2) running time when building an n-byte string by
repeated concatenation.
The string on the right-hand side is only borrowed; its contents are copied into the returned
String.
Concatenating two Strings takes the first by value and borrows the second:
let a = String::from("hello");
let b = String::from(" world");
let c = a + &b;
// `a` is moved and can no longer be used here.If you want to keep using the first String, you can clone it and append to the clone instead:
let a = String::from("hello");
let b = String::from(" world");
let c = a.clone() + &b;
// `a` is still valid here.Concatenating &str slices can be done by converting the first to a String:
+ operator.+ operation. Read moreImplements the += operator for appending to a String.
This has the same behavior as the push_str method.
Clones the contents of source into self.
This method is preferred over simply assigning source.clone() to self,
as it avoids reallocation if possible.
extend_one #72631)extend_one #72631)extend_one #72631)extend_one #72631)extend_one #72631)extend_one #72631)extend_one #72631)extend_one #72631)extend_one #72631)extend_one #72631)extend_one #72631)extend_one #72631)extend_one #72631)extend_one #72631)extend_one #72631)extend_one #72631)Converts a &String into a String.
This clones s and returns the clone.
Converts a &mut str into a String.
The result is allocated on the heap.
Converts the given boxed str slice to a String.
It is notable that the str slice is owned.
Converts a clone-on-write string to an owned
instance of String.
This extracts the owned string, clones the string if it is not already owned.
Converts the given String to a boxed str slice that is owned.
s to return a value of this type. Read morecontainer[index]) operation. Read morecontainer[index]) operation. Read moreself and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.self and other values to be equal, and is used by ==.!=. The default implementation is almost always sufficient,
and should not be overridden without very good reason.A convenience impl that delegates to the impl for &str.
pattern #27721)pattern #27721)self and the haystack to search in.pattern #27721)pattern #27721)pattern #27721)pattern #27721)pattern #27721)pattern #27721)SocketAddrs. Read moreConverts a CString into a String if it contains valid UTF-8 data.
This method is equivalent to CString::into_string.
clone_to_uninit #126799)Calls U::from(self).
That is, this conversion is whatever the implementation of
From<T> for U chooses to do.
arbitrary_self_types #44874)| Web Proxy Viewer | New URL | Original Page |