Type Definition generic_str::str [−][src]
pub type str = StringSlice<u8>;
Expand description
Exactly the same as std::primitive::str
, except generic
Implementations
Returns the length of self
.
This length is in bytes, not char
s or graphemes. In other words,
it may not be what a human considers the length of the string.
Examples
Basic usage:
let len = <&str>::from("foo").len();
assert_eq!(3, len);
assert_eq!("ƒoo".len(), 4); // fancy f!
assert_eq!("ƒoo".chars().count(), 3);
Returns true
if self
has a length of zero bytes.
Examples
Basic usage:
let s: &str = "".into();
assert!(s.is_empty());
let s: &str = "not empty".into();
assert!(!s.is_empty());
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()
.
Examples
let s: &str = "Löwe 老虎 Léopard".into();
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));
Converts a mutable string slice to a mutable byte slice.
Safety
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.
Examples
Basic usage:
let mut s = String::from("Hello");
let bytes = unsafe { s.as_bytes_mut() };
assert_eq!(bytes, b"Hello");
Mutability:
let mut s = String::from("🗻∈🌏");
unsafe {
let bytes = s.as_bytes_mut();
bytes[0] = 0xF0;
bytes[1] = 0x9F;
bytes[2] = 0x8D;
bytes[3] = 0x94;
}
assert_eq!(s, <&str>::from("🍔∈🌏"));
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
.
Examples
Basic usage:
let s: &str = "Hello".into();
let ptr = 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 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.
Examples
let v = String::from("🗻∈🌏");
assert_eq!(v.get(0..4), Some(<&str>::from("🗻")));
// indices not on UTF-8 sequence boundaries
assert!(v.get(1..).is_none());
assert!(v.get(..8).is_none());
// out of bounds
assert!(v.get(..42).is_none());
Returns a mutable subslice of str
.
This is the non-panicking alternative to indexing the str
. Returns
None
whenever equivalent indexing operation would panic.
Examples
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!(v.get_mut(0..2).map(|v| &*v), Some(<&str>::from("he")));
assert_eq!(v, <&str>::from("hello"));
{
let s = v.get_mut(0..2);
let s = s.map(|s| {
s.make_ascii_uppercase();
&*s
});
assert_eq!(s, Some(<&str>::from("HE")));
}
assert_eq!(v, <&str>::from("HEllo"));
Returns an unchecked subslice of str
.
This is the unchecked alternative to indexing the str
.
Safety
Callers of this function are responsible that these preconditions are satisfied:
- 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 or
violate the invariants communicated by the str
type.
Examples
let v = <&str>::from("🗻∈🌏");
unsafe {
assert_eq!(v.get_unchecked(0..4), <&str>::from("🗻"));
assert_eq!(v.get_unchecked(4..7), <&str>::from("∈"));
assert_eq!(v.get_unchecked(7..11), <&str>::from("🌏"));
}
Returns a mutable, unchecked subslice of str
.
This is the unchecked alternative to indexing the str
.
Safety
Callers of this function are responsible that these preconditions are satisfied:
- 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 or
violate the invariants communicated by the str
type.
Examples
let mut v = String::from("🗻∈🌏");
unsafe {
assert_eq!(v.get_unchecked_mut(0..4), <&str>::from("🗻"));
assert_eq!(v.get_unchecked_mut(4..7), <&str>::from("∈"));
assert_eq!(v.get_unchecked_mut(7..11), <&str>::from("🌏"));
}
Divide 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
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.
Examples
Basic usage:
let s: &str = "Per Martin-Löf".into();
let (first, last) = s.split_at(3);
assert_eq!(first, <&str>::from("Per"));
assert_eq!(last, <&str>::from(" Martin-Löf"));
Divide 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
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.
Examples
Basic usage:
let mut s = String::from("Per Martin-Löf");
{
let (first, last) = s.split_at_mut(3);
first.make_ascii_uppercase();
assert_eq!(first, <&str>::from("PER"));
assert_eq!(last, <&str>::from(" Martin-Löf"));
}
assert_eq!(s, <&str>::from("PER Martin-Löf"));
Returns an iterator over the char
s 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.
It’s important to remember that char
represents a Unicode Scalar
Value, and may 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 Rust’s standard library, check crates.io instead.
Examples
Basic usage:
let word = <&str>::from("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, char
s may not match your intuition about characters:
let y = "y̆";
let mut chars = y.chars();
assert_eq!(Some('y'), chars.next()); // not 'y̆'
assert_eq!(Some('\u{0306}'), chars.next());
assert_eq!(None, chars.next());
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.
Examples
Basic usage:
let mut bytes = <&str>::from("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());
Checks if all characters in this string are within the ASCII range.
Examples
let ascii = <&str>::from("hello!\n");
let non_ascii = <&str>::from("Grüße, Jürgen ❤");
assert!(ascii.is_ascii());
assert!(!non_ascii.is_ascii());
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.
Examples
assert!(<&str>::from("Ferris").eq_ignore_ascii_case("FERRIS".into()));
assert!(<&str>::from("Ferrös").eq_ignore_ascii_case("FERRöS".into()));
assert!(!<&str>::from("Ferrös").eq_ignore_ascii_case("FERRÖS".into()));
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()
.
Examples
let mut s = String::from("Grüße, Jürgen ❤");
s.make_ascii_uppercase();
assert_eq!(s, <&str>::from("GRüßE, JüRGEN ❤"));
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()
.
Examples
let mut s = String::from("GRÜßE, JÜRGEN ❤");
s.make_ascii_lowercase();
assert_eq!(s, <&str>::from("grÜße, jÜrgen ❤"));
Returns the lowercase equivalent of this string slice, as a new String
.
‘Lowercase’ is defined according to the terms of the Unicode Derived Core Property
Lowercase
.
Since some characters can expand into multiple characters when changing
the case, this function returns a String
instead of modifying the
parameter in-place.
Examples
Basic usage:
let s = <&str>::from("HELLO");
assert_eq!(s.to_lowercase(), <&str>::from("hello"));
A tricky example, with sigma:
let sigma = <&str>::from("Σ");
assert_eq!(sigma.to_lowercase(), <&str>::from("σ"));
// but at the end of a word, it's ς, not σ:
let odysseus = <&str>::from("ὈΔΥΣΣΕΎΣ");
assert_eq!(odysseus.to_lowercase(), <&str>::from("ὀδυσσεύς"));
Languages without case are not changed:
let new_year = <&str>::from("农历新年");
assert_eq!(new_year, new_year.to_lowercase());
Returns the uppercase equivalent of this string slice, as a new String
.
‘Uppercase’ is defined according to the terms of the Unicode Derived Core Property
Uppercase
.
Since some characters can expand into multiple characters when changing
the case, this function returns a String
instead of modifying the
parameter in-place.
Examples
Basic usage:
let s = <&str>::from("hello");
assert_eq!(s.to_uppercase(), <&str>::from("HELLO"));
Scripts without case are not changed:
let new_year = <&str>::from("农历新年");
assert_eq!(new_year, new_year.to_uppercase());
One character can become multiple:
let s = <&str>::from("tschüß");
assert_eq!(s.to_uppercase(), <&str>::from("TSCHÜSS"));