Skip to main content

Crate nhs_number

Crate nhs_number 

Source
Expand description

§NHS Number

documentation • source • llms.txt • crate • email

A National Health Service (NHS) Number is a unique number allocated in a shared numbering scheme to registered users of the public health services in England and the Isle of Man.

The NHS Number is the key to the identification of patients, especially in delivering safe care across provider organisations, and is required in all new software deployed within the National Health Service (NHS) organisations.

References:

§Syntax

The current system uses a ten-digit number in ‘3 3 4’ format with the final digit being an error-detecting checksum. Examples given include 987 654 4321.

§Ranges

Currently issued numbers are in these ranges:

  • 300 000 000 to 399 999 999 (England)

  • 400 000 000 to 499 999 999 (England, Isle of Man)

  • 600 000 000 to 799 999 999 (England, Isle of Man)

Unavailable number ranges include:

  • 320 000 001 to 399 999 999 (allocated to the Northern Irish system)

  • 010 100 0000 to 311 299 9999 (used for CHI numbers in Scotland)

For test purposes, this range is valid but is guaranteed to never be issued:

  • 999 000 0000 to 999 999 9999

§Checksum

The checksum is calculated by multiplying each of the first nine digits by 11 minus its position. Using the number 943 476 5919 as an example:

  • The first digit is 9. This is multiplied by 10.

  • The second digit is 4. This is multiplied by 9.

  • And so on until the ninth digit (1) is multiplied by 2.

  • The result of this calculation is summed. In this example: (9×10) + (4×9) + (3×8) + (4×7) + (7×6) + (6×5) + (5×4) + (9×3) + (1×2) = 299.

  • The remainder when dividing this number by 11 is calculated, yielding a number in the range 0–10, which would be 2 in this case.

  • Finally, this number is subtracted from 11 to give the checksum in the range 1–11, in this case 9, which becomes the last digit of the NHS Number.

  • A checksum of 11 is represented by 0 in the final NHS Number. If the checksum is 10 then the number is not valid.

§Quick start

Parse, validate, and re-render an NHS Number:

use nhs_number::NHSNumber;
use std::str::FromStr;

// A test-safe number drawn from the reserved testable range.
let input = "999 100 0003";

let n = NHSNumber::from_str(input).unwrap();
assert!(n.validate_check_digit());
assert_eq!(n.to_string(), input);

Compute a check digit from raw digits:

// The Wikipedia worked example: digits 9 4 3 4 7 6 5 9 1 → check digit 9.
let digits = [9, 4, 3, 4, 7, 6, 5, 9, 1, 9];
assert_eq!(nhs_number::calculate_check_digit(digits), 9);
assert!(nhs_number::validate_check_digit(digits));

Generate a sample for tests:

use nhs_number::{NHSNumber, testable::TESTABLE_RANGE_INCLUSIVE};

let sample = NHSNumber::testable_random_sample();
assert!(TESTABLE_RANGE_INCLUSIVE.contains(&sample));

§Public surface (at a glance)

§Specification

The canonical behavioural specification for this crate lives in spec.md at the repo root. When the spec and the code disagree, the spec is the source of truth; see AGENTS/spec-driven-development.md for how to evolve both.

Re-exports§

pub use testable::*;

Modules§

from_str
FromStr parser for NHSNumber.
parse_error
The error type returned by NHSNumber::from_str.
testable
The reserved testable NHS Number range and a random sampler.

Structs§

NHSNumber
A ten-digit NHS Number — the unique identifier allocated to patients of the National Health Service of England and the Isle of Man.

Functions§

calculate_check_digit
Compute the check digit for a ten-digit array using the NHS modulo-11 algorithm (see spec.md §6).
check_digit
Return the stored tenth digit of a ten-digit array — the check digit as it appears in the input.
format
Format a ten-digit array as the canonical "DDD DDD DDDD" string.
validate_check_digit
Return true iff the stored tenth digit equals the one calculate_check_digit would compute from the first nine.