Struct str::Str

pub struct Str { /* fields omitted */ }

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.

Methods

impl Str

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

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

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

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

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

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

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

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

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[..]);

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[..]);

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

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[..]);

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

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

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

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

fn truncate(&mut self, new_len: usize)

fn push(&mut self, ch: char)

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

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

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

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

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

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

fn len(&self) -> usize

fn is_empty(&self) -> bool

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

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

fn clear(&mut self)

fn iter(self) -> StrIterator

Trait Implementations

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 Eq for Str

impl Ord for Str

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

This method returns an Ordering between self and other.

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

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

Compares and returns the maximum of two values.

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

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

Compares and returns the minimum of two values.

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

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

Performs the conversion.

impl From<String> for Str

fn from(string: String) -> Str

Performs the conversion.

impl From<Vec<char>> for Str

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

Performs the conversion.

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

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

Performs the conversion.

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

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

Performs the conversion.

impl Into<String> for Str

fn into(self) -> String

Performs the conversion.

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

fn into(self) -> String

Performs the conversion.

impl Default for Str

fn default() -> Str

Returns the "default value" for a 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 AsRef<Str> for Str

fn as_ref(&self) -> &Str

Performs the conversion.

impl AsMut<Str> for Str

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

Performs the conversion.

impl AsRef<[char]> for Str

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

Performs the conversion.

impl AsMut<[char]> for Str

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

Performs the conversion.

impl Add for Str

type Output = Str

The resulting type after applying the + operator

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

The method for the + operator

impl Add<char> for Str

type Output = Str

The resulting type after applying the + operator

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

The method for the + operator

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

type Output = Str

The resulting type after applying the + operator

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

The method for the + operator

impl AddAssign for Str

fn add_assign(&mut self, other: Str)

The method for the += operator

impl AddAssign<char> for Str

fn add_assign(&mut self, other: char)

The method for the += operator

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

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

The method for the += operator

impl PartialEq for Str

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl Index<usize> for Str

type Output = char

The returned type after indexing

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

The method for the indexing (container[index]) operation

impl Index<Range<usize>> for Str

type Output = [char]

The returned type after indexing

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

The method for 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]

The method for 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]

The method for the indexing (container[index]) operation

impl Index<RangeFull> for Str

type Output = [char]

The returned type after indexing

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

The method for the indexing (container[index]) operation

impl IndexMut<usize> for Str

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

The method for the mutable indexing (container[index]) operation

impl IndexMut<Range<usize>> for Str

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

The method for the mutable indexing (container[index]) operation

impl IndexMut<RangeFrom<usize>> for Str

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

The method for the mutable indexing (container[index]) operation

impl IndexMut<RangeTo<usize>> for Str

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

The method for the mutable indexing (container[index]) operation

impl IndexMut<RangeFull> for Str

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

The method for the mutable indexing (container[index]) operation

impl Display for Str

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

Formats the value using the given formatter.

impl Debug for Str

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

Formats the value using the given formatter.