@spec canonical_name(encoding()) :: {:ok, String.t()} | :error

Resolves an encoding name, alias, built-in ID, or registered codec module.

@spec convert(binary(), encoding(), encoding()) :: conversion_result()

Equivalent to convert/4 with default options.

@spec convert(binary(), encoding(), encoding(), conversion_options()) ::
  conversion_result()

Converts a complete encoded binary.

Invalid options and suffixes return typed request errors. Malformed source input returns Iconvex.Error. Destination handling follows GNU libiconv: ordinary unavailable characters error, while extended UCS values use U+FFFD when the destination family defines that fallback and can encode it. Discard, transliteration, and substitution options take precedence over the fallback. GNU suffixes such as //IGNORE, //NON_IDENTICAL_DISCARD, and //TRANSLIT may be appended to encoding names.

@spec convert!(binary(), encoding(), encoding()) :: binary()

Equivalent to convert!/4 with default options.

@spec convert!(binary(), encoding(), encoding(), conversion_options()) :: binary()

Converts a complete binary, raising for conversion or request errors.

@spec encodings() :: [String.t()]

Returns all currently registered canonical encoding names.

@spec feed(Iconvex.Converter.t(), binary()) ::
  {:ok, binary(), Iconvex.Converter.t()} | {:error, request_error()}

Adds a binary chunk in O(1) time.

Output is intentionally empty until finalization. Full buffering is the contract that makes chunked conversion exactly equivalent to convert/4 across every possible byte split.

@spec finish(Iconvex.Converter.t()) :: conversion_result()

Performs the buffered conversion and returns its final output.

Errors use byte offsets from the beginning of the complete stream. Because Elixir values are immutable, this compatibility function cannot mark the caller's converter finished; use finish_with_state/1 when lifecycle checks are required.

@spec finish_with_state(Iconvex.Converter.t()) ::
  {:ok, binary(), Iconvex.Converter.t()}
  | {:error, Iconvex.Error.t() | request_error()}

Finalizes a buffered converter and returns its terminal state.

@spec new(encoding(), encoding()) ::
  {:ok, Iconvex.Converter.t()} | {:error, request_error()}

Equivalent to new/3 with default options.

@spec new(encoding(), encoding(), conversion_options()) ::
  {:ok, Iconvex.Converter.t()} | {:error, request_error()}

Creates a buffered chunked converter.

Encoding entries and table-provider routing are resolved once, so a converter remains stable if an external codec or its provider is later unregistered, replaced, or stopped.

@spec register_codec(
  module(),
  keyword()
) :: :ok | {:error, term()}

Registers a codec implemented by an external library.

:canonical can replace the module's declared canonical name for this registration. This lets independent sources expose colliding codec names under source-qualified names without overriding a built-in. Module and option aliases remain active and subject to the normal conflict checks.

@spec register_codec_if_absent(
  module(),
  keyword()
) :: {:ok, registration_token() | :existing} | {:error, term()}

Atomically registers a codec only when that module is not already registered.

Returns {:ok, token} for a new registration or {:ok, :existing} without replacing caller-owned metadata. Pass a returned token to unregister_codec/2 during application shutdown. Registration replacement has one externally visible commit point, so concurrent lookups see either the complete old entry or the complete new entry.

@spec register_codec_owned(
  module(),
  keyword()
) :: {:ok, registration_token()} | {:error, term()}

Registers a codec and returns an ownership token for conditional cleanup.

This variant retains register_codec/2 replacement semantics. A library should normally prefer register_codec_if_absent/2 during application start. Registrations and their tokens survive a supervised registry-worker restart while the :iconvex application remains running.

@spec stream(Enumerable.t(), encoding(), encoding()) ::
  {:ok, Enumerable.t()} | {:error, request_error()}

Equivalent to stream/4 with default options.

@spec stream(Enumerable.t(), encoding(), encoding(), conversion_options()) ::
  {:ok, Enumerable.t()} | {:error, request_error()}

Creates a lazy, bounded-memory conversion stream.

Input enumerable must emit binaries. Output stream emits converted binaries as source chunks become stable. Conversion errors raise Iconvex.Error during enumeration because earlier output may already have been consumed.

Built-in stateful codecs carry designation, shift, Base64, and BOM state across chunks. External codecs opt in through the incremental callbacks in Iconvex.Codec; a missing callback returns {:streaming_unsupported, role, encoding} instead of silently buffering.

@spec stream!(Enumerable.t(), encoding(), encoding(), conversion_options()) ::
  Enumerable.t()

Equivalent to stream/4, returning the stream or raising for request errors.

@spec unregister_codec(module()) :: :ok | {:error, term()}

Removes a previously registered external codec.

@spec unregister_codec(module(), registration_token()) :: :ok | {:error, term()}

Removes a codec only when token owns its current registration.