diff --git a/docs/topics/apiDocs/map.md b/docs/topics/apiDocs/map.md index 3f7a0b39..d3a86703 100644 --- a/docs/topics/apiDocs/map.md +++ b/docs/topics/apiDocs/map.md @@ -17,7 +17,8 @@ map() — element-wise transformation preserving shape. Applies a transformation function to each element and returns a new array of the same shape. Indexed variants provide the element's flat index (`mapIndexed`, 1D only) or multi-dimensional -index (`mapMultiIndexed`). The result element type `R` must be a supported `DataType`. +index (`mapMultiIndexed`). The `NotNull` variants drop `null` results and, like `filter`, return +a 1D array. The result element type `R` must be a supported `DataType`. ## Signatures @@ -36,18 +37,28 @@ inline fun MultiArray.mapMultiIndexed( inline fun MultiArray.mapNotNull( transform: (T) -> R? -): NDArray +): D1Array + +inline fun MultiArray.mapIndexedNotNull( + transform: (index: Int, T) -> R? +): D1Array + +inline fun MultiArray.mapMultiIndexedNotNull( + transform: (index: IntArray, T) -> R? +): D1Array ``` ## Parameters -| Parameter | Type | Description | -|-------------|-----------------------------|-----------------------------------| -| `transform` | `(T) -> R` | Maps each element to a new value. | -| `transform` | `(index: Int, T) -> R` | With flat index (1D arrays only). | -| `transform` | `(index: IntArray, T) -> R` | With multi-dimensional index. | +| Parameter | Type | Description | +|-------------|-----------------------------|-------------------------------------------------------| +| `transform` | `(T) -> R` | Maps each element to a new value. | +| `transform` | `(index: Int, T) -> R` | With flat index (1D arrays only). | +| `transform` | `(index: IntArray, T) -> R` | With multi-dimensional index. | +| `transform` | `(T) -> R?` | `NotNull` variants: return `null` to drop an element. | -**Returns:** `NDArray` — a new array with the same shape and transformed elements. +**Returns:** `NDArray` — a new array with the same shape and transformed elements. The `NotNull` +variants return a new `D1Array` of the non-null results in row-major order. ## Example @@ -67,11 +78,15 @@ b.mapIndexed { i, v -> v + i } a.mapMultiIndexed { idx, v -> idx.sum() + v } // [[1, 3], // [4, 6]] + +a.mapNotNull { if (it % 2 == 0) it * 10 else null } +// [20, 40] ``` -> `map` preserves the **shape** of the original array. Use `flatMap` if you need to change the shape. +> `map` preserves the **shape** of the original array; the `NotNull` variants always return a **1D** array. +> Use `flatMap` if you need to change the shape. > {style="note"} diff --git a/docs/topics/gettingStarted/quickstart.md b/docs/topics/gettingStarted/quickstart.md index 6ab840e6..84ce0640 100644 --- a/docs/topics/gettingStarted/quickstart.md +++ b/docs/topics/gettingStarted/quickstart.md @@ -374,6 +374,7 @@ println(d) // 15 > mapIndexed > mapMultiIndexed > mapIndexedNotNull +> mapMultiIndexedNotNull > mapNotNull > minimum > maximum diff --git a/multik-core/src/commonMain/kotlin/org/jetbrains/kotlinx/multik/ndarray/operations/IteratingNDArray.kt b/multik-core/src/commonMain/kotlin/org/jetbrains/kotlinx/multik/ndarray/operations/IteratingNDArray.kt index 7361f15e..308bf0de 100644 --- a/multik-core/src/commonMain/kotlin/org/jetbrains/kotlinx/multik/ndarray/operations/IteratingNDArray.kt +++ b/multik-core/src/commonMain/kotlin/org/jetbrains/kotlinx/multik/ndarray/operations/IteratingNDArray.kt @@ -915,7 +915,16 @@ public inline fun MultiArray.mapMultiI } /** - * Return a new array contains elements after applying [transform]. + * Returns a new 1D array with only the non-null results of applying [transform] to each element and its index. + * + * ``` + * val a = mk.ndarray(mk[10, 20, 30, 40]) + * a.mapIndexedNotNull { i, v -> if (i % 2 == 0) v + i else null } // [10, 32] + * ``` + * + * @param transform maps an index and an element to a value of a supported element type [R], or to `null` to drop it. + * @return a new [D1Array] of the non-null results in index order; empty if there are none. + * @see [mapIndexed] */ @JvmName("mapD1IndexedNotNull") public inline fun MultiArray.mapIndexedNotNull(transform: (index: Int, T) -> R?): D1Array { @@ -923,30 +932,59 @@ public inline fun MultiArray.mapIndexedNotNull(trans val data = initMemoryView(size, newDtype) var count = 0 forEachIndexed { index, element -> transform(index, element)?.let { data[count++] = it } } - return D1Array(data, shape = shape, dim = D1) + val result = if (count == size) data else data.copyInto(initMemoryView(count, newDtype), endIndex = count) + return D1Array(result, shape = intArrayOf(count), dim = D1) } /** - * Return a new array contains elements after applying [transform]. + * Returns a new 1D array with only the non-null results of applying [transform] to each element and its + * multi-dimensional index. + * + * Elements are visited in row-major order, and the result is 1D whatever the dimension of this array. + * + * ``` + * val a = mk.ndarray(mk[mk[1, 2], mk[3, 4]]) + * a.mapMultiIndexedNotNull { idx, v -> if (idx[0] == idx[1]) v else null } // [1, 4] + * ``` + * + * @param transform maps a multi-dimensional index and an element to a value of a supported element type [R], + * or to `null` to drop it. + * @return a new [D1Array] of the non-null results; empty if there are none. + * @see [mapMultiIndexed] */ @JvmName("mapDNIndexedNotNull") -public inline fun MultiArray.mapMultiIndexedNotNull(transform: (index: IntArray, T) -> R?): NDArray { +public inline fun MultiArray.mapMultiIndexedNotNull(transform: (index: IntArray, T) -> R?): D1Array { val newDtype = DataType.ofKClass(R::class) val data = initMemoryView(size, newDtype) var count = 0 forEachMultiIndexed { index, element -> transform(index, element)?.let { data[count++] = it } } - return NDArray(data, shape = shape.copyOf(), dim = dim) + val result = if (count == size) data else data.copyInto(initMemoryView(count, newDtype), endIndex = count) + return D1Array(result, shape = intArrayOf(count), dim = D1) } /** - * Return a new array contains elements after applying [transform]. + * Returns a new 1D array with only the non-null results of applying [transform] to each element. + * + * Elements are visited in row-major order, and the result is 1D whatever the dimension of this array, + * as with [filter]. + * + * ``` + * val a = mk.ndarray(mk[mk[1, 2], mk[3, 4]]) + * a.mapNotNull { if (it % 2 == 0) it * 10 else null } // [20, 40] + * ``` + * + * @param transform maps an element to a value of a supported element type [R], or to `null` to drop it. + * @return a new [D1Array] of the non-null results; empty if there are none. + * @see [map] + * @see [filter] */ -public inline fun MultiArray.mapNotNull(transform: (T) -> R?): NDArray { +public inline fun MultiArray.mapNotNull(transform: (T) -> R?): D1Array { val newDtype = DataType.ofKClass(R::class) val data = initMemoryView(size, newDtype) - var index = 0 - forEach { element -> transform(element)?.let { data[index++] = it } } - return NDArray(data, shape = shape, dim = dim) + var count = 0 + forEach { element -> transform(element)?.let { data[count++] = it } } + val result = if (count == size) data else data.copyInto(initMemoryView(count, newDtype), endIndex = count) + return D1Array(result, shape = intArrayOf(count), dim = D1) } /** diff --git a/multik-core/src/commonTest/kotlin/org/jetbrains/kotlinx/multik/iterable/IterableNDArrayTest.kt b/multik-core/src/commonTest/kotlin/org/jetbrains/kotlinx/multik/iterable/IterableNDArrayTest.kt index f993c037..6b9c6bc4 100644 --- a/multik-core/src/commonTest/kotlin/org/jetbrains/kotlinx/multik/iterable/IterableNDArrayTest.kt +++ b/multik-core/src/commonTest/kotlin/org/jetbrains/kotlinx/multik/iterable/IterableNDArrayTest.kt @@ -43,7 +43,10 @@ import org.jetbrains.kotlinx.multik.ndarray.operations.intersect import org.jetbrains.kotlinx.multik.ndarray.operations.last import org.jetbrains.kotlinx.multik.ndarray.operations.map import org.jetbrains.kotlinx.multik.ndarray.operations.mapIndexed +import org.jetbrains.kotlinx.multik.ndarray.operations.mapIndexedNotNull import org.jetbrains.kotlinx.multik.ndarray.operations.mapMultiIndexed +import org.jetbrains.kotlinx.multik.ndarray.operations.mapMultiIndexedNotNull +import org.jetbrains.kotlinx.multik.ndarray.operations.mapNotNull import org.jetbrains.kotlinx.multik.ndarray.operations.max import org.jetbrains.kotlinx.multik.ndarray.operations.maxBy import org.jetbrains.kotlinx.multik.ndarray.operations.maximum @@ -528,6 +531,60 @@ class IterableNDArrayTest { ndarray.mapMultiIndexed { idx: IntArray, value -> value * (idx[0] xor idx[1]) } } + @Test + fun testMapNotNull() { + val a = mk.ndarray(mk[1, 2, 3, 4]) + val actual = a.mapNotNull { if (it == 2) null else it } + assertEquals(mk.ndarray(mk[1, 3, 4]), actual) + assertTrue(actual.consistent) + + // The source shape can't be kept for D > 1, so the result is 1D, as with filter. + val b = mk.ndarray(mk[mk[1, 2], mk[3, 4]]) + assertEquals(mk.ndarray(mk[1, 3, 4]), b.mapNotNull { if (it == 2) null else it }) + assertEquals(mk.ndarray(mk[1, 2, 3, 4]), b.mapNotNull { it }) + // A transposed view is visited in its own row-major order: 1, 3, 2, 4. + assertEquals(mk.ndarray(mk[1.0, 3.0, 4.0]), b.transpose().mapNotNull { if (it == 2) null else it.toDouble() }) + } + + @Test + fun testMapNotNullEmptyResult() { + val allNull = mk.ndarray(mk[mk[1, 2], mk[3, 4]]).mapNotNull { if (it > 10) it.toDouble() else null } + assertContentEquals(intArrayOf(0), allNull.shape) + assertEquals(DataType.DoubleDataType, allNull.dtype) + + val fromEmpty = mk.zeros(0).mapNotNull { it.toFloat() } + assertContentEquals(intArrayOf(0), fromEmpty.shape) + assertEquals(DataType.FloatDataType, fromEmpty.dtype) + } + + @Test + fun testMapIndexedNotNull() { + val data = mk.ndarray(mk[10, 20, 30, 40]) + val actual = data.mapIndexedNotNull { i, v -> if (i % 2 == 0) v + i else null } + assertEquals(mk.ndarray(mk[10, 32]), actual) + assertTrue(actual.consistent) + + val empty = data.mapIndexedNotNull { i, v -> if (i > 10) v.toLong() else null } + assertContentEquals(intArrayOf(0), empty.shape) + assertEquals(DataType.LongDataType, empty.dtype) + } + + @Test + fun testMapMultiIndexedNotNull() { + val data = mk.ndarray(mk[mk[1, 2], mk[3, 4]]) + val actual = data.mapMultiIndexedNotNull { idx, v -> if (idx[0] == idx[1]) v else null } + assertEquals(mk.ndarray(mk[1, 4]), actual) + assertTrue(actual.consistent) + + val complex = data.mapMultiIndexedNotNull { idx, v -> if (idx[1] == 0) ComplexDouble(v.toDouble(), 1.0) else null } + assertEquals(mk.ndarray(mk[ComplexDouble(1.0, 1.0), ComplexDouble(3.0, 1.0)]), complex) + assertTrue(complex.consistent) + + val empty = data.mapMultiIndexedNotNull { idx, v -> if (idx[0] > 10) v.toShort() else null } + assertContentEquals(intArrayOf(0), empty.shape) + assertEquals(DataType.ShortDataType, empty.dtype) + } + @Test fun `test_max`() { val array = intArrayOf(1, -2, 10, 23, 3, 10, 32, -1, 17) diff --git a/multik-core/src/commonTest/kotlin/samples/docs/apiDocs/arrayOperations.kt b/multik-core/src/commonTest/kotlin/samples/docs/apiDocs/arrayOperations.kt index 1b641437..9bd454c8 100644 --- a/multik-core/src/commonTest/kotlin/samples/docs/apiDocs/arrayOperations.kt +++ b/multik-core/src/commonTest/kotlin/samples/docs/apiDocs/arrayOperations.kt @@ -46,6 +46,7 @@ import org.jetbrains.kotlinx.multik.ndarray.operations.lastOrNull import org.jetbrains.kotlinx.multik.ndarray.operations.map import org.jetbrains.kotlinx.multik.ndarray.operations.mapIndexed import org.jetbrains.kotlinx.multik.ndarray.operations.mapMultiIndexed +import org.jetbrains.kotlinx.multik.ndarray.operations.mapNotNull import org.jetbrains.kotlinx.multik.ndarray.operations.max import org.jetbrains.kotlinx.multik.ndarray.operations.maxBy import org.jetbrains.kotlinx.multik.ndarray.operations.maxWith @@ -280,6 +281,9 @@ class ArrayOperations { a.mapMultiIndexed { idx, v -> idx.sum() + v } // [[1, 3], // [4, 6]] + + a.mapNotNull { if (it % 2 == 0) it * 10 else null } + // [20, 40] // SampleEnd }