document EntityBundleMap and EntityBitVec

Author: meithecatte

public/entity/src/bitvec.rs

@@ -1,3 +1,4 @@
+//! A [`BitVec`] with strongly-typed indices.
 use core::hash::Hash;
 use core::marker::PhantomData;
 use core::ops::Index;
@@ -10,6 +11,7 @@ use crate::id::EntityRange;
 use bitvec::order::Lsb0;
 use bitvec::vec::BitVec;
 
+/// A [`BitVec`] with strongly-typed indices.
 #[derive(Clone, Eq, PartialEq, Hash)]
 pub struct EntityBitVec<I: EntityId> {
     vals: BitVec,
@@ -124,6 +126,13 @@ impl<I: EntityId> EntityBitVec<I> {
         res
     }
 
+    /// Create a bitvector of size `len`, and fill it with the data from `buf`, starting from the
+    /// least significant bit of each byte.
+    ///
+    /// ## Panics
+    ///
+    /// `buf` must have enough data to fill `len` bits, and there must be less than a full byte
+    /// left over. Panics if this is not the case.
     fn from_bytes(buf: &[u8], len: usize) -> Self {
         assert_eq!(buf.len(), len.div_ceil(8));
         let mut res = BitVec::repeat(false, len);

public/entity/src/bundle_map.rs

@@ -1,28 +1,48 @@
+//! A map where each key-value pair is assigned a contiguous range of IDs.
 use crate::{EntityId, EntityRange, EntityVec, EntityMap};
 use crate::map::Entry;
 use crate::id::{EntityTag, EntityIdU32};
 
+/// Indices occupied by a given bundle.
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
-pub enum EntityBundleIndex<I: EntityId> {
+pub enum EntityBundleIndices<I: EntityId> {
+    /// Singular index occupied by a unit-shaped bundle.
     Single(I),
+    /// Range of indices occupied by an array-shaped bundle.
     Array(EntityRange<I>),
 }
 
+/// An index within a particular bundle.
 #[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub enum EntityBundleItemIndex {
+    /// The bundle is unit-shaped, thus we shall meow no further of indices within it.
     Single,
-    Array { index: usize, total: usize },
+    /// The bundle is array-shaped.
+    Array {
+        /// The index within the array.
+        index: usize,
+        /// The total size of the array.
+        total: usize,
+    },
 }
 
 struct BundleTag;
 impl EntityTag for BundleTag {}
 type BundleId = EntityIdU32<BundleTag>;
 
-/// A map where each `(K, V)` pair is assigned a contiguous range of IDs.
+/// A map where each key-value pair is assigned a contiguous range of IDs.
+///
+/// An `EntityBundleMap` is a collection of *bundles*. Each bundle consists of a key, a value,
+/// and a *range* of IDs assigned to it. The amount of IDs assigned to a bundle is determined by
+/// its *shape*: an array of a specified size, or just a single unit.
+///
+/// Note that we distinguish between a *single unit* and *an array of size one*. This is
+/// intentional, as this datastructure is used to implement data models that make this distinction,
+/// much like Rust makes a distinction between `u32` and `[u32; 1]`.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct EntityBundleMap<I: EntityId, T> {
     ids: EntityVec<I, BundleId>,
-    bundles: EntityMap<BundleId, String, (EntityBundleIndex<I>, T)>,
+    bundles: EntityMap<BundleId, String, (EntityBundleIndices<I>, T)>,
 }
 
 impl<I: EntityId, T> EntityBundleMap<I, T> {
@@ -33,6 +53,7 @@ impl<I: EntityId, T> EntityBundleMap<I, T> {
         }
     }
 
+    /// Returns the number of allocated IDs, i.e. the total size of all the bundles.
     pub fn len(&self) -> usize {
         self.ids.len()
     }
@@ -45,12 +66,13 @@ impl<I: EntityId, T> EntityBundleMap<I, T> {
         self.ids.ids()
     }
 
-    pub fn get(&self, key: &str) -> Option<(EntityBundleIndex<I>, &T)> {
+    /// Retrieve a bundle by its key.
+    pub fn get(&self, key: &str) -> Option<(EntityBundleIndices<I>, &T)> {
         let (_, (idx, val)) = self.bundles.get(key)?;
         Some((*idx, val))
     }
 
-    pub fn get_mut(&mut self, key: &str) -> Option<(EntityBundleIndex<I>, &mut T)> {
+    pub fn get_mut(&mut self, key: &str) -> Option<(EntityBundleIndices<I>, &mut T)> {
         let (_, (idx, val)) = self.bundles.get_mut(key)?;
         Some((*idx, val))
     }
@@ -59,16 +81,18 @@ impl<I: EntityId, T> EntityBundleMap<I, T> {
         self.bundles.contains_key(key)
     }
 
+    /// Given an ID, returns the key of the bundle which owns that ID, as well as the particular
+    /// position within the bundle that corresponds to the ID.
     pub fn key(&self, id: I) -> (&str, EntityBundleItemIndex) {
         let idx = self.ids[id];
         let key = self.bundles.key(idx);
         let (bidx, _) = self.bundles[idx];
         match bidx {
-            EntityBundleIndex::Single(sid) => {
+            EntityBundleIndices::Single(sid) => {
                 assert_eq!(id, sid);
                 (key, EntityBundleItemIndex::Single)
             }
-            EntityBundleIndex::Array(range) => (
+            EntityBundleIndices::Array(range) => (
                 key,
                 EntityBundleItemIndex::Array {
                     index: range.index_of(id).unwrap(),
@@ -78,17 +102,19 @@ impl<I: EntityId, T> EntityBundleMap<I, T> {
         }
     }
 
+    /// Insert a unit-shaped bundle.
     pub fn insert(&mut self, name: String, value: T) -> Option<I> {
         match self.bundles.entry(name) {
             Entry::Occupied(_) => None,
             Entry::Vacant(e) => {
                 let id = self.ids.push(e.index());
-                e.insert((EntityBundleIndex::Single(id), value));
+                e.insert((EntityBundleIndices::Single(id), value));
                 Some(id)
             }
         }
     }
 
+    /// Insert an array-shaped bundle.
     pub fn insert_array(&mut self, name: String, num: usize, value: T) -> Option<EntityRange<I>> {
         match self.bundles.entry(name) {
             Entry::Occupied(_) => None,
@@ -98,7 +124,7 @@ impl<I: EntityId, T> EntityBundleMap<I, T> {
                 for _ in 0..num {
                     self.ids.push(e.index());
                 }
-                e.insert((EntityBundleIndex::Array(range), value));
+                e.insert((EntityBundleIndices::Array(range), value));
                 Some(range)
             }
         }
@@ -111,19 +137,19 @@ impl<I: EntityId, T> EntityBundleMap<I, T> {
         })
     }
 
-    pub fn bundles(&self) -> impl Iterator<Item = (EntityBundleIndex<I>, &str, &T)> {
+    pub fn bundles(&self) -> impl Iterator<Item = (EntityBundleIndices<I>, &str, &T)> {
         self.bundles
             .iter()
             .map(|(_, k, (i, v))| (*i, k.as_str(), v))
     }
 
-    pub fn bundles_mut(&mut self) -> impl Iterator<Item = (EntityBundleIndex<I>, &str, &mut T)> {
+    pub fn bundles_mut(&mut self) -> impl Iterator<Item = (EntityBundleIndices<I>, &str, &mut T)> {
         self.bundles
             .iter_mut()
             .map(|(_, k, (i, v))| (*i, k.as_str(), v))
     }
 
-    pub fn into_bundles(self) -> impl Iterator<Item = (EntityBundleIndex<I>, String, T)> {
+    pub fn into_bundles(self) -> impl Iterator<Item = (EntityBundleIndices<I>, String, T)> {
         self.bundles.into_iter().map(|(_, k, (i, v))| (i, k, v))
     }
 }

public/entity/src/bundle_map/bincode.rs

@@ -1,6 +1,6 @@
 use bincode::{BorrowDecode, Decode, Encode};
 
-use crate::{EntityBundleIndex, EntityBundleMap, EntityId};
+use crate::{EntityBundleIndices, EntityBundleMap, EntityId};
 
 impl<I: EntityId, T: Encode> Encode for EntityBundleMap<I, T> {
     fn encode<E: bincode::enc::Encoder>(
@@ -10,8 +10,8 @@ impl<I: EntityId, T: Encode> Encode for EntityBundleMap<I, T> {
         self.bundles.len().encode(encoder)?;
         for (_, key, (idx, val)) in &self.bundles {
             let num = match idx {
-                EntityBundleIndex::Single(_) => None,
-                EntityBundleIndex::Array(range) => Some(range.len()),
+                EntityBundleIndices::Single(_) => None,
+                EntityBundleIndices::Array(range) => Some(range.len()),
             };
             num.encode(encoder)?;
             key.encode(encoder)?;

public/entity/src/lib.rs

@@ -15,7 +15,7 @@ pub mod set;
 
 #[cfg(feature = "map")]
 pub use {
-    bundle_map::EntityBundleIndex, bundle_map::EntityBundleItemIndex, bundle_map::EntityBundleMap,
+    bundle_map::EntityBundleIndices, bundle_map::EntityBundleItemIndex, bundle_map::EntityBundleMap,
     map::EntityMap, set::EntitySet,
 };
 

public/entity/src/map.rs

@@ -1,3 +1,4 @@
+//! An [`IndexMap`] with strongly-typed indices.
 use core::hash::{BuildHasher, Hash};
 use core::marker::PhantomData;
 use core::ops::{Index, IndexMut};

public/entity/src/set.rs

@@ -1,3 +1,4 @@
+//! An [`indexmap::IndexSet`] with strongly-typed indices.
 use core::hash::{BuildHasher, Hash};
 use core::marker::PhantomData;
 use core::ops::Index;

public/interconnect/src/dump.rs

@@ -2,7 +2,7 @@ use crate::db::{
     BelAttribute, BelAttributeType, BelInfo, BelKind, ConnectorWire, IntDb, PadKind, PinDir,
     SwitchBoxItem, TableValue, TileClass,
 };
-use prjcombine_entity::{EntityBundleIndex, EntityBundleItemIndex, EntityId};
+use prjcombine_entity::{EntityBundleIndices, EntityBundleItemIndex, EntityId};
 use prjcombine_types::bsdata::{PolTileBit, TileBit};
 use std::collections::BTreeMap;
 
@@ -552,8 +552,8 @@ impl IntDb {
                     nr = if pin.nonroutable { "nonroutable " } else { "" }
                 )?;
                 match index {
-                    EntityBundleIndex::Single(_) => writeln!(o, ";")?,
-                    EntityBundleIndex::Array(range) => {
+                    EntityBundleIndices::Single(_) => writeln!(o, ";")?,
+                    EntityBundleIndices::Array(range) => {
                         if pin.indexing == Default::default() {
                             writeln!(o, "[{n}];", n = range.len())?;
                         } else {
@@ -574,8 +574,8 @@ impl IntDb {
                     nr = if pin.nonroutable { "nonroutable " } else { "" }
                 )?;
                 match index {
-                    EntityBundleIndex::Single(_) => writeln!(o, ";")?,
-                    EntityBundleIndex::Array(range) => {
+                    EntityBundleIndices::Single(_) => writeln!(o, ";")?,
+                    EntityBundleIndices::Array(range) => {
                         if pin.indexing == Default::default() {
                             writeln!(o, "[{n}];", n = range.len())?;
                         } else {
@@ -596,8 +596,8 @@ impl IntDb {
                     nr = if pin.nonroutable { "nonroutable " } else { "" }
                 )?;
                 match index {
-                    EntityBundleIndex::Single(_) => writeln!(o, ";")?,
-                    EntityBundleIndex::Array(range) => {
+                    EntityBundleIndices::Single(_) => writeln!(o, ";")?,
+                    EntityBundleIndices::Array(range) => {
                         if pin.indexing == Default::default() {
                             writeln!(o, "[{n}];", n = range.len())?;
                         } else {
@@ -614,8 +614,8 @@ impl IntDb {
             for (index, pname, pad) in bcls.pads.bundles() {
                 write!(o, "\t\tpad {pname}")?;
                 match index {
-                    EntityBundleIndex::Single(_) => (),
-                    EntityBundleIndex::Array(range) => write!(o, "[{n}]", n = range.len())?,
+                    EntityBundleIndices::Single(_) => (),
+                    EntityBundleIndices::Array(range) => write!(o, "[{n}]", n = range.len())?,
                 }
                 writeln!(
                     o,

public/tablegen/src/emit.rs

@@ -1,6 +1,6 @@
 use std::str::FromStr;
 
-use prjcombine_entity::{EntityBundleIndex, EntityBundleMap, EntityId, EntityVec};
+use prjcombine_entity::{EntityBundleIndices, EntityBundleMap, EntityId, EntityVec};
 use prjcombine_interconnect::db::{BelPinIndexing, IntDb};
 use proc_macro::{Delimiter, Group, Ident, Literal, Punct, Spacing, Span, TokenStream, TokenTree};
 
@@ -67,7 +67,7 @@ fn emit_array_ids<I: EntityId>(
 
     for (index, _, ident) in idents.bundles() {
         match index {
-            EntityBundleIndex::Single(id) => {
+            EntityBundleIndices::Single(id) => {
                 res.extend([
                     keyword("pub"),
                     keyword("const"),
@@ -83,7 +83,7 @@ fn emit_array_ids<I: EntityId>(
                     punct(';'),
                 ]);
             }
-            EntityBundleIndex::Array(range) => {
+            EntityBundleIndices::Array(range) => {
                 res.extend([
                     keyword("pub"),
                     keyword("const"),
@@ -128,10 +128,10 @@ fn emit_pin_array_ids<I: EntityId>(
     let mut new_idents: EntityBundleMap<I, _> = EntityBundleMap::new();
     for (idx, name, (ident, _)) in idents.bundles() {
         match idx {
-            EntityBundleIndex::Single(_) => {
+            EntityBundleIndices::Single(_) => {
                 new_idents.insert(name.into(), ident.clone());
             }
-            EntityBundleIndex::Array(range) => {
+            EntityBundleIndices::Array(range) => {
                 new_idents.insert_array(name.into(), range.len(), ident.clone());
             }
         }