diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/drop.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/drop.kt index 4bf23e4a08..f0da4d78ac 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/drop.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/drop.kt @@ -1,6 +1,5 @@ package org.jetbrains.kotlinx.dataframe.api -import org.jetbrains.kotlinx.dataframe.ColumnFilter import org.jetbrains.kotlinx.dataframe.DataColumn import org.jetbrains.kotlinx.dataframe.DataFrame import org.jetbrains.kotlinx.dataframe.DataRow @@ -15,6 +14,9 @@ import org.jetbrains.kotlinx.dataframe.columns.SingleColumn import org.jetbrains.kotlinx.dataframe.columns.size import org.jetbrains.kotlinx.dataframe.documentation.CommonTakeAndDropDocs import org.jetbrains.kotlinx.dataframe.documentation.CommonTakeAndDropWhileDocs +import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls +import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns +import org.jetbrains.kotlinx.dataframe.documentation.SelectingRows import org.jetbrains.kotlinx.dataframe.documentation.TakeAndDropColumnsSelectionDslGrammar import org.jetbrains.kotlinx.dataframe.impl.columns.transform import org.jetbrains.kotlinx.dataframe.impl.columns.transformSingle @@ -24,8 +26,37 @@ import kotlin.reflect.KProperty // region DataColumn +/** + * Returns a [DataColumn] containing only the values that do not match the given [predicate]. + * + * For more information: {@include [DocumentationUrls.Drop]} + * + * See also: + * - [filter][DataColumn.filter] — keeps only the values that match the predicate. + * - [drop][DataColumn.drop]`(n: Int)` — drops a fixed number of first values. + * - [dropLast][DataColumn.dropLast] — drops a fixed number of last values. + * + * @param [predicate] The condition used to exclude values from this [DataColumn]. + * @return A [DataColumn] containing the values that do not match the [predicate]. + */ public inline fun DataColumn.drop(predicate: Predicate): DataColumn = filter { !predicate(it) } +/** + * Returns a [DataColumn] containing all values of this [DataColumn] except the first [n] values. + * + * If [n] is greater than or equal to the size of this [DataColumn], an empty [DataColumn] is returned. + * + * See also: + * - [dropLast][DataColumn.dropLast] — drops the last [n] values instead. + * - [take][DataColumn.take] — keeps only the first [n] values. + * - [takeLast][DataColumn.takeLast] — keeps only the last [n] values. + * - [drop][DataColumn.drop]`{ predicate: Predicate }` — drops every value that matches the predicate. + * + * @param [n] The number of values to drop. Must not be negative. + * @return A [DataColumn] containing all values of this [DataColumn] except the first [n], + * or an empty [DataColumn] if [n] is greater than or equal to its size. + * @throws [IndexOutOfBoundsException] if [n] is negative. + */ public fun DataColumn.drop(n: Int): DataColumn = when { n == 0 -> this @@ -33,6 +64,22 @@ public fun DataColumn.drop(n: Int): DataColumn = else -> get(n until size) } +/** + * Returns a [DataColumn] containing all values of this [DataColumn] except the last [n] values. + * + * If [n] is zero or negative, this [DataColumn] is returned as is. + * + * See also: + * - [drop][DataColumn.drop]`(n: Int)` — drops the first [n] values instead. + * - [takeLast][DataColumn.takeLast] — keeps only the last [n] values. + * - [take][DataColumn.take] — keeps only the first [n] values. + * - [drop][DataColumn.drop]`{ predicate: Predicate }` — drops every value that matches the predicate. + * + * @param [n] The number of values to drop. Must not exceed the size of this [DataColumn]. + * @return A [DataColumn] containing all values of this [DataColumn] except the last [n], + * or this [DataColumn] if [n] is zero or negative. + * @throws [IllegalArgumentException] if [n] is greater than the size of this [DataColumn]. + */ public fun DataColumn.dropLast(n: Int = 1): DataColumn = take(size - n) // endregion @@ -40,8 +87,19 @@ public fun DataColumn.dropLast(n: Int = 1): DataColumn = take(size - n // region DataFrame /** - * Returns a DataFrame containing all rows except first [n] rows. + * Returns a [DataFrame] containing all rows except the first [n] rows. * + * If [n] is greater than or equal to the number of rows, an empty [DataFrame] is returned. + * + * See also: + * - [dropLast][DataFrame.dropLast] — drops the last [n] rows instead. + * - [dropWhile][DataFrame.dropWhile] — drops the first rows while the predicate holds. + * - [take][DataFrame.take] — keeps only the first [n] rows. + * - [drop][DataFrame.drop]`{ predicate: RowFilter }` — drops every row that matches the predicate. + * + * @param [n] The number of rows to drop. Must not be negative. + * @return A [DataFrame] containing all rows except the first [n], + * or an empty [DataFrame] if [n] is greater than or equal to the number of rows. * @throws IllegalArgumentException if [n] is negative. */ public fun DataFrame.drop(n: Int): DataFrame { @@ -50,8 +108,19 @@ public fun DataFrame.drop(n: Int): DataFrame { } /** - * Returns a DataFrame containing all rows except last [n] rows. + * Returns a [DataFrame] containing all rows except the last [n] rows. + * + * If [n] is greater than or equal to the number of rows, an empty [DataFrame] is returned. + * + * See also: + * - [drop][DataFrame.drop]`(n: Int)` — drops the first [n] rows instead. + * - [dropWhile][DataFrame.dropWhile] — drops the first rows while the predicate holds. + * - [takeLast][DataFrame.takeLast] — keeps only the last [n] rows. + * - [drop][DataFrame.drop]`{ predicate: RowFilter }` — drops every row that matches the predicate. * + * @param [n] The number of rows to drop. Must not be negative. + * @return A [DataFrame] containing all rows except the last [n], + * or an empty [DataFrame] if [n] is greater than or equal to the number of rows. * @throws IllegalArgumentException if [n] is negative. */ public fun DataFrame.dropLast(n: Int = 1): DataFrame { @@ -60,12 +129,42 @@ public fun DataFrame.dropLast(n: Int = 1): DataFrame { } /** - * Returns a DataFrame containing all rows except rows that satisfy the given [predicate]. + * Returns a [DataFrame] containing all rows except the rows that satisfy the given [predicate]. + * + * @include [SelectingRows.RowFilterSnippet] + * + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] + * + * {@include [DocumentationUrls.Drop]} + * + * See also: + * - [filter][DataFrame.filter] — keeps only the rows that match the predicate. + * - [dropWhile][DataFrame.dropWhile] — drops only the first rows that match the predicate. + * - [drop][DataFrame.drop]`(n: Int)` — drops a fixed number of first rows. + * + * @param [predicate] The [RowFilter] used to exclude rows from this [DataFrame]. + * @return A [DataFrame] containing all rows that do not satisfy the [predicate]. */ public inline fun DataFrame.drop(predicate: RowFilter): DataFrame = filter { !predicate(it, it) } /** - * Returns a DataFrame containing all rows except first rows that satisfy the given [predicate]. + * Returns a [DataFrame] containing all rows except the first rows that satisfy the given [predicate]. + * + * Rows are dropped for as long as the [predicate] holds; the operation stops at the first row that + * does not satisfy it, and no later row is dropped even if it satisfies the [predicate]. + * + * @include [SelectingRows.RowFilterSnippet] + * + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] + * + * See also: + * - [drop][DataFrame.drop]`(n: Int)` — drops a fixed number of first rows. + * - [dropLast][DataFrame.dropLast] — drops a fixed number of last rows. + * - [takeWhile][DataFrame.takeWhile] — keeps the first rows while the predicate holds. + * - [drop][DataFrame.drop]`{ predicate: RowFilter }` — drops every row that matches the predicate. + * + * @param [predicate] The [RowFilter] that the leading rows to drop must satisfy. + * @return A [DataFrame] containing all rows except the first ones that satisfy the [predicate]. */ public inline fun DataFrame.dropWhile(predicate: RowFilter): DataFrame = firstOrNull { !predicate(it, it) }?.let { drop(it.index()) } ?: this @@ -115,6 +214,12 @@ public interface DropColumnsSelectionDsl { * @set [CommonTakeAndDropDocs.OPERATION] drop * @set [CommonTakeAndDropDocs.NOUN] drop * @set [CommonTakeAndDropDocs.FIRST_OR_LAST] first + * @set [CommonTakeAndDropDocs.SEE_ALSO] + * - [dropLast][ColumnsSelectionDsl.dropLast] — drops the last `n` columns instead. + * - [dropWhile][ColumnsSelectionDsl.dropWhile] — drops the first columns while a predicate holds. + * - [dropLastWhile][ColumnsSelectionDsl.dropLastWhile] — drops the last columns while a predicate holds. + * - [take][ColumnsSelectionDsl.take] — keeps only the first `n` columns. + * @set [CommonTakeAndDropDocs.RETURN] A [ColumnSet] containing all columns except the first [n\]. */ private typealias CommonDropFirstDocs = Nothing @@ -184,6 +289,12 @@ public interface DropColumnsSelectionDsl { * @set [CommonTakeAndDropDocs.OPERATION] dropLast * @set [CommonTakeAndDropDocs.NOUN] drop * @set [CommonTakeAndDropDocs.FIRST_OR_LAST] last + * @set [CommonTakeAndDropDocs.SEE_ALSO] + * - [drop][ColumnsSelectionDsl.drop] — drops the first `n` columns instead. + * - [dropWhile][ColumnsSelectionDsl.dropWhile] — drops the first columns while a predicate holds. + * - [dropLastWhile][ColumnsSelectionDsl.dropLastWhile] — drops the last columns while a predicate holds. + * - [takeLast][ColumnsSelectionDsl.takeLast] — keeps only the last `n` columns. + * @set [CommonTakeAndDropDocs.RETURN] A [ColumnSet] containing all columns except the last [n\]. */ private typealias CommonDropLastDocs = Nothing @@ -253,6 +364,13 @@ public interface DropColumnsSelectionDsl { * @set [CommonTakeAndDropWhileDocs.OPERATION] drop * @set [CommonTakeAndDropWhileDocs.NOUN] drop * @set [CommonTakeAndDropWhileDocs.FIRST_OR_LAST] first + * @set [CommonTakeAndDropWhileDocs.SEE_ALSO] + * - [drop][ColumnsSelectionDsl.drop] — drops a fixed number of first columns. + * - [dropLast][ColumnsSelectionDsl.dropLast] — drops a fixed number of last columns. + * - [dropLastWhile][ColumnsSelectionDsl.dropLastWhile] — drops the last columns while a predicate holds. + * - [takeWhile][ColumnsSelectionDsl.takeWhile] — keeps the first columns while a predicate holds. + * @set [CommonTakeAndDropWhileDocs.RETURN] A [ColumnSet] containing all columns except the first + * ones adhering to the [predicate\]. */ private typealias CommonDropWhileDocs = Nothing @@ -324,6 +442,13 @@ public interface DropColumnsSelectionDsl { * @set [CommonTakeAndDropWhileDocs.OPERATION] dropLast * @set [CommonTakeAndDropWhileDocs.NOUN] drop * @set [CommonTakeAndDropWhileDocs.FIRST_OR_LAST] last + * @set [CommonTakeAndDropWhileDocs.SEE_ALSO] + * - [drop][ColumnsSelectionDsl.drop] — drops a fixed number of first columns. + * - [dropLast][ColumnsSelectionDsl.dropLast] — drops a fixed number of last columns. + * - [dropWhile][ColumnsSelectionDsl.dropWhile] — drops the first columns while a predicate holds. + * - [takeLastWhile][ColumnsSelectionDsl.takeLastWhile] — keeps the last columns while a predicate holds. + * @set [CommonTakeAndDropWhileDocs.RETURN] A [ColumnSet] containing all columns except the last + * ones adhering to the [predicate\]. */ private typealias CommonDropLastWhileDocs = Nothing diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/take.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/take.kt index 760c3bdbe7..a2b4bd3c07 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/take.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/take.kt @@ -1,6 +1,5 @@ package org.jetbrains.kotlinx.dataframe.api -import org.jetbrains.kotlinx.dataframe.ColumnFilter import org.jetbrains.kotlinx.dataframe.DataColumn import org.jetbrains.kotlinx.dataframe.DataFrame import org.jetbrains.kotlinx.dataframe.DataRow @@ -14,6 +13,9 @@ import org.jetbrains.kotlinx.dataframe.columns.SingleColumn import org.jetbrains.kotlinx.dataframe.columns.size import org.jetbrains.kotlinx.dataframe.documentation.CommonTakeAndDropDocs import org.jetbrains.kotlinx.dataframe.documentation.CommonTakeAndDropWhileDocs +import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls +import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns +import org.jetbrains.kotlinx.dataframe.documentation.SelectingRows import org.jetbrains.kotlinx.dataframe.documentation.TakeAndDropColumnsSelectionDslGrammar import org.jetbrains.kotlinx.dataframe.impl.columns.transform import org.jetbrains.kotlinx.dataframe.impl.columns.transformSingle @@ -23,6 +25,22 @@ import kotlin.reflect.KProperty // region DataColumn +/** + * Returns a [DataColumn] containing the first [n] values of this [DataColumn]. + * + * If [n] is greater than or equal to the size of this [DataColumn], this [DataColumn] is returned as is. + * + * See also: + * - [takeLast][DataColumn.takeLast] — takes the last [n] values instead. + * - [drop][DataColumn.drop]`(n: Int)` — drops the first [n] values. + * - [dropLast][DataColumn.dropLast] — drops the last [n] values. + * - [drop][DataColumn.drop]`{ predicate: Predicate }` — drops every value that matches the predicate. + * + * @param [n] The number of values to take. Must not be negative. + * @return A [DataColumn] containing the first [n] values of this [DataColumn], + * or this [DataColumn] if [n] is greater than or equal to its size. + * @throws [IllegalArgumentException] if [n] is negative. + */ public fun DataColumn.take(n: Int): DataColumn = when { n == 0 -> get(emptyList()) @@ -30,6 +48,22 @@ public fun DataColumn.take(n: Int): DataColumn = else -> get(0 until n) } +/** + * Returns a [DataColumn] containing the last [n] values of this [DataColumn]. + * + * If [n] is zero or negative, an empty [DataColumn] is returned. + * + * See also: + * - [take][DataColumn.take] — takes the first [n] values instead. + * - [dropLast][DataColumn.dropLast] — drops the last [n] values. + * - [drop][DataColumn.drop]`(n: Int)` — drops the first [n] values. + * - [drop][DataColumn.drop]`{ predicate: Predicate }` — drops every value that matches the predicate. + * + * @param [n] The number of values to take. Must not exceed the size of this [DataColumn]. + * @return A [DataColumn] containing the last [n] values of this [DataColumn], + * or an empty [DataColumn] if [n] is zero or negative. + * @throws [IndexOutOfBoundsException] if [n] is greater than the size of this [DataColumn]. + */ public fun DataColumn.takeLast(n: Int = 1): DataColumn = drop(size - n) // endregion @@ -37,8 +71,19 @@ public fun DataColumn.takeLast(n: Int = 1): DataColumn = drop(size - n // region DataFrame /** - * Returns a DataFrame containing first [n] rows. + * Returns a [DataFrame] containing the first [n] rows. * + * If [n] is greater than or equal to the number of rows, the whole [DataFrame] is returned. + * + * See also: + * - [takeLast][DataFrame.takeLast] — takes the last [n] rows instead. + * - [takeWhile][DataFrame.takeWhile] — takes the first rows while the predicate holds. + * - [drop][DataFrame.drop]`(n: Int)` — drops the first [n] rows. + * - [filter][DataFrame.filter] — keeps every row that matches the predicate. + * + * @param [n] The number of rows to take. Must not be negative. + * @return A [DataFrame] containing the first [n] rows, + * or the whole [DataFrame] if [n] is greater than or equal to the number of rows. * @throws IllegalArgumentException if [n] is negative. */ public fun DataFrame.take(n: Int): DataFrame { @@ -47,8 +92,19 @@ public fun DataFrame.take(n: Int): DataFrame { } /** - * Returns a DataFrame containing last [n] rows. + * Returns a [DataFrame] containing the last [n] rows. + * + * If [n] is greater than or equal to the number of rows, the whole [DataFrame] is returned. * + * See also: + * - [take][DataFrame.take] — takes the first [n] rows instead. + * - [takeWhile][DataFrame.takeWhile] — takes the first rows while the predicate holds. + * - [dropLast][DataFrame.dropLast] — drops the last [n] rows. + * - [filter][DataFrame.filter] — keeps every row that matches the predicate. + * + * @param [n] The number of rows to take. Must not be negative. + * @return A [DataFrame] containing the last [n] rows, + * or the whole [DataFrame] if [n] is greater than or equal to the number of rows. * @throws IllegalArgumentException if [n] is negative. */ public fun DataFrame.takeLast(n: Int = 1): DataFrame { @@ -57,7 +113,23 @@ public fun DataFrame.takeLast(n: Int = 1): DataFrame { } /** - * Returns a DataFrame containing first rows that satisfy the given [predicate]. + * Returns a [DataFrame] containing the first rows that satisfy the given [predicate]. + * + * Rows are taken for as long as the [predicate] holds; the operation stops at the first row that + * does not satisfy it, and no later row is taken even if it satisfies the [predicate]. + * + * @include [SelectingRows.RowFilterSnippet] + * + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsSnippet] + * + * See also: + * - [take][DataFrame.take] — takes a fixed number of first rows. + * - [takeLast][DataFrame.takeLast] — takes a fixed number of last rows. + * - [dropWhile][DataFrame.dropWhile] — drops the first rows while the predicate holds. + * - [filter][DataFrame.filter] — keeps every row that matches the predicate. + * + * @param [predicate] The [RowFilter] that the leading rows to take must satisfy. + * @return A [DataFrame] containing the first rows that satisfy the [predicate]. */ public inline fun DataFrame.takeWhile(predicate: RowFilter): DataFrame = firstOrNull { !predicate(it, it) }?.let { take(it.index()) } ?: this @@ -107,6 +179,12 @@ public interface TakeColumnsSelectionDsl { * @set [CommonTakeAndDropDocs.OPERATION] take * @set [CommonTakeAndDropDocs.NOUN] take * @set [CommonTakeAndDropDocs.FIRST_OR_LAST] first + * @set [CommonTakeAndDropDocs.SEE_ALSO] + * - [takeLast][ColumnsSelectionDsl.takeLast] — takes the last `n` columns instead. + * - [takeWhile][ColumnsSelectionDsl.takeWhile] — takes the first columns while a predicate holds. + * - [takeLastWhile][ColumnsSelectionDsl.takeLastWhile] — takes the last columns while a predicate holds. + * - [drop][ColumnsSelectionDsl.drop] — drops the first `n` columns. + * @set [CommonTakeAndDropDocs.RETURN] A [ColumnSet] containing the first [n\] columns. */ private typealias CommonTakeFirstDocs = Nothing @@ -178,6 +256,12 @@ public interface TakeColumnsSelectionDsl { * @set [CommonTakeAndDropDocs.OPERATION] takeLast * @set [CommonTakeAndDropDocs.NOUN] take * @set [CommonTakeAndDropDocs.FIRST_OR_LAST] last + * @set [CommonTakeAndDropDocs.SEE_ALSO] + * - [take][ColumnsSelectionDsl.take] — takes the first `n` columns instead. + * - [takeWhile][ColumnsSelectionDsl.takeWhile] — takes the first columns while a predicate holds. + * - [takeLastWhile][ColumnsSelectionDsl.takeLastWhile] — takes the last columns while a predicate holds. + * - [dropLast][ColumnsSelectionDsl.dropLast] — drops the last `n` columns. + * @set [CommonTakeAndDropDocs.RETURN] A [ColumnSet] containing the last [n\] columns. */ private typealias CommonTakeLastDocs = Nothing @@ -249,6 +333,13 @@ public interface TakeColumnsSelectionDsl { * @set [CommonTakeAndDropWhileDocs.OPERATION] take * @set [CommonTakeAndDropWhileDocs.NOUN] take * @set [CommonTakeAndDropWhileDocs.FIRST_OR_LAST] first + * @set [CommonTakeAndDropWhileDocs.SEE_ALSO] + * - [take][ColumnsSelectionDsl.take] — takes a fixed number of first columns. + * - [takeLast][ColumnsSelectionDsl.takeLast] — takes a fixed number of last columns. + * - [takeLastWhile][ColumnsSelectionDsl.takeLastWhile] — takes the last columns while a predicate holds. + * - [dropWhile][ColumnsSelectionDsl.dropWhile] — drops the first columns while a predicate holds. + * @set [CommonTakeAndDropWhileDocs.RETURN] A [ColumnSet] containing the first columns + * adhering to the [predicate\]. */ private typealias CommonTakeFirstWhileDocs = Nothing @@ -322,6 +413,13 @@ public interface TakeColumnsSelectionDsl { * @set [CommonTakeAndDropWhileDocs.OPERATION] takeLast * @set [CommonTakeAndDropWhileDocs.NOUN] take * @set [CommonTakeAndDropWhileDocs.FIRST_OR_LAST] last + * @set [CommonTakeAndDropWhileDocs.SEE_ALSO] + * - [take][ColumnsSelectionDsl.take] — takes a fixed number of first columns. + * - [takeLast][ColumnsSelectionDsl.takeLast] — takes a fixed number of last columns. + * - [takeWhile][ColumnsSelectionDsl.takeWhile] — takes the first columns while a predicate holds. + * - [dropLastWhile][ColumnsSelectionDsl.dropLastWhile] — drops the last columns while a predicate holds. + * @set [CommonTakeAndDropWhileDocs.RETURN] A [ColumnSet] containing the last columns + * adhering to the [predicate\]. */ private typealias CommonTakeLastWhileDocs = Nothing diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropDocs.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropDocs.kt index efe647a393..0a47356327 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropDocs.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropDocs.kt @@ -37,8 +37,11 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnSet * * {@get [CommonTakeAndDropDocs.EXAMPLE]} * + * See also: + * {@get [SEE_ALSO]} + * * @param [n\] The number of columns to {@get [NOUN]}. - * @return A [ColumnSet] containing the {@get [FIRST_OR_LAST]} [n\] columns. + * @return {@get [RETURN]} */ internal interface CommonTakeAndDropDocs { @@ -56,4 +59,10 @@ internal interface CommonTakeAndDropDocs { // Example argument to use typealias EXAMPLE = Nothing + + // Related operations (the `See also` part) + typealias SEE_ALSO = Nothing + + // Value returned by the operation (the `@return` part) + typealias RETURN = Nothing } diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropWhileDocs.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropWhileDocs.kt index ccb8be896a..6ebb1e250e 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropWhileDocs.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/CommonTakeAndDropWhileDocs.kt @@ -15,8 +15,9 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath /** * ## {@get [TITLE]} (Cols) While - * This function {@get [NOUN]}s the {@get [FIRST_OR_LAST]} columns from [this\] adhering to the - * given [predicate\] collecting the result into a [ColumnSet]. + * This function {@get [NOUN]}s the {@get [FIRST_OR_LAST]} columns from [this\] for as long as the + * given [predicate\] holds, stopping as soon as a column does not adhere to it, and collects the + * result into a [ColumnSet]. * * This function operates solely on columns at the top-level. * @@ -26,7 +27,7 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath * `{@get [CommonTakeAndDropWhileDocs.OPERATION]}ColsWhile` when called on a [String] or [ColumnPath] resembling * a [ColumnGroup]. * - * ### Check out: [Usage\] + * ### Check out: [Grammar\] * * #### Examples: * `df.`[select][DataFrame.select]` { `[`cols`][ColumnsSelectionDsl.cols]` { "my" `[`in`][String.contains]` it.`[`name`][DataColumn.name]` }.`[\`{@get [OPERATION]}While\`][ColumnSet.{@get [OPERATION]}While]` { "my" `[`in`][String.contains]` it.`[`name`][DataColumn.name]` } }` @@ -39,8 +40,11 @@ import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath * * {@get [CommonTakeAndDropWhileDocs.EXAMPLE]} * + * See also: + * {@get [SEE_ALSO]} + * * @param [predicate\] The [ColumnFilter] to control which columns to {@get [NOUN]}. - * @return A [ColumnSet] containing the {@get [FIRST_OR_LAST]} columns adhering to the [predicate\]. + * @return {@get [RETURN]} */ internal interface CommonTakeAndDropWhileDocs { @@ -58,4 +62,10 @@ internal interface CommonTakeAndDropWhileDocs { // Example argument to use typealias EXAMPLE = Nothing + + // Related operations (the `See also` part) + typealias SEE_ALSO = Nothing + + // Value returned by the operation (the `@return` part) + typealias RETURN = Nothing } diff --git a/docs/StardustDocs/resources/api/pivot/pivotInward_properties.html b/docs/StardustDocs/resources/api/pivot/pivotInward_properties.html index 711be6bb1c..c877ab506b 100644 --- a/docs/StardustDocs/resources/api/pivot/pivotInward_properties.html +++ b/docs/StardustDocs/resources/api/pivot/pivotInward_properties.html @@ -459,7 +459,7 @@ /**/ diff --git a/docs/StardustDocs/topics/drop.md b/docs/StardustDocs/topics/drop.md index 87feba307b..dd0c7be807 100644 --- a/docs/StardustDocs/topics/drop.md +++ b/docs/StardustDocs/topics/drop.md @@ -25,6 +25,9 @@ df.drop { it["weight"] == null || it["city"] == null } +If called on a [`DataColumn`](DataColumn.md), removes all the values that match the predicate +and returns a [`DataColumn`](DataColumn.md) containing the values that do not match the predicate. + ## dropNulls Remove rows with `null` values. This is a DataFrame equivalent of `filterNotNull`.