fleet.emissions

pub fn fleet_emissions(activity: &str, quantity: &str, unit: &str, factor_year: i64) -> FleetEmissions

// EmissionsUnit is a string in Rust, one of: "litres", "km", "miles".
// Parameters take it as &str and results hold it as String.

/// The emissions and the factor that produced them, for the audit trail.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FleetEmissions {
    /// quantity times factor, rounded half up to the gram
    pub co2e_grams: i64,
    /// the factor as published, kg CO2e per unit, to 5 decimal places
    pub factor: String,
    pub factor_year: i64,
    pub activity: String,
    pub unit: String,
}

fune!(fleet.emissions@^1);  // then call fleet_emissions(…)

use super::funejson::Value;  ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
use super::fleet_emissions_data::GHG_FACTORS;  ← this capability’s own data, compiled from data/ghg-factors.json into the same file by fune build

const MAX_SAFE: i128 = 9007199254740991;

fn format_factor(factor: i64) -> String {
    format!("{}.{:05}", factor / 100000, factor % 100000)
}

/// Split plain decimal text into its whole and fractional digits, or None.
fn split_decimal(text: &str) -> Option<(&str, &str)> {
    let (whole, fraction) = match text.find('.') {
        Some(i) => (&text[..i], &text[i + 1..]),
        None => (text, ""),
    };
    let digits = |s: &str| s.bytes().all(|b| b.is_ascii_digit());
    if whole.is_empty() || !digits(whole) || !digits(fraction) || (text.contains('.') && fraction.is_empty()) {
        return None;
    }
    Some((whole, fraction))
}

/// Scope 1 emissions for fuel burned or distance driven, from the UK
/// government's conversion factors for company reporting.
///
/// The quantity is decimal text and the factor an integer in 1e-5 kg, so the
/// product is exact and rounded once, to the gram. Multiplying floats instead
/// drifts in the last place and can round a half-gram the wrong way.
///
/// # Panics
/// Panics on an unknown unit, year or activity, a unit the activity has no
/// factor for, a malformed or negative quantity, or a result beyond 2^53 - 1.
pub fn fleet_emissions(activity: &str, quantity: &str, unit: &str, factor_year: i64) -> FleetEmissions {
    if unit != "litres" && unit != "km" && unit != "miles" {
        panic!("unknown unit \"{}\": use litres, km or miles", unit);
    }
    let (whole, fraction) = match split_decimal(quantity) {
        Some(parts) => parts,
        None => panic!(
            "quantity must be plain decimal text, not negative, received \"{}\"",
            quantity
        ),
    };
    let all_digits = format!("{}{}", whole, fraction);
    let significant = all_digits.trim_start_matches('0');
    if significant.len() > 15 || fraction.len() > 9 {
        panic!(
            "quantity must have at most 15 significant digits and 9 decimal places, received \"{}\"",
            quantity
        );
    }

    let mut found: Option<i64> = None;
    let mut year_known = false;
    let mut activity_known = false;
    for row in GHG_FACTORS {
        if row.factor_year != factor_year {
            continue;
        }
        year_known = true;
        if row.activity != activity {
            continue;
        }
        activity_known = true;
        if row.unit == unit {
            found = Some(row.factor);
        }
    }
    if !year_known {
        panic!("no conversion factors for {}: this package carries 2023 to 2026", factor_year);
    }
    if !activity_known {
        panic!("unknown activity \"{}\" in the {} factors", activity, factor_year);
    }
    let factor = match found {
        Some(f) => f,
        None => panic!("no conversion factor for {} per {} in {}", activity, unit, factor_year),
    };

    // grams = quantity x factor x 1e-5 kg x 1000 g/kg = quantity x factor / 100.
    // At most 15 digits times a factor below 1e7 fits i128 with room to spare.
    let value: i128 = if significant.is_empty() { 0 } else { significant.parse().unwrap() };
    let numerator = value * factor as i128;
    let denominator = 10i128.pow(fraction.len() as u32) * 100;
    let grams = (2 * numerator + denominator) / (2 * denominator);
    if grams > MAX_SAFE {
        panic!("the result exceeds 2^53 - 1 grams");
    }
    FleetEmissions {
        co2e_grams: grams as i64,
        factor: format_factor(factor),
        factor_year,
        activity: activity.to_string(),
        unit: unit.to_string(),
    }
}

pub fn fleet_emissions_to_value(e: &FleetEmissions) -> Value {
    Value::obj(vec![
        ("co2eGrams", Value::Int(e.co2e_grams)),
        ("factor", Value::str(&e.factor)),
        ("factorYear", Value::Int(e.factor_year)),
        ("activity", Value::str(&e.activity)),
        ("unit", Value::str(&e.unit)),
    ])
}

