---
title: SAIF.Framework.BaseN overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: <owner>
last_reviewed: 2026-07-23
library: SAIF.Framework.BaseN
reference_type: package
---

# SAIF.Framework.BaseN overview

> **Documentation context:** Packaged Component (NuGet)
>
> `SAIF.Framework.BaseN` is bundled into the `SAIF.BOF.Framework` NuGet package via a source-glob
> mechanism in `SAIF.Framework.Core\SAIF.BOF.Framework.Core.nuspec` rather than via a project
> reference or front-end entry-point.

`SAIF.Framework.BaseN` is a small, self-contained numeric base-conversion utility library. It implements a Strategy-pattern toolkit — an `IConverter` contract, an abstract `ConverterBase` template implementation, four concrete converters (binary, octal, hexadecimal, Excel-style base-26), a custom exception type, and a VB extension-method facade that exposes fluent conversion methods over any `IConverter`.

## Purpose
- Convert between decimal (`Long`/`Integer`) values and alphanumeric string representations in a configurable numeric base (binary, octal, hexadecimal, or Excel-style base-26 column naming).
- Provide a pluggable conversion contract (`IConverter`) so callers can substitute different base-N strategies interchangeably, with a fluent extension-method API (`BaseNToDecimal`, `DecimalToBaseN`) that decouples callers from converter-internal digit-array plumbing.

## Responsibilities
- Decode alphanumeric BaseN strings into decimal (`Long`) values.
- Encode decimal (`Long`/`Integer`) values into alphanumeric BaseN strings.
- Define and enforce base-specific digit mapping and formatting rules per converter (binary, octal, hex, Excel).
- Signal invalid digit values (exceeding a converter's base) via a dedicated exception type (`ConverterException`).

## Key components
- `IConverter`: Conversion contract — `Base`, `ConvertNumericToAlpha`, `ConvertAlphaToNumeric`, `FormatBaseN`.
- `ConverterBase`: Abstract base class supplying default digit-conversion and formatting logic.
- `BinaryConverter` / `OctalConverter`: Concrete converters for base 2 and base 8, relying on `ConverterBase` defaults.
- `HexConverter`: Concrete converter for base 16 with A–F digit mapping and strict bounds checking.
- `ExcelConverter`: Concrete converter for base 26 with bijective Excel-style column-letter semantics.
- `ConverterException`: Exception thrown when a digit value exceeds a converter's base.
- `BaseNConverter`: VB `Module` providing the `BaseNToDecimal`/`DecimalToBaseN` extension-method facade.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Configuration](configuration.md)
- [API reference](api/index.md)

## Sources
- `SAIF.Framework.BaseN\IConverter.vb`
- `SAIF.Framework.BaseN\ConverterBase.vb`
- `SAIF.Framework.BaseN\BinaryConverter.vb`
- `SAIF.Framework.BaseN\OctalConverter.vb`
- `SAIF.Framework.BaseN\HexConverter.vb`
- `SAIF.Framework.BaseN\ExcelConverter.vb`
- `SAIF.Framework.BaseN\ConverterException.vb`
- `SAIF.Framework.BaseN\BaseNConverter.vb`
- `SAIF.Framework.Core\SAIF.BOF.Framework.Core.nuspec`