Skip to content

Convert a number to English words

This operation converts a Long numeric value into its English-word representation (e.g., for check or amount-in-words rendering), using recursive magnitude decomposition down to the ones/teens level.

Field Value
Operation ID OP-UTIL-002
Trigger Caller invokes mdlTextConversion.NumberToText(n).
Inputs A Long value n.
Outputs A String spelling out n in English words.
Primary components mdlTextConversion.NumberToText, mdlTextConversion.RoundDown
Entry point SAIF.Business.Utilities\mdlTextConversion.vb

Steps

  1. Reject values greater than 999,999,999,999,999 by throwing ApplicationException("Number too large to convert to text..."). (BR-UTIL-010)
  2. On failure: exception propagates to the caller; no partial result is returned.
  3. If the value is negative, prefix "Minus " and recurse on the absolute value.
  4. If the value is zero, return an empty string (no "Zero" word emitted). (BR-UTIL-011)
  5. If the value is 1–19, look up the word directly from a fixed ones/teens array.
  6. If the value is 20–99, look up the tens word (Twenty…Ninety) and recurse on the remainder (n Mod 10) for the ones digit.
  7. If the value is 100–199, prefix "One Hundred " and recurse on the remainder (n Mod 100).
  8. If the value is 200–999, recurse to spell the hundreds digit, append "Hundred ", and recurse on the remainder (n Mod 100).
  9. Apply the same "≤1999-of-that-unit special case, else group-of-3 recursion" pattern successively for Thousand, Million, Billion, and Trillion magnitudes: each level has a branch that says "One {Unit} " for values ≤ 1,999 of that unit, and a general branch that recurses to spell the leading digit group, appends "{Unit} ", then recurses on the remainder.
  10. Private helper RoundDown(inValue, inDivisor) performs integer floor-division used by the recursion at each magnitude level.
  11. Return the fully composed English-word string.

No step in this operation delegates into another project/library in this repository or into a SAIF BOF Framework operation — the operation is entirely self-contained BCL-only integer arithmetic.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Trigger: NumberToText call]) --> Bound{n greater than 999,999,999,999,999?}
    Bound -->|Yes| Throw([Throw ApplicationException])
    Bound -->|No| Sign{n negative?}
    Sign -->|Yes| Minus[Prefix Minus, recurse on abs value]
    Sign -->|No| Zero{n = 0?}
    Zero -->|Yes| EmptyStr([Return empty string])
    Zero -->|No| Magnitude[Recurse by magnitude:<br>ones/teens, tens, hundreds,<br>thousands, millions, billions, trillions]
    Magnitude --> End([Return spelled-out words])

Failure and edge-case behavior

  • n greater than 999,999,999,999,999: throws ApplicationException, no result returned.
  • n equal to 0: returns an empty string rather than the word "Zero", so whole-hundred/thousand values omit trailing "Zero" text.
  • n negative: recurses on the absolute value with a "Minus " prefix.

Sources

  • SAIF.Business.Utilities\mdlTextConversion.vb
  • .saifdocgen/state/runs/20260821-113120-claims-bof-web-legal/analysis/TSK007-analysis.md