Extract asList to an extension function and return a custom immutable list

Author: daniel-rusu

buildSrc/src/main/kotlin/com/danrusu/pods4k/immutableArrays/core/ImmutableArrayExtensionsGenerator.kt

@@ -21,6 +21,7 @@ import java.io.File
 internal object ImmutableArrayExtensionsGenerator {
     fun generate(destinationPath: String) {
         val fileSpec = createFile(ImmutableArrayConfig.packageName, "ImmutableArrays") {
+            addAsList()
             addContains()
             addIndexOf()
             addLastIndexOf()
@@ -37,6 +38,53 @@ internal object ImmutableArrayExtensionsGenerator {
     }
 }
 
+private fun FileSpec.Builder.addAsList() {
+    val standardKdoc = "Returns an immutable list that wraps the same backing array without copying the elements."
+
+    for (baseType in BaseType.entries) {
+        function(
+            kdoc = when (baseType) {
+                GENERIC -> standardKdoc
+                else -> {
+                    """
+                    $standardKdoc
+
+                    Note that accessing values from the resulting list will auto-box them everytime they are accessed.  This is because [${baseType.generatedClassName}] stores primitive values whereas [List] is defined as a generic type.  If the number of accesses is expected to be multiple times larger than the size of this array, then you might want to consider using [toList] instead in order to copy all the elements into a standalone list and only auto-box each element once.
+                    """.trimIndent()
+                }
+            },
+            receiver = baseType.getGeneratedTypeName(),
+            name = "asList",
+            returns = List::class.asTypeName().parameterizedBy(baseType.type),
+        ) {
+            if (baseType == GENERIC) {
+                addTypeVariable(baseType.type as TypeVariableName)
+            }
+            // IMPORTANT: Don't attempt to delegate to the backing array (eg. "return values.asList()") because that can allow an outsider to mutate the backing array via the list wrapper
+            // See https://youtrack.jetbrains.com/issue/KT-70779/Array.asList-exposes-mutation-back-door
+            addCode(
+                """
+                    return object : %T<%T>(), %T {
+                        override val size: Int get() = this@asList.size
+                        override fun isEmpty(): Boolean = this@asList.isEmpty()
+                        override fun contains(element: %T): Boolean = this@asList.contains(element)
+                        override fun get(index: Int): %T = this@asList[index]
+                        override fun indexOf(element: %T): Int = this@asList.indexOf(element)
+                        override fun lastIndexOf(element: %T): Int = this@asList.lastIndexOf(element)
+                    }
+                """.trimIndent(),
+                AbstractList::class.asTypeName(),
+                baseType.type,
+                RandomAccess::class.asTypeName(),
+                baseType.type,
+                baseType.type,
+                baseType.type,
+                baseType.type,
+            )
+        }
+    }
+}
+
 private fun FileSpec.Builder.addContains() {
     for (baseType in BaseType.entries) {
         function(
@@ -192,6 +240,7 @@ private fun FileSpec.Builder.addSortedDescending() {
             receiver = receiver,
             name = "sortedDescending",
             returns = receiver,
+            forceFunctionBody = true,
         ) {
             if (baseType == GENERIC) {
                 addTypeVariable(

buildSrc/src/main/kotlin/com/danrusu/pods4k/immutableArrays/core/ImmutableArrayGenerator.kt

@@ -220,21 +220,6 @@ private fun generateImmutableArrayFile(baseType: BaseType): FileSpec {
                 baseType = baseType,
                 returns = Sequence::class.asTypeName().parameterizedBy(baseType.type),
             )
-            "asList"(
-                typeSpecBuilder = this,
-                baseType = baseType,
-                kdoc = when (baseType) {
-                    GENERIC -> "Wraps the backing array in a class that implements the read-only [List] interface by referencing the same backing array without copying the elements."
-                    else -> {
-                        """
-                            Wraps the backing array in a class that implements the read-only [List] interface by referencing the same backing array without copying the elements.
-
-                            Note that [${baseType.generatedClassName}] stores primitive values whereas [List] operates on generic types so this will auto-box the value that is accessed on every access.  If the total number of accesses is expected to be multiple times larger than the total number of elements then you might want to consider converting it into a list instead as that will auto-box all the elements only once at the cost of allocating a separate backing array.
-                        """.trimIndent()
-                    }
-                },
-                returns = List::class.asTypeName().parameterizedBy(baseType.type),
-            )
             "forEach"(
                 typeSpecBuilder = this,
                 baseType = baseType,

changelog.md

@@ -9,6 +9,10 @@ _Date TBD_
 
 **Breaking Changes:**
 
+* Extracted the `asList` method to an extension function and replaced the previous implementation, which delegated to
+  the `asList` function on the backing array, with a custom list implementation that's guaranteed to always be
+  immutable. This was necessary because the Kotlin standard library `Array<T>.asList` extension function doesn't
+  guarantee immutability via the wrapper list that it returns.
 * Renamed the `specializations` package to `multiplicativeSpecializations` to better reflect its contents. These
   specializations are generated by multiplying all combinations of base types and using the most efficient resulting
   type for each combination. There are hundreds of regular non-multiplicative specializations so this updated name stops

immutable-arrays/core/src/main/kotlin/com/danrusu/pods4k/immutableArrays/ImmutableArray.kt

@@ -18,7 +18,6 @@ import kotlin.Unit
 import kotlin.collections.IndexedValue
 import kotlin.collections.Iterable
 import kotlin.collections.Iterator
-import kotlin.collections.List
 import kotlin.jvm.JvmInline
 import kotlin.ranges.IntRange
 import kotlin.sequences.Sequence
@@ -225,12 +224,6 @@ public value class ImmutableArray<out T> @PublishedApi internal constructor(
      */
     public inline fun asSequence(): Sequence<T> = values.asSequence()
 
-    /**
-     * Wraps the backing array in a class that implements the read-only [List] interface by
-     * referencing the same backing array without copying the elements.
-     */
-    public inline fun asList(): List<T> = values.asList()
-
     /**
      * See [Array.forEach]
      */

immutable-arrays/core/src/main/kotlin/com/danrusu/pods4k/immutableArrays/ImmutableArrays.kt

@@ -3,6 +3,7 @@ package com.danrusu.pods4k.immutableArrays
 
 import java.lang.IllegalArgumentException
 import java.util.Arrays
+import java.util.RandomAccess
 import kotlin.Boolean
 import kotlin.Byte
 import kotlin.Char
@@ -13,6 +14,168 @@ import kotlin.Int
 import kotlin.Long
 import kotlin.Short
 import kotlin.Suppress
+import kotlin.collections.AbstractList
+import kotlin.collections.List
+
+/**
+ * Returns an immutable list that wraps the same backing array without copying the elements.
+ */
+public fun <T> ImmutableArray<T>.asList(): List<T> = object : AbstractList<T>(), RandomAccess {
+    override val size: Int get() = this@asList.size
+    override fun isEmpty(): Boolean = this@asList.isEmpty()
+    override fun contains(element: T): Boolean = this@asList.contains(element)
+    override fun get(index: Int): T = this@asList[index]
+    override fun indexOf(element: T): Int = this@asList.indexOf(element)
+    override fun lastIndexOf(element: T): Int = this@asList.lastIndexOf(element)
+}
+
+/**
+ * Returns an immutable list that wraps the same backing array without copying the elements.
+ *
+ * Note that accessing values from the resulting list will auto-box them everytime they are
+ * accessed.  This is because [ImmutableBooleanArray] stores primitive values whereas [List] is defined
+ * as a generic type.  If the number of accesses is expected to be multiple times larger than the size
+ * of this array, then you might want to consider using [toList] instead in order to copy all the
+ * elements into a standalone list and only auto-box each element once.
+ */
+public fun ImmutableBooleanArray.asList(): List<Boolean> = object :
+    AbstractList<Boolean>(),
+    RandomAccess {
+    override val size: Int get() = this@asList.size
+    override fun isEmpty(): Boolean = this@asList.isEmpty()
+    override fun contains(element: Boolean): Boolean = this@asList.contains(element)
+    override fun get(index: Int): Boolean = this@asList[index]
+    override fun indexOf(element: Boolean): Int = this@asList.indexOf(element)
+    override fun lastIndexOf(element: Boolean): Int = this@asList.lastIndexOf(element)
+}
+
+/**
+ * Returns an immutable list that wraps the same backing array without copying the elements.
+ *
+ * Note that accessing values from the resulting list will auto-box them everytime they are
+ * accessed.  This is because [ImmutableByteArray] stores primitive values whereas [List] is defined as
+ * a generic type.  If the number of accesses is expected to be multiple times larger than the size of
+ * this array, then you might want to consider using [toList] instead in order to copy all the elements
+ * into a standalone list and only auto-box each element once.
+ */
+public fun ImmutableByteArray.asList(): List<Byte> = object : AbstractList<Byte>(), RandomAccess {
+    override val size: Int get() = this@asList.size
+    override fun isEmpty(): Boolean = this@asList.isEmpty()
+    override fun contains(element: Byte): Boolean = this@asList.contains(element)
+    override fun get(index: Int): Byte = this@asList[index]
+    override fun indexOf(element: Byte): Int = this@asList.indexOf(element)
+    override fun lastIndexOf(element: Byte): Int = this@asList.lastIndexOf(element)
+}
+
+/**
+ * Returns an immutable list that wraps the same backing array without copying the elements.
+ *
+ * Note that accessing values from the resulting list will auto-box them everytime they are
+ * accessed.  This is because [ImmutableCharArray] stores primitive values whereas [List] is defined as
+ * a generic type.  If the number of accesses is expected to be multiple times larger than the size of
+ * this array, then you might want to consider using [toList] instead in order to copy all the elements
+ * into a standalone list and only auto-box each element once.
+ */
+public fun ImmutableCharArray.asList(): List<Char> = object : AbstractList<Char>(), RandomAccess {
+    override val size: Int get() = this@asList.size
+    override fun isEmpty(): Boolean = this@asList.isEmpty()
+    override fun contains(element: Char): Boolean = this@asList.contains(element)
+    override fun get(index: Int): Char = this@asList[index]
+    override fun indexOf(element: Char): Int = this@asList.indexOf(element)
+    override fun lastIndexOf(element: Char): Int = this@asList.lastIndexOf(element)
+}
+
+/**
+ * Returns an immutable list that wraps the same backing array without copying the elements.
+ *
+ * Note that accessing values from the resulting list will auto-box them everytime they are
+ * accessed.  This is because [ImmutableShortArray] stores primitive values whereas [List] is defined
+ * as a generic type.  If the number of accesses is expected to be multiple times larger than the size
+ * of this array, then you might want to consider using [toList] instead in order to copy all the
+ * elements into a standalone list and only auto-box each element once.
+ */
+public fun ImmutableShortArray.asList(): List<Short> = object : AbstractList<Short>(), RandomAccess {
+    override val size: Int get() = this@asList.size
+    override fun isEmpty(): Boolean = this@asList.isEmpty()
+    override fun contains(element: Short): Boolean = this@asList.contains(element)
+    override fun get(index: Int): Short = this@asList[index]
+    override fun indexOf(element: Short): Int = this@asList.indexOf(element)
+    override fun lastIndexOf(element: Short): Int = this@asList.lastIndexOf(element)
+}
+
+/**
+ * Returns an immutable list that wraps the same backing array without copying the elements.
+ *
+ * Note that accessing values from the resulting list will auto-box them everytime they are
+ * accessed.  This is because [ImmutableIntArray] stores primitive values whereas [List] is defined as
+ * a generic type.  If the number of accesses is expected to be multiple times larger than the size of
+ * this array, then you might want to consider using [toList] instead in order to copy all the elements
+ * into a standalone list and only auto-box each element once.
+ */
+public fun ImmutableIntArray.asList(): List<Int> = object : AbstractList<Int>(), RandomAccess {
+    override val size: Int get() = this@asList.size
+    override fun isEmpty(): Boolean = this@asList.isEmpty()
+    override fun contains(element: Int): Boolean = this@asList.contains(element)
+    override fun get(index: Int): Int = this@asList[index]
+    override fun indexOf(element: Int): Int = this@asList.indexOf(element)
+    override fun lastIndexOf(element: Int): Int = this@asList.lastIndexOf(element)
+}
+
+/**
+ * Returns an immutable list that wraps the same backing array without copying the elements.
+ *
+ * Note that accessing values from the resulting list will auto-box them everytime they are
+ * accessed.  This is because [ImmutableLongArray] stores primitive values whereas [List] is defined as
+ * a generic type.  If the number of accesses is expected to be multiple times larger than the size of
+ * this array, then you might want to consider using [toList] instead in order to copy all the elements
+ * into a standalone list and only auto-box each element once.
+ */
+public fun ImmutableLongArray.asList(): List<Long> = object : AbstractList<Long>(), RandomAccess {
+    override val size: Int get() = this@asList.size
+    override fun isEmpty(): Boolean = this@asList.isEmpty()
+    override fun contains(element: Long): Boolean = this@asList.contains(element)
+    override fun get(index: Int): Long = this@asList[index]
+    override fun indexOf(element: Long): Int = this@asList.indexOf(element)
+    override fun lastIndexOf(element: Long): Int = this@asList.lastIndexOf(element)
+}
+
+/**
+ * Returns an immutable list that wraps the same backing array without copying the elements.
+ *
+ * Note that accessing values from the resulting list will auto-box them everytime they are
+ * accessed.  This is because [ImmutableFloatArray] stores primitive values whereas [List] is defined
+ * as a generic type.  If the number of accesses is expected to be multiple times larger than the size
+ * of this array, then you might want to consider using [toList] instead in order to copy all the
+ * elements into a standalone list and only auto-box each element once.
+ */
+public fun ImmutableFloatArray.asList(): List<Float> = object : AbstractList<Float>(), RandomAccess {
+    override val size: Int get() = this@asList.size
+    override fun isEmpty(): Boolean = this@asList.isEmpty()
+    override fun contains(element: Float): Boolean = this@asList.contains(element)
+    override fun get(index: Int): Float = this@asList[index]
+    override fun indexOf(element: Float): Int = this@asList.indexOf(element)
+    override fun lastIndexOf(element: Float): Int = this@asList.lastIndexOf(element)
+}
+
+/**
+ * Returns an immutable list that wraps the same backing array without copying the elements.
+ *
+ * Note that accessing values from the resulting list will auto-box them everytime they are
+ * accessed.  This is because [ImmutableDoubleArray] stores primitive values whereas [List] is defined
+ * as a generic type.  If the number of accesses is expected to be multiple times larger than the size
+ * of this array, then you might want to consider using [toList] instead in order to copy all the
+ * elements into a standalone list and only auto-box each element once.
+ */
+public fun ImmutableDoubleArray.asList(): List<Double> = object :
+    AbstractList<Double>(),
+    RandomAccess {
+    override val size: Int get() = this@asList.size
+    override fun isEmpty(): Boolean = this@asList.isEmpty()
+    override fun contains(element: Double): Boolean = this@asList.contains(element)
+    override fun get(index: Int): Double = this@asList[index]
+    override fun indexOf(element: Double): Int = this@asList.indexOf(element)
+    override fun lastIndexOf(element: Double): Int = this@asList.lastIndexOf(element)
+}
 
 /**
  * See [Array.contains]
@@ -425,8 +588,9 @@ public fun ImmutableDoubleArray.sorted(): ImmutableDoubleArray {
  *
  * The sort is _stable_ so equal elements preserve their order relative to each other after sorting.
  */
-public fun <T : Comparable<T>> ImmutableArray<T>.sortedDescending(): ImmutableArray<T> =
-    sortedWith(reverseOrder())
+public fun <T : Comparable<T>> ImmutableArray<T>.sortedDescending(): ImmutableArray<T> {
+    return sortedWith(reverseOrder())
+}
 
 /**
  * Leaves [this] immutable array as is and returns an [ImmutableByteArray] with all elements sorted

immutable-arrays/core/src/main/kotlin/com/danrusu/pods4k/immutableArrays/ImmutableBooleanArray.kt

@@ -17,7 +17,6 @@ import kotlin.Unit
 import kotlin.collections.IndexedValue
 import kotlin.collections.Iterable
 import kotlin.collections.Iterator
-import kotlin.collections.List
 import kotlin.jvm.JvmInline
 import kotlin.ranges.IntRange
 import kotlin.sequences.Sequence
@@ -224,18 +223,6 @@ public value class ImmutableBooleanArray @PublishedApi internal constructor(
      */
     public inline fun asSequence(): Sequence<Boolean> = values.asSequence()
 
-    /**
-     * Wraps the backing array in a class that implements the read-only [List] interface by
-     * referencing the same backing array without copying the elements.
-     *
-     * Note that [ImmutableBooleanArray] stores primitive values whereas [List] operates on generic
-     * types so this will auto-box the value that is accessed on every access.  If the total number of
-     * accesses is expected to be multiple times larger than the total number of elements then you
-     * might want to consider converting it into a list instead as that will auto-box all the elements
-     * only once at the cost of allocating a separate backing array.
-     */
-    public inline fun asList(): List<Boolean> = values.asList()
-
     /**
      * See [BooleanArray.forEach]
      */

immutable-arrays/core/src/main/kotlin/com/danrusu/pods4k/immutableArrays/ImmutableByteArray.kt

@@ -18,7 +18,6 @@ import kotlin.Unit
 import kotlin.collections.IndexedValue
 import kotlin.collections.Iterable
 import kotlin.collections.Iterator
-import kotlin.collections.List
 import kotlin.jvm.JvmInline
 import kotlin.ranges.IntRange
 import kotlin.sequences.Sequence
@@ -225,18 +224,6 @@ public value class ImmutableByteArray @PublishedApi internal constructor(
      */
     public inline fun asSequence(): Sequence<Byte> = values.asSequence()
 
-    /**
-     * Wraps the backing array in a class that implements the read-only [List] interface by
-     * referencing the same backing array without copying the elements.
-     *
-     * Note that [ImmutableByteArray] stores primitive values whereas [List] operates on generic
-     * types so this will auto-box the value that is accessed on every access.  If the total number of
-     * accesses is expected to be multiple times larger than the total number of elements then you
-     * might want to consider converting it into a list instead as that will auto-box all the elements
-     * only once at the cost of allocating a separate backing array.
-     */
-    public inline fun asList(): List<Byte> = values.asList()
-
     /**
      * See [ByteArray.forEach]
      */