banking.cheque-amount-words

export function chequeAmountWords(amount: Money, penceStyle: ChequePenceStyle): ChequeWording

export type ChequePenceStyle = "words" | "figures";

/** What goes on the two amount lines of a cheque. */
export interface ChequeWording {
  /** capitalised, ending "only" */
  readonly words: string;
  /** e.g. "£1,234.56" */
  readonly figures: string;
}

import { chequeAmountWords } from "#fune/banking.cheque-amount-words@^1";

import { type Money, money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { formatMoney } from "./money_format.ts";  ← from money.format ^1.0.0 · built alongside by fune
import { amountInWords } from "./text_number_to_words.ts";  ← from text.number-to-words ^1.0.0 · built alongside by fune
import { type ChequePenceStyle, type ChequeWording } from "./banking_cheque_amount_words_types.ts";

/** The abbreviation written after pence as figures: 50p, 50c. */
const MINOR_SUFFIX: { [code: string]: string } = { GBP: "p", EUR: "c", USD: "c" };

/**
 * The amount lines of a cheque. The words come from text.number-to-words,
 * capitalised and closed with "only" so nothing can be added after them; the
 * figures come from money.format.
 */
export function chequeAmountWords(amount: Money, penceStyle: ChequePenceStyle): ChequeWording {
  if (amount.minor <= 0) {
    throw new RangeError(`a cheque amount must be greater than zero, received ${amount.minor}`);
  }
  let body: string;
  if (penceStyle === "words") {
    body = amountInWords(amount);
  } else if (penceStyle === "figures") {
    // The pounds are always in words, even when there are none, so the line
    // never starts with a figure that could be altered.
    const major = Math.floor(amount.minor / 100);
    const minor = amount.minor % 100;
    body = amountInWords(money(major * 100, amount.currency));
    if (minor > 0) {
      body += ` and ${minor}${MINOR_SUFFIX[amount.currency]}`;
    }
  } else {
    throw new RangeError(`unknown pence style "${penceStyle}": expected words or figures`);
  }
  const words = `${body.charAt(0).toUpperCase()}${body.slice(1)} only`;
  return { words, figures: formatMoney(amount) };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the TypeScript 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. Or pin a range in fune.project and build in one step:

fune add banking.cheque-amount-words

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./banking.cheque-amount-words-1.0.0-typescript.fune, or fetch it from a terminal with fune pull banking.cheque-amount-words@1.0.0:typescript.

The whole function, every language, is one file too: banking.cheque-amount-words-1.0.0.fune, 14,328 bytes, sha256 80d0e873ffe7b7ee2442c5a529db085afa8ab56d9a5f17e5a870ca935d0a7a10. It installs into a project of any language.

// fune: before banking.cheque-amount-words

// fune: after banking.cheque-amount-words

// fune: replace money.amount in banking.cheque-amount-words
// fune: replace money.format in banking.cheque-amount-words
// fune: replace text.number-to-words in banking.cheque-amount-words

// fune: step banking.cheque-amount-words after <n|label>

More from the author

## Conventions

- The words line starts with a capital and ends with "only", the traditional guard against words being added after the amount. - `penceStyle` `words` spells the pence out; `figures` writes them as a number with "p" (GBP) or "c" (EUR, USD): "One hundred and twenty pounds and 50p only". Many UK cheque writers and banks' own guidance use the figures style; both are valid. Single pence are not padded: "and 5p". - Whole amounts leave the pence out in both styles: "Ten pounds only". - In the figures style the pounds are always in words, even when there are none ("Zero pounds and 50p only"), so the line never starts with a figure that could be altered. In the words style an amount under a pound reads "Fifty pence only", as `text.number-to-words` writes it.

## Edge cases

- The amount must be greater than zero: a cheque cannot be written for nothing or for a negative sum. (`text.number-to-words` accepts negatives for credit notes; this does not.) - GBP, EUR and USD only, because those are the currencies `text.number-to-words` has unit names for; anything else fails with its error ("no words for currency"). - US checks conventionally write cents as a fraction ("and 99/100 dollars"); that style is not offered.

Files