npm package: @lppedd/kotlinx-charset
Description: Minimal support for charset encoding and decoding
Latest version: 0.2.1

<!--suppress HtmlDeprecatedAttribute -->
<h1 align="center">kotlinx-charset</h1>
<p align="center">Minimal charset support for Kotlin Multiplatform</p>
<div align="center">

[![maven central](https://img.shields.io/maven-central/v/com.lppedd.kotlinx-charset/core)](https://mvnrepository.com/artifact/com.lppedd.kotlinx-charset)
[![npm](https://img.shields.io/npm/v/%40lppedd%2Fkotlinx-charset?color=%23de1f1f&logo=npm)](https://www.npmjs.com/package/@lppedd/kotlinx-charset)
[![kotlin](https://img.shields.io/badge/kotlin-2.3.0-blue.svg?logo=kotlin)](https://kotlinlang.org)
[![build](https://img.shields.io/github/actions/workflow/status/lppedd/kotlinx-charset/build.yml.svg?branch=master)](https://github.com/lppedd/kotlinx-charset/actions/workflows/build.yml)
[![license](https://img.shields.io/github/license/lppedd/kotlinx-charset?color=F7F7F7)](./LICENSE)

</div>

### Changelog

See [CHANGELOG.md](./CHANGELOG.md).

### Supported Kotlin platforms

All Kotlin platforms are supported, except for Android Native.

### Design considerations

**kotlinx-charset** aims to be straightforward for existing JDK consumers.  
It replicates parts of the JDK's `Charset` API, albeit with more restrictions.

The core types you will work with are:

- `XCharset` - describes a character set
- `XCharsetDecoder` - decodes a byte sequence into characters
- `XCharsetEncoder` - encodes characters into a byte sequence
- `XCharsetRegistrar` - a registry and lookup service for obtaining `XCharset` instances

## core

The `core` module provides the foundational components for implementing
and registering new charsets.

```kotlin
// Create an empty charset registry
private val registrar = XCharsetRegistrar()

// Register a new charset
registrar.registerCharset(YourCharset())

// Retrieve and use a charset
val charset = registrar.getCharset("YourCharsetName")
val decoder = charset.newDecoder()
val encoder = charset.newEncoder()
```

## ebcdic

The `ebcdic` module adds support for:

```text
IBM037  IBM930   IBM1144
IBM273  IBM937   IBM1146
IBM278  IBM939   IBM1147
IBM277  IBM1047  IBM1390
IBM280  IBM1141  IBM1399
IBM285  IBM1142
IBM297  IBM1143
```

You can register supported EBCDIC charsets to your `XCharsetRegistrar`
via the `provideCharsets` function.

```kotlin
import com.lppedd.kotlinx.charset.ebcdic.provideCharsets as provideEbcdicCharsets

// Your shared charset registry
private val registrar = XCharsetRegistrar()

provideEbcdicCharsets(registrar)
```

## exported

The `exported` module allows JS consumers to decode bytes and encode strings,
using top-level functions exported from ECMAScript modules.

> [!TIP]  
> Avoid using this module when consuming `kotlinx-charset` from a Kotlin project

You can depend on the [@lppedd/kotlinx-charset][npm] npm package.  
For example, consuming the library from TypeScript would look like:

```ts
import { decode, encode, getCharset } from "@lppedd/kotlinx-charset";

function funsExample(bytes: Uint8Array): Uint8Array {
  const str = decode("ibm037", bytes);
  return encode("ibm037", str);
}

// Alternatively, you can interact with a charset instance directly.
// This allows setting or removing (by passing null) the replacement character.
function instanceExample(bytes: Uint8Array): Uint8Array {
  const charset = getCharset("ibm037");

  const decoder = charset.newDecoder();
  const str = decoder.decode(bytes);

  const encoder = charset.newEncoder();
  return encoder.encode(str);
}
```

Both the `decode` and `encode` functions will throw an `Error`
if the specified charset does not exist or if an error occurs
during data processing.

## License

[MIT License](./LICENSE) 2025-present [Edoardo Luppi][lppedd]

[npm]: https://www.npmjs.com/package/@lppedd/kotlinx-charset
[lppedd]: https://github.com/lppedd