diff --git a/01.workspace/heave/src/imp/catalog_contains_key.rs b/01.workspace/heave/src/imp/catalog_contains_key.rs index fcc6d79..5d1744b 100644 --- a/01.workspace/heave/src/imp/catalog_contains_key.rs +++ b/01.workspace/heave/src/imp/catalog_contains_key.rs @@ -1,6 +1,21 @@ use crate::*; impl Catalog { + /// Checks if the catalog contains an entity with the specified key. + /// + /// # Arguments + /// + /// * `k` - The key to check for. + /// + /// # Returns + /// + /// `Ok(true)` if an entity with the specified key exists in the catalog, + /// `Ok(false)` otherwise. + /// + /// # Errors + /// + /// Returns `Err(FailedTo::LockCatalog)` if the catalog's internal mutex + /// could not be locked. pub fn contains_key(&self, k: &str) -> Result { self.with_items(|items| Ok(items.contains_key(k))) } diff --git a/01.workspace/heave/src/imp/catalog_is_empty.rs b/01.workspace/heave/src/imp/catalog_is_empty.rs index e392841..aa255aa 100644 --- a/01.workspace/heave/src/imp/catalog_is_empty.rs +++ b/01.workspace/heave/src/imp/catalog_is_empty.rs @@ -1,6 +1,16 @@ use crate::*; impl Catalog { + /// Checks if the catalog is empty. + /// + /// # Returns + /// + /// `Ok(true)` if the catalog contains no entities, `Ok(false)` otherwise. + /// + /// # Errors + /// + /// Returns `Err(FailedTo::LockCatalog)` if the catalog's internal mutex + /// could not be locked. pub fn is_empty(&self) -> Result { self.with_items(|items| Ok(items.is_empty())) } diff --git a/01.workspace/heave/src/imp/catalog_len.rs b/01.workspace/heave/src/imp/catalog_len.rs index 1a8761d..ae12ee9 100644 --- a/01.workspace/heave/src/imp/catalog_len.rs +++ b/01.workspace/heave/src/imp/catalog_len.rs @@ -1,6 +1,16 @@ use crate::*; impl Catalog { + /// Returns the number of entities in the catalog. + /// + /// # Returns + /// + /// The total number of entities currently held in the catalog's memory. + /// + /// # Errors + /// + /// Returns `Err(FailedTo::LockCatalog)` if the catalog's internal mutex + /// could not be locked. pub fn len(&self) -> Result { self.with_items(|items| Ok(items.len())) } diff --git a/01.workspace/heave/src/imp/catalog_list_by_class.rs b/01.workspace/heave/src/imp/catalog_list_by_class.rs index 58de8f2..df4f593 100644 --- a/01.workspace/heave/src/imp/catalog_list_by_class.rs +++ b/01.workspace/heave/src/imp/catalog_list_by_class.rs @@ -1,13 +1,25 @@ use crate::*; impl Catalog { - /// Returns an iterator over all entities of a specific class in the in-memory catalog. + /// Returns a list of all entities of a specific class from the in-memory catalog. /// - /// This is a purely in-memory operation and does not interact with the database. + /// This method filters the in-memory entities by the class of type `T` and + /// attempts to convert them into `T`. This is a purely in-memory operation + /// and does not interact with the database. /// /// # Returns /// - /// An iterator that yields items of type `T` from the in-memory cache. + /// A `Result` containing a `Vec` of `Result>`. Each inner `Result` + /// represents the outcome of converting an entity to type `T`. + /// + /// - `Ok(Vec)`: A vector of successfully converted entities. + /// - `Ok(Vec)`: If an entity of the correct class + /// could not be converted to type `T`. + /// + /// # Errors + /// + /// Returns `Err(FailedTo::LockCatalog)` if the catalog's internal mutex + /// could not be locked. pub fn list_by_class(&self) -> Result>, FailedTo> where T: EAV, diff --git a/01.workspace/heave/src/imp/catalog_list_by_class_and_subclass.rs b/01.workspace/heave/src/imp/catalog_list_by_class_and_subclass.rs index 86d93c9..23b5f02 100644 --- a/01.workspace/heave/src/imp/catalog_list_by_class_and_subclass.rs +++ b/01.workspace/heave/src/imp/catalog_list_by_class_and_subclass.rs @@ -1,14 +1,29 @@ use crate::*; impl Catalog { - /// Returns an iterator over all entities of a specific class and subclass - /// in the in-memory catalog. + /// Returns a list of all entities of a specific class and subclass from the in-memory catalog. /// - /// This is a purely in-memory operation and does not interact with the database. + /// This method filters the in-memory entities by the class of type `T` and the + /// provided `subclass`, then attempts to convert them into `T`. This is a purely + /// in-memory operation and does not interact with the database. + /// + /// # Arguments + /// + /// * `subclass` - The subclass to filter by. /// /// # Returns /// - /// An iterator that yields items of type `T` from the in-memory cache. + /// A `Result` containing a `Vec` of `Result>`. Each inner `Result` + /// represents the outcome of converting an entity to type `T`. + /// + /// - `Ok(Vec)`: A vector of successfully converted entities. + /// - `Ok(Vec)`: If an entity of the correct class + /// and subclass could not be converted to type `T`. + /// + /// # Errors + /// + /// Returns `Err(FailedTo::LockCatalog)` if the catalog's internal mutex + /// could not be locked. pub fn list_by_class_and_subclass( &self, subclass: &str, diff --git a/01.workspace/heave/src/lib.rs b/01.workspace/heave/src/lib.rs index 994570c..796170a 100644 --- a/01.workspace/heave/src/lib.rs +++ b/01.workspace/heave/src/lib.rs @@ -1,6 +1,6 @@ //! A lightweight and intuitive Entity-Attribute-Value (EAV) database library for Rust. //! -//! This library provides a simple way to persist and query semi-structured data using an EAV model on top of a SQLite database. It is designed to be easy to use, with a focus on simplicity and developer experience. +//! This library provides a simple and thread safe way to persist and query semi-structured data using an EAV model on top of a SQLite database. It is designed to be easy to use, with a focus on simplicity and developer experience. //! //! ## What is the Entity-Attribute-Value (EAV) Model? //! diff --git a/01.workspace/heave/src/str/attribute.rs b/01.workspace/heave/src/str/attribute.rs index 797a278..5eab9de 100644 --- a/01.workspace/heave/src/str/attribute.rs +++ b/01.workspace/heave/src/str/attribute.rs @@ -1,12 +1,26 @@ use crate::*; +/// Represents an attribute of an entity, consisting of an ID and a `Value`. #[derive(Debug, PartialEq, Clone)] pub struct O { + /// The unique identifier for this attribute (e.g., "name", "price"). pub id: String, + /// The value of the attribute. pub value: Value, } impl Attribute { + /// Creates a new `Attribute` instance. + /// + /// # Arguments + /// + /// * `id` - The ID of the attribute. + /// * `value` - The value of the attribute, which can be any type that + /// implements `Into`. + /// + /// # Returns + /// + /// A new `Attribute` instance. pub fn new(id: &str, value: impl Into) -> Self { Self { id: String::from(id), diff --git a/01.workspace/heave/src/str/filter.rs b/01.workspace/heave/src/str/filter.rs index fd35b99..5f34b98 100644 --- a/01.workspace/heave/src/str/filter.rs +++ b/01.workspace/heave/src/str/filter.rs @@ -21,12 +21,22 @@ impl<'a> Filter<'a> { conditions: Vec::new(), } } - /// Adds a class condition to the filter. + /// Sets the entity class to filter by. + /// + /// # Arguments + /// + /// * `value` - The class name to filter for. Only entities with this class + /// name will be considered. pub fn with_class(mut self, value: &str) -> Self { self.class = Some(value.to_string()); self } - /// Adds a subclass condition to the filter. + /// Sets the entity subclass to filter by. + /// + /// # Arguments + /// + /// * `value` - The subclass name to filter for. Only entities with this + /// subclass name will be considered. pub fn with_subclass(mut self, value: &str) -> Self { self.subclass = Some(value.to_string()); self diff --git a/01.workspace/heave/src/str/sqlite_failed_to.rs b/01.workspace/heave/src/str/sqlite_failed_to.rs index 2725967..754bb63 100644 --- a/01.workspace/heave/src/str/sqlite_failed_to.rs +++ b/01.workspace/heave/src/str/sqlite_failed_to.rs @@ -1,11 +1,20 @@ +/// Represents failures that can occur specifically within the SQLite implementation. #[derive(Debug, PartialEq, PartialOrd, Eq, Ord, Clone, Copy, Hash)] pub enum FailedTo { + /// Failed to begin a database transaction. BeginTransaction, + /// Failed to build a SQL statement. BuildStatement, + /// Failed to commit a database transaction. CommitTransaction, + /// Failed to execute a batch of SQL statements. ExecuteBatch, + /// Failed to execute a SQL query. ExecuteQuery, + /// Failed to execute a prepared SQL statement. ExecuteStatement, + /// Failed to open a connection to the SQLite database. OpenConnection, + /// Failed to prepare a SQL statement for execution. PrepareStatement, } diff --git a/01.workspace/heave/src/str/value.rs b/01.workspace/heave/src/str/value.rs index c30f7c9..9157ca6 100644 --- a/01.workspace/heave/src/str/value.rs +++ b/01.workspace/heave/src/str/value.rs @@ -1,11 +1,20 @@ use crate::*; +/// Represents the value of an entity's attribute. +/// +/// This enum can hold different data types, allowing for flexible and +/// semi-structured data storage. #[derive(Debug, PartialEq, PartialOrd, Clone)] pub enum Value { + /// A boolean value (`true` or `false`). Bool(bool), + /// A floating-point number (`f64`). Real(f64), + /// A signed 64-bit integer. SignedInt(i64), + /// A UTF-8 encoded string. Text(String), + /// An unsigned 64-bit integer. UnsignedInt(u64), }