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:

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.

Methods

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

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

Returns this String2's capacity, in bytes.

Examples

Basic usage:

use string2::String2;

let s = String2::with_capacity(10);

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

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

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

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

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

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

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

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

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

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

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

Important traits for StrIterator

Trait Implementations

impl Clone for String2
[src]

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

impl Eq for String2
[src]

impl Ord for String2
[src]

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

impl<'a> From<&'a str> for String2
[src]

Performs the conversion.

impl From<String> for String2
[src]

Performs the conversion.

impl From<Vec<char>> for String2
[src]

Performs the conversion.

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

Performs the conversion.

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

Performs the conversion.

impl Into<String> for String2
[src]

Performs the conversion.

impl<'a> Into<String> for &'a String2
[src]

Performs the conversion.

impl Default for String2
[src]

Returns the "default value" for a type. Read more

impl IntoIterator for String2
[src]

The type of the elements being iterated over.

Which kind of iterator are we turning this into?

Creates an iterator from a value. Read more

impl AsRef<String2> for String2
[src]

Performs the conversion.

impl AsMut<String2> for String2
[src]

Performs the conversion.

impl AsRef<[char]> for String2
[src]

Performs the conversion.

impl AsMut<[char]> for String2
[src]

Performs the conversion.

impl Add for String2
[src]

The resulting type after applying the + operator.

Performs the + operation.

impl Add<char> for String2
[src]

The resulting type after applying the + operator.

Performs the + operation.

impl<'a> Add<&'a str> for String2
[src]

The resulting type after applying the + operator.

Performs the + operation.

impl AddAssign for String2
[src]

Performs the += operation.

impl AddAssign<char> for String2
[src]

Performs the += operation.

impl<'a> AddAssign<&'a str> for String2
[src]

Performs the += operation.

impl PartialEq for String2
[src]

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

This method tests for !=.

impl PartialOrd for String2
[src]

This method returns an ordering between self and other values if one exists. Read more

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

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

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

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

impl Index<usize> for String2
[src]

The returned type after indexing.

Performs the indexing (container[index]) operation.

impl Index<Range<usize>> for String2
[src]

The returned type after indexing.

Performs the indexing (container[index]) operation.

impl Index<RangeFrom<usize>> for String2
[src]

The returned type after indexing.

Performs the indexing (container[index]) operation.

impl Index<RangeTo<usize>> for String2
[src]

The returned type after indexing.

Performs the indexing (container[index]) operation.

impl Index<RangeFull> for String2
[src]

The returned type after indexing.

Performs the indexing (container[index]) operation.

impl IndexMut<usize> for String2
[src]

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

impl IndexMut<Range<usize>> for String2
[src]

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

impl IndexMut<RangeFrom<usize>> for String2
[src]

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

impl IndexMut<RangeTo<usize>> for String2
[src]

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

impl IndexMut<RangeFull> for String2
[src]

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

impl Display for String2
[src]

Formats the value using the given formatter. Read more

impl Debug for String2
[src]

Formats the value using the given formatter. Read more

Auto Trait Implementations

impl Send for String2

impl Sync for String2