Shared callback helpers for codecs backed by Iconvex.TableCodec.
Package codecs must make table ownership explicit. Use table_entry/2 when
the table belongs to a known OTP application, or provider_entry/1 when the
table application is selected through Iconvex.Tables provider routing:
entry = Iconvex.CodecSupport.table_entry(:my_encoding, :my_package)
Iconvex.CodecSupport.decode(entry, bytes)
provider_entry = Iconvex.CodecSupport.provider_entry(:shared_encoding)
Iconvex.CodecSupport.encode(provider_entry, codepoints)The helpers preserve the Iconvex.TableCodec strict, discard,
substitution, streaming, and direct UTF-8 contracts. Direct UTF-8 fallback
also preserves global first-error ordering: an unrepresentable character in
the valid prefix wins over malformed UTF-8 that occurs later.
Summary
Types
The target-side policy accepted by chunk encoders.
A table entry accepted by the codec helpers.
An entry resolved through the current table-provider route.
An entry pinned to a table-owning OTP application.
Functions
Decodes a complete source binary using strict error handling.
Decodes one source chunk, retaining an incomplete suffix when non-final.
Decodes a complete source binary while discarding malformed units.
Returns the source bytes consumed when recovering from a decode error.
Decodes directly to UTF-8.
Encodes codepoints using strict unrepresentable-character handling.
Encodes one target chunk and retains any incomplete codepoint prefix.
Encodes codepoints while discarding unrepresentable characters.
Encodes UTF-8 directly, falling back through codepoints when required.
Encodes codepoints and invokes replacer for each unrepresentable character.
Applies substitution one codepoint at a time using an arbitrary encoder.
Builds a substituted codepoint sequence, then passes it once to encoder.
Validates UTF-8 and passes decoded codepoints to encoder.
Uses valid_encoder for valid UTF-8 and prefix_encoder only to establish
first-error ordering when the source is malformed.
Returns the first malformed UTF-8 suffix and its absolute byte offset.
Builds an entry whose table application is selected by provider routing.
Builds an entry pinned to table_app.
Types
The target-side policy accepted by chunk encoders.
@type entry() :: table_entry() | provider_entry()
A table entry accepted by the codec helpers.
@type provider_entry() :: %{id: atom()}
An entry resolved through the current table-provider route.
An entry pinned to a table-owning OTP application.
Functions
Decodes a complete source binary using strict error handling.
Decodes one source chunk, retaining an incomplete suffix when non-final.
Decodes a complete source binary while discarding malformed units.
@spec decode_error_consumption(atom(), binary()) :: pos_integer()
Returns the source bytes consumed when recovering from a decode error.
Decodes directly to UTF-8.
Single-unit tables use the table engine's direct path. Other tables fall back to codepoints without changing errors or offsets.
Encodes codepoints using strict unrepresentable-character handling.
@spec encode_chunk(entry(), [integer()], boolean(), encode_policy()) :: {:ok, binary(), [integer()]} | tuple()
Encodes one target chunk and retains any incomplete codepoint prefix.
Encodes codepoints while discarding unrepresentable characters.
Encodes UTF-8 directly, falling back through codepoints when required.
If a representable UTF-8 prefix already contains an unrepresentable target character, that target error is returned before a later malformed UTF-8 suffix.
@spec encode_substitute(entry(), [integer()], (integer() -> [integer()])) :: {:ok, binary()} | tuple()
Encodes codepoints and invokes replacer for each unrepresentable character.
@spec encode_substitute_each( [integer()], ([integer()] -> {:ok, binary()} | tuple()), (integer() -> [integer()]) ) :: {:ok, binary()} | tuple()
Applies substitution one codepoint at a time using an arbitrary encoder.
This is useful for codecs whose encoder cannot be expressed as a table entry but follows the standard unrepresentable-character tuple contract.
@spec encode_substitute_transform( [integer()], ([integer()] -> {:ok, binary()} | tuple()), (integer() -> [ integer() ]) ) :: {:ok, binary()} | tuple()
Builds a substituted codepoint sequence, then passes it once to encoder.
Each original and replacement segment is first validated independently, so replacement failures retain the encoder's original error tuple.
Validates UTF-8 and passes decoded codepoints to encoder.
Target errors in a valid prefix take precedence over a later malformed source suffix.
Uses valid_encoder for valid UTF-8 and prefix_encoder only to establish
first-error ordering when the source is malformed.
@spec malformed_utf8(binary(), non_neg_integer()) :: tuple()
Returns the first malformed UTF-8 suffix and its absolute byte offset.
@spec provider_entry(atom()) :: provider_entry()
Builds an entry whose table application is selected by provider routing.
@spec table_entry(atom(), atom()) :: table_entry()
Builds an entry pinned to table_app.