Struct StringBase

pub struct StringBase<S: ?Sized> { /* private fields */ }

Implementations

impl StringBase<GenericVec<char, Box<[MaybeUninit<char>]>>>

pub fn new() -> Self

Creates a new empty String32.

Given that the String32 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 String32 will hold, consider the with_capacity method to prevent excessive re-allocation.

Examples

Basic usage:

let s = String32::new();

pub fn with_capacity(capacity: usize) -> Self

Creates a new empty String with a particular 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 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.

Examples

Basic usage:

let mut s = String32::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');

impl<A: Allocator> StringBase<GenericVec<char, Box<[MaybeUninit<char>], A>>>

pub fn with_alloc(alloc: A) -> Self

impl<const N: usize> StringBase<GenericVec<char, [MaybeUninit<char>; N]>>

pub fn new() -> Self

Creates a new empty ArrayString.

Examples

Basic usage:

let s = ArrayString32::<8>::new();

impl<S: ?Sized + Storage<Item = char>> StringBase<GenericVec<char, S>>

pub fn push_str32(&mut self, string: &str32)

Appends a given string slice onto the end of this String.

Examples

Basic usage:

let mut s = String32::from("foo");
let t = String32::from("bar");

s.push_str32(&t);

assert_eq!(s, String32::from("foobar"));

pub fn push(&mut self, ch: char)

Appends the given char to the end of this String.

Examples

Basic usage:

let mut s = String32::new();

s.push('1');
s.push('2');
s.push('3');

assert_eq!(s, String32::from("123"));

pub fn pop(&mut self) -> Option<char>

Removes the last character from the string buffer and returns it.

Returns None if this String is empty.

Examples

Basic usage:

let mut s = String32::from("foo");

assert_eq!(s.pop(), Some('o'));
assert_eq!(s.pop(), Some('o'));
assert_eq!(s.pop(), Some('f'));

assert_eq!(s.pop(), None);

pub fn truncate(&mut self, new_len: usize)

Shortens this String to the specified length.

If new_len is greater than the string’s current length, this has no effect.

Note that this method has no effect on the allocated capacity of the string

Panics

Panics if new_len does not lie on a char boundary.

Examples

Basic usage:

let mut s = String32::from("hello");

s.truncate(2);

assert_eq!(s, String32::from("he"));

pub fn remove(&mut self, idx: usize) -> char

Removes a char from this String at a byte position and returns it.

This is an O(n) operation, as it requires copying every element in the buffer.

Panics

Panics if idx is larger than or equal to the String’s length, or if it does not lie on a char boundary.

Examples

Basic usage:

let mut s = String32::from("foo");

assert_eq!(s.remove(0), 'f');
assert_eq!(s.remove(1), 'o');
assert_eq!(s.remove(0), 'o');

pub fn insert(&mut self, idx: usize, ch: char)

Inserts a character into this String at a byte position.

This is an O(n) operation as it requires copying every element in the buffer.

Panics

Panics if idx is larger than the String’s length, or if it does not lie on a char boundary.

Examples

Basic usage:

let mut s = String32::with_capacity(3);

s.insert(0, 'f');
s.insert(1, 'o');
s.insert(2, 'o');

assert_eq!(s, String32::from("foo"));

pub fn as_mut_vec(&mut self) -> &mut GenericVec<S::Item, S>

Returns a mutable reference to the contents of this String.

Examples

Basic usage:

let mut s = String32::from("hello");

unsafe {
    let vec = s.as_mut_vec();
    assert_eq!(&['h', 'e', 'l', 'l', 'o'][..], &vec[..]);

    vec.reverse();
}
assert_eq!(s, String32::from("olleh"));

pub fn split_off<B: ?Sized + StorageWithCapacity<Item = char>>( &mut self, at: usize, ) -> OwnedString<char, B>

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

Panics if at is not on a UTF-8 code point boundary, or if it is beyond the last code point of the string.

Examples

let mut hello = String32::from("Hello, World!");
let world: String32 = hello.split_off(7);
assert_eq!(hello, String32::from("Hello, "));
assert_eq!(world, String32::from("World!"));

pub fn clear(&mut self)

Truncates this String, removing all contents.

While this means the String will have a length of zero, it does not touch its capacity.

