Rename DataFrame.map overloads into DataFrame.mapToColumns and DataFrame.mapToFrame. Add DataFrame.map that returns List. Add name argument to DataColumn.map.

Author: nikitinas

docs/StardustDocs/topics/map.md

@@ -2,7 +2,23 @@
 
 <!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Modify-->
 
-Creates `DataFrame` or `DataColumn` with values computed from rows of original `DataFrame`.
+Creates `List`, [DataFrame](DataFrame.md) or [DataColumn](DataColumn.md) with values computed from rows of original `DataFrame`.
+
+**Map into `List`:**
+
+```text
+map { transform }: List<T>
+
+transform: (DataRow) -> T
+```
+
+<!---FUN map-->
+
+```kotlin
+df.map { 2021 - it.age }
+```
+
+<!---END-->
 
 **Map into `DataColumn`:**
 
@@ -12,6 +28,34 @@ map(columnName) { rowExpression }: DataColumn
 rowExpression: DataRow.(DataRow) -> Value
 ```
 
+<!---FUN mapToColumn-->
+<tabs>
+<tab title="Properties">
+
+```kotlin
+df.mapToColumn("year of birth") { 2021 - age }
+```
+
+</tab>
+<tab title="Accessors">
+
+```kotlin
+val age by column<Int>()
+val yearOfBirth by column<Int>("year of birth")
+
+df.mapToColumn(yearOfBirth) { 2021 - age }
+```
+
+</tab>
+<tab title="Strings">
+
+```kotlin
+df.mapToColumn("year of birth") { 2021 - "age"<Int>() }
+```
+
+</tab></tabs>
+<!---END-->
+
 See [row expressions](DataRow.md#row-expressions)
 
 **Map into `DataFrame`:**
@@ -31,7 +75,7 @@ columnMapping = column into columnName | columnName from column | columnName fro
 <tab title="Properties">
 
 ```kotlin
-df.map {
+df.mapToFrame {
     "year of birth" from 2021 - age
     age gt 18 into "is adult"
     name.lastName.length() into "last name length"
@@ -54,7 +98,7 @@ val firstName by name.column<String>()
 val lastName by name.column<String>()
 val city by column<String?>()
 
-df.map {
+df.mapToFrame {
     yob from 2021 - age
     age gt 18 into isAdult
     lastName.length() into lastNameLength
@@ -67,7 +111,7 @@ df.map {
 <tab title="Strings">
 
 ```kotlin
-df.map {
+df.mapToFrame {
     "year of birth" from 2021 - "age"<Int>()
     "age"<Int>() gt 18 into "is adult"
     "name"["lastName"]<String>().length() into "last name length"

examples/jupyter-notebooks/github/github.ipynb

@@ -1292,7 +1292,7 @@
     }
    ],
    "source": [
-    "val df = jbRepos.map { \n",
+    "val df = jbRepos.mapToFrame { \n",
     "    \"id\" from { id }\n",
     "    +name\n",
     "    \"total\" from  { contributors.count() }\n",
@@ -1584,7 +1584,7 @@
     }
    ],
    "source": [
-    "organizations.map(\"most_starred_repo\") {\n",
+    "organizations.mapToColumn(\"most_starred_repo\") {\n",
     "    it.repos.maxBy { stargazers_count }\n",
     "}"
    ]
@@ -1693,7 +1693,7 @@
     }
    ],
    "source": [
-    "organizations.map(\"most_starred_repo\") {\n",
+    "organizations.mapToColumn(\"most_starred_repo\") {\n",
     "    // Alternative syntax\n",
     "    // this.repos.maxBy { stargazers_count }\n",
     "    // it.repos.maxBy { stargazers_count }\n",
@@ -1800,7 +1800,7 @@
     }
    ],
    "source": [
-    "organizations.map(\"most_starred_repo\") {\n",
+    "organizations.mapToColumn(\"most_starred_repo\") {\n",
     "    repos.select { name and html_url and stargazers_count }.maxBy { stargazers_count }\n",
     "}"
    ]
@@ -1858,7 +1858,7 @@
     }
    ],
    "source": [
-    "organizations.map { \n",
+    "organizations.mapToFrame { \n",
     "    \"most_starred_repo\" from { \n",
     "        repos\n",
     "            .select { name and html_url and stargazers_count }\n",
@@ -1979,7 +1979,7 @@
     }
    ],
    "source": [
-    "organizationsWithMinifiedRepos.map { \n",
+    "organizationsWithMinifiedRepos.mapToFrame { \n",
     "    \"most_starred_repo\" from { \n",
     "        repos.maxBy { stargazers_count } \n",
     "    }\n",
@@ -2042,7 +2042,7 @@
     }
    ],
    "source": [
-    "organizationsWithMinifiedRepos.map(\"interesting_repos\") {\n",
+    "organizationsWithMinifiedRepos.mapToColumn(\"interesting_repos\") {\n",
     "    val sorted = repos.sortByDesc { stargazers_count }\n",
     "    sorted.take(5).concat(sorted.takeLast(5))\n",
     "}"

examples/jupyter-notebooks/puzzles/40 puzzles.ipynb

@@ -1673,7 +1673,7 @@
     }
    ],
    "source": [
-    "df.map(\"res\") { \n",
+    "df.mapToColumn(\"res\") { \n",
     "    namedValuesOf<Double>()\n",
     "        .filter { it.value.isNaN() }.drop(2)\n",
     "        .firstOrNull()?.name \n",
@@ -2021,7 +2021,7 @@
     }
    ],
    "source": [
-    "df.map(\"Y\") {\n",
+    "df.mapToColumn(\"Y\") {\n",
     "    if(it.X == 0) 0 else (prev()?.new() ?: 0) + 1\n",
     "}"
    ]
@@ -3118,4 +3118,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 1
-}
+}

src/main/kotlin/org/jetbrains/kotlinx/dataframe/DataColumn.kt

@@ -5,7 +5,7 @@ import org.jetbrains.kotlinx.dataframe.api.asDataColumn
 import org.jetbrains.kotlinx.dataframe.api.cast
 import org.jetbrains.kotlinx.dataframe.api.concat
 import org.jetbrains.kotlinx.dataframe.api.filter
-import org.jetbrains.kotlinx.dataframe.api.map
+import org.jetbrains.kotlinx.dataframe.api.mapToFrame
 import org.jetbrains.kotlinx.dataframe.api.schema
 import org.jetbrains.kotlinx.dataframe.api.take
 import org.jetbrains.kotlinx.dataframe.columns.BaseColumn

src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl.kt

@@ -341,7 +341,7 @@ public inline fun <T, reified R> ColumnsSelectionDsl<T>.expr(
     name: String = "",
     infer: Infer = Infer.Nulls,
     noinline expression: AddExpression<T, R>
-): DataColumn<R> = map(name, infer, expression)
+): DataColumn<R> = mapToColumn(name, infer, expression)
 
 internal fun <T, C> ColumnsSelector<T, C>.filter(predicate: (ColumnWithPath<C>) -> Boolean): ColumnsSelector<T, C> =
     { this@filter(it, it).filter(predicate) }

src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/add.kt

@@ -9,6 +9,7 @@ import org.jetbrains.kotlinx.dataframe.ColumnsContainer
 import org.jetbrains.kotlinx.dataframe.DataFrame
 import org.jetbrains.kotlinx.dataframe.DataRow
 import org.jetbrains.kotlinx.dataframe.RowExpression
+import org.jetbrains.kotlinx.dataframe.Selector
 import org.jetbrains.kotlinx.dataframe.columns.ColumnAccessor
 import org.jetbrains.kotlinx.dataframe.columns.ColumnPath
 import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
@@ -32,21 +33,21 @@ internal class AddDataRowImpl<T>(index: Int, owner: DataFrame<T>, private val co
     override fun <C> AnyRow.new() = container[index] as C
 }
 
-public typealias AddExpression<T, C> = AddDataRow<T>.(AddDataRow<T>) -> C
+public typealias AddExpression<T, C> = Selector<AddDataRow<T>, C>
 
 public inline fun <reified R, T> DataFrame<T>.add(
     name: String,
     infer: Infer = Infer.Nulls,
     noinline expression: AddExpression<T, R>
 ): DataFrame<T> =
-    (this + map(name, infer, expression))
+    (this + mapToColumn(name, infer, expression))
 
 public inline fun <reified R, T> DataFrame<T>.add(
     property: KProperty<R>,
     infer: Infer = Infer.Nulls,
     noinline expression: AddExpression<T, R>
 ): DataFrame<T> =
-    (this + map(property, infer, expression))
+    (this + mapToColumn(property, infer, expression))
 
 public inline fun <reified R, T> DataFrame<T>.add(
     column: ColumnAccessor<R>,
@@ -60,7 +61,7 @@ public inline fun <reified R, T> DataFrame<T>.add(
     infer: Infer = Infer.Nulls,
     noinline expression: AddExpression<T, R>
 ): DataFrame<T> {
-    val col = map(path.name(), infer, expression)
+    val col = mapToColumn(path.name(), infer, expression)
     if (path.size == 1) return this + col
     return insertImpl(path, col)
 }
@@ -103,7 +104,7 @@ public class AddDsl<T>(@PublishedApi internal val df: DataFrame<T>) : ColumnsCon
         name: String,
         infer: Infer = Infer.Nulls,
         noinline expression: RowExpression<T, R>
-    ): Boolean = add(df.map(name, infer, expression))
+    ): Boolean = add(df.mapToColumn(name, infer, expression))
 
     public inline infix fun <reified R> String.from(noinline expression: RowExpression<T, R>): Boolean = add(this, Infer.Nulls, expression)
 

src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt

@@ -180,9 +180,11 @@ public fun DataColumn<Long>.convertToLocalDate(zone: TimeZone = defaultTimeZone)
 public fun DataColumn<Long?>.convertToLocalDate(zone: TimeZone = defaultTimeZone): DataColumn<LocalDate?> = map { it?.toLocalDate(zone) }
 
 @JvmName("convertToLocalDateFromInt")
-public fun DataColumn<Int>.convertToLocalDate(zone: TimeZone = defaultTimeZone): DataColumn<LocalDate> = map { it.toLong().toLocalDate(zone) }
+public fun DataColumn<Int>.convertToLocalDate(zone: TimeZone = defaultTimeZone): DataColumn<LocalDate> =
+    map { it.toLong().toLocalDate(zone) }
 @JvmName("convertToLocalDateFromIntNullable")
-public fun DataColumn<Int?>.convertToLocalDate(zone: TimeZone = defaultTimeZone): DataColumn<LocalDate?> = map { it?.toLong()?.toLocalDate(zone) }
+public fun DataColumn<Int?>.convertToLocalDate(zone: TimeZone = defaultTimeZone): DataColumn<LocalDate?> =
+    map { it?.toLong()?.toLocalDate(zone) }
 
 @JvmName("convertToLocalDateFromString")
 public fun DataColumn<String>.convertToLocalDate(pattern: String? = null, locale: Locale? = null): DataColumn<LocalDate> {
@@ -213,9 +215,11 @@ public fun DataColumn<Long>.convertToLocalTime(zone: TimeZone = defaultTimeZone)
 public fun DataColumn<Long?>.convertToLocalTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalTime?> = map { it?.toLocalTime(zone) }
 
 @JvmName("convertToLocalTimeFromInt")
-public fun DataColumn<Int>.convertToLocalTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalTime> = map { it.toLong().toLocalTime(zone) }
+public fun DataColumn<Int>.convertToLocalTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalTime> =
+    map { it.toLong().toLocalTime(zone) }
 @JvmName("convertToLocalTimeIntNullable")
-public fun DataColumn<Int?>.convertToLocalTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalTime?> = map { it?.toLong()?.toLocalTime(zone) }
+public fun DataColumn<Int?>.convertToLocalTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalTime?> =
+    map { it?.toLong()?.toLocalTime(zone) }
 
 @JvmName("convertToLocalTimeFromString")
 public fun DataColumn<String>.convertToLocalTime(pattern: String? = null, locale: Locale? = null): DataColumn<LocalTime> {
@@ -246,14 +250,18 @@ public fun DataColumn<Long>.convertToLocalDateTime(zone: TimeZone = defaultTimeZ
 public fun DataColumn<Long?>.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalDateTime?> = map { it?.toLocalDateTime(zone) }
 
 @JvmName("convertToLocalDateTimeFromInstant")
-public fun DataColumn<Instant>.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalDateTime> = map { it.toLocalDateTime(zone) }
+public fun DataColumn<Instant>.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalDateTime> =
+    map { it.toLocalDateTime(zone) }
 @JvmName("convertToLocalDateTimeFromInstantNullable")
-public fun DataColumn<Instant?>.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalDateTime?> = map { it?.toLocalDateTime(zone) }
+public fun DataColumn<Instant?>.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalDateTime?> =
+    map { it?.toLocalDateTime(zone) }
 
 @JvmName("convertToLocalDateTimeFromInt")
-public fun DataColumn<Int>.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalDateTime> = map { it.toLong().toLocalDateTime(zone) }
+public fun DataColumn<Int>.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalDateTime> =
+    map { it.toLong().toLocalDateTime(zone) }
 @JvmName("convertToLocalDateTimeFromIntNullable")
-public fun DataColumn<Int?>.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalDateTime?> = map { it?.toLong()?.toLocalDateTime(zone) }
+public fun DataColumn<Int?>.convertToLocalDateTime(zone: TimeZone = defaultTimeZone): DataColumn<LocalDateTime?> =
+    map { it?.toLong()?.toLocalDateTime(zone) }
 
 @JvmName("convertToLocalDateTimeFromString")
 public fun DataColumn<String>.convertToLocalDateTime(pattern: String? = null, locale: Locale? = null): DataColumn<LocalDateTime> {

src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/insert.kt

@@ -17,7 +17,7 @@ public inline fun <T, reified R> DataFrame<T>.insert(
     name: String,
     infer: Infer = Infer.Nulls,
     noinline expression: RowExpression<T, R>
-): InsertClause<T> = insert(map(name, infer, expression))
+): InsertClause<T> = insert(mapToColumn(name, infer, expression))
 
 public inline fun <T, reified R> DataFrame<T>.insert(
     column: ColumnAccessor<R>,

src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/map.kt

@@ -26,15 +26,17 @@ public inline fun <C, reified R> ColumnReference<C>.map(infer: Infer = Infer.Nul
 // region DataColumn
 
 public inline fun <T, reified R> DataColumn<T>.map(
+    name: String = name(),
     infer: Infer = Infer.Nulls,
     crossinline transform: (T) -> R
 ): DataColumn<R> {
     val newValues = Array(size()) { transform(get(it)) }.asList()
-    return DataColumn.create(name(), newValues, typeOf<R>(), infer)
+    return DataColumn.create(name, newValues, typeOf<R>(), infer)
 }
 
-public fun <T, R> DataColumn<T>.mapTo(
+public fun <T, R> DataColumn<T>.map(
     type: KType,
+    name: String = name(),
     infer: Infer = Infer.Nulls,
     transform: (T) -> R
 ): DataColumn<R> {
@@ -46,29 +48,52 @@ public fun <T, R> DataColumn<T>.mapTo(
 
 // region DataFrame
 
-public fun <T> DataFrame<T>.map(body: AddDsl<T>.() -> Unit): AnyFrame {
-    val dsl = AddDsl(this)
-    body(dsl)
-    return dataFrameOf(dsl.columns)
-}
+public fun <T, R> DataFrame<T>.map(transform: (DataRow<T>) -> R): List<R> = rows().map(transform)
 
-public inline fun <T, reified R> ColumnsContainer<T>.map(
+public inline fun <T, reified R> ColumnsContainer<T>.mapToColumn(
     name: String,
     infer: Infer = Infer.Nulls,
     noinline body: AddExpression<T, R>
-): DataColumn<R> = newColumn(typeOf<R>(), name, infer, body)
+): DataColumn<R> = mapToColumn(name, typeOf<R>(), infer, body)
 
-public inline fun <T, reified R> ColumnsContainer<T>.map(
+public inline fun <T, reified R> ColumnsContainer<T>.mapToColumn(
     column: ColumnAccessor<R>,
     infer: Infer = Infer.Nulls,
     noinline body: AddExpression<T, R>
-): DataColumn<R> = map(column.name(), infer, body)
+): DataColumn<R> = mapToColumn(column, typeOf<R>(), infer, body)
 
-public inline fun <T, reified R> ColumnsContainer<T>.map(
+public inline fun <T, reified R> ColumnsContainer<T>.mapToColumn(
     column: KProperty<R>,
     infer: Infer = Infer.Nulls,
     noinline body: AddExpression<T, R>
-): DataColumn<R> = map(column.columnName, infer, body)
+): DataColumn<R> = mapToColumn(column, typeOf<R>(), infer, body)
+
+public fun <T, R> ColumnsContainer<T>.mapToColumn(
+    name: String,
+    type: KType,
+    infer: Infer = Infer.Nulls,
+    body: AddExpression<T, R>
+): DataColumn<R> = newColumn(type, name, infer, body)
+
+public fun <T, R> ColumnsContainer<T>.mapToColumn(
+    column: ColumnAccessor<R>,
+    type: KType,
+    infer: Infer = Infer.Nulls,
+    body: AddExpression<T, R>
+): DataColumn<R> = mapToColumn(column.name(), type, infer, body)
+
+public fun <T, R> ColumnsContainer<T>.mapToColumn(
+    column: KProperty<R>,
+    type: KType,
+    infer: Infer = Infer.Nulls,
+    body: AddExpression<T, R>
+): DataColumn<R> = mapToColumn(column.columnName, type, infer, body)
+
+public fun <T> DataFrame<T>.mapToFrame(body: AddDsl<T>.() -> Unit): AnyFrame {
+    val dsl = AddDsl(this)
+    body(dsl)
+    return dataFrameOf(dsl.columns)
+}
 
 // endregion