use std::fmt;
use super::time::format_hms;
use super::Error;
use super::{Distance, RaceTime};
mod mldr_2025;
mod table;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum AgeGradeTable {
UsatfMldr2025,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum Gender {
Male,
Female,
}
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct AgeGradeResult {
pub percent: f64,
pub level: PerformanceLevel,
pub age_factor: f64,
pub open_equivalent_secs: f64,
pub age_standard_secs: f64,
pub table: AgeGradeTable,
pub equivalent_at_age_secs: Option<f64>,
pub equivalent_age: Option<u8>,
}
impl AgeGradeResult {
pub fn open_equivalent_hms(&self) -> String {
format_hms(self.open_equivalent_secs)
}
pub fn equivalent_at_age_hms(&self) -> Option<String> {
self.equivalent_at_age_secs.map(format_hms)
}
}
impl fmt::Display for AgeGradeResult {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
f,
"{:.1}% {} | open eq {}",
self.percent,
self.level.label(),
self.open_equivalent_hms()
)?;
if let (Some(age), Some(hms)) = (self.equivalent_age, self.equivalent_at_age_hms()) {
write!(f, " | as {age}yo {hms}")?;
}
Ok(())
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum PerformanceLevel {
WorldRecord,
WorldClass,
NationalClass,
RegionalClass,
LocalClass,
Recreational,
Developing,
}
impl PerformanceLevel {
pub fn from_percent(p: f64) -> Self {
if p >= 100.0 {
Self::WorldRecord
} else if p >= 90.0 {
Self::WorldClass
} else if p >= 80.0 {
Self::NationalClass
} else if p >= 70.0 {
Self::RegionalClass
} else if p >= 60.0 {
Self::LocalClass
} else if p >= 50.0 {
Self::Recreational
} else {
Self::Developing
}
}
pub fn label(self) -> &'static str {
match self {
Self::WorldRecord => "world-record level",
Self::WorldClass => "world class",
Self::NationalClass => "national class",
Self::RegionalClass => "regional class",
Self::LocalClass => "local class",
Self::Recreational => "recreational",
Self::Developing => "developing",
}
}
}
pub fn open_standard_secs(distance: Distance, gender: Gender) -> Result<f64, Error> {
open_standard_secs_with(distance, gender, AgeGradeTable::UsatfMldr2025)
}
pub fn open_standard_secs_with(
distance: Distance,
gender: Gender,
table: AgeGradeTable,
) -> Result<f64, Error> {
match table {
AgeGradeTable::UsatfMldr2025 => table::open_standard_mldr2025(distance, gender),
}
}
pub fn age_factor(age: u8, gender: Gender, distance: Distance) -> Result<f64, Error> {
age_factor_with(age, gender, distance, AgeGradeTable::UsatfMldr2025)
}
pub fn age_factor_with(
age: u8,
gender: Gender,
distance: Distance,
table: AgeGradeTable,
) -> Result<f64, Error> {
Ok(table::lookup(table, distance, age, gender)?.factor)
}
pub fn age_grade(
race: RaceTime,
age: u8,
gender: Gender,
equivalent_age: Option<u8>,
) -> Result<AgeGradeResult, Error> {
age_grade_with(
race,
age,
gender,
equivalent_age,
AgeGradeTable::UsatfMldr2025,
)
}
pub fn age_grade_with(
race: RaceTime,
age: u8,
gender: Gender,
equivalent_age: Option<u8>,
table: AgeGradeTable,
) -> Result<AgeGradeResult, Error> {
let looked = table::lookup(table, race.distance(), age, gender)?;
let factor = looked.factor;
let age_standard_secs = looked.age_standard_secs;
let percent = 100.0 * age_standard_secs / race.seconds();
let open_eq = race.seconds() * factor;
let eq = match equivalent_age {
Some(n) => {
let f_n = table::lookup(table, race.distance(), n, gender)?.factor;
Some(race.seconds() * factor / f_n)
}
None => None,
};
Ok(AgeGradeResult {
percent,
level: PerformanceLevel::from_percent(percent),
age_factor: factor,
open_equivalent_secs: open_eq,
age_standard_secs,
table,
equivalent_at_age_secs: eq,
equivalent_age,
})
}
pub fn age_equivalent(
race: RaceTime,
age: u8,
gender: Gender,
target_age: u8,
) -> Result<f64, Error> {
age_equivalent_with(race, age, gender, target_age, AgeGradeTable::UsatfMldr2025)
}
pub fn age_equivalent_with(
race: RaceTime,
age: u8,
gender: Gender,
target_age: u8,
table: AgeGradeTable,
) -> Result<f64, Error> {
let f = table::lookup(table, race.distance(), age, gender)?.factor;
let f_n = table::lookup(table, race.distance(), target_age, gender)?.factor;
Ok(race.seconds() * f / f_n)
}
#[cfg(test)]
mod tests {
use super::Error;
use super::*;
#[test]
fn open_headers_match_generated_table() {
assert_eq!(
open_standard_secs(Distance::FiveK, Gender::Male).unwrap(),
769.0
);
assert_eq!(
open_standard_secs(Distance::FiveK, Gender::Female).unwrap(),
834.0
);
assert_eq!(
open_standard_secs(Distance::Marathon, Gender::Male).unwrap(),
7235.0
);
}
#[test]
fn per_event_factors_differ() {
let five = age_factor(60, Gender::Male, Distance::FiveK).unwrap();
let mara = age_factor(60, Gender::Male, Distance::Marathon).unwrap();
assert!(
(five - mara).abs() > 1e-6,
"5K={five} marathon={mara} should differ"
);
}
#[test]
fn age_out_of_range() {
assert_eq!(
age_factor(4, Gender::Male, Distance::FiveK),
Err(Error::AgeOutOfRange { min: 5, max: 99 })
);
assert_eq!(
age_factor(100, Gender::Male, Distance::FiveK),
Err(Error::AgeOutOfRange { min: 5, max: 99 })
);
let race = RaceTime::from_hms(Distance::FiveK, 0, 20, 0).unwrap();
assert_eq!(
age_grade(race, 4, Gender::Male, None),
Err(Error::AgeOutOfRange { min: 5, max: 99 })
);
assert_eq!(
age_grade(race, 100, Gender::Male, None),
Err(Error::AgeOutOfRange { min: 5, max: 99 })
);
}
#[test]
fn three_k_unsupported() {
assert_eq!(
open_standard_secs(Distance::ThreeK, Gender::Male),
Err(Error::UnsupportedAgeGradeDistance)
);
assert_eq!(
age_factor(40, Gender::Male, Distance::ThreeK),
Err(Error::UnsupportedAgeGradeDistance)
);
}
#[test]
fn ages_5_and_99_in_range() {
assert!(age_factor(5, Gender::Male, Distance::FiveK).unwrap() > 0.0);
assert!(age_factor(99, Gender::Male, Distance::FiveK).unwrap() > 0.0);
}
#[test]
fn eight_k_standard_between_5k_and_10k() {
let age = 40_u8;
let s = |d: Distance| {
let open = open_standard_secs(d, Gender::Male).unwrap();
let f = age_factor(age, Gender::Male, d).unwrap();
open / f
};
let s5 = s(Distance::FiveK);
let s8 = s(Distance::custom(8_000.0, "8K").unwrap());
let s10 = s(Distance::TenK);
assert!(s8 > s5 && s8 < s10, "s5={s5} s8={s8} s10={s10}");
}
#[test]
fn custom_log_interpolation_between_neighbours() {
let age = 40_u8;
let seven = Distance::custom(7_000.0, "7K").unwrap();
let lookup7 =
table::lookup(AgeGradeTable::UsatfMldr2025, seven, age, Gender::Male).unwrap();
let low = Distance::custom(4.0 * super::super::units::METERS_PER_MILE, "4mi").unwrap();
let high = Distance::custom(8_000.0, "8K").unwrap();
let s_at = |d: Distance| {
let open = open_standard_secs(d, Gender::Male).unwrap();
open / age_factor(age, Gender::Male, d).unwrap()
};
let s_low = s_at(low);
let s_high = s_at(high);
assert!(lookup7.age_standard_secs > s_low);
assert!(lookup7.age_standard_secs < s_high);
let u_lin = (7_000.0 - low.meters()) / (high.meters() - low.meters());
let open_low = open_standard_secs(low, Gender::Male).unwrap();
let open_high = open_standard_secs(high, Gender::Male).unwrap();
let fake_open = open_low + u_lin * (open_high - open_low);
let shared_f = age_factor(age, Gender::Male, Distance::FiveK).unwrap();
let fake_std = fake_open / shared_f;
assert!(
(lookup7.age_standard_secs - fake_std).abs() > 0.05,
"expected Jones log-std interpolation to differ from linear-open/shared-factor"
);
}
#[test]
fn outside_official_span_errors() {
let short = Distance::custom(1_000.0, "1K").unwrap();
let long = Distance::custom(250_000.0, "250K").unwrap();
assert_eq!(
age_factor(40, Gender::Male, short),
Err(Error::UnsupportedAgeGradeDistance)
);
assert_eq!(
age_factor(40, Gender::Male, long),
Err(Error::UnsupportedAgeGradeDistance)
);
}
#[test]
fn grubb_oracle_cases() {
let cases = [
(Gender::Male, 42, Distance::FiveK, 0, 20, 0, 0.9335, 68.6485),
(
Gender::Female,
42,
Distance::FiveK,
0,
22,
0,
0.9346,
67.6031,
),
(Gender::Male, 28, Distance::FiveK, 0, 20, 0, 1.0000, 64.0833),
(
Gender::Male,
60,
Distance::Marathon,
3,
30,
0,
0.8143,
70.5153,
),
(
Gender::Female,
55,
Distance::HalfMarathon,
1,
45,
0,
0.8235,
72.7055,
),
];
for (gender, age, distance, h, m, s, want_f, want_pct) in cases {
let race = RaceTime::from_hms(distance, h, m, s).unwrap();
let ag = age_grade(race, age, gender, None).unwrap();
assert!(
(ag.age_factor - want_f).abs() < 5e-4,
"{gender:?} {age} {distance}: factor {} vs {want_f}",
ag.age_factor
);
assert!(
(ag.percent - want_pct).abs() < 0.1,
"{gender:?} {age} {distance}: percent {} vs {want_pct}",
ag.percent
);
assert_eq!(ag.table, AgeGradeTable::UsatfMldr2025);
assert!(ag.age_standard_secs > 0.0);
}
}
#[test]
fn equivalent_age_round_trip() {
let race = RaceTime::from_hms(Distance::FiveK, 0, 20, 0).unwrap();
let ag = age_grade(race, 42, Gender::Male, Some(25)).unwrap();
let as_25 = ag.equivalent_at_age_secs.unwrap();
let back = age_equivalent(
RaceTime::from_secs(Distance::FiveK, as_25).unwrap(),
25,
Gender::Male,
42,
)
.unwrap();
assert!((back - race.seconds()).abs() < 1e-6);
let direct = age_equivalent(race, 42, Gender::Male, 25).unwrap();
assert!((direct - as_25).abs() < 1e-9);
}
#[test]
fn prime_age_open_equivalent_is_the_race_time() {
let race = RaceTime::from_hms(Distance::TenK, 0, 40, 0).unwrap();
let ag = age_grade(race, 25, Gender::Female, None).unwrap();
assert!((ag.age_factor - 1.0).abs() < 1e-9);
assert!((ag.open_equivalent_secs - race.seconds()).abs() < 1e-9);
assert_eq!(ag.open_equivalent_hms(), "40:00");
}
#[test]
fn age_grade_display_includes_percent_and_open_eq() {
let race = RaceTime::from_hms(Distance::FiveK, 0, 20, 0).unwrap();
let s = age_grade(race, 42, Gender::Male, Some(25))
.unwrap()
.to_string();
assert!(s.contains('%'));
assert!(s.contains("open eq"));
assert!(s.contains("25yo"));
}
#[test]
fn performance_level_thresholds() {
assert_eq!(
PerformanceLevel::from_percent(100.0),
PerformanceLevel::WorldRecord
);
assert_eq!(
PerformanceLevel::from_percent(90.0),
PerformanceLevel::WorldClass
);
assert_eq!(
PerformanceLevel::from_percent(80.0),
PerformanceLevel::NationalClass
);
assert_eq!(
PerformanceLevel::from_percent(70.0),
PerformanceLevel::RegionalClass
);
assert_eq!(
PerformanceLevel::from_percent(60.0),
PerformanceLevel::LocalClass
);
assert_eq!(
PerformanceLevel::from_percent(50.0),
PerformanceLevel::Recreational
);
assert_eq!(
PerformanceLevel::from_percent(49.9),
PerformanceLevel::Developing
);
}
#[test]
fn open_standards_ordered_for_supported_named() {
for gender in [Gender::Male, Gender::Female] {
let mut prev = 0.0;
for d in [
Distance::FiveK,
Distance::TenK,
Distance::HalfMarathon,
Distance::Marathon,
] {
let s = open_standard_secs(d, gender).unwrap();
assert!(s > prev);
prev = s;
}
}
}
#[cfg(feature = "serde")]
#[test]
fn serde_age_grade_roundtrip() {
let race = RaceTime::from_hms(Distance::FiveK, 0, 20, 0).unwrap();
let ag = age_grade(race, 42, Gender::Male, Some(25)).unwrap();
let back: AgeGradeResult =
serde_json::from_str(&serde_json::to_string(&ag).unwrap()).unwrap();
assert!((back.percent - ag.percent).abs() < 1e-6);
assert_eq!(back.level, ag.level);
assert_eq!(back.table, AgeGradeTable::UsatfMldr2025);
}
}