Type Definition generic_str::OwnedString

pub type OwnedString<T, S> = StringBase<GenericVec<T, S>>;

Implementations

impl<S: ?Sized + Storage<Item = char>> OwnedString<char, S>

pub fn push_str32(&mut self, string: &str32)

Appends a given string slice onto the end of this String.

Examples

Basic usage:

let mut s = String32::from("foo");
let t = String32::from("bar");

s.push_str32(&t);

assert_eq!(s, String32::from("foobar"));

pub fn push(&mut self, ch: char)

Appends the given char to the end of this String.

Examples

Basic usage:

let mut s = String32::new();

s.push('1');
s.push('2');
s.push('3');

assert_eq!(s, String32::from("123"));

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

Removes the last character from the string buffer and returns it.

Returns None if this String is empty.

Examples

Basic usage:

let mut s = String32::from("foo");

assert_eq!(s.pop(), Some('o'));
assert_eq!(s.pop(), Some('o'));
assert_eq!(s.pop(), Some('f'));

assert_eq!(s.pop(), None);

pub fn truncate(&mut self, new_len: usize)

Shortens this String to the specified length.

If new_len is greater than the string’s current length, this has no effect.

Note that this method has no effect on the allocated capacity of the string

Panics

Panics if new_len does not lie on a char boundary.

Examples

Basic usage:

let mut s = String32::from("hello");

s.truncate(2);

assert_eq!(s, String32::from("he"));

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

Removes a char from this String at a byte position and returns it.

This is an O(n) operation, as it requires copying every element in the buffer.

Panics

Panics if idx is larger than or equal to the String’s length, or if it does not lie on a char boundary.

Examples

Basic usage:

let mut s = String32::from("foo");

assert_eq!(s.remove(0), 'f');
assert_eq!(s.remove(1), 'o');
assert_eq!(s.remove(0), 'o');

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

Inserts a character into this String at a byte position.

This is an O(n) operation as it requires copying every element in the buffer.

Panics

Panics if idx is larger than the String’s length, or if it does not lie on a char boundary.

Examples

Basic usage:

let mut s = String32::with_capacity(3);

s.insert(0, 'f');
s.insert(1, 'o');
s.insert(2, 'o');

assert_eq!(s, String32::from("foo"));

pub fn as_mut_vec(&mut self) -> &mut GenericVec<S::Item, S>

Returns a mutable reference to the contents of this String.

Examples

Basic usage:

let mut s = String32::from("hello");

unsafe {
    let vec = s.as_mut_vec();
    assert_eq!(&['h', 'e', 'l', 'l', 'o'][..], &vec[..]);

    vec.reverse();
}
assert_eq!(s, String32::from("olleh"));

pub fn split_off<B: ?Sized + StorageWithCapacity<Item = char>>(
    &mut self,
    at: usize
) -> OwnedString<char, B>

Splits the string into two at the given byte index.

Returns a newly allocated String. self contains bytes [0, at), and the returned String contains bytes [at, len). at must be on the boundary of a UTF-8 code point.

Note that the capacity of self does not change.

Panics

Panics if at is not on a UTF-8 code point boundary, or if it is beyond the last code point of the string.

Examples

let mut hello = String32::from("Hello, World!");
let world: String32 = hello.split_off(7);
assert_eq!(hello, String32::from("Hello, "));
assert_eq!(world, String32::from("World!"));

pub fn clear(&mut self)

Truncates this String, removing all contents.

While this means the String will have a length of zero, it does not touch its capacity.

Examples

Basic usage:

let mut s = String32::from("foo");
let cap = s.capacity();

s.clear();

assert!(s.is_empty());
assert_eq!(0, s.len());
assert_eq!(cap, s.capacity());

pub fn capacity(&self) -> usize

Returns this String’s capacity, in bytes.

Examples

Basic usage:

let s = String32::with_capacity(10);

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

impl<S: ?Sized + Storage<Item = u8>> OwnedString<u8, S>

pub fn from_utf8(vec: GenericVec<S::Item, S>) -> Result<Self, FromUtf8Error<S>> where
    S: Sized, 

Converts a vector of bytes to a String.

A string (String) is made of bytes (u8), and a vector of bytes (Vec<u8>) is made of bytes, so this function converts between the two. Not all byte slices are valid Strings, however: String requires that it is valid UTF-8. from_utf8() checks to ensure that the bytes are valid UTF-8, and then does the conversion.

If you are sure that the byte slice is valid UTF-8, and you don’t want to incur the overhead of the validity check, there is an unsafe version of this function, from_utf8_unchecked, which has the same behavior but skips the check.

This method will take care to not copy the vector, for efficiency’s sake.

