feat(cmn): various macros and optimizations

README.md

@@ -29,25 +29,40 @@ A Rust library for accessing a collection of mathematical and cryptographic cons
 
 ## Overview 📖
 
-`Common (CMN)`, a Rust library designed for developers who are looking for a comprehensive collection of mathematical and cryptographic constants.
-
-`Common (CMN)` is a modern, fast, and user-friendly library that makes it easy to access a wide range of mathematical and cryptographic constants, including the mathematical constant `Euler`, the `hash` algorithm used, the `cost` of the hash algorithm, the `length` of the hash, the mathematical constant `Phi`, the mathematical constant `Pi`, the `Planck` constant, a set of `special` characters, and much more.
+`Common (CMN)` is a modern, fast, and user-friendly library that makes it easy to access a wide range of mathematical and cryptographic constants.
 
 ## Features ✨
 
-The library includes two main structures: `Constant` and `Constants`.
-
-- The `Constant` structure holds the name and value of each constant as
-a `&'static str` and a `String`, respectively.
-- The Constants structure implements a method constants that returns a
-`Vec<Constant>` containing all the available constants.
-- The available constants include the mathematical constants `EULER`,
-`PHI`, `PI`, `PLANCK`, and `SQRT5`, and the cryptographic constants
-`HASH_ALGORITHM`, `HASH_COST`, `HASH_LENGTH`, and `SPECIAL_CHARS`.
-- The library also includes an enumeration `ConstantValue` that
-represents the different constant values. The values can be an
-`f64 float`, a `String`, a `u32`, a `usize`, or a `&'static [char]`
-array of characters.
+The `Common (CMN)` uses the `serde` crate to serialize and deserialize the data.
+
+The library has three modules:
+
+- **Macros**: This module contains functions for generating macros that can be used to access the constants.
+- **Constants**: This module contains the Constants structure, which provides a collection of constant values that are used throughout the library.
+- **Words**: This module contains the Words structure, which provides a collection of words that are used throughout the library.
+
+### Mathematical and Cryptographic Constants
+
+The following table lists the most important mathematical and cryptographic constants available in the `Common (CMN)` library:
+
+| Constants | Description | Example |
+| --- | --- | --- |
+| AVOGADRO | Avogadro's constant is the number of atoms or molecules in one mole of a substance. | The number of atoms in 12 grams of carbon-12 is 6.02214076 × 10^23. This can be used to calculate the number of atoms or molecules in a given sample. |
+| BOLTZMANN | Boltzmann's constant is the physical constant relating the temperature of a system to the average kinetic energy of its constituent particles. | The kinetic energy of an atom at room temperature is about 2.0 × 10^-21 joules. This can be used to calculate the temperature of a system, or to calculate the average kinetic energy of its particles. |
+| EULER | Euler's constant is a mathematical constant approximately equal to 2.71828. | The sum of the infinite series 1 + 1/2 + 1/3 + ... is equal to Euler's constant, e. This can be used to calculate the sum of an infinite series, or to calculate the logarithm of a number. |
+| GAMMA | The gamma constant is a mathematical constant approximately equal to 0.57721. | The gamma function of 2 is equal to 1. This can be used to calculate the gamma function of a number, or to calculate the factorial of a number. |
+| HASH_ALGORITHM | The hash algorithm used to generate the hash. The default is Blake3. | The hash of the string "Hello, world!" is 5eb63bbbe01eeed093cb22bb8f5acdc32790160b123138d53f2173b8d3dc3eee. This can be used to verify the integrity of data, or to create a unique identifier for a file. |
+| HASH_COST | The cost of the hash. | The hash cost of Blake3 is 2^128. This can be used to determine how secure a hash algorithm is. |
+| HASH_LENGTH | The length of the hash. | The hash length of Blake3 is 32 bytes. This can be used to determine how much space is required to store the hash output. |
+| PHI | The golden ratio is a number approximately equal to 1.618033988749895. | The golden ratio can be used to create a symmetrical design, or a design that is pleasing to the eye. |
+| Pi (π) | Pi is the ratio of a circle's circumference to its diameter. | The circumference of a circle with a radius of 1 is equal to pi. This can be used to calculate the circumference, area, and volume of circles, spheres, and other geometric shapes. |
+| PLANCK | Planck's constant is a physical constant that is approximately equal to 6.62607015 × 10^−34 joule seconds. | The energy of a photon of light with a wavelength of 500 nanometers is equal to Planck's constant multiplied by the frequency of the light. This can be used to calculate the energy of photons and other elementary particles. |
+| SILVER_RATIO | The silver ratio is a number approximately equal to 1.414213562373095. | The silver ratio can be used to create a symmetrical design, or a design that is pleasing to the eye. |
+| SPECIAL_CHARS | A list of special characters. | The special characters are: !@#$%^&*()_+-={}[]|\:;"'<>,.? |
+| SQRT2 | The square root of 2 is a number approximately equal to 1.414213562373095. | The area of a circle with a radius of 1 is equal to the square root of 2. This can be used to calculate the area and volume of circles, spheres, and other geometric shapes. |
+| SQRT3 | The square root of 3 is a number approximately equal to 1.732050807568877. | The area of a circle with a radius of 1 is equal to the square root of 3. This can be used to calculate the area and volume of circles
+| SQRT5 | The square root of 5 is a number approximately equal to 2.23606797749979. | The area of a circle with a radius of 1 is equal to the square root of 5. |
+| TAU | Tau is a number approximately equal to 6.283185307179586. | The circumference of a circle with a radius of 1 is equal to tau. |
 
 ## Getting Started 🚀
 

