Core API

Namespace

namespace iconv_lite

Batch character encoding conversion APIs for polycpp.

Since

1.0.0

Options and diagnostics

struct EncodeOptions

Options for encode().

Since

1.0.0

Public Members

std::optional<bool> addBOM

Whether to prepend a BOM for BOM-aware encodings.

When unset, utf16 and utf32 auto encoders add a BOM by default, matching iconv-lite. Other BOM-aware encodings only add a BOM when this is explicitly true.

Since

1.0.0

std::string defaultEncoding

Default endianness for auto encoders.

Currently used by utf32; accepted values include utf32le and utf32be. Invalid values fall back to iconv-lite’s default.

Since

1.0.0

struct DecodeOptions

Options for decode().

Since

1.0.0

Public Members

bool stripBOM = true

Strip an initial decoded U+FEFF from BOM-aware encodings.

Since

1.0.0

std::function<void()> onBOMStripped

Optional observer called when an initial BOM is actually stripped.

This models iconv-lite’s stripBOM callback form while keeping the C++ option that controls stripping as an explicit boolean.

Since

1.0.0

std::string defaultEncoding

Fallback endianness for UTF-16/UTF-32 auto detection.

Accepted values include utf16le, utf16be, utf32le, and utf32be. Invalid values fall back to iconv-lite’s default little-endian behavior.

Since

1.0.0

struct EncodingInfo

Resolved encoding metadata for diagnostics and tests.

Since

1.0.0

Public Members

std::string requested

Original label passed by the caller.

Since

1.0.0

std::string canonical

iconv-lite-style canonical label.

Since

1.0.0

std::string converter

Resolved upstream table name or local internal codec name.

Since

1.0.0

bool bomAware = false

True when BOM strip/prepend behavior applies.

Since

1.0.0

bool isInternal = false

True when handled by a local internal codec instead of generated SBCS/DBCS tables.

Since

1.0.0

struct Codec

Resolved codec descriptor returned by getCodec().

JavaScript iconv-lite exposes codec constructor objects through getCodec. This C++ companion exposes deterministic metadata plus factories for the stateful encoder and decoder objects that carry stream chunk-boundary state.

Since

1.0.0

Public Functions

inline bool bomAware() const noexcept

True when BOM strip/prepend wrappers apply.

Since

1.0.0

inline bool isInternal() const noexcept

True when this is a local internal codec instead of generated table data.

Since

1.0.0

Encoder encoder(const EncodeOptions &options = {}) const

Create a stateful encoder for this codec.

Since

1.0.0

Decoder decoder(const DecodeOptions &options = {}) const

Create a stateful decoder for this codec.

Since

1.0.0

Public Members

EncodingInfo info

Resolved metadata for this codec.

Since

1.0.0

class Encoder

Stateful low-level encoder, matching iconv-lite getEncoder().

write() may be called multiple times. end() flushes any pending bytes for encodings whose upstream encoders keep chunk-boundary state, such as base64, UTF-7-IMAP, GB18030/DBCS sequence state, and BOM prepending.

Since

1.0.0

Public Functions

Encoder(std::string_view encoding, const EncodeOptions &options = {})

Create a stateful encoder for an encoding label.

Since

1.0.0

Encoder(const Codec &codec, const EncodeOptions &options = {})

Create a stateful encoder from a resolved codec descriptor.

Since

1.0.0

Buffer write(std::string_view input)

Encode the next UTF-8 text chunk.

Since

1.0.0

Buffer end()

Flush pending encoder state.

Since

1.0.0

EncodingInfo info() const

Resolved encoding metadata for this encoder.

Since

1.0.0

class Decoder

Stateful low-level decoder, matching iconv-lite getDecoder().

write() may be called multiple times. end() flushes pending incomplete input according to iconv-lite behavior for DBCS, UTF-7, UTF-16, UTF-32, and BOM stripping.

Since

1.0.0

Public Functions

Decoder(std::string_view encoding, const DecodeOptions &options = {})

Create a stateful decoder for an encoding label.

Since

1.0.0

Decoder(const Codec &codec, const DecodeOptions &options = {})

Create a stateful decoder from a resolved codec descriptor.

Since

1.0.0

std::string write(const Buffer &input)

Decode the next byte chunk into UTF-8 text.

Since

1.0.0

std::string end()

Flush pending decoder state.

Since

1.0.0

EncodingInfo info() const

Resolved encoding metadata for this decoder.

Since

1.0.0

struct IconvStreamOptions

Stream construction options for iconv-lite transform streams.

Since

1.0.0

Public Members

EventContext *context = nullptr

Event context to bind the stream to; null uses polycpp’s default event loop.

Since

1.0.0

size_t highWaterMark = stream::kDefaultHighWaterMark

Read/write high-water mark in bytes.

Since

1.0.0

bool emitClose = true

Whether the stream emits close on destroy.

Since

1.0.0

bool autoDestroy = true

Whether the stream auto-destroys after completion.

Since

1.0.0

class EncodeStream : public stream::Transform