If you need a &str instead of a String, consider from_utf8.

The inverse of this method is into_bytes.

Errors

Returns Err if the slice is not UTF-8 with a description as to why the provided bytes are not UTF-8. The vector you moved in is also included.

Examples

Basic usage:

// some bytes, in a vector
let sparkle_heart = vec![240, 159, 146, 150];

// We know these bytes are valid, so we'll use `unwrap()`.
let sparkle_heart = String::from_utf8(sparkle_heart.into()).unwrap();

assert_eq!(sparkle_heart, <&str>::from("💖"));

Incorrect bytes:

// some invalid bytes, in a vector
let sparkle_heart = vec![0, 159, 146, 150];

assert!(String::from_utf8(sparkle_heart.into()).is_err());

See the docs for FromUtf8Error for more details on what you can do with this error.

pub unsafe fn from_utf8_unchecked(vec: GenericVec<S::Item, S>) -> Self where
    S: Sized, 

Converts a vector of bytes to a String without checking that the string contains valid UTF-8.

See the safe version, from_utf8, for more details.

Safety

This function is unsafe because it does not check that the bytes passed to it are valid UTF-8. If this constraint is violated, it may cause memory unsafety issues with future users of the String, as the rest of the standard library assumes that Strings are valid UTF-8.

Examples

Basic usage:

// some bytes, in a vector
let sparkle_heart = vec![240, 159, 146, 150];

let sparkle_heart = unsafe {
    String::from_utf8_unchecked(sparkle_heart.into())
};

assert_eq!(sparkle_heart, <&str>::from("💖"));

pub fn into_bytes(self) -> GenericVec<S::Item, S> where
    S: Sized, 

Converts a String into a byte vector.

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

Examples

Basic usage:

let s = String::from("hello");
let bytes = s.into_bytes();

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

pub fn as_str(&self) -> &str

Extracts a string slice containing the entire String.

Examples

Basic usage:

let s = String::from("foo");

assert_eq!(s.as_str(), <&str>::from("foo"));

pub fn as_mut_str(&mut self) -> &mut str

Converts a String into a mutable string slice.

Examples

Basic usage:

let mut s = String::from("foobar");
let s_mut_str = s.as_mut_str();

s_mut_str.make_ascii_uppercase();

assert_eq!(s_mut_str, <&str>::from("FOOBAR"));

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

Appends a given string slice onto the end of this String.

Examples

Basic usage:

let mut s = String::from("foo");

s.push_str("bar".into());

assert_eq!(s, <&str>::from("foobar"));

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

Ensures that this String’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.

Panics

Panics if the new capacity overflows usize.

Examples

Basic usage:

let mut s = String::new();

s.reserve(10);

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

This may not actually increase the capacity:

let mut s = String::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 try_reserve(&mut self, additional: usize) -> AllocResult

Tries to reserve capacity for at least additional more elements to be inserted in the given String. The collection may reserve more space to avoid frequent reallocations. After calling reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if capacity is already sufficient.

Errors

If the capacity overflows, or the allocator reports a failure, then an error is returned.

pub fn push(&mut self, ch: char)

Appends the given char to the end of this String.

Examples

Basic usage:

let mut s = String::from("abc");

s.push('1');
s.push('2');
s.push('3');

assert_eq!(s, <&str>::from("abc123"));

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

Removes the last character from the string buffer and returns it.

Returns None if this String is empty.

Examples

Basic usage:

let mut s = String::from("foo");

assert_eq!(s.pop(), Some('o'));
assert_eq!(s.pop(), Some('o'));
assert_eq!(s.pop(), Some('f'));

assert_eq!(s.pop(), None);

pub fn truncate(&mut self, new_len: usize)

Shortens this String to the specified length.

If new_len is greater than the string’s current length, this has no effect.

Note that this method has no effect on the allocated capacity of the string

Panics

Panics if new_len does not lie on a char boundary.

Examples

Basic usage:

let mut s = String::from("hello");

s.truncate(2);

assert_eq!(s, <&str>::from("he"));

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

Removes a char from this String at a byte position and returns it.

This is an O(n) operation, as it requires copying every element in the buffer.

Panics

Panics if idx is larger than or equal to the String’s length, or if it does not lie on a char boundary.

Examples

Basic usage:

let mut s = String::from("foo");

assert_eq!(s.remove(0), 'f');
assert_eq!(s.remove(1), 'o');
assert_eq!(s.remove(0), 'o');

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

Inserts a character into this String at a byte position.

This is an O(n) operation as it requires copying every element in the buffer.

Panics

Panics if idx is larger than the String’s length, or if it does not lie on a char boundary.

