text.number-to-words

export function amountInWords(amount: Money): string

import { amountInWords } from "#fune/text.number-to-words@^1";

import { type Money } from "./money_amount.ts";  ← from money.amount ^1.0.0 · built alongside by fune
import { integerToWords } from "./text_integer_to_words.ts";  ← from text.integer-to-words ^1.0.0 · built alongside by fune

interface UnitNames {
  majorOne: string;
  majorMany: string;
  minorOne: string;
  minorMany: string;
}

/**
 * English unit names for the currencies this capability supports. All three
 * have two decimal places, so the split below is by 100. A currency is not
 * added here without its real unit names: they cannot be derived from a code.
 */
const UNITS: { [code: string]: UnitNames } = {
  GBP: { majorOne: "pound", majorMany: "pounds", minorOne: "penny", minorMany: "pence" },
  EUR: { majorOne: "euro", majorMany: "euros", minorOne: "cent", minorMany: "cents" },
  USD: { majorOne: "dollar", majorMany: "dollars", minorOne: "cent", minorMany: "cents" },
};

/**
 * Write a money amount in words, cheque style: 123456 GBP minor units is
 * "one thousand two hundred and thirty-four pounds and fifty-six pence".
 */
export function amountInWords(amount: Money): string {
  const units = Object.prototype.hasOwnProperty.call(UNITS, amount.currency) ? UNITS[amount.currency] : undefined;
  if (units === undefined) {
    throw new RangeError(`no words for currency "${amount.currency}"`);
  }

  // Validate the whole amount first, so an out-of-range value fails with the
  // same message it would as a plain number.
  integerToWords(amount.minor);

  const magnitude = Math.abs(amount.minor);
  const major = Math.floor(magnitude / 100);
  const minor = magnitude % 100;

  const parts: string[] = [];
  if (major > 0 || minor === 0) {
    parts.push(`${integerToWords(major)} ${major === 1 ? units.majorOne : units.majorMany}`);
  }
  if (minor > 0) {
    parts.push(`${integerToWords(minor)} ${minor === 1 ? units.minorOne : units.minorMany}`);
  }

  const body = parts.join(" and ");
  return amount.minor < 0 ? `minus ${body}` : body;
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 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 text.number-to-words

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

The whole function, every language, is one file too: text.number-to-words-1.0.0.fune, 11,719 bytes, sha256 fdaf116aa82fea8fd199e36476f6a67f745c9cc3fc9eac5e96dae653996723b7. It installs into a project of any language.

// fune: before text.number-to-words

// fune: after text.number-to-words

// fune: replace money.amount in text.number-to-words
// fune: replace text.integer-to-words in text.number-to-words

// fune: step text.number-to-words after <n|label>

More from the author

A cheque amount is money, and money in this registry is never a float. Taking `Money` (integer minor units) means 0.1 + 0.2 can never turn into "thirty pence and a bit", and the pence are always exactly what was paid.

## Wording

- Major units, then " and ", then minor units: "one pound and one penny". - Singular for exactly one: "one pound", "one penny", "one euro", "one cent", "one dollar". Otherwise plural: "pounds", "pence", "euros", "cents", "dollars". - A whole amount leaves the minor units out: "ten pounds", not "ten pounds and zero pence". An amount under one major unit leaves the major units out: "fifty pence". Zero is "zero pounds". - No "only" is added. Cheque writers traditionally end with "only" to stop words being added afterwards; append it yourself if your stationery wants it. - Negative amounts (credit notes) read as "minus ...". - Everything is lower case.

## Currencies

Only the three currencies whose English unit names are listed below are supported; any other currency is an error, not a guess, because the words for a currency's units are not derivable from its code.

| Code | Major (one / many) | Minor (one / many) | |------|--------------------|--------------------| | GBP | pound / pounds | penny / pence | | EUR | euro / euros | cent / cents | | USD | dollar / dollars | cent / cents |

All three have two decimal places. EU legislation spells the plural "euro" with no "s" in English; everyday British and Irish usage, and most invoices, say "euros", which is what this writes.

## Limits

The amount's minor units must be within 2^53 - 1 (the range all three languages agree on); `text.integer-to-words` rejects anything larger.

Files