test(cmn): ✅ add macros unit tests and reformatting

benches/criterion.rs

@@ -40,4 +40,4 @@ fn bench_words(c: &mut Criterion) {
 }
 
 criterion_group!(benches, bench_cmn, bench_words);
-criterion_main!(benches);
+criterion_main!(benches);

src/lib.rs

@@ -38,26 +38,37 @@
 //! 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. |
+//!| -- | -- | -- |
+//!| APERY | Apéry's constant, is the sum of the reciprocals of the positive cubes.<br>`ζ(3) ≈ 1.2020569032` | Used in various mathematical calculations and series approximations. |
+//!| AVOGADRO | Avogadro's constant is the number of atoms or molecules in one mole of a substance.<br>`N_A ≈ 6.02214076 x 10^23 mol^-1` | 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.<br>`k_B ≈ 1.380648 x 10^-23 J K^-1` | 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. |
+//!| CATALAN | Catalan's constant, is the sum of the alternating harmonic series.<br>`C ≈ 0.915965594177219` | Used in various mathematical calculations and series approximations. |
+//!| COULOMB | Coulomb's constant, is the proportionality constant in Coulomb's law.<br>`k_e ≈ 8.9875517923` x 10^9 N m^2 C^-2 | Used in calculations related to electrostatic forces and electric fields. |
+//!| EULER | Euler's constant is a mathematical constant approximately equal to 2.71828.<br>`e ≈ 2.7182818284590452353602874713527` | 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. |
+//!| FARADAY | Faraday constant, which represents the amount of electric charge carried by one mole of electrons.<br>`F ≈ 96485.33212 C mol^-1` | Used in calculations related to electrochemistry and electrolysis. |
+//!| GAMMA | The gamma constant is a mathematical constant approximately equal to 0.57721.<br>`γ ≈ 0.5772156649015329` | 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. |
+//!| GAS_CONSTANT | The gas constant, which relates the energy scale to the temperature scale in the ideal gas law.<br>`R ≈ 8.314462618 J mol^-1 K^-1` | Used in calculations related to the behavior of gases and thermodynamics. |
+//!| GLAISHER_KINKELIN | Glaisher-Kinkelin constant, which arises in the asymptotic expansion of the Barnes G-function.<br>`A ≈ 1.2824271291` | Used in various mathematical calculations and series approximations. |
+//!| GRAVITATIONAL_CONSTANT | The gravitational constant, is the proportionality constant in Newton's law of universal gravitation.<br>`G ≈ 6.67430 x 10^-11 m^3 kg^-1 s^-2` | Used in calculations related to gravitational forces and celestial mechanics. |
 //!| 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_COST | The cost of the hash. | The hash cost of Blake3 is<br>`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. |
-//!
-//! The following table lists the dictionaries available in the Common
-//! library.
+//!| KHINCHIN | Khinchin's constant, which appears in the theory of continued fractions.<br>`K ≈ 2.6854520010` | Used in various mathematical calculations and series approximations. |
+//!| PHI | The golden ratio is a number approximately equal to 1.618033988749895.<br>`φ = (1 + √5) / 2 ≈ 1.6180339887498948482045868343656` | 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.<br>`π ≈ 3.14159265358979323846264338327950288` | 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, which relates the energy of a photon to its frequency.<br>`h ≈ 6.62607015 x 10^-34 J s` | 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. |
+//!| PLANCK_REDUCED | Planck's reduced constant, is Planck's constant divided by 2π.<br>`ħ = h / (2π) ≈ 1.054571817 x 10^-34 J s` | Used in quantum mechanics and related calculations. |
+//!| SILVER_RATIO | The silver ratio is one of the silver means.<br>`δ_s = 1 + √2 ≈ 2.4142135623730950488016887242097` | The silver ratio can be used to create a symmetrical design, or a design that is pleasing to the eye. |
+//!| SPEED_OF_LIGHT | The speed of light in vacuum.<br>`c ≈ 299792458 m s^-1` | Used in calculations related to relativity and electromagnetic phenomena. |
+//!| SPECIAL_CHARS | A set of special characters. | The special characters are: !@#$%^&*()_+-={}[]|\:;"'<>,.?` |
+//!| SQRT2 | The square root of 2.<br>`√2 ≈ 1.4142135623730950488016887242097` | 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.<br>`√3 ≈ 1.7320508075688772935274463415059` | 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.<br>`√5 ≈ 2.23606797749979` | The area of a circle with a radius of 1 is equal to the square root of 5. |
+//!| TAU | The circle constant, is the ratio of a circle's circumference to its radius.<br>`τ = 2π ≈ 6.28318530717958647692528676655900577` | The circumference of a circle with a radius of 1 is equal to tau. |
+//!| VACUUM_PERMEABILITY | The vacuum permeability, which relates magnetic induction to magnetic field strength.<br>`μ_0 ≈ 1.25663706212 x 10^-6 N A^-2` | Used in calculations related to electromagnetism and magnetic fields. |
+//!| VACUUM_PERMITTIVITY | The vacuum permittivity, which relates electric displacement to electric field strength.<br>`ε_0 ≈ 8.8541878128 x 10^-12 F m^-1` | Used in calculations related to electromagnetism and electric fields. |
+//!
+//! The following table lists the dictionaries available in the Common library.
 //!
 //!| Words | Description |
 //!| --- | --- |
@@ -171,7 +182,9 @@ impl Common {
                     .as_array()
                     .expect("Words data is not an array")
                     .iter()
-                    .map(|word_value| word_value.as_str().unwrap().to_string())
+                    .map(|word_value| {
+                        word_value.as_str().unwrap().to_string()
+                    })
                     .collect::<Vec<String>>()
             })
             .unwrap_or_default(); // Add this line
@@ -180,11 +193,20 @@ impl Common {
             words: HashSet::from_iter(words_data),
         }
     }
-    /// Parses a string of JSON data and returns a new instance of the
-    /// `Common` structure.
+    /// Parses a string of JSON data and returns a new instance of the `Common` structure.
     pub fn parse(input: &str) -> Result<Self, serde_json::Error> {
-        match serde_json::from_str(input) {
-            Ok(common) => Ok(common),
+        match serde_json::from_str::<Common>(input) {
+            Ok(common) => {
+                if common.fields.is_null()
+                    || common.fields.is_object()
+                        && common.fields.as_object().unwrap().is_empty()
+                {
+                    // If the `fields` object is null or empty, return the default `Common` instance
+                    Ok(Common::default())
+                } else {
+                    Ok(common)
+                }
+            }
             Err(e) => {
                 // Handle the JSON parsing error
                 match e.classify() {

src/macros.rs

@@ -81,6 +81,18 @@ macro_rules! cmn_join {
     }};
 }
 
+/// This macro creates a new map of the given key-value pairs.
+#[macro_export]
+macro_rules! cmn_map {
+    ($($key:expr => $value:expr),*) => {{
+        let mut map = ::std::collections::HashMap::new();
+        $(
+            map.insert($key, $value);
+        )*
+        map
+    }};
+}
+
 /// This macro finds the maximum value of the given values.
 #[macro_export]
 macro_rules! cmn_max {
@@ -135,6 +147,14 @@ macro_rules! cmn_split {
     }};
 }
 
+/// This macro converts the given string to a number.
+#[macro_export]
+macro_rules! cmn_to_num {
+    ($s:expr) => {
+        $s.parse::<f64>().unwrap_or(0.0)
+    };
+}
+
 /// This macro creates a new vector with the given elements.
 #[macro_export]
 macro_rules! cmn_vec {