Examples

Basic usage:

let mut s = String::with_capacity(3);

s.insert(0, 'f');
s.insert(1, 'o');
s.insert(2, 'o');

assert_eq!(s, <&str>::from("foo"));

pub fn insert_str(&mut self, idx: usize, string: &str)

Inserts a string slice into this String at a byte position.

This is an O(n) operation as it requires copying every element in the buffer.

Panics

Panics if idx is larger than the String’s length, or if it does not lie on a char boundary.

Examples

Basic usage:

let mut s = String::from("bar");

s.insert_str(0, "foo");

assert_eq!(s, <&str>::from("foobar"));

pub unsafe fn as_mut_vec(&mut self) -> &mut GenericVec<S::Item, S>

Returns a mutable reference to the contents of this String.

Safety

This function is unsafe because it does not check that the bytes passed to it are valid UTF-8. If this constraint is violated, it may cause memory unsafety issues with future users of the String, as the rest of the standard library assumes that Strings are valid UTF-8.

Examples

Basic usage:

let mut s = String::from("hello");

unsafe {
    let vec = s.as_mut_vec();
    assert_eq!(&[104, 101, 108, 108, 111][..], &vec[..]);

    vec.reverse();
}
assert_eq!(s, <&str>::from("olleh"));

pub fn split_off<B: ?Sized + StorageWithCapacity<Item = u8>>(
    &mut self,
    at: usize
) -> StringBase<GenericVec<S::Item, B>>

Splits the string into two at the given byte index.

Returns a newly allocated String. self contains bytes [0, at), and the returned String contains bytes [at, len). at must be on the boundary of a UTF-8 code point.

Note that the capacity of self does not change.

Panics

Panics if at is not on a UTF-8 code point boundary, or if it is beyond the last code point of the string.

Examples

let mut hello = String::from("Hello, World!");
let world: String = hello.split_off(7);
assert_eq!(hello, <&str>::from("Hello, "));
assert_eq!(world, <&str>::from("World!"));

pub fn clear(&mut self)

Truncates this String, removing all contents.

While this means the String will have a length of zero, it does not touch its capacity.

Examples

Basic usage:

let mut s = String::from("foo");

s.clear();

assert!(s.is_empty());
assert_eq!(0, s.len());
assert_eq!(3, s.capacity());

pub fn capacity(&self) -> usize

Returns this String’s capacity, in bytes.

Examples

Basic usage:

let s = String::with_capacity(10);

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

Trait Implementations

impl<S: ?Sized + Storage<Item = char>> Debug for OwnedString<char, S>

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

Formats the value using the given formatter.

impl<S: ?Sized + Storage<Item = u8>> Debug for OwnedString<u8, S>

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

Formats the value using the given formatter.

impl<S: ?Sized + Storage<Item = char>> Display for OwnedString<char, S>

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

Formats the value using the given formatter.

impl<S: ?Sized + Storage<Item = u8>> Display for OwnedString<u8, S>

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

Formats the value using the given formatter.

impl<S: ?Sized + Storage> Ord for OwnedString<S::Item, S> where
    S::Item: Ord, 

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

Restrict a value to a certain interval.

impl<S: ?Sized + Storage> PartialEq<&'_ StringBase<[<S as Storage>::Item]>> for OwnedString<S::Item, S> where
    S::Item: PartialEq, 

fn eq(&self, other: &&StringSlice<S::Item>) -> 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<S: ?Sized + Storage> PartialEq<StringBase<[<S as Storage>::Item]>> for OwnedString<S::Item, S> where
    S::Item: PartialEq, 

fn eq(&self, other: &StringSlice<S::Item>) -> 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<S: ?Sized + Storage> PartialOrd<&'_ StringBase<[<S as Storage>::Item]>> for OwnedString<S::Item, S> where
    S::Item: PartialOrd, 

fn partial_cmp(&self, other: &&StringSlice<S::Item>) -> 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<S: ?Sized + Storage> PartialOrd<StringBase<[<S as Storage>::Item]>> for OwnedString<S::Item, S> where
    S::Item: PartialOrd, 

fn partial_cmp(&self, other: &StringSlice<S::Item>) -> 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<S: ?Sized + Storage, T: ?Sized + Storage> PartialOrd<StringBase<GenericVec<<T as Storage>::Item, T>>> for OwnedString<S::Item, S> where
    GenericVec<S::Item, S>: PartialOrd<GenericVec<T::Item, T>>, 

fn partial_cmp(&self, other: &OwnedString<T::Item, T>) -> 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<S: ?Sized + Storage> Eq for OwnedString<S::Item, S> where
    S::Item: Eq,