Examples

Basic usage:

let mut s = String32::from("foo");
let cap = s.capacity();

s.clear();

assert!(s.is_empty());
assert_eq!(0, s.len());
assert_eq!(cap, s.capacity());

pub fn capacity(&self) -> usize

Returns this String’s capacity, in bytes.

Examples

Basic usage:

let s = String32::with_capacity(10);

assert!(s.capacity() >= 10);

impl StringBase<GenericVec<u8, Box<[MaybeUninit<u8>]>>>

pub fn new() -> Self

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.

Examples

Basic usage:

let s = String::new();

pub fn with_capacity(capacity: usize) -> Self

Creates a new empty String with a particular 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 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.

Examples

Basic usage:

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

impl<A: Allocator> StringBase<GenericVec<u8, Box<[MaybeUninit<u8>], A>>>

pub fn with_alloc(alloc: A) -> Self

impl<const N: usize> StringBase<GenericVec<u8, [MaybeUninit<u8>; N]>>

pub fn new() -> Self

Creates a new empty ArrayString.

Examples

Basic usage:

let s = ArrayString::<8>::new();

impl<S: ?Sized + Storage<Item = u8>> StringBase<GenericVec<u8, S>>

pub fn from_utf8(vec: GenericVec<S::Item, S>) -> Result<Self, FromUtf8Error<S>>

where S: Sized,

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 don’t 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 efficiency’s sake.

If you need a &str instead of a String, consider from_utf8.

The inverse of this method is into_bytes.

Errors

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.

Examples

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.into()).unwrap();

assert_eq!(sparkle_heart, <&str>::from("💖"));

Incorrect bytes:

// some invalid bytes, in a vector
let sparkle_heart = vec![0, 159, 146, 150];

assert!(String::from_utf8(sparkle_heart.into()).is_err());

See the docs for FromUtf8Error for more details on what you can do with this error.

pub unsafe fn from_utf8_unchecked(vec: GenericVec<S::Item, S>) -> Self

where S: Sized,

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.

Safety

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.

Examples

Basic usage:

// some bytes, in a vector
let sparkle_heart = vec![240, 159, 146, 150];

let sparkle_heart = unsafe {
    String::from_utf8_unchecked(sparkle_heart.into())
};

assert_eq!(sparkle_heart, <&str>::from("💖"));

pub fn into_bytes(self) -> GenericVec<S::Item, S>

where S: Sized,

Converts a String into a byte vector.

This consumes the String, so we do not need to copy its contents.

Examples

Basic usage:

let s = String::from("hello");
let bytes = s.into_bytes();

assert_eq!(&[104, 101, 108, 108, 111][..], &bytes[..]);

pub fn as_str(&self) -> &str

Extracts a string slice containing the entire String.

Examples

Basic usage:

let s = String::from("foo");

assert_eq!(s.as_str(), <&str>::from("foo"));

pub fn as_mut_str(&mut self) -> &mut str

Converts a String into a mutable string slice.

Examples

Basic usage:

let mut s = String::from("foobar");
let s_mut_str = s.as_mut_str();

s_mut_str.make_ascii_uppercase();

assert_eq!(s_mut_str, <&str>::from("FOOBAR"));

pub fn push_str(&mut self, string: &str)

Appends a given string slice onto the end of this String.

Examples

Basic usage:

let mut s = String::from("foo");

s.push_str("bar".into());

assert_eq!(s, <&str>::from("foobar"));

pub fn reserve(&mut self, additional: usize)

Ensures that this String’s capacity is at least additional bytes larger than its length.

The capacity may be increased by more than additional bytes if it chooses, to prevent frequent reallocations.

Panics

Panics if the new capacity overflows usize.

Examples

Basic usage:

let mut s = String::new();

s.reserve(10);

assert!(s.capacity() >= 10);

This may 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 10
assert_eq!(2, s.len());
assert_eq!(10, s.capacity());

// Since we already have an extra 8 capacity, calling this...
s.reserve(8);

// ... doesn't actually increase.
assert_eq!(10, s.capacity());

pub fn try_reserve(&mut self, additional: usize) -> AllocResult

