Skip to content

Encode decimal to BaseN string

This operation converts a decimal number into a BaseN string. It recursively divides the value by the converter's base to build the digit sequence, then hands the finished digit array to the converter's formatter for final rendering.

Field Value
Operation ID OP-BASEN-002
Trigger Caller request through BaseNConverter.DecimalToBaseN
Inputs Decimal Integer or Long, IConverter
Outputs BaseN string
Primary components BaseNConverter.DecimalToBaseN, BaseNConverter.ConvertDecimalToBaseN, BaseNConverter.ConvertToNumericArray, IConverter.FormatBaseN
Entry point SAIF.Framework.BaseN\BaseNConverter.vb

Steps

  1. The caller reaches DecimalToBaseN through either its Integer or Long overload.
  2. If the Integer overload is used, the value is cast to Long and delegated to the Long overload; no further conversion logic exists in the Integer path.
  3. The Long overload calls the recursive helper ConvertDecimalToBaseN.
  4. Each recursive frame computes the integer quotient newValue = value \ converter.Base and the remainder remainder = value Mod converter.Base.
  5. The frame then builds an intermediate CSV fragment based on the quotient:
  6. If newValue >= converter.Base, the frame recurses on newValue first, then appends converter.ConvertNumericToAlpha(remainder) to the result returned by the deeper call.
  7. If newValue = 0, recursion stops and the frame returns only converter.ConvertNumericToAlpha(remainder).
  8. Otherwise, recursion stops and the frame returns converter.ConvertNumericToAlpha(newValue) followed by converter.ConvertNumericToAlpha(remainder).
  9. Each of these digit conversions goes through the converter's own ConvertNumericToAlpha, so HexConverter and ExcelConverter enforce their upper-bound checks at this point (BR-001, BR-002).
  10. Once recursion completes, commas are stripped from the CSV result and ConvertToNumericArray turns the rendered characters back into a numeric digit array.
  11. That digit array is passed to converter.FormatBaseN, which renders the final output string.
  12. ExcelConverter.FormatBaseN rewrites any zero digit through borrow/rollover logic at this stage, so the result stays in bijective A-through-Z, AA-style form (BR-003).
  13. The formatted BaseN string is returned to the caller.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([DecimalToBaseN called]) --> S1{Integer overload?}
    S1 -->|Yes| S2[Cast to Long]
    S1 -->|No| S3[Enter recursive conversion]
    S2 --> S3
    S3 --> S4[Compute quotient and remainder]
    S4 --> S5[Build intermediate digit CSV]
    S5 --> S6[Remove commas and rebuild digit array]
    S6 --> S7[FormatBaseN renders final string]
    S7 --> EndOk([Return BaseN string])

Failure and edge-case behavior

  • The Integer overload performs only a widening cast to Long; all conversion logic — recursion, digit rendering, and formatting — runs in the Long overload.
  • HexConverter and ExcelConverter can raise ConverterException mid-recursion if a direct IConverter call supplies a digit value greater than the converter's base while rendering (BR-001, BR-002).
  • ExcelConverter depends entirely on FormatBaseN to normalize zero digits; without that final formatting pass, the intermediate digit array would still contain literal zeros (BR-003).

Sources

  • SAIF.Framework.BaseN\BaseNConverter.vb
  • SAIF.Framework.BaseN\HexConverter.vb
  • SAIF.Framework.BaseN\ExcelConverter.vb