Struct Str

pub struct Str { /* private fields */ }

A UTF-8 encoded, growable string.

The Str type is string type that has owership over the char.

Example

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

use str::Str;

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

You can append a char to a Str with the push method, and append a &str with the push_str method;

use str::Str;

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

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

If you have a String, you can create a Str from it with the from method, and you can convert Str to String whit the into method:

use str::Str;

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

let world = Str::from(hello);

let hello_world: String = world.into();

Representation

A Str is made up of three components: a pointer to some chars, a length, and a capacity. The pointer points to an internal buffer Str uses to store its data. The length is the munber of bytes currently stored in the buffer, and the capacity is the size of the buffer in chars. As such, the length will always be less than or equal to the capacity.

The buffer is always stored on the heap.

You can look at these with the as_ptr, len, and capacity methods:

use std::mem;
use str::Str;

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

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

// story has nineteen chars
assert_eq!(19, len);

// Now that we have our parts, we throw the story away.
mem::forget(story);

// We can re-build a Str out of ptr, len, and capacity. This is all
// unsafe because we are responsible for making sure the components
// valid:
let s = unsafe { Str::from_raw_parts(ptr as *mut _, len, capacity) };

assert_eq!(Str::from("Once upon a time..."), s);

If a Str has enough capacity, adding elements to it will not re-allocate. For example, consider this program:

use str::Str;

let mut s = Str::new();

println!("{}", s.capacity());

for _ in 0..5 {
    s.push_str("hello");
    println!("{}", s.capacity());
}

This will output the following:

0
5
10
20
20
40

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:

use str::Str;

let mut s = Str::with_capacity(25);

println!("{}", s.capacity());

for _ in 0..5 {
    s.push_str("hello");
    println!("{}", s.capacity());
}

We end up with a different output:

25
25
25
25
25
25

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

Implementations

impl Str

pub fn new() -> Str

Creates a new empty Str.

Given that the Str is empty, this will not allocate any initial buffer. While that means that this initial operation is very inexpensive, but may cause excessive allocation later, when you add data. If you have an idea of how much data the Str will hold, consider the with_capacity method to prevent excessive re-allocation.

Examples

Basic usage:

use str::Str;

let s = Str::new();

pub fn with_capacity(capacity: usize) -> Str

Creates a new empty Str with a particular capacity.

Strs 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 Str, 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 Str, 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:

use str::Str;

let mut s = Str::with_capacity(10);

// The Str 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 i in 0..10 {
    s.push('a');
}

assert_eq!(s.capacity(), cap);

// ...but this may make the vector reallocate
s.push('a');

pub fn capacity(&self) -> usize

Returns this Str’s capacity, in bytes.

Examples

Basic usage:

use str::Str;

let s = Str::with_capacity(10);

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

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

Ensures that this Str’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.

If you do not want this “at least” behavior, see the reserve_exact method.

Panics

Panics if the new capacity overflows usize.

Examples

Basic usage:

use str::Str;

let mut s = Str::new();

s.reserve(10);

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

This may not actually increase the capacity:

use str::Str;

let mut s = Str::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 reserve_exact(&mut self, additional: usize)

Ensures that this Str’s capacity is additional bytes larger than its length.

Consider using the reserve method unless you absolutely know better than the allocator.

Panics

Panics if the new capacity overflows usize.

Examples

Basic usage:

use str::Str;

let mut s = Str::new();

s.reserve_exact(10);

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

This may not actually increase the capacity:

use str::Str;

let mut s = Str::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_exact(8);

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

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of this Str to match its length.

Examples

Basic usage:

use str::Str;

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

s.reserve(100);
assert!(s.capacity() >= 100);

s.shrink_to_fit();
assert_eq!(3, s.capacity());

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

Converts a Str to a raw pointer. As Str are a vector of chars, the raw pointer points to a char. This pointer will be pointing to the first byte of the Str.

Examples

Basic usage:

use str::Str;

let s = Str::from("Hello");
let ptr = s.as_ptr();

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

Creates a new Str from a length, capacity, and pointer.

Safety

This is highly unsafe, due to the number of invariants that aren’t checked:

• The memory at ptr needs to have been previously allocated by the same allocator the standard library uses.
• length needs to be less than or equal to capacity.
• capacity needs to be the correct value.

Violating these may cause problems like corrupting the allocator’s internal datastructures.

The ownership of ptr is effectively transferred to the Str which may then deallocate, reallocate or change the contents of memory pointed to by the pointer at will. Ensure that nothing else uses the pointer after calling this function.

Examples

Basic usage:

use std::mem;
use str::Str;

let s = Str::from("hello");
let ptr = s.as_ptr();
let len = s.len();
let capacity = s.capacity();

mem::forget(s);

let s = unsafe { Str::from_raw_parts(ptr as *mut _, len, capacity) };

assert_eq!(Str::from("hello"), s);

pub fn as_bytes(&self) -> Vec<u8>

Converts a Str into a byte vector.

Examples

Basic usage:

use str::Str;

let s = Str::from("hello");
let bytes = s.as_bytes();

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

pub fn as_slice(&self) -> &[char]

Converts a Str into a char slice.

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

Examples

Basic usage:

use str::Str;

let s = Str::from("hello");
let bytes = s.as_slice();

assert_eq!(&['h', 'e', 'l', 'l', 'o'][..], &bytes[..]);

