text_decoder

Decode byte sequences into text in a specified character encoding, optionally retaining state across multi-byte boundaries. Pass a one-shot input through decode for stateless decoding. For default UTF-8 decoding, gleam/bit_array.to_string is sufficient.

Types

Builder

opaque </>

The configuration for a TextDecoder.

pub opaque type Builder

TextDecoder

</>

Decodes a stream of bytes into text using a specified character encoding.

See TextDecoder on MDN.

pub type TextDecoder

Values

build

</>

pub fn build(
  builder: Builder,
) -> Result(TextDecoder, encoding.DecoderError)

Constructs a TextDecoder from the configured Builder. Returns UnsupportedEncoding if the label isn’t an encoding the runtime recognizes.

decode

</>

pub fn decode(
  input: BitArray,
  with builder: Builder,
) -> Result(String, encoding.DecoderError)

Decodes input using the given builder configuration in a single shot (no streaming state retained). Returns UnsupportedEncoding if the builder’s label isn’t an encoding the runtime recognizes, or MalformedInput if the builder is fatal and decoding encounters bytes that don’t form a valid sequence. For default UTF-8 decoding, use gleam/bit_array.to_string.

decode_chunk

</>

pub fn decode_chunk(
  decoder: TextDecoder,
  of input: BitArray,
) -> Result(String, encoding.DecoderError)

Decodes input, keeping state for multi-byte sequences that span chunks. Returns MalformedInput if the decoder is fatal and input contains bytes that don’t form a valid sequence. Equivalent to JavaScript’s decoder.decode(input, { stream: true }).

encoding

</>

pub fn encoding(decoder: TextDecoder) -> String

The decoder’s resolved encoding name. A label like "sjis" resolves to its canonical name "shift_jis".

flush

</>

pub fn flush(
  decoder: TextDecoder,
) -> Result(String, encoding.DecoderError)

Emits any remaining bytes buffered from prior decode_chunk calls. Returns MalformedInput if the decoder is fatal and an incomplete multi-byte sequence was left in the buffer. Equivalent to JavaScript’s decoder.decode().

is_fatal

</>

pub fn is_fatal(decoder: TextDecoder) -> Bool

Whether decoding malformed data returns an error instead of substituting it with a replacement character. Equivalent to JavaScript’s decoder.fatal.

is_ignore_bom

</>

pub fn is_ignore_bom(decoder: TextDecoder) -> Bool

Whether the byte order mark is skipped over rather than included in the decoded output. Equivalent to JavaScript’s decoder.ignoreBOM.

new

</>

pub fn new(label: String) -> Builder

Creates a new Builder for the given encoding label. Both flags default to False.

with_fatal

</>

pub fn with_fatal(builder: Builder, fatal: Bool) -> Builder

Sets whether decoding malformed data returns an error instead of substituting it with a replacement character.

with_ignore_bom

</>

pub fn with_ignore_bom(
  builder: Builder,
  ignore_bom: Bool,
) -> Builder

Sets whether the byte order mark is included in the decoded output (False) or skipped over (True).