feat: add comprehensive volume conversion module

[AliAlimohammadi]

Description

This PR adds a new volume conversion module to the conversions library, enabling conversion between 40+ volume units across different measurement systems.

Motivation

While the repository has excellent conversion modules for temperature, length, and other units, it lacks comprehensive volume conversion support. This module fills that gap by providing a robust, well-tested solution for volume conversions commonly needed in scientific, engineering, and everyday applications.

Implementation

Design Decisions

• SI-based conversions: All conversions route through cubic meters (the SI base unit) as an intermediary, ensuring consistency and accuracy
• Two-step conversion: Follows the established pattern of to_cubic_meters() → cubic_meters_to_unit() for clarity

Supported Units (40+ units)

Metric Units (9)

• Cubic meter, cubic centimeter, cubic millimeter
• Liter, milliliter, centiliter, deciliter, kiloliter, hectoliter

Imperial Units (7)

• Gallon, quart, pint, fluid ounce
• Tablespoon, teaspoon, barrel

US Customary Units (9)

• Liquid: gallon, quart, pint, cup, fluid ounce, tablespoon, teaspoon
• Dry: quart, pint
• Barrels: oil barrel, liquid barrel

Cubic Units (3)

• Cubic yard, cubic foot, cubic inch

Specialized Units (5)

• Board foot, cord (firewood)
• Metric cup
• Canadian tablespoon, Canadian teaspoon

Testing

Test Coverage

• ✅ 100+ individual conversion tests covering all major unit pairs
• ✅ Round-trip conversions verify accuracy in both directions for 8 common units
• ✅ Same-unit conversions ensure identity operations work correctly
• ✅ Edge cases including large values, small values, and precision tests
• ✅ Cross-system conversions (e.g., Imperial ↔ US, Metric ↔ Imperial)

Test Organization

All tests are consolidated into a single test_volume_conversions() function, organized by category for easy maintenance and readability.

Verification

cargo test volume          # Run all volume tests
cargo test --doc volume    # Run documentation tests
cargo clippy -- -D warnings  # Zero warnings
cargo fmt --check          # Properly formatted

Code Quality

• Documentation: Comprehensive module and function documentation with examples
• Type Safety: Enum prevents invalid unit specifications at compile time
• Precision: Uses f64 for all calculations with appropriate tolerance checks
• Consistency: Matches existing code style (particularly temperature.rs)
• No Dependencies: Uses only standard library

Examples

use rust_algorithms::conversions::volume::{convert_volume, VolumeUnit};

// Metric conversions
let liters = convert_volume(1.0, VolumeUnit::CubicMeter, VolumeUnit::Liter);
assert_eq!(liters, 1000.0);

// US customary
let gallons = convert_volume(1.0, VolumeUnit::Liter, VolumeUnit::GallonUs);
// ≈ 0.264172 gallons

// Imperial to US
let us_pints = convert_volume(1.0, VolumeUnit::PintImperial, VolumeUnit::PintUsLiquid);
// ≈ 1.20095 US pints

// Cooking measurements
let cups = convert_volume(16.0, VolumeUnit::TablespoonUs, VolumeUnit::CupUs);
assert_eq!(cups, 1.0);

References

All conversion factors are based on authoritative sources:

• Unit of volume - Wikipedia
• Cubic metre - Wikipedia
• Litre - Wikipedia
• Gallon - Wikipedia
• Pint - Wikipedia
• Barrel (unit) - Wikipedia

Checklist

• Code follows the repository's style guidelines
• Self-review of code completed
• Code is well-commented, particularly complex conversions
• Corresponding documentation added
• No new warnings generated
• Follows the same pattern as existing conversion modules

[codecov-commenter]

Codecov Report

❌ Patch coverage is 90.65421% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.12%. Comparing base (c6ab1f0) to head (6214806).

Files with missing lines	Patch %	Lines
src/conversions/volume.rs	90.65%	20 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1011      +/-   ##
==========================================
- Coverage   96.16%   96.12%   -0.05%     
==========================================
  Files         379      380       +1     
  Lines       28036    28250     +214     
==========================================
+ Hits        26961    27154     +193     
- Misses       1075     1096      +21     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.