Tries to reserve capacity for at least additional more elements to be inserted in the given String. The collection may reserve more space to avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if capacity is already sufficient.

Errors

If the capacity overflows, or the allocator reports a failure, then an error is returned.

pub fn push(&mut self, ch: char)

Appends the given char to the end of this String.

Examples

Basic usage:

let mut s = String::from("abc");

s.push('1');
s.push('2');
s.push('3');

assert_eq!(s, <&str>::from("abc123"));

pub fn pop(&mut self) -> Option<char>

Removes the last character from the string buffer and returns it.

Returns None if this String is empty.

Examples

Basic usage:

let mut s = String::from("foo");

assert_eq!(s.pop(), Some('o'));
assert_eq!(s.pop(), Some('o'));
assert_eq!(s.pop(), Some('f'));

assert_eq!(s.pop(), None);

pub fn truncate(&mut self, new_len: usize)

Shortens this String to the specified length.

If new_len is greater than the string’s current length, this has no effect.

Note that this method has no effect on the allocated capacity of the string

Panics

Panics if new_len does not lie on a char boundary.

Examples

Basic usage:

let mut s = String::from("hello");

s.truncate(2);

assert_eq!(s, <&str>::from("he"));

pub fn remove(&mut self, idx: usize) -> char

Removes a char from this String at a byte position and returns it.

This is an O(n) operation, as it requires copying every element in the buffer.

Panics

Panics if idx is larger than or equal to the String’s length, or if it does not lie on a char boundary.

Examples

Basic usage:

let mut s = String::from("foo");

assert_eq!(s.remove(0), 'f');
assert_eq!(s.remove(1), 'o');
assert_eq!(s.remove(0), 'o');

pub fn insert(&mut self, idx: usize, ch: char)

Inserts a character into this String at a byte position.

This is an O(n) operation as it requires copying every element in the buffer.

Panics

Panics if idx is larger than the String’s length, or if it does not lie on a char boundary.

Examples

Basic usage:

let mut s = String::with_capacity(3);

s.insert(0, 'f');
s.insert(1, 'o');
s.insert(2, 'o');

assert_eq!(s, <&str>::from("foo"));

pub fn insert_str(&mut self, idx: usize, string: &str)

Inserts a string slice into this String at a byte position.

This is an O(n) operation as it requires copying every element in the buffer.

Panics

Panics if idx is larger than the String’s length, or if it does not lie on a char boundary.

Examples

Basic usage:

let mut s = String::from("bar");

s.insert_str(0, "foo");

assert_eq!(s, <&str>::from("foobar"));

pub unsafe fn as_mut_vec(&mut self) -> &mut GenericVec<S::Item, S>

Returns a mutable reference to the contents of this String.

Safety

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.

Examples

Basic usage:

let mut s = String::from("hello");

unsafe {
    let vec = s.as_mut_vec();
    assert_eq!(&[104, 101, 108, 108, 111][..], &vec[..]);

    vec.reverse();
}
assert_eq!(s, <&str>::from("olleh"));

pub fn split_off<B: ?Sized + StorageWithCapacity<Item = u8>>( &mut self, at: usize, ) -> StringBase<GenericVec<S::Item, B>>

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

Panics if at is not on a UTF-8 code point boundary, or if it is beyond the last code point of the string.

Examples

let mut hello = String::from("Hello, World!");
let world: String = hello.split_off(7);
assert_eq!(hello, <&str>::from("Hello, "));
assert_eq!(world, <&str>::from("World!"));

pub fn clear(&mut self)

Truncates this String, removing all contents.

While this means the String will have a length of zero, it does not touch its capacity.

Examples

Basic usage:

let mut s = String::from("foo");

s.clear();

assert!(s.is_empty());
assert_eq!(0, s.len());
assert_eq!(3, s.capacity());

pub fn capacity(&self) -> usize

Returns this String’s capacity, in bytes.

Examples

Basic usage:

let s = String::with_capacity(10);

assert!(s.capacity() >= 10);

impl StringBase<[char]>

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:

assert_eq!(String32::from("foo").len(), 3);
assert_eq!(String32::from("ƒoo").len(), 3); // fancy f!

pub fn is_empty(&self) -> bool

Returns true if self has a length of zero bytes.

Examples

Basic usage:

