Stabilize UnitMath v1.0.0

Author: LJrobinson

Cargo.lock

@@ -1,6 +1,11 @@
 [package]
 name = "unitmath"
-version = "0.8.0"
+version = "1.0.0"
 edition = "2021"
+description = "A small Rust library and CLI for unit conversions, parsing, and package math."
+license = "MIT"
+repository = "https://github.com/LJrobinson/UnitMath"
+keywords = ["units", "conversion", "measurement", "parsing", "cli"]
+categories = ["command-line-utilities", "parser-implementations", "science", "mathematics"]
 
 [dependencies]

Cargo.toml

@@ -1,133 +1,163 @@
 # UnitMath
 
-UnitMath is a small Rust library for pure unit conversion utilities.
+UnitMath is a small Rust library and dependency-free CLI for unit conversions, parsing, and package math.
 
-Version 0.8.0 supports weight, US liquid volume, potency conversions, package math helpers, basic string parsing, and parsed conversion helpers.
+Version 1.0.0 is a stable MVP focused on:
+
+- Weight conversions
+- US liquid volume conversions
+- Potency conversions
+- Simple package math helpers
+- Basic string parsing for weight, volume, and potency quantities
+- Parsed conversion helpers
+- A minimal CLI
+
+UnitMath intentionally does not include universal conversion, package parsing, JSON output, or trait-based quantity abstractions yet.
 
 ## Supported Units
 
 ### Weight
 
-- Milligram
-- Gram
-- Kilogram
-- Ounce
-- Pound
+- Milligram: `mg`
+- Gram: `g`, `gram`, `grams`
+- Kilogram: `kg`
+- Ounce: `oz`, `ounce`, `ounces`
+- Pound: `lb`, `lbs`, `pound`, `pounds`
 
 Weight conversions use grams as the canonical base unit internally.
 
 ### Volume
 
-- Milliliter
-- Liter
-- FluidOunce
-- Cup
-- Pint
-- Quart
-- Gallon
+- Milliliter: `ml`, `milliliter`, `milliliters`
+- Liter: `l`, `liter`, `liters`
+- US fluid ounce: `fl oz`, `floz`, `fluid ounce`, `fluid ounces`
+- US cup: `cup`, `cups`
+- US pint: `pint`, `pints`
+- US quart: `quart`, `quarts`
+- US gallon: `gallon`, `gallons`
 
 Volume conversions use milliliters as the canonical base unit internally.
 
 ### Potency
 
-- Percent
-- MilligramsPerGram
+- Percent: `%`, `percent`, `percentage`
+- Milligrams per gram: `mg/g`, `mgg`, `mg per g`, `mg/g dry weight`, `milligrams per gram`
 
 Potency conversions use milligrams per gram as the canonical base unit internally.
 
-### Package Math
-
-- `calculate_total_units(container_count, units_per_container)`
-- `calculate_total_quantity(unit_count, quantity_per_unit)`
+## Library Usage
 
-Package math helpers multiply counts by per-unit quantities without applying unit conversion.
+```rust
+use unitmath::{
+    calculate_total_quantity, calculate_total_units, convert_parsed_potency,
+    convert_parsed_volume, convert_parsed_weight, convert_potency, convert_volume,
+    convert_weight, parse_potency, parse_volume, parse_weight, PotencyUnit, VolumeUnit,
+    WeightUnit,
+};
 
-### Weight Parsing
+let grams = convert_weight(1000.0, WeightUnit::Milligram, WeightUnit::Gram);
+assert_eq!(grams, 1.0);
 
-- `parse_weight("1000 mg")`
-- `parse_weight("1000mg")`
-- `parse_weight("3.5 g")`
-- `parse_weight("2 pounds")`
+let liters = convert_volume(1000.0, VolumeUnit::Milliliter, VolumeUnit::Liter);
+assert_eq!(liters, 1.0);
 
-Weight parsing is case-insensitive and returns a `ParsedQuantity<WeightUnit>`.
+let milligrams_per_gram =
+    convert_potency(22.4, PotencyUnit::Percent, PotencyUnit::MilligramsPerGram);
+assert_eq!(milligrams_per_gram, 224.0);
 
-### Volume Parsing
+let units = calculate_total_units(2.0, 12.0);
+assert_eq!(units, 24.0);
 
-- `parse_volume("1000 ml")`
-- `parse_volume("1000ml")`
-- `parse_volume("8 fl oz")`
-- `parse_volume("2 gallons")`
+let total_grams = calculate_total_quantity(10.0, 3.5);
+assert_eq!(total_grams, 35.0);
 
-Volume parsing is case-insensitive and returns a `ParsedQuantity<VolumeUnit>`.
+let parsed_weight = parse_weight("  3.5G  ")?;
+assert_eq!(parsed_weight.value, 3.5);
+assert_eq!(parsed_weight.unit, WeightUnit::Gram);
 
-### Potency Parsing
+let parsed_volume = parse_volume("8 fl oz")?;
+assert_eq!(parsed_volume.unit, VolumeUnit::FluidOunce);
 
-- `parse_potency("22.4%")`
-- `parse_potency("22.4 percent")`
-- `parse_potency("224 mg/g")`
-- `parse_potency("224 milligrams per gram")`
+let parsed_potency = parse_potency("22.4%")?;
+assert_eq!(parsed_potency.unit, PotencyUnit::Percent);
 
-Potency parsing is case-insensitive and returns a `ParsedQuantity<PotencyUnit>`.
+let grams = convert_parsed_weight("1000mg", WeightUnit::Gram)?;
+assert_eq!(grams, 1.0);
 
-### Parsed Conversion Helpers
+let cups = convert_parsed_volume("8 fl oz", VolumeUnit::Cup)?;
+assert_eq!(cups, 1.0);
 
-- `convert_parsed_weight("1000mg", WeightUnit::Gram)`
-- `convert_parsed_volume("8 fl oz", VolumeUnit::Cup)`
-- `convert_parsed_potency("22.4%", PotencyUnit::MilligramsPerGram)`
+let milligrams_per_gram =
+    convert_parsed_potency("22.4%", PotencyUnit::MilligramsPerGram)?;
+assert_eq!(milligrams_per_gram, 224.0);
 
-Parsed conversion helpers parse a quantity string and convert it to a target unit in one step.
+# Ok::<(), unitmath::UnitMathError>(())
+```
 
-## Usage
+## Parsing Examples
 
 ```rust
-use unitmath::{
-    calculate_total_quantity, calculate_total_units, convert_potency, convert_volume,
-    convert_parsed_potency, convert_parsed_volume, convert_parsed_weight, convert_weight,
-    parse_potency, parse_volume, parse_weight, PotencyUnit, VolumeUnit, WeightUnit,
-};
+use unitmath::{parse_potency, parse_volume, parse_weight, PotencyUnit, VolumeUnit, WeightUnit};
 
-let grams = convert_weight(1000.0, WeightUnit::Milligram, WeightUnit::Gram);
-assert_eq!(grams, 1.0);
+assert_eq!(parse_weight("1000 mg")?.unit, WeightUnit::Milligram);
+assert_eq!(parse_weight("1000mg")?.unit, WeightUnit::Milligram);
+assert_eq!(parse_weight(".5 g")?.value, 0.5);
 
-let pounds = convert_weight(16.0, WeightUnit::Ounce, WeightUnit::Pound);
-assert!((pounds - 1.0).abs() < 1e-12);
+assert_eq!(parse_volume("1000 ml")?.unit, VolumeUnit::Milliliter);
+assert_eq!(parse_volume("8floz")?.unit, VolumeUnit::FluidOunce);
+assert_eq!(parse_volume("2 gallons")?.unit, VolumeUnit::Gallon);
 
-let liters = convert_volume(1000.0, VolumeUnit::Milliliter, VolumeUnit::Liter);
-assert!((liters - 1.0).abs() < 1e-12);
+assert_eq!(parse_potency("22.4 %")?.unit, PotencyUnit::Percent);
+assert_eq!(parse_potency("224mg/g")?.unit, PotencyUnit::MilligramsPerGram);
+assert_eq!(
+    parse_potency("224 milligrams per gram")?.unit,
+    PotencyUnit::MilligramsPerGram
+);
 
-let milligrams_per_gram = convert_potency(22.4, PotencyUnit::Percent, PotencyUnit::MilligramsPerGram);
-assert!((milligrams_per_gram - 224.0).abs() < 1e-12);
+# Ok::<(), unitmath::UnitMathError>(())
+```
 
-let units = calculate_total_units(2.0, 12.0);
-assert_eq!(units, 24.0);
+Parsing trims whitespace, is case-insensitive, and returns `UnitMathError` for empty input, missing numbers, invalid numbers, missing units, and unknown units.
 
-let grams = calculate_total_quantity(10.0, 3.5);
-assert_eq!(grams, 35.0);
+## Package Helpers
 
-let parsed = parse_weight("3.5 g").unwrap();
-assert_eq!(parsed.value, 3.5);
-assert_eq!(parsed.unit, WeightUnit::Gram);
+```rust
+use unitmath::{calculate_total_quantity, calculate_total_units};
 
-let parsed = parse_volume("8 fl oz").unwrap();
-assert_eq!(parsed.value, 8.0);
-assert_eq!(parsed.unit, VolumeUnit::FluidOunce);
+let units = calculate_total_units(5.0, 24.0);
+assert_eq!(units, 120.0);
 
-let parsed = parse_potency("22.4%").unwrap();
-assert_eq!(parsed.value, 22.4);
-assert_eq!(parsed.unit, PotencyUnit::Percent);
+let total_milligrams = calculate_total_quantity(24.0, 100.0);
+assert_eq!(total_milligrams, 2400.0);
+```
 
-let grams = convert_parsed_weight("1000mg", WeightUnit::Gram).unwrap();
-assert_eq!(grams, 1.0);
+Package helpers only multiply counts by per-unit quantities. They do not parse package strings or perform unit conversion.
 
-let cups = convert_parsed_volume("8 fl oz", VolumeUnit::Cup).unwrap();
-assert!((cups - 1.0).abs() < 1e-12);
+## CLI Usage
 
-let milligrams_per_gram =
-    convert_parsed_potency("22.4%", PotencyUnit::MilligramsPerGram).unwrap();
-assert_eq!(milligrams_per_gram, 224.0);
+```sh
+unitmath weight "1000mg" g
+unitmath weight "1 lb" oz
+unitmath volume "8 fl oz" cup
+unitmath volume "1 gallon" ml
+unitmath potency "22.4%" mg/g
+unitmath potency "224mg/g" percent
+```
+
+Each command prints only the numeric converted value on success. Errors are written to stderr with usage guidance.
+
+## Examples
+
+```sh
+cargo run --example basic_weight
+cargo run --example basic_volume
+cargo run --example basic_potency
 ```
 
-## Roadmap
+## Roadmap After v1.0.0
 
 - Additional parsers
-- CLI
+- Package parsing
+- More unit families
+- Optional structured output modes
+- Broader CLI ergonomics

README.md

@@ -0,0 +1,15 @@
+use unitmath::{convert_parsed_potency, convert_potency, parse_potency, PotencyUnit};
+
+fn main() -> Result<(), unitmath::UnitMathError> {
+    let milligrams_per_gram =
+        convert_potency(22.4, PotencyUnit::Percent, PotencyUnit::MilligramsPerGram);
+    println!("22.4% = {milligrams_per_gram} mg/g");
+
+    let parsed = parse_potency("224 mg/g")?;
+    println!("parsed potency: {} {:?}", parsed.value, parsed.unit);
+
+    let percent = convert_parsed_potency("224mg/g", PotencyUnit::Percent)?;
+    println!("224 mg/g = {percent}%");
+
+    Ok(())
+}

examples/basic_potency.rs

@@ -0,0 +1,14 @@
+use unitmath::{convert_parsed_volume, convert_volume, parse_volume, VolumeUnit};
+
+fn main() -> Result<(), unitmath::UnitMathError> {
+    let liters = convert_volume(1000.0, VolumeUnit::Milliliter, VolumeUnit::Liter);
+    println!("1000 ml = {liters} l");
+
+    let parsed = parse_volume("8 fl oz")?;
+    println!("parsed volume: {} {:?}", parsed.value, parsed.unit);
+
+    let cups = convert_parsed_volume("8 fl oz", VolumeUnit::Cup)?;
+    println!("8 fl oz = {cups} cup");
+
+    Ok(())
+}

examples/basic_volume.rs

@@ -0,0 +1,14 @@
+use unitmath::{convert_parsed_weight, convert_weight, parse_weight, WeightUnit};
+
+fn main() -> Result<(), unitmath::UnitMathError> {
+    let grams = convert_weight(1000.0, WeightUnit::Milligram, WeightUnit::Gram);
+    println!("1000 mg = {grams} g");
+
+    let parsed = parse_weight("3.5 g")?;
+    println!("parsed weight: {} {:?}", parsed.value, parsed.unit);
+
+    let ounces = convert_parsed_weight("3.5g", WeightUnit::Ounce)?;
+    println!("3.5 g = {ounces} oz");
+
+    Ok(())
+}

examples/basic_weight.rs

@@ -1,3 +1,5 @@
+use std::{error::Error, fmt};
+
 /// Errors returned by UnitMath parsing helpers.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum UnitMathError {
@@ -12,3 +14,19 @@ pub enum UnitMathError {
     /// The unit string is not supported.
     UnknownUnit,
 }
+
+impl fmt::Display for UnitMathError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let message = match self {
+            Self::EmptyInput => "input is empty",
+            Self::MissingNumber => "missing numeric value",
+            Self::InvalidNumber => "invalid numeric value",
+            Self::MissingUnit => "missing unit",
+            Self::UnknownUnit => "unknown unit",
+        };
+
+        formatter.write_str(message)
+    }
+}
+
+impl Error for UnitMathError {}