---
title: Encode decimal to BaseN string
summary: Converts a decimal `Integer` or `Long` value into the selected BaseN string.
status: draft
owner: SAIF DocGen
last_reviewed: 2026-07-30
library: SAIF.Framework.BaseN
reference_type: package
operation_id: OP-BASEN-002
trigger: Caller invokes `DecimalToBaseN` on an `Integer` or `Long`.
---

# 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:
   - If `newValue >= converter.Base`, the frame recurses on `newValue` first, then appends `converter.ConvertNumericToAlpha(remainder)` to the result returned by the deeper call.
   - If `newValue = 0`, recursion stops and the frame returns only `converter.ConvertNumericToAlpha(remainder)`.
   - Otherwise, recursion stops and the frame returns `converter.ConvertNumericToAlpha(newValue)` followed by `converter.ConvertNumericToAlpha(remainder)`.
   - 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](../business-rules.md#br-001-hexadecimal-digit-must-not-exceed-base-16), [BR-002](../business-rules.md#br-002-excel-base-26-digit-must-not-exceed-base-26)).
6. Once recursion completes, commas are stripped from the CSV result and `ConvertToNumericArray` turns the rendered characters back into a numeric digit array.
7. That digit array is passed to `converter.FormatBaseN`, which renders the final output string.
   - `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](../business-rules.md#br-003-excel-style-base-26-conversion-is-bijective-no-zero-digit)).
8. The formatted BaseN string is returned to the caller.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
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](../business-rules.md#br-001-hexadecimal-digit-must-not-exceed-base-16), [BR-002](../business-rules.md#br-002-excel-base-26-digit-must-not-exceed-base-26)).
- `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](../business-rules.md#br-003-excel-style-base-26-conversion-is-bijective-no-zero-digit)).

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

## Sources
- `SAIF.Framework.BaseN\BaseNConverter.vb`
- `SAIF.Framework.BaseN\HexConverter.vb`
- `SAIF.Framework.BaseN\ExcelConverter.vb`