Skip to content

Numeric-to-text conversion

This operation converts a signed integer amount into its English-words representation (e.g., for printed check or dollar amounts), recursively decomposing the value into magnitude groups and concatenating the words for each group with the appropriate magnitude label.

Field Value
Operation ID OP-BU-02
Trigger Caller calls mdlTextConversion.NumberToText(n)
Inputs n As Long
Outputs String (English-words representation of n)
Primary components mdlTextConversion.NumberToText, mdlTextConversion.RoundDown
Entry point Business\SAIF.Business.Utilities\mdlTextConversion.vb

Steps

  1. Validate the upper bound. If n exceeds 999,999,999,999,999, throw ApplicationException("Number too large to convert to text. Limit is 999,999,999,999,999."). (BR-002)
  2. On failure: the exception propagates to the caller; no partial result is returned.
  3. Handle negative values. If n is less than zero, prefix the result with "Minus " and recursively convert the absolute value (-n).
  4. Handle the zero case. If n equals zero, return an empty string (used as the recursion base case for magnitude groups with no remainder).
  5. Convert ones and teens (1–19). Look up the value in a fixed array of number words ("One" through "Nineteen").
  6. Convert tens (20–99). Look up the tens digit in a fixed array of tens words ("Twenty" through "Ninety") using RoundDown(n, 10) - 2 as the index, and recursively convert and append the remainder (n Mod 10).
  7. Convert hundreds (100–999). For 100–199, prefix "One Hundred " and recursively convert the remainder (n Mod 100); for 200–999, recursively convert the hundreds digit, append "Hundred ", and recursively convert the remainder.
  8. Convert thousands, millions, billions, and trillions, following the same pattern at each magnitude: a 1999-style band prefixes "One <Magnitude> " and recursively converts the remainder; the general band recursively converts the leading digits (via RoundDown), appends the magnitude label ("Thousand ", "Million ", "Billion ", "Trillion "), and recursively converts the remainder.
  9. Return the concatenated result. The recursive calls build up the final words string, which is returned to the caller with a trailing space after each word group.*

Process flow

The following diagram visualizes the magnitude-band recursion used by this operation.

flowchart TD
    Start([Start: NumberToText n]) --> Bound{n exceeds<br>999,999,999,999,999?}
    Bound -->|Yes| Ex([Throw ApplicationException])
    Bound -->|No| Neg{n less than 0?}
    Neg -->|Yes| Minus["Prefix 'Minus '<br>recurse on -n"]
    Neg -->|No| Zero{n equals 0?}
    Zero -->|Yes| Empty([Return empty string])
    Zero -->|No| Band{Which magnitude band?}
    Band -->|1-19| Ones[Look up in ones/teens array]
    Band -->|20-99| Tens[Look up tens word,<br>recurse on remainder]
    Band -->|100-999| Hundreds[Recurse on hundreds digit,<br>append 'Hundred',<br>recurse on remainder]
    Band -->|Thousands/Millions/<br>Billions/Trillions| Magnitude[Recurse on leading digits,<br>append magnitude label,<br>recurse on remainder]
    Ones --> Return([Return concatenated words])
    Tens --> Return
    Hundreds --> Return
    Magnitude --> Return
    Minus --> Return

Failure and edge-case behavior

  • n greater than 999,999,999,999,999 throws ApplicationException rather than returning a partial or truncated result. (BR-002)
  • Negative numbers are supported via a "Minus " prefix and recursion on the absolute value; there is no explicit lower-bound guard symmetrical to the upper-bound check.*
  • Zero returns an empty string rather than the word "Zero" — this is relied upon as the recursion base case for magnitude groups with no remainder, but also means a top-level call with n = 0 returns an empty string rather than a descriptive word.*

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

  • Business\SAIF.Business.Utilities\mdlTextConversion.vb