https://github.com/lppedd/kotlinx-charset
Minimal charset support for KMP
https://github.com/lppedd/kotlinx-charset
Last synced: 3 months ago
JSON representation
Minimal charset support for KMP
- Host: GitHub
- URL: https://github.com/lppedd/kotlinx-charset
- Owner: lppedd
- License: mit
- Created: 2025-05-06T17:01:25.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-12-21T14:51:23.000Z (7 months ago)
- Last Synced: 2025-12-22T19:29:33.811Z (7 months ago)
- Language: Kotlin
- Homepage:
- Size: 830 KB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
kotlinx-charset
Minimal charset support for Kotlin Multiplatform
[](https://mvnrepository.com/artifact/com.lppedd.kotlinx-charset)
[](https://www.npmjs.com/package/@lppedd/kotlinx-charset)
[](https://kotlinlang.org)
[](https://github.com/lppedd/kotlinx-charset/actions/workflows/build.yml)
[](./LICENSE)
### 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