Struct compact_strings::CompactStrings

pub struct CompactStrings { /* private fields */ }

A cache-friendly but limited representation of a list of strings.

Strings are stored contiguously in a vector of bytes, with their lengths and starting indices being stored separately.

Limitations include being unable to mutate strings stored in the vector.

Examples

let mut cmpstrs = CompactStrings::with_capacity(10);

cmpstrs.push("One".to_string());
cmpstrs.push("Two".to_string());
cmpstrs.push("Three".to_string());

cmpstrs.remove(1);

assert_eq!(cmpstrs.get(0), Some("One"));
assert_eq!(cmpstrs.get(1), Some("Three"));
assert_eq!(cmpstrs.get(2), None);

Implementations

impl CompactStrings

pub const fn new() -> Self

Constructs a new, empty CompactStrings.

The CompactStrings will not allocate until strings are pushed into it.

Examples

let mut cmpstrs = CompactStrings::new();

pub fn with_capacity(capacity: usize) -> Self

Constructs a new, empty CompactStrings with at least the specified capacity in the inner vector where the bytes of the strings are stored.

Note that this does not affect the indices and lengths vectors which store information about where each string is stored.

The CompactStrings will be able to hold at least capacity bytes worth of strings without reallocating the inner vector. This method is allowed to allocate for more bytes than capacity. If capacity is 0, the inner vector will not allocate.

It is important to note that although the returned vector has the minimum capacity specified, the inner vector will have a zero length.

If it is important to know the exact allocated capacity of the inner vector, always use the capacity method after construction.

Examples

let mut cmpstrs = CompactStrings::with_capacity(10);

assert_eq!(cmpstrs.len(), 0);
assert!(cmpstrs.capacity() >= 10);

pub fn push(&mut self, string: String)

Appends a string to the back of the CompactStrings.

Examples

let mut cmpstrs = CompactStrings::new();
cmpstrs.push("One".to_string());
cmpstrs.push("Two".to_string());
cmpstrs.push("Three".to_string());

assert_eq!(cmpstrs.get(0), Some("One"));
assert_eq!(cmpstrs.get(1), Some("Two"));
assert_eq!(cmpstrs.get(2), Some("Three"));
assert_eq!(cmpstrs.get(3), None);

pub fn get(&self, index: usize) -> Option<&str>

Returns a reference to the string stored in the CompactStrings at that position.

Examples

let mut cmpstrs = CompactStrings::new();
cmpstrs.push("One".to_string());
cmpstrs.push("Two".to_string());
cmpstrs.push("Three".to_string());

assert_eq!(cmpstrs.get(0), Some("One"));
assert_eq!(cmpstrs.get(1), Some("Two"));
assert_eq!(cmpstrs.get(2), Some("Three"));
assert_eq!(cmpstrs.get(3), None);

pub unsafe fn get_unchecked(&self, index: usize) -> &str

Returns a reference to the string stored in the CompactStrings at that position, without doing bounds checking.

Safety

Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used.

Examples

let mut cmpstrs = CompactStrings::new();
cmpstrs.push("One".to_string());
cmpstrs.push("Two".to_string());
cmpstrs.push("Three".to_string());

unsafe {
    assert_eq!(cmpstrs.get_unchecked(0), "One");
    assert_eq!(cmpstrs.get_unchecked(1), "Two");
    assert_eq!(cmpstrs.get_unchecked(2), "Three");
}

pub fn len(&self) -> usize

Returns the number of strings in the CompactStrings, also referred to as its ‘length’.

Examples

let mut cmpstrs = CompactStrings::new();

cmpstrs.push("One".to_string());
cmpstrs.push("Two".to_string());
cmpstrs.push("Three".to_string());

assert_eq!(cmpstrs.len(), 3);

pub fn is_empty(&self) -> bool

Returns true if the CompactStrings contains no strings.

Examples

let mut cmpstrs = CompactStrings::new();
assert!(cmpstrs.is_empty());

cmpstrs.push("One".to_string());

assert!(!cmpstrs.is_empty());

pub fn capacity(&self) -> usize

Returns the number of bytes the inner vector can store without reallocating.

Examples

let mut cmpstrs = CompactStrings::with_capacity(10);

cmpstrs.push("One".to_string());

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

pub fn clear(&mut self)

Clears the CompactStrings, removing all strings.

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

Examples

let mut cmpstrs = CompactStrings::new();

cmpstrs.push("One".to_string());
cmpstrs.push("Two".to_string());
cmpstrs.push("Three".to_string());
cmpstrs.clear();

assert!(cmpstrs.is_empty());

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the inner vector, which stores the bytes of the held strings, as much as possible.

It will drop down as close as possible to the length but the allocator may still inform the vector that there is space for a few more elements.

Examples

let mut cmpstrs = CompactStrings::with_capacity(10);

cmpstrs.push("One".to_string());
cmpstrs.push("Two".to_string());
cmpstrs.push("Three".to_string());

assert!(cmpstrs.capacity() >= 10);
cmpstrs.shrink_to_fit();
assert!(cmpstrs.capacity() >= 3);

pub fn shrink_to(&mut self, min_capacity: usize)

Shrinks the capacity of the inner vector, which stores the bytes of the held strings, with a lower bound.

The capacity will remain at least as large as both the length and the supplied value.

If the current capacity is less than the lower limit, this is a no-op.

Examples

let mut cmpstrs = CompactStrings::with_capacity(10);

cmpstrs.push("One".to_string());
cmpstrs.push("Two".to_string());
cmpstrs.push("Three".to_string());

assert!(cmpstrs.capacity() >= 10);
cmpstrs.shrink_to(4);
assert!(cmpstrs.capacity() >= 4);

pub fn remove(&mut self, index: usize)

Removes the data pointing to where the string at the specified index is stored.

Note that this does not remove the bytes of the string from memory, you may want to use remove_full if you desire that behavior.

Examples

let mut cmpstrs = CompactStrings::with_capacity(10);

cmpstrs.push("One".to_string());
cmpstrs.push("Two".to_string());
cmpstrs.push("Three".to_string());

cmpstrs.remove(1);

assert_eq!(cmpstrs.get(0), Some("One"));
assert_eq!(cmpstrs.get(1), Some("Three"));
assert_eq!(cmpstrs.get(2), None);

pub fn remove_full(&mut self, index: usize)

Removes the data pointing to where the string at the specified index is stored.

Note that this also removes the bytes of the string from memory, which requires all bytes after the string to be shifted into the empty space, you may want to use remove if you do not desire that behavior.

Examples

let mut cmpstrs = CompactStrings::with_capacity(10);

cmpstrs.push("One".to_string());
cmpstrs.push("Two".to_string());
cmpstrs.push("Three".to_string());

cmpstrs.remove_full(1);

assert_eq!(cmpstrs.get(0), Some("One"));
assert_eq!(cmpstrs.get(1), Some("Three"));
assert_eq!(cmpstrs.get(2), None);

Trait Implementations

impl Index<usize> for CompactStrings

type Output = str

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<'a> IntoIterator for &'a CompactStrings

type Item = &'a str

The type of the elements being iterated over.

type IntoIter = CompactStringIterator<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.