payroll.tax-period Unreviewed

pub fn tax_period(pay_date: &str, frequency: &str) -> TaxPeriod

// PayFrequency is a string in Rust, one of: "weekly", "fortnightly", "four-weekly", "monthly".
// Parameters take it as &str and results hold it as String.

/// Where a pay date sits in the UK tax year.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TaxPeriod {
    /// HMRC's label, e.g. 2026/27
    pub tax_year: String,
    /// 6 April of that tax year
    pub tax_year_start: String,
    /// tax week 1-53: week 1 is 6-12 April
    pub week: i64,
    /// tax month 1-12: month 1 is 6 April to 5 May
    pub month: i64,
    /// the period PAYE and NICs are worked out for: the month when paid monthly, otherwise the tax week, with week 53 reported as 53, 54 or 56 for weekly, fortnightly or four-weekly pay
    pub period: i64,
}

fune!(payroll.tax-period@^1);  // then call tax_period(…)

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::dates_add_days::{days_between, parse_iso_date};  ← from dates.add-days ^1.0.0 · built alongside by fune
use super::dates_uk_tax_year::uk_tax_year;  ← from dates.uk-tax-year ^1.0.0 · built alongside by fune

/// The tax week, tax month and payroll period a pay date falls in.
///
/// The tax year is 365 or 366 days, which is 52 weeks and one or two days over.
/// Those spare days are week 53, and they are the reason `period` exists: HMRC
/// numbers the extra payday 53, 54 or 56 by frequency and taxes it
/// non-cumulatively, so a payroll that just counts weeks gets it wrong.
///
/// # Panics
/// Panics on a malformed date or an unknown frequency.
pub fn tax_period(pay_date: &str, frequency: &str) -> TaxPeriod {
    if !matches!(frequency, "weekly" | "fortnightly" | "four-weekly" | "monthly") {
        panic!("unknown pay frequency \"{}\"", frequency);
    }
    let year = uk_tax_year(pay_date);
    let week = days_between(&year.start, pay_date) / 7 + 1;

    // Tax months run from the 6th to the 5th, so the calendar month moves on
    // five days before the tax month does.
    let date = parse_iso_date(pay_date);
    let mut month = if date.day >= 6 { date.month - 3 } else { date.month - 4 };
    if month <= 0 {
        month += 12;
    }

    let period = if frequency == "monthly" {
        month
    } else if week < 53 {
        week
    } else {
        match frequency {
            "weekly" => 53,
            "fortnightly" => 54,
            _ => 56,
        }
    };

    TaxPeriod {
        tax_year: year.label,
        tax_year_start: year.start,
        week,
        month,
        period,
    }
}

pub fn tax_period_to_value(p: &TaxPeriod) -> Value {
    Value::obj(vec![
        ("taxYear", Value::str(&p.tax_year)),
        ("taxYearStart", Value::str(&p.tax_year_start)),
        ("week", Value::Int(p.week)),
        ("month", Value::Int(p.month)),
        ("period", Value::Int(p.period)),
    ])
}

pub fn fune_vector(args: &[Value]) -> Value {
    tax_period_to_value(&tax_period(args[0].as_str(), args[1].as_str()))
}

Install

fune build

With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and its 2 dependencies, 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 payroll.tax-period

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

The whole function, every language, is one file too: payroll.tax-period-1.0.1.fune, 14,493 bytes, sha256 aec12ac339e717be493bd6db1e7a8778fd8e04e4e8fe86674c1d4853d504fe83. It installs into a project of any language.

// fune: before payroll.tax-period

// fune: after payroll.tax-period

// fune: replace dates.add-days in payroll.tax-period
// fune: replace dates.uk-tax-year in payroll.tax-period

// fune: step payroll.tax-period after <n|label>

More from the author

This capability does not check that a payroll really is fortnightly or four-weekly (that the paydays are 14 or 28 days apart); it places one date.

Sources: HMRC, "Employer further guide to PAYE and NICs" (CWG2), sections on tax weeks and months and on week 53 payments, https://www.gov.uk/government/publications/cwg2-further-guide-to-paye-and-national-insurance-contributions; HMRC, "Specification for PAYE tax table routines" v24.0, paragraph 14 (payments in weeks 53, 54 or 56), https://www.gov.uk/government/publications/payroll-technical-specifications-income-tax.

## Before you rely on this

**Not professional advice.** This capability calculates payroll figures from published rules. It is a software component for developers, not tax or legal advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a payroll specialist review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified payroll specialist has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

## 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 marks it unreviewed and adds its attribution notices (NOTICE). The code and the tests are unchanged.

Files