Skip to content

Format digit array as BaseN string

This operation walks a digit array from its last position to its first and renders each position into the final output string. Most converters use the shared ConverterBase implementation as-is; ExcelConverter overrides it to enforce Excel-style bijective base-26 rollover, since base-26 column naming has no zero digit.

Field Value
Operation ID OP-BASEN-003
Trigger Encode flow or direct formatter call
Inputs Integer digit array
Outputs Formatted BaseN string
Primary components ConverterBase.FormatBaseN, ExcelConverter.FormatBaseN
Entry point SAIF.Framework.BaseN\ConverterBase.vb

Steps

  1. The numeric digit array arrives through IConverter.FormatBaseN.
  2. An empty output string is initialized, and the array is iterated from its last index back to its first.
  3. ConverterBase.FormatBaseN converts each digit with ConvertNumericToAlpha(values(i)) and prepends the rendered token to the front of the output string, building the string in correct left-to-right reading order.
  4. When HexConverter renders a digit through this shared formatter, its digit conversion still enforces the upper-bound rule (BR-001).
  5. ExcelConverter.FormatBaseN parses the current position's value and, for every non-leading position, applies rollover handling before rendering:
  6. If the current digit is 0, it is replaced with 26.
  7. The preceding digit is then decremented by one.
  8. If that preceding digit is also 0, the borrow continues backward through the array until a non-zero digit absorbs the decrement.
  9. This borrow chain removes zero digits from the rendered alphabetic form, which is what makes the output correctly bijective (BR-003).
  10. In the Excel override, a position is only rendered when its adjusted value is greater than 0, using ConvertNumericToAlpha(value) to produce the emitted token.
  11. This digit renderer still enforces the upper-bound rule before converting the adjusted value to a character (BR-002).
  12. The completed output string is returned to the caller.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([FormatBaseN called]) --> S1[Iterate digits right to left]
    S1 --> D{ExcelConverter?}
    D -->|No| S2[Render each digit directly]
    D -->|Yes| S3[Normalize zero digits by borrowing]
    S3 --> S4[Render positive adjusted digits]
    S2 --> EndOk([Return formatted string])
    S4 --> EndOk

Failure and edge-case behavior

  • ConverterBase.FormatBaseN renders every digit it receives without exception; it does not validate array length against the converter's base or suppress zero digits.
  • ExcelConverter.FormatBaseN mutates the incoming digit array in place while borrowing across zero digits to enforce bijective output (BR-003).
  • ExcelConverter.FormatBaseN skips any position whose adjusted value is 0 after rollover processing, which is how leading zero placeholders are removed from the final output.

Sources

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