banking.cheque-amount-words

def cheque_amount_words(amount: Money, pence_style: ChequePenceStyle) -> ChequeWording

ChequePenceStyle = Literal["words", "figures"]

@dataclass(frozen=True)
class ChequeWording:
    """What goes on the two amount lines of a cheque."""

    #: capitalised, ending "only"
    words: str
    #: e.g. "£1,234.56"
    figures: str

from fune.banking.cheque_amount_words import cheque_amount_words  # banking.cheque-amount-words@^1

from .banking_cheque_amount_words_types import ChequePenceStyle, ChequeWording
from .money_amount import Money, money  ← from money.amount ^1.0.0 · built alongside by fune
from .money_format import format_money  ← from money.format ^1.0.0 · built alongside by fune
from .text_number_to_words import amount_in_words  ← from text.number-to-words ^1.0.0 · built alongside by fune

#: The abbreviation written after pence as figures: 50p, 50c.
_MINOR_SUFFIX = {"GBP": "p", "EUR": "c", "USD": "c"}


def cheque_amount_words(amount: Money, pence_style: ChequePenceStyle) -> ChequeWording:
    """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.
    """
    if amount.minor <= 0:
        raise ValueError("a cheque amount must be greater than zero, received %d" % (amount.minor,))
    if pence_style == "words":
        body = amount_in_words(amount)
    elif pence_style == "figures":
        # The pounds are always in words, even when there are none, so the
        # line never starts with a figure that could be altered.
        major, minor = divmod(amount.minor, 100)
        body = amount_in_words(money(major * 100, amount.currency))
        if minor > 0:
            body += " and %d%s" % (minor, _MINOR_SUFFIX[amount.currency])
    else:
        raise ValueError('unknown pence style "%s": expected words or figures' % (pence_style,))
    words = body[0].upper() + body[1:] + " only"
    return ChequeWording(words=words, figures=format_money(amount))

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the Python 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 Python implementation. Install it without the registry with fune add ./banking.cheque-amount-words-1.0.0-python.fune, or fetch it from a terminal with fune pull banking.cheque-amount-words@1.0.0:python.

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