diff --git a/README.md b/README.md index fe7b67c..1d22fe4 100644 --- a/README.md +++ b/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` 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 🚀 diff --git a/benches/criterion.rs b/benches/criterion.rs index e1dc939..52eac87 100644 --- a/benches/criterion.rs +++ b/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, }; diff --git a/build.rs b/build.rs index fabb4b0..77de8d3 100644 --- a/build.rs +++ b/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"); } diff --git a/examples/cmn.rs b/examples/cmn.rs index 9da7a17..a96f16f 100644 --- a/examples/cmn.rs +++ b/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); } diff --git a/src/constants.rs b/src/constants.rs index 1dad806..9ff26c3 100644 --- a/src/constants.rs +++ b/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; diff --git a/src/lib.rs b/src/lib.rs index 97cbcf3..9438603 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -19,16 +19,23 @@ //! //! //! -//! ## 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> { + let common: Common = serde_json::from_str(input)?; + Ok(common) + } } impl Default for Common { diff --git a/src/macros.rs b/src/macros.rs index b88879a..ed7ff54 100644 --- a/src/macros.rs +++ b/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 +// } diff --git a/tests/test_macros.rs b/tests/test_macros.rs index 7f3fb61..4fc0dde 100644 --- a/tests/test_macros.rs +++ b/tests/test_macros.rs @@ -1,69 +1,158 @@ #[cfg(test)] mod tests { + // Importing cmn crate and all of its macros extern crate cmn; - use cmn::*; + use cmn::{ + cmn_assert, cmn_contains, cmn_in_range, cmn_join, cmn_max, + cmn_min, cmn_print, cmn_print_vec, cmn_split, cmn_vec, + constants::*, + }; #[test] #[should_panic(expected = "Assertion failed!")] fn test_cmn_assert_fail() { - // This should panic with "Assertion failed!" + // Test that cmn_assert! macro correctly triggers a panic when the argument is false cmn_assert!(false); } #[test] fn test_cmn_assert() { - // This should not panic + // Test that cmn_assert! macro does not trigger a panic when the argument is true cmn_assert!(true); } #[test] fn test_cmn_join() { + // Test that cmn_join! macro correctly joins the string arguments together let s = cmn_join!("Hello", " ", "World"); assert_eq!(s, "Hello World"); } #[test] fn test_cmn_min() { + // Test that cmn_min! macro correctly identifies the minimum value among the arguments assert_eq!(cmn_min!(10, 20, 30), 10); } #[test] fn test_cmn_max() { + // Test that cmn_max! macro correctly identifies the maximum value among the arguments assert_eq!(cmn_max!(10, 20, 30), 30); } #[test] fn test_cmn_print() { + // Test that cmn_print! macro correctly prints the argument cmn_print!("Hello, World!"); } #[test] fn test_cmn_print_vec() { + // Test that cmn_print_vec! macro correctly prints the elements of the vector argument cmn_print_vec!(&[1, 2, 3]); } #[test] fn test_cmn_split() { + // Test that cmn_split! macro correctly splits the string argument into a vector of words let v = cmn_split!("Hello World"); assert_eq!(v, vec!["Hello", "World"]); } #[test] fn test_cmn_vec() { + // Test that cmn_vec! macro correctly creates a vector from the arguments let v = cmn_vec!(1, 2, 3); assert_eq!(v, &[1, 2, 3]); } #[test] fn test_cmn_contains() { + // Test that cmn_contains! macro correctly checks if the first string contains the second assert!(cmn_contains!("Hello", "H")); assert!(!cmn_contains!("Hello", "x")); } #[test] fn test_cmn_in_range() { + // Test that cmn_in_range! macro correctly checks if a number is within a range assert!(cmn_in_range!(10, 0, 100)); assert!(!cmn_in_range!(-10, 0, 100)); } + + #[test] + fn test_cmn_constants() { + // Test that each constant defined by the cmn_constants! macro has the expected value or is not empty + assert_eq!( + AVOGADRO, 6.02214076e23, + "AVOGADRO should have a specific value" + ); + assert_eq!( + BOLTZMANN, 1.380648e-23, + "BOLTZMANN should have a specific value" + ); + assert_eq!( + EULER, std::f64::consts::E, + "EULER should have a specific value" + ); + assert_eq!( + GAMMA, 0.5772156649015329, + "GAMMA should have a specific value" + ); + assert_eq!( + HASH_ALGORITHM, "Blake3", + "HASH_ALGORITHM should have a specific value" + ); + assert_eq!( + HASH_COST, 8, + "HASH_COST should have a specific value" + ); + assert_eq!( + HASH_LENGTH, 32, + "HASH_LENGTH should have a specific value" + ); + assert_eq!( + PHI, + (1.0 + SQRT5) / 2.0, + "PHI should have a specific value" + ); + assert_eq!( + PI, + std::f64::consts::PI, + "PI should have a specific value" + ); + assert_eq!( + PLANCK, 6.62607015e-34, + "PLANCK should have a specific value" + ); + assert_eq!( + SILVER_RATIO, + 1.0 + SQRT2, + "SILVER_RATIO should have a specific value" + ); + assert_eq!( + SPECIAL_CHARS, + &[ + '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', + '+', '=', '[', ']', '{', '}', '|', ';', ':', '"', '<', + '>', ',', '.', '?', '/', '~', '`' + ], + "SPECIAL_CHARS should have a specific value" + ); + assert_eq!( + SQRT2, + std::f64::consts::SQRT_2, + "SQRT2 should have a specific value" + ); + assert_eq!( + SQRT3, 1.7320508075688772, + "SQRT3 should have a specific value" + ); + assert_eq!( + SQRT5, 2.23606797749979, + "SQRT5 should have a specific value" + ); + assert_eq!(TAU, 2.0 * PI, "TAU should have a specific value"); + } }