h_math/

lib.rs

/// h_math
/// 
/// A comprehensive math library for Rust, providing a wide range of mathematical functions and utilities.
/// The library is designed to be easy to use with traits and generics.
/// The naming conventions for traits and functions are h_ followed by what the trait and function does.
/// 
/// # Examples
/// h_average, h_median, h_haramond_product, h_factorial, h_sphere_volume ect.
/// 
/// use h_math::prelude::*; for the best experience, as it will import all the traits and functions into scope.
/// and since the traits are implemented for primitive types, you can call the functions directly on the values.
/// also, since the functions and traits always hav h_xxxxxx you won't have to worry about naming conflicts with other libraries.
/// 
/// Please refer to the documentation for each module for more details on the available functions and how to use them.
///
/// # Core Mathematics Functions
///
/// ## Factorial Trait (`Factorial`)
/// - **Function**: `h_factorial()` 
/// - **Input**: Any numeric type implementing `Copy + PartialOrd + Into<u32>`
/// - **Output**: `u64`
/// - **Purpose**: Calculates the factorial of a number (n!)
/// - **Formula**: n! = n × (n-1) × (n-2) × ... × 1
/// - **Panics**: If given a negative number
///
/// ## Root Degree Trait (`RootDegree`)
/// - **Function**: `h_root_degree(degree: u32)`
/// - **Input**: Self (numeric type), degree (u32)
/// - **Output**: `f64`
/// - **Purpose**: Calculates the nth root of a number
/// - **Formula**: ⁿ√x = x^(1/n)
///
/// ## h_sigma Function
/// - **Signature**: `h_sigma<T>(start: T, repetitions: u32, steps: T) -> f64`
/// - **Input**: start value, number of repetitions, step size
/// - **Output**: `f64` (sum)
/// - **Purpose**: Calculates the sum of an arithmetic sequence
/// - **Example**: h_sigma(1, 5, 1) sums 1+2+3+4+5 = 15
///
/// ## h_arrange_vec Function
/// - **Signature**: `h_arrange_vec<I>(start: I, stop: I, step: I) -> Vec<f64>`
/// - **Input**: start value, stop value, step size
/// - **Output**: `Vec<f64>` containing evenly spaced values
/// - **Purpose**: Creates a vector of evenly spaced numbers from start to stop
/// - **Returns empty**: If step is 0, or if direction is invalid (positive step but start > stop)
///
/// ## h_pi Function
/// - **Signature**: `h_pi() -> f64`
/// - **Input**: None
/// - **Output**: `f64` (π)
/// - **Purpose**: Returns the mathematical constant π (3.14159265...)
///
/// # Algebra Functions
///
/// ## h_quadratic_equation Function
/// - **Signature**: `h_quadratic_equation<A,B,C>(a: A, b: B, c: C) -> (f64, f64)`
/// - **Input**: Coefficients a, b, c of ax² + bx + c = 0
/// - **Output**: `(f64, f64)` tuple with two roots
/// - **Purpose**: Solves quadratic equations using the quadratic formula
/// - **Formula**: x = (-b ± √(b² - 4ac)) / 2a
/// - **Panics**: If discriminant is negative (no real roots)
///
/// ## h_simple_eq_checker_x Function
/// - **Signature**: `h_simple_eq_checker_x<...>(x_value: X, num_left: NL, x_left: XL, num_right: NR, x_right: XR) -> bool`
/// - **Input**: x value to check, left side numeric coefficient, left side x coefficient, right side numeric coefficient, right side x coefficient
/// - **Output**: `bool`
/// - **Purpose**: Checks if a given x value satisfies a linear equation: (x_left × x + num_left) = (x_right × x + num_right)
///
/// # Temperature Conversions
///
/// ## CelsiusToFahrenheit Trait
/// - **Function**: `h_celsius_to_fahrenheit()`
/// - **Input**: Temperature in Celsius
/// - **Output**: `f64` (Fahrenheit)
/// - **Formula**: (C × 9/5) + 32
///
/// ## FahrenheitToCelsius Trait
/// - **Function**: `h_fahrenheit_to_celsius()`
/// - **Input**: Temperature in Fahrenheit
/// - **Output**: `f64` (Celsius)
/// - **Formula**: (F - 32) × 5/9
///
/// ## CelsiusToKelvin Trait
/// - **Function**: `h_celsius_to_kelvin()`
/// - **Input**: Temperature in Celsius
/// - **Output**: `f64` (Kelvin)
/// - **Formula**: C + 273.15
///
/// ## KelvinToCelsius Trait
/// - **Function**: `h_kelvin_to_celsius()`
/// - **Input**: Temperature in Kelvin
/// - **Output**: `f64` (Celsius)
/// - **Formula**: K - 273.15
///
/// ## FahrenheitToKelvin Trait
/// - **Function**: `h_fahrenheit_to_kelvin()`
/// - **Input**: Temperature in Fahrenheit
/// - **Output**: `f64` (Kelvin)
/// - **Formula**: ((F - 32) × 5/9) + 273.15
///
/// ## KelvinToFahrenheit Trait
/// - **Function**: `h_kelvin_to_fahrenheit()`
/// - **Input**: Temperature in Kelvin
/// - **Output**: `f64` (Fahrenheit)
/// - **Formula**: ((K - 273.15) × 9/5) + 32
///
/// # Length Conversions
///
/// ## MetersToKilometers Trait
/// - **Function**: `h_meters_to_kilometers()`
/// - **Input**: Distance in meters
/// - **Output**: `f64` (kilometers)
/// - **Formula**: m ÷ 1000
///
/// ## KilometersToMeters Trait
/// - **Function**: `h_kilometers_to_meters()`
/// - **Input**: Distance in kilometers
/// - **Output**: `f64` (meters)
/// - **Formula**: km × 1000
///
/// ## CentimetersToMeters Trait
/// - **Function**: `h_centimeters_to_meters()`
/// - **Input**: Distance in centimeters
/// - **Output**: `f64` (meters)
/// - **Formula**: cm ÷ 100
///
/// ## MetersToCentimeters Trait
/// - **Function**: `h_meters_to_centimeters()`
/// - **Input**: Distance in meters
/// - **Output**: `f64` (centimeters)
/// - **Formula**: m × 100
///
/// ## CentimetersToMillimeters Trait
/// - **Function**: `h_centimeters_to_millimeters()`
/// - **Input**: Distance in centimeters
/// - **Output**: `f64` (millimeters)
/// - **Formula**: cm × 10
///
/// ## MillimetersToCentimeters Trait
/// - **Function**: `h_millimeters_to_centimeters()`
/// - **Input**: Distance in millimeters
/// - **Output**: `f64` (centimeters)
/// - **Formula**: mm ÷ 10
///
/// ## KilometersToMiles Trait
/// - **Function**: `h_kilometers_to_miles()`
/// - **Input**: Distance in kilometers
/// - **Output**: `f64` (miles)
/// - **Formula**: km × 0.621371
///
/// ## MilesToKilometers Trait
/// - **Function**: `h_miles_to_kilometers()`
/// - **Input**: Distance in miles
/// - **Output**: `f64` (kilometers)
/// - **Formula**: miles ÷ 0.621371
///
/// ## InchesToCentimeters Trait
/// - **Function**: `h_inches_to_centimeters()`
/// - **Input**: Distance in inches
/// - **Output**: `f64` (centimeters)
/// - **Formula**: inches × 2.54
///
/// ## CentimetersToInches Trait
/// - **Function**: `h_centimeters_to_inches()`
/// - **Input**: Distance in centimeters
/// - **Output**: `f64` (inches)
/// - **Formula**: cm ÷ 2.54
///
/// ## CentimetersToDecimeters Trait
/// - **Function**: `h_centimeters_to_decimeters()`
/// - **Input**: Distance in centimeters
/// - **Output**: `f64` (decimeters)
/// - **Formula**: cm ÷ 10
///
/// ## DecimetersToCentimeters Trait
/// - **Function**: `h_decimeters_to_centimeters()`
/// - **Input**: Distance in decimeters
/// - **Output**: `f64` (centimeters)
/// - **Formula**: dm × 10
///
/// # Geometry Functions
///
/// ## CircleCircumference Trait
/// - **Function**: `h_circle_circumference()`
/// - **Input**: Radius of circle
/// - **Output**: `f64`
/// - **Purpose**: Calculates the circumference of a circle
/// - **Formula**: 2πr
///
/// ## CircleArea Trait
/// - **Function**: `h_circle_area()`
/// - **Input**: Radius of circle
/// - **Output**: `f64`
/// - **Purpose**: Calculates the area of a circle
/// - **Formula**: πr²
///
/// ## h_pythagorean_theorem Function
/// - **Signature**: `h_pythagorean_theorem<A, B>(a: A, b: B) -> f64`
/// - **Input**: Two sides of a right triangle (a, b)
/// - **Output**: `f64` (hypotenuse)
/// - **Purpose**: Calculates the hypotenuse of a right triangle
/// - **Formula**: c = √(a² + b²)
///
/// ## h_reverse_pythagorean_theorem Function
/// - **Signature**: `h_reverse_pythagorean_theorem<K, H>(x: K, h: H) -> f64`
/// - **Input**: One known side (x) and hypotenuse (h)
/// - **Output**: `f64` (other side)
/// - **Purpose**: Finds the missing side of a right triangle
/// - **Formula**: a = √(h² - x²)
///
/// ## h_find_equal_legs_from_hypotenuse Function
/// - **Signature**: `h_find_equal_legs_from_hypotenuse<H>(h: H) -> f64`
/// - **Input**: Hypotenuse of an isosceles right triangle
/// - **Output**: `f64` (length of equal legs)
/// - **Purpose**: Finds the length of equal legs in a 45-45-90 triangle
/// - **Formula**: leg = √(h²/2)
///
/// ## ShortFromLongLeg30_60_90 Trait
/// - **Function**: `h_short_from_long_leg_30_60_90()`
/// - **Input**: Long leg of a 30-60-90 triangle
/// - **Output**: `f64` (short leg)
/// - **Formula**: short_leg = long_leg ÷ √3
///
/// # 3D Geometry Functions
///
/// ## SphereVolume Trait
/// - **Function**: `h_sphere_volume()`
/// - **Input**: Radius of sphere
/// - **Output**: `f64`
/// - **Purpose**: Calculates the volume of a sphere
/// - **Formula**: V = (4/3)πr³
///
/// ## SphereSurfaceArea Trait
/// - **Function**: `h_sphere_surface_area()`
/// - **Input**: Radius of sphere
/// - **Output**: `f64`
/// - **Purpose**: Calculates the surface area of a sphere
/// - **Formula**: A = 4πr²
///
/// ## CylinderVolume Trait
/// - **Function**: `h_cylinder_volume(height: H)`
/// - **Input**: Radius and height of cylinder
/// - **Output**: `f64`
/// - **Purpose**: Calculates the volume of a cylinder
/// - **Formula**: V = πr²h
///
/// ## CylinderSurfaceArea Trait
/// - **Function**: `h_cylinder_surface_area(height: H)`
/// - **Input**: Radius and height of cylinder
/// - **Output**: `f64`
/// - **Purpose**: Calculates the surface area of a cylinder
/// - **Formula**: A = 2πr² + 2πrh
///
/// ## CubeVolume Trait
/// - **Function**: `h_cube_volume()`
/// - **Input**: Side length of cube
/// - **Output**: `f64`
/// - **Purpose**: Calculates the volume of a cube
/// - **Formula**: V = s³
///
/// ## CubeSurfaceArea Trait
/// - **Function**: `h_cube_surface_area()`
/// - **Input**: Side length of cube
/// - **Output**: `f64`
/// - **Purpose**: Calculates the surface area of a cube
/// - **Formula**: A = 6s²
///
/// ## ConeVolume Trait
/// - **Function**: `h_cone_volume(height: H)`
/// - **Input**: Radius and height of cone
/// - **Output**: `f64`
/// - **Purpose**: Calculates the volume of a cone
/// - **Formula**: V = (1/3)πr²h
///
/// ## ConeSurfaceArea Trait
/// - **Function**: `h_cone_surface_area(height: H)`
/// - **Input**: Radius and height of cone
/// - **Output**: `f64`
/// - **Purpose**: Calculates the surface area of a cone
/// - **Formula**: A = πr(r + √(r² + h²)) where √(r² + h²) is the slant height
///
/// ## RectangularPrismVolume Trait
/// - **Function**: `h_rectangular_prism_volume(height: H)`
/// - **Input**: Length/width and height of rectangular prism
/// - **Output**: `f64`
/// - **Purpose**: Calculates the volume of a rectangular prism
/// - **Formula**: V = l × w × h
///
/// ## RectangularPrismSurfaceArea Trait
/// - **Function**: `h_rectangular_prism_surface_area(height: H)`
/// - **Input**: Length/width and height of rectangular prism
/// - **Output**: `f64`
/// - **Purpose**: Calculates the surface area of a rectangular prism
/// - **Formula**: A = 2(lw + lh + wh)
///
/// ## PyramidVolume Trait
/// - **Function**: `h_pyramid_volume(height: H)`
/// - **Input**: Base area and height of pyramid
/// - **Output**: `f64`
/// - **Purpose**: Calculates the volume of a pyramid
/// - **Formula**: V = (1/3) × base_area × height
///
/// ## SquarePyramidSurfaceArea Trait
/// - **Function**: `h_square_pyramid_surface_area(height: H)`
/// - **Input**: Base area and height of square pyramid
/// - **Output**: `f64`
/// - **Purpose**: Calculates the surface area of a square pyramid
/// - **Formula**: A = base_area + 2 × √(base_area/4) × slant_height
///
/// # Finance Functions
///
/// ## ROI Trait (Return on Investment)
/// - **Function**: `h_return_on_investment(new_value: f64)`
/// - **Input**: Initial investment value, new value
/// - **Output**: `f64` (percentage)
/// - **Purpose**: Calculates return on investment as a percentage
/// - **Formula**: ROI = ((new_value - initial) / initial) × 100
///
/// ## DiscountedPrice Trait
/// - **Function**: `h_decreased_price(decrease_percent: f64)`
/// - **Input**: Original price, discount percentage
/// - **Output**: `f64` (discounted price)
/// - **Purpose**: Calculates the price after a percentage discount
/// - **Formula**: discounted_price = original × (1 - percentage/100)
///
/// ## IncreasedPrice Trait
/// - **Function**: `h_increased_price(increase_percent: f64)`
/// - **Input**: Original price, increase percentage
/// - **Output**: `f64` (increased price)
/// - **Purpose**: Calculates the price after a percentage increase
/// - **Formula**: new_price = original × (1 + percentage/100)
///
/// # Probability Functions
///
/// ## h_permutations Function
/// - **Signature**: `h_permutations<T, S>(total: &T, select: &S) -> u64`
/// - **Input**: Total items (n), items to select (r)
/// - **Output**: `u64` (number of permutations)
/// - **Purpose**: Calculates the number of ways to arrange r items from n items
/// - **Formula**: P(n,r) = n! / (n-r)!
///
/// ## h_combinations Function
/// - **Signature**: `h_combinations<T, S>(total: &T, select: &S) -> u64`
/// - **Input**: Total items (n), items to select (r)
/// - **Output**: `u64` (number of combinations)
/// - **Purpose**: Calculates the number of ways to choose r items from n items (order doesn't matter)
/// - **Formula**: C(n,r) = n! / (r! × (n-r)!)
///
/// # Statistics Functions
///
/// ## Average Trait
/// - **Function**: `h_average()`
/// - **Input**: Slice of numeric values `&[T]`
/// - **Output**: `f64`
/// - **Purpose**: Calculates the arithmetic mean of a set of numbers
/// - **Returns 0.0**: If slice is empty
///
/// ## Median Trait
/// - **Function**: `h_median()`
/// - **Input**: Slice of numeric values `&[T]`
/// - **Output**: `f64`
/// - **Purpose**: Calculates the median (middle value) of a set of numbers
/// - **Behavior**: For even-length sets, returns the average of two middle values
/// - **Returns 0.0**: If slice is empty
///
/// ## Sum Trait
/// - **Function**: `h_sum()`
/// - **Input**: Slice or Vec of numeric values
/// - **Output**: `f64`
/// - **Purpose**: Calculates the sum of all elements
///
/// ## Variance Trait
/// - **Function**: `h_variance()`
/// - **Input**: Slice of numeric values `&[T]`
/// - **Output**: `f64`
/// - **Purpose**: Calculates the variance (range) between max and min values
/// - **Formula**: max - min
/// - **Returns 0.0**: If less than 2 elements
///
/// ## ModusMult Trait
/// - **Function**: `h_modus_mult()`
/// - **Input**: Slice of numeric values `&[T]`
/// - **Output**: `Vec<f64>` (all modes)
/// - **Purpose**: Finds all values that appear most frequently
/// - **Returns empty**: If no value appears more than once
///
/// # Linear Algebra Functions
///
/// ## h_hadamard_product Function (private)
/// - **Signature**: `h_hadamard_product<I, T>(vec1: &[I], vec2: &[T]) -> Vec<f64>`
/// - **Input**: Two vectors of equal length
/// - **Output**: `Vec<f64>` (element-wise product)
/// - **Purpose**: Computes element-wise multiplication of two vectors
/// - **Panics**: If vectors have different lengths
///
/// ## h_2d_dot_product Function
/// - **Signature**: `h_2d_dot_product<A, B>(vec1: &Vec<A>, vec2: &Vec<B>) -> f64`
/// - **Input**: Two vectors of equal length
/// - **Output**: `f64` (scalar)
/// - **Purpose**: Calculates the dot product of two vectors
/// - **Formula**: vec1 · vec2 = Σ(a_i × b_i)
/// - **Panics**: If vectors have different lengths
///
/// # Collection/Functionality Traits
///
/// ## HashMapValuesToHashSet Trait
/// - **Function**: `h_hashmap_values_to_hashset()`
/// - **Input**: HashMap with cloneable values
/// - **Output**: `HashSet<V>` containing all unique values
/// - **Purpose**: Extracts all values from a HashMap into a HashSet
///
/// ## HashMapKeysToHashSet Trait
/// - **Function**: `h_hashmap_keys_to_hashset()`
/// - **Input**: HashMap with cloneable keys
/// - **Output**: `HashSet<K>` containing all unique keys
/// - **Purpose**: Extracts all keys from a HashMap into a HashSet
///
/// ## ListToHashMap Trait
/// - **Function**: `h_list_to_hashmap(&self, values: &[V])`
/// - **Input**: Keys (Vec or slice), values slice
/// - **Output**: `HashMap<K, V>`
/// - **Purpose**: Creates a HashMap from a list of keys and a list of values
/// - **Panics**: If keys and values have different lengths, or if keys contain duplicates
///
/// ## ListToHashSet Trait
/// - **Function**: `h_list_to_hashset()`
/// - **Input**: Slice or Vec of values
/// - **Output**: `HashSet<T>` with unique elements
/// - **Purpose**: Converts a list to a HashSet, removing duplicates
///
/// ## Tof64 Trait
/// - **Function**: `h_f64()`
/// - **Input**: Any numeric type implementing `Copy + Into<f64>`
/// - **Output**: `f64`
/// - **Purpose**: Generic conversion to f64 for any numeric type
///
/// ## Toi32 Trait
/// - **Function**: `h_i32()`
/// - **Input**: Any numeric type implementing `Copy + Into<i32>`
/// - **Output**: `i32`
/// - **Purpose**: Generic conversion to i32 for any numeric type
///
/// ## ToVecf64 Trait
/// - **Function**: `h_to_vec_f64()`
/// - **Input**: Vec<T> where T implements `Copy + Into<f64>`
/// - **Output**: `Vec<f64>`
/// - **Purpose**: Converts a vector of any numeric type to a vector of f64
///
/// ## ToVeci32 Trait
/// - **Function**: `h_to_vec_i32()`
/// - **Input**: Vec<T> where T implements `Copy + Into<i32>`
/// - **Output**: `Vec<i32>`
/// - **Purpose**: Converts a vector of any numeric type to a vector of i32
///
/// # Terminal Input Functions
///
/// ## h_input_data_single_f64 Function
/// - **Signature**: `h_input_data_single_f64(length: i32) -> Vec<f64>`
/// - **Input**: 
///   - `length`: Number of data points to collect (if ≤ 0, collects until user enters "<<")
/// - **Output**: `Vec<f64>` containing the input numbers
/// - **Purpose**: Prompts user to enter f64 numbers one at a time
/// - **Behavior**: 
///   - Skips zero values automatically
///   - If length > 0, collects exactly that many non-zero numbers
///   - If length ≤ 0, continues until user enters "<<"
///
/// ## h_input_data_single_i32 Function
/// - **Signature**: `h_input_data_single_i32(length: i32) -> Vec<i32>`
/// - **Input**: 
///   - `length`: Number of data points to collect (if ≤ 0, collects until user enters "<<")
/// - **Output**: `Vec<i32>` containing the input integers
/// - **Purpose**: Prompts user to enter i32 integers one at a time
/// - **Behavior**: 
///   - Skips zero values automatically
///   - If length > 0, collects exactly that many non-zero numbers
///   - If length ≤ 0, continues until user enters "<<"
///
/// ## InputType Enum
/// - **Variants**: `Lowercase`, `Uppercase`, `Letters`, `Integer`
/// - **Purpose**: Specifies validation requirements for input strings
/// - **Usage**: Used with the ValidateInput trait to validate string content
///
/// ## ValidateInput Trait
/// - **Function**: `h_validate_input(input_requirements: InputType) -> Result<(), String>`
/// - **Input**: 
///   - Self: String to validate
///   - `input_requirements`: InputType enum specifying validation rules
/// - **Output**: `Result<(), String>` 
///   - Ok(()) if validation passes
///   - Err(String) with error message listing unexpected characters if validation fails
/// - **Purpose**: Validates string input against specific requirements
/// - **Validation Options**:
///   - `Lowercase`: Only a-z allowed
///   - `Uppercase`: Only A-Z allowed
///   - `Letters`: Both uppercase and lowercase letters allowed (A-Z, a-z)
///   - `Integer`: Only digits 0-9 allowed (must be parseable as i32)
/// - **Returns Error**: If input is empty or contains invalid characters
///
///








pub mod prelude;

pub mod algebra;
pub mod conversions;
pub mod core_math;
pub mod finance;
pub mod functionality;
pub mod geometry;
pub mod linear_algebra;
pub mod probability;
pub mod statisticss;
pub mod terminal_input;