Struct CompactStrings

Source

pub struct CompactStrings(/* private fields */);

Expand description

A more compact 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(20, 3);

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

cmpstrs.remove(1);

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

Implementations§

Source §

impl CompactStrings

Source

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

Source

pub fn with_capacity(data_capacity: usize, capacity_meta: usize) -> Self

Constructs a new, empty CompactStrings with at least the specified capacities in each vector.

data_capacity: The capacity of the data vector where the bytes of the strings are stored.
capacity_meta: The capacity of the meta vector where the starting indices and lengths of the strings are stored.

The CompactStrings will be able to hold at least data_capacity bytes worth of strings without reallocating the data vector, and at least capacity_meta of starting indices and lengths without reallocating the meta vector. This method is allowed to allocate for more bytes than the capacities. If a capacity is 0, the vector will not allocate.

It is important to note that although the data and meta vectors have the minimum capacities specified, they will have a zero length.

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

§Examples

let mut cmpstrs = CompactStrings::with_capacity(20, 3);

assert_eq!(cmpstrs.len(), 0);
assert!(cmpstrs.capacity() >= 20);
assert!(cmpstrs.capacity_meta() >= 3);

Source

pub fn push<S>(&mut self, string: S)
where S: Deref<Target = str>,

Appends a string to the back of the CompactStrings.

§Examples

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

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

Source

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");
cmpstrs.push("Two");
cmpstrs.push("Three");

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

Source

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");
cmpstrs.push("Two");
cmpstrs.push("Three");

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

Source

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");
cmpstrs.push("Two");
cmpstrs.push("Three");

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

Source

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

assert!(!cmpstrs.is_empty());

Source

pub fn capacity(&self) -> usize

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

§Examples

let mut cmpstrs = CompactStrings::with_capacity(20, 3);

cmpstrs.push("One");

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

Source

pub fn capacity_meta(&self) -> usize

Returns the number of starting indices and lengths can store without reallocating.

§Examples

let mut cmpstrs = CompactStrings::with_capacity(20, 3);

cmpstrs.push("One");
cmpstrs.push("Two");
cmpstrs.push("Three");
assert!(cmpstrs.capacity_meta() >= 3);

cmpstrs.push("Three");
assert!(cmpstrs.capacity_meta() > 3);

Source

pub fn clear(&mut self)

Clears the CompactStrings, removing all strings.

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

§Examples

let mut cmpstrs = CompactStrings::new();

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

assert!(cmpstrs.is_empty());

Source

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the data 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(20, 3);

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

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

Source

pub fn shrink_meta_to_fit(&mut self)

Shrinks the capacity of the info vector, which stores the starting indices and lengths 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(20, 10);

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

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

Source

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

Shrinks the capacity of the data 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(20, 4);

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

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

Source

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

Shrinks the capacity of the meta vector, which starting indices and lengths 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(20, 10);

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

assert!(cmpstrs.capacity_meta() >= 10);
cmpstrs.shrink_meta_to(4);
assert!(cmpstrs.capacity_meta() >= 4);

Source

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

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

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

Note: Because this shifts over the remaining elements in the meta vector, it has a worst-case performance of O(n).

§Examples

let mut cmpstrs = CompactStrings::with_capacity(20, 3);

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

cmpstrs.ignore(1);

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

Source

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

Removes the bytes of the string and data pointing to the string is stored.

Note: This does not shrink the vectors where the bytes of the string and data to the string are stored. You may shrink the data vector with shrink_to and shrink_to_fit and the meta vector with shrink_meta_to and shrink_meta_to_fit.

Note: Because this shifts over the remaining elements in both data and meta vectors, it has a worst-case performance of O(n). If you don’t need the bytes of the string to be removed, use ignore instead.

§Examples

let mut cmpstrs = CompactStrings::with_capacity(20, 3);

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

cmpstrs.remove(1);

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

Source

pub fn iter(&self) -> Iter<'_>

Returns an iterator over the slice.

The iterator yields all items from start to end.

§Examples

let mut cmpstrs = CompactStrings::with_capacity(20, 3);
cmpstrs.push("One");
cmpstrs.push("Two");
cmpstrs.push("Three");
let mut iterator = cmpstrs.iter();

assert_eq!(iterator.next(), Some("One"));
assert_eq!(iterator.next(), Some("Two"));
assert_eq!(iterator.next(), Some("Three"));
assert_eq!(iterator.next(), None);