https://github.com/Kotlin/kotlinx-io
Kotlin multiplatform I/O library
https://github.com/Kotlin/kotlinx-io
io kotlin kotlinx
Last synced: about 1 month ago
JSON representation
Kotlin multiplatform I/O library
- Host: GitHub
- URL: https://github.com/Kotlin/kotlinx-io
- Owner: Kotlin
- License: apache-2.0
- Created: 2017-10-04T19:31:15.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-01-08T23:08:57.000Z (3 months ago)
- Last Synced: 2025-01-25T09:05:28.913Z (3 months ago)
- Topics: io, kotlin, kotlinx
- Language: Kotlin
- Homepage:
- Size: 4.83 MB
- Stars: 1,337
- Watchers: 56
- Forks: 60
- Open Issues: 80
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG-0.1.X.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-kotlin-multiplatform - kotlinx-io
- kmp-awesome - kotlinx-io - Kotlin multiplatform I/O library (Libraries / 📁 File)
README
# kotlinx-io
[](https://kotlinlang.org/docs/components-stability.html)
[](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
[](LICENSE)
[](https://central.sonatype.com/artifact/org.jetbrains.kotlinx/kotlinx-io-core/)
[](http://kotlinlang.org)
[](https://teamcity.jetbrains.com/viewType.html?buildTypeId=KotlinTools_KotlinxIo_BuildAggregated&guest=1)
[](https://kotlin.github.io/kotlinx-io/)
A multiplatform Kotlin library providing basic IO primitives. `kotlinx-io` is based on [Okio](https://github.com/square/okio) but does not preserve backward compatibility with it.
## Overview
**kotlinx-io** is built around `Buffer` - a mutable sequence of bytes.
`Buffer` works like a queue, allowing to read data from its head or to write data to its tail.
`Buffer` provides functions to read and write data of different built-in types, and to copy data to or from other `Buffer`s.
Depending on the target platform, extension functions allowing data exchange with platform-specific types are also available.
A `Buffer` consists of segments organized as a linked list: segments allow reducing memory allocations during the buffer's expansion and copy,
with the latter achieved by delegating or sharing the ownership over the underlying buffer's segments with other buffers.
**kotlinx-io** provides interfaces representing data sources and destinations - `Source` and `Sink`,
and in addition to the *mutable* `Buffer` the library also provides an *immutable* sequence of bytes - `ByteString`.
An experimental filesystem support is shipped under the `kotlinx.io.files` package,
which includes the `FileSystem` interface and its default implementation - `SystemFileSystem`.
`FileSystem` provides basic operations for working with files and directories, which are represented by yet another class under the same package - `Path`.
There are several `kotlinx-io` modules:
- [kotlinx-io-bytestring](./bytestring) - provides `ByteString`.
- [kotlinx-io-core](./core) - provides IO primitives (`Buffer`, `Source`, `Sink`), filesystems support, depends on `kotlinx-io-bytestring`.
- [kotlinx-io-okio](./integration/okio) - bridges `kotlinx-io` and `Okio` `ByteString`, `kotlinx.io.RawSource` and `okio.Source`, `kotlinx.io.RawSink` and `okio.Sink`.
## Using in your projects
> Note that the library is experimental, and the API is subject to change.
### Gradle
Make sure that you have `mavenCentral()` in the list of repositories:
```kotlin
repositories {
mavenCentral()
}
```
Add the library to dependencies:
```kotlin
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-io-core:0.7.0")
}
```
In multiplatform projects, add a dependency to the `commonMain` source set dependencies:
```kotlin
kotlin {
sourceSets {
commonMain {
dependencies {
implementation("org.jetbrains.kotlinx:kotlinx-io-core:0.7.0")
}
}
}
}
```
### Maven
Add the library to dependencies:
```xml
org.jetbrains.kotlinx
kotlinx-io-core-jvm
0.7.0
```
### JPMS support
On JVM, `kotlinx-io` supports Java Modules:
- `kotlinx-io-bytestring` library provides `kotlinx.io.bytestring` module;
- `kotlinx-io-core` library provides `kotlinx.io.core` module.
- `kotlinx-io-okio` library provides `kotlinx.io.okio` module.
Read [this](https://kotlinlang.org/docs/gradle-configure-project.html#configure-with-java-modules-jpms-enabled) article
for details on how to configure a Gradle project to utilize JPMS.
### Android
`kotlinx-io` is not tested on Android on a regular basis,
but the library is compatible with Android 5.0+ (API level 21+).
## Contributing
Read the [Contributing Guidelines](CONTRIBUTING.md).
## Code of Conduct
This project and the corresponding community are governed by the [JetBrains Open Source and Community Code of Conduct](https://confluence.jetbrains.com/display/ALL/JetBrains+Open+Source+and+Community+Code+of+Conduct). Please make sure you read it.
## License
kotlinx-io is licensed under the [Apache 2.0 License](LICENSE).
## Credits
Thanks to everyone involved in the project.
An honorable mention goes to the developers of [Okio](https://square.github.io/okio/)
that served as the foundation for `kotlinx-io` and to [Jesse Wilson](https://github.com/swankjesse),
for the help with `Okio` adaption, his suggestions, assistance and guidance with `kotlinx-io` development.