Struct compact_strings::FixedCompactStrings

source ·

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

Expand description

An even more compact but limited representation of a list of strings.

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

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

§Examples

let mut cmpstrs = FixedCompactStrings::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 FixedCompactStrings

source

pub const fn new() -> Self

Constructs a new, empty FixedCompactStrings.

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

§Examples

let mut cmpstrs = FixedCompactStrings::new();

source

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

Constructs a new, empty FixedCompactStrings 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 of the strings are stored.

The FixedCompactStrings 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 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 = FixedCompactStrings::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 FixedCompactStrings.

§Examples

let mut cmpstrs = FixedCompactStrings::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 FixedCompactStrings at that position.

§Examples

let mut cmpstrs = FixedCompactStrings::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 FixedCompactStrings 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 = FixedCompactStrings::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 FixedCompactStrings, also referred to as its ‘length’.

§Examples

let mut cmpstrs = FixedCompactStrings::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 FixedCompactStrings contains no strings.

§Examples

let mut cmpstrs = FixedCompactStrings::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 = FixedCompactStrings::with_capacity(20, 3);

cmpstrs.push("One");

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

source

pub fn capacity_meta(&self) -> usize

Returns the number of starting indices can store without reallocating.

§Examples

let mut cmpstrs = FixedCompactStrings::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 FixedCompactStrings, removing all strings.

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

§Examples

let mut cmpstrs = FixedCompactStrings::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 = FixedCompactStrings::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 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 = FixedCompactStrings::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 = FixedCompactStrings::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 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 = FixedCompactStrings::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 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).

§Examples

let mut cmpstrs = FixedCompactStrings::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 = FixedCompactStrings::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);