# Crate Documentation

**Version:** 0.3.0

**Format Version:** 43

# Module `nhs_number`

# NHS Number

A National Health Service (NHS) Number is a unique number allocated in a shared
numbering scheme to registered users of the three public health services in
England, Wales, 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) organizations.

References:

* [National Health Service (NHS)](https://en.wikipedia.org/wiki/National_Health_Service)

* [NHS Number](https://en.wikipedia.org/wiki/NHS_number)

## 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, Wales, Isle of Man)

* 600 000 000 to 799 999 999 (England, Wales, 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.

## Examples

```rust
use nhs_number::*;
use std::str::FromStr;
 
// NHS Number that we can use for testing purposes
let str = "999 123 4560";
 
// Create a new NHS Number by converting from a string.
let nhs_number = NHSNumber::from_str(str).unwrap();

// Validate a NHS Number using the check digit algorithm.
let valid: bool = nhs_number.validate_check_digit();
```


## Modules

## Module `from_str`

```rust
pub mod from_str { /* ... */ }
```

## Module `parse_error`

```rust
pub mod parse_error { /* ... */ }
```

### Types

#### Struct `ParseError`

NHS Number Parse Error, which is for the implementation `FromStr`.

```rust
pub struct ParseError;
```

##### Implementations

###### Trait Implementations

- **TryFrom**
  - ```rust
    fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> { /* ... */ }
    ```

- **VZip**
  - ```rust
    fn vzip(self: Self) -> V { /* ... */ }
    ```

- **Debug**
  - ```rust
    fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<''_>) -> $crate::fmt::Result { /* ... */ }
    ```

- **Send**
- **Freeze**
- **Unpin**
- **Into**
  - ```rust
    fn into(self: Self) -> U { /* ... */ }
    ```
    Calls `U::from(self)`.

- **StructuralPartialEq**
- **BorrowMut**
  - ```rust
    fn borrow_mut(self: &mut Self) -> &mut T { /* ... */ }
    ```

- **Borrow**
  - ```rust
    fn borrow(self: &Self) -> &T { /* ... */ }
    ```

- **From**
  - ```rust
    fn from(t: T) -> T { /* ... */ }
    ```
    Returns the argument unchanged.

- **PartialEq**
  - ```rust
    fn eq(self: &Self, other: &ParseError) -> bool { /* ... */ }
    ```

- **Sync**
- **RefUnwindSafe**
- **Eq**
- **Any**
  - ```rust
    fn type_id(self: &Self) -> TypeId { /* ... */ }
    ```

- **UnwindSafe**
- **TryInto**
  - ```rust
    fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error> { /* ... */ }
    ```

## Module `testable`

```rust
pub mod testable { /* ... */ }
```

### Functions

#### Function `testable_random_sample`

**Attributes:**

- `#[allow(dead_code)]`

Generate a NHS Number testable range random sample.
The generated number is valid but is never going to be issued.

Example:

```rust
use nhs_number::{NHSNumber, testable::*};
let nhs_number = testable_random_sample();
assert!(nhs_number >= *TESTABLE_MIN);
assert!(nhs_number <= *TESTABLE_MAX);
```


```rust
pub fn testable_random_sample() -> crate::NHSNumber { /* ... */ }
```

### Constants and Statics

#### Static `TESTABLE_MIN`

**Attributes:**

- `#[allow(dead_code)]`

Get the NHS Number testable range minimum value.
This number is valid but is never going to be issued.

Example:

```rust
use nhs_number::NHSNumber;
use nhs_number::testable::TESTABLE_MIN;
let nhs_number = NHSNumber { digits: [9, 9, 9, 0, 1, 2, 3, 4, 5, 6] };
assert!(nhs_number >= *TESTABLE_MIN);
```


```rust
pub static TESTABLE_MIN: std::sync::LazyLock<crate::NHSNumber> = _;
```

#### Static `TESTABLE_MAX`

**Attributes:**

- `#[allow(dead_code)]`

Get the NHS Number testable range maximum value.
This number is valid but is never going to be issued.

Example:

```rust
use nhs_number::NHSNumber;
use nhs_number::testable::TESTABLE_MAX;
let nhs_number = NHSNumber { digits: [9, 9, 9, 0, 1, 2, 3, 4, 5, 6] };
assert!(nhs_number <= *TESTABLE_MAX);
```


```rust
pub static TESTABLE_MAX: std::sync::LazyLock<crate::NHSNumber> = _;
```

#### Static `TESTABLE_RANGE_INCLUSIVE`

**Attributes:**

- `#[allow(dead_code)]`

Get the NHS Number testable range.
This range is valid but is never going to be issued.

Example:
```rust
 use nhs_number::{NHSNumber, testable::*};
let nhs_number = NHSNumber { digits: [9, 9, 9, 0, 1, 2, 3, 4, 5, 6] };
 assert!(TESTABLE_RANGE_INCLUSIVE.contains(&nhs_number));
```

```rust
pub static TESTABLE_RANGE_INCLUSIVE: std::sync::LazyLock<std::ops::RangeInclusive<crate::NHSNumber>> = _;
```

## Types

### Struct `NHSNumber`

NHS Number is a unique identifier for patients in the National Health
Service of England, Wales, and the Isle of Man.

Reference:

* [National Health Service (NHS)](https://en.wikipedia.org/wiki/National_Health_Service)

* [NHS Number](https://en.wikipedia.org/wiki/NHS_number)

```rust
use nhs_number::NHSNumber;
let digits = [9, 9, 9, 1, 2, 3, 4, 5, 6, 0];
let nhs_number = NHSNumber { digits: digits };
```


```rust
pub struct NHSNumber {
    pub digits: [i8; 10],
}
```

#### Fields

| Name | Type | Documentation |
|------|------|---------------|
| `digits` | `[i8; 10]` |  |

#### Implementations

##### Methods

- ```rust
  pub fn new(digits: [i8; 10]) -> Self { /* ... */ }
  ```
  Create a new NHS Number instance with the provided digits.

- ```rust
  pub fn check_digit(self: &Self) -> i8 { /* ... */ }
  ```
  Get the NHS Number check digit i.e. the last digit.

- ```rust
  pub fn calculate_check_digit(self: &Self) -> i8 { /* ... */ }
  ```
  Calculate the NHS Number check digit using a checksum algorithm.

- ```rust
  pub fn validate_check_digit(self: &Self) -> bool { /* ... */ }
  ```
  Validate the NHS Number check digit equals the calculated check digit.

- ```rust
  pub fn testable_random_sample() -> NHSNumber { /* ... */ }
  ```
  Generate a testable random sample NHS Number.

##### Trait Implementations

- **TryFrom**
  - ```rust
    fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> { /* ... */ }
    ```

- **Any**
  - ```rust
    fn type_id(self: &Self) -> TypeId { /* ... */ }
    ```

- **ToOwned**
  - ```rust
    fn to_owned(self: &Self) -> T { /* ... */ }
    ```

  - ```rust
    fn clone_into(self: &Self, target: &mut T) { /* ... */ }
    ```

- **Borrow**
  - ```rust
    fn borrow(self: &Self) -> &T { /* ... */ }
    ```

- **Sync**
- **CloneToUninit**
  - ```rust
    unsafe fn clone_to_uninit(self: &Self, dest: *mut u8) { /* ... */ }
    ```

- **From**
  - ```rust
    fn from(t: T) -> T { /* ... */ }
    ```
    Returns the argument unchanged.

- **Deserialize**
  - ```rust
    fn deserialize<__D>(__deserializer: __D) -> _serde::__private::Result<Self, <__D as >::Error>
where
    __D: _serde::Deserializer<''de> { /* ... */ }
    ```

- **Unpin**
- **Display**
  - ```rust
    fn fmt(self: &Self, f: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
    ```

- **Send**
- **TryInto**
  - ```rust
    fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error> { /* ... */ }
    ```

- **FromStr**
  - ```rust
    fn from_str(s: &str) -> Result<Self, <Self as >::Err> { /* ... */ }
    ```

- **Serialize**
  - ```rust
    fn serialize<__S>(self: &Self, __serializer: __S) -> _serde::__private::Result<<__S as >::Ok, <__S as >::Error>
where
    __S: _serde::Serializer { /* ... */ }
    ```

- **Ord**
  - ```rust
    fn cmp(self: &Self, other: &NHSNumber) -> $crate::cmp::Ordering { /* ... */ }
    ```

- **Copy**
- **BorrowMut**
  - ```rust
    fn borrow_mut(self: &mut Self) -> &mut T { /* ... */ }
    ```

- **DeserializeOwned**
- **StructuralPartialEq**
- **PartialOrd**
  - ```rust
    fn partial_cmp(self: &Self, other: &NHSNumber) -> $crate::option::Option<$crate::cmp::Ordering> { /* ... */ }
    ```

- **Eq**
- **Into**
  - ```rust
    fn into(self: Self) -> U { /* ... */ }
    ```
    Calls `U::from(self)`.

  - ```rust
    fn into(self: Self) -> String { /* ... */ }
    ```

- **PartialEq**
  - ```rust
    fn eq(self: &Self, other: &NHSNumber) -> bool { /* ... */ }
    ```

- **Clone**
  - ```rust
    fn clone(self: &Self) -> NHSNumber { /* ... */ }
    ```

- **UnwindSafe**
- **VZip**
  - ```rust
    fn vzip(self: Self) -> V { /* ... */ }
    ```

- **RefUnwindSafe**
- **Debug**
  - ```rust
    fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<''_>) -> $crate::fmt::Result { /* ... */ }
    ```

- **ToString**
  - ```rust
    fn to_string(self: &Self) -> String { /* ... */ }
    ```

- **Freeze**
## Functions

### Function `format`

**Attributes:**

- `#[allow(dead_code)]`

Format the NHS Number as a 10-digit number with spaces.

Example:

```rust
let digits = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
let nhs_number_string = ::nhs_number::format(digits);
assert_eq!(nhs_number_string, "012 345 6789");
```

The NHS Number is formatted as a 10-digit number with spaces:

* 3 digits
* space
* 3 digits
* space
* 4 digits

This function output must be identical to the method
[`NHSNumber::to_string`](NHSNumber::to_string).


```rust
pub fn format(digits: [i8; 10]) -> String { /* ... */ }
```

### Function `check_digit`

**Attributes:**

- `#[allow(dead_code)]`

Get the NHS Number check digit i.e. the last digit.

Example:

```rust
let digits = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
let check_digit = ::nhs_number::check_digit(digits);
assert_eq!(check_digit, 9);
```

This function is called by the method [`NHSNumber::check_digit`](NHSNumber::check_digit).


```rust
pub fn check_digit(digits: [i8; 10]) -> i8 { /* ... */ }
```

### Function `calculate_check_digit`

**Attributes:**

- `#[allow(dead_code)]`

Calculate the NHS Number check digit using a checksum algorithm.

Example:

```rust
let digits = [9, 9, 9, 1, 2, 3, 4, 5, 6, 0];
let check_digit = ::nhs_number::calculate_check_digit(digits);
assert_eq!(check_digit, 0);
```

This function is called by the method [`NHSNumber::calculate_check_digit`](NHSNumber::calculate_check_digit).


```rust
pub fn calculate_check_digit(digits: [i8; 10]) -> i8 { /* ... */ }
```

## Re-exports

### Re-export `testable::*`

```rust
pub use testable::*;
```