Skip to content

Convert a number to English words

Recursively converts a whole number to its English-word rendering, decomposing by magnitude band.

Field Value
Operation ID op-03-number-to-text
Trigger A caller needs a written-word rendering of a whole number
Inputs n As Long
Outputs Space-delimited English words (trailing space is produced by the unit branch)
Primary components mdlTextConversion.NumberToText
Entry point SAIF.Business.Utilities/mdlTextConversion.vb

Steps

  1. If n > 999999999999999, throw ApplicationException("Number too large to convert to text. Limit is 999,999,999,999,999.") (BR-013).
  2. If n < 0, return "Minus " concatenated with the recursive conversion of -n (BR-014).
  3. If n = 0, return an empty string (BR-015) — this is also the recursion terminator for exact multiples.
  4. If n <= 19, index the literal ones/teens word array and append a trailing space.
  5. If n <= 99, index the tens word array via RoundDown(n, 10) - 2 and recurse on n Mod 10.
  6. For each higher magnitude band (hundred, thousand, million, billion, trillion) the function emits "One <band> " for the 1xxx… special case, otherwise recurses on RoundDown(n, band), appends the band name, and recurses on n Mod band (BR-016).

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Caller invokes NumberToText]) --> CheckLimit{n > 999999999999999?}
    CheckLimit -->|Yes| ThrowEx(["Throw ApplicationException:<br>Number too large to convert"])
    CheckLimit -->|No| CheckNeg{n < 0?}
    CheckNeg -->|Yes| Negate["Return 'Minus ' concatenated<br>with recursive conversion of -n"]
    CheckNeg -->|No| CheckZero{n = 0?}
    CheckZero -->|Yes| ReturnEmpty([Return empty string])
    CheckZero -->|No| CheckTeens{n <= 19?}
    CheckTeens -->|Yes| IndexOnes["Index ones/teens word array,<br>append trailing space"]
    CheckTeens -->|No| CheckTens{n <= 99?}
    CheckTens -->|Yes| TensBranch["Index tens word array via<br>RoundDown(n, 10) - 2,<br>recurse on n Mod 10"]
    CheckTens -->|No| BandCheck{"n is in a higher<br>magnitude band?"}
    BandCheck -->|"1xxx… special case"| OneBand["Emit 'One band '"]
    BandCheck -->|Otherwise| RecurseBand["Recurse on RoundDown(n, band),<br>append band name,<br>recurse on n Mod band"]
    Negate --> Done([Return word rendering])
    IndexOnes --> Done
    TensBranch --> Done
    OneBand --> Done
    RecurseBand --> Done
    ReturnEmpty --> Done

Failure and edge-case behavior

  • Only the explicit ApplicationException above; no other validation.

Sources

  • SAIF.Business.Utilities/mdlTextConversion.vb