Type Definition generic_str::str

pub type str = StringSlice<u8>;

Exactly the same as std::primitive::str, except generic

Implementations

impl str

pub fn len(&self) -> usize

Returns the length of self.

This length is in bytes, not chars 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);

pub fn is_empty(&self) -> bool

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());

pub fn is_char_boundary(&self, index: usize) -> bool

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));

pub fn as_bytes(&self) -> &[u8]

Converts a string slice to a byte slice. To convert the byte slice back into a string slice, use the from_utf8 function.

Examples

Basic usage:

let bytes = <&str>::from("bors").as_bytes();
assert_eq!(b"bors", bytes);

pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8]

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("🍔∈🌏"));

pub fn as_ptr(&self) -> *const u8

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();

pub fn as_mut_ptr(&mut self) -> *mut u8

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.

pub fn get<I: SliceIndex<Self>>(&self, i: I) -> Option<&I::Output>

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());

pub fn get_mut<I: SliceIndex<Self>>(&mut self, i: I) -> Option<&mut I::Output>

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"));

pub unsafe fn get_unchecked<I: SliceIndex<Self>>(&self, i: I) -> &I::Output

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("🌏"));
}

pub unsafe fn get_unchecked_mut<I: SliceIndex<Self>>(
    &mut self,
    i: I
) -> &mut I::Output

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("🌏"));
}

pub fn split_at(&self, mid: usize) -> (&Self, &Self)

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"));

pub fn split_at_mut(&mut self, mid: usize) -> (&mut Self, &mut Self)

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"));

pub fn chars(&self) -> Chars<'_>

Returns 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.

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, chars 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());

pub fn char_indices(&self) -> CharIndices<'_>

pub fn bytes(&self) -> Bytes<'_>

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());

pub fn is_ascii(&self) -> bool

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());

pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool

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()));

pub fn make_ascii_uppercase(&mut self)

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 ❤"));

pub fn make_ascii_lowercase(&mut self)

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 ❤"));

pub fn to_lowercase(&self) -> String

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());

pub fn to_uppercase(&self) -> String

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"));