Struct string2::String2[−][src]

pub struct String2 { /* fields omitted */ }

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:

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:

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

Methods

`impl String2`
[src]

`pub fn new() -> String2`
[src]

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`
[src]

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`
[src]

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)`
[src]

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)`
[src]

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)`
[src]

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`
[src]

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`
[src]

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>`
[src]

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]`
[src]

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]`
[src]

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>`
[src]

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>`
[src]

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