Struct bevy_internal::utils::smallvec::alloc::string::String

1.0.0 · source ·

pub struct String { /* private fields */ }

Expand description

A UTF-8–encoded, growable string.

The String type is the most common string type that has ownership over the contents of the string. It has a close relationship with its borrowed counterpart, the primitive str.

Examples

You can create a String from a literal string with String::from:

let hello = String::from("Hello, world!");

You can append a char to a String with the push method, and append a &str with the push_str method:

let mut hello = String::from("Hello, ");

hello.push('w');
hello.push_str("orld!");

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:

use std::mem;

// `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| mem::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| mem::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 else similar. Since we’re 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:

let s = "hello";

// The following will not compile!
println!("The first letter of s is {}", s[0]);

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.

Deref

String implements Deref<Target = str>, and so inherits all of str’s methods. In addition, this means that you can pass a String to a function which takes a &str by using an ampersand (&):

fn takes_str(s: &str) { }

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

takes_str(&s);

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 doesn’t 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 doesn’t 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.

Representation

A String is made up of three components: a pointer to some bytes, a length, and a capacity. The pointer points to an internal buffer 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:

use std::mem;

let story = String::from("Once upon a time...");

// Prevent automatically dropping the String's data
let mut story = mem::ManuallyDrop::new(story);

let ptr = story.as_mut_ptr();
let len = story.len();
let capacity = story.capacity();

// 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:

At 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:

Here, there’s no need to allocate more memory inside the loop.

Struct bevy_internal::utils::smallvec::alloc::string::String

Implementations§

impl String

pub const fn new() -> String

pub fn with_capacity(capacity: usize) -> String

pub fn from_utf8(vec: Vec<u8>) -> Result<String, FromUtf8Error>

pub fn from_utf8_lossy(v: &[u8]) -> Cow<'_, str>

pub fn from_utf16(v: &[u16]) -> Result<String, FromUtf16Error>

pub fn from_utf16_lossy(v: &[u16]) -> String

pub fn from_utf16le(v: &[u8]) -> Result<String, FromUtf16Error>

pub fn from_utf16le_lossy(v: &[u8]) -> String

pub fn from_utf16be(v: &[u8]) -> Result<String, FromUtf16Error>

pub fn from_utf16be_lossy(v: &[u8]) -> String

pub fn into_raw_parts(self) -> (*mut u8, usize, usize)

pub unsafe fn from_raw_parts( buf: *mut u8, length: usize, capacity: usize ) -> String

pub unsafe fn from_utf8_unchecked(bytes: Vec<u8>) -> String

pub fn into_bytes(self) -> Vec<u8> ⓘ

pub fn as_str(&self) -> &str

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

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

pub fn extend_from_within<R>(&mut self, src: R)where R: RangeBounds<usize>,

pub fn capacity(&self) -> usize

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

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

pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>

pub fn try_reserve_exact( &mut self, additional: usize ) -> Result<(), TryReserveError>

pub fn shrink_to_fit(&mut self)

pub fn shrink_to(&mut self, min_capacity: usize)

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

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

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

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

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

pub fn remove_matches<P, 'a>(&'a mut self, pat: P)where P: for<'x> Pattern<'x>,

pub fn retain<F>(&mut self, f: F)where F: FnMut(char) -> bool,

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

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

pub unsafe fn as_mut_vec(&mut self) -> &mut Vec<u8> ⓘ

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn split_off(&mut self, at: usize) -> String

pub fn clear(&mut self)

pub fn drain<R>(&mut self, range: R) -> Drain<'_> ⓘwhere R: RangeBounds<usize>,

pub fn replace_range<R>(&mut self, range: R, replace_with: &str)where R: RangeBounds<usize>,

pub fn into_boxed_str(self) -> Box<str>

pub fn leak<'a>(self) -> &'a mut str

Methods from Deref<Target = str>§

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

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

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

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

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

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

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

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

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

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

pub unsafe fn get_unchecked<I>(&self, i: I) -> &<I as SliceIndex<str>>::Outputwhere I: SliceIndex<str>,

pub unsafe fn get_unchecked_mut<I>( &mut self, i: I ) -> &mut <I as SliceIndex<str>>::Outputwhere I: SliceIndex<str>,

pub unsafe fn slice_unchecked(&self, begin: usize, end: usize) -> &str

pub fn extend_from_within<R>(&mut self, src: R)
where R: RangeBounds<usize>,

pub fn remove_matches<P, 'a>(&'a mut self, pat: P)
where P: for<'x> Pattern<'x>,

pub fn retain<F>(&mut self, f: F)
where F: FnMut(char) -> bool,

pub fn drain<R>(&mut self, range: R) -> Drain<'_> ⓘ
where R: RangeBounds<usize>,

pub fn replace_range<R>(&mut self, range: R, replace_with: &str)
where R: RangeBounds<usize>,

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

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

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

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