let s = String32::from("");
assert!(s.is_empty());

let s = String32::from("not empty");
assert!(!s.is_empty());

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

Converts a string slice to a raw pointer.

As string slices are a slice of bytes, the raw pointer points to a char. 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 = String32::from("Hello");
let ptr = s.as_ptr();

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

Converts a mutable string slice to a raw pointer.

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

pub fn from_slice(data: &[char]) -> &Self

Converts a mutable string slice to a raw pointer.

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

pub fn from_slice_mut(data: &mut [char]) -> &mut Self

Converts a mutable string slice to a raw pointer.

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

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 = String32::from("🗻∈🌏");

assert_eq!(v.get(0..2).unwrap().to_owned(), String32::from("🗻∈"));

// out of bounds
assert!(v.get(..4).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 = String32::from("hello");
// correct length
assert!(v.get_mut(0..5).is_some());
// out of bounds
assert!(v.get_mut(..42).is_none());

{
    let s = v.get_mut(0..2);
    let s = s.map(|s| {
        s.make_ascii_uppercase();
        &*s
    });
}
assert_eq!(v, String32::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 = "🗻∈🌏";
unsafe {
    assert_eq!(v.get_unchecked(0..4), "🗻");
    assert_eq!(v.get_unchecked(4..7), "∈");
    assert_eq!(v.get_unchecked(7..11), "🌏");
}

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 = String32::from("🗻∈🌏");
unsafe {
    assert_eq!(*v.get_unchecked_mut(0..2), String32::from("🗻∈"));
}

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

Divide one string slice into two at an index.

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 past the end of the last code point of the string slice.

Examples

Basic usage:

let s = String32::from("Per Martin-Löf");

let (first, last) = s.split_at(3);

assert_eq!(first.to_owned(), String32::from("Per"));
assert_eq!(last.to_owned(), String32::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 = String32::from("Per Martin-Löf");
{
    let (first, last) = s.split_at_mut(3);
    first.make_ascii_uppercase();
    assert_eq!(first.to_owned(), String32::from("PER"));
    assert_eq!(last.to_owned(), String32::from(" Martin-Löf"));
}
assert_eq!(s, String32::from("PER Martin-Löf"));

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 = String32::from("Grüße, Jürgen ❤");

s.make_ascii_uppercase();

assert_eq!(s, String32::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 = String32::from("GRÜßE, JÜRGEN ❤");

s.make_ascii_lowercase();

assert_eq!(s, String32::from("grÜße, jÜrgen ❤"));

impl StringBase<[u8]>

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

impl<S: StorageWithCapacity> StringBase<GenericVec<S::Item, S>>

pub fn new_with_capacity(capacity: usize) -> Self

impl<S: ?Sized + Storage> StringBase<GenericVec<S::Item, S>>

pub fn with_storage(storage: S) -> Self

where S: Sized,

Creates a new empty String with a particular storage backend.

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

Examples

Basic usage:

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

Trait Implementations

impl<'a> Add<&'a StringBase<[char]>> for Cow<'a, str32>

type Output = Cow<'a, StringBase<[char]>>

The resulting type after applying the + operator.

fn add(self, rhs: &'a str32) -> Self::Output

Performs the + operation.

impl<'a> Add<&'a StringBase<[u8]>> for Cow<'a, str>

type Output = Cow<'a, StringBase<[u8]>>

The resulting type after applying the + operator.

fn add(self, rhs: &'a str) -> Self::Output

Performs the + operation.

impl<'a> AddAssign<&'a StringBase<[char]>> for Cow<'a, str32>

fn add_assign(&mut self, rhs: &'a str32)

Performs the += operation.

impl<'a> AddAssign<&'a StringBase<[u8]>> for Cow<'a, str>

fn add_assign(&mut self, rhs: &'a str)

Performs the += operation.

impl<T: ?Sized + AsMut<U>, U: ?Sized> AsMut<StringBase<U>> for StringBase<T>

fn as_mut(&mut self) -> &mut StringBase<U>

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsMut<str> for StringBase<[u8]>

fn as_mut(&mut self) -> &mut str

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T: ?Sized + AsRef<U>, U: ?Sized> AsRef<StringBase<U>> for StringBase<T>

fn as_ref(&self) -> &StringBase<U>

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<str> for StringBase<[u8]>

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl<T, A: Allocator> Borrow<StringBase<[T]>> for StringBase<HeapVec<T, A>>

fn borrow(&self) -> &StringBase<[T]>

Immutably borrows from an owned value.

impl<S: Clone + ?Sized> Clone for StringBase<S>

fn clone(&self) -> StringBase<S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for StringBase<[u8]>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<S: Default + ?Sized> Default for StringBase<S>

fn default() -> StringBase<S>

Returns the “default value” for a type.

impl<T: ?Sized + Deref> Deref for StringBase<T>

type Target = StringBase<<T as Deref>::Target>

The resulting type after dereferencing.

fn deref(&self) -> &StringBase<T::Target>

Dereferences the value.

impl<T: ?Sized + DerefMut> DerefMut for StringBase<T>

fn deref_mut(&mut self) -> &mut StringBase<T::Target>

Mutably dereferences the value.

impl Display for StringBase<[u8]>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, S: ?Sized + AsRef<[u8]>> From<&'a StringBase<S>> for &'a str

fn from(s: &'a StringBase<S>) -> Self

Converts to this type from the input type.

impl From<&mut str> for &mut StringBase<[u8]>

fn from(s: &mut str) -> Self

Converts to this type from the input type.

impl From<&str> for &StringBase<[u8]>

fn from(s: &str) -> Self

Converts to this type from the input type.

impl From<&str> for StringBase<HeapVec<char>>

fn from(s: &str) -> Self

Converts to this type from the input type.

impl From<&str> for StringBase<HeapVec<u8>>

fn from(s: &str) -> Self

Converts to this type from the input type.

impl From<String> for StringBase<HeapVec<u8>>

fn from(s: String) -> Self

Converts to this type from the input type.

impl<I> Index<I> for StringBase<[u8]>

where I: SliceIndex<StringBase<[u8]>>,

type Output = <I as SliceIndex<StringBase<[u8]>>>::Output

The returned type after indexing.

fn index(&self, index: I) -> &I::Output

Performs the indexing (container[index]) operation.

impl<I> IndexMut<I> for StringBase<[u8]>

where I: SliceIndex<StringBase<[u8]>>,

fn index_mut(&mut self, index: I) -> &mut I::Output

Performs the mutable indexing (container[index]) operation.

impl<S: ?Sized + Storage> PartialEq<&StringBase<[<S as Storage>::Item]>> for OwnedString<S::Item, S>

where S::Item: PartialEq,

fn eq(&self, other: &&StringSlice<S::Item>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<S: ?Sized + Storage> PartialEq<StringBase<[<S as Storage>::Item]>> for OwnedString<S::Item, S>

where S::Item: PartialEq,

fn eq(&self, other: &StringSlice<S::Item>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<S: ?Sized + Storage> PartialEq<StringBase<GenericVec<<S as Storage>::Item, S>>> for &StringSlice<S::Item>

where S::Item: PartialEq,

fn eq(&self, other: &OwnedString<S::Item, S>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<S: ?Sized + Storage> PartialEq<StringBase<GenericVec<<S as Storage>::Item, S>>> for StringSlice<S::Item>

where S::Item: PartialEq,

fn eq(&self, other: &OwnedString<S::Item, S>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<S: ?Sized + Storage, T: ?Sized + Storage> PartialEq<StringBase<GenericVec<<T as Storage>::Item, T>>> for StringBase<GenericVec<S::Item, S>>

where GenericVec<S::Item, S>: PartialEq<GenericVec<T::Item, T>>,

fn eq(&self, other: &OwnedString<T::Item, T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<S: ?Sized + Storage<Item = char>, T: ?Sized + AsRef<[char]>> PartialEq<T> for StringBase<GenericVec<S::Item, S>>

fn eq(&self, other: &T) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<S: ?Sized + Storage> PartialOrd<&StringBase<[<S as Storage>::Item]>> for OwnedString<S::Item, S>

where S::Item: PartialOrd,

fn partial_cmp(&self, other: &&StringSlice<S::Item>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<S: ?Sized + Storage> PartialOrd<StringBase<[<S as Storage>::Item]>> for OwnedString<S::Item, S>

where S::Item: PartialOrd,

fn partial_cmp(&self, other: &StringSlice<S::Item>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<S: ?Sized + Storage> PartialOrd<StringBase<GenericVec<<S as Storage>::Item, S>>> for &StringSlice<S::Item>

where S::Item: PartialOrd,

fn partial_cmp(&self, other: &OwnedString<S::Item, S>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<S: ?Sized + Storage> PartialOrd<StringBase<GenericVec<<S as Storage>::Item, S>>> for StringSlice<S::Item>

where S::Item: PartialOrd,

fn partial_cmp(&self, other: &OwnedString<S::Item, S>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<S: ?Sized + Storage, T: ?Sized + Storage> PartialOrd<StringBase<GenericVec<<T as Storage>::Item, T>>> for OwnedString<S::Item, S>

where GenericVec<S::Item, S>: PartialOrd<GenericVec<T::Item, T>>,

fn partial_cmp(&self, other: &OwnedString<T::Item, T>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl SliceIndex<StringBase<[char]>> for Range<usize>

Implements substring slicing with syntax &self[begin .. end] or &mut self[begin .. end].

Returns a slice of the given string from the byte range [begin, end).

This operation is O(1).

Prior to 1.20.0, these indexing operations were still supported by direct implementation of Index and IndexMut.

Panics

Panics if begin > end, or if end > len.

type Output = StringBase<[char]>

The output type returned by methods.

fn get(self, slice: &StringBase<[char]>) -> Option<&Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut StringBase<[char]>) -> Option<&mut Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked( self, slice: *const StringBase<[char]>, ) -> *const Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a pointer to the output at this location, without performing any bounds checking.

unsafe fn get_unchecked_mut( self, slice: *mut StringBase<[char]>, ) -> *mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable pointer to the output at this location, without performing any bounds checking.

fn index(self, slice: &StringBase<[char]>) -> &Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut StringBase<[char]>) -> &mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl SliceIndex<StringBase<[char]>> for RangeFrom<usize>

Implements substring slicing with syntax &self[begin ..] or &mut self[begin ..].

Returns a slice of the given string from the char range [begin, len). Equivalent to &self[begin .. len] or &mut self[begin .. len].

This operation is O(1).

Prior to 1.20.0, these indexing operations were still supported by direct implementation of Index and IndexMut.

Panics

Panics if begin > len.

type Output = StringBase<[char]>

The output type returned by methods.

fn get(self, slice: &StringBase<[char]>) -> Option<&Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut StringBase<[char]>) -> Option<&mut Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked( self, slice: *const StringBase<[char]>, ) -> *const Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a pointer to the output at this location, without performing any bounds checking.

unsafe fn get_unchecked_mut( self, slice: *mut StringBase<[char]>, ) -> *mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable pointer to the output at this location, without performing any bounds checking.

fn index(self, slice: &StringBase<[char]>) -> &Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut StringBase<[char]>) -> &mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl SliceIndex<StringBase<[char]>> for RangeFull

Implements substring slicing with syntax &self[..] or &mut self[..].

Returns a slice of the whole string, i.e., returns &self or &mut self. Equivalent to &self[0 .. len] or &mut self[0 .. len]. Unlike other indexing operations, this can never panic.

This operation is O(1).

Prior to 1.20.0, these indexing operations were still supported by direct implementation of Index and IndexMut.

Equivalent to &self[0 .. len] or &mut self[0 .. len].

type Output = StringBase<[char]>

The output type returned by methods.

fn get(self, slice: &StringBase<[char]>) -> Option<&Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut StringBase<[char]>) -> Option<&mut Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked( self, slice: *const StringBase<[char]>, ) -> *const Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a pointer to the output at this location, without performing any bounds checking.

unsafe fn get_unchecked_mut( self, slice: *mut StringBase<[char]>, ) -> *mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable pointer to the output at this location, without performing any bounds checking.

fn index(self, slice: &StringBase<[char]>) -> &Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut StringBase<[char]>) -> &mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl SliceIndex<StringBase<[char]>> for RangeTo<usize>

Implements substring slicing with syntax &self[.. end] or &mut self[.. end].

Returns a slice of the given string from the char range [0, end). Equivalent to &self[0 .. end] or &mut self[0 .. end].

This operation is O(1).

Prior to 1.20.0, these indexing operations were still supported by direct implementation of Index and IndexMut.

Panics

Panics if end > len.

type Output = StringBase<[char]>

The output type returned by methods.

fn get(self, slice: &StringBase<[char]>) -> Option<&Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut StringBase<[char]>) -> Option<&mut Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked( self, slice: *const StringBase<[char]>, ) -> *const Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a pointer to the output at this location, without performing any bounds checking.

unsafe fn get_unchecked_mut( self, slice: *mut StringBase<[char]>, ) -> *mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable pointer to the output at this location, without performing any bounds checking.

fn index(self, slice: &StringBase<[char]>) -> &Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut StringBase<[char]>) -> &mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl SliceIndex<StringBase<[char]>> for RangeToInclusive<usize>

Implements substring slicing with syntax &self[..= end] or &mut self[..= end].

Returns a slice of the given string from the byte range [0, end]. Equivalent to &self [0 .. end + 1], except if end has the maximum value for usize.

This operation is O(1).

Panics

Panics if end does not point to the ending byte offset of a character (end + 1 is either a starting byte offset as defined by is_char_boundary, or equal to len), or if end >= len.

type Output = StringBase<[char]>

The output type returned by methods.

fn get(self, slice: &StringBase<[char]>) -> Option<&Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut StringBase<[char]>) -> Option<&mut Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked( self, slice: *const StringBase<[char]>, ) -> *const Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a pointer to the output at this location, without performing any bounds checking.

unsafe fn get_unchecked_mut( self, slice: *mut StringBase<[char]>, ) -> *mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable pointer to the output at this location, without performing any bounds checking.

fn index(self, slice: &StringBase<[char]>) -> &Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut StringBase<[char]>) -> &mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl SliceIndex<StringBase<[u8]>> for Range<usize>

Implements substring slicing with syntax &self[begin .. end] or &mut self[begin .. end].

Returns a slice of the given string from the byte range [begin, end).

This operation is O(1).

Prior to 1.20.0, these indexing operations were still supported by direct implementation of Index and IndexMut.

Panics

Panics if begin or end does not point to the starting byte offset of a character (as defined by is_char_boundary), if begin > end, or if end > len.

Examples

let s = "Löwe 老虎 Léopard";
assert_eq!(&s[0 .. 1], "L");

assert_eq!(&s[1 .. 9], "öwe 老");

// these will panic:
// byte 2 lies within `ö`:
// &s[2 ..3];

// byte 8 lies within `老`
// &s[1 .. 8];

// byte 100 is outside the string
// &s[3 .. 100];

type Output = StringBase<[u8]>

The output type returned by methods.

fn get(self, slice: &StringBase<[u8]>) -> Option<&Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut StringBase<[u8]>) -> Option<&mut Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked( self, slice: *const StringBase<[u8]>, ) -> *const Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a pointer to the output at this location, without performing any bounds checking.

unsafe fn get_unchecked_mut( self, slice: *mut StringBase<[u8]>, ) -> *mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable pointer to the output at this location, without performing any bounds checking.

fn index(self, slice: &StringBase<[u8]>) -> &Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut StringBase<[u8]>) -> &mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl SliceIndex<StringBase<[u8]>> for RangeFrom<usize>

Implements substring slicing with syntax &self[begin ..] or &mut self[begin ..].

Returns a slice of the given string from the byte range [begin, len). Equivalent to &self[begin .. len] or &mut self[begin .. len].

This operation is O(1).

Prior to 1.20.0, these indexing operations were still supported by direct implementation of Index and IndexMut.

Panics

Panics if begin does not point to the starting byte offset of a character (as defined by is_char_boundary), or if begin > len.

type Output = StringBase<[u8]>

The output type returned by methods.

fn get(self, slice: &StringBase<[u8]>) -> Option<&Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut StringBase<[u8]>) -> Option<&mut Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked( self, slice: *const StringBase<[u8]>, ) -> *const Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a pointer to the output at this location, without performing any bounds checking.

unsafe fn get_unchecked_mut( self, slice: *mut StringBase<[u8]>, ) -> *mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable pointer to the output at this location, without performing any bounds checking.

fn index(self, slice: &StringBase<[u8]>) -> &Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut StringBase<[u8]>) -> &mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl SliceIndex<StringBase<[u8]>> for RangeFull

Implements substring slicing with syntax &self[..] or &mut self[..].

Returns a slice of the whole string, i.e., returns &self or &mut self. Equivalent to &self[0 .. len] or &mut self[0 .. len]. Unlike other indexing operations, this can never panic.

This operation is O(1).

Prior to 1.20.0, these indexing operations were still supported by direct implementation of Index and IndexMut.

Equivalent to &self[0 .. len] or &mut self[0 .. len].

type Output = StringBase<[u8]>

The output type returned by methods.

fn get(self, slice: &StringBase<[u8]>) -> Option<&Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut StringBase<[u8]>) -> Option<&mut Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked( self, slice: *const StringBase<[u8]>, ) -> *const Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a pointer to the output at this location, without performing any bounds checking.

unsafe fn get_unchecked_mut( self, slice: *mut StringBase<[u8]>, ) -> *mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable pointer to the output at this location, without performing any bounds checking.

fn index(self, slice: &StringBase<[u8]>) -> &Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut StringBase<[u8]>) -> &mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl SliceIndex<StringBase<[u8]>> for RangeTo<usize>

Implements substring slicing with syntax &self[.. end] or &mut self[.. end].

Returns a slice of the given string from the byte range [0, end). Equivalent to &self[0 .. end] or &mut self[0 .. end].

This operation is O(1).

Prior to 1.20.0, these indexing operations were still supported by direct implementation of Index and IndexMut.

Panics

Panics if end does not point to the starting byte offset of a character (as defined by is_char_boundary), or if end > len.

type Output = StringBase<[u8]>

The output type returned by methods.

fn get(self, slice: &StringBase<[u8]>) -> Option<&Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut StringBase<[u8]>) -> Option<&mut Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked( self, slice: *const StringBase<[u8]>, ) -> *const Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a pointer to the output at this location, without performing any bounds checking.

unsafe fn get_unchecked_mut( self, slice: *mut StringBase<[u8]>, ) -> *mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable pointer to the output at this location, without performing any bounds checking.

fn index(self, slice: &StringBase<[u8]>) -> &Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut StringBase<[u8]>) -> &mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl SliceIndex<StringBase<[u8]>> for RangeToInclusive<usize>

Implements substring slicing with syntax &self[..= end] or &mut self[..= end].

Returns a slice of the given string from the byte range [0, end]. Equivalent to &self [0 .. end + 1], except if end has the maximum value for usize.

This operation is O(1).

Panics

Panics if end does not point to the ending byte offset of a character (end + 1 is either a starting byte offset as defined by is_char_boundary, or equal to len), or if end >= len.

type Output = StringBase<[u8]>

The output type returned by methods.

fn get(self, slice: &StringBase<[u8]>) -> Option<&Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, if in bounds.

fn get_mut(self, slice: &mut StringBase<[u8]>) -> Option<&mut Self::Output>

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, if in bounds.

unsafe fn get_unchecked( self, slice: *const StringBase<[u8]>, ) -> *const Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a pointer to the output at this location, without performing any bounds checking.

unsafe fn get_unchecked_mut( self, slice: *mut StringBase<[u8]>, ) -> *mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable pointer to the output at this location, without performing any bounds checking.

fn index(self, slice: &StringBase<[u8]>) -> &Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a shared reference to the output at this location, panicking if out of bounds.

fn index_mut(self, slice: &mut StringBase<[u8]>) -> &mut Self::Output

🔬This is a nightly-only experimental API. (slice_index_methods)

Returns a mutable reference to the output at this location, panicking if out of bounds.

impl<T: Clone> ToOwned for StringBase<[T]>

type Owned = StringBase<GenericVec<T, Box<[MaybeUninit<T>]>>>

The resulting type after obtaining ownership.

fn to_owned(&self) -> Self::Owned

Creates owned data from borrowed data, usually by cloning.

fn clone_into(&self, target: &mut Self::Owned)

Uses borrowed data to replace owned data, usually by cloning.

impl<S: Copy + ?Sized> Copy for StringBase<S>