benches/criterion.rs

@@ -1,6 +1,7 @@
 // Copyright © 2023 Common (CMN) library. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
+//! Benchmarks for the Common (CMN) library.
 use criterion::{
     black_box, criterion_group, criterion_main, Criterion,
 };

build.rs

@@ -1,7 +1,14 @@
 // Copyright © 2023 Common (CMN) library. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
+//! The main function of the build script.
+//!
+//! This function is executed when building the crate and performs certain tasks
+//! necessary for the build process.
+//!
+//! It prints a "cargo:rerun-if-changed" directive to indicate that the build
+//! should be re-run if the "build.rs" file is changed.
 fn main() {
     // println!("cargo:rerun-if-changed=src/lib.rs");
-    // println!("cargo:rerun-if-changed=build.rs");
+    println!("cargo:rerun-if-changed=build.rs");
 }

examples/cmn.rs

@@ -1,10 +1,11 @@
 // Copyright © 2023 Common (CMN) library. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
-extern crate cmn;
-
-use cmn::constants::{Constant, ConstantValue, Constants};
-pub use cmn::Words;
+//! Examples of how to use the Common (CMN) library.
+use cmn::{
+    cmn_constants,
+    constants::{Constant, ConstantValue, Constants},
+};
 
 fn main() {
     // Create a Constants instance
@@ -36,4 +37,33 @@ fn main() {
     // Retrieve a constant by name and print it (in this case, EULER)
     let euler_constant = c.constant("EULER");
     println!("🦀 ConstantValue of EULER: ✅ {euler_constant:?}");
+
+    // Retrieve a constant by name and print it (in this case, PI)
+    cmn_constants! {
+        AVOGADRO = cmn::constants::AVOGADRO,
+        BOLTZMANN = cmn::constants::BOLTZMANN,
+        EULER = cmn::constants::EULER,
+        GAMMA = cmn::constants::GAMMA,
+        PHI = cmn::constants::PHI,
+        PI = cmn::constants::PI,
+        PLANCK = cmn::constants::PLANCK,
+        SILVER_RATIO = cmn::constants::SILVER_RATIO,
+        SQRT2 = cmn::constants::SQRT2,
+        SQRT3 = cmn::constants::SQRT3,
+        SQRT5 = cmn::constants::SQRT5,
+        TAU = cmn::constants::TAU
+    }
+    println!("🦀 Using cmn_constants! macro:");
+    println!("- Avogadro's constant:     ✅ {}", &AVOGADRO);
+    println!("- Boltzmann's constant:    ✅ {}", &BOLTZMANN);
+    println!("- Euler's constant:        ✅ {}", &EULER);
+    println!("- Gamma's constant:        ✅ {}", &GAMMA);
+    println!("- Phi's constant:          ✅ {}", &PHI);
+    println!("- Pi's constant:           ✅ {}", &PI);
+    println!("- Planck's constant:       ✅ {}", &PLANCK);
+    println!("- Silver ratio's constant: ✅ {}", &SILVER_RATIO);
+    println!("- Sqrt2's constant:        ✅ {}", &SQRT2);
+    println!("- Sqrt3's constant:        ✅ {}", &SQRT3);
+    println!("- Sqrt5's constant:        ✅ {}", &SQRT5);
+    println!("- Tau's constant:          ✅ {}", &TAU);
 }

src/constants.rs

@@ -188,24 +188,22 @@ pub enum ConstantValue {
     CharArray(&'static [char]),
 }
 
-/// The Avogadro constant, `N_A`.
-/// N_A = 6.022_140_76e23
-pub const AVOGADRO: f64 = 6.022_140_76e23_f64;
+/// Avogadro's constant
+/// Approximately 6.02214076 x 10^23
+pub const AVOGADRO: f64 = 602214076000000000000000.0;
 
-/// The Boltzmann constant, `k_B`.
-/// k_B = 1.380_649e-23
-/// k_B = R/N_A
-/// R = 8.314_462_618_153_24
-pub const BOLTZMANN: f64 = 1.380_649e-23_f64;
+/// Boltzmann's constant
+/// Approximately 1.380648 x 10^-23
+pub const BOLTZMANN: f64 = 1.380648e-23;
 
-/// The Euler–Mascheroni constant, `γ`.
-/// γ = 0.577_215_664_901_532_9
-pub const EULER: f64 = 0.577_215_664_901_532_9_f64;
+/// The base of the natural logarithm, Euler's number (e).
+/// e ≈ 2.7182818284590452353602874713527
+pub const EULER: f64 = std::f64::consts::E;
 
 /// The mathematical constant `γ` or the Euler–Mascheroni constant. It
 /// is the limit of the difference between the harmonic series and the
 /// natural logarithm of the natural numbers.
-pub const GAMMA: f64 = 0.577_215_664_901_532_9_f64;
+pub const GAMMA: f64 = 0.5772156649015329;
 
 /// The hash algorithm used. The default is Blake3.
 pub const HASH_ALGORITHM: &str = "Blake3";
@@ -229,7 +227,7 @@ pub const PHI: f64 = (1.0 + SQRT5) / 2.0;
 pub const PI: f64 = std::f64::consts::PI;
 
 /// The Planck constant, `h`.
-pub const PLANCK: f64 = 6.626_070_15e-34_f64;
+pub const PLANCK: f64 = 6.62607015e-34;
 
 /// The mathematical constant `δs' or the silver ratio (or silver mean).
 /// δs = 1+√2. One of the silver means (n+sqrt(n2+1))/2 for n>0.
@@ -252,14 +250,14 @@ pub const SQRT2: f64 = std::f64::consts::SQRT_2;
 /// It is the length of the side of an equilateral triangle with unit
 /// side length.
 /// 3 = 1 + √3
-pub const SQRT3: f64 = 1.732_050_807_568_877_2_f64;
+pub const SQRT3: f64 = 1.732_050_807_568_877_2;
 
 /// The mathematical constant `√5` or the principal square root of 5.
 /// It is the length of the diagonal of a regular pentagon with unit
 /// side length.
 /// 5 = 2 + 2√5
-pub const SQRT5: f64 = 2.236_067_977_499_79_f64;
+pub const SQRT5: f64 = 2.236_067_977_499_79;
 
 /// The mathematical constant `τ` or the ratio of a circle's
 /// circumference to its radius.
-pub const TAU: f64 = 2.0 * PI;
+pub const TAU: f64 = std::f64::consts::TAU;

src/lib.rs

@@ -19,16 +19,23 @@
 //!
 //! </center>
 //!
-//! ## Overview
+//! ## Overview 📖
 //!
-//!`Common (CMN)` is a modern, fast, and user-friendly library that
-//! makes it easy to access a wide range of mathematical and
-//! cryptographic constants, including the following constants.
+//! `Common (CMN)` is a modern, fast, and user-friendly library that makes it easy to access a wide range of mathematical and cryptographic constants.
 //!
-//! ## Features
+//! ## Features ✨
 //!
-//! The following table lists the features available in the Common (CMN)
-//! library.
+//! The `Common (CMN)` uses the `serde` crate to serialize and deserialize the data.
+//!
+//! The library has three modules:
+//!
+//! - **Macros**: This module contains functions for generating macros that can be used to access the constants.
+//! - **Constants**: This module contains the Constants structure, which provides a collection of constant values that are used throughout the library.
+//! - **Words**: This module contains the Words structure, which provides a collection of words that are used throughout the library.
+//!
+//! ### Mathematical and Cryptographic Constants
+//!
+//! The following table lists the most important mathematical and cryptographic constants available in the `Common (CMN)` library:
 //!
 //!| Constants | Description | Example |
 //!| --- | --- | --- |
@@ -154,6 +161,14 @@ impl Common {
     pub fn words(&self) -> Words {
         Words::new()
     }
+    /// Parses a string of JSON data and returns a new instance of the
+    /// `Common` structure.
+    pub fn parse(
+        input: &str,
+    ) -> Result<Self, Box<dyn std::error::Error>> {
+        let common: Common = serde_json::from_str(input)?;
+        Ok(common)
+    }
 }
 
 impl Default for Common {

src/macros.rs

@@ -34,8 +34,7 @@
 #[macro_export]
 macro_rules! cmn {
     ($($tt:tt)*) => {
-        // Parse the arguments into a Rust value.
-        $crate::parse!($($tt)*)
+        cmn::Common::parse($($tt)*)
     };
 }
 
@@ -153,3 +152,35 @@ macro_rules! cmn_parse {
         Common::parse($input)
     };
 }
+
+/// This macro defines a set of constants with their corresponding
+/// values. The macros can be used to define constants in a concise
+/// and easy-to-read way.
+#[macro_export]
+macro_rules! cmn_constants {
+    ($($name:ident = $value:expr),*) => {
+        $(
+            /// The value of the constant.
+            pub const $name: f64 = $value;
+        )*
+    };
+}
+
+// cmn_constants! {
+//     AVOGADRO = super::constants::AVOGADRO,
+//     BOLTZMANN = super::constants::BOLTZMANN,
+//     EULER = super::constants::EULER,
+//     GAMMA = super::constants::GAMMA,
+//     HASH_ALGORITHM = super::constants::HASH_ALGORITHM,
+//     HASH_COST = super::constants::HASH_COST,
+//     HASH_LENGTH = super::constants::HASH_LENGTH,
+//     PHI = super::constants::PHI,
+//     PI = super::constants::PI,
+//     PLANCK = super::constants::PLANCK,
+//     SILVER_RATIO = super::constants::SILVER_RATIO,
+//     SPECIAL_CHARS = super::constants::SPECIAL_CHARS,
+//     SQRT2 = super::constants::SQRT2,
+//     SQRT3 = super::constants::SQRT3,
+//     SQRT5 = super::constants::SQRT5,
+//     TAU = super::constants::TAU
+// }