pub fn as_mut_slice(&mut self) -> &mut [char]

Converts a Str into a mut char slice.

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

Examples

Basic usage:

use str::Str;

let mut s = Str::from("hello");
{
    let bytes = s.as_mut_slice();
    bytes[1] = 'a';
}

assert_eq!(Str::from("hallo"), s);

pub fn as_vec(self) -> Vec<char>

Converts a Str into a char vector.

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

Examples

Basic usage:

use str::Str;

let s = Str::from("hello");
let bytes = s.as_vec();

assert_eq!(&['h', 'e', 'l', 'l', 'o'], &bytes[..]);

pub fn as_mut_vec(&mut self) -> &mut Vec<char>

Converts a Str into a mut char slice.

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

Examples

Basic usage:

use str::Str;

let mut s = Str::from("hello");
{
    let bytes = s.as_mut_vec();
    bytes[1] = 'a';
}

assert_eq!(Str::from("hallo"), s);

pub fn retain<F>(&mut self, f: F)

where F: FnMut(&char) -> bool,

pub fn get(&self, idx: usize) -> Option<&char>

pub fn get_mut(&mut self, idx: usize) -> Option<&mut char>

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

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

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

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

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

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

pub fn insert_str(&mut self, _idx: usize, _string: &str)

pub fn append(&mut self, other: &mut Self)

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

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

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

pub fn clear(&mut self)

pub fn iter(self) -> StrIterator

Trait Implementations

impl<'a> Add<&'a str> for Str

type Output = Str

The resulting type after applying the + operator.

fn add(self, other: &str) -> Str

Performs the + operation.

impl Add<char> for Str

type Output = Str

The resulting type after applying the + operator.

fn add(self, other: char) -> Str

Performs the + operation.

impl Add for Str

type Output = Str

The resulting type after applying the + operator.

fn add(self, other: Str) -> Str

Performs the + operation.

impl<'a> AddAssign<&'a str> for Str

fn add_assign(&mut self, other: &str)

Performs the += operation.

impl AddAssign<char> for Str

fn add_assign(&mut self, other: char)

Performs the += operation.

impl AddAssign for Str

fn add_assign(&mut self, other: Str)

Performs the += operation.

impl AsMut<[char]> for Str

fn as_mut(&mut self) -> &mut [char]

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

impl AsMut<Str> for Str

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

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

impl AsRef<[char]> for Str

fn as_ref(&self) -> &[char]

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

impl AsRef<Str> for Str

fn as_ref(&self) -> &Str

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

impl Clone for Str

fn clone(&self) -> Str

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Str

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

Formats the value using the given formatter.

impl Default for Str

fn default() -> Str

Returns the “default value” for a type.

impl Display for Str

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

Formats the value using the given formatter.

impl<'a> From<&'a [char]> for Str

fn from(s: &'a [char]) -> Str

Converts to this type from the input type.

impl<'a> From<&'a mut [char]> for Str

fn from(s: &'a mut [char]) -> Str

Converts to this type from the input type.

impl<'a> From<&'a str> for Str

fn from(string: &'a str) -> Str

Converts to this type from the input type.

impl From<String> for Str

fn from(string: String) -> Str

Converts to this type from the input type.

impl From<Vec<char>> for Str

fn from(s: Vec<char>) -> Str

Converts to this type from the input type.

impl Index<Range<usize>> for Str

type Output = [char]

The returned type after indexing.

fn index(&self, range: Range<usize>) -> &[char]

Performs the indexing (container[index]) operation.

impl Index<RangeFrom<usize>> for Str

type Output = [char]

The returned type after indexing.

fn index(&self, range: RangeFrom<usize>) -> &[char]

Performs the indexing (container[index]) operation.

impl Index<RangeFull> for Str

type Output = [char]

The returned type after indexing.

fn index(&self, _range: RangeFull) -> &[char]

Performs the indexing (container[index]) operation.

impl Index<RangeTo<usize>> for Str

type Output = [char]

The returned type after indexing.

fn index(&self, range: RangeTo<usize>) -> &[char]

Performs the indexing (container[index]) operation.

impl Index<usize> for Str

type Output = char

The returned type after indexing.

fn index(&self, idx: usize) -> &char

Performs the indexing (container[index]) operation.

impl IndexMut<Range<usize>> for Str

fn index_mut(&mut self, range: Range<usize>) -> &mut [char]

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

impl IndexMut<RangeFrom<usize>> for Str

fn index_mut(&mut self, range: RangeFrom<usize>) -> &mut [char]

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

impl IndexMut<RangeFull> for Str

fn index_mut(&mut self, range: RangeFull) -> &mut [char]

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

impl IndexMut<RangeTo<usize>> for Str

fn index_mut(&mut self, range: RangeTo<usize>) -> &mut [char]

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

impl IndexMut<usize> for Str

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

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

impl<'a> Into<String> for &'a Str

fn into(self) -> String

Converts this type into the (usually inferred) input type.

impl Into<String> for Str

fn into(self) -> String

Converts this type into the (usually inferred) input type.

impl IntoIterator for Str

type Item = char

The type of the elements being iterated over.

type IntoIter = StrIterator

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl Ord for Str

fn cmp(&self, other: &Str) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Str

fn eq(&self, other: &Str) -> 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 PartialOrd for Str

fn partial_cmp(&self, other: &Str) -> 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 Eq for Str