---
title: Numeric-to-text conversion
summary: Converts an integer amount into its English-words representation, with an explicit upper bound.
status: draft
owner: <owner>
last_reviewed: 2026-07-30
library: SAIF.Business.Utilities
reference_type: package
operation_id: OP-BU-02
trigger: Caller calls mdlTextConversion.NumberToText
---

# 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](../business-rules.md#br-002-numeric-conversion-upper-bound))
   - On failure: the exception propagates to the caller; no partial result is returned.
2. **Handle negative values.** If `n` is less than zero, prefix the result with `"Minus "` and recursively convert the absolute value (`-n`).
3. **Handle the zero case.** If `n` equals zero, return an empty string (used as the recursion base case for magnitude groups with no remainder).
4. **Convert ones and teens (1–19).** Look up the value in a fixed array of number words ("One" through "Nineteen").
5. **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`).
6. **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.
7. **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.
8. **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.

```mermaid
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](../business-rules.md#br-002-numeric-conversion-upper-bound))
- 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.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- `Business\SAIF.Business.Utilities\mdlTextConversion.vb`