Skip to content

Commit

Permalink
doc: update public items' documentation entries (#47)
Browse files Browse the repository at this point in the history 
* doc: update utils module entries

* doc: update doc entries of attribute collections types

also, correct some methods' name

* chore: add clippy::pedantic lint

also add some allow() rules to work through later

* doc: fix missing panics in twomap doc

* doc: allow more lints & apply auto fixes

* doc: finish fixing all enabled clippy::pedantic warnings

* doc: fix lints of the utils module

* chore: set missing_doc lint to warning level

* doc: adjust doc in the twomap module

* doc: add missing entries

* doc: complete & cleanup module level docs

* doc: finish last adjustment
  • Loading branch information
@imrn99
imrn99 authored Apr 19, 2024
1 parent 2186a09 commit 0f33e1d
Show file tree
Hide file tree
Showing 14 changed files with 451 additions and 163 deletions.
179 changes: 165 additions & 14 deletions honeycomb-core/src/attributes/collections.rs
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
//! Attribute storage structures
//!
//! This module contains all code used to describe custom collections used to store attributes
//! (see [AttributeBind], [AttributeUpdate]).
//! (see [`AttributeBind`], [`AttributeUpdate`]).
// ------ IMPORTS

Expand All @@ -23,10 +23,14 @@ use num::ToPrimitive;
///
/// # Example
///
/// todo
/// **Currently, this type is not meant to be used directly** when operating on combinatorial maps,
/// but it is kept public because it should eventually be part of the map building system where
/// the user will add its own attributes and choose how they are stored. As such, no example
/// is provided.
///
#[cfg_attr(feature = "utils", derive(Clone))]
pub struct AttrSparseVec<T: AttributeBind + AttributeUpdate> {
/// Inner storage.
data: Vec<Option<T>>,
}

