feat: add UnicodeRangeAlphabet and CharAlphabet interfaces with tests to enhance character encoding options

Author: rasros

src/commonMain/kotlin/com/eignex/kencode/BaseRadix.kt

@@ -18,30 +18,74 @@ object Base62 : BaseRadix(BASE_62)
 object Base36 : BaseRadix(BASE_62.take(36))
 
 /**
- * Generic base-N encoder/decoder for binary data using arbitrary alphabets and block processing.
+ * Maps indices to characters (encoding) and characters back to indices (decoding).
+ * [indexOf] returns -1 for characters not in the alphabet.
  */
-open class BaseRadix(private val alphabet: String, val blockSize: Int = 32) :
-    ByteEncoding {
+interface Alphabet {
+    val size: Int
+    operator fun get(index: Int): Char
+    fun indexOf(c: Char): Int
+}
 
+/**
+ * Alphabet backed by an explicit string of characters.
+ */
+class CharAlphabet(private val chars: String) : Alphabet {
+    init {
+        require(chars.length > 1) { "Alphabet must contain at least 2 characters." }
+        require(chars.toSet().size == chars.length) { "Alphabet must not contain duplicate characters." }
+    }
+
+    override val size: Int = chars.length
+    private val maxCode: Int = chars.maxOf { it.code }
+    private val inverse: IntArray = IntArray(maxCode + 1) { -1 }.also { lookup ->
+        chars.forEachIndexed { index, c -> lookup[c.code] = index }
+    }
+
+    override fun get(index: Int): Char = chars[index]
+    override fun indexOf(c: Char): Int = if (c.code <= maxCode) inverse[c.code] else -1
+}
+
+/**
+ * Alphabet backed by a contiguous Unicode range starting at [start].
+ * Defaults to U+0020 – U+D7FF (55,264 characters), the largest BMP range
+ * that avoids surrogate code points.
+ */
+class UnicodeRangeAlphabet(
+    private val start: Int = 0x0020,
+    override val size: Int = 0xD800 - 0x0020
+) : Alphabet {
     init {
-        require(alphabet.length > 1) { "Alphabet must contain at least 2 characters." }
-        require(alphabet.toSet().size == alphabet.length) { "Alphabet must not contain duplicate characters." }
+        require(size > 1) { "Alphabet must contain at least 2 characters." }
+        require(start >= 0) { "Unicode range start must be non-negative." }
+        require(start + size <= 0xD800 || start >= 0xE000) {
+            "Unicode range must not overlap surrogate block (U+D800–U+DFFF)."
+        }
+        require(start + size <= 0x110000) { "Unicode range out of bounds." }
     }
 
-    private val alphabetSize: Int = alphabet.length
-    private val base: BigInteger = BigInteger.fromLong(alphabetSize.toLong())
-    private val logBase: Double = log2(alphabetSize.toDouble())
+    override fun get(index: Int): Char = (start + index).toChar()
+    override fun indexOf(c: Char): Int {
+        val offset = c.code - start
+        return if (offset in 0 until size) offset else -1
+    }
+}
+
+/**
+ * Generic base-N encoder/decoder for binary data using arbitrary alphabets and block processing.
+ */
+open class BaseRadix(private val alphabet: Alphabet, val blockSize: Int = 32) :
+    ByteEncoding {
+
+    constructor(chars: String, blockSize: Int = 32) : this(CharAlphabet(chars), blockSize)
+
+    private val base: BigInteger = BigInteger.fromLong(alphabet.size.toLong())
+    private val logBase: Double = log2(alphabet.size.toDouble())
 
     private val bigZero = BigInteger.ZERO
     private val bigFF = BigInteger.fromLong(0xFFL)
     private val zeroChar: Char get() = alphabet[0]
 
-    private val maxAlphabetChar: Int = alphabet.maxOf { it.code }
-    private val inverseAlphabet: IntArray =
-        IntArray(maxAlphabetChar + 1) { -1 }.also { lookup ->
-            alphabet.forEachIndexed { index, c -> lookup[c.code] = index }
-        }
-
     private val lengths: IntArray = IntArray(blockSize) { blockIndex ->
         val bytesCount = blockIndex + 1
         ceil((bytesCount * 8) / logBase).toInt()
@@ -136,8 +180,7 @@ open class BaseRadix(private val alphabet: String, val blockSize: Int = 32) :
         var writeIndex = output.length - 1
         while (n > bigZero && writeIndex >= startPos) {
             val remainder = n.rem(base)
-            output[writeIndex--] =
-                alphabet[remainder.intValue(exactRequired = false)]
+            output[writeIndex--] = alphabet[remainder.intValue(exactRequired = false)]
             n /= base
         }
         return output
@@ -153,9 +196,7 @@ open class BaseRadix(private val alphabet: String, val blockSize: Int = 32) :
     ): ByteArray {
         var n = bigZero
         for (i in inPos until (inPos + inLen)) {
-            val code = input[i].code
-            val index =
-                if (code < inverseAlphabet.size) inverseAlphabet[code] else -1
+            val index = alphabet.indexOf(input[i])
             require(index >= 0) { "Not an encoding char: '${input[i]}'" }
             n = n * base + BigInteger.fromLong(index.toLong())
         }

src/commonTest/kotlin/com/eignex/kencode/BaseRadixTest.kt

@@ -214,4 +214,53 @@ class BaseRadixTest {
             )
         }
     }
+
+    @Test
+    fun `UnicodeRangeAlphabet default roundtrips for various lengths`() {
+        val codec = BaseRadix(UnicodeRangeAlphabet())
+        val rng = Random(1111L)
+        for (len in 0..(codec.blockSize * 2)) {
+            val bytes = ByteArray(len).also { rng.nextBytes(it) }
+            assertRoundtrip(codec, bytes, "UnicodeRange default roundtrip failed for len=$len")
+        }
+    }
+
+    @Test
+    fun `UnicodeRangeAlphabet produces shorter output than Base62`() {
+        val unicode = BaseRadix(UnicodeRangeAlphabet())
+        val bytes = ByteArray(32) { it.toByte() }
+        assertTrue(unicode.encode(bytes).length < Base62.encode(bytes).length)
+    }
+
+    @Test
+    fun `UnicodeRangeAlphabet custom range roundtrips`() {
+        // Narrow range: Greek letters U+0391–U+03C9 (57 chars)
+        val greek = BaseRadix(UnicodeRangeAlphabet(start = 0x0391, size = 57))
+        val rng = Random(2222L)
+        for (len in 0..greek.blockSize) {
+            val bytes = ByteArray(len).also { rng.nextBytes(it) }
+            assertRoundtrip(greek, bytes, "Greek range roundtrip failed for len=$len")
+        }
+    }
+
+    @Test
+    fun `UnicodeRangeAlphabet indexOf returns -1 for out-of-range char`() {
+        val alpha = UnicodeRangeAlphabet(start = 0x0391, size = 57)
+        assertEquals(-1, alpha.indexOf('A'))
+        assertEquals(-1, alpha.indexOf('\u0000'))
+    }
+
+    @Test
+    fun `UnicodeRangeAlphabet rejects surrogate overlap`() {
+        assertFailsWith<IllegalArgumentException> {
+            UnicodeRangeAlphabet(start = 0xD000, size = 0x1000)
+        }
+    }
+
+    @Test
+    fun `UnicodeRangeAlphabet rejects size less than 2`() {
+        assertFailsWith<IllegalArgumentException> {
+            UnicodeRangeAlphabet(start = 0x0020, size = 1)
+        }
+    }
 }