pub fn fune_vector(args: &[Value]) -> Value {
    let quantity = match &args[1] {
        Value::Str(s) => s.as_str(),
        other => panic!(
            "quantity must be plain decimal text, not negative, received {:?}",
            other
        ),
    };
    let year = match &args[3] {
        Value::Int(i) => *i,
        other => panic!("factorYear must be a whole year, received {:?}", other),
    };
    fleet_emissions_to_value(&fleet_emissions(args[0].as_str(), quantity, args[2].as_str(), year))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Rust package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. A crate’s build.rs runs it before every compile. Or pin a range in fune.project and build in one step:

fune add fleet.emissions

The manifest, vectors and README with only the Rust implementation. Install it without the registry with fune add ./fleet.emissions-1.0.1-rust.fune, or fetch it from a terminal with fune pull fleet.emissions@1.0.1:rust.

The whole function, every language, is one file too: fleet.emissions-1.0.1.fune, 142,757 bytes, sha256 889b6473407bbb10b8b415ea8a5d9fa9ddc9d09a15beacbd289c885db32cce5c. It installs into a project of any language.

// fune: before fleet.emissions

// fune: after fleet.emissions

// fune: step fleet.emissions after <n|label>

More from the author

Fuel is the better measure when you have it (fuel cards, bunkered fuel): it already reflects how the vehicles were driven. Distance by vehicle class is the fallback. The factors are the **Scope 1** figures, direct tailpipe emissions in kg CO2e (CO2, CH4 and N2O together):

- fuels, per litre: `fuel-diesel` and `fuel-petrol` (UK forecourt fuel with its average biofuel blend), `fuel-diesel-mineral` and `fuel-petrol-mineral` (100% mineral), `fuel-lpg`; - cars by size, per km or mile: `car-{small|medium|large|average}-{diesel|petrol|hybrid|phev|cng|lpg|unknown}` where DESNZ publishes one (there is no small CNG or LPG car); - `motorbike-{small|medium|large|average}`; - vans: `van-{class-1|class-2|class-3|average}-{diesel|petrol}`, and `van-average-{cng|lpg|unknown|phev}` and `van-class-3-phev` (the van PHEV factors appear from 2024); - HGVs (all diesel): `hgv-{rigid-3.5-7.5t|rigid-7.5-17t|rigid-over-17t|all-rigids|artic-3.5-33t|artic-over-33t|all-artics|all-hgvs}-laden-{0|50|100|average}`.

Battery electric vehicles are deliberately absent: their Scope 1 factor is zero, and their emissions belong to the electricity used (Scope 2, DESNZ's "UK electricity for EVs" table), which this package does not carry. A plug-in hybrid's factor likewise covers only the fuel it burns.

Per-mile factors are DESNZ's own, not the per-km factor times 1.609344, so a report matches the published spreadsheet exactly.

## Which year

`factorYear` picks the DESNZ set: 2023, 2024, 2025 or 2026. DESNZ publishes each set in June for reporting periods in that year; use the set for the year you are reporting, and keep it for restatements. The sets are publications, not rules that expire, so the table has no effective columns and ships whole.

In the 2026 set DESNZ split HGVs into refrigerated and non-refrigerated and renamed the averages; the `hgv-*` codes read the non-refrigerated rows for 2026 (earlier years' "HGV (all diesel)" table is the non-refrigerated fleet, refrigerated HGVs having had their own table), so the codes mean the same vehicle in every year.

## Exactness

Each factor is stored as an integer in units of 0.00001 kg (10 mg): DESNZ publishes five decimal places. The 2023 flat file holds the unrounded values behind them (2.5120638845637586 for diesel); they are rounded half up to the five places shown in the published tables (2.51206). The quantity is decimal text, so quantity times factor is exact, and the only rounding is the final one, half up to a whole gram. Quantities are limited to 15 significant digits and 9 decimal places, and a result above 2^53 - 1 grams is an error, so all three languages agree.

## Relationship to energy.*

This package is self-contained. If an `energy.carbon-emissions` capability with the same DESNZ tables appears in the registry, a later version of this one should read its data instead of carrying a second copy.

## Sources

- DESNZ, "Greenhouse gas reporting: conversion factors 2023", flat file (ghg-conversion-factors-2023-flat-file-update.xlsx): https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2023 - DESNZ, "Greenhouse gas reporting: conversion factors 2024", flat file v1.1 (ghg-conversion-factors-2024-FlatFormat_v1_1.xlsx): https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2024 - DESNZ, "Greenhouse gas reporting: conversion factors 2025", flat file (ghg-conversion-factors-2025-flat-format.xlsx): https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2025 - DESNZ, "Greenhouse gas reporting: conversion factors 2026", flat file, revised July 2026 (ghg-conversion-factors-2026-flat-format-revised.xlsx): https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2026

Every row of `data/ghg-factors.json` names the spreadsheet path it came from (Level 1 / Level 2 / Level 3 / column), always the "kg CO2e" row of Scope 1.

## Notices

Contains public sector information licensed under the Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).

1.0.1 adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files