Merge pull request #18 from cketti/value_class

Add nicer API based on a `CodePoint` class

Author: cketti

build.gradle.kts

@@ -1,83 +1,5 @@
-import org.jetbrains.kotlin.gradle.plugin.KotlinPlatformType
-
-plugins {
-    kotlin("multiplatform") version "1.8.0"
-    id("com.vanniktech.maven.publish") version "0.23.2"
-}
-
-repositories {
-    mavenCentral()
-}
-
-kotlin {
-    androidNativeArm32()
-    androidNativeArm64()
-    androidNativeX86()
-    androidNativeX64()
-
-    iosArm32()
-    iosArm64()
-    iosX64()
-    iosSimulatorArm64()
-
-    js(IR) {
-        browser {}
-    }
-
-    jvm {
-        compilations.all {
-            kotlinOptions.jvmTarget = "1.8"
-        }
+allprojects {
+    repositories {
+        mavenCentral()
     }
-
-    linuxArm32Hfp()
-    linuxArm64()
-    linuxMips32()
-    linuxMipsel32()
-    linuxX64()
-
-    macosX64()
-    macosArm64()
-
-    mingwX64()
-    mingwX86()
-
-    tvosArm64()
-    tvosX64()
-    tvosSimulatorArm64()
-
-    wasm32()
-
-    watchosArm32()
-    watchosArm64()
-    watchosDeviceArm64()
-    watchosX86()
-    watchosX64()
-    watchosSimulatorArm64()
-
-    sourceSets {
-        val commonMain by getting
-        val commonTest by getting {
-            dependencies {
-                implementation(kotlin("test"))
-            }
-        }
-
-        val commonImplementation by creating {
-            dependsOn(commonMain)
-        }
-    }
-
-    targets.onEach {
-        if (it.platformType != KotlinPlatformType.jvm) {
-            it.compilations.getByName("main").source(sourceSets.getByName("commonImplementation"))
-        }
-    }
-}
-
-tasks.create("publishMips") {
-    dependsOn(
-        "publishLinuxMips32PublicationToMavenCentralRepository",
-        "publishLinuxMipsel32PublicationToMavenCentralRepository"
-    )
 }

gradle.properties

@@ -1,9 +1,6 @@
 GROUP=de.cketti.unicode
-POM_ARTIFACT_ID=kotlin-codepoints
 VERSION_NAME=0.4.0-SNAPSHOT
 
-POM_NAME=kotlin-codepoints
-POM_DESCRIPTION=Kotlin Multiplatform (KMP) library that adds basic support for Unicode code points.
 POM_INCEPTION_YEAR=2023
 
 POM_URL=https://github.com/cketti/kotlin-codepoints

gradle/libs.versions.toml

@@ -0,0 +1,6 @@
+[versions]
+kotlin = "1.8.0"
+
+[plugins]
+kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
+vanniktech-maven-publish = "com.vanniktech.maven.publish:0.23.2"

kotlin-codepoints-deluxe/build.gradle.kts

@@ -0,0 +1,79 @@
+plugins {
+    alias(libs.plugins.kotlin.multiplatform)
+    alias(libs.plugins.vanniktech.maven.publish)
+}
+
+kotlin {
+    androidNativeArm32()
+    androidNativeArm64()
+    androidNativeX86()
+    androidNativeX64()
+
+    iosArm32()
+    iosArm64()
+    iosX64()
+    iosSimulatorArm64()
+
+    js(IR) {
+        browser {}
+    }
+
+    jvm {
+        compilations.all {
+            kotlinOptions.jvmTarget = "1.8"
+        }
+    }
+
+    linuxArm32Hfp()
+    linuxArm64()
+    linuxMips32()
+    linuxMipsel32()
+    linuxX64()
+
+    macosX64()
+    macosArm64()
+
+    mingwX64()
+    mingwX86()
+
+    tvosArm64()
+    tvosX64()
+    tvosSimulatorArm64()
+
+    wasm32()
+
+    watchosArm32()
+    watchosArm64()
+    watchosDeviceArm64()
+    watchosX86()
+    watchosX64()
+    watchosSimulatorArm64()
+
+    sourceSets {
+        val commonMain by getting {
+            dependencies {
+                api(project(":kotlin-codepoints"))
+            }
+        }
+        val commonTest by getting {
+            dependencies {
+                implementation(kotlin("test"))
+            }
+        }
+    }
+}
+
+@Suppress("UnstableApiUsage")
+mavenPublishing {
+    pom {
+        name.set("kotlin-codepoint-deluxe")
+        description.set("Kotlin Multiplatform (KMP) library that adds a nicer API than kotlin-codepoint for dealing with Unicode code points.")
+    }
+}
+
+tasks.create("publishMips") {
+    dependsOn(
+        "publishLinuxMips32PublicationToMavenCentralRepository",
+        "publishLinuxMipsel32PublicationToMavenCentralRepository"
+    )
+}

kotlin-codepoints-deluxe/src/commonMain/kotlin/CodePoint.kt

@@ -0,0 +1,129 @@
+package de.cketti.codepoints.deluxe
+
+import de.cketti.codepoints.CodePoints
+import kotlin.jvm.JvmInline
+
+/**
+ * Represents a Unicode code point.
+ * 
+ * You can create/retrieve instances of this class by using the following functions:
+ * - [Int.toCodePoint]
+ * - [Char.toCodePoint]
+ * - [String.codePointSequence]
+ * - [String.codePointIterator]
+ */
+@JvmInline
+value class CodePoint internal constructor(val value: Int) {
+    init {
+        require(CodePoints.isValidCodePoint(value)) { "Not a valid code point" }
+    }
+
+    /**
+     * `true` if this Unicode code point is in the Basic Multilingual Plane (BMP).
+     *
+     * Such code points can be represented using a single `Char`.
+     */
+    val isBasic: Boolean
+        get() = CodePoints.isBmpCodePoint(value)
+
+    /**
+     * `true` if this Unicode code point is in the supplementary character range.
+     *
+     * In a `String` such a code point is represented using a surrogate pair, i.e. two `Char` values.
+     */
+    val isSupplementary: Boolean
+        get() = CodePoints.isSupplementaryCodePoint(value)
+
+    /**
+     * The number of `Char` values needed to represent this Unicode code point.
+     *
+     * If the specified code point is in the [BMP][CodePoint.isBasic], this property is `1`, otherwise it is `2`.
+     */
+    val charCount: Int
+        get() = CodePoints.charCount(value)
+
+    /**
+     * `true` if this code point is a surrogate code unit.
+     */
+    val isSurrogate: Boolean
+        get() = !isSupplementary && value.toChar().isSurrogate()
+
+    /**
+     * `true` if this code point is a high surrogate code unit.
+     */
+    val isHighSurrogate: Boolean
+        get() = !isSupplementary && value.toChar().isHighSurrogate()
+
+    /**
+     * `true` if this code point is a low surrogate code unit.
+     */
+    val isLowSurrogate: Boolean
+        get() = !isSupplementary && value.toChar().isLowSurrogate()
+
+    /**
+     * The leading surrogate (a high surrogate code unit) of the surrogate pair representing this supplementary
+     * Unicode code point.
+     *
+     * If this code point is not a supplementary character, an unspecified `Char` is returned.
+     */
+    val highSurrogateChar: Char
+        get() = CodePoints.highSurrogate(value)
+
+    /**
+     * The trailing surrogate (a low surrogate code unit) of the surrogate pair representing this supplementary
+     * Unicode code point.
+     *
+     * If this code point is not a supplementary character, an unspecified `Char` is returned.
+     */
+    val lowSurrogateChar: Char
+        get() = CodePoints.lowSurrogate(value)
+
+    /**
+     * Converts this Unicode code point to its UTF-16 representation stored in a char array.
+     *
+     * If this code point is a BMP (Basic Multilingual Plane or Plane 0) value, the resulting char array has the same 
+     * value as [value]. If the specified code point is a supplementary code point, the resulting char array has the 
+     * corresponding surrogate pair.
+     */
+    fun toChars(): CharArray {
+        return CodePoints.toChars(value)
+    }
+
+    /**
+     * Converts this Unicode code point to its UTF-16 representation. 
+     * 
+     * If this code point is a BMP (Basic Multilingual Plane or Plane 0) value, the same value is stored in 
+     * `destination[offset]`, and 1 is returned. If this code point is a supplementary character, its surrogate values 
+     * are stored in `destination[offset]` (high-surrogate) and `destination[offset+1]` (low-surrogate), and 2 is 
+     * returned.
+     */
+    fun toChars(destination: CharArray, offset: Int): Int {
+        return CodePoints.toChars(value, destination, offset)
+    }
+
+    /**
+     * Returns a string representation of this code point.
+     * 
+     * "U+" followed by the code point value in hexadecimal (using upper case letters), which is prepended with leading
+     * zeros to a minimum of four digits.
+     */
+    override fun toString(): String {
+        return "U+${value.toString(16).uppercase().padStart(4, '0')}"
+    }
+}
+
+/**
+ * Returns a [CodePoint] with this value.
+ * 
+ * Throws [IllegalArgumentException] if this value falls outside the range of valid code points.
+ */
+fun Int.toCodePoint(): CodePoint {
+    return CodePoint(this)
+}
+
+/**
+ * Returns a [CodePoint] with the same value as this `Char`.
+ */
+fun Char.toCodePoint(): CodePoint {
+    return CodePoint(this.code)
+}

kotlin-codepoints-deluxe/src/commonMain/kotlin/CodePointSequence.kt

@@ -0,0 +1,30 @@
+package de.cketti.codepoints.deluxe
+
+import kotlin.jvm.JvmInline
+
+/**
+ * Sequence of [CodePoint]s in the given [String].
+ */
+@JvmInline
+value class CodePointSequence(private val text: String) : Sequence<CodePoint> {
+    override fun iterator(): CodePointIterator {
+        return CodePointIterator(text)
+    }
+}
+
+/**
+ * Iterator for [CodePoint]s in the given [String].
+ */
+class CodePointIterator(private val text: String) : Iterator<CodePoint> {
+    private var index = 0
+    
+    override fun hasNext(): Boolean {
+        return index < text.length
+    }
+
+    override fun next(): CodePoint {
+        return text.codePointAt(index).also { codePoint ->
+            index += codePoint.charCount
+        }
+    }
+}

kotlin-codepoints-deluxe/src/commonMain/kotlin/StringExtensions.kt

@@ -0,0 +1,50 @@
+@file:Suppress(
+    "INVISIBLE_MEMBER", // Required to be able to use kotlin.internal.HidesMembers
+    "INVISIBLE_REFERENCE", // Required to be able to use kotlin.internal.HidesMembers
+)
+package de.cketti.codepoints.deluxe
+
+import de.cketti.codepoints.codePointAt as intCodePointAt
+import de.cketti.codepoints.codePointBefore as intCodePointBefore
+
+/**
+ * Returns the Unicode code point at the specified index.
+ *
+ * The `index` parameter is the regular `String` index, i.e. the number of `Char`s from the start of the string.
+ *
+ * If the `index` is out of bounds of this string, this method throws an [IndexOutOfBoundsException].
+ * 
+ * See [codePointAt][intCodePointAt].
+ * ```
+ */
+@kotlin.internal.HidesMembers
+fun String.codePointAt(index: Int): CodePoint {
+    return intCodePointAt(index).toCodePoint()
+}
+
+/**
+ * Returns the Unicode code point before the specified index.
+ *
+ * The `index` parameter is the regular `String` index, i.e. the number of `Char`s from the start of the string.
+ *
+ * If the value `index - 1` is out of bounds of this string, this method throws an [IndexOutOfBoundsException].
+ * 
+ * See [codePointBefore][intCodePointBefore].
+ */
+fun String.codePointBefore(index: Int): CodePoint {
+    return intCodePointBefore(index).toCodePoint()
+}
+
+/**
+ * Sequence of [CodePoint]s in this string.
+ */
+fun String.codePointSequence(): CodePointSequence {
+    return CodePointSequence(this)
+}
+
+/**
+ * Iterator for [CodePoint]s in this string.
+ */
+fun String.codePointIterator(): CodePointIterator {
+    return CodePointIterator(this)
+}