#![forbid(unsafe_code)]
#![warn(missing_docs)]
use std::error::Error;
use std::fmt;
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct Voltage(f64);
impl Voltage {
pub fn volts(value: f64) -> Result<Self, ElectricError> {
validate_non_negative_finite(value, "voltage")?;
Ok(Self(value))
}
pub const fn as_volts(self) -> f64 {
self.0
}
}
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct Current(f64);
impl Current {
pub fn amperes(value: f64) -> Result<Self, ElectricError> {
validate_non_negative_finite(value, "current")?;
Ok(Self(value))
}
pub const fn as_amperes(self) -> f64 {
self.0
}
}
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct Resistance(f64);
impl Resistance {
pub fn ohms(value: f64) -> Result<Self, ElectricError> {
validate_positive_finite(value, "resistance")?;
Ok(Self(value))
}
pub const fn as_ohms(self) -> f64 {
self.0
}
}
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct Power(f64);
impl Power {
pub fn watts(value: f64) -> Result<Self, ElectricError> {
validate_non_negative_finite(value, "power")?;
Ok(Self(value))
}
pub fn from_voltage_and_current(
voltage: Voltage,
current: Current,
) -> Result<Self, ElectricError> {
let watts = voltage.0 * current.0;
ensure_finite(watts)?;
Ok(Self(watts))
}
pub const fn as_watts(self) -> f64 {
self.0
}
}
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct Duration(f64);
impl Duration {
pub fn seconds(value: f64) -> Result<Self, ElectricError> {
validate_non_negative_finite(value, "duration")?;
Ok(Self(value))
}
pub fn hours(value: f64) -> Result<Self, ElectricError> {
validate_non_negative_finite(value, "duration")?;
let seconds = value * 3_600.0;
ensure_finite(seconds)?;
Ok(Self(seconds))
}
pub const fn as_seconds(self) -> f64 {
self.0
}
pub fn as_hours(self) -> f64 {
self.0 / 3_600.0
}
}
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct Energy(f64);
impl Energy {
pub fn joules(value: f64) -> Result<Self, ElectricError> {
validate_non_negative_finite(value, "energy")?;
Ok(Self(value))
}
pub fn watt_hours(value: f64) -> Result<Self, ElectricError> {
validate_non_negative_finite(value, "energy")?;
let joules = value * 3_600.0;
ensure_finite(joules)?;
Ok(Self(joules))
}
pub fn from_power_over(power: Power, duration: Duration) -> Result<Self, ElectricError> {
let joules = power.0 * duration.0;
ensure_finite(joules)?;
Ok(Self(joules))
}
pub const fn as_joules(self) -> f64 {
self.0
}
pub fn as_watt_hours(self) -> f64 {
self.0 / 3_600.0
}
pub fn runtime_at(self, power: Power) -> Result<Duration, ElectricError> {
if power.0 == 0.0 {
return Err(ElectricError::ZeroPower);
}
let seconds = self.0 / power.0;
ensure_finite(seconds)?;
Ok(Duration(seconds))
}
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct DcOperatingPoint {
voltage: Voltage,
current: Current,
resistance: Resistance,
power: Power,
}
impl DcOperatingPoint {
pub fn from_voltage_and_resistance(
voltage: Voltage,
resistance: Resistance,
) -> Result<Self, ElectricError> {
let current = Current(voltage.0 / resistance.0);
ensure_finite(current.0)?;
Self::assemble(voltage, current, resistance)
}
pub fn from_current_and_resistance(
current: Current,
resistance: Resistance,
) -> Result<Self, ElectricError> {
let voltage = Voltage(current.0 * resistance.0);
ensure_finite(voltage.0)?;
Self::assemble(voltage, current, resistance)
}
pub fn from_voltage_and_current(
voltage: Voltage,
current: Current,
) -> Result<Self, ElectricError> {
if voltage.0 == 0.0 || current.0 == 0.0 {
return Err(ElectricError::UnderdeterminedResistance);
}
let resistance = Resistance(voltage.0 / current.0);
ensure_finite(resistance.0)?;
Self::assemble(voltage, current, resistance)
}
fn assemble(
voltage: Voltage,
current: Current,
resistance: Resistance,
) -> Result<Self, ElectricError> {
let power = Power::from_voltage_and_current(voltage, current)?;
Ok(Self {
voltage,
current,
resistance,
power,
})
}
pub const fn voltage(self) -> Voltage {
self.voltage
}
pub const fn current(self) -> Current {
self.current
}
pub const fn resistance(self) -> Resistance {
self.resistance
}
pub const fn power(self) -> Power {
self.power
}
}
pub fn series_resistance(resistors: &[Resistance]) -> Result<Resistance, ElectricError> {
if resistors.is_empty() {
return Err(ElectricError::EmptyResistanceNetwork);
}
let mut total = 0.0;
for resistor in resistors {
total += resistor.0;
ensure_finite(total)?;
}
Ok(Resistance(total))
}
pub fn parallel_resistance(resistors: &[Resistance]) -> Result<Resistance, ElectricError> {
if resistors.is_empty() {
return Err(ElectricError::EmptyResistanceNetwork);
}
let mut reciprocal_sum = 0.0;
for resistor in resistors {
reciprocal_sum += 1.0 / resistor.0;
ensure_finite(reciprocal_sum)?;
}
let equivalent = 1.0 / reciprocal_sum;
ensure_finite(equivalent)?;
if equivalent == 0.0 {
return Err(ElectricError::CalculationOutOfRange);
}
Ok(Resistance(equivalent))
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ElectricError {
NonFinite(&'static str),
Negative(&'static str),
Zero(&'static str),
UnderdeterminedResistance,
ZeroPower,
EmptyResistanceNetwork,
CalculationOutOfRange,
}
impl fmt::Display for ElectricError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::NonFinite(name) => write!(formatter, "{name} must be finite"),
Self::Negative(name) => write!(formatter, "{name} must not be negative"),
Self::Zero(name) => write!(formatter, "{name} must be greater than zero"),
Self::UnderdeterminedResistance => formatter
.write_str("voltage and current must both be positive to derive resistance"),
Self::ZeroPower => formatter.write_str("runtime at zero power is undefined"),
Self::EmptyResistanceNetwork => {
formatter.write_str("resistance network must not be empty")
}
Self::CalculationOutOfRange => {
formatter.write_str("calculation exceeded representable finite range")
}
}
}
}
impl Error for ElectricError {}
fn validate_non_negative_finite(value: f64, name: &'static str) -> Result<(), ElectricError> {
if !value.is_finite() {
return Err(ElectricError::NonFinite(name));
}
if value < 0.0 {
return Err(ElectricError::Negative(name));
}
Ok(())
}
fn validate_positive_finite(value: f64, name: &'static str) -> Result<(), ElectricError> {
validate_non_negative_finite(value, name)?;
if value == 0.0 {
return Err(ElectricError::Zero(name));
}
Ok(())
}
fn ensure_finite(value: f64) -> Result<(), ElectricError> {
if value.is_finite() {
Ok(())
} else {
Err(ElectricError::CalculationOutOfRange)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn voltage_and_resistance_derive_current_and_power() {
let point = DcOperatingPoint::from_voltage_and_resistance(
Voltage::volts(12.0).unwrap(),
Resistance::ohms(6.0).unwrap(),
)
.unwrap();
assert_eq!(point.current().as_amperes(), 2.0);
assert_eq!(point.power().as_watts(), 24.0);
}
#[test]
fn current_and_resistance_derive_voltage() {
let point = DcOperatingPoint::from_current_and_resistance(
Current::amperes(0.5).unwrap(),
Resistance::ohms(20.0).unwrap(),
)
.unwrap();
assert_eq!(point.voltage().as_volts(), 10.0);
assert_eq!(point.power().as_watts(), 5.0);
}
#[test]
fn voltage_and_current_derive_resistance() {
let point = DcOperatingPoint::from_voltage_and_current(
Voltage::volts(9.0).unwrap(),
Current::amperes(0.3).unwrap(),
)
.unwrap();
assert_eq!(point.resistance().as_ohms(), 30.0);
}
#[test]
fn equivalent_resistances_are_calculated() {
let resistors = [
Resistance::ohms(100.0).unwrap(),
Resistance::ohms(100.0).unwrap(),
];
assert_eq!(series_resistance(&resistors).unwrap().as_ohms(), 200.0);
assert!((parallel_resistance(&resistors).unwrap().as_ohms() - 50.0).abs() < 1e-12);
}
#[test]
fn power_over_time_produces_energy_and_runtime() {
let energy =
Energy::from_power_over(Power::watts(24.0).unwrap(), Duration::hours(3.0).unwrap())
.unwrap();
assert_eq!(energy.as_watt_hours(), 72.0);
assert_eq!(
energy
.runtime_at(Power::watts(36.0).unwrap())
.unwrap()
.as_hours(),
2.0
);
}
#[test]
fn invalid_inputs_are_rejected() {
assert_eq!(
Voltage::volts(f64::NAN),
Err(ElectricError::NonFinite("voltage"))
);
assert_eq!(
Current::amperes(-1.0),
Err(ElectricError::Negative("current"))
);
assert_eq!(
Resistance::ohms(0.0),
Err(ElectricError::Zero("resistance"))
);
assert_eq!(
parallel_resistance(&[]),
Err(ElectricError::EmptyResistanceNetwork)
);
assert_eq!(
Energy::joules(10.0)
.unwrap()
.runtime_at(Power::watts(0.0).unwrap()),
Err(ElectricError::ZeroPower)
);
}
#[test]
fn zero_pair_cannot_derive_resistance() {
assert_eq!(
DcOperatingPoint::from_voltage_and_current(
Voltage::volts(0.0).unwrap(),
Current::amperes(0.0).unwrap()
),
Err(ElectricError::UnderdeterminedResistance)
);
}
#[test]
fn calculation_overflow_is_reported() {
assert_eq!(
Power::from_voltage_and_current(
Voltage::volts(f64::MAX).unwrap(),
Current::amperes(2.0).unwrap()
),
Err(ElectricError::CalculationOutOfRange)
);
}
}