iconvex_platforms

# Iconvex Platforms

`iconvex_platforms` adds 117 pure-Elixir, vendor- and platform-qualified codecs
to [Iconvex](https://hex.pm/packages/iconvex). The package contributes 354
unique registry names: 117 canonicals and 237 aliases.

There are no NIFs, ports, subprocesses, or runtime calls to `iconv`. Installing
the OTP application registers the complete surface and its tables in one
transaction; stopping it removes exactly those routes and providers.

## Installation

```elixir
def deps do
  [
    {:iconvex, "~> 0.1"},
    {:iconvex_platforms, "~> 0.1"}
  ]
end
```

## A few fun conversions

IBM-1175 is the Turkish EBCDIC euro-and-lira revision:

```elixir
iex> Iconvex.convert("TRY ₺€", "UTF-8", "IBM-1175")
{:ok, <<0xE3, 0xD9, 0xE8, 0x40, 0x9A, 0x9F>>}
```

GNU glibc's BRF map turns Braille ASCII cells into Unicode Braille:

```elixir
iex> Iconvex.convert("AB", "BRF", "UTF-8")
{:ok, "⠁⠃"}
```

VietUnicode's four VNI transports are kept distinct. This is the 2002 ANSI
Win/Unix profile:

```elixir
iex> Iconvex.convert("Việt", "UTF-8", "VIETUNICODE-2002-VNI-ANSI-WIN-UNIX")
{:ok, <<0x56, 0x69, 0x65, 0xE4, 0x74>>}
```

Windows best-fit mappings are intentionally directional:

```elixir
iex> Iconvex.convert("−", "UTF-8", "WINDOWS-BESTFIT-1252")
{:ok, "-"}
iex> Iconvex.convert("-", "WINDOWS-BESTFIT-1252", "UTF-8")
{:ok, "-"}
```

Java Modified UTF-8 rejects a literal zero byte and accepts the two-byte NUL:

```elixir
iex> Iconvex.convert(<<0xC0, 0x80>>, "JAVA-MODIFIED-UTF-8", "UTF-8")
{:ok, <<0>>}
```

The stateful IBM-965 and IBM-17354 codecs emit designation and shift
sequences, while `UTF-8-MAC` implements the HFS Plus decomposition profile:

```elixir
iex> {:ok, encoded} = Iconvex.convert("A一", "UTF-8", "IBM-965")
iex> Iconvex.convert(encoded, "IBM-965", "UTF-8")
{:ok, "A一"}

iex> Iconvex.convert("é", "UTF-8", "UTF-8-MAC")
{:ok, "é"}
```

## What is included

| Family | Codecs | Examples |
|---|---:|---|
| glibc charmaps | 29 | TSCII, BRF, EUC-JP-MS, ISO_6937, KOI-8 |
| Adobe and Apple legacy maps | 28 | Adobe Standard, MacJapanese, MacKeyboard |
| ordinary platform/spec profiles | 30 | IBM-1175, IBM-965, Java Modified UTF-8, UTF-8-MAC |
| Windows best-fit | 15 | 874, 932, 936, 949, 950, 1250–1258, 1361 |
| Evertype source-qualified | 7 | Mac Armenian, Ogham, Georgian, Turkic Cyrillic |
| VietUnicode VNI 2002 | 4 | DOS, ANSI, Mac, Internet Mail |
| secondary source-qualified | 3 | Wang WISCII, EKI Sami CP1270, Polytonic Greek |
| Unicode legacy | 1 | US-ASCII-QUOTES |

Use `Iconvex.Platforms.encodings/0` for the canonical list and
`Iconvex.Platforms.registrations/0` for canonicals, aliases, modules, and
source families. The immutable row-by-row contract is
[`SURFACE_MANIFEST.tsv`](SURFACE_MANIFEST.tsv).

## Archive-independent IBM tables

IBM-1175, IBM-965, and IBM-17354 were originally routed through ICU Archive
provider IDs. IBM-934/938 and IBM-5052/5053/5055/958 also had seven hidden
Archive table dependencies. Platforms copies all ten immutable tables under
package-owned IDs. It neither depends on `iconvex_icu_archive` nor claims any
Archive provider, so both optional packages can be installed without provider
ownership collisions.

In total the package owns 84 tables: 73 declared manifest providers, ten
relocated IBM dependencies, and the pinned glibc IBM423 table.

## Verification

The test suite carries the original source fixtures and a 1,112,064-scalar
UTF-32BE corpus. It verifies every row and canonical inverse of the generated
mapping families, all 94×94 positions for IBM-965 and IBM-17354, every
byte/inverse for the single-byte profiles, stateful boundaries, substitution
and discard policies, malformed UTF-8 offsets, lifecycle rollback/restart,
artifact selection, source digests, and license selection.

Representative source-bound benchmarks enforce a 30× native/reference ceiling
and linear reduction scaling. See [`BENCHMARKS.md`](BENCHMARKS.md).

## Extending Iconvex

Third-party packages can use `Iconvex.Extension.register/2` to add codecs and
table providers transactionally. Platforms itself is a leaf package: its only
runtime dependency is Iconvex Core and its runtime contains no references to
the former monolithic Specs namespace.

Original Iconvex code is LGPL-2.1-or-later. Retained mapping/source artifacts
keep their upstream terms; see [`NOTICE`](NOTICE) and the shipped license
files.