text.number-to-words

pub fn amount_in_words(amount: &Money) -> String

fune!(text.number-to-words@^1);  // then call amount_in_words(…)

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::money_amount::{money_from_value, Money};  ← from money.amount ^1.0.0 · built alongside by fune
use super::text_integer_to_words::integer_to_words;  ← from text.integer-to-words ^1.0.0 · built alongside by fune

/// English unit names: (code, major one, major many, minor one, minor many).
/// All three currencies 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: [(&str, &str, &str, &str, &str); 3] = [
    ("GBP", "pound", "pounds", "penny", "pence"),
    ("EUR", "euro", "euros", "cent", "cents"),
    ("USD", "dollar", "dollars", "cent", "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".
///
/// # Panics
/// Panics on a currency without listed unit names, or an out-of-range amount.
pub fn amount_in_words(amount: &Money) -> String {
    let units = match UNITS.iter().find(|u| u.0 == amount.currency) {
        Some(found) => found,
        None => panic!("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.
    integer_to_words(amount.minor);

    let magnitude = amount.minor.abs();
    let major = magnitude / 100;
    let minor = magnitude % 100;

    let mut parts: Vec<String> = Vec::new();
    if major > 0 || minor == 0 {
        let name = if major == 1 { units.1 } else { units.2 };
        parts.push(format!("{} {}", integer_to_words(major), name));
    }
    if minor > 0 {
        let name = if minor == 1 { units.3 } else { units.4 };
        parts.push(format!("{} {}", integer_to_words(minor), name));
    }

    let body = parts.join(" and ");
    if amount.minor < 0 {
        format!("minus {}", body)
    } else {
        body
    }
}

pub fn fune_vector(args: &[Value]) -> Value {
    Value::Str(amount_in_words(&money_from_value(&args[0])))
}

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 text.number-to-words

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

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