Home › encoding/error

Module encoding/error

encoding/error
Stability: unstable — this type is ONE enum doing three codecs' jobs, and whether it stays that way is the open question. `OddLength` can only come from hex, `InvalidLength` and `InvalidLastSymbol` only from base64, `UnpairedSurrogate` only from UTF-16 — so every exhaustive `match` on a `hex_decode` failure has to spell out three arms hex can never produce. Rust splits them (`hex::FromHexError`, `base64::DecodeError`, `char::DecodeUtf16Error`) for exactly that reason, and splitting here is breaking for every caller that names the type. The mixed unit is the other half of the same problem: `pos` is a byte offset in four variants and a CODE-UNIT index in `UnpairedSurrogate`, because that is what each input is measured in. `pos()` therefore returns a number whose unit depends on which codec produced it — survivable while the caller knows what it called, wrong the moment an error is passed along. Per-codec types would give each one an unambiguous offset. Nothing here has shipped: the `pos` fields on every position-bearing variant, and `UnpairedSurrogate` replacing three `InvalidChar(0)` reports, both landed 2026-09-09 (#526). — stable modules only change additively; this one may still change.

Shared error type for the std/encoding codecs.

hex, base64 and utf16 all report decoding failures with this type.

Example

{ EncodingError } :: import "std/encoding/error";

exn.throw(dyn(EncodingError.OddLength(len : usize(5))));

Stability

unstable — this type is ONE enum doing three codecs' jobs, and whether it stays that way is the open question. OddLength can only come from hex, InvalidLength and InvalidLastSymbol only from base64, UnpairedSurrogate only from UTF-16 — so every exhaustive match on a hex_decode failure has to spell out three arms hex can never produce. Rust splits them (hex::FromHexError, base64::DecodeError, char::DecodeUtf16Error) for exactly that reason, and splitting here is breaking for every caller that names the type.

The mixed unit is the other half of the same problem: pos is a byte offset in four variants and a CODE-UNIT index in UnpairedSurrogate, because that is what each input is measured in. pos() therefore returns a number whose unit depends on which codec produced it — survivable while the caller knows what it called, wrong the moment an error is passed along. Per-codec types would give each one an unambiguous offset.

Nothing here has shipped: the pos fields on every position-bearing variant, and UnpairedSurrogate replacing three InvalidChar(0) reports, both landed 2026-09-09 (#526).

Types

EncodingError enum
EncodingError

Encoding/decoding error type.

Every variant that can name a position carries pos, the OFFSET into the input where the fault is — in bytes for hex and base64, and in CODE UNITS for UnpairedSurrogate, because that is what each input is measured in. Without it a caller decoding a 4 KiB blob learns only that one byte somewhere was wrong, which is not enough to report, highlight, or skip past — the character alone does not say WHICH occurrence of it (Rust's base64::DecodeError carries the same offset for exactly this reason).

Variants

VariantFieldsDescription
InvalidCharch: u8, pos: usize

Invalid character encountered during decoding, and where it was.

OddLengthlen: usize

Input string has odd length (hex requires even length); len is the length seen, so the caller need not re-measure.

InvalidLengthlen: usize

base64 input whose length is 1 mod 4 (after padding): one sextet cannot encode a byte, so no encoder produces it.

InvalidLastSymbolch: u8, pos: usize

base64 input whose final symbol carries bits that no byte can occupy (a 2-symbol group must end in one of AQgw, a 3-symbol group in a symbol whose low two bits are zero); Rust's InvalidLastSymbol.

UnpairedSurrogatecode_unit: u16, pos: usize

A UTF-16 surrogate with no partner: a high surrogate at the end of the input or followed by a non-low unit, or a bare low surrogate. pos is an index in CODE UNITS, not bytes, because that is what the input is.

The field is code_unit rather than unit because a field named after a builtin type breaks the unhygienic derived body — see issues/derive-body-field-name-collides-with-a-builtin-type.md.

A separate variant because InvalidChar cannot carry it: a UTF-16 code unit is 16 bits and ch is a u8, so the surrogate decoders were all reporting InvalidChar(0) — an offending character of NUL, which is not what was wrong and told the caller nothing.

Trait Implementations

Error Format
impl(generic(T : Type), where(T <: ToString), T : (ToString))
impl(generic(T : Type), where(T <: ToString), T : (ToString), Format)
format : fn(self : Self, spec : str) -> String

Render self under spec. An unrecognised spec degrades to the plain to_string() rendering rather than failing.

Parameters

NameTypeNotes
selfSelf
specstr

Returns: String

impl(EncodingError, ...)
pos : (EncodingError) fn(self : EncodingError) -> Option(usize)

The offset the fault was found at, for the variants that have one. .None for a whole-input length complaint, which has no single position.

The UNIT depends on which codec produced the error — bytes from hex and base64, code units from utf16 — so read it against the input you handed in, not as a byte offset unconditionally.

Parameters

NameTypeNotes
selfEncodingError

Returns: Option(usize)

Methods
to_string : (EncodingError) fn(self : EncodingError) -> String

Parameters

NameTypeNotes
selfEncodingError

Returns: String

source : (EncodingError) fn(self : EncodingError) -> Option(dyn( + ToString))

The error that caused this one, or .None at the root of the chain.

Rust's Error::source. Defaulted to .None, so an error with nothing underneath it implements the trait by saying only what it is; a wrapper overrides it to hand back what it wrapped. Walking the chain to the root cause is not expressible yet — the returned Dyn loses the Error trait on an erased receiver, so a caller can print one link but cannot follow it (#521, issues/self-trait-in-a-return-type-loses-the-trait-on-an-erased-receiver.md).

Parameters

NameTypeNotes
selfEncodingError

Returns: Option(dyn( + ToString))