Introduce peekCharUtf8

Author: Sergey Mashkov

binary-compatibility-validator/reference-public-api/kotlinx-io-jvm.txt

@@ -304,6 +304,7 @@ public final class kotlinx/io/core/InputKt {
 	public static final fun discard (Lkotlinx/io/core/Input;)J
 	public static final fun discardExact (Lkotlinx/io/core/Input;I)V
 	public static final fun discardExact (Lkotlinx/io/core/Input;J)V
+	public static final fun peekCharUtf8 (Lkotlinx/io/core/Input;)C
 	public static final fun readAvailable (Lkotlinx/io/core/Input;Lkotlinx/io/core/IoBuffer;I)I
 	public static final fun readAvailable (Lkotlinx/io/core/Input;[BII)I
 	public static final fun readAvailable (Lkotlinx/io/core/Input;[DII)I

src/main/kotlin/kotlinx/io/core/Input.kt

@@ -221,3 +221,30 @@ inline fun Input.takeWhileSize(initialSize: Int = 1, block: (IoBuffer) -> Int) {
     }
 }
 
+@ExperimentalIoApi
+fun Input.peekCharUtf8(): Char {
+    val rc = tryPeek()
+    if (rc and 0x80 == 0) return rc.toChar()
+    if (rc == -1) throw EOFException("Failed to peek a char: end of input")
+
+    return peekCharUtf8Impl(rc)
+}
+
+private fun Input.peekCharUtf8Impl(first: Int): Char {
+    var rc = '?'
+    var found = false
+
+    takeWhileSize(byteCountUtf8(first)) {
+        it.decodeUTF8 { ch ->
+            found = true
+            rc = ch
+            false
+        }
+    }
+
+    if (!found) {
+        throw MalformedUTF8InputException("No UTF-8 character found")
+    }
+
+    return rc
+}

src/main/kotlin/kotlinx/io/core/internal/UTF8.kt

@@ -81,6 +81,25 @@ suspend fun decodeUTF8LineLoopSuspend(
 private fun prematureEndOfStreamUtf(size: Int): Nothing =
     throw EOFException("Premature end of stream: expected $size bytes to decode UTF-8 char")
 
+@DangerousInternalIoApi
+internal fun byteCountUtf8(firstByte: Int): Int {
+    var byteCount = 0
+    var mask = 0x80
+    var value = firstByte
+
+    for (i in 1..6) {
+        if (value and mask != 0) {
+            value = value and mask.inv()
+            mask = mask shr 1
+            byteCount++
+        } else {
+            break
+        }
+    }
+
+    return byteCount
+}
+
 /**
  * Decodes all the bytes to utf8 applying every character on [consumer] until or consumer return `false`.
  * If a consumer returned false then a character will be pushed back (including all surrogates will be pushed back as well)

src/test/kotlin/kotlinx/io/tests/PeekCharTest.kt

@@ -0,0 +1,159 @@
+package kotlinx.io.tests
+
+import kotlinx.io.core.*
+import kotlin.test.*
+
+class PeekCharTest {
+    @Test
+    fun testPeekEOF() {
+        assertFailsWith<EOFException> {
+            ByteReadPacket.Empty.peekCharUtf8()
+        }
+    }
+
+    @Test
+    fun testPeekAsciiSingle() {
+        buildPacket {
+            writeByte(0x37)
+        }.use {
+            assertEquals('7', it.peekCharUtf8())
+            assertEquals(1, it.remaining)
+        }
+    }
+
+    @Test
+    fun testPeekAsciiSeveral() {
+        buildPacket {
+            writeByte(0x37)
+            writeByte(0x38)
+            writeByte(0x39)
+        }.use {
+            assertEquals('7', it.peekCharUtf8())
+            it.discardExact(1)
+            assertEquals('8', it.peekCharUtf8())
+            it.discardExact(1)
+            assertEquals('9', it.peekCharUtf8())
+            it.discardExact(1)
+            assertEquals(0, it.remaining)
+        }
+    }
+
+    @Test
+    fun testPeekUtf8() {
+        buildPacket {
+            append('\u0422')
+        }.use {
+            assertEquals('\u0422', it.peekCharUtf8())
+        }
+    }
+
+    @Test
+    fun testPeekUtf8of3bytes() {
+        val bopomofoChar = '\u310f'
+
+        buildPacket {
+            append(bopomofoChar)
+        }.use {
+            assertEquals(3, it.remaining)
+            assertEquals(bopomofoChar, it.peekCharUtf8())
+        }
+    }
+
+    @Test
+    fun testPeekUtf8Edge() {
+        val oSlash = '\u00f8'
+
+        val chunk1 = IoBuffer.Pool.borrow()
+        val chunk2 = IoBuffer.Pool.borrow()
+        chunk1.reserveEndGap(8)
+        chunk1.next = chunk2
+
+        chunk1.writeByte(0xc3.toByte())
+        chunk2.writeByte(0xb8.toByte())
+
+        ByteReadPacket(chunk1, IoBuffer.Pool).use {
+            assertEquals(oSlash, it.peekCharUtf8())
+        }
+    }
+
+    @Test
+    fun testPeekUtf8EdgeFor3BytesCharacter() {
+        val bopomofoChar = '\u310f'
+
+        val chunk1 = IoBuffer.Pool.borrow()
+        val chunk2 = IoBuffer.Pool.borrow()
+        chunk1.reserveEndGap(8)
+        chunk1.next = chunk2
+
+        chunk1.writeByte(0xe3.toByte())
+        chunk2.writeByte(0x84.toByte())
+        chunk2.writeByte(0x8f.toByte())
+
+        ByteReadPacket(chunk1, IoBuffer.Pool).use {
+            assertEquals(bopomofoChar, it.peekCharUtf8())
+        }
+    }
+
+    @Test
+    fun testPeekUtf8EdgeFor3BytesCharacter2() {
+        val bopomofoChar = '\u310f'
+
+        val chunk1 = IoBuffer.Pool.borrow()
+        val chunk2 = IoBuffer.Pool.borrow()
+        chunk1.reserveEndGap(8)
+        chunk1.next = chunk2
+
+        chunk1.writeByte(0xe3.toByte())
+        chunk1.writeByte(0x84.toByte())
+        chunk2.writeByte(0x8f.toByte())
+
+        ByteReadPacket(chunk1, IoBuffer.Pool).use {
+            assertEquals(bopomofoChar, it.peekCharUtf8())
+        }
+    }
+
+    @Test
+    fun testPeekUtf8EdgeReservedFor3BytesCharacter() {
+        val bopomofoChar = '\u310f'
+
+        val chunk1 = IoBuffer.Pool.borrow()
+        val chunk2 = IoBuffer.Pool.borrow()
+        chunk1.reserveEndGap(8)
+        chunk1.next = chunk2
+
+        chunk1.writeFully(ByteArray(4087))
+        chunk1.writeByte(0xe3.toByte())
+        chunk2.writeByte(0x84.toByte())
+        chunk2.writeByte(0x8f.toByte())
+        chunk2.writeByte(0x30)
+
+        ByteReadPacket(chunk1, IoBuffer.Pool).use {
+            it.discardExact(4087)
+            assertEquals(bopomofoChar, it.peekCharUtf8())
+            it.discardExact(3)
+            assertEquals('0', it.peekCharUtf8())
+        }
+    }
+
+    @Test
+    fun testPeekUtf8EdgeFor3BytesCharacterFromAbstractInput() {
+        val bopomofoChar = '\u310f'
+        var count = 0
+
+        val myInput = object : AbstractInput() {
+            override fun fill(): IoBuffer? = when (count++) {
+                0 -> pool.borrow().apply { writeByte(0xe3.toByte()) }
+                1 -> pool.borrow().apply { writeByte(0x84.toByte()) }
+                2 -> pool.borrow().apply { writeByte(0x8f.toByte()) }
+                else -> null
+            }
+
+            override fun closeSource() {
+            }
+        }
+
+        myInput.use {
+            assertEquals(bopomofoChar, it.peekCharUtf8())
+        }
+    }
+}