Transform stream that encodes UTF-8 text chunks into encoded bytes.

Since

1.0.0

Public Functions

EncodeStream(std::string_view encoding, const EncodeOptions &options = {}, const IconvStreamOptions &streamOptions = {})

Create an encoding transform stream for an encoding label.

Since

1.0.0

EncodeStream(Encoder encoder, const IconvStreamOptions &streamOptions = {})

Create an encoding transform stream from a stateful encoder.

Since

1.0.0

explicit EncodeStream(std::shared_ptr<detail::EncodeStreamImpl> impl)

Create an encoding transform stream from an implementation object.

Since

1.0.0

EncodeStream &collect(std::function<void(Error::Ptr, Buffer)> callback)

Collect emitted byte chunks and call the callback at end/error.

The callback receives a non-null error on failure, otherwise the concatenated output buffer.

Since

1.0.0

class DecodeStream : public stream::Transform

Transform stream that decodes encoded byte chunks into UTF-8 text.

The readable side emits UTF-8 buffers because polycpp streams are byte oriented; collect() exposes the decoded text directly.

Since

1.0.0

Public Functions

DecodeStream(std::string_view encoding, const DecodeOptions &options = {}, const IconvStreamOptions &streamOptions = {})

Create a decoding transform stream for an encoding label.

Since

1.0.0

DecodeStream(Decoder decoder, const IconvStreamOptions &streamOptions = {})

Create a decoding transform stream from a stateful decoder.

Since

1.0.0

explicit DecodeStream(std::shared_ptr<detail::DecodeStreamImpl> impl)

Create a decoding transform stream from an implementation object.

Since

1.0.0

DecodeStream &collect(std::function<void(Error::Ptr, std::string)> callback)

Collect emitted UTF-8 text chunks and call the callback at end/error.

Since

1.0.0

Functions

std::string polycpp::iconv_lite::canonicalizeEncoding(std::string_view encoding)

Canonicalize an encoding label the same way iconv-lite does.

The label is lowercased, a trailing :YYYY suffix is removed, and all non-alphanumeric characters are stripped.

Since

1.0.0

bool polycpp::iconv_lite::encodingExists(std::string_view encoding) noexcept

Return true when an encoding label can be resolved by this port.

Since

1.0.0

EncodingInfo polycpp::iconv_lite::inspectEncoding(std::string_view encoding)

Resolve an encoding label to diagnostic metadata.

Since

1.0.0

Throws:

polycpp::TypeError – if the label is not supported.

Codec polycpp::iconv_lite::getCodec(std::string_view encoding)

Return the resolved codec descriptor for an encoding label.

Since

1.0.0

Throws:

polycpp::TypeError – if the label is not supported.

Encoder polycpp::iconv_lite::getEncoder(std::string_view encoding, const EncodeOptions &options = {})

Create a stateful low-level encoder for an encoding label.

Since

1.0.0

Decoder polycpp::iconv_lite::getDecoder(std::string_view encoding, const DecodeOptions &options = {})

Create a stateful low-level decoder for an encoding label.

Since

1.0.0

std::string polycpp::iconv_lite::defaultCharUnicode()

Current Unicode replacement string used by table decoders.

Since

1.0.0

void polycpp::iconv_lite::setDefaultCharUnicode(std::string value)

Set the Unicode replacement string used by future table decoders.

Since

1.0.0

std::string polycpp::iconv_lite::defaultCharSingleByte()

Current single-byte replacement string used by table encoders.

Since

1.0.0

void polycpp::iconv_lite::setDefaultCharSingleByte(std::string value)

Set the single-byte replacement string used by future table encoders.

Since

1.0.0

Buffer polycpp::iconv_lite::encode(std::string_view input, std::string_view encoding, const EncodeOptions &options = {})

Encode UTF-8 text into a byte buffer using the requested encoding.

Since

1.0.0

Parameters:

• input – UTF-8 text.

• encoding – iconv-lite-style encoding label.

• options – encode options.

Throws:

polycpp::TypeError – for unsupported labels or conversion failures.

Returns:

Encoded bytes as polycpp::buffer::Buffer.

std::string polycpp::iconv_lite::decode(const Buffer &input, std::string_view encoding, const DecodeOptions &options = {})

Decode bytes in the requested encoding into UTF-8 text.

Since

1.0.0

Parameters:

• input – Encoded bytes.

• encoding – iconv-lite-style encoding label.

• options – decode options.

Throws:

polycpp::TypeError – for unsupported labels or conversion failures.

Returns:

UTF-8 text.

EncodeStream polycpp::iconv_lite::encodeStream(std::string_view encoding, const EncodeOptions &options = {}, const IconvStreamOptions &streamOptions = {})

Create a transform stream that encodes UTF-8 text chunks.

Since

1.0.0

DecodeStream polycpp::iconv_lite::decodeStream(std::string_view encoding, const DecodeOptions &options = {}, const IconvStreamOptions &streamOptions = {})

Create a transform stream that decodes byte chunks into UTF-8 text.

Since

1.0.0