Expand All @@ -40,19 +44,26 @@ impl<T: AttributeBind + AttributeUpdate> AttrSparseVec<T> {
///
/// # Return
///
/// Return a [AttrSparseVec] object full of `None`.
/// Return a [`AttrSparseVec`] object full of `None`.
///
pub fn new(n_ids: usize) -> Self {
Self {
data: (0..n_ids).map(|_| None).collect(),
}
}

/// Extend the inner vector's length
///
/// # Arguments
///
/// - `length: usize` -- number of `None` instances to append to the current storage.
///
pub fn extend(&mut self, length: usize) {
self.data.extend((0..length).map(|_| None));
}

pub fn n_vertices(&self) -> usize {
/// Return the number of stored attributes (i.e. number of `Some(_)` instances)
pub fn n_attributes(&self) -> usize {
self.data.iter().filter(|val| val.is_some()).count()
}

Expand All @@ -62,10 +73,12 @@ impl<T: AttributeBind + AttributeUpdate> AttrSparseVec<T> {
///
/// - `index: T::IdentifierType` -- Cell index.
///
/// # Return / Panic
/// # Return
///
/// Return a reference to the value indexed by `index`.
///
/// # Panics
///
/// The method may panic if:
/// - the index lands out of bounds
/// - the index cannot be converted to `usize`
Expand All @@ -80,10 +93,12 @@ impl<T: AttributeBind + AttributeUpdate> AttrSparseVec<T> {
///
/// - `index: T::IdentifierType` -- Cell index.
///
/// # Return / Panic
/// # Return
///
/// Return a mutable reference to the value indexed by `index`.
///
/// # Panics
///
/// The method may panic if:
/// - the index lands out of bounds
/// - the index cannot be converted to `usize`
Expand All @@ -101,7 +116,7 @@ impl<T: AttributeBind + AttributeUpdate> AttrSparseVec<T> {
/// - `index: T::IdentifierType` -- Cell index.
/// - `val: T` -- Attribute value.
///
/// # Panic
/// # Panics
///
/// The method may panic if:
/// - the index lands out of bounds
Expand All @@ -120,7 +135,7 @@ impl<T: AttributeBind + AttributeUpdate> AttrSparseVec<T> {
/// - `index: T::IdentifierType` -- Cell index.
/// - `val: T` -- Attribute value.
///
/// # Panic
/// # Panics
///
/// The method may panic if:
/// - **there is already a value associated to the specified index**
Expand All @@ -142,10 +157,12 @@ impl<T: AttributeBind + AttributeUpdate> AttrSparseVec<T> {
/// - `index: T::IdentifierType` -- Cell index.
/// - `val: T` -- Attribute value.
///
/// # Return / Panic
/// # Return
///
/// Return an option containing the old value if it existed.
///
/// # Panics
///
/// The method may panic if:
/// - the index lands out of bounds
/// - the index cannot be converted to `usize`
Expand All @@ -161,11 +178,13 @@ impl<T: AttributeBind + AttributeUpdate> AttrSparseVec<T> {
///
/// - `index: T::IdentifierType` -- Cell index.
///
/// # Return / Panic
/// # Return
///
/// Return the item associated to the specified index. Note that the method will not panic if
/// there was not one, it will simply return `None`.
///
/// # Panics
///
/// The method may panic if:
/// - the index lands out of bounds
/// - the index cannot be converted to `usize`
Expand All @@ -178,14 +197,17 @@ impl<T: AttributeBind + AttributeUpdate> AttrSparseVec<T> {

#[cfg(feature = "utils")]
impl<T: AttributeBind + AttributeUpdate + Clone> AttrSparseVec<T> {
/// Return the amount of space allocated for the storage.
pub fn allocated_size(&self) -> usize {
self.data.capacity() * std::mem::size_of::<Option<T>>()
}

/// Return the total amount of space used by the storage.
pub fn effective_size(&self) -> usize {
self.data.len() * std::mem::size_of::<Option<T>>()
}

/// Return the amount of space used by valid entries of the storage.
pub fn used_size(&self) -> usize {
self.data.iter().filter(|val| val.is_some()).count() * std::mem::size_of::<Option<T>>()
}
Expand All @@ -201,21 +223,39 @@ impl<T: AttributeBind + AttributeUpdate + Clone> AttrSparseVec<T> {
///
/// # Generics
///
/// - `T: AttributeBind + AttributeUpdate + Default` -- Type of the stored attributes. The
/// `Default` implementation is required in order to create dummy values for unused slots.
/// - `T: AttributeBind + AttributeUpdate + Clone` -- Type of the stored attributes. The
/// `Clone` implementation is required in order to return copied values & invalidate internal
/// storage slot.
///
/// # Example
///
/// todo
/// **Currently, this type is not meant to be used directly** when operating on combinatorial maps,
/// but it is kept public because it should eventually be part of the map building system where
/// the user will add its own attributes and choose how they are stored. As such, no example
/// is provided.
///
#[cfg_attr(feature = "utils", derive(Clone))]
pub struct AttrCompactVec<T: AttributeBind + AttributeUpdate + Clone> {
/// Tracker of unused internal slots.
unused_data_slots: Vec<usize>,
/// Map between attribute index and internal index.
index_map: Vec<Option<usize>>,
/// Inner storage.
data: Vec<T>,
}

impl<T: AttributeBind + AttributeUpdate + Clone> AttrCompactVec<T> {
/// Constructor
///
/// # Arguments
///
/// - `n_ids: usize` -- Upper bound of IDs used to index the attribute's values (in practice,
/// the number of darts).
///
/// # Return
///
/// Return a "value-empty" [`AttrSparseVec`] object.
///
pub fn new(n_ids: usize) -> Self {
Self {
unused_data_slots: Vec::new(),
Expand All @@ -224,22 +264,78 @@ impl<T: AttributeBind + AttributeUpdate + Clone> AttrCompactVec<T> {
}
}

/// Extend the inner vector's length
///
/// # Arguments
///
/// - `length: usize` -- number of `None` instances to append to the current storage.
///
pub fn extend(&mut self, length: usize) {
self.index_map.extend((0..length).map(|_| None));
}

pub fn n_vertices(&self) -> usize {
/// Return the number of stored attributes in the internal storage.
pub fn n_attributes(&self) -> usize {
self.data.len()
}

/// Getter
///
/// # Arguments
///
/// - `index: T::IdentifierType` -- Cell index.
///
/// # Return
///
/// Return an `Option` that may contain a reference to the value associated to `index`, if
/// it exists.
///
/// # Panics
///
/// The method may panic if:
/// - the index lands out of bounds
/// - the index cannot be converted to `usize`
///
pub fn get(&self, index: T::IdentifierType) -> Option<&T> {
self.index_map[index.to_usize().unwrap()].map(|idx| &self.data[idx])
}

/// Getter
///
/// # Arguments
///
/// - `index: T::IdentifierType` -- Cell index.
///
/// # Return
///
/// Return an `Option` that may contain a mutable reference to the value associated to `index`,
/// if it exists.
///
/// # Panics
///
/// The method may panic if:
/// - the index lands out of bounds
/// - the index cannot be converted to `usize`
///
pub fn get_mut(&mut self, index: T::IdentifierType) -> Option<&mut T> {
self.index_map[index.to_usize().unwrap()].map(|idx| &mut self.data[idx])
}

/// Setter
///
/// Set the value of an element at a given index.
///
/// # Arguments
///
/// - `index: T::IdentifierType` -- Cell index.
/// - `val: T` -- Attribute value.
///
/// # Panics
///
/// The method may panic if:
/// - the index lands out of bounds
/// - the index cannot be converted to `usize`
///
pub fn set(&mut self, index: T::IdentifierType, val: T) {
if let Some(idx) = self.index_map[index.to_usize().unwrap()] {
// internal index is defined => there should be associated data
Expand All @@ -255,6 +351,22 @@ impl<T: AttributeBind + AttributeUpdate + Clone> AttrCompactVec<T> {
}
}

/// Setter
///
/// Insert a value at a given index.
///
/// # Arguments
///
/// - `index: T::IdentifierType` -- Cell index.
/// - `val: T` -- Attribute value.
///
/// # Panics
///
/// The method may panic if:
/// - **there is already a value associated to the specified index**
/// - the index lands out of bounds
/// - the index cannot be converted to `usize`
///
pub fn insert(&mut self, index: T::IdentifierType, val: T) {
let idx = &mut self.index_map[index.to_usize().unwrap()];
assert!(idx.is_none());
Expand All @@ -267,13 +379,49 @@ impl<T: AttributeBind + AttributeUpdate + Clone> AttrCompactVec<T> {
};
}

/// Setter
///
/// Replace the value of an element at a given index.
///
/// # Arguments
///
/// - `index: T::IdentifierType` -- Cell index.
/// - `val: T` -- Attribute value.
///
/// # Return
///
/// Return an option containing the old value if it existed.
///
/// # Panics
///
/// The method may panic if:
/// - the index lands out of bounds
/// - the index cannot be converted to `usize`
///
pub fn replace(&mut self, index: T::IdentifierType, val: T) -> Option<T> {
let idx = &self.index_map[index.to_usize().unwrap()];
assert!(idx.is_some());
self.data.push(val);
Some(self.data.swap_remove(idx.unwrap()))
}

/// Remove an item from the storage and return it
///
/// # Arguments
///
/// - `index: T::IdentifierType` -- Cell index.
///
/// # Return
///
/// Return the item associated to the specified index. Note that the method will not panic if
/// there was not one, it will simply return `None`.
///
/// # Panics
///
/// The method may panic if:
/// - the index lands out of bounds
/// - the index cannot be converted to `usize`
///
pub fn remove(&mut self, index: T::IdentifierType) -> Option<T> {
self.index_map.push(None);
if let Some(tmp) = self.index_map.swap_remove(index.to_usize().unwrap()) {
Expand All @@ -286,18 +434,21 @@ impl<T: AttributeBind + AttributeUpdate + Clone> AttrCompactVec<T> {

#[cfg(feature = "utils")]
impl<T: AttributeBind + AttributeUpdate + Clone> AttrCompactVec<T> {
/// Return the amount of space allocated for the storage.
pub fn allocated_size(&self) -> usize {
self.unused_data_slots.capacity() * std::mem::size_of::<usize>()
+ self.index_map.capacity() * std::mem::size_of::<Option<usize>>()
+ self.data.capacity() * std::mem::size_of::<T>()
}

/// Return the total amount of space used by the storage.
pub fn effective_size(&self) -> usize {
self.unused_data_slots.len() * std::mem::size_of::<usize>()
+ self.index_map.len() * std::mem::size_of::<Option<usize>>()
+ self.data.len() * std::mem::size_of::<T>()
}

/// Return the amount of space used by valid entries of the storage.
pub fn used_size(&self) -> usize {
self.unused_data_slots.len() * std::mem::size_of::<usize>()
+ self.index_map.iter().filter(|val| val.is_some()).count()
Expand Down
6 changes: 2 additions & 4 deletions honeycomb-core/src/attributes/mod.rs
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
//! Module short description
//! Attribute modeling code
//!
//! Should you interact with this module directly?
//!
//! Content description if needed
//! This module contains all code related to generic attribute modelling and handling.
// ------ MODULE DECLARATIONS

Expand Down
Loading

0 comments on commit 0f33e1d

Please sign in to comment.