Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 24 additions & 9 deletions docs/topics/apiDocs/map.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -36,18 +37,28 @@ inline fun <T, D : Dimension, reified R : Any> MultiArray<T, D>.mapMultiIndexed(

inline fun <T, D : Dimension, reified R : Any> MultiArray<T, D>.mapNotNull(
transform: (T) -> R?
): NDArray<R, D>
): D1Array<R>

inline fun <T, reified R : Any> MultiArray<T, D1>.mapIndexedNotNull(
transform: (index: Int, T) -> R?
): D1Array<R>

inline fun <T, D : Dimension, reified R : Any> MultiArray<T, D>.mapMultiIndexedNotNull(
transform: (index: IntArray, T) -> R?
): D1Array<R>
```

## 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<R, D>` — a new array with the same shape and transformed elements.
**Returns:** `NDArray<R, D>` — a new array with the same shape and transformed elements. The `NotNull`
variants return a new `D1Array<R>` of the non-null results in row-major order.

## Example

Expand All @@ -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]
```

<!---END-->

> `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"}

<seealso style="cards">
Expand Down
1 change: 1 addition & 0 deletions docs/topics/gettingStarted/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -374,6 +374,7 @@ println(d) // 15
> <a href="map.md">mapIndexed</a>
> <a href="map.md">mapMultiIndexed</a>
> <a href="map.md">mapIndexedNotNull</a>
> <a href="map.md">mapMultiIndexedNotNull</a>
> <a href="map.md">mapNotNull</a>
> <a href="minimum.md">minimum</a>
> <a href="maximum.md">maximum</a>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -915,38 +915,76 @@ public inline fun <T, D : Dimension, reified R : Any> MultiArray<T, D>.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 <T, reified R : Any> MultiArray<T, D1>.mapIndexedNotNull(transform: (index: Int, T) -> R?): D1Array<R> {
val newDtype = DataType.ofKClass(R::class)
val data = initMemoryView<R>(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 <T, D : Dimension, reified R : Any> MultiArray<T, D>.mapMultiIndexedNotNull(transform: (index: IntArray, T) -> R?): NDArray<R, D> {
public inline fun <T, D : Dimension, reified R : Any> MultiArray<T, D>.mapMultiIndexedNotNull(transform: (index: IntArray, T) -> R?): D1Array<R> {
val newDtype = DataType.ofKClass(R::class)
val data = initMemoryView<R>(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 <T, D : Dimension, reified R : Any> MultiArray<T, D>.mapNotNull(transform: (T) -> R?): NDArray<R, D> {
public inline fun <T, D : Dimension, reified R : Any> MultiArray<T, D>.mapNotNull(transform: (T) -> R?): D1Array<R> {
val newDtype = DataType.ofKClass(R::class)
val data = initMemoryView<R>(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)
}

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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<Int>(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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
}

Expand Down
Loading