Struct String2 

pub struct String2 { /* private fields */ }

A UTF-8 encoded, growable string.

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

Example

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

use string2::String2;

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

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

use string2::String2;

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

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

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

use string2::String2;

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

let world = String2::from(hello);

let hello_world: String = world.into();

Representation

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

let story = String2::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 String2 out of ptr, len, and capacity. This is all
// unsafe because we are responsible for making sure the components
// valid:
let s = unsafe { String2::from_raw_parts(ptr as *mut _, len, capacity) };

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

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

use string2::String2;

let mut s = String2::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 string2::String2;

let mut s = String2::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 String2

pub fn new() -> String2

Creates a new empty String2.

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

Examples

Basic usage:

use string2::String2;

let s = String2::new();

pub fn with_capacity(capacity: usize) -> String2

Creates a new empty String2 with a particular capacity.

String2s 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 String2, 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 String2, 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 string2::String2;

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

// The String2 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 String2’s capacity, in bytes.

Examples

Basic usage:

use string2::String2;

let s = String2::with_capacity(10);

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

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

Ensures that this String2’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 string2::String2;

let mut s = String2::new();

s.reserve(10);

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

This may not actually increase the capacity:

use string2::String2;

let mut s = String2::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 String2’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 string2::String2;

let mut s = String2::new();

s.reserve_exact(10);

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

This may not actually increase the capacity:

use string2::String2;

let mut s = String2::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 String2 to match its length.

Examples

Basic usage:

use string2::String2;

let mut s = String2::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 String2 to a raw pointer. As String2 are a vector of chars, the raw pointer points to a char. This pointer will be pointing to the first byte of the String2.

Examples

Basic usage:

use string2::String2;

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

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

Creates a new String2 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 String2 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 string2::String2;

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

mem::forget(s);

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

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

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

Converts a String2 into a byte vector.

Examples

Basic usage:

use string2::String2;

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

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

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

Converts a String2 into a char slice.

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

Examples

Basic usage:

use string2::String2;

let s = String2::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 String2 into a mut char slice.

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

Examples

Basic usage:

use string2::String2;

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

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

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

Converts a String2 into a char vector.

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

Examples

Basic usage:

use string2::String2;

let s = String2::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 String2 into a mut char slice.

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

Examples

Basic usage:

use string2::String2;

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

assert_eq!(String2::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) -> String2

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

pub fn clear(&mut self)

pub fn iter(self) -> StrIterator

Trait Implementations

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

type Output = String2

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<char> for String2

type Output = String2

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add for String2

type Output = String2

The resulting type after applying the + operator.

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

Performs the + operation.

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

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

Performs the += operation.

impl AddAssign<char> for String2

fn add_assign(&mut self, other: char)

Performs the += operation.

impl AddAssign for String2

fn add_assign(&mut self, other: String2)

Performs the += operation.

impl AsMut<[char]> for String2

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

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

impl AsMut<String2> for String2

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

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

impl AsRef<[char]> for String2

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

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

impl AsRef<String2> for String2

fn as_ref(&self) -> &String2

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

impl Clone for String2

fn clone(&self) -> String2

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for String2

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

Formats the value using the given formatter.

impl Default for String2

fn default() -> String2

Returns the “default value” for a type.

impl Display for String2

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

Formats the value using the given formatter.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

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

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

Converts to this type from the input type.

impl From<String> for String2

fn from(string: String) -> String2

Converts to this type from the input type.

impl From<Vec<char>> for String2

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

Converts to this type from the input type.

impl Index<Range<usize>> for String2

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 String2

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 String2

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 String2

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 String2

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 String2

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

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

impl IndexMut<RangeFrom<usize>> for String2

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

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

impl IndexMut<RangeFull> for String2

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

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

impl IndexMut<RangeTo<usize>> for String2

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

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

impl IndexMut<usize> for String2

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

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

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

fn into(self) -> String

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

impl Into<String> for String2

fn into(self) -> String

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

impl IntoIterator for String2

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 String2

fn cmp(&self, other: &String2) -> 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 String2

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

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