energy.gas-kwh

cubic metres = units              (metric meter)
             = units x 2.83       (imperial meter, reading in hundreds of cubic feet)
kWh          = cubic metres x 1.02264 x calorific value (MJ/m³) / 3.6

pub fn gas_kwh(volume: i64, volume_unit: &str, calorific_value: i64) -> GasEnergy

// GasVolumeUnit is a string in Rust, one of: "cubic-metres", "hundreds-cubic-feet".
// Parameters take it as &str and results hold it as String.

/// The gas used, as a volume and as the energy it is billed on.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct GasEnergy {
    /// volume in hundredths of a cubic metre: 100 hundreds of cubic feet is 28300
    pub cubic_metres_hundredths: i64,
    /// energy in thousandths of a kWh, rounded half-up
    pub watt_hours: i64,
}

fune!(energy.gas-kwh@^1);  // then call gas_kwh(…)

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::math_round_div::round_div;  ← from math.round-div ^1.0.0 · built alongside by fune

// 1.02264 / 3.6 in lowest terms, with the scales of the arguments folded in:
// watt-hours = hundredths of m³ x 4261 x CV (thousandths of MJ/m³) / 1,500,000.
const FACTOR: i64 = 4261;
const DIVISOR: i64 = 1_500_000;
const MAX_VOLUME: i64 = 1_000_000_000_000;
const MAX_SAFE: i128 = 9_007_199_254_740_991;

/// Gas meter units to kWh, the way a GB bill does it: volume (x 2.83 for an
/// imperial meter) x 1.02264 x calorific value / 3.6, rounded once, half-up,
/// to the watt-hour.
///
/// # Panics
/// Panics on a volume or calorific value out of range, an unknown unit, or a
/// result too large to be exact in every language.
pub fn gas_kwh(volume: i64, volume_unit: &str, calorific_value: i64) -> GasEnergy {
    if volume < 0 || volume > MAX_VOLUME {
        panic!("volume must be a whole number of units from 0 to {}, received {}", MAX_VOLUME, volume);
    }
    if !(1..=100000).contains(&calorific_value) {
        panic!(
            "calorific value must be a whole number of thousandths of a MJ/m³ from 1 to 100000, received {}",
            calorific_value
        );
    }
    let hundredths = match volume_unit {
        "cubic-metres" => volume * 100,
        "hundreds-cubic-feet" => volume * 283,
        other => panic!("unknown volume unit \"{}\": expected cubic-metres or hundreds-cubic-feet", other),
    };
    let scaled = FACTOR * calorific_value;
    let whole = hundredths / DIVISOR;
    let rest = hundredths % DIVISOR;
    let watt_hours = whole as i128 * scaled as i128 + round_div(rest * scaled, DIVISOR, "half-up") as i128;
    if watt_hours > MAX_SAFE {
        panic!("gas energy too large to calculate exactly");
    }
    GasEnergy {
        cubic_metres_hundredths: hundredths,
        watt_hours: watt_hours as i64,
    }
}

pub fn gas_energy_to_value(e: &GasEnergy) -> Value {
    Value::obj(vec![
        ("cubicMetresHundredths", Value::Int(e.cubic_metres_hundredths)),
        ("wattHours", Value::Int(e.watt_hours)),
    ])
}

pub fn fune_vector(args: &[Value]) -> Value {
    if let Value::Float(f) = &args[0] {
        panic!("volume must be a whole number of units, received {}", f);
    }
    if let Value::Float(f) = &args[2] {
        panic!("calorific value must be a whole number of thousandths of a MJ/m³, received {}", f);
    }
    gas_energy_to_value(&gas_kwh(args[0].as_i64(), args[1].as_str(), args[2].as_i64()))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and its 1 dependency, 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 energy.gas-kwh

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

The whole function, every language, is one file too: energy.gas-kwh-1.0.0.fune, 14,672 bytes, sha256 e3046be9b02977427aee15807504a946cb0aaefd4e8d24bf6126de1e89db8f57. It installs into a project of any language.

// fune: before energy.gas-kwh

// fune: after energy.gas-kwh

// fune: replace math.round-div in energy.gas-kwh

// fune: step energy.gas-kwh after <n|label>

More from the author

1.02264 is the volume correction factor prescribed by the Gas (Calculation of Thermal Energy) Regulations 1996 for a meter that is not temperature and pressure corrected: it brings the metered volume to the standard conditions of 15 °C and 1013.25 mbar. 3.6 converts megajoules to kilowatt-hours. The calorific value is the average for the gas delivered to the property over the billing period, and is printed on the bill.

## Exactness and rounding

Everything is done in integers. The whole formula reduces to

watt-hours = hundredths of m³ x 4261 x CV in thousandths of MJ/m³ / 1,500,000

(102264 / 36,000,000 = 4261 / 1,500,000), computed exactly and rounded **once, half-up, to the nearest watt-hour** (a thousandth of a kWh). A float version of the same formula drifts in the last place and, for a large site, overflows the exact range of a JavaScript number before it divides; here the volume is split by the divisor first so every intermediate stays exact.

Suppliers round the kWh they print on a bill in different ways (whole kWh, two decimal places). Round the watt-hours to the precision your bill shows; the capability keeps three places so nothing is lost before that.

## Decisions

- **The constants are not dated data.** 1.02264, 3.6 and the 2.83 factor for hundreds of cubic feet have been fixed since the Regulations were made and are not rates that change by date. The calorific value, which does change daily, is an argument. - **2.83, not 2.8317.** 100 ft³ is 2.8316846592 m³ exactly, but the conversion prescribed for billing, and used on every GB bill, is 2.83. Using the exact factor would disagree with the supplier by about 0.06%. - **Whole units.** The volume is the difference between two reads of the black digits; the red digits are ignored when reading. Use `energy.meter-advance` to get it from two reads across a rollover. - **Bounds.** The volume is 0 to 10^12 units and the calorific value 1 to 100000 (100 MJ/m³; natural gas is kept between 38 and 41). A result that would not be an exact integer in JavaScript is refused rather than rounded.

## Sources

- Office for Product Safety and Standards, "Gas meter readings and bill calculation", https://www.gov.uk/guidance/gas-meter-readings-and-bill-calculation (the 2.83 conversion, the calorific value, the 1.02264 factor and the division by 3.6, all "as prescribed in the Gas (Calculation of Thermal Energy) Regulations 1996"). - The Gas (Calculation of Thermal Energy) Regulations 1996, SI 1996/439, https://www.legislation.gov.uk/uksi/1996/439

Files