Struct OrderedMap 

pub struct OrderedMap<V> { /* private fields */ }

A map from String to V that remembers the order its keys arrived in.

use structio::OrderedMap;

let mut map = OrderedMap::new();
map.insert("zeta".to_string(), 1);
map.insert("alpha".to_string(), 2);
map.insert("zeta".to_string(), 3); // replaces, keeps position

assert_eq!(map.get("zeta"), Some(&3));
assert_eq!(
    map.keys().map(String::as_str).collect::<Vec<_>>(),
    ["zeta", "alpha"]
);

See the module docs for how lookups work and what the ordering does and does not extend to.

Implementations

impl<V> OrderedMap<V>

pub fn new() -> Self

An empty map. Allocates nothing.

pub fn with_capacity(capacity: usize) -> Self

An empty map with room for capacity entries.

The table is not allocated here, however large the capacity. A table that exists describes every entry, so one built ahead of the entries would have to be maintained through the first eight inserts that the whole point of LINEAR_MAX is to leave alone; the map builds it at the entry that first needs it, sized from the entries it actually holds.

pub fn capacity(&self) -> usize

How many entries the map can hold before it reallocates.

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

Reserve room for additional more entries.

pub fn len(&self) -> usize

The number of entries.

pub fn is_empty(&self) -> bool

Whether the map holds nothing.

pub fn clear(&mut self)

Drop every entry, keeping the entries’ allocated capacity.

The table goes, since an empty map scans; a map refilled to past LINEAR_MAX builds a new one.

pub fn get(&self, key: &str) -> Option<&V>

A reference to the value key maps to.

pub fn get_mut(&mut self, key: &str) -> Option<&mut V>

A mutable reference to the value key maps to.

The key itself is never handed out mutably: changing it would move the entry to a different place in the index without moving the slot that points at it.

pub fn get_key_value(&self, key: &str) -> Option<(&str, &V)>

The stored key and its value.

The key comes back as &str rather than &String, as it does from every other accessor here; only Self::iter hands out &String, because the writers take their entries that way.

pub fn contains_key(&self, key: &str) -> bool

Whether key is present.

pub fn insert(&mut self, key: String, value: V) -> Option<V>

Insert a key and value, returning the previous value if the key was already present.

A duplicate key keeps the position it already had: the map records where a key first appeared, and writing to it again is not a reason to move it. This is the one difference from BTreeMap::insert, which has no position to keep.

There is no separate duplicate check to pay for. The probe that would find an existing key is the same probe that finds the bucket a new one goes in, so an insert costs one walk of the table either way.

pub fn remove(&mut self, key: &str) -> Option<V>

Remove key, returning its value.

Entries after it shift down to close the gap, which is O(n) and is what keeps the order intact. A swap with the last entry would be O(1) and would scramble exactly the thing this map exists to preserve.

pub fn remove_entry(&mut self, key: &str) -> Option<(String, V)>

Remove key, returning the stored key along with its value.

pub fn retain<F>(&mut self, f: F)

where F: FnMut(&str, &mut V) -> bool,

Keep only the entries f returns true for, in order.

pub fn sort_keys(&mut self)

Reorder the entries by key.

The escape hatch for a caller who wants a BTreeMap’s output: sort once, deliberately, instead of paying for an ordering on every read. The order the map was built in is gone afterwards.

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

The key and value at position index, in insertion order.

pub fn get_index_mut(&mut self, index: usize) -> Option<(&str, &mut V)>

The key and mutable value at position index, in insertion order.

pub fn first(&self) -> Option<(&str, &V)>

The first entry, or None if the map is empty.

pub fn last(&self) -> Option<(&str, &V)>

The last entry, or None if the map is empty.

pub fn entry(&mut self, key: String) -> Entry<'_, V>

The entry for key, occupied or vacant.

Takes an owned key because a vacant entry will store it, and looking up by &str first only to allocate the same string afterwards is the cost this avoids.

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

The entries, in insertion order.

Yields (&String, &V) rather than &(String, V), which is the shape the JSON and BEVE writers take their keyed entries in, so a map goes straight into one.

pub fn iter_mut(&mut self) -> IterMut<'_, V>

The entries with mutable values, in insertion order.

pub fn keys(&self) -> Keys<'_, V>

The keys, in insertion order.

pub fn values(&self) -> Values<'_, V>

The values, in insertion order.

pub fn values_mut(&mut self) -> ValuesMut<'_, V>

The values, mutably, in insertion order.

Trait Implementations

impl<V: Clone> Clone for OrderedMap<V>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<V: Debug> Debug for OrderedMap<V>

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

Formats the value using the given formatter.

impl<V> Default for OrderedMap<V>

fn default() -> Self

Returns the “default value” for a type.

impl<V: Eq> Eq for OrderedMap<V>

Sound because keys are unique: equal lengths plus a value-for-value match in one direction is a bijection, so the relation is symmetric and transitive.

impl<V> Extend<(String, V)> for OrderedMap<V>

fn extend<I: IntoIterator<Item = (String, V)>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: T)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl From<OrderedMap<Value>> for Value

fn from(v: Object) -> Self

Converts to this type from the input type.

impl<V, const N: usize> From<[(String, V); N]> for OrderedMap<V>

fn from(entries: [(String, V); N]) -> Self

Converts to this type from the input type.

impl<V> FromIterator<(String, V)> for OrderedMap<V>

fn from_iter<I: IntoIterator<Item = (String, V)>>(iter: I) -> Self

Creates a value from an iterator.

impl<V> Index<&str> for OrderedMap<V>

fn index(&self, key: &str) -> &V

Panics

If the key is not present. Use OrderedMap::get for a map that may not have it.

type Output = V

The returned type after indexing.

impl<V> IntoIterator for OrderedMap<V>

type Item = (String, V)

The type of the elements being iterated over.

type IntoIter = IntoIter<V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, V> IntoIterator for &'a OrderedMap<V>

type Item = (&'a String, &'a V)

The type of the elements being iterated over.

type IntoIter = Iter<'a, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, V> IntoIterator for &'a mut OrderedMap<V>

type Item = (&'a String, &'a mut V)

The type of the elements being iterated over.

type IntoIter = IterMut<'a, V>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<V: PartialEq> PartialEq for OrderedMap<V>

Equality is over the entries, not over their order: see the module docs.

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<'de, V: Read<'de> + Default> Read<'de> for OrderedMap<V>

OrderedMap keeps the order its members arrived in, which is what makes it the map behind Object.

Hand-written rather than an arm of impl_map!: that macro is generic over the key type, and this map’s key is always a String. It reserves on the member count, as the hashed map does, since its entries live in one vector.

fn read<O: Options>(&mut self, r: &mut Reader<'de, O>) -> Result<(), ErrorCode>

Read into self, from the reader’s current position.

fn read_bulk<O: Options>( _out: &mut Vec<Self>, _n: usize, _elem: u8, _r: &mut Reader<'de, O>, ) -> Result<bool, ErrorCode>

Fill out from the payload of a typed array of n elements whose element header is elem, or return false to decline.

impl<'de, V: Read<'de> + Default> Read<'de> for OrderedMap<V>

OrderedMap keeps the order its members arrived in, which is what makes it the map behind Object.

Hand-written rather than an arm of impl_map!: that macro is generic over the key type, and this map’s key is always a String.

fn read<O: Options>(&mut self, p: &mut Parser<'de, O>) -> Result<(), ErrorCode>

Parse into self, from the cursor’s current position.

impl<'de, VA, V: Default> ReadAs<'de, OrderedMap<V>> for OrderedMap<VA>

where VA: ReadAs<'de, V>,

OrderedMap’s adapter form takes one adapter rather than two, since its key type is fixed: the object header is always the string-keyed one, and the keys go through String’s own FromBeveKey/ToBeveKey.

fn read<O: Options>( value: &mut OrderedMap<V>, r: &mut Reader<'de, O>, ) -> Result<(), ErrorCode>

Read into value, from the reader’s current position.

fn read_bulk<O: Options>( _out: &mut Vec<T>, _n: usize, _elem: u8, _r: &mut Reader<'de, O>, ) -> Result<bool, ErrorCode>

Fill out from the payload of a typed array of n elements whose element header is elem, or return false to decline.

impl<'de, VA, V: Default> ReadAs<'de, OrderedMap<V>> for OrderedMap<VA>

where VA: ReadAs<'de, V>,

OrderedMap’s adapter form takes one adapter rather than two, since its key type is fixed: OrderedMap<Millis> adapts the values and leaves the keys to String’s own FromJsonKey/ToJsonKey.

fn read<O: Options>( value: &mut OrderedMap<V>, p: &mut Parser<'de, O>, ) -> Result<(), ErrorCode>

Read into value, from the cursor’s current position.

impl<V: Write> Write for OrderedMap<V>

fn write<O: Options>(&self, w: &mut Writer<'_, O>)

fn is_null(&self) -> bool

Whether this value is absent, and so is left out of an object under Options::SKIP_NULL.

const ARRAY: Option<&'static [u8]> = None

The header bytes a contiguous run of this type is stored under, or None if it has no array form of its own and belongs in a generic one.

fn write_payload<O: Options>(items: &[Self], w: &mut Writer<'_, O>)

where Self: Sized,

Append items as the payload of a typed array whose header and count the caller has already written.

impl<V: Write> Write for OrderedMap<V>

fn write<O: Options>(&self, w: &mut Writer<'_, O>)

fn is_null(&self) -> bool

Whether this value is absent, and so is left out of an object under Options::SKIP_NULL.

impl<VA, V> WriteAs<OrderedMap<V>> for OrderedMap<VA>

where VA: WriteAs<V>,

fn write<O: Options>(value: &OrderedMap<V>, w: &mut Writer<'_, O>)

Write value.

fn is_null(value: &T) -> bool

Whether the field is absent, and so is left out of an object under Options::SKIP_NULL.

const ARRAY: Option<&'static [u8]> = None

The adapter’s answer to Write::ARRAY: the header bytes a contiguous run of adapted values is stored under, or None for a generic array.

fn write_payload<O: Options>(items: &[T], w: &mut Writer<'_, O>)

where T: Sized,

Append items as the payload of a typed array whose header and count the caller has already written.

impl<VA, V> WriteAs<OrderedMap<V>> for OrderedMap<VA>

where VA: WriteAs<V>,

fn write<O: Options>(value: &OrderedMap<V>, w: &mut Writer<'_, O>)

Write value.

fn is_null(value: &T) -> bool

Whether the field is absent, and so is left out of an object under Options::SKIP_NULL.