kotlinx-io

Introduction to kotlinx-io

kotlinx-io is a versatile library designed for Kotlin programming that provides essential input and output (IO) operations across multiple platforms. It is built on the foundation of Okio, another popular IO library, though it introduces changes that break backward compatibility with Okio.

Core Features

The cornerstone of kotlinx-io is the Buffer. This is essentially a mutable sequence of bytes that operates somewhat like a queue. Users can either read data from the front (head) of the buffer or write data to the back (tail). It offers various functions to handle data of different built-in types and allows copying data between different Buffer instances. This feature is further enhanced by extension functions that facilitate data interaction with platform-specific types, depending on where the code runs (e.g., JVM, JS, Native).

A Buffer is organized as a linked list of segments, which is an efficient approach for managing memory. This segment-based structure helps minimize unnecessary memory allocations when expanding buffers or when data needs to be copied, by allowing buffers to share or delegate access to these segments.

In addition to the mutable Buffer, kotlinx-io offers an immutable byte sequence known as ByteString.

Moreover, kotlinx-io includes Source and Sink interfaces that represent generic data sources and destinations. This structure is pivotal for streamlining IO processes.

Experimental Features

kotlinx-io introduces experimental support for file system operations within the kotlinx.io.files package. This includes an interface FileSystem and a standard implementation titled SystemFileSystem. Through these interfaces, developers can execute fundamental file and directory operations using a class called Path.

Modules

kotlinx-io is divided into two primary modules:

• kotlinx-io-bytestring: Focuses solely on providing the ByteString functionality.
• kotlinx-io-core: Encompasses the main IO primitives (Buffer, Source, Sink), and filesystem operations, with a dependency on the kotlinx-io-bytestring module.

Integration

Using Gradle

To incorporate kotlinx-io into a project, ensure that mavenCentral() is included in the list of repositories. Dependencies should be added in your Gradle setup using the following syntax:

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.jetbrains.kotlinx:kotlinx-io-core:0.5.4")
}

For multiplatform projects, include it in the commonMain source set:

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation("org.jetbrains.kotlinx:kotlinx-io-core:0.5.4")
            }
        }
    }
}

Using Maven

To use kotlinx-io with Maven, insert the below snippet into your project's dependencies:

<dependency>
    <groupId>org.jetbrains.kotlinx</groupId>
    <artifactId>kotlinx-io-core-jvm</artifactId>
    <version>0.5.4</version>
</dependency>

Android Compatibility

Despite not being regularly tested on Android, kotlinx-io supports Android version 5.0 (API level 21) and above.

Contributing and Community

Potential contributors are encouraged to review the Contributing Guidelines. The project adheres to the JetBrains Open Source and Community Code of Conduct.

License

kotlinx-io is distributed under the Apache 2.0 License.

Acknowledgments

Considerable thanks go to everyone contributing to the project, with special acknowledgment to the developers behind Okio and to Jesse Wilson for his suggestions and involvement in adapting Okio for kotlinx-io's development.