Skip to content

mdlTextConversion

A public module providing number-to-words conversion and sentence-case string formatting utilities. These operations are independent of the title-casing logic in TitleCase and serve specialized formatting needs (e.g. rendering numeric amounts as written English for legal or printed output, normalizing sentence-style display text). When SAIF.Business.Utilities is imported, NumberToText and ToSentenceCase become available directly on target values or as module-level functions. All members are public and shared; the module holds no state.

Purpose

  • Render whole numbers as English words (e.g. 1234 → One Thousand Two Hundred Thirty Four), suitable for written amounts on legal documents or printed forms.
  • Normalize strings to sentence casing (first character upper, remainder lower) for consistent display presentation.
  • Provide a clean API for magnitude-based numeric conversion with explicit error bounds and negative-number handling.

Context

  • Namespace: SAIF.Business.Utilities
  • Assembly/package: SAIF.Business.Utilities.dll
  • Module type: VB.NET Public Module (all members are either public functions or extension methods)

Public members

Member Signature Purpose
NumberToText Public Function NumberToText(ByVal n As Long) As String Convert a whole number (long integer) to English words. Recursively decomposes by magnitude band (ones, tens, hundreds, thousands, millions, billions, trillions) and concatenates word forms. Returns space-delimited words with a trailing space. Throws ApplicationException if magnitude exceeds 999,999,999,999,999. Returns empty string for zero.
ToSentenceCase Public Function ToSentenceCase(ByVal Target As String) As String (extension method) Normalize a string to sentence casing: upper-case the first character, lower-case the remainder. Handles Nothing by returning Nothing; handles empty/single-character strings as edge cases.

Private implementation members (documented for control flow)

Member Signature Role
RoundDown Private Function (ByVal inValue As Long, ByVal inDivisor As Long) As Integer Integer magnitude division helper; used to extract the high-order band from a number (e.g., RoundDown(1234, 1000) → 1, to identify "One Thousand").

Behavioral notes

  • Magnitude decomposition: NumberToText recursively processes numbers band-by-band (ones/teens, tens, hundreds, thousands, etc.). Each band from hundreds onward follows the pattern "emit One <band> for the leading 1, otherwise recurse and append band name". Band recursion continues for the remainder via n Mod band (BR-016).
  • Zero and termination: Returning empty string for zero (BR-015) also serves as the recursion terminator when n Mod band becomes zero (e.g., 1000 terminates after "One Thousand" with no trailing "Zero").
  • Trailing space: The output of NumberToText includes a trailing space (emitted by the ones/teens/unit branch). Consuming code may need to trim this for final display**.
  • Negative numbers: Handled by prefixing "Minus " and recursing on the absolute value (BR-014). The recursive result is concatenated directly, so the trailing space from the absolute value is retained.
  • Magnitude limit: Values > 999,999,999,999,999 throw ApplicationException("Number too large to convert to text. Limit is 999,999,999,999,999.") (BR-013). Callers must validate or catch this exception.
  • StrConv not used: Unlike TitleCaseExtensions.ToProperCase, sentence casing is implemented directly (not via VB runtime functions) by manipulating the first character and calling .ToLower() on the remainder.
  • Recursion depth in NumberToText: Depth is bounded by the magnitude bands (ones/tens/hundreds/thousands/millions/billions/trillions = ~7 levels maximum) but may increase if intermediate bands also recurse on their modulo remainder. For typical numbers, depth is modest*.

Constraints and usage notes

  • Stateless: All members are shared; calls are thread-safe.
  • Explicit output contract: The output format (space-delimited words with trailing space) is stable for all inputs within the magnitude limit.
  • No locale/culture awareness: The English word forms are hard-coded; no support for other languages or regional number formatting*.
  • No special handling for Nothing: Calling NumberToText with a Nothing value is not applicable (VB Nothing for Long is 0, which is valid and returns empty string). Calling ToSentenceCase(Nothing) explicitly returns Nothing*.
  • Actual callers within this repository: NumberToText has no confirmed caller in the SAIF.Business.Utilities source or the consuming SAIF.Business.View.Policy project — its intended use (written amounts on legal/printed forms) is not observed in this codebase**.
  • ToSentenceCase callers: Similarly, ToSentenceCase has no observed caller in this repository**.
  • RoundDown implementation: Uses integer truncation to extract the magnitude band; the return type is Integer (32-bit signed), not Long. For inputs near the Long.MaxValue, overflow is theoretically possible (though the magnitude limit check in NumberToText prevents actual overflow)*.

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources

  • SAIF.Business.Utilities/mdlTextConversion.vb
  • SAIF.Business.Utilities/SAIF.Business.Utilities.vbproj