Crate conversions_rs

Crate conversions_rs 

Source
Expand description

§Conversions RS - A Comprehensive Unit Conversion Library

conversions_rs is a Rust library and command-line tool for converting between different units of measurement. It supports comprehensive SI (International System of Units) base and derived units including: length, weight/mass, temperature, volume, time, electric current, amount of substance, luminous intensity, and area with high precision and extensive unit support.

§Features

§SI Base Units

  • Length conversions: meters, kilometers, feet, inches, yards, miles, etc.
  • Mass conversions: kilograms, grams, pounds, ounces, tons, stones
  • Temperature conversions: Celsius, Fahrenheit, Kelvin
  • Time conversions: seconds, minutes, hours, days, weeks, years, etc.
  • Electric current conversions: amperes and SI prefixes (mA, µA, kA, etc.)
  • Amount of substance conversions: moles and SI prefixes (mmol, µmol, etc.)
  • Luminous intensity conversions: candela and related historical units

§SI Derived Units

  • Volume conversions: liters, gallons (US/UK), cups, pints, quarts, etc.
  • Area conversions: square meters, acres, hectares, square feet, etc.

§Additional Features

  • Case-insensitive unit names with support for singular/plural forms
  • High precision calculations using standard conversion factors
  • Comprehensive error handling for invalid units
  • Modular API organized by unit type for better discoverability

§Usage Patterns

§1. Modular API (Recommended - Type-safe & Discoverable)

The modular API organizes conversions by unit type, making it easy to discover available conversions with IDE autocomplete:

use conversions_rs::conversions::*;

// Length conversions - organized by source unit
let feet = length::meters::to_feet(10.0);           // 32.8084 feet
let inches = length::feet::to_inches(5.0);          // 60.0 inches  
let cm = length::inches::to_centimeters(12.0);      // 30.48 cm
let km = length::miles::to_kilometers(5.0);         // 8.0467 km

// Weight conversions
let pounds = weight::kilograms::to_pounds(5.0);     // 11.0231 pounds
let grams = weight::pounds::to_grams(1.0);          // 453.592 grams

// Temperature conversions
let fahrenheit = temperature::celsius::to_fahrenheit(25.0);  // 77.0°F
let kelvin = temperature::celsius::to_kelvin(0.0);           // 273.15K

// Volume conversions
let gallons = volume::liters::to_gallons_us(10.0);          // 2.64 gallons
let milliliters = volume::gallons_us::to_milliliters(1.0);  // 3785.41 ml

// Time conversions (NEW SI BASE UNIT)
let minutes = time::seconds::to_minutes(3600.0);            // 60.0 minutes
let hours = time::minutes::to_hours(120.0);                 // 2.0 hours
let milliseconds = time::seconds::to_milliseconds(1.5);     // 1500.0 ms

// Electric current conversions (NEW SI BASE UNIT)
let milliamperes = current::amperes::to_milliamperes(1.5);  // 1500.0 mA
let amperes = current::milliamperes::to_amperes(500.0);     // 0.5 A
let microamperes = current::amperes::to_microamperes(0.001); // 1000.0 μA

// Amount of substance conversions (NEW SI BASE UNIT)
let millimoles = substance::moles::to_millimoles(0.5);      // 500.0 mmol
let moles = substance::millimoles::to_moles(250.0);         // 0.25 mol
let micromoles = substance::moles::to_micromoles(0.001);    // 1000.0 μmol

// Luminous intensity conversions (NEW SI BASE UNIT)
let millicandela = luminous_intensity::candela::to_millicandela(2.5);  // 2500.0 mcd
let candela = luminous_intensity::millicandela::to_candela(1500.0);    // 1.5 cd
let hefnerkerze = luminous_intensity::candela::to_hefnerkerze(1.0);    // 1.11 hk

// Area conversions (NEW SI DERIVED UNIT)
let hectares = area::square_meters::to_hectares(10000.0);   // 1.0 ha
let acres = area::hectares::to_acres(1.0);                  // 2.471 acres
let sq_feet = area::square_meters::to_square_feet(1.0);     // 10.764 ft²

// Easy to chain conversions
let result = length::meters::to_feet(length::kilometers::to_meters(1.0)); // 1 km to feet

§2. General Conversion Functions (String-based)

Best for user input and flexible conversions:

use conversions_rs::*;

// Length conversions
let meters = convert_length(100.0, "ft", "m").unwrap();
println!("100 feet = {:.2} meters", meters);

// Weight conversions
let pounds = convert_weight(5.0, "kg", "lb").unwrap();
println!("5 kg = {:.2} pounds", pounds);

// Temperature conversions  
let celsius = convert_temperature(32.0, "F", "C").unwrap();
println!("32°F = {:.1}°C", celsius);

// Volume conversions
let liters = convert_volume(1.0, "gal", "l").unwrap();
println!("1 gallon = {:.2} liters", liters);

// Time conversions
let seconds = convert_time(5.0, "min", "s").unwrap();
println!("5 minutes = {:.0} seconds", seconds);

// Electric current conversions
let amperes = convert_current(1500.0, "mA", "A").unwrap();
println!("1500 mA = {:.2} A", amperes);

// Amount of substance conversions
let millimoles = convert_amount(0.5, "mol", "mmol").unwrap();
println!("0.5 mol = {:.0} mmol", millimoles);

// Luminous intensity conversions
let millicandela = convert_luminous_intensity(2.5, "cd", "mcd").unwrap();
println!("2.5 cd = {:.0} mcd", millicandela);

// Area conversions
let hectares = convert_area(10000.0, "m²", "ha").unwrap();
println!("10000 m² = {:.1} ha", hectares);

§3. Legacy Functions (Backward compatible)

use conversions_rs::*;

let feet = meters_to_feet(10.0);
let kg = pounds_to_kilograms(22.0);
let fahrenheit = celsius_to_fahrenheit(25.0);

§Error Handling

The general conversion functions return Result<f64, String> for proper error handling:

use conversions_rs::convert_length;

match convert_length(100.0, "ft", "invalid_unit") {
    Ok(result) => println!("Converted: {}", result),
    Err(error) => eprintln!("Conversion error: {}", error),
}

§Command-Line Usage

This library can also be used as a command-line tool with support for all SI units:

# SI Base Units
conversions_rs length 100 ft m              # Length conversions
conversions_rs weight 5 kg lb               # Mass conversions  
conversions_rs temperature 32 F C           # Temperature conversions
conversions_rs time 3600 s min              # Time conversions
conversions_rs current 1500 mA A            # Electric current conversions
conversions_rs amount 0.5 mol mmol          # Amount of substance conversions
conversions_rs luminosity 2.5 cd mcd        # Luminous intensity conversions

# SI Derived Units
conversions_rs volume 5 gal l               # Volume conversions
conversions_rs area 10000 "m²" ha           # Area conversions

# Interactive mode with full menu
conversions_rs

Re-exports§

pub use conversions::*;

Modules§

conversions
Unit conversion modules for the conversions_rs library.