feat: add speed conversion module

[AliAlimohammadi]

Description

This PR adds a new module for converting between different speed units (km/h, m/s, mph, knots, ft/s, Mach, and speed of light).

Features Added

• convert_speed: Convert speed values between any two supported units
• SpeedUnit enum for type-safe speed unit representation
• Support for 7 different speed units:
  • Kilometers per hour (km/h)
  • Meters per second (m/s) - SI derived unit
  • Miles per hour (mph)
  • Knots (nautical miles per hour)
  • Feet per second (ft/s)
  • Mach number (dimensionless)
  • Speed of light (c) - natural units
• Comprehensive test coverage

Type of Change

✅ New algorithm/data structure
✅ Documentation
✅ Tests

Testing

All tests pass:

cargo test conversions::speed

Results:

• 25 test assertions passed
• Test coverage includes:
  • Basic conversions (km/h ↔ m/s, mph ↔ knots, etc.)
  • All 7 speed units (km/h, m/s, mph, knot, ft/s, Mach, c)
  • Bidirectional conversions between all unit pairs
  • Same-unit conversions (identity)
  • High-speed conversions (Mach, speed of light)
  • Precision (results rounded to 3 decimal places)

Algorithm Complexity

• Time Complexity: $O(1)$ - constant time operations (direct multiplication/division)
• Space Complexity: $O(1)$ - fixed size enum and primitive types

Implementation Details

Conversion Algorithm

Uses kilometers per hour (km/h) as the base unit for all conversions:

1. Two-step process:
   • Convert input value from source unit → km/h
   • Convert km/h → target unit
2. Results rounded to 3 decimal places for precision

Speed Unit Values

All conversions use these standardized conversion factors:

To km/h (multiply by):

• km/h: 1.0
• m/s: 3.6
• mph: 1.609344
• knot: 1.852
• ft/s: 1.09728
• Mach: 1225.08 (at sea level, 15°C)
• c: 1,079,252,848.8

From km/h (multiply by):

• km/h: 1.0
• m/s: 0.277777778
• mph: 0.621371192
• knot: 0.539956803
• ft/s: 0.911344415
• Mach: 0.000816164
• c: 9.265669311e-10

Enum-Based Design

• Uses SpeedUnit enum instead of string dictionaries for type safety
• Implements Copy, Clone, Debug, PartialEq traits
• Implements Display trait for user-friendly unit names
• Private helper methods (as_kmh_multiplier(), kmh_multiplier()) for conversion logic

Type Safety Benefits

• Compile-time validation of units (no runtime string errors)
• No need for error handling - invalid units caught at compile time
• More efficient than dictionary lookups

References

• Kilometers per hour - Wikipedia
• Miles per hour - Wikipedia
• Knot (unit) - Wikipedia
• Meter per second - Wikipedia
• Foot per second - Wikipedia
• Mach number - Wikipedia
• Speed of light - Wikipedia

Checklist

✅ Code follows Rust idioms and best practices
✅ Self-documenting code with comprehensive doc comments
✅ All functions have doc comments
✅ Tests cover normal cases and edge cases
✅ Code compiles without warnings (clippy clean)
✅ All tests pass
✅ Proper use of type-safe enum (SpeedUnit)
✅ Module properly integrated into src/conversions/mod.rs
✅ No external dependencies beyond std

Example Usage

use conversions::speed::{convert_speed, SpeedUnit};

// Basic conversions
let ms = convert_speed(100.0, SpeedUnit::KilometersPerHour, SpeedUnit::MetersPerSecond);
assert_eq!(ms, 27.778);

let mph = convert_speed(100.0, SpeedUnit::KilometersPerHour, SpeedUnit::MilesPerHour);
assert_eq!(mph, 62.137);

// Nautical conversions
let knots = convert_speed(100.0, SpeedUnit::KilometresPerHour, SpeedUnit::Knot);
assert_eq!(knots, 53.996);

// Aviation speeds
let mach = convert_speed(1225.08, SpeedUnit::KilometersPerHour, SpeedUnit::Mach);
assert_eq!(mach, 1.0);

let kmh = convert_speed(2.0, SpeedUnit::Mach, SpeedUnit::KilometersPerHour);
assert_eq!(kmh, 2450.16);

// Speed of light conversions
let c_ms = convert_speed(1.0, SpeedUnit::SpeedOfLight, SpeedUnit::MetersPerSecond);
assert_eq!(c_ms, 299792458.24);

let fraction_c = convert_speed(0.1, SpeedUnit::SpeedOfLight, SpeedUnit::MetersPerSecond);
assert_eq!(fraction_c, 29979245.824); // 0.1c

// Feet per second
let fps = convert_speed(100.0, SpeedUnit::MetersPerSecond, SpeedUnit::FeetPerSecond);
assert_eq!(fps, 328.084);

// Same unit conversion (identity)
let same = convert_speed(100.0, SpeedUnit::KilometersPerHour, SpeedUnit::KilometersPerHour);
assert_eq!(same, 100.0);

Additional Notes

• Mach number is calculated using standard sea level conditions (340.3 m/s at 15°C). In reality, the speed of sound varies with temperature and altitude.
• Speed of light uses the exact defined value: c = 299,792,458 m/s (exact, by definition of the meter).

[AliAlimohammadi]

@siriak, this is ready to be merged.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.00%. Comparing base (39607d1) to head (bf90c42).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #998      +/-   ##
==========================================
+ Coverage   95.98%   96.00%   +0.01%     
==========================================
  Files         368      369       +1     
  Lines       25451    25557     +106     
==========================================
+ Hits        24430    24536     +106     
  Misses       1021     1021              

☔ 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.