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]
impl String2
pub fn new() -> String2
[src]
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
[src]
pub fn with_capacity(capacity: usize) -> String2
Creates a new empty String2
with a particular capacity.
String2
s 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]
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)
[src]
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)
[src]
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)
[src]
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
[src]
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
[src]
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 tocapacity
.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]
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]
[src]
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]
[src]
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>
[src]
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>
[src]
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,
[src]
pub fn retain<F>(&mut self, f: F) where
F: FnMut(&char) -> bool,
pub fn get(&self, idx: usize) -> Option<&char>
[src]
pub fn get(&self, idx: usize) -> Option<&char>
pub fn get_mut(&mut self, idx: usize) -> Option<&mut char>
[src]
pub fn get_mut(&mut self, idx: usize) -> Option<&mut char>
pub fn truncate(&mut self, new_len: usize)
[src]
pub fn truncate(&mut self, new_len: usize)
pub fn push(&mut self, ch: char)
[src]
pub fn push(&mut self, ch: char)
pub fn push_str(&mut self, string: &str)
[src]
pub fn push_str(&mut self, string: &str)
pub fn pop(&mut self) -> Option<char>
[src]
pub fn pop(&mut self) -> Option<char>
pub fn remove(&mut self, idx: usize) -> char
[src]
pub fn remove(&mut self, idx: usize) -> char
pub fn insert(&mut self, idx: usize, ch: char)
[src]
pub fn insert(&mut self, idx: usize, ch: char)
pub fn insert_str(&mut self, _idx: usize, _string: &str)
[src]
pub fn insert_str(&mut self, _idx: usize, _string: &str)
pub fn append(&mut self, other: &mut Self)
[src]
pub fn append(&mut self, other: &mut Self)
pub fn len(&self) -> usize
[src]
pub fn len(&self) -> usize
pub fn is_empty(&self) -> bool
[src]
pub fn is_empty(&self) -> bool
pub fn split_off(&mut self, at: usize) -> String2
[src]
pub fn split_off(&mut self, at: usize) -> String2
pub fn split_at(&self, mid: usize) -> (String2, String2)
[src]
pub fn split_at(&self, mid: usize) -> (String2, String2)
pub fn clear(&mut self)
[src]
pub fn clear(&mut self)
ⓘImportant traits for StrIteratorpub fn iter(self) -> StrIterator
[src]
pub fn iter(self) -> StrIterator
Trait Implementations
impl Clone for String2
[src]
impl Clone for String2
fn clone(&self) -> String2
[src]
fn clone(&self) -> String2
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0[src]
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
impl Eq for String2
[src]
impl Eq for String2
impl Ord for String2
[src]
impl Ord for String2
fn cmp(&self, other: &String2) -> Ordering
[src]
fn cmp(&self, other: &String2) -> Ordering
This method returns an Ordering
between self
and other
. Read more
fn max(self, other: Self) -> Self
1.21.0[src]
fn max(self, other: Self) -> Self
Compares and returns the maximum of two values. Read more
fn min(self, other: Self) -> Self
1.21.0[src]
fn min(self, other: Self) -> Self
Compares and returns the minimum of two values. Read more
impl<'a> From<&'a str> for String2
[src]
impl<'a> From<&'a str> for String2
impl From<String> for String2
[src]
impl From<String> for String2
impl From<Vec<char>> for String2
[src]
impl From<Vec<char>> for String2
impl<'a> From<&'a [char]> for String2
[src]
impl<'a> From<&'a [char]> for String2
impl<'a> From<&'a mut [char]> for String2
[src]
impl<'a> From<&'a mut [char]> for String2
impl Into<String> for String2
[src]
impl Into<String> for String2
impl<'a> Into<String> for &'a String2
[src]
impl<'a> Into<String> for &'a String2
impl Default for String2
[src]
impl Default for String2
impl IntoIterator for String2
[src]
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
[src]
fn into_iter(self) -> Self::IntoIter
Creates an iterator from a value. Read more
impl AsRef<String2> for String2
[src]
impl AsRef<String2> for String2
impl AsMut<String2> for String2
[src]
impl AsMut<String2> for String2
impl AsRef<[char]> for String2
[src]
impl AsRef<[char]> for String2
impl AsMut<[char]> for String2
[src]
impl AsMut<[char]> for String2
impl Add for String2
[src]
impl Add for String2
type Output = String2
The resulting type after applying the +
operator.
fn add(self, other: String2) -> String2
[src]
fn add(self, other: String2) -> String2
Performs the +
operation.
impl Add<char> for String2
[src]
impl Add<char> for String2
type Output = String2
The resulting type after applying the +
operator.
fn add(self, other: char) -> String2
[src]
fn add(self, other: char) -> String2
Performs the +
operation.
impl<'a> Add<&'a str> for String2
[src]
impl<'a> Add<&'a str> for String2
type Output = String2
The resulting type after applying the +
operator.
fn add(self, other: &str) -> String2
[src]
fn add(self, other: &str) -> String2
Performs the +
operation.
impl AddAssign for String2
[src]
impl AddAssign for String2
fn add_assign(&mut self, other: String2)
[src]
fn add_assign(&mut self, other: String2)
Performs the +=
operation.
impl AddAssign<char> for String2
[src]
impl AddAssign<char> for String2
fn add_assign(&mut self, other: char)
[src]
fn add_assign(&mut self, other: char)
Performs the +=
operation.
impl<'a> AddAssign<&'a str> for String2
[src]
impl<'a> AddAssign<&'a str> for String2
fn add_assign(&mut self, other: &str)
[src]
fn add_assign(&mut self, other: &str)
Performs the +=
operation.
impl PartialEq for String2
[src]
impl PartialEq for String2
fn eq(&self, other: &String2) -> bool
[src]
fn eq(&self, other: &String2) -> bool
This method tests for self
and other
values to be equal, and is used by ==
. Read more
fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
fn ne(&self, other: &Rhs) -> bool
This method tests for !=
.
impl PartialOrd for String2
[src]
impl PartialOrd for String2
fn partial_cmp(&self, other: &String2) -> Option<Ordering>
[src]
fn partial_cmp(&self, other: &String2) -> Option<Ordering>
This method returns an ordering between self
and other
values if one exists. Read more
fn lt(&self, other: &Rhs) -> bool
1.0.0[src]
fn lt(&self, other: &Rhs) -> bool
This method tests less than (for self
and other
) and is used by the <
operator. Read more
fn le(&self, other: &Rhs) -> bool
1.0.0[src]
fn le(&self, other: &Rhs) -> bool
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
fn gt(&self, other: &Rhs) -> bool
1.0.0[src]
fn gt(&self, other: &Rhs) -> bool
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
fn ge(&self, other: &Rhs) -> bool
1.0.0[src]
fn ge(&self, other: &Rhs) -> bool
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]
impl Index<usize> for String2
type Output = char
The returned type after indexing.
fn index(&self, idx: usize) -> &char
[src]
fn index(&self, idx: usize) -> &char
Performs the indexing (container[index]
) operation.
impl Index<Range<usize>> for String2
[src]
impl Index<Range<usize>> for String2
type Output = [char]
The returned type after indexing.
fn index(&self, range: Range<usize>) -> &[char]
[src]
fn index(&self, range: Range<usize>) -> &[char]
Performs the indexing (container[index]
) operation.
impl Index<RangeFrom<usize>> for String2
[src]
impl Index<RangeFrom<usize>> for String2
type Output = [char]
The returned type after indexing.
fn index(&self, range: RangeFrom<usize>) -> &[char]
[src]
fn index(&self, range: RangeFrom<usize>) -> &[char]
Performs the indexing (container[index]
) operation.
impl Index<RangeTo<usize>> for String2
[src]
impl Index<RangeTo<usize>> for String2
type Output = [char]
The returned type after indexing.
fn index(&self, range: RangeTo<usize>) -> &[char]
[src]
fn index(&self, range: RangeTo<usize>) -> &[char]
Performs the indexing (container[index]
) operation.
impl Index<RangeFull> for String2
[src]
impl Index<RangeFull> for String2
type Output = [char]
The returned type after indexing.
fn index(&self, _range: RangeFull) -> &[char]
[src]
fn index(&self, _range: RangeFull) -> &[char]
Performs the indexing (container[index]
) operation.
impl IndexMut<usize> for String2
[src]
impl IndexMut<usize> for String2
fn index_mut(&mut self, idx: usize) -> &mut char
[src]
fn index_mut(&mut self, idx: usize) -> &mut char
Performs the mutable indexing (container[index]
) operation.
impl IndexMut<Range<usize>> for String2
[src]
impl IndexMut<Range<usize>> for String2
fn index_mut(&mut self, range: Range<usize>) -> &mut [char]
[src]
fn index_mut(&mut self, range: Range<usize>) -> &mut [char]
Performs the mutable indexing (container[index]
) operation.
impl IndexMut<RangeFrom<usize>> for String2
[src]
impl IndexMut<RangeFrom<usize>> for String2
fn index_mut(&mut self, range: RangeFrom<usize>) -> &mut [char]
[src]
fn index_mut(&mut self, range: RangeFrom<usize>) -> &mut [char]
Performs the mutable indexing (container[index]
) operation.
impl IndexMut<RangeTo<usize>> for String2
[src]
impl IndexMut<RangeTo<usize>> for String2
fn index_mut(&mut self, range: RangeTo<usize>) -> &mut [char]
[src]
fn index_mut(&mut self, range: RangeTo<usize>) -> &mut [char]
Performs the mutable indexing (container[index]
) operation.
impl IndexMut<RangeFull> for String2
[src]
impl IndexMut<RangeFull> for String2
fn index_mut(&mut self, range: RangeFull) -> &mut [char]
[src]
fn index_mut(&mut self, range: RangeFull) -> &mut [char]
Performs the mutable indexing (container[index]
) operation.
impl Display for String2
[src]
impl Display for String2
fn fmt(&self, f: &mut Formatter) -> Result
[src]
fn fmt(&self, f: &mut Formatter) -> Result
Formats the value using the given formatter. Read more
impl Debug for String2
[src]
impl Debug for String2