remaining docs for Nulls.kt

Author: Jolanrensen

core/build.gradle.kts

@@ -14,8 +14,8 @@ plugins {
     id("org.jetbrains.kotlinx.kover")
     id("org.jmailen.kotlinter")
     id("org.jetbrains.kotlinx.dataframe")
-    id("com.github.jolanrensen.docProcessorGradlePlugin") version "v0.1.0"
-//    id("nl.jolanrensen.docProcessor") version "1.0-SNAPSHOT"
+//    id("com.github.jolanrensen.docProcessorGradlePlugin") version "v0.1.0"
+    id("nl.jolanrensen.docProcessor") version "0.1.1"
 }
 
 group = "org.jetbrains.kotlinx"

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/DataColumnArithmetics.kt

@@ -108,4 +108,4 @@ public infix fun <T> DataColumn<T>.neq(value: T): DataColumn<Boolean> = isMatchi
 public infix fun <T : Comparable<T>> DataColumn<T>.gt(value: T): DataColumn<Boolean> = isMatching { it > value }
 public infix fun <T : Comparable<T>> DataColumn<T>.lt(value: T): DataColumn<Boolean> = isMatching { it < value }
 
-internal infix fun <T> DataColumn<T>.isMatching(predicate: Predicate<T>): DataColumn<Boolean> = map { predicate(it) }
+internal fun <T> DataColumn<T>.isMatching(predicate: Predicate<T>): DataColumn<Boolean> = map { predicate(it) }

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/Nulls.kt

@@ -2,14 +2,22 @@ package org.jetbrains.kotlinx.dataframe.api
 
 import org.jetbrains.kotlinx.dataframe.ColumnsSelector
 import org.jetbrains.kotlinx.dataframe.DataFrame
+import org.jetbrains.kotlinx.dataframe.columns.ColumnReference
 import org.jetbrains.kotlinx.dataframe.impl.api.flattenImpl
+import org.jetbrains.kotlinx.dataframe.impl.columns.toColumns
+import kotlin.reflect.KProperty
 
 // region DataFrame
 
 public fun <T> DataFrame<T>.flatten(): DataFrame<T> = flatten { all() }
 
-public fun <T, C> DataFrame<T>.flatten(
-    columns: ColumnsSelector<T, C>
-): DataFrame<T> = flattenImpl(columns)
+public fun <T, C> DataFrame<T>.flatten(columns: ColumnsSelector<T, C>): DataFrame<T> = flattenImpl(columns)
+
+public fun <T> DataFrame<T>.flatten(vararg columns: String): DataFrame<T> = flattenImpl { columns.toColumns() }
+
+public fun <T, C> DataFrame<T>.flatten(vararg columns: KProperty<C>): DataFrame<T> = flattenImpl { columns.toColumns() }
+
+public fun <T, C> DataFrame<T>.flatten(vararg columns: ColumnReference<C>): DataFrame<T> =
+    flattenImpl { columns.toColumns() }
 
 // endregion

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/flatten.kt

@@ -22,12 +22,12 @@ public fun <T> DataFrame<T>.group(vararg columns: KProperty<*>): GroupClause<T,
 @JvmName("intoString")
 @OverloadResolutionByLambdaReturnType
 @OptIn(ExperimentalTypeInference::class)
-public infix fun <T, C> GroupClause<T, C>.into(column: ColumnsSelectionDsl<T>.(ColumnWithPath<C>) -> String): DataFrame<T> = df.move(columns).under { column(it).toColumnAccessor() }
+public fun <T, C> GroupClause<T, C>.into(column: ColumnsSelectionDsl<T>.(ColumnWithPath<C>) -> String): DataFrame<T> = df.move(columns).under { column(it).toColumnAccessor() }
 
 @JvmName("intoColumn")
-public infix fun <T, C> GroupClause<T, C>.into(column: ColumnsSelectionDsl<T>.(ColumnWithPath<C>) -> AnyColumnReference): DataFrame<T> = df.move(columns).under(column)
-public infix fun <T, C> GroupClause<T, C>.into(column: String): DataFrame<T> = into(columnGroup().named(column))
-public infix fun <T, C> GroupClause<T, C>.into(column: AnyColumnGroupAccessor): DataFrame<T> = df.move(columns).under(column)
-public infix fun <T, C> GroupClause<T, C>.into(column: KProperty<*>): DataFrame<T> = into(column.columnName)
+public fun <T, C> GroupClause<T, C>.into(column: ColumnsSelectionDsl<T>.(ColumnWithPath<C>) -> AnyColumnReference): DataFrame<T> = df.move(columns).under(column)
+public fun <T, C> GroupClause<T, C>.into(column: String): DataFrame<T> = into(columnGroup().named(column))
+public fun <T, C> GroupClause<T, C>.into(column: AnyColumnGroupAccessor): DataFrame<T> = df.move(columns).under(column)
+public fun <T, C> GroupClause<T, C>.into(column: KProperty<*>): DataFrame<T> = into(column.columnName)
 
 // endregion

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/group.kt

@@ -340,7 +340,7 @@ public fun <T, C> Update<T, C>.at(rowRange: IntRange): Update<T, C> = where { in
  *  - [Update per col][org.jetbrains.kotlinx.dataframe.api.Update.perCol] to provide a new value for every selected cell giving its column.
  * @param expression The [Row Column Expression][org.jetbrains.kotlinx.dataframe.documentation.ExpressionsGivenRowAndColumn.RowColumnExpression] to provide a new value for every selected cell giving its row and column.
  */
-public infix fun <T, C> Update<T, C>.perRowCol(expression: RowColumnExpression<T, C, C>): DataFrame<T> =
+public fun <T, C> Update<T, C>.perRowCol(expression: RowColumnExpression<T, C, C>): DataFrame<T> =
     updateImpl { row, column, _ -> expression(row, column) }
 
 /** [Update per row col][Update.perRowCol] to provide a new value for every selected cell giving its row and column. */
@@ -374,7 +374,7 @@ public typealias UpdateExpression<T, C, R> = AddDataRow<T>.(C) -> R
  * - [Update per row col][org.jetbrains.kotlinx.dataframe.api.Update.perRowCol] to provide a new value for every selected cell giving its row and column.
  * @param expression The [Row Value Expression][org.jetbrains.kotlinx.dataframe.documentation.ExpressionsGivenRow.RowValueExpression.WithExample] to update the rows with.
  */
-public infix fun <T, C> Update<T, C>.with(expression: UpdateExpression<T, C, C?>): DataFrame<T> =
+public fun <T, C> Update<T, C>.with(expression: UpdateExpression<T, C, C?>): DataFrame<T> =
     updateImpl { row, _, value ->
         expression(row, value)
     }
@@ -394,7 +394,7 @@ private interface SeeAlsoWith
  * .`[asFrame][org.jetbrains.kotlinx.dataframe.api.asFrame]}
  * @param expression The [Data Frame Expression][org.jetbrains.kotlinx.dataframe.documentation.ExpressionsGivenDataFrame.DataFrameExpression] to replace the selected column group with.
  */
-public infix fun <T, C, R> Update<T, DataRow<C>>.asFrame(expression: DataFrameExpression<C, DataFrame<R>>): DataFrame<T> =
+public fun <T, C, R> Update<T, DataRow<C>>.asFrame(expression: DataFrameExpression<C, DataFrame<R>>): DataFrame<T> =
     asFrameImpl(expression)
 
 @Deprecated(
@@ -758,4 +758,4 @@ public fun <T, C> Update<T, C>.withZero(): DataFrame<T> = updateWithValuePerColu
  *
  * @param value The value to set the selected rows to. In contrast to [with][Update.with], this must be the same exact type.
  */
-public infix fun <T, C> Update<T, C>.withValue(value: C): DataFrame<T> = with { value }
+public fun <T, C> Update<T, C>.withValue(value: C): DataFrame<T> = with { value }

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/update.kt

@@ -261,7 +261,7 @@ internal fun String.escapeHTML(): String {
     val str = this
     return buildString {
         for (c in str) {
-            if (c.code > 127 || c == '"' || c == '\'' || c == '<' || c == '>' || c == '&') {
+            if (c.code > 127 || c == '"' || c == '\'' || c == '<' || c == '>' || c == '&' || c == '\\') {
                 append("&#")
                 append(c.code)
                 append(';')

core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/html.kt

@@ -10,6 +10,7 @@ import org.jetbrains.kotlinx.dataframe.impl.columns.toColumns
 import kotlin.reflect.KProperty
 
 /**
+ * ## `NaN`
  * [Floats][Float] or [Doubles][Double] can be represented as [Float.NaN] or [Double.NaN], respectively,
  * in cases where a mathematical operation is undefined, such as dividing by zero.
  *
@@ -21,6 +22,7 @@ import kotlin.reflect.KProperty
 internal interface NaN
 
 /**
+ * ## `NA`
  * `NA` in Dataframe can be seen as "[NaN] or `null`".
  *
  * [Floats][Float] or [Doubles][Double] can be represented as [Float.NaN] or [Double.NaN], respectively,
@@ -263,13 +265,21 @@ public fun <T, C> DataFrame<T>.fillNA(columns: Iterable<ColumnReference<C>>): Up
 /** @param columns The {@include [SelectingColumns.DslLink]} used to select the columns of this [DataFrame] to drop rows in. */
 private interface DropDslParam
 
+/** @param columns The {@include [SelectingColumns.KPropertiesLink]} used to select the columns of this [DataFrame] to drop rows in. */
+private interface DropKPropertiesParam
+
+/** @param columns The {@include [SelectingColumns.ColumnNamesLink]} used to select the columns of this [DataFrame] to drop rows in. */
+private interface DropColumnNamesParam
+
+/** @param columns The {@include [SelectingColumns.ColumnAccessors]} used to select the columns of this [DataFrame] to drop rows in. */
+private interface DropColumnAccessorsParam
 
 // region dropNulls
 
 /**
  * ## The Drop Nulls Operation
  *
- * Removes rows with `null` values.
+ * Removes rows with `null` values. Specific case of [drop][DataFrame.drop].
  *
  * Optionally, you can select which columns to operate on (see {@include [SelectingColumnsLink]}).
  * Also, you can supply `whereAllNull = true` to only drop rows where all selected cells are `null`. By default,
@@ -300,7 +310,6 @@ private interface CommonDropNullsFunctionDoc
  * @include [CommonDropNullsFunctionDoc]
  * @include [SelectingColumns.Dsl.WithExample] {@include [SetDropNullsOperationArg]}
  * `df.`[dropNulls][dropNulls]`(whereAllNull = true) { `[colsOf][colsOf]`<`[Double][Double]`>() }`
- *
  * @include [DropNulls.WhereAllNullParam]
  * @include [DropDslParam]
  */
@@ -323,7 +332,7 @@ public fun <T> DataFrame<T>.dropNulls(whereAllNull: Boolean = false): DataFrame<
  * @include [SelectingColumns.KProperties.WithExample] {@include [SetDropNullsOperationArg]}
  * `df.`[dropNulls][dropNulls]`(Person::length, whereAllNull = true)`
  * @include [DropNulls.WhereAllNullParam]
- * @include [DropDslParam]
+ * @include [DropKPropertiesParam]
  */
 public fun <T> DataFrame<T>.dropNulls(vararg columns: KProperty<*>, whereAllNull: Boolean = false): DataFrame<T> =
     dropNulls(whereAllNull) { columns.toColumns() }
@@ -333,7 +342,7 @@ public fun <T> DataFrame<T>.dropNulls(vararg columns: KProperty<*>, whereAllNull
  * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetDropNullsOperationArg]}
  * `df.`[dropNulls][dropNulls]`("length", whereAllNull = true)`
  * @include [DropNulls.WhereAllNullParam]
- * @include [DropDslParam]
+ * @include [DropColumnNamesParam]
  */
 public fun <T> DataFrame<T>.dropNulls(vararg columns: String, whereAllNull: Boolean = false): DataFrame<T> =
     dropNulls(whereAllNull) { columns.toColumns() }
@@ -343,7 +352,7 @@ public fun <T> DataFrame<T>.dropNulls(vararg columns: String, whereAllNull: Bool
  * @include [SelectingColumns.ColumnAccessors.WithExample] {@include [SetDropNullsOperationArg]}
  * `df.`[dropNulls][dropNulls]`(length, whereAllNull = true)`
  * @include [DropNulls.WhereAllNullParam]
- * @include [DropDslParam]
+ * @include [DropColumnAccessorsParam]
  */
 public fun <T> DataFrame<T>.dropNulls(vararg columns: AnyColumnReference, whereAllNull: Boolean = false): DataFrame<T> =
     dropNulls(whereAllNull) { columns.toColumns() }
@@ -353,7 +362,7 @@ public fun <T> DataFrame<T>.dropNulls(vararg columns: AnyColumnReference, whereA
  */
 public fun <T> DataFrame<T>.dropNulls(
     columns: Iterable<AnyColumnReference>,
-    whereAllNull: Boolean = false
+    whereAllNull: Boolean = false,
 ): DataFrame<T> =
     dropNulls(whereAllNull) { columns.toColumnSet() }
 
@@ -369,28 +378,98 @@ public fun <T> DataColumn<T?>.dropNulls(): DataColumn<T> =
 
 // region dropNA
 
-public fun <T> DataFrame<T>.dropNA(whereAllNA: Boolean = false, selector: ColumnsSelector<T, *>): DataFrame<T> {
-    val columns = this[selector]
+/**
+ * ## The Drop `NA` Operation
+ *
+ * Removes rows with [`NA`][NA] values. Specific case of [drop][DataFrame.drop].
+ *
+ * Optionally, you can select which columns to operate on (see {@include [SelectingColumnsLink]}).
+ * Also, you can supply `whereAllNA = true` to only drop rows where all selected cells are [`NA`][NA]. By default,
+ * rows are dropped if any of the selected cells are [`NA`][NA].
+ *
+ * For more information: {@include [DocumentationUrls.Drop.DropNA]}
+ */
+internal interface DropNA {
+
+    /**
+     * @param whereAllNA `false` by default.
+     *   If `true`, rows are dropped if all selected cells are [`NA`][NA].
+     *   If `false`, rows are dropped if any of the selected cells is [`NA`][NA].
+     */
+    interface WhereAllNAParam
+}
+
+/** {@arg [SelectingColumns.OperationArg] [dropNA][dropNA]} */
+private interface SetDropNAOperationArg
+
+/**
+ * @include [DropNA] {@comment Description of the dropNA operation.}
+ * ## This Drop NA Overload
+ */
+private interface CommonDropNAFunctionDoc
 
-    return if (whereAllNA) drop { columns.all { this[it].isNA } }
-    else drop { columns.any { this[it].isNA } }
+/**
+ * @include [CommonDropNAFunctionDoc]
+ * @include [SelectingColumns.Dsl.WithExample] {@include [SetDropNAOperationArg]}
+ * `df.`[dropNA][dropNA]`(whereAllNA = true) { `[colsOf][colsOf]`<`[Double][Double]`>() }`
+ * @include [DropNA.WhereAllNAParam]
+ * @include [DropDslParam]
+ */
+public fun <T> DataFrame<T>.dropNA(whereAllNA: Boolean = false, columns: ColumnsSelector<T, *>): DataFrame<T> {
+    val cols = this[columns]
+    return if (whereAllNA) drop { cols.all { this[it].isNA } }
+    else drop { cols.any { this[it].isNA } }
 }
 
+/**
+ * @include [CommonDropNAFunctionDoc]
+ * @include [SelectingColumns.KProperties.WithExample] {@include [SetDropNAOperationArg]}
+ * `df.`[dropNA][dropNA]`(Person::length, whereAllNA = true)`
+ * @include [DropNA.WhereAllNAParam]
+ * @include [DropKPropertiesParam]
+ */
 public fun <T> DataFrame<T>.dropNA(vararg columns: KProperty<*>, whereAllNA: Boolean = false): DataFrame<T> =
     dropNA(whereAllNA) { columns.toColumns() }
 
+/**
+ * @include [CommonDropNAFunctionDoc]
+ * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetDropNAOperationArg]}
+ * `df.`[dropNA][dropNA]`("length", whereAllNA = true)`
+ * @include [DropNA.WhereAllNAParam]
+ * @include [DropColumnNamesParam]
+ */
 public fun <T> DataFrame<T>.dropNA(vararg columns: String, whereAllNA: Boolean = false): DataFrame<T> =
     dropNA(whereAllNA) { columns.toColumns() }
 
+/**
+ * @include [CommonDropNAFunctionDoc]
+ * @include [SelectingColumns.ColumnAccessors.WithExample] {@include [SetDropNAOperationArg]}
+ * `df.`[dropNA][dropNA]`(length, whereAllNA = true)`
+ * @include [DropNA.WhereAllNAParam]
+ * @include [DropColumnAccessorsParam]
+ */
 public fun <T> DataFrame<T>.dropNA(vararg columns: AnyColumnReference, whereAllNA: Boolean = false): DataFrame<T> =
     dropNA(whereAllNA) { columns.toColumns() }
 
+/**
+ * TODO will be deprecated
+ */
 public fun <T> DataFrame<T>.dropNA(columns: Iterable<AnyColumnReference>, whereAllNA: Boolean = false): DataFrame<T> =
     dropNA(whereAllNA) { columns.toColumnSet() }
 
+/**
+ * @include [CommonDropNAFunctionDoc]
+ * This overload operates on all columns in the [DataFrame].
+ * @include [DropNA.WhereAllNAParam]
+ */
 public fun <T> DataFrame<T>.dropNA(whereAllNA: Boolean = false): DataFrame<T> =
     dropNA(whereAllNA) { all() }
 
+/**
+ * ## The Drop `NA` Operation
+ *
+ * Removes [`NA`][NA] values from this [DataColumn], adjusting the type accordingly.
+ */
 public fun <T> DataColumn<T?>.dropNA(): DataColumn<T> =
     when (typeClass) {
         Double::class, Float::class -> filter { !it.isNA }.cast()
@@ -401,28 +480,98 @@ public fun <T> DataColumn<T?>.dropNA(): DataColumn<T> =
 
 // region dropNaNs
 
-public fun <T> DataFrame<T>.dropNaNs(whereAllNaN: Boolean = false, selector: ColumnsSelector<T, *>): DataFrame<T> {
-    val cols = this[selector]
+/**
+ * ## The Drop `NaN` Operation
+ *
+ * Removes rows with [`NaN`][Double.isNaN] values. Specific case of [drop][DataFrame.drop].
+ *
+ * Optionally, you can select which columns to operate on (see {@include [SelectingColumnsLink]}).
+ * Also, you can supply `whereAllNaN = true` to only drop rows where all selected cells are [`NaN`][Double.isNaN]. By default,
+ * rows are dropped if any of the selected cells are [`NaN`][Double.isNaN].
+ *
+ * For more information: {@include [DocumentationUrls.Drop.DropNaNs]}
+ */
+internal interface DropNaNs {
+
+    /**
+     * @param whereAllNaN `false` by default.
+     *   If `true`, rows are dropped if all selected cells are [`NaN`][Double.isNaN].
+     *   If `false`, rows are dropped if any of the selected cells is [`NaN`][Double.isNaN].
+     */
+    interface WhereAllNaNParam
+}
+
+/** {@arg [SelectingColumns.OperationArg] [dropNaNs][dropNaNs]} */
+private interface SetDropNaNsOperationArg
 
+/**
+ * @include [DropNaNs] {@comment Description of the dropNaNs operation.}
+ * ## This Drop NaNs Overload
+ */
+private interface CommonDropNaNsFunctionDoc
+
+/**
+ * @include [CommonDropNaNsFunctionDoc]
+ * @include [SelectingColumns.Dsl.WithExample] {@include [SetDropNaNsOperationArg]}
+ * `df.`[dropNaNs][dropNaNs]`(whereAllNaN = true) { `[colsOf][colsOf]`<`[Double][Double]`>() }`
+ * @include [DropNaNs.WhereAllNaNParam]
+ * @include [DropDslParam]
+ */
+public fun <T> DataFrame<T>.dropNaNs(whereAllNaN: Boolean = false, columns: ColumnsSelector<T, *>): DataFrame<T> {
+    val cols = this[columns]
     return if (whereAllNaN) drop { cols.all { this[it].isNaN } }
     else drop { cols.any { this[it].isNaN } }
 }
 
-public fun <T> DataFrame<T>.dropNaNs(vararg cols: KProperty<*>, whereAllNaN: Boolean = false): DataFrame<T> =
-    dropNaNs(whereAllNaN) { cols.toColumns() }
+/**
+ * @include [CommonDropNaNsFunctionDoc]
+ * @include [SelectingColumns.KProperties.WithExample] {@include [SetDropNaNsOperationArg]}
+ * `df.`[dropNaNs][dropNaNs]`(Person::length, whereAllNaN = true)`
+ * @include [DropNaNs.WhereAllNaNParam]
+ * @include [DropKPropertiesParam]
+ */
+public fun <T> DataFrame<T>.dropNaNs(vararg columns: KProperty<*>, whereAllNaN: Boolean = false): DataFrame<T> =
+    dropNaNs(whereAllNaN) { columns.toColumns() }
 
-public fun <T> DataFrame<T>.dropNaNs(vararg cols: String, whereAllNaN: Boolean = false): DataFrame<T> =
-    dropNaNs(whereAllNaN) { cols.toColumns() }
+/**
+ * @include [CommonDropNaNsFunctionDoc]
+ * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetDropNaNsOperationArg]}
+ * `df.`[dropNaNs][dropNaNs]`("length", whereAllNaN = true)`
+ * @include [DropNaNs.WhereAllNaNParam]
+ * @include [DropColumnNamesParam]
+ */
+public fun <T> DataFrame<T>.dropNaNs(vararg columns: String, whereAllNaN: Boolean = false): DataFrame<T> =
+    dropNaNs(whereAllNaN) { columns.toColumns() }
 
-public fun <T> DataFrame<T>.dropNaNs(vararg cols: AnyColumnReference, whereAllNaN: Boolean = false): DataFrame<T> =
-    dropNaNs(whereAllNaN) { cols.toColumns() }
+/**
+ * @include [CommonDropNaNsFunctionDoc]
+ * @include [SelectingColumns.ColumnAccessors.WithExample] {@include [SetDropNaNsOperationArg]}
+ * `df.`[dropNaNs][dropNaNs]`(length, whereAllNaN = true)`
+ * @include [DropNaNs.WhereAllNaNParam]
+ * @include [DropColumnAccessorsParam]
+ */
+public fun <T> DataFrame<T>.dropNaNs(vararg columns: AnyColumnReference, whereAllNaN: Boolean = false): DataFrame<T> =
+    dropNaNs(whereAllNaN) { columns.toColumns() }
 
-public fun <T> DataFrame<T>.dropNaNs(cols: Iterable<AnyColumnReference>, whereAllNaN: Boolean = false): DataFrame<T> =
-    dropNaNs(whereAllNaN) { cols.toColumnSet() }
+/**
+ * TODO will be deprecated
+ */
+public fun <T> DataFrame<T>.dropNaNs(columns: Iterable<AnyColumnReference>, whereAllNaN: Boolean = false): DataFrame<T> =
+    dropNaNs(whereAllNaN) { columns.toColumnSet() }
 
+/**
+ * @include [CommonDropNaNsFunctionDoc]
+ * This overload operates on all columns in the [DataFrame].
+ * @include [DropNaNs.WhereAllNaNParam]
+ */
 public fun <T> DataFrame<T>.dropNaNs(whereAllNaN: Boolean = false): DataFrame<T> =
     dropNaNs(whereAllNaN) { all() }
 
+/**
+ * ## The Drop `NaN` Operation
+ *
+ * Removes [`NaN`][NaN] values from this [DataColumn], adjusting the type accordingly.
+ */
 public fun <T> DataColumn<T>.dropNaNs(): DataColumn<T> =
     when (typeClass) {
         Double::class, Float::class -> filter { !it.isNaN }.cast()