#![forbid(unsafe_code)]
#![warn(missing_docs)]
use std::error::Error;
use std::f64::consts::PI;
use std::fmt;
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct FlowRate(f64);
impl FlowRate {
pub fn liters_per_minute(value: f64) -> Result<Self, SuidoError> {
validate_non_negative_finite(value, "flow rate")?;
Ok(Self(value))
}
pub const fn as_liters_per_minute(self) -> f64 {
self.0
}
pub fn volume_over(self, duration: Duration) -> Result<Volume, SuidoError> {
let liters = self.0 * duration.as_seconds() / 60.0;
ensure_finite(liters)?;
Ok(Volume(liters))
}
}
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct FlowMargin(f64);
impl FlowMargin {
pub const fn as_liters_per_minute(self) -> f64 {
self.0
}
}
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct Volume(f64);
impl Volume {
pub fn liters(value: f64) -> Result<Self, SuidoError> {
validate_non_negative_finite(value, "volume")?;
Ok(Self(value))
}
pub const fn as_liters(self) -> f64 {
self.0
}
}
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct Duration(f64);
impl Duration {
pub fn seconds(value: f64) -> Result<Self, SuidoError> {
validate_non_negative_finite(value, "duration")?;
Ok(Self(value))
}
pub fn minutes(value: f64) -> Result<Self, SuidoError> {
validate_non_negative_finite(value, "duration")?;
let seconds = value * 60.0;
ensure_finite(seconds)?;
Ok(Self(seconds))
}
pub const fn as_seconds(self) -> f64 {
self.0
}
}
#[derive(Debug, Clone, Copy, PartialEq, PartialOrd)]
pub struct PipeDiameter(f64);
impl PipeDiameter {
pub fn millimeters(value: f64) -> Result<Self, SuidoError> {
validate_positive_finite(value, "pipe diameter")?;
Ok(Self(value))
}
pub const fn as_millimeters(self) -> f64 {
self.0
}
pub fn velocity_mps(self, flow: FlowRate) -> Result<f64, SuidoError> {
let diameter_m = self.0 / 1_000.0;
let area_m2 = PI * diameter_m * diameter_m / 4.0;
let cubic_meters_per_second = flow.as_liters_per_minute() / 60_000.0;
let velocity = cubic_meters_per_second / area_m2;
ensure_finite(velocity)?;
Ok(velocity)
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct FixtureDemand {
name: String,
flow_per_unit: FlowRate,
units: u32,
}
impl FixtureDemand {
pub fn new(
name: impl Into<String>,
flow_per_unit: FlowRate,
units: u32,
) -> Result<Self, SuidoError> {
let name = name.into();
if name.trim().is_empty() {
return Err(SuidoError::EmptyFixtureName);
}
if units == 0 {
return Err(SuidoError::ZeroFixtureUnits);
}
Ok(Self {
name,
flow_per_unit,
units,
})
}
pub fn name(&self) -> &str {
&self.name
}
pub const fn flow_per_unit(&self) -> FlowRate {
self.flow_per_unit
}
pub const fn units(&self) -> u32 {
self.units
}
pub fn total_flow(&self) -> Result<FlowRate, SuidoError> {
let total = self.flow_per_unit.0 * f64::from(self.units);
ensure_finite(total)?;
Ok(FlowRate(total))
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct WaterSupplyPlan {
supply: FlowRate,
storage: Volume,
pipe_diameter: PipeDiameter,
demands: Vec<FixtureDemand>,
}
impl WaterSupplyPlan {
pub const fn new(supply: FlowRate, storage: Volume, pipe_diameter: PipeDiameter) -> Self {
Self {
supply,
storage,
pipe_diameter,
demands: Vec::new(),
}
}
pub fn add_demand(&mut self, demand: FixtureDemand) -> Result<(), SuidoError> {
let _ = demand.total_flow()?;
self.demands.push(demand);
Ok(())
}
pub fn demands(&self) -> &[FixtureDemand] {
&self.demands
}
pub fn evaluate(&self) -> Result<SupplyReport, SuidoError> {
let mut demand_lpm = 0.0;
for demand in &self.demands {
demand_lpm += demand.total_flow()?.as_liters_per_minute();
ensure_finite(demand_lpm)?;
}
let margin_lpm = self.supply.0 - demand_lpm;
ensure_finite(margin_lpm)?;
let state = if margin_lpm > 0.0 {
SupplyState::Surplus
} else if margin_lpm < 0.0 {
SupplyState::Deficit
} else {
SupplyState::Balanced
};
let storage_endurance_minutes = if state == SupplyState::Deficit {
let minutes = self.storage.0 / -margin_lpm;
ensure_finite(minutes)?;
Some(minutes)
} else {
None
};
Ok(SupplyReport {
state,
supply: self.supply,
demand: FlowRate(demand_lpm),
margin: FlowMargin(margin_lpm),
storage: self.storage,
storage_endurance_minutes,
pipe_velocity_mps: self.pipe_diameter.velocity_mps(self.supply)?,
})
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SupplyState {
Surplus,
Balanced,
Deficit,
}
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct SupplyReport {
state: SupplyState,
supply: FlowRate,
demand: FlowRate,
margin: FlowMargin,
storage: Volume,
storage_endurance_minutes: Option<f64>,
pipe_velocity_mps: f64,
}
impl SupplyReport {
pub const fn state(self) -> SupplyState {
self.state
}
pub const fn supply(self) -> FlowRate {
self.supply
}
pub const fn demand(self) -> FlowRate {
self.demand
}
pub const fn margin(self) -> FlowMargin {
self.margin
}
pub const fn storage(self) -> Volume {
self.storage
}
pub const fn storage_endurance_minutes(self) -> Option<f64> {
self.storage_endurance_minutes
}
pub const fn pipe_velocity_mps(self) -> f64 {
self.pipe_velocity_mps
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum SuidoError {
NonFinite(&'static str),
Negative(&'static str),
Zero(&'static str),
EmptyFixtureName,
ZeroFixtureUnits,
CalculationOverflow,
}
impl fmt::Display for SuidoError {
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::EmptyFixtureName => formatter.write_str("fixture name must not be blank"),
Self::ZeroFixtureUnits => {
formatter.write_str("fixture units must be greater than zero")
}
Self::CalculationOverflow => formatter.write_str("calculation exceeded finite range"),
}
}
}
impl Error for SuidoError {}
fn validate_non_negative_finite(value: f64, name: &'static str) -> Result<(), SuidoError> {
if !value.is_finite() {
return Err(SuidoError::NonFinite(name));
}
if value < 0.0 {
return Err(SuidoError::Negative(name));
}
Ok(())
}
fn validate_positive_finite(value: f64, name: &'static str) -> Result<(), SuidoError> {
validate_non_negative_finite(value, name)?;
if value == 0.0 {
return Err(SuidoError::Zero(name));
}
Ok(())
}
fn ensure_finite(value: f64) -> Result<(), SuidoError> {
if value.is_finite() {
Ok(())
} else {
Err(SuidoError::CalculationOverflow)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn flow(value: f64) -> FlowRate {
FlowRate::liters_per_minute(value).unwrap()
}
fn plan(supply: f64, storage: f64) -> WaterSupplyPlan {
WaterSupplyPlan::new(
flow(supply),
Volume::liters(storage).unwrap(),
PipeDiameter::millimeters(20.0).unwrap(),
)
}
#[test]
fn flow_over_time_produces_volume() {
let volume = flow(12.0)
.volume_over(Duration::minutes(2.5).unwrap())
.unwrap();
assert_eq!(volume.as_liters(), 30.0);
}
#[test]
fn pipe_velocity_uses_internal_diameter() {
let velocity = PipeDiameter::millimeters(20.0)
.unwrap()
.velocity_mps(flow(20.0))
.unwrap();
assert!((velocity - 1.061_032_953_945_969).abs() < 1e-12);
}
#[test]
fn fixture_units_are_included_in_demand() {
let mut plan = plan(20.0, 0.0);
plan.add_demand(FixtureDemand::new("tap", flow(4.0), 3).unwrap())
.unwrap();
let report = plan.evaluate().unwrap();
assert_eq!(report.demand().as_liters_per_minute(), 12.0);
assert_eq!(report.margin().as_liters_per_minute(), 8.0);
assert_eq!(report.state(), SupplyState::Surplus);
}
#[test]
fn storage_covers_only_a_deficit() {
let mut plan = plan(18.0, 120.0);
plan.add_demand(FixtureDemand::new("fixtures", flow(22.0), 1).unwrap())
.unwrap();
let report = plan.evaluate().unwrap();
assert_eq!(report.state(), SupplyState::Deficit);
assert_eq!(report.storage_endurance_minutes(), Some(30.0));
}
#[test]
fn exact_supply_is_balanced() {
let mut plan = plan(10.0, 50.0);
plan.add_demand(FixtureDemand::new("tap", flow(10.0), 1).unwrap())
.unwrap();
let report = plan.evaluate().unwrap();
assert_eq!(report.state(), SupplyState::Balanced);
assert_eq!(report.storage_endurance_minutes(), None);
}
#[test]
fn invalid_quantities_and_fixtures_are_rejected() {
assert_eq!(
FlowRate::liters_per_minute(f64::NAN),
Err(SuidoError::NonFinite("flow rate"))
);
assert_eq!(Volume::liters(-1.0), Err(SuidoError::Negative("volume")));
assert_eq!(
PipeDiameter::millimeters(0.0),
Err(SuidoError::Zero("pipe diameter"))
);
assert_eq!(
FixtureDemand::new(" ", flow(1.0), 1),
Err(SuidoError::EmptyFixtureName)
);
assert_eq!(
FixtureDemand::new("tap", flow(1.0), 0),
Err(SuidoError::ZeroFixtureUnits)
);
}
#[test]
fn calculation_overflow_is_reported() {
let demand = FixtureDemand::new("huge", flow(f64::MAX), 2).unwrap();
assert_eq!(demand.total_flow(), Err(SuidoError::CalculationOverflow));
}
}