A trimmed-down API (#136)

What changed compared to the previous API version:
- Removed byte strings and ByteString related APIs
- Moved some methods that were previously implemented as member functions to extensions, provided basic implementation
- Get rid of hash functions and select API
- Get rid of unsafe cursors
- Updated documentation
- Changed Buffer::toString behavior
- Improved test coverage
- Changed naming of read/write methods, explicitly documented exception policies
- Added extensions for unsigned types
- Made code-point-related extensions internal
- On JVM, Buffer no longer implements NIO interfaces
- Buffer has default equals/hashCode

A few new build features were added:
- Enable Dokka
- Enable Kover for core-io
- Enabled explicit API mode

Author: fzhinkin

benchmarks/src/commonMain/kotlin/BufferOps.kt

@@ -97,18 +97,21 @@ open class DecimalLongBenchmark: BufferRWBenchmarkBase() {
     var value = 0L
 
     override fun padding(): ByteArray {
-        val tmpBuffer = Buffer()
-        while (tmpBuffer.size < minGap) {
-            // use space as a delimiter between consecutive decimal values
-            tmpBuffer.writeDecimalLong(value).writeByte(' '.code)
+        return with (Buffer()) {
+            while (size < minGap) {
+                writeDecimalLong(value)
+                // use space as a delimiter between consecutive decimal values
+                writeByte(' '.code.toByte())
+            }
+            readByteArray()
         }
-        return tmpBuffer.readByteArray()
     }
 
     @Benchmark
     fun benchmark(): Long {
         // use space as a delimiter between consecutive decimal values
-        buffer.writeDecimalLong(value).writeByte(' '.code)
+        buffer.writeDecimalLong(value)
+        buffer.writeByte(' '.code.toByte())
         val l = buffer.readDecimalLong()
         buffer.readByte() // consume the delimiter
         return l
@@ -120,45 +123,25 @@ open class HexadecimalLongBenchmark: BufferRWBenchmarkBase() {
     var value = 0L
 
     override fun padding(): ByteArray {
-        val tmpBuffer = Buffer()
-        while (tmpBuffer.size < minGap) {
-            tmpBuffer.writeHexadecimalUnsignedLong(value).writeByte(' '.code)
+        return with(Buffer()) {
+            while (size < minGap) {
+                writeHexadecimalUnsignedLong(value)
+                writeByte(' '.code.toByte())
+            }
+            readByteArray()
         }
-        return tmpBuffer.readByteArray()
     }
 
     @Benchmark
     fun benchmark(): Long {
-        buffer.writeHexadecimalUnsignedLong(value).writeByte(' '.code)
+        buffer.writeHexadecimalUnsignedLong(value)
+        buffer.writeByte(' '.code.toByte())
         val l = buffer.readHexadecimalUnsignedLong()
         buffer.readByte()
         return l
     }
 }
 
-open class Utf8CodePointBenchmark: BufferRWBenchmarkBase() {
-    @Param("1", "2", "3")
-    var bytes: Int = 0
-
-    private var codePoint: Int = 0
-
-    @Setup
-    fun setupCodePoints() {
-        codePoint = when (bytes) {
-            1 -> 'a'.code
-            2 -> 'ɐ'.code
-            3 -> 'ა'.code
-            else -> throw IllegalArgumentException()
-        }
-    }
-
-    @Benchmark
-    fun benchmark(): Int {
-        buffer.writeUtf8CodePoint(codePoint)
-        return buffer.readUtf8CodePoint()
-    }
-}
-
 // This benchmark is based on Okio benchmark:
 // https://raw.githubusercontent.com/square/okio/master/okio/jvm/jmh/src/jmh/java/com/squareup/okio/benchmarks/BufferUtf8Benchmark.java
 open class Utf8StringBenchmark: BufferRWBenchmarkBase() {
@@ -211,8 +194,9 @@ open class Utf8StringBenchmark: BufferRWBenchmarkBase() {
 
     override fun padding(): ByteArray {
         val baseString = constructString()
-        if (baseString.utf8Size() >= minGap) {
-            return baseString.encodeToByteArray()
+        val baseStringByteArray = baseString.encodeToByteArray()
+        if (baseStringByteArray.size >= minGap) {
+            return baseStringByteArray
         }
         val builder = StringBuilder((minGap * 1.5).toInt())
         while (builder.length < minGap) {
@@ -317,7 +301,11 @@ open class IndexOfBenchmark {
         if (valueOffset >= 0) array[valueOffset] = VALUE_TO_FIND
 
         val padding = ByteArray(paddingSize)
-        buffer.write(padding).write(array).skip(paddingSize.toLong())
+        with(buffer) {
+            write(padding)
+            write(array)
+            skip(paddingSize.toLong())
+        }
     }
 
     @Benchmark
@@ -358,7 +346,7 @@ open class BufferReadWriteByteArray: BufferRWBenchmarkBase() {
     @Benchmark
     fun benchmark(blackhole: Blackhole) {
         buffer.write(inputArray)
-        buffer.readFully(outputArray)
+        buffer.readTo(outputArray)
         blackhole.consume(outputArray)
     }
 }
@@ -377,6 +365,6 @@ open class BufferReadNewByteArray: BufferRWBenchmarkBase() {
     @Benchmark
     fun benchmark(): ByteArray {
         buffer.write(inputArray)
-        return buffer.readByteArray(size.toLong())
+        return buffer.readByteArray(size)
     }
 }

benchmarks/src/jvmMain/kotlin/ByteBufferBenchmarks.kt

@@ -5,10 +5,13 @@
 
 package kotlinx.io.benchmarks
 
+import kotlinx.benchmark.Benchmark
+import kotlinx.benchmark.Param
+import kotlinx.benchmark.Setup
+import kotlinx.io.readAtMostTo
+import kotlinx.io.write
 import java.nio.ByteBuffer
 
-import kotlinx.benchmark.*
-
 open class ByteBufferReadWrite: BufferRWBenchmarkBase() {
     private var inputBuffer = ByteBuffer.allocate(0)
     private var outputBuffer = ByteBuffer.allocate(0)
@@ -28,7 +31,7 @@ open class ByteBufferReadWrite: BufferRWBenchmarkBase() {
         inputBuffer.rewind()
         outputBuffer.clear()
         buffer.write(inputBuffer)
-        while (buffer.read(outputBuffer) > 0) {
+        while (buffer.readAtMostTo(outputBuffer) > 0) {
             // do nothing
         }
         return outputBuffer

benchmarks/src/jvmMain/kotlin/SegmentPoolBenchmarkMT.kt

@@ -5,15 +5,16 @@
 
 package kotlinx.io.benchmarks
 
-import kotlinx.io.*
 import kotlinx.benchmark.*
+import kotlinx.io.*
 import org.openjdk.jmh.annotations.Group
 import org.openjdk.jmh.annotations.GroupThreads
 
 @State(Scope.Benchmark)
 open class SegmentPoolBenchmarkMT {
     private fun testCycle(): Buffer {
-        val buffer = Buffer().writeByte(0)
+        val buffer = Buffer()
+        buffer.writeByte(0)
         buffer.clear()
         return buffer
     }

benchmarks/src/jvmMain/kotlin/StreamBenchmarks.kt

@@ -5,10 +5,16 @@
 
 package kotlinx.io.benchmarks
 
-import kotlinx.benchmark.*
+import kotlinx.benchmark.Benchmark
+import kotlinx.benchmark.Blackhole
+import kotlinx.benchmark.Param
+import kotlinx.benchmark.Setup
+import kotlinx.io.asInputStream
+import kotlinx.io.asOutputStream
+import kotlinx.io.readTo
 
 open class InputStreamByteRead: BufferRWBenchmarkBase() {
-   private val stream = buffer.inputStream()
+   private val stream = buffer.asInputStream()
 
     @Benchmark
     fun benchmark(): Int {
@@ -18,7 +24,7 @@ open class InputStreamByteRead: BufferRWBenchmarkBase() {
 }
 
 open class OutputStreamByteWrite: BufferRWBenchmarkBase() {
-    private val stream = buffer.outputStream()
+    private val stream = buffer.asOutputStream()
 
     @Benchmark
     fun benchmark(): Byte {
@@ -42,7 +48,7 @@ abstract class StreamByteArrayBenchmarkBase: BufferRWBenchmarkBase() {
 }
 
 open class InputStreamByteArrayRead: StreamByteArrayBenchmarkBase() {
-    private val stream = buffer.inputStream()
+    private val stream = buffer.asInputStream()
 
     @Benchmark
     fun benchmark(blackhole: Blackhole) {
@@ -56,12 +62,12 @@ open class InputStreamByteArrayRead: StreamByteArrayBenchmarkBase() {
 }
 
 open class OutputStreamByteArrayWrite: StreamByteArrayBenchmarkBase() {
-    private val stream = buffer.outputStream()
+    private val stream = buffer.asOutputStream()
 
     @Benchmark
     fun benchmark(blackhole: Blackhole) {
         stream.write(outputArray)
-        buffer.readFully(inputArray)
+        buffer.readTo(inputArray)
         blackhole.consume(inputArray)
     }
 }

build.gradle.kts

@@ -3,10 +3,12 @@
  * Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
  */
 
-import org.jetbrains.kotlin.gradle.tasks.*
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+import org.jetbrains.kotlin.gradle.tasks.KotlinNativeCompile
 
 plugins {
-    id("org.jetbrains.kotlinx.binary-compatibility-validator") version "0.11.1"
+    id("org.jetbrains.kotlinx.binary-compatibility-validator") version "0.13.2"
+    id("org.jetbrains.dokka") version "1.8.20"
     `maven-publish`
     signing
 }
@@ -33,6 +35,10 @@ apply(plugin = "maven-publish")
 apply(plugin = "signing")
 
 subprojects {
+    if (name.contains("benchmark")) {
+        return@subprojects
+    }
+
     repositories {
         mavenCentral()
     }
@@ -58,6 +64,13 @@ subprojects {
     tasks.withType<KotlinCompile>().configureEach {
         kotlinOptions {
             jvmTarget = JavaVersion.VERSION_1_8.toString()
+            allWarningsAsErrors = true
+            freeCompilerArgs += "-Xjvm-default=all"
+        }
+    }
+    tasks.withType<KotlinNativeCompile>().configureEach {
+        kotlinOptions {
+            allWarningsAsErrors = true
         }
     }
 }

buildSrc/src/main/kotlin/Platforms.kt

@@ -17,9 +17,14 @@ fun KotlinMultiplatformExtension.configureNativePlatforms() {
     tvosSimulatorArm64()
     watchosArm32()
     watchosArm64()
-    watchosX86()
     watchosX64()
     watchosSimulatorArm64()
+    watchosDeviceArm64()
+    linuxArm64()
+    androidNativeArm32()
+    androidNativeArm64()
+        androidNativeX64()
+    androidNativeX86()
     // Required to generate tests tasks: https://youtrack.jetbrains.com/issue/KT-26547
     linuxX64()
     macosX64()
@@ -38,20 +43,28 @@ private val appleTargets = listOf(
     "tvosSimulatorArm64",
     "watchosArm32",
     "watchosArm64",
-    "watchosX86",
     "watchosX64",
-    "watchosSimulatorArm64"
+    "watchosSimulatorArm64",
+    "watchosDeviceArm64"
 )
 
 private val mingwTargets = listOf(
     "mingwX64"
 )
 
 private val linuxTargets = listOf(
-    "linuxX64"
+    "linuxX64",
+    "linuxArm64"
 )
 
-val nativeTargets = appleTargets + linuxTargets + mingwTargets
+private val androidTargets = listOf(
+    "androidNativeArm32",
+    "androidNativeArm64",
+    "androidNativeX64",
+    "androidNativeX86"
+)
+
+val nativeTargets = appleTargets + linuxTargets + mingwTargets + androidTargets
 
 /**
  * Creates a source set for a directory that isn't already a built-in platform. Use this to create

core/Module.md

@@ -0,0 +1,84 @@
+# Module kotlinx-io-core
+
+The module provides core multiplatform IO primitives and integrates it with platform-specific APIs.
+
+`kotlinx-io core` aims to provide a concise but powerful API along with efficient implementation.
+
+The main interfaces for the IO interaction are [kotlinx.io.Source] and [kotlinx.io.Sink] providing buffered read and 
+write operations for integer types, byte arrays, and other sources and sinks. There are also extension functions
+bringing support for strings and other types. 
+Implementations of these interfaces are built on top of [kotlinx.io.Buffer], [kotlinx.io.RawSource],
+and [kotlinx.io.RawSink].
+
+A central part of the library, [kotlinx.io.Buffer], is a container optimized to reduce memory allocations and to avoid
+data copying when possible.
+
+[kotlinx.io.RawSource] and [kotlinx.io.RawSink] are interfaces aimed for integration with anything that can provide 
+or receive data: network interfaces, files, etc. The module provides integration with some platform-specific IO APIs,
+but if something not yet supported by the library needs to be integrated, then these interfaces are exactly what should 
+be implemented for that.
+
+Example below shows how to manually serialize an object to [BSON](https://bsonspec.org/spec.html) 
+and then back to an object using `kotlinx.io`. Please note that the example aimed to show `kotlinx-io` API in action,
+rather than to provide a robust BSON-serialization.
+```kotlin
+data class Message(val timestamp: Long, val text: String) {
+    companion object
+}
+
+fun Message.toBson(sink: Sink) {
+    val buffer = Buffer()
+    with (buffer) {
+        writeByte(0x9)                          // UTC-timestamp field
+        writeUtf8("timestamp")                  // field name
+        writeByte(0)
+        writeLongLe(timestamp)                  // field value
+        writeByte(0x2)                          // string field
+        writeUtf8("text")                       // field name
+        writeByte(0)
+        writeIntLe(text.utf8Size().toInt() + 1) // field value: length followed by the string
+        writeUtf8(text)
+        writeByte(0)
+        writeByte(0)                            // end of BSON document
+    }
+
+    // Write document length and then its body
+    sink.writeIntLe(buffer.size.toInt() + 4)
+    buffer.transferTo(sink)
+    sink.flush()
+}
+
+fun Message.Companion.fromBson(source: Source): Message {
+    source.require(4)                                    // check if the source contains length
+    val length = source.readIntLe() - 4L
+    source.require(length)                               // check if the source contains the whole message
+
+    fun readFieldName(source: Source): String {
+        val delimiterOffset = source.indexOf(0)          // find offset of the 0-byte terminating the name
+        check(delimiterOffset >= 0)                      // indexOf return -1 if value not found
+        val fieldName = source.readUtf8(delimiterOffset) // read the string until terminator
+        source.skip(1)                                   // skip the terminator
+        return fieldName
+    }
+
+    // for simplicity, let's assume that the order of fields matches serialization order
+    var tag = source.readByte().toInt()                // read the field type
+    check(tag == 0x9 && readFieldName(source) == "timestamp")
+    val timestamp = source.readLongLe()                // read long value
+    tag = source.readByte().toInt()
+    check(tag == 0x2 && readFieldName(source) == "text")
+    val textLen = source.readIntLe() - 1L              // read string length (it includes the terminator)
+    val text = source.readUtf8(textLen)                // read value
+    source.skip(1)                                     // skip terminator
+    source.skip(1)                                     // skip end of the document
+    return Message(timestamp, text)
+}
+```
+
+# Package kotlinx.io
+
+Core IO primitives.
+
+# Package kotlinx.io.files
+
+Basic API for working with files.