Iconvex Telecom

Iconvex Telecom provides pure Elixir telecom encodings through the external-codec API in Iconvex. Its 61 codecs include every GSM 03.38 national locking and single-shift table.

The package includes ITA alphabets, MTK-2, IA5, Morse, CCIR 476, AIS6, ARIB Shift-JIS, IBM Six-Bit Transcode, TBCD, and SIM alpha identifiers. It also includes Murray tape, Wheatstone action tape, Japanese carrier emoji, and the U.S. Army POW tap-count matrix.

The packed facade supports 53 fixed-width profiles in MSB and LSB order. Their widths are 3, 5, 6, or 7 bits. Family helpers preserve CCIR FEC polarity and AIS payload armoring.

Registered GSM codecs use the unpacked SMPP representation. Each septet occupies one octet, and its high bit is zero. The separate TPDU packing API accepts the required septet count and UDH alignment.

Installation

Add both packages to mix.exs:

def deps do
  [
    {:iconvex, "~> 0.1.1"},
    {:iconvex_telecom, "~> 0.1.1"}
  ]
end

Starting :iconvex_telecom registers all 61 named codecs. One managed transaction installs the complete set. Its cleanup token survives a supervised Iconvex registry-worker restart.

You can start all feature packages in any order. The complete registry contains 2,105 unique canonical names.

The generated ../ICONVEX_FULL_STACK_SUPPORT.md file provides workspace-level integration evidence. It covers all 2,105 canonical names and GNU libiconv 1.19. The package artifact does not include this file. Use the relative path only from the sibling-package source checkout.

SURFACE_MANIFEST.tsv records the package ownership changes. It covers six registered codecs and two packed profiles from this release.

Iconvex.convert("€Ğ", "UTF-8", "GSM0338-TURKISH")
# => {:ok, <<0x04, 0x1B, 0x47>>}

Iconvex.convert(<<0x04, 0x1B, 0x47>>, "GSM0338-TURKISH", "UTF-8")
# => {:ok, "€Ğ"}

Iconvex.convert("HELLO 123", "UTF-8", "ITA2")
# => {:ok, <<20, 1, 18, 18, 24, 4, 27, 23, 19, 1>>}

Iconvex.convert("HELLO 123", "UTF-8", "CCIR476")
# => {:ok, <<0x4B, 0x35, 0x53, 0x53, 0x47, 0x1D, 0x36, 0x3A, 0x72, 0x35>>}

Iconvex.convert("AIS 123?", "UTF-8", "AIS6")
# => {:ok, <<1, 9, 19, 32, 49, 50, 51, 63>>}

Iconvex.convert("ABCd", "UTF-8", "ITA2-S2")
# => {:ok, <<27, 31, 3, 25, 14, 31, 9>>}

Iconvex.convert("ABCD", "UTF-8", "IBM-2780-SIX-BIT-TRANSCODE-GA27-3005-3")
# => {:ok, <<1, 2, 3, 4>>}

Iconvex.convert("あ⛌", "UTF-8", "ARIB-STD-B24-SHIFT-JIS-6.4-E1")
# => {:ok, <<0x82, 0xA0, 0xED, 0x9F>>}

Iconvex.convert(<<0x82, 0xA0, 0xED, 0x9F>>, "ARIB-STD-B24-SHIFT-JIS-6.4-E1", "UTF-8")
# => {:ok, "あ⛌"}

Iconvex.convert("12345", "UTF-8", "TBCD")
# => {:ok, <<0x21, 0x43, 0xF5>>}

Iconvex.convert(<<0x81, 2, 0x08, 0x41, 0x90>>, "SIM-ALPHA", "UTF-8")
# => {:ok, "AА"}

Iconvex.convert("1A", "UTF-8", "MURRAY-1905-FIGURE-7-TAPE")
# => {:ok, <<27, 29, 31, 24>>}

Iconvex.convert(". -", "UTF-8", "WHEATSTONE-1915-HAUSMANN-THREE-KEY-ACTION-TAPE")
# => {:ok, <<0b111, 0b010, 0b110, 0b011>>}

Iconvex.convert("☀", "UTF-8", "UNICODE-17.0.0-EMOJISOURCES-DOCOMO-SHIFT-JIS")
# => {:ok, <<0xF8, 0x9F>>}

Iconvex.convert("CK", "UTF-8", "US-ARMY-GTA-31-70-001-TAP-CODE-PAIR-VALUES")
# => {:ok, <<1, 3, 1, 3>>}

The long canonical names define provenance boundaries. The package does not register Murray as MURRAY or BAUDOT. The Wheatstone profile represents physical perforator actions, not framed Morse characters. The Army profile stores row and column tap counts as two numeric octets. It does not claim every Tap Code variant.

The three carrier profiles overlay exact EmojiSources.txt byte pairs on CP932. They cover DoCoMo, KDDI, and SoftBank. Carrier bytes take priority over displaced CP932 PUA mappings. Other CP932 mappings and canonical inverses do not change. See UNICODE17_CARRIER_EMOJI.md.

SIM alpha identifiers use a framing-aware incremental decoder. Recovery can discard or replace an invalid UCS-2 unit without losing the framing mode. It does not reinterpret the suffix as GSM or change the callback position.

After an invalid first default-alphabet octet, recovery commits to GSM mode. It does not treat a later 0x80, 0x81, or 0x82 value as a framing header. One-shot conversion and every lazy Stream split produce the same result. An earlier invalid UCS-2 unit takes priority over a later odd tail.

A short 0x81 or 0x82 payload reports its empty sequence at physical EOF. Plain discard retains a valid payload prefix without creating a callback for an absent byte. Physical compressed-payload errors take priority over a later EOF. A trailing GSM escape reports its byte when the frame declares more payload.

ETSI TS 102 221 section 8.2 limits a linear fixed record to 255 octets. The helper and codec APIs reject a 256th physical record byte. Streaming state counts consumed and pending octets separately. Their sum cannot exceed 255. Target state uses the same limit. SIMAlphaIdentifier.max_bytes/0 and SIMAlphaIdentifierCodec.max_bytes/0 expose it.

Independent national tables

3GPP permits the locking and single-shift tables to name different languages. The low-level API exposes every one of the 182 valid pairings:

alias Iconvex.Telecom.GSM0338

options = [locking: :portuguese, single_shift: :bengali]

GSM0338.decode(<<0x04, 0x1B, 0x19>>, options)
# => {:ok, [0x00EA, 0x09E6]}

GSM0338.encode([0x00EA, 0x09E6], options)
# => {:ok, <<0x04, 0x1B, 0x19>>}

GSM0338.valid_pairs() |> length()
# => 182

Locking choices are :default, :turkish, :portuguese, :bengali, :gujarati, :hindi, :kannada, :malayalam, :oriya, :punjabi, :tamil, :telugu, and :urdu.

Single-shift choices contain the same set plus :spanish. Spanish has no locking table in 3GPP, so GSM0338-SPANISH combines the default locking table with the Spanish single-shift table.

decode_utf8/2 and encode_utf8/2 are the fastest direct paths. Iconvex.convert/4 calls equivalent codec fast paths automatically.

See SUPPORTED_ENCODINGS.md, SUPPORTED_CODEC_INVENTORY.csv, CONFORMANCE.md, and BENCHMARKS.md.

Telecom transports

alias Iconvex.Telecom.{AIS6, GSM0338.Packing, ITA2, SIMAlphaIdentifier, TBCD}

Packing.pack("hellohello")
# => {:ok, <<0xE8, 0x32, 0x9B, 0xFD, 0x46, 0x97, 0xD9, 0xEC, 0x37>>}

TBCD.encode("12345")
# => {:ok, <<0x21, 0x43, 0xF5>>}

SIMAlphaIdentifier.encode("AА")
# => {:ok, <<0x81, 2, 0x08, 0x41, 0x90>>}

{:ok, ita2_units} = ITA2.encode(~c"HELLO")
ITA2.Packing.pack(ita2_units)
# => {:ok, <<20::5, 1::5, 18::5, 18::5, 24::5>>}

{:ok, ais_units} = AIS6.encode(~c"AIS 123?")
AIS6.Armor.encode(ais_units)
# => {:ok, "19CPijkw"}

{:ok, gsm_packed} =
  Iconvex.Telecom.Packed.encode_from_utf8("hellohello", "GSM0338")

Base.encode16(gsm_packed.data)
# => "E8329BFD4697D9EC37"

Iconvex.Telecom.Packed.decode_to_utf8(gsm_packed, "GSM0338")
# => {:ok, "hellohello"}

Iconvex.Telecom.Packed.profiles/0 returns the exact runtime list. Each profile accepts :standard, :msb, or :lsb. SUPPORTED_PACKED_CODEC_INVENTORY.csv records the standard order. The facade caches immutable metadata in persistent_term. Runtime calls do not rebuild the 53-profile catalog.

IBM Transcode defaults to its documented low-order-first transport. The same facade also accepts the explicit MSB name. A -PACKED-MSB or -PACKED-LSB suffix selects its named order. An explicit conflicting order returns {:error, :bit_order_mismatch}. A non-LSB tag on an LSB transport returns the same error.

Packed decode failures report physical bit offsets. They do not report offsets in the temporary unpacked buffer. MSB fragments retain their exact bit width. LSB fragments use the failing unit integer. These rules match the Core packed transport contracts.

License

The original library code uses LGPL-2.1-or-later, matching GNU libiconv. Imported Android/Apache and Unicode fixtures retain upstream licenses. Public-domain historical publications and U.S. government source evidence keep their attribution and package-boundary notes. See LICENSE.APACHE-2.0, LICENSE.UNICODE, SOURCE_PROVENANCE.md, and NOTICE.

Complete codec catalog

The generator builds this table from the release inventories. Do not edit this section by hand. Codec names ignore ASCII letter case. You can use each alias to look up its codec. Aliases do not increase the canonical codec count.

61 canonical codecs · 129 aliases · 190 accepted names.

Registered codec names

Packed transport profiles

53 base codec profiles · 106 explicit packed names. These profiles change the bit transport only. They do not add registered Unicode mappings.