diff --git a/core/api/core.api b/core/api/core.api index fa71b6b95a..b54428c0cf 100644 --- a/core/api/core.api +++ b/core/api/core.api @@ -6277,6 +6277,10 @@ public final class org/jetbrains/kotlinx/dataframe/api/MoveKt { public static final fun moveTo (Lorg/jetbrains/kotlinx/dataframe/DataFrame;I[Ljava/lang/String;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; public static final fun moveTo (Lorg/jetbrains/kotlinx/dataframe/DataFrame;I[Lkotlin/reflect/KProperty;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; public static final fun moveTo (Lorg/jetbrains/kotlinx/dataframe/DataFrame;I[Lorg/jetbrains/kotlinx/dataframe/columns/ColumnReference;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; + public static final fun moveToEnd (Lorg/jetbrains/kotlinx/dataframe/DataFrame;Lkotlin/jvm/functions/Function2;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; + public static final fun moveToEnd (Lorg/jetbrains/kotlinx/dataframe/DataFrame;[Ljava/lang/String;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; + public static final fun moveToEnd (Lorg/jetbrains/kotlinx/dataframe/DataFrame;[Lkotlin/reflect/KProperty;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; + public static final fun moveToEnd (Lorg/jetbrains/kotlinx/dataframe/DataFrame;[Lorg/jetbrains/kotlinx/dataframe/columns/ColumnReference;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; public static final fun moveToLeft (Lorg/jetbrains/kotlinx/dataframe/DataFrame;Lkotlin/jvm/functions/Function2;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; public static final fun moveToLeft (Lorg/jetbrains/kotlinx/dataframe/DataFrame;[Ljava/lang/String;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; public static final fun moveToLeft (Lorg/jetbrains/kotlinx/dataframe/DataFrame;[Lkotlin/reflect/KProperty;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; @@ -6285,9 +6289,15 @@ public final class org/jetbrains/kotlinx/dataframe/api/MoveKt { public static final fun moveToRight (Lorg/jetbrains/kotlinx/dataframe/DataFrame;[Ljava/lang/String;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; public static final fun moveToRight (Lorg/jetbrains/kotlinx/dataframe/DataFrame;[Lkotlin/reflect/KProperty;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; public static final fun moveToRight (Lorg/jetbrains/kotlinx/dataframe/DataFrame;[Lorg/jetbrains/kotlinx/dataframe/columns/ColumnReference;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; + public static final fun moveToStart (Lorg/jetbrains/kotlinx/dataframe/DataFrame;Lkotlin/jvm/functions/Function2;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; + public static final fun moveToStart (Lorg/jetbrains/kotlinx/dataframe/DataFrame;[Ljava/lang/String;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; + public static final fun moveToStart (Lorg/jetbrains/kotlinx/dataframe/DataFrame;[Lkotlin/reflect/KProperty;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; + public static final fun moveToStart (Lorg/jetbrains/kotlinx/dataframe/DataFrame;[Lorg/jetbrains/kotlinx/dataframe/columns/ColumnReference;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; public static final fun to (Lorg/jetbrains/kotlinx/dataframe/api/MoveClause;I)Lorg/jetbrains/kotlinx/dataframe/DataFrame; + public static final fun toEnd (Lorg/jetbrains/kotlinx/dataframe/api/MoveClause;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; public static final fun toLeft (Lorg/jetbrains/kotlinx/dataframe/api/MoveClause;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; public static final fun toRight (Lorg/jetbrains/kotlinx/dataframe/api/MoveClause;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; + public static final fun toStart (Lorg/jetbrains/kotlinx/dataframe/api/MoveClause;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; public static final fun toTop (Lorg/jetbrains/kotlinx/dataframe/api/MoveClause;Lkotlin/jvm/functions/Function2;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; public static synthetic fun toTop$default (Lorg/jetbrains/kotlinx/dataframe/api/MoveClause;Lkotlin/jvm/functions/Function2;ILjava/lang/Object;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; public static final fun under (Lorg/jetbrains/kotlinx/dataframe/api/MoveClause;Ljava/lang/String;)Lorg/jetbrains/kotlinx/dataframe/DataFrame; diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/move.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/move.kt index 5095e1c579..3a2308174a 100644 --- a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/move.kt +++ b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/move.kt @@ -6,39 +6,400 @@ import org.jetbrains.kotlinx.dataframe.ColumnSelector import org.jetbrains.kotlinx.dataframe.ColumnsSelector import org.jetbrains.kotlinx.dataframe.DataFrame import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload +import org.jetbrains.kotlinx.dataframe.annotations.CandidateForRemoval import org.jetbrains.kotlinx.dataframe.annotations.Interpretable import org.jetbrains.kotlinx.dataframe.annotations.Refine +import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup import org.jetbrains.kotlinx.dataframe.columns.ColumnReference import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath import org.jetbrains.kotlinx.dataframe.columns.toColumnSet +import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns import org.jetbrains.kotlinx.dataframe.impl.api.afterOrBefore import org.jetbrains.kotlinx.dataframe.impl.api.moveImpl import org.jetbrains.kotlinx.dataframe.impl.api.moveTo import org.jetbrains.kotlinx.dataframe.ncol +import org.jetbrains.kotlinx.dataframe.util.MOVE_TO_LEFT +import org.jetbrains.kotlinx.dataframe.util.MOVE_TO_LEFT_REPLACE +import org.jetbrains.kotlinx.dataframe.util.MOVE_TO_RIGHT +import org.jetbrains.kotlinx.dataframe.util.MOVE_TO_RIGHT_REPLACE +import org.jetbrains.kotlinx.dataframe.util.TO_LEFT +import org.jetbrains.kotlinx.dataframe.util.TO_LEFT_REPLACE +import org.jetbrains.kotlinx.dataframe.util.TO_RIGHT +import org.jetbrains.kotlinx.dataframe.util.TO_RIGHT_REPLACE import kotlin.reflect.KProperty // region DataFrame // region move +/** + * Moves the specified [columns] within the [DataFrame]. + * + * This function does not immediately move the columns but instead select columns to move and + * returns a [MoveClause], + * which serves as an intermediate step. The [MoveClause] allows specifying the final + * destination of the selected columns using methods such as [to][MoveClause.to], [toStart][MoveClause.toStart], + * [toEnd][MoveClause.toEnd], [into][MoveClause.into], [intoIndexed][MoveClause.intoIndexed], [toTop][MoveClause.toTop], + * [after][MoveClause.after] or [under][MoveClause.under], that return a new [DataFrame] with updated columns structure. + * Check out [Grammar]. + * + * This can include [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns. + * + * See [Selecting Columns][MoveSelectingOptions]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + */ +internal interface Move { + + /** + * + * ## Selecting Columns + * Selecting columns for various operations (including but not limited to + * [DataFrame.select][org.jetbrains.kotlinx.dataframe.DataFrame.select], [DataFrame.update][org.jetbrains.kotlinx.dataframe.DataFrame.update], [DataFrame.gather][org.jetbrains.kotlinx.dataframe.DataFrame.gather], and [DataFrame.fillNulls][org.jetbrains.kotlinx.dataframe.DataFrame.fillNulls]) + * can be done in the following ways: + * ### 1. [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.Dsl.WithExample] + * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl]. + * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]). + * + * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda, + * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and + * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]). + * This is an entity formed by calling any (combination) of the functions + * in the DSL that is or can be resolved into one or more columns. + * + * #### NOTE: + * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi] + * in this DSL directly with any function, they are NOT valid return types for the + * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance + * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col]. + * + * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar] + * + *      + * + * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html) + * + * #### For example: + * + * `df.`[move][org.jetbrains.kotlinx.dataframe.api.move]` { length `[and][org.jetbrains.kotlinx.dataframe.api.AndColumnsSelectionDsl.and]` age }` + * + * `df.`[move][org.jetbrains.kotlinx.dataframe.api.move]` { `[cols][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.cols]`(1..5) }` + * + * `df.`[move][org.jetbrains.kotlinx.dataframe.api.move]` { `[colsOf][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.colsOf]`<`[Double][Double]`>() }` + * + * + * #### NOTE: There's also a 'single column' variant used sometimes: [Column Selection DSL][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.DslSingle.WithExample]. + * ### 2. [Column names][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.ColumnNames.WithExample] + * Select columns using their [column names][String] + * ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]). + * + * #### For example: + * + * `df.`[move][org.jetbrains.kotlinx.dataframe.api.move]`("length", "age")` + * + * ### 3. [Column references][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.ColumnAccessors.WithExample] + * Select columns using [column accessors][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] + * ([Column Accessors API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ColumnAccessorsApi]). + * + * #### For example: + * + * `val length by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()` + * + * `val age by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()` + * + * `df.`[move][org.jetbrains.kotlinx.dataframe.api.move]`(length, age)` + * + * ### 4. [KProperties][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.KProperties.WithExample] + * Select columns using [KProperties][KProperty] ([KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]). + * + * #### For example: + * ```kotlin + * data class Person(val length: Double, val age: Double) + * ``` + * + * `df.`[move][org.jetbrains.kotlinx.dataframe.api.move]`(Person::length, Person::age)` + * + */ + interface MoveSelectingOptions + + /** + * ## Move Operation Grammar + * + *      + * + * [(What is this notation?)][org.jetbrains.kotlinx.dataframe.documentation.DslGrammar] + * + *      + * + * + * **[`move`][move]****` { `**`columnsSelector: `[`ColumnsSelector`][ColumnsSelector]**` }`** + * + *      + * __`.`__[**`into`**][MoveClause.into]**` { `**`targetColumnPaths: `[`ColumnsSelector`][ColumnsSelector]**` } `** + * + *      + * `| `__`.`__[**`intoIndexed`**][MoveClause.intoIndexed]**` { `**`targetColumnPaths: `[`ColumnsSelector`][ColumnsSelector]**` }`** + * + *      + * `| `__`.`__[**`under`**][MoveClause.under]**` { `**`parentColumnGroupPath: `[`ColumnSelector`][ColumnSelector]**` }`** + * + *      + * `| `__`.`__[**`after`**][MoveClause.after]**` { `**`column: `[`ColumnSelector`][ColumnSelector]**` }`** + * + *      + * `| `__`.`__[**`to`**][MoveClause.to]**`(`**`position: `[`Int`][Int]**`)`** + * + *      + * `| `__`.`__[**`toTop`**][MoveClause.toTop]**`()`** + * + *      + * `| `__`.`__[**`toStart`**][MoveClause.toStart]**`()`** + * + *      + * `| `__`.`__[**`toEnd`**][MoveClause.toEnd]**`()`** + */ + interface Grammar +} + +/** + * Moves the specified [columns] within the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame]. + * + * This function does not immediately move the columns but instead select columns to move and + * returns a [MoveClause][org.jetbrains.kotlinx.dataframe.api.MoveClause], + * which serves as an intermediate step. The [MoveClause][org.jetbrains.kotlinx.dataframe.api.MoveClause] allows specifying the final + * destination of the selected columns using methods such as [to][org.jetbrains.kotlinx.dataframe.api.MoveClause.to], [toStart][org.jetbrains.kotlinx.dataframe.api.MoveClause.toStart], + * [toEnd][org.jetbrains.kotlinx.dataframe.api.MoveClause.toEnd], [into][org.jetbrains.kotlinx.dataframe.api.MoveClause.into], [intoIndexed][org.jetbrains.kotlinx.dataframe.api.MoveClause.intoIndexed], [toTop][org.jetbrains.kotlinx.dataframe.api.MoveClause.toTop], + * [after][org.jetbrains.kotlinx.dataframe.api.MoveClause.after] or [under][org.jetbrains.kotlinx.dataframe.api.MoveClause.under], that return a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with updated columns structure. + * Check out [Grammar][org.jetbrains.kotlinx.dataframe.api.Move.Grammar]. + * + * This can include [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns. + * + * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Move.MoveSelectingOptions]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * ### This Move Overload + * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl]. + * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]). + * + * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda, + * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and + * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]). + * This is an entity formed by calling any (combination) of the functions + * in the DSL that is or can be resolved into one or more columns. + * + * #### NOTE: + * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi] + * in this DSL directly with any function, they are NOT valid return types for the + * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance + * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col]. + * + * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar] + * + *      + * + * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html) + * ### Examples: + * ```kotlin + * df.move { columnA and columnB }.after { columnC } + * df.move { cols(0..3) }.under("info") + * df.move { colsOf() }.to(5) + * ``` + * @param [columns] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ @Interpretable("Move0") public fun DataFrame.move(columns: ColumnsSelector): MoveClause = MoveClause(this, columns) -public fun DataFrame.move(vararg cols: String): MoveClause = move { cols.toColumnSet() } +/** + * Moves the specified [columns] within the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame]. + * + * This function does not immediately move the columns but instead select columns to move and + * returns a [MoveClause][org.jetbrains.kotlinx.dataframe.api.MoveClause], + * which serves as an intermediate step. The [MoveClause][org.jetbrains.kotlinx.dataframe.api.MoveClause] allows specifying the final + * destination of the selected columns using methods such as [to][org.jetbrains.kotlinx.dataframe.api.MoveClause.to], [toStart][org.jetbrains.kotlinx.dataframe.api.MoveClause.toStart], + * [toEnd][org.jetbrains.kotlinx.dataframe.api.MoveClause.toEnd], [into][org.jetbrains.kotlinx.dataframe.api.MoveClause.into], [intoIndexed][org.jetbrains.kotlinx.dataframe.api.MoveClause.intoIndexed], [toTop][org.jetbrains.kotlinx.dataframe.api.MoveClause.toTop], + * [after][org.jetbrains.kotlinx.dataframe.api.MoveClause.after] or [under][org.jetbrains.kotlinx.dataframe.api.MoveClause.under], that return a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with updated columns structure. + * Check out [Grammar][org.jetbrains.kotlinx.dataframe.api.Move.Grammar]. + * + * This can include [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns. + * + * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.Move.MoveSelectingOptions]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * ### This Move Overload + * Select columns using their [column names][String] + * ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]). + * ### Examples: + * ```kotlin + * df.move("columnA", "columnB").after("columnC") + * df.move("age").under("info") + * ``` + * @param [columns] The [Column Names][String] used to select the columns of this [DataFrame] to move. + */ +public fun DataFrame.move(vararg columns: String): MoveClause = move { columns.toColumnSet() } @AccessApiOverload -public fun DataFrame.move(vararg cols: ColumnReference): MoveClause = move { cols.toColumnSet() } +public fun DataFrame.move(vararg columns: ColumnReference): MoveClause = + move { columns.toColumnSet() } @AccessApiOverload -public fun DataFrame.move(vararg cols: KProperty): MoveClause = move { cols.toColumnSet() } +public fun DataFrame.move(vararg columns: KProperty): MoveClause = move { columns.toColumnSet() } // endregion // region moveTo +/** + * Moves the specified [columns] to a new position specified by + * [newColumnIndex] within the [DataFrame]. + * + * Returns a new [DataFrame] with updated columns structure. + * + * This can include [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns. + * + * See [Selecting Columns][MoveToSelectingOptions]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + */ +internal interface MoveTo { + /** + * + * ## Selecting Columns + * Selecting columns for various operations (including but not limited to + * [DataFrame.select][org.jetbrains.kotlinx.dataframe.DataFrame.select], [DataFrame.update][org.jetbrains.kotlinx.dataframe.DataFrame.update], [DataFrame.gather][org.jetbrains.kotlinx.dataframe.DataFrame.gather], and [DataFrame.fillNulls][org.jetbrains.kotlinx.dataframe.DataFrame.fillNulls]) + * can be done in the following ways: + * ### 1. [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.Dsl.WithExample] + * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl]. + * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]). + * + * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda, + * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and + * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]). + * This is an entity formed by calling any (combination) of the functions + * in the DSL that is or can be resolved into one or more columns. + * + * #### NOTE: + * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi] + * in this DSL directly with any function, they are NOT valid return types for the + * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance + * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col]. + * + * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar] + * + *      + * + * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html) + * + * #### For example: + * + * `df.`[moveTo][org.jetbrains.kotlinx.dataframe.api.moveTo]` { length `[and][org.jetbrains.kotlinx.dataframe.api.AndColumnsSelectionDsl.and]` age }` + * + * `df.`[moveTo][org.jetbrains.kotlinx.dataframe.api.moveTo]` { `[cols][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.cols]`(1..5) }` + * + * `df.`[moveTo][org.jetbrains.kotlinx.dataframe.api.moveTo]` { `[colsOf][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.colsOf]`<`[Double][Double]`>() }` + * + * + * #### NOTE: There's also a 'single column' variant used sometimes: [Column Selection DSL][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.DslSingle.WithExample]. + * ### 2. [Column names][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.ColumnNames.WithExample] + * Select columns using their [column names][String] + * ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]). + * + * #### For example: + * + * `df.`[moveTo][org.jetbrains.kotlinx.dataframe.api.moveTo]`("length", "age")` + * + * ### 3. [Column references][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.ColumnAccessors.WithExample] + * Select columns using [column accessors][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] + * ([Column Accessors API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ColumnAccessorsApi]). + * + * #### For example: + * + * `val length by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()` + * + * `val age by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()` + * + * `df.`[moveTo][org.jetbrains.kotlinx.dataframe.api.moveTo]`(length, age)` + * + * ### 4. [KProperties][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.KProperties.WithExample] + * Select columns using [KProperties][KProperty] ([KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]). + * + * #### For example: + * ```kotlin + * data class Person(val length: Double, val age: Double) + * ``` + * + * `df.`[moveTo][org.jetbrains.kotlinx.dataframe.api.moveTo]`(Person::length, Person::age)` + * + */ + interface MoveToSelectingOptions +} + +/** + * Moves the specified [columns] to a new position specified by + * [newColumnIndex] within the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame]. + * + * Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with updated columns structure. + * + * This can include [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns. + * + * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.MoveTo.MoveToSelectingOptions]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * ### This MoveTo Overload + * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl]. + * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]). + * + * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda, + * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and + * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]). + * This is an entity formed by calling any (combination) of the functions + * in the DSL that is or can be resolved into one or more columns. + * + * #### NOTE: + * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi] + * in this DSL directly with any function, they are NOT valid return types for the + * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance + * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col]. + * + * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar] + * + *      + * + * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html) + * ### Examples: + * ```kotlin + * df.moveTo(0) { length and age } + * df.moveTo(2) { cols(1..5) } + * ``` + * @param [newColumnIndex] The index specifying the position in the [DataFrame] columns + * where the selected columns will be moved. + * @param [columns] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ public fun DataFrame.moveTo(newColumnIndex: Int, columns: ColumnsSelector): DataFrame = move(columns).to(newColumnIndex) +/** + * Moves the specified [columns] to a new position specified by + * [newColumnIndex] within the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame]. + * + * Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with updated columns structure. + * + * This can include [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns. + * + * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.MoveTo.MoveToSelectingOptions]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * ### This MoveTo Overload + * Select columns using their [column names][String] + * ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]). + * ### Examples: + * ```kotlin + * df.moveTo(0) { length and age } + * df.moveTo(2) { cols(1..5) } + * ``` + * @param [newColumnIndex] The index specifying the position in the [DataFrame] columns + * where the selected columns will be moved. + * @param [columns] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ public fun DataFrame.moveTo(newColumnIndex: Int, vararg columns: String): DataFrame = moveTo(newColumnIndex) { columns.toColumnSet() } @@ -51,39 +412,358 @@ public fun DataFrame.moveTo(newColumnIndex: Int, vararg columns: KPropert // endregion -// region moveToLeft +// region moveToStart +/** + * Moves the specified [columns] to the [DataFrame] start (on top-level). + * Returns a new [DataFrame] with updated columns structure. + * + * This can include [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns. + * + * See [Selecting Columns][MoveToStartSelectingOptions]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + */ +internal interface MoveToStart { + /** + * + * ## Selecting Columns + * Selecting columns for various operations (including but not limited to + * [DataFrame.select][org.jetbrains.kotlinx.dataframe.DataFrame.select], [DataFrame.update][org.jetbrains.kotlinx.dataframe.DataFrame.update], [DataFrame.gather][org.jetbrains.kotlinx.dataframe.DataFrame.gather], and [DataFrame.fillNulls][org.jetbrains.kotlinx.dataframe.DataFrame.fillNulls]) + * can be done in the following ways: + * ### 1. [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.Dsl.WithExample] + * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl]. + * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]). + * + * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda, + * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and + * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]). + * This is an entity formed by calling any (combination) of the functions + * in the DSL that is or can be resolved into one or more columns. + * + * #### NOTE: + * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi] + * in this DSL directly with any function, they are NOT valid return types for the + * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance + * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col]. + * + * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar] + * + *      + * + * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html) + * + * #### For example: + * + * `df.`[moveToStart][org.jetbrains.kotlinx.dataframe.api.moveToStart]` { length `[and][org.jetbrains.kotlinx.dataframe.api.AndColumnsSelectionDsl.and]` age }` + * + * `df.`[moveToStart][org.jetbrains.kotlinx.dataframe.api.moveToStart]` { `[cols][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.cols]`(1..5) }` + * + * `df.`[moveToStart][org.jetbrains.kotlinx.dataframe.api.moveToStart]` { `[colsOf][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.colsOf]`<`[Double][Double]`>() }` + * + * + * #### NOTE: There's also a 'single column' variant used sometimes: [Column Selection DSL][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.DslSingle.WithExample]. + * ### 2. [Column names][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.ColumnNames.WithExample] + * Select columns using their [column names][String] + * ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]). + * + * #### For example: + * + * `df.`[moveToStart][org.jetbrains.kotlinx.dataframe.api.moveToStart]`("length", "age")` + * + * ### 3. [Column references][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.ColumnAccessors.WithExample] + * Select columns using [column accessors][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] + * ([Column Accessors API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ColumnAccessorsApi]). + * + * #### For example: + * + * `val length by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()` + * + * `val age by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()` + * + * `df.`[moveToStart][org.jetbrains.kotlinx.dataframe.api.moveToStart]`(length, age)` + * + * ### 4. [KProperties][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.KProperties.WithExample] + * Select columns using [KProperties][KProperty] ([KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]). + * + * #### For example: + * ```kotlin + * data class Person(val length: Double, val age: Double) + * ``` + * + * `df.`[moveToStart][org.jetbrains.kotlinx.dataframe.api.moveToStart]`(Person::length, Person::age)` + * + */ + interface MoveToStartSelectingOptions +} + +@Deprecated(MOVE_TO_LEFT, ReplaceWith(MOVE_TO_LEFT_REPLACE), DeprecationLevel.ERROR) +public fun DataFrame.moveToLeft(columns: ColumnsSelector): DataFrame = move(columns).toStart() + +/** + * Moves the specified [columns] to the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] start (on top-level). + * Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with updated columns structure. + * + * This can include [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns. + * + * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.MoveToStart.MoveToStartSelectingOptions]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * ### This MoveToStart Overload + * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl]. + * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]). + * + * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda, + * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and + * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]). + * This is an entity formed by calling any (combination) of the functions + * in the DSL that is or can be resolved into one or more columns. + * + * #### NOTE: + * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi] + * in this DSL directly with any function, they are NOT valid return types for the + * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance + * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col]. + * + * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar] + * + *      + * + * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html) + * + * #### For example: + * + * `df.`[moveToStart][org.jetbrains.kotlinx.dataframe.api.moveToStart]` { length `[and][org.jetbrains.kotlinx.dataframe.api.AndColumnsSelectionDsl.and]` age }` + * + * `df.`[moveToStart][org.jetbrains.kotlinx.dataframe.api.moveToStart]` { `[cols][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.cols]`(1..5) }` + * + * `df.`[moveToStart][org.jetbrains.kotlinx.dataframe.api.moveToStart]` { `[colsOf][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.colsOf]`<`[Double][Double]`>() }` + * + * + * @param [columns] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ @Refine -@Interpretable("MoveToLeft1") -public fun DataFrame.moveToLeft(columns: ColumnsSelector): DataFrame = move(columns).toLeft() +@Interpretable("MoveToStart1") +public fun DataFrame.moveToStart(columns: ColumnsSelector): DataFrame = move(columns).toStart() -public fun DataFrame.moveToLeft(vararg columns: String): DataFrame = moveToLeft { columns.toColumnSet() } +@Deprecated(MOVE_TO_LEFT, ReplaceWith(MOVE_TO_LEFT_REPLACE), DeprecationLevel.ERROR) +public fun DataFrame.moveToLeft(vararg columns: String): DataFrame = moveToStart { columns.toColumnSet() } +/** + * Moves the specified [columns] to the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] start (on top-level). + * Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with updated columns structure. + * + * This can include [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns. + * + * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.MoveToStart.MoveToStartSelectingOptions]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * ### This MoveToStart Overload + * Select columns using their [column names][String] + * ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]). + * + * #### For example: + * + * `df.`[moveToStart][org.jetbrains.kotlinx.dataframe.api.moveToStart]`("length", "age")` + * + * @param [columns] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ +public fun DataFrame.moveToStart(vararg columns: String): DataFrame = moveToStart { columns.toColumnSet() } + +@Deprecated(MOVE_TO_LEFT, ReplaceWith(MOVE_TO_LEFT_REPLACE), DeprecationLevel.ERROR) @AccessApiOverload public fun DataFrame.moveToLeft(vararg columns: AnyColumnReference): DataFrame = - moveToLeft { columns.toColumnSet() } + moveToStart { columns.toColumnSet() } + +@AccessApiOverload +public fun DataFrame.moveToStart(vararg columns: AnyColumnReference): DataFrame = + moveToStart { columns.toColumnSet() } +@Deprecated(MOVE_TO_LEFT, ReplaceWith(MOVE_TO_LEFT_REPLACE), DeprecationLevel.ERROR) @AccessApiOverload public fun DataFrame.moveToLeft(vararg columns: KProperty<*>): DataFrame = - moveToLeft { columns.toColumnSet() } + moveToStart { columns.toColumnSet() } + +@AccessApiOverload +public fun DataFrame.moveToStart(vararg columns: KProperty<*>): DataFrame = + moveToStart { columns.toColumnSet() } // endregion -// region moveToRight +// region moveToEnd + +/** + * Moves the specified [columns] to the [DataFrame] end. + * Returns a new [DataFrame] with updated columns structure. + * + * This can include [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns. + * + * See [Selecting Columns][MoveToEndSelectingOptions]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + */ +internal interface MoveToEnd { + /** + * + * ## Selecting Columns + * Selecting columns for various operations (including but not limited to + * [DataFrame.select][org.jetbrains.kotlinx.dataframe.DataFrame.select], [DataFrame.update][org.jetbrains.kotlinx.dataframe.DataFrame.update], [DataFrame.gather][org.jetbrains.kotlinx.dataframe.DataFrame.gather], and [DataFrame.fillNulls][org.jetbrains.kotlinx.dataframe.DataFrame.fillNulls]) + * can be done in the following ways: + * ### 1. [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.Dsl.WithExample] + * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl]. + * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]). + * + * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda, + * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and + * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]). + * This is an entity formed by calling any (combination) of the functions + * in the DSL that is or can be resolved into one or more columns. + * + * #### NOTE: + * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi] + * in this DSL directly with any function, they are NOT valid return types for the + * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance + * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col]. + * + * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar] + * + *      + * + * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html) + * + * #### For example: + * + * `df.`[moveToEnd][org.jetbrains.kotlinx.dataframe.api.moveToEnd]` { length `[and][org.jetbrains.kotlinx.dataframe.api.AndColumnsSelectionDsl.and]` age }` + * + * `df.`[moveToEnd][org.jetbrains.kotlinx.dataframe.api.moveToEnd]` { `[cols][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.cols]`(1..5) }` + * + * `df.`[moveToEnd][org.jetbrains.kotlinx.dataframe.api.moveToEnd]` { `[colsOf][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.colsOf]`<`[Double][Double]`>() }` + * + * + * #### NOTE: There's also a 'single column' variant used sometimes: [Column Selection DSL][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.DslSingle.WithExample]. + * ### 2. [Column names][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.ColumnNames.WithExample] + * Select columns using their [column names][String] + * ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]). + * + * #### For example: + * + * `df.`[moveToEnd][org.jetbrains.kotlinx.dataframe.api.moveToEnd]`("length", "age")` + * + * ### 3. [Column references][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.ColumnAccessors.WithExample] + * Select columns using [column accessors][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] + * ([Column Accessors API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ColumnAccessorsApi]). + * + * #### For example: + * + * `val length by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()` + * + * `val age by `[column][org.jetbrains.kotlinx.dataframe.api.column]`<`[Double][Double]`>()` + * + * `df.`[moveToEnd][org.jetbrains.kotlinx.dataframe.api.moveToEnd]`(length, age)` + * + * ### 4. [KProperties][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns.KProperties.WithExample] + * Select columns using [KProperties][KProperty] ([KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi]). + * + * #### For example: + * ```kotlin + * data class Person(val length: Double, val age: Double) + * ``` + * + * `df.`[moveToEnd][org.jetbrains.kotlinx.dataframe.api.moveToEnd]`(Person::length, Person::age)` + * + */ + interface MoveToEndSelectingOptions +} + +@Deprecated(MOVE_TO_RIGHT, ReplaceWith(MOVE_TO_RIGHT_REPLACE), DeprecationLevel.ERROR) +public fun DataFrame.moveToRight(columns: ColumnsSelector): DataFrame = move(columns).toEnd() +/** + * Moves the specified [columns] to the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] end. + * Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with updated columns structure. + * + * This can include [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns. + * + * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.MoveToEnd.MoveToEndSelectingOptions]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * ### This MoveToEnd Overload + * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl]. + * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]). + * + * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda, + * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and + * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]). + * This is an entity formed by calling any (combination) of the functions + * in the DSL that is or can be resolved into one or more columns. + * + * #### NOTE: + * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi] + * in this DSL directly with any function, they are NOT valid return types for the + * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance + * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col]. + * + * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar] + * + *      + * + * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html) + * + * #### For example: + * + * `df.`[moveToEnd][org.jetbrains.kotlinx.dataframe.api.moveToEnd]` { length `[and][org.jetbrains.kotlinx.dataframe.api.AndColumnsSelectionDsl.and]` age }` + * + * `df.`[moveToEnd][org.jetbrains.kotlinx.dataframe.api.moveToEnd]` { `[cols][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.cols]`(1..5) }` + * + * `df.`[moveToEnd][org.jetbrains.kotlinx.dataframe.api.moveToEnd]` { `[colsOf][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.colsOf]`<`[Double][Double]`>() }` + * + * + * @param [columns] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ @Refine -@Interpretable("MoveToRight1") -public fun DataFrame.moveToRight(columns: ColumnsSelector): DataFrame = move(columns).toRight() +@Interpretable("MoveToEnd1") +public fun DataFrame.moveToEnd(columns: ColumnsSelector): DataFrame = move(columns).toEnd() -public fun DataFrame.moveToRight(vararg columns: String): DataFrame = moveToRight { columns.toColumnSet() } +@Deprecated(MOVE_TO_RIGHT, ReplaceWith(MOVE_TO_RIGHT_REPLACE), DeprecationLevel.ERROR) +public fun DataFrame.moveToRight(vararg columns: String): DataFrame = moveToEnd { columns.toColumnSet() } +/** + * Moves the specified [columns] to the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] end. + * Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with updated columns structure. + * + * This can include [column groups][org.jetbrains.kotlinx.dataframe.columns.ColumnGroup] and nested columns. + * + * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.api.MoveToEnd.MoveToEndSelectingOptions]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * ### This MoveToEnd Overload + * Select columns using their [column names][String] + * ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]). + * + * #### For example: + * + * `df.`[moveToEnd][org.jetbrains.kotlinx.dataframe.api.moveToEnd]`("length", "age")` + * + * @param [columns] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ +public fun DataFrame.moveToEnd(vararg columns: String): DataFrame = moveToEnd { columns.toColumnSet() } + +@Deprecated(MOVE_TO_RIGHT, ReplaceWith(MOVE_TO_RIGHT_REPLACE), DeprecationLevel.ERROR) @AccessApiOverload public fun DataFrame.moveToRight(vararg columns: AnyColumnReference): DataFrame = - moveToRight { columns.toColumnSet() } + moveToEnd { columns.toColumnSet() } + +@AccessApiOverload +public fun DataFrame.moveToEnd(vararg columns: AnyColumnReference): DataFrame = + moveToEnd { columns.toColumnSet() } +@Deprecated(MOVE_TO_RIGHT, ReplaceWith(MOVE_TO_RIGHT_REPLACE), DeprecationLevel.ERROR) @AccessApiOverload public fun DataFrame.moveToRight(vararg columns: KProperty<*>): DataFrame = - moveToRight { columns.toColumnSet() } + moveToEnd { columns.toColumnSet() } + +@AccessApiOverload +public fun DataFrame.moveToEnd(vararg columns: KProperty<*>): DataFrame = moveToEnd { columns.toColumnSet() } // endregion @@ -93,6 +773,46 @@ public fun DataFrame.moveToRight(vararg columns: KProperty<*>): DataFrame // region into +/** + * Moves columns, previously selected with [move] into a new position specified by a + * given column path within the [DataFrame]. + * If there are non-existent column groups on this path, they will be created. + * + * See [Selecting Columns][SelectingColumns]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * + * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl]. + * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]). + * + * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda, + * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and + * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]). + * This is an entity formed by calling any (combination) of the functions + * in the DSL that is or can be resolved into one or more columns. + * + * #### NOTE: + * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi] + * in this DSL directly with any function, they are NOT valid return types for the + * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance + * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col]. + * + * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar] + * + *      + * + * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html) + * + * ### Examples: + * ```kotlin + * df.move { age and weight }.into { pathOf("info", it.name()) } + * df.move { age and weight }.into { "info"[it.name()] } + * df.move { name.firstName and name.lastName }.into { pathOf("fullName", it.name().dropLast(4)) } + * ``` + * + * @param [column] The [Column With Path Selector][ColumnsSelector] used to specify + * a path in the [DataFrame] to move columns. + */ public fun MoveClause.into( column: ColumnsSelectionDsl.(ColumnWithPath) -> AnyColumnReference, ): DataFrame = @@ -104,10 +824,51 @@ public fun MoveClause.into( /** * Move a single selected column to top level with a new name */ +@CandidateForRemoval @Refine @Interpretable("MoveInto0") public fun MoveClause.into(column: String): DataFrame = pathOf(column).let { path -> into { path } } +/** + * Moves columns, previously selected with [move] into a new position specified by a + * given column path within the [DataFrame]. + * Provides selected column indices. + * If there are non-existent column groups on this path, they will be created. + * + * See [Selecting Columns][SelectingColumns]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * + * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl]. + * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]). + * + * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda, + * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and + * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]). + * This is an entity formed by calling any (combination) of the functions + * in the DSL that is or can be resolved into one or more columns. + * + * #### NOTE: + * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi] + * in this DSL directly with any function, they are NOT valid return types for the + * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance + * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col]. + * + * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar] + * + *      + * + * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html) + * + * ### Examples: + * ```kotlin + * df.move { cols { it.name == "user" } } + * .intoIndexed { it, index -> "allUsers"["user$index"] } + * ``` + * + * @param [column] The [Column With Path Selector And Indices][ColumnsSelector] used to specify + * a path in the [DataFrame] to move columns. + */ public fun MoveClause.intoIndexed( newPathExpression: ColumnsSelectionDsl.(ColumnWithPath, Int) -> AnyColumnReference, ): DataFrame { @@ -121,6 +882,27 @@ public fun MoveClause.intoIndexed( // region under +/** + * Moves columns, previously selected with [move] under a new or + * an existing column group within the [DataFrame]. + * If the column group doesn't exist, it will be created. + * + * See [Selecting Columns][SelectingColumns]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * + * Select columns using their [column names][String] + * ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]). + * + * ### Examples: + * ```kotlin + * df.move("age", "weight").under("info") + * df.move { age and weight }.under("info") + * ``` + * + * @param [column] A [ColumnsSelector] that defines the path to a [ColumnGroup] + * in the [DataFrame], where the selected columns will be moved. + */ @Refine @Interpretable("MoveUnder0") public fun MoveClause.under(column: String): DataFrame = pathOf(column).let { path -> under { path } } @@ -130,7 +912,46 @@ public fun MoveClause.under(column: AnyColumnGroupAccessor): DataFr column.path().let { path -> under { path } } /** - * Move selected columns under existing column group + * Moves columns, previously selected with [move] under a new or + * an existing column group specified by a + * column path within the [DataFrame]. + * If there are non-existent column groups on this path, they will be created. + * + * See [Selecting Columns][SelectingColumns]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * + * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl]. + * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]). + * + * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda, + * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and + * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]). + * This is an entity formed by calling any (combination) of the functions + * in the DSL that is or can be resolved into one or more columns. + * + * #### NOTE: + * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi] + * in this DSL directly with any function, they are NOT valid return types for the + * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance + * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col]. + * + * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar] + * + *      + * + * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html) + * + * ### Examples: + * ```kotlin + * // move under an existing column group + * df.move { age and weight }.under { info } + * // move under a new column group + * df.move { age and weight }.under { columnGroup(info) } + * ``` + * + * @param [column] The [ColumnsSelector] that defines the path to a [ColumnGroup] + * in the [DataFrame], where the selected columns will be moved. */ @Refine @Interpretable("MoveUnder1") @@ -146,8 +967,44 @@ public fun MoveClause.under( // region to +/** + * Moves columns, previously selected with [move] to a new position specified + * by [columnIndex] within the [DataFrame]. + * + * Returns a new [DataFrame] with updated columns structure. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * + * ### Examples: + * ```kotlin + * df.move { age and weight }.to(0) + * df.move("age", "weight").to(2) + * ``` + * + * @param [columnIndex] The index specifying the position in the [DataFrame] columns + * * where the selected columns will be moved. + */ public fun MoveClause.to(columnIndex: Int): DataFrame = moveTo(columnIndex) +/** + * Moves columns, previously selected with [move] to the top-level within the [DataFrame]. + * Moved columns name can be specified via special ColumnSelectionDsl. + * + * Returns a new [DataFrame] with updated columns. + * + * See [Selecting Columns][SelectingColumns]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * + * ### Examples: + * ```kotlin + * df.move { info.age and info.weight }.toTop() + * df.move { colsAtAnyDepth { it.name() == "number" } }.toTop { it.parentName + it.name() } + * ``` + * + * @param [newColumnName] The special [ColumnsSelector] for define name of moved column. + * Optional, the original name is used by default + */ @Refine @Interpretable("ToTop") public fun MoveClause.toTop( @@ -158,10 +1015,72 @@ public fun MoveClause.toTop( // region after +/** + * Moves columns, previously selected with [move][org.jetbrains.kotlinx.dataframe.api.move] to the position after the + * specified [column][org.jetbrains.kotlinx.dataframe.api.column] within the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame]. + * + * Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with updated columns. + * + * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * + * ### This After Overload + * Select or express columns using the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl]. + * (Any (combination of) [Access API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi]). + * + * This DSL is initiated by a [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda, + * which operates in the context of the [Columns Selection DSL][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl] and + * expects you to return a [SingleColumn][org.jetbrains.kotlinx.dataframe.columns.SingleColumn] or [ColumnSet][org.jetbrains.kotlinx.dataframe.columns.ColumnSet] (so, a [ColumnsResolver][org.jetbrains.kotlinx.dataframe.columns.ColumnsResolver]). + * This is an entity formed by calling any (combination) of the functions + * in the DSL that is or can be resolved into one or more columns. + * + * #### NOTE: + * While you can use the [String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi] and [KProperties API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.KPropertiesApi] + * in this DSL directly with any function, they are NOT valid return types for the + * [Columns Selector][org.jetbrains.kotlinx.dataframe.ColumnsSelector] lambda. You'd need to turn them into a [ColumnReference][org.jetbrains.kotlinx.dataframe.columns.ColumnReference] first, for instance + * with a function like [`col("name")`][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.col]. + * + * ### Check out: [Columns Selection DSL Grammar][org.jetbrains.kotlinx.dataframe.api.ColumnsSelectionDsl.DslGrammar] + * + *      + * + * [See Column Selectors on the documentation website.](https://kotlin.github.io/dataframe/columnselectors.html) + * + * ### Examples: + * ```kotlin + * df.move { age and weight }.after { surname } + * df.move { cols(0..2) }.after { col(3) } + * ``` + * + * @param [column] A [ColumnSelector] specifying the column + * after which the selected columns will be placed. + */ @Refine @Interpretable("MoveAfter0") public fun MoveClause.after(column: ColumnSelector): DataFrame = afterOrBefore(column, true) +/** + * Moves columns, previously selected with [move][org.jetbrains.kotlinx.dataframe.api.move] to the position after the + * specified [column][org.jetbrains.kotlinx.dataframe.api.column] within the [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame]. + * + * Returns a new [DataFrame][org.jetbrains.kotlinx.dataframe.DataFrame] with updated columns. + * + * See [Selecting Columns][org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns]. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * + * ### This After Overload + * Select columns using their [column names][String] + * ([String API][org.jetbrains.kotlinx.dataframe.documentation.AccessApi.StringApi]). + * + * ### Examples: + * ```kotlin + * df.move("age", "weight").after("surname") + * ``` + * @param [column] The [Column Name][String] specifying the column + * after which the selected columns will be placed. + */ public fun MoveClause.after(column: String): DataFrame = after { column.toColumnAccessor() } @AccessApiOverload @@ -180,14 +1099,67 @@ fun MoveColsClause.before(column: String) = before { column.toColum fun MoveColsClause.before(column: ColumnSelector) = afterOrBefore(column, false) */ -@Refine -@Interpretable("MoveToLeft0") +@Deprecated(TO_LEFT, ReplaceWith(TO_LEFT_REPLACE), DeprecationLevel.ERROR) public fun MoveClause.toLeft(): DataFrame = to(0) +/** + * Moves columns, previously selected with [move] to the [DataFrame] start (on top-level). + * + * Returns a new [DataFrame] with updated columns. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * + * ### Examples: + * ```kotlin + * df.move { age and weight }.toStart() + * df.move { colsOf() }.toStart() + * df.move("age", "weight").toStart() + * ``` + */ @Refine -@Interpretable("MoveToRight0") +@Interpretable("MoveToStart0") +public fun MoveClause.toStart(): DataFrame = to(0) + +@Deprecated(TO_RIGHT, ReplaceWith(TO_RIGHT_REPLACE), DeprecationLevel.ERROR) public fun MoveClause.toRight(): DataFrame = to(df.ncol) +/** + * Moves columns, previously selected with [move] to the [DataFrame] end. + * + * Returns a new [DataFrame] with updated columns. + * + * For more information: [See `move` on the documentation website.](https://kotlin.github.io/dataframe/move.html) + * + * ### Examples: + * ```kotlin + * df.move { age and weight }.toEnd() + * df.move { colsOf() }.toEnd() + * df.move("age", "weight").toEnd() + * ``` + */ +@Refine +@Interpretable("MoveToEnd0") +public fun MoveClause.toEnd(): DataFrame = to(df.ncol) + +/** + * An intermediate class used in the [move] operation. + * + * This class itself does nothing—it is just a transitional step before specifying + * where to move the selected columns. + * It must be followed by one of the positioning methods + * to produce a new [DataFrame] with the updated column structure. + * + * Use the following methods to finalize the move: + * - [to] – moves columns to a specific index. + * - [toStart] – moves columns to the beginning. + * - [toEnd] – moves columns to the end. + * - [into] / [intoIndexed] – moves columns to a new position. + * - [toTop] – moves columns to the top-level. + * - [after] – places columns after a specific column. + * - [under] – nests columns under a column group. + * + * See [Grammar][Move.Grammar] for more details. + */ public class MoveClause(internal val df: DataFrame, internal val columns: ColumnsSelector) { override fun toString(): String = "MoveClause(df=$df, columns=$columns)" } diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt index f4dbb83ebc..1022a0ad4c 100644 --- a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt +++ b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt @@ -8,7 +8,6 @@ import org.jetbrains.kotlinx.dataframe.annotations.Interpretable import org.jetbrains.kotlinx.dataframe.annotations.Refine import org.jetbrains.kotlinx.dataframe.columns.ColumnReference import org.jetbrains.kotlinx.dataframe.columns.toColumnSet -import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls.Select import org.jetbrains.kotlinx.dataframe.impl.api.removeImpl import org.jetbrains.kotlinx.dataframe.util.MINUS import org.jetbrains.kotlinx.dataframe.util.MINUS_REPLACE diff --git a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt index a500535206..6539d2a584 100644 --- a/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt +++ b/core/generated-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt @@ -60,6 +60,18 @@ internal const val IS_URL_IMPORT = "org.jetbrains.kotlinx.dataframe.io.isUrl" internal const val MINUS = "This minus overload will be removed in favor of `remove`. $MESSAGE_0_16" internal const val MINUS_REPLACE = "this.remove(columns)" +internal const val MOVE_TO_LEFT = "This `moveToLeft` overload will be removed in favor of `moveToStart`. $MESSAGE_0_16" +internal const val MOVE_TO_LEFT_REPLACE = "this.moveToStart(columns)" + +internal const val MOVE_TO_RIGHT = "This `moveToRight` overload will be removed in favor of `moveToEnd`. $MESSAGE_0_16" +internal const val MOVE_TO_RIGHT_REPLACE = "this.moveToEnd(columns)" + +internal const val TO_LEFT = "This `toLeft` overload will be removed in favor of `toStart`. $MESSAGE_0_16" +internal const val TO_LEFT_REPLACE = "this.toStart()" + +internal const val TO_RIGHT = "This `toRight` overload will be removed in favor of `toEnd`. $MESSAGE_0_16" +internal const val TO_RIGHT_REPLACE = "this.toEnd()" + // endregion // region WARNING in 0.16, ERROR in 0.17 diff --git a/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Modify.kt b/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Modify.kt index 2b7663cbb8..296dacb8bf 100644 --- a/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Modify.kt +++ b/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Modify.kt @@ -88,7 +88,7 @@ import org.jetbrains.kotlinx.dataframe.api.split import org.jetbrains.kotlinx.dataframe.api.sum import org.jetbrains.kotlinx.dataframe.api.to import org.jetbrains.kotlinx.dataframe.api.toFloat -import org.jetbrains.kotlinx.dataframe.api.toLeft +import org.jetbrains.kotlinx.dataframe.api.toStart import org.jetbrains.kotlinx.dataframe.api.toMap import org.jetbrains.kotlinx.dataframe.api.toPath import org.jetbrains.kotlinx.dataframe.api.toTop @@ -114,7 +114,6 @@ import org.junit.Test import java.net.URL import java.time.format.DateTimeFormatter import java.util.* -import kotlin.streams.toList @Suppress("ktlint:standard:chain-method-continuation", "ktlint:standard:argument-list-wrapping") class Modify : TestBase() { @@ -340,7 +339,7 @@ class Modify : TestBase() { @TransformDataFrameExpressions fun move() { // SampleStart - df.move { age }.toLeft() + df.move { age }.toStart() df.move { weight }.to(1) diff --git a/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTests.kt b/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTests.kt index 8a1fda14d8..5bc715e078 100644 --- a/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTests.kt +++ b/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTests.kt @@ -107,8 +107,8 @@ import org.jetbrains.kotlinx.dataframe.api.minOf import org.jetbrains.kotlinx.dataframe.api.minus import org.jetbrains.kotlinx.dataframe.api.move import org.jetbrains.kotlinx.dataframe.api.moveTo -import org.jetbrains.kotlinx.dataframe.api.moveToLeft -import org.jetbrains.kotlinx.dataframe.api.moveToRight +import org.jetbrains.kotlinx.dataframe.api.moveToEnd +import org.jetbrains.kotlinx.dataframe.api.moveToStart import org.jetbrains.kotlinx.dataframe.api.name import org.jetbrains.kotlinx.dataframe.api.named import org.jetbrains.kotlinx.dataframe.api.notNull @@ -142,11 +142,11 @@ import org.jetbrains.kotlinx.dataframe.api.toColumnAccessor import org.jetbrains.kotlinx.dataframe.api.toColumnOf import org.jetbrains.kotlinx.dataframe.api.toDataFrame import org.jetbrains.kotlinx.dataframe.api.toDouble +import org.jetbrains.kotlinx.dataframe.api.toEnd import org.jetbrains.kotlinx.dataframe.api.toInt import org.jetbrains.kotlinx.dataframe.api.toList import org.jetbrains.kotlinx.dataframe.api.toListOf import org.jetbrains.kotlinx.dataframe.api.toMap -import org.jetbrains.kotlinx.dataframe.api.toRight import org.jetbrains.kotlinx.dataframe.api.toStr import org.jetbrains.kotlinx.dataframe.api.toValueColumn import org.jetbrains.kotlinx.dataframe.api.transpose @@ -689,14 +689,14 @@ class DataFrameTests : BaseTest() { @Test fun `move several columns to left`() { - val moved = typed.moveToLeft { weight and age } + val moved = typed.moveToStart { weight and age } val expected = typed.select { cols(weight, age, name, city) } moved shouldBe expected } @Test fun `move several columns to right`() { - val moved = typed.moveToRight { weight and name } + val moved = typed.moveToEnd { weight and name } val expected = typed.select { cols(age, city, weight, name) } moved shouldBe expected } @@ -1130,7 +1130,7 @@ class DataFrameTests : BaseTest() { val cities = filtered.city.toList().map { it!!.lowercase() } val gathered = res.gather { colsOf { cities.contains(it.name()) } }.where { it }.keysInto("city") - val expected = filtered.select { name and age and city.map { it!!.lowercase() } }.moveToRight { city } + val expected = filtered.select { name and age and city.map { it!!.lowercase() } }.moveToEnd { city } gathered shouldBe expected } @@ -2273,7 +2273,7 @@ class DataFrameTests : BaseTest() { df.remove { city }.convertTo() shouldBe df.update { city }.withNull() - .move { city }.toRight() + .move { city }.toEnd() shouldThrow { df.remove { age }.convertTo() @@ -2283,7 +2283,7 @@ class DataFrameTests : BaseTest() { fill { age }.with { -1 } } shouldBe df.update { age }.with { -1 } - .move { age }.toRight() + .move { age }.toEnd() shouldThrow { df.update { name }.at(2).withNull() diff --git a/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTreeTests.kt b/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTreeTests.kt index f84bdea9f9..0a757d4acc 100644 --- a/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTreeTests.kt +++ b/core/generated-sources/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTreeTests.kt @@ -72,8 +72,8 @@ import org.jetbrains.kotlinx.dataframe.api.maxBy import org.jetbrains.kotlinx.dataframe.api.median import org.jetbrains.kotlinx.dataframe.api.move import org.jetbrains.kotlinx.dataframe.api.moveTo -import org.jetbrains.kotlinx.dataframe.api.moveToLeft -import org.jetbrains.kotlinx.dataframe.api.moveToRight +import org.jetbrains.kotlinx.dataframe.api.moveToEnd +import org.jetbrains.kotlinx.dataframe.api.moveToStart import org.jetbrains.kotlinx.dataframe.api.pathOf import org.jetbrains.kotlinx.dataframe.api.perRowCol import org.jetbrains.kotlinx.dataframe.api.pivot @@ -554,7 +554,7 @@ class DataFrameTreeTests : BaseTest() { .remove { it[groupCol]["city"] } .ungroup(groupCol) .sortBy { name and age } - res shouldBe typed.sortBy { name and age }.moveToLeft { city } + res shouldBe typed.sortBy { name and age }.moveToStart { city } } @Test @@ -567,7 +567,7 @@ class DataFrameTreeTests : BaseTest() { .remove { it[groupCol]["city"] } .ungroup(groupCol) .sortBy { name and age } - res shouldBe typed.sortBy { name and age }.moveToLeft { city } + res shouldBe typed.sortBy { name and age }.moveToStart { city } } @Test @@ -592,7 +592,7 @@ class DataFrameTreeTests : BaseTest() { @Test fun `join with right path`() { val joined = typed.remove { city }.join(typed2.remove { weight }) { name.match(right.nameAndCity.name) and age } - val expected = typed.moveToRight { city }.move { city }.under("nameAndCity") + val expected = typed.moveToEnd { city }.move { city }.under("nameAndCity") joined shouldBe expected } diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/move.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/move.kt index 5095e1c579..891fcb264d 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/move.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/move.kt @@ -6,39 +6,203 @@ import org.jetbrains.kotlinx.dataframe.ColumnSelector import org.jetbrains.kotlinx.dataframe.ColumnsSelector import org.jetbrains.kotlinx.dataframe.DataFrame import org.jetbrains.kotlinx.dataframe.annotations.AccessApiOverload +import org.jetbrains.kotlinx.dataframe.annotations.CandidateForRemoval import org.jetbrains.kotlinx.dataframe.annotations.Interpretable import org.jetbrains.kotlinx.dataframe.annotations.Refine +import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup import org.jetbrains.kotlinx.dataframe.columns.ColumnReference import org.jetbrains.kotlinx.dataframe.columns.ColumnWithPath import org.jetbrains.kotlinx.dataframe.columns.toColumnSet +import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls +import org.jetbrains.kotlinx.dataframe.documentation.DslGrammarLink +import org.jetbrains.kotlinx.dataframe.documentation.ExcludeFromSources +import org.jetbrains.kotlinx.dataframe.documentation.Indent +import org.jetbrains.kotlinx.dataframe.documentation.LineBreak +import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns import org.jetbrains.kotlinx.dataframe.impl.api.afterOrBefore import org.jetbrains.kotlinx.dataframe.impl.api.moveImpl import org.jetbrains.kotlinx.dataframe.impl.api.moveTo import org.jetbrains.kotlinx.dataframe.ncol +import org.jetbrains.kotlinx.dataframe.util.MOVE_TO_LEFT +import org.jetbrains.kotlinx.dataframe.util.MOVE_TO_LEFT_REPLACE +import org.jetbrains.kotlinx.dataframe.util.MOVE_TO_RIGHT +import org.jetbrains.kotlinx.dataframe.util.MOVE_TO_RIGHT_REPLACE +import org.jetbrains.kotlinx.dataframe.util.TO_LEFT +import org.jetbrains.kotlinx.dataframe.util.TO_LEFT_REPLACE +import org.jetbrains.kotlinx.dataframe.util.TO_RIGHT +import org.jetbrains.kotlinx.dataframe.util.TO_RIGHT_REPLACE import kotlin.reflect.KProperty // region DataFrame // region move +/** + * Moves the specified [columns\] within the [DataFrame]. + * + * This function does not immediately move the columns but instead select columns to move and + * returns a [MoveClause], + * which serves as an intermediate step. The [MoveClause] allows specifying the final + * destination of the selected columns using methods such as [to][MoveClause.to], [toStart][MoveClause.toStart], + * [toEnd][MoveClause.toEnd], [into][MoveClause.into], [intoIndexed][MoveClause.intoIndexed], [toTop][MoveClause.toTop], + * [after][MoveClause.after] or [under][MoveClause.under], that return a new [DataFrame] with updated columns structure. + * Check out [Grammar]. + * + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * + * See [Selecting Columns][MoveSelectingOptions]. + * + * For more information: {@include [DocumentationUrls.Move]} + */ +internal interface Move { + + /** + * {@comment Version of [SelectingColumns] with correctly filled in examples} + * @include [SelectingColumns] {@include [SetMoveOperationArg]} + */ + interface MoveSelectingOptions + + /** + * ## Move Operation Grammar + * {@include [LineBreak]} + * {@include [DslGrammarLink]} + * {@include [LineBreak]} + * + * **[`move`][move]****` { `**`columnsSelector: `[`ColumnsSelector`][ColumnsSelector]**` }`** + * + * {@include [Indent]} + * __`.`__[**`into`**][MoveClause.into]**` { `**`targetColumnPaths: `[`ColumnsSelector`][ColumnsSelector]**` } `** + * + * {@include [Indent]} + * `| `__`.`__[**`intoIndexed`**][MoveClause.intoIndexed]**` { `**`targetColumnPaths: `[`ColumnsSelector`][ColumnsSelector]**` }`** + * + * {@include [Indent]} + * `| `__`.`__[**`under`**][MoveClause.under]**` { `**`parentColumnGroupPath: `[`ColumnSelector`][ColumnSelector]**` }`** + * + * {@include [Indent]} + * `| `__`.`__[**`after`**][MoveClause.after]**` { `**`column: `[`ColumnSelector`][ColumnSelector]**` }`** + * + * {@include [Indent]} + * `| `__`.`__[**`to`**][MoveClause.to]**`(`**`position: `[`Int`][Int]**`)`** + * + * {@include [Indent]} + * `| `__`.`__[**`toTop`**][MoveClause.toTop]**`()`** + * + * {@include [Indent]} + * `| `__`.`__[**`toStart`**][MoveClause.toStart]**`()`** + * + * {@include [Indent]} + * `| `__`.`__[**`toEnd`**][MoveClause.toEnd]**`()`** + */ + interface Grammar +} + +/** {@set [SelectingColumns.OPERATION] [move][move]} */ +@ExcludeFromSources +private interface SetMoveOperationArg + +/** + * {@include [Move]} + * ### This Move Overload + */ +@ExcludeFromSources +private interface CommonMoveDocs + +/** + * @include [CommonMoveDocs] + * @include [SelectingColumns.Dsl] {@include [SetMoveOperationArg]} + * ### Examples: + * ```kotlin + * df.move { columnA and columnB }.after { columnC } + * df.move { cols(0..3) }.under("info") + * df.move { colsOf() }.to(5) + * ``` + * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ @Interpretable("Move0") public fun DataFrame.move(columns: ColumnsSelector): MoveClause = MoveClause(this, columns) -public fun DataFrame.move(vararg cols: String): MoveClause = move { cols.toColumnSet() } +/** + * @include [CommonMoveDocs] + * @include [SelectingColumns.ColumnNames] {@include [SetMoveOperationArg]} + * ### Examples: + * ```kotlin + * df.move("columnA", "columnB").after("columnC") + * df.move("age").under("info") + * ``` + * @param [columns\] The [Column Names][String] used to select the columns of this [DataFrame] to move. + */ +public fun DataFrame.move(vararg columns: String): MoveClause = move { columns.toColumnSet() } @AccessApiOverload -public fun DataFrame.move(vararg cols: ColumnReference): MoveClause = move { cols.toColumnSet() } +public fun DataFrame.move(vararg columns: ColumnReference): MoveClause = + move { columns.toColumnSet() } @AccessApiOverload -public fun DataFrame.move(vararg cols: KProperty): MoveClause = move { cols.toColumnSet() } +public fun DataFrame.move(vararg columns: KProperty): MoveClause = move { columns.toColumnSet() } // endregion // region moveTo +/** + * Moves the specified [columns\] to a new position specified by + * [newColumnIndex] within the [DataFrame]. + * + * Returns a new [DataFrame] with updated columns structure. + * + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * + * See [Selecting Columns][MoveToSelectingOptions]. + * + * For more information: {@include [DocumentationUrls.Move]} + */ +internal interface MoveTo { + /** + * {@comment Version of [SelectingColumns] with correctly filled in examples} + * @include [SelectingColumns] {@include [SetMoveToOperationArg]} + */ + interface MoveToSelectingOptions +} + +/** {@set [SelectingColumns.OPERATION] [moveTo][moveTo]} */ +@ExcludeFromSources +private interface SetMoveToOperationArg + +/** + * {@include [MoveTo]} + * ### This MoveTo Overload + */ +@ExcludeFromSources +private interface CommonMoveToDocs + +/** + * @include [CommonMoveToDocs] + * @include [SelectingColumns.Dsl] {@include [SetMoveToOperationArg]} + * ### Examples: + * ```kotlin + * df.moveTo(0) { length and age } + * df.moveTo(2) { cols(1..5) } + * ``` + * @param [newColumnIndex] The index specifying the position in the [DataFrame] columns + * where the selected columns will be moved. + * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ public fun DataFrame.moveTo(newColumnIndex: Int, columns: ColumnsSelector): DataFrame = move(columns).to(newColumnIndex) +/** + * @include [CommonMoveToDocs] + * @include [SelectingColumns.ColumnNames] {@include [SetMoveToOperationArg]} + * ### Examples: + * ```kotlin + * df.moveTo(0) { length and age } + * df.moveTo(2) { cols(1..5) } + * ``` + * @param [newColumnIndex] The index specifying the position in the [DataFrame] columns + * where the selected columns will be moved. + * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ public fun DataFrame.moveTo(newColumnIndex: Int, vararg columns: String): DataFrame = moveTo(newColumnIndex) { columns.toColumnSet() } @@ -51,39 +215,148 @@ public fun DataFrame.moveTo(newColumnIndex: Int, vararg columns: KPropert // endregion -// region moveToLeft +// region moveToStart + +/** + * Moves the specified [columns\] to the [DataFrame] start (on top-level). + * Returns a new [DataFrame] with updated columns structure. + * + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * + * See [Selecting Columns][MoveToStartSelectingOptions]. + * + * For more information: {@include [DocumentationUrls.Move]} + */ +internal interface MoveToStart { + /** + * {@comment Version of [SelectingColumns] with correctly filled in examples} + * @include [SelectingColumns] {@include [SetMoveToStartOperationArg]} + */ + interface MoveToStartSelectingOptions +} + +/** {@set [SelectingColumns.OPERATION] [moveToStart][moveToStart]} */ +@ExcludeFromSources +private interface SetMoveToStartOperationArg + +/** + * {@include [MoveToStart]} + * ### This MoveToStart Overload + */ +@ExcludeFromSources +private interface CommonMoveToStartDocs + +@Deprecated(MOVE_TO_LEFT, ReplaceWith(MOVE_TO_LEFT_REPLACE), DeprecationLevel.ERROR) +public fun DataFrame.moveToLeft(columns: ColumnsSelector): DataFrame = move(columns).toStart() +/** + * @include [CommonMoveToStartDocs] + * @include [SelectingColumns.Dsl.WithExample] {@include [SetMoveToStartOperationArg]} + * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ @Refine -@Interpretable("MoveToLeft1") -public fun DataFrame.moveToLeft(columns: ColumnsSelector): DataFrame = move(columns).toLeft() +@Interpretable("MoveToStart1") +public fun DataFrame.moveToStart(columns: ColumnsSelector): DataFrame = move(columns).toStart() + +@Deprecated(MOVE_TO_LEFT, ReplaceWith(MOVE_TO_LEFT_REPLACE), DeprecationLevel.ERROR) +public fun DataFrame.moveToLeft(vararg columns: String): DataFrame = moveToStart { columns.toColumnSet() } -public fun DataFrame.moveToLeft(vararg columns: String): DataFrame = moveToLeft { columns.toColumnSet() } +/** + * @include [CommonMoveToStartDocs] + * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetMoveToStartOperationArg]} + * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ +public fun DataFrame.moveToStart(vararg columns: String): DataFrame = moveToStart { columns.toColumnSet() } +@Deprecated(MOVE_TO_LEFT, ReplaceWith(MOVE_TO_LEFT_REPLACE), DeprecationLevel.ERROR) @AccessApiOverload public fun DataFrame.moveToLeft(vararg columns: AnyColumnReference): DataFrame = - moveToLeft { columns.toColumnSet() } + moveToStart { columns.toColumnSet() } +@AccessApiOverload +public fun DataFrame.moveToStart(vararg columns: AnyColumnReference): DataFrame = + moveToStart { columns.toColumnSet() } + +@Deprecated(MOVE_TO_LEFT, ReplaceWith(MOVE_TO_LEFT_REPLACE), DeprecationLevel.ERROR) @AccessApiOverload public fun DataFrame.moveToLeft(vararg columns: KProperty<*>): DataFrame = - moveToLeft { columns.toColumnSet() } + moveToStart { columns.toColumnSet() } + +@AccessApiOverload +public fun DataFrame.moveToStart(vararg columns: KProperty<*>): DataFrame = + moveToStart { columns.toColumnSet() } // endregion -// region moveToRight +// region moveToEnd +/** + * Moves the specified [columns\] to the [DataFrame] end. + * Returns a new [DataFrame] with updated columns structure. + * + * @include [SelectingColumns.ColumnGroupsAndNestedColumnsMention] + * + * See [Selecting Columns][MoveToEndSelectingOptions]. + * + * For more information: {@include [DocumentationUrls.Move]} + */ +internal interface MoveToEnd { + /** + * {@comment Version of [SelectingColumns] with correctly filled in examples} + * @include [SelectingColumns] {@include [SetMoveToEndOperationArg]} + */ + interface MoveToEndSelectingOptions +} + +/** {@set [SelectingColumns.OPERATION] [moveToEnd][moveToEnd]} */ +@ExcludeFromSources +private interface SetMoveToEndOperationArg + +/** + * {@include [MoveToEnd]} + * ### This MoveToEnd Overload + */ +@ExcludeFromSources +private interface CommonMoveToEndDocs + +@Deprecated(MOVE_TO_RIGHT, ReplaceWith(MOVE_TO_RIGHT_REPLACE), DeprecationLevel.ERROR) +public fun DataFrame.moveToRight(columns: ColumnsSelector): DataFrame = move(columns).toEnd() + +/** + * @include [CommonMoveToEndDocs] + * @include [SelectingColumns.Dsl.WithExample] {@include [SetMoveToEndOperationArg]} + * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ @Refine -@Interpretable("MoveToRight1") -public fun DataFrame.moveToRight(columns: ColumnsSelector): DataFrame = move(columns).toRight() +@Interpretable("MoveToEnd1") +public fun DataFrame.moveToEnd(columns: ColumnsSelector): DataFrame = move(columns).toEnd() -public fun DataFrame.moveToRight(vararg columns: String): DataFrame = moveToRight { columns.toColumnSet() } +@Deprecated(MOVE_TO_RIGHT, ReplaceWith(MOVE_TO_RIGHT_REPLACE), DeprecationLevel.ERROR) +public fun DataFrame.moveToRight(vararg columns: String): DataFrame = moveToEnd { columns.toColumnSet() } + +/** + * @include [CommonMoveToEndDocs] + * @include [SelectingColumns.ColumnNames.WithExample] {@include [SetMoveToEndOperationArg]} + * @param [columns\] The [Columns Selector][ColumnsSelector] used to select the columns of this [DataFrame] to move. + */ +public fun DataFrame.moveToEnd(vararg columns: String): DataFrame = moveToEnd { columns.toColumnSet() } +@Deprecated(MOVE_TO_RIGHT, ReplaceWith(MOVE_TO_RIGHT_REPLACE), DeprecationLevel.ERROR) @AccessApiOverload public fun DataFrame.moveToRight(vararg columns: AnyColumnReference): DataFrame = - moveToRight { columns.toColumnSet() } + moveToEnd { columns.toColumnSet() } + +@AccessApiOverload +public fun DataFrame.moveToEnd(vararg columns: AnyColumnReference): DataFrame = + moveToEnd { columns.toColumnSet() } +@Deprecated(MOVE_TO_RIGHT, ReplaceWith(MOVE_TO_RIGHT_REPLACE), DeprecationLevel.ERROR) @AccessApiOverload public fun DataFrame.moveToRight(vararg columns: KProperty<*>): DataFrame = - moveToRight { columns.toColumnSet() } + moveToEnd { columns.toColumnSet() } + +@AccessApiOverload +public fun DataFrame.moveToEnd(vararg columns: KProperty<*>): DataFrame = moveToEnd { columns.toColumnSet() } // endregion @@ -93,6 +366,27 @@ public fun DataFrame.moveToRight(vararg columns: KProperty<*>): DataFrame // region into +/** + * Moves columns, previously selected with [move] into a new position specified by a + * given column path within the [DataFrame]. + * If there are non-existent column groups on this path, they will be created. + * + * See [Selecting Columns][SelectingColumns]. + * + * For more information: {@include [DocumentationUrls.Move]} + * + * @include [SelectingColumns.Dsl] + * + * ### Examples: + * ```kotlin + * df.move { age and weight }.into { pathOf("info", it.name()) } + * df.move { age and weight }.into { "info"[it.name()] } + * df.move { name.firstName and name.lastName }.into { pathOf("fullName", it.name().dropLast(4)) } + * ``` + * + * @param [column] The [Column With Path Selector][ColumnsSelector] used to specify + * a path in the [DataFrame] to move columns. + */ public fun MoveClause.into( column: ColumnsSelectionDsl.(ColumnWithPath) -> AnyColumnReference, ): DataFrame = @@ -104,10 +398,32 @@ public fun MoveClause.into( /** * Move a single selected column to top level with a new name */ +@CandidateForRemoval @Refine @Interpretable("MoveInto0") public fun MoveClause.into(column: String): DataFrame = pathOf(column).let { path -> into { path } } +/** + * Moves columns, previously selected with [move] into a new position specified by a + * given column path within the [DataFrame]. + * Provides selected column indices. + * If there are non-existent column groups on this path, they will be created. + * + * See [Selecting Columns][SelectingColumns]. + * + * For more information: {@include [DocumentationUrls.Move]} + * + * @include [SelectingColumns.Dsl] + * + * ### Examples: + * ```kotlin + * df.move { cols { it.name == "user" } } + * .intoIndexed { it, index -> "allUsers"["user\$index"] } + * ``` + * + * @param [column] The [Column With Path Selector And Indices][ColumnsSelector] used to specify + * a path in the [DataFrame] to move columns. + */ public fun MoveClause.intoIndexed( newPathExpression: ColumnsSelectionDsl.(ColumnWithPath, Int) -> AnyColumnReference, ): DataFrame { @@ -121,6 +437,26 @@ public fun MoveClause.intoIndexed( // region under +/** + * Moves columns, previously selected with [move] under a new or + * an existing column group within the [DataFrame]. + * If the column group doesn't exist, it will be created. + * + * See [Selecting Columns][SelectingColumns]. + * + * For more information: {@include [DocumentationUrls.Move]} + * + * @include [SelectingColumns.ColumnNames] + * + * ### Examples: + * ```kotlin + * df.move("age", "weight").under("info") + * df.move { age and weight }.under("info") + * ``` + * + * @param [column] A [ColumnsSelector] that defines the path to a [ColumnGroup] + * in the [DataFrame], where the selected columns will be moved. + */ @Refine @Interpretable("MoveUnder0") public fun MoveClause.under(column: String): DataFrame = pathOf(column).let { path -> under { path } } @@ -130,7 +466,27 @@ public fun MoveClause.under(column: AnyColumnGroupAccessor): DataFr column.path().let { path -> under { path } } /** - * Move selected columns under existing column group + * Moves columns, previously selected with [move] under a new or + * an existing column group specified by a + * column path within the [DataFrame]. + * If there are non-existent column groups on this path, they will be created. + * + * See [Selecting Columns][SelectingColumns]. + * + * For more information: {@include [DocumentationUrls.Move]} + * + * @include [SelectingColumns.Dsl] + * + * ### Examples: + * ```kotlin + * // move under an existing column group + * df.move { age and weight }.under { info } + * // move under a new column group + * df.move { age and weight }.under { columnGroup(info) } + * ``` + * + * @param [column] The [ColumnsSelector] that defines the path to a [ColumnGroup] + * in the [DataFrame], where the selected columns will be moved. */ @Refine @Interpretable("MoveUnder1") @@ -146,8 +502,44 @@ public fun MoveClause.under( // region to +/** + * Moves columns, previously selected with [move] to a new position specified + * by [columnIndex] within the [DataFrame]. + * + * Returns a new [DataFrame] with updated columns structure. + * + * For more information: {@include [DocumentationUrls.Move]} + * + * ### Examples: + * ```kotlin + * df.move { age and weight }.to(0) + * df.move("age", "weight").to(2) + * ``` + * + * @param [columnIndex] The index specifying the position in the [DataFrame] columns + * * where the selected columns will be moved. + */ public fun MoveClause.to(columnIndex: Int): DataFrame = moveTo(columnIndex) +/** + * Moves columns, previously selected with [move] to the top-level within the [DataFrame]. + * Moved columns name can be specified via special ColumnSelectionDsl. + * + * Returns a new [DataFrame] with updated columns. + * + * See [Selecting Columns][SelectingColumns]. + * + * For more information: {@include [DocumentationUrls.Move]} + * + * ### Examples: + * ```kotlin + * df.move { info.age and info.weight }.toTop() + * df.move { colsAtAnyDepth { it.name() == "number" } }.toTop { it.parentName + it.name() } + * ``` + * + * @param [newColumnName] The special [ColumnsSelector] for define name of moved column. + * Optional, the original name is used by default + */ @Refine @Interpretable("ToTop") public fun MoveClause.toTop( @@ -158,10 +550,49 @@ public fun MoveClause.toTop( // region after +/** + * Moves columns, previously selected with [move] to the position after the + * specified [column] within the [DataFrame]. + * + * Returns a new [DataFrame] with updated columns. + * + * See [Selecting Columns][SelectingColumns]. + * + * For more information: {@include [DocumentationUrls.Move]} + * + * ### This After Overload + */ +@ExcludeFromSources +internal interface MoveAfter + +/** + * {@include [MoveAfter]} + * @include [SelectingColumns.Dsl] + * + * ### Examples: + * ```kotlin + * df.move { age and weight }.after { surname } + * df.move { cols(0..2) }.after { col(3) } + * ``` + * + * @param [column] A [ColumnSelector] specifying the column + * after which the selected columns will be placed. + */ @Refine @Interpretable("MoveAfter0") public fun MoveClause.after(column: ColumnSelector): DataFrame = afterOrBefore(column, true) +/** + * {@include [MoveAfter]} + * @include [SelectingColumns.ColumnNames] + * + * ### Examples: + * ```kotlin + * df.move("age", "weight").after("surname") + * ``` + * @param [column] The [Column Name][String] specifying the column + * after which the selected columns will be placed. + */ public fun MoveClause.after(column: String): DataFrame = after { column.toColumnAccessor() } @AccessApiOverload @@ -180,14 +611,67 @@ fun MoveColsClause.before(column: String) = before { column.toColum fun MoveColsClause.before(column: ColumnSelector) = afterOrBefore(column, false) */ -@Refine -@Interpretable("MoveToLeft0") +@Deprecated(TO_LEFT, ReplaceWith(TO_LEFT_REPLACE), DeprecationLevel.ERROR) public fun MoveClause.toLeft(): DataFrame = to(0) +/** + * Moves columns, previously selected with [move] to the [DataFrame] start (on top-level). + * + * Returns a new [DataFrame] with updated columns. + * + * For more information: {@include [DocumentationUrls.Move]} + * + * ### Examples: + * ```kotlin + * df.move { age and weight }.toStart() + * df.move { colsOf() }.toStart() + * df.move("age", "weight").toStart() + * ``` + */ @Refine -@Interpretable("MoveToRight0") +@Interpretable("MoveToStart0") +public fun MoveClause.toStart(): DataFrame = to(0) + +@Deprecated(TO_RIGHT, ReplaceWith(TO_RIGHT_REPLACE), DeprecationLevel.ERROR) public fun MoveClause.toRight(): DataFrame = to(df.ncol) +/** + * Moves columns, previously selected with [move] to the [DataFrame] end. + * + * Returns a new [DataFrame] with updated columns. + * + * For more information: {@include [DocumentationUrls.Move]} + * + * ### Examples: + * ```kotlin + * df.move { age and weight }.toEnd() + * df.move { colsOf() }.toEnd() + * df.move("age", "weight").toEnd() + * ``` + */ +@Refine +@Interpretable("MoveToEnd0") +public fun MoveClause.toEnd(): DataFrame = to(df.ncol) + +/** + * An intermediate class used in the [move] operation. + * + * This class itself does nothing—it is just a transitional step before specifying + * where to move the selected columns. + * It must be followed by one of the positioning methods + * to produce a new [DataFrame] with the updated column structure. + * + * Use the following methods to finalize the move: + * - [to] – moves columns to a specific index. + * - [toStart] – moves columns to the beginning. + * - [toEnd] – moves columns to the end. + * - [into] / [intoIndexed] – moves columns to a new position. + * - [toTop] – moves columns to the top-level. + * - [after] – places columns after a specific column. + * - [under] – nests columns under a column group. + * + * See [Grammar][Move.Grammar] for more details. + */ public class MoveClause(internal val df: DataFrame, internal val columns: ColumnsSelector) { override fun toString(): String = "MoveClause(df=$df, columns=$columns)" } diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt index 36612edcad..c7441eca1d 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/remove.kt @@ -9,7 +9,6 @@ import org.jetbrains.kotlinx.dataframe.annotations.Refine import org.jetbrains.kotlinx.dataframe.columns.ColumnReference import org.jetbrains.kotlinx.dataframe.columns.toColumnSet import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls -import org.jetbrains.kotlinx.dataframe.documentation.DocumentationUrls.Select import org.jetbrains.kotlinx.dataframe.documentation.ExcludeFromSources import org.jetbrains.kotlinx.dataframe.documentation.SelectingColumns import org.jetbrains.kotlinx.dataframe.impl.api.removeImpl diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt index 6e9400cbd6..7754e04822 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/documentation/DocumentationUrls.kt @@ -83,4 +83,7 @@ internal interface DocumentationUrls { /** [See `describe` on the documentation website.]({@include [Url]}/describe.html) */ interface Describe + + /** [See `move` on the documentation website.]({@include [Url]}/move.html) */ + interface Move } diff --git a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt index a500535206..6539d2a584 100644 --- a/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt +++ b/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt @@ -60,6 +60,18 @@ internal const val IS_URL_IMPORT = "org.jetbrains.kotlinx.dataframe.io.isUrl" internal const val MINUS = "This minus overload will be removed in favor of `remove`. $MESSAGE_0_16" internal const val MINUS_REPLACE = "this.remove(columns)" +internal const val MOVE_TO_LEFT = "This `moveToLeft` overload will be removed in favor of `moveToStart`. $MESSAGE_0_16" +internal const val MOVE_TO_LEFT_REPLACE = "this.moveToStart(columns)" + +internal const val MOVE_TO_RIGHT = "This `moveToRight` overload will be removed in favor of `moveToEnd`. $MESSAGE_0_16" +internal const val MOVE_TO_RIGHT_REPLACE = "this.moveToEnd(columns)" + +internal const val TO_LEFT = "This `toLeft` overload will be removed in favor of `toStart`. $MESSAGE_0_16" +internal const val TO_LEFT_REPLACE = "this.toStart()" + +internal const val TO_RIGHT = "This `toRight` overload will be removed in favor of `toEnd`. $MESSAGE_0_16" +internal const val TO_RIGHT_REPLACE = "this.toEnd()" + // endregion // region WARNING in 0.16, ERROR in 0.17 diff --git a/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Modify.kt b/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Modify.kt index 2b7663cbb8..296dacb8bf 100644 --- a/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Modify.kt +++ b/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Modify.kt @@ -88,7 +88,7 @@ import org.jetbrains.kotlinx.dataframe.api.split import org.jetbrains.kotlinx.dataframe.api.sum import org.jetbrains.kotlinx.dataframe.api.to import org.jetbrains.kotlinx.dataframe.api.toFloat -import org.jetbrains.kotlinx.dataframe.api.toLeft +import org.jetbrains.kotlinx.dataframe.api.toStart import org.jetbrains.kotlinx.dataframe.api.toMap import org.jetbrains.kotlinx.dataframe.api.toPath import org.jetbrains.kotlinx.dataframe.api.toTop @@ -114,7 +114,6 @@ import org.junit.Test import java.net.URL import java.time.format.DateTimeFormatter import java.util.* -import kotlin.streams.toList @Suppress("ktlint:standard:chain-method-continuation", "ktlint:standard:argument-list-wrapping") class Modify : TestBase() { @@ -340,7 +339,7 @@ class Modify : TestBase() { @TransformDataFrameExpressions fun move() { // SampleStart - df.move { age }.toLeft() + df.move { age }.toStart() df.move { weight }.to(1) diff --git a/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTests.kt b/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTests.kt index 8a1fda14d8..5bc715e078 100644 --- a/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTests.kt +++ b/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTests.kt @@ -107,8 +107,8 @@ import org.jetbrains.kotlinx.dataframe.api.minOf import org.jetbrains.kotlinx.dataframe.api.minus import org.jetbrains.kotlinx.dataframe.api.move import org.jetbrains.kotlinx.dataframe.api.moveTo -import org.jetbrains.kotlinx.dataframe.api.moveToLeft -import org.jetbrains.kotlinx.dataframe.api.moveToRight +import org.jetbrains.kotlinx.dataframe.api.moveToEnd +import org.jetbrains.kotlinx.dataframe.api.moveToStart import org.jetbrains.kotlinx.dataframe.api.name import org.jetbrains.kotlinx.dataframe.api.named import org.jetbrains.kotlinx.dataframe.api.notNull @@ -142,11 +142,11 @@ import org.jetbrains.kotlinx.dataframe.api.toColumnAccessor import org.jetbrains.kotlinx.dataframe.api.toColumnOf import org.jetbrains.kotlinx.dataframe.api.toDataFrame import org.jetbrains.kotlinx.dataframe.api.toDouble +import org.jetbrains.kotlinx.dataframe.api.toEnd import org.jetbrains.kotlinx.dataframe.api.toInt import org.jetbrains.kotlinx.dataframe.api.toList import org.jetbrains.kotlinx.dataframe.api.toListOf import org.jetbrains.kotlinx.dataframe.api.toMap -import org.jetbrains.kotlinx.dataframe.api.toRight import org.jetbrains.kotlinx.dataframe.api.toStr import org.jetbrains.kotlinx.dataframe.api.toValueColumn import org.jetbrains.kotlinx.dataframe.api.transpose @@ -689,14 +689,14 @@ class DataFrameTests : BaseTest() { @Test fun `move several columns to left`() { - val moved = typed.moveToLeft { weight and age } + val moved = typed.moveToStart { weight and age } val expected = typed.select { cols(weight, age, name, city) } moved shouldBe expected } @Test fun `move several columns to right`() { - val moved = typed.moveToRight { weight and name } + val moved = typed.moveToEnd { weight and name } val expected = typed.select { cols(age, city, weight, name) } moved shouldBe expected } @@ -1130,7 +1130,7 @@ class DataFrameTests : BaseTest() { val cities = filtered.city.toList().map { it!!.lowercase() } val gathered = res.gather { colsOf { cities.contains(it.name()) } }.where { it }.keysInto("city") - val expected = filtered.select { name and age and city.map { it!!.lowercase() } }.moveToRight { city } + val expected = filtered.select { name and age and city.map { it!!.lowercase() } }.moveToEnd { city } gathered shouldBe expected } @@ -2273,7 +2273,7 @@ class DataFrameTests : BaseTest() { df.remove { city }.convertTo() shouldBe df.update { city }.withNull() - .move { city }.toRight() + .move { city }.toEnd() shouldThrow { df.remove { age }.convertTo() @@ -2283,7 +2283,7 @@ class DataFrameTests : BaseTest() { fill { age }.with { -1 } } shouldBe df.update { age }.with { -1 } - .move { age }.toRight() + .move { age }.toEnd() shouldThrow { df.update { name }.at(2).withNull() diff --git a/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTreeTests.kt b/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTreeTests.kt index f84bdea9f9..0a757d4acc 100644 --- a/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTreeTests.kt +++ b/core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/testSets/person/DataFrameTreeTests.kt @@ -72,8 +72,8 @@ import org.jetbrains.kotlinx.dataframe.api.maxBy import org.jetbrains.kotlinx.dataframe.api.median import org.jetbrains.kotlinx.dataframe.api.move import org.jetbrains.kotlinx.dataframe.api.moveTo -import org.jetbrains.kotlinx.dataframe.api.moveToLeft -import org.jetbrains.kotlinx.dataframe.api.moveToRight +import org.jetbrains.kotlinx.dataframe.api.moveToEnd +import org.jetbrains.kotlinx.dataframe.api.moveToStart import org.jetbrains.kotlinx.dataframe.api.pathOf import org.jetbrains.kotlinx.dataframe.api.perRowCol import org.jetbrains.kotlinx.dataframe.api.pivot @@ -554,7 +554,7 @@ class DataFrameTreeTests : BaseTest() { .remove { it[groupCol]["city"] } .ungroup(groupCol) .sortBy { name and age } - res shouldBe typed.sortBy { name and age }.moveToLeft { city } + res shouldBe typed.sortBy { name and age }.moveToStart { city } } @Test @@ -567,7 +567,7 @@ class DataFrameTreeTests : BaseTest() { .remove { it[groupCol]["city"] } .ungroup(groupCol) .sortBy { name and age } - res shouldBe typed.sortBy { name and age }.moveToLeft { city } + res shouldBe typed.sortBy { name and age }.moveToStart { city } } @Test @@ -592,7 +592,7 @@ class DataFrameTreeTests : BaseTest() { @Test fun `join with right path`() { val joined = typed.remove { city }.join(typed2.remove { weight }) { name.match(right.nameAndCity.name) and age } - val expected = typed.moveToRight { city }.move { city }.under("nameAndCity") + val expected = typed.moveToEnd { city }.move { city }.under("nameAndCity") joined shouldBe expected } diff --git a/docs/StardustDocs/topics/move.md b/docs/StardustDocs/topics/move.md index dfbc4cf5d8..faa6e793ba 100644 --- a/docs/StardustDocs/topics/move.md +++ b/docs/StardustDocs/topics/move.md @@ -6,7 +6,7 @@ Moves one or several columns within [`DataFrame`](DataFrame.md). ```kotlin move { columns } - .into { pathSelector } | .under { parentColumn } | .after { column } | .to(position) | .toTop() | .toLeft() | .toRight() + .into { pathSelector } | .under { parentColumn } | .after { column } | .to(position) | .toTop() | .toStart() | .toEnd() pathSelector: DataFrame.(DataColumn) -> ColumnPath ``` @@ -18,7 +18,7 @@ Can be used to change columns hierarchy by providing `ColumnPath` for every move ```kotlin -df.move { age }.toLeft() +df.move { age }.toStart() df.move { weight }.to(1) diff --git a/plugins/kotlin-dataframe/src/org/jetbrains/kotlinx/dataframe/plugin/impl/api/move.kt b/plugins/kotlin-dataframe/src/org/jetbrains/kotlinx/dataframe/plugin/impl/api/move.kt index 90c7db09dd..50f7bc933b 100644 --- a/plugins/kotlin-dataframe/src/org/jetbrains/kotlinx/dataframe/plugin/impl/api/move.kt +++ b/plugins/kotlin-dataframe/src/org/jetbrains/kotlinx/dataframe/plugin/impl/api/move.kt @@ -3,9 +3,9 @@ package org.jetbrains.kotlinx.dataframe.plugin.impl.api import org.jetbrains.kotlinx.dataframe.api.after import org.jetbrains.kotlinx.dataframe.api.into import org.jetbrains.kotlinx.dataframe.api.move -import org.jetbrains.kotlinx.dataframe.api.moveToLeft -import org.jetbrains.kotlinx.dataframe.api.toLeft -import org.jetbrains.kotlinx.dataframe.api.toRight +import org.jetbrains.kotlinx.dataframe.api.moveToStart +import org.jetbrains.kotlinx.dataframe.api.toStart +import org.jetbrains.kotlinx.dataframe.api.toEnd import org.jetbrains.kotlinx.dataframe.api.toTop import org.jetbrains.kotlinx.dataframe.api.under import org.jetbrains.kotlinx.dataframe.columns.toColumnSet @@ -65,32 +65,32 @@ class MoveInto0 : AbstractSchemaModificationInterpreter() { } } -class MoveToLeft0 : AbstractSchemaModificationInterpreter() { +class MoveToStart0 : AbstractSchemaModificationInterpreter() { val Arguments.receiver: MoveClauseApproximation by arg() override fun Arguments.interpret(): PluginDataFrameSchema { val columns = receiver.columns.resolve(receiver.df).map { it.path } - return receiver.df.asDataFrame().move { columns.toColumnSet() }.toLeft().toPluginDataFrameSchema() + return receiver.df.asDataFrame().move { columns.toColumnSet() }.toStart().toPluginDataFrameSchema() } } -class MoveToLeft1 : AbstractSchemaModificationInterpreter() { +class MoveToStart1 : AbstractSchemaModificationInterpreter() { val Arguments.receiver: PluginDataFrameSchema by dataFrame() val Arguments.columns: ColumnsResolver by arg() override fun Arguments.interpret(): PluginDataFrameSchema { val columns = columns.resolve(receiver).map { it.path } - return receiver.asDataFrame().moveToLeft { columns.toColumnSet() }.toPluginDataFrameSchema() + return receiver.asDataFrame().moveToStart { columns.toColumnSet() }.toPluginDataFrameSchema() } } -class MoveToRight0 : AbstractSchemaModificationInterpreter() { +class MoveToEnd0 : AbstractSchemaModificationInterpreter() { val Arguments.receiver: MoveClauseApproximation by arg() override fun Arguments.interpret(): PluginDataFrameSchema { val columns = receiver.columns.resolve(receiver.df).map { it.path } - return receiver.df.asDataFrame().move { columns.toColumnSet() }.toRight().toPluginDataFrameSchema() + return receiver.df.asDataFrame().move { columns.toColumnSet() }.toEnd().toPluginDataFrameSchema() } } diff --git a/plugins/kotlin-dataframe/src/org/jetbrains/kotlinx/dataframe/plugin/loadInterpreter.kt b/plugins/kotlin-dataframe/src/org/jetbrains/kotlinx/dataframe/plugin/loadInterpreter.kt index 2f091af117..c121d5c656 100644 --- a/plugins/kotlin-dataframe/src/org/jetbrains/kotlinx/dataframe/plugin/loadInterpreter.kt +++ b/plugins/kotlin-dataframe/src/org/jetbrains/kotlinx/dataframe/plugin/loadInterpreter.kt @@ -105,9 +105,9 @@ import org.jetbrains.kotlinx.dataframe.plugin.impl.api.MergeInto0 import org.jetbrains.kotlinx.dataframe.plugin.impl.api.Move0 import org.jetbrains.kotlinx.dataframe.plugin.impl.api.MoveAfter0 import org.jetbrains.kotlinx.dataframe.plugin.impl.api.MoveInto0 -import org.jetbrains.kotlinx.dataframe.plugin.impl.api.MoveToLeft0 -import org.jetbrains.kotlinx.dataframe.plugin.impl.api.MoveToLeft1 -import org.jetbrains.kotlinx.dataframe.plugin.impl.api.MoveToRight0 +import org.jetbrains.kotlinx.dataframe.plugin.impl.api.MoveToStart0 +import org.jetbrains.kotlinx.dataframe.plugin.impl.api.MoveToStart1 +import org.jetbrains.kotlinx.dataframe.plugin.impl.api.MoveToEnd0 import org.jetbrains.kotlinx.dataframe.plugin.impl.api.MoveUnder0 import org.jetbrains.kotlinx.dataframe.plugin.impl.api.MoveUnder1 import org.jetbrains.kotlinx.dataframe.plugin.impl.api.PairConstructor @@ -290,9 +290,9 @@ internal inline fun String.load(): T { "MoveUnder0" -> MoveUnder0() "MoveUnder1" -> MoveUnder1() "MoveInto0" -> MoveInto0() - "MoveToLeft0" -> MoveToLeft0() - "MoveToLeft1" -> MoveToLeft1() - "MoveToRight0" -> MoveToRight0() + "MoveToStart0" -> MoveToStart0() + "MoveToStart1" -> MoveToStart1() + "MoveToEnd0" -> MoveToEnd0() "MoveAfter0" -> MoveAfter0() "GroupByAdd" -> GroupByAdd() "Merge0" -> Merge0() diff --git a/plugins/kotlin-dataframe/testData/box/moveToRight.fir.txt b/plugins/kotlin-dataframe/testData/box/moveToEnd.fir.txt similarity index 89% rename from plugins/kotlin-dataframe/testData/box/moveToRight.fir.txt rename to plugins/kotlin-dataframe/testData/box/moveToEnd.fir.txt index 83dfcc3897..9f7ddcd6b2 100644 --- a/plugins/kotlin-dataframe/testData/box/moveToRight.fir.txt +++ b/plugins/kotlin-dataframe/testData/box/moveToEnd.fir.txt @@ -1,6 +1,6 @@ -FILE: moveToRight.kt +FILE: moveToEnd.kt public final fun box(): R|kotlin/String| { - lval df: R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_56>| = R|org/jetbrains/kotlinx/dataframe/api/dataFrameOf|(vararg(String(s))).R|kotlin/let|/Invoke_56>|>( = fun (it: R|org/jetbrains/kotlinx/dataframe/api/DataFrameBuilder|): R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_56>| { + lval df: R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_06>| = R|org/jetbrains/kotlinx/dataframe/api/dataFrameOf|(vararg(String(s))).R|kotlin/let|/Invoke_56>|>( = fun (it: R|org/jetbrains/kotlinx/dataframe/api/DataFrameBuilder|): R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_56>| { local abstract class Invoke_56I : R|kotlin/Any| { @R|org/jetbrains/kotlinx/dataframe/annotations/Order|(order = Int(0)) public abstract val s: R|kotlin/String| public get(): R|kotlin/String| @@ -72,44 +72,44 @@ FILE: moveToRight.kt ).R|org/jetbrains/kotlinx/dataframe/api/move|/Invoke_69|, R|kotlin/Int|>( = move@fun R|org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl</Invoke_69>|.(it: R|org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl</Invoke_69>|): R|org/jetbrains/kotlinx/dataframe/columns/ColumnsResolver| { ^ (this@R|/box|, this@R|special/anonymous|).R|/Scope0.id| } - ).R|kotlin/let|/Invoke_69, kotlin/Int>|, R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_56>|>( = fun (it: R|org/jetbrains/kotlinx/dataframe/api/MoveClause</Invoke_69, kotlin/Int>|): R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_56>| { - local abstract class Invoke_56I : R|kotlin/Any| { + ).R|kotlin/let|/Invoke_69, kotlin/Int>|, R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_06>|>( = fun (it: R|org/jetbrains/kotlinx/dataframe/api/MoveClause</Invoke_69, kotlin/Int>|): R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_06>| { + local abstract class Invoke_06I : R|kotlin/Any| { @R|org/jetbrains/kotlinx/dataframe/annotations/Order|(order = Int(1)) public abstract val id: R|kotlin/Int| public get(): R|kotlin/Int| @R|org/jetbrains/kotlinx/dataframe/annotations/Order|(order = Int(0)) public abstract val s: R|kotlin/String| public get(): R|kotlin/String| - public constructor(): R|/Invoke_56I| + public constructor(): R|/Invoke_06I| } local final class Scope0 : R|kotlin/Any| { - public final val R|org/jetbrains/kotlinx/dataframe/DataRow</Invoke_56I>|.id: R|kotlin/Int| + public final val R|org/jetbrains/kotlinx/dataframe/DataRow</Invoke_06I>|.id: R|kotlin/Int| public get(): R|kotlin/Int| - public final val R|org/jetbrains/kotlinx/dataframe/ColumnsScope</Invoke_56I>|.id: R|org/jetbrains/kotlinx/dataframe/DataColumn| + public final val R|org/jetbrains/kotlinx/dataframe/ColumnsScope</Invoke_06I>|.id: R|org/jetbrains/kotlinx/dataframe/DataColumn| public get(): R|org/jetbrains/kotlinx/dataframe/DataColumn| - public final val R|org/jetbrains/kotlinx/dataframe/DataRow</Invoke_56I>|.s: R|kotlin/String| + public final val R|org/jetbrains/kotlinx/dataframe/DataRow</Invoke_06I>|.s: R|kotlin/String| public get(): R|kotlin/String| - public final val R|org/jetbrains/kotlinx/dataframe/ColumnsScope</Invoke_56I>|.s: R|org/jetbrains/kotlinx/dataframe/DataColumn| + public final val R|org/jetbrains/kotlinx/dataframe/ColumnsScope</Invoke_06I>|.s: R|org/jetbrains/kotlinx/dataframe/DataColumn| public get(): R|org/jetbrains/kotlinx/dataframe/DataColumn| public constructor(): R|/Scope0| } - local abstract class Invoke_56 : R|/Invoke_56I| { + local abstract class Invoke_06 : R|/Invoke_06I| { @R|org/jetbrains/kotlinx/dataframe/annotations/ScopeProperty|() public abstract val scope0: R|/Scope0| public get(): R|/Scope0| - public constructor(): R|/Invoke_56| + public constructor(): R|/Invoke_06| } - ^ R|/it|.R|org/jetbrains/kotlinx/dataframe/api/toRight|/Invoke_69|, R|kotlin/Int|>() + ^ R|/it|.R|org/jetbrains/kotlinx/dataframe/api/toEnd|/Invoke_69|, R|kotlin/Int|>() } ) ^box String(OK) diff --git a/plugins/kotlin-dataframe/testData/box/moveToRight.kt b/plugins/kotlin-dataframe/testData/box/moveToEnd.kt similarity index 77% rename from plugins/kotlin-dataframe/testData/box/moveToRight.kt rename to plugins/kotlin-dataframe/testData/box/moveToEnd.kt index 444125a085..cda9c2966e 100644 --- a/plugins/kotlin-dataframe/testData/box/moveToRight.kt +++ b/plugins/kotlin-dataframe/testData/box/moveToEnd.kt @@ -5,6 +5,6 @@ import org.jetbrains.kotlinx.dataframe.api.* import org.jetbrains.kotlinx.dataframe.io.* fun box(): String { - val df = dataFrameOf("s")("str").addId().move { id }.toRight() + val df = dataFrameOf("s")("str").addId().move { id }.toEnd() return "OK" } diff --git a/plugins/kotlin-dataframe/testData/box/moveToLeft.fir.txt b/plugins/kotlin-dataframe/testData/box/moveToStart.fir.txt similarity index 87% rename from plugins/kotlin-dataframe/testData/box/moveToLeft.fir.txt rename to plugins/kotlin-dataframe/testData/box/moveToStart.fir.txt index cf3b43a6b7..999488ce22 100644 --- a/plugins/kotlin-dataframe/testData/box/moveToLeft.fir.txt +++ b/plugins/kotlin-dataframe/testData/box/moveToStart.fir.txt @@ -1,6 +1,6 @@ -FILE: moveToLeft.kt +FILE: moveToStart.kt public final fun box(): R|kotlin/String| { - lval df: R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_83>| = R|org/jetbrains/kotlinx/dataframe/api/dataFrameOf|(vararg(String(s))).R|kotlin/let|/Invoke_56>|>( = fun (it: R|org/jetbrains/kotlinx/dataframe/api/DataFrameBuilder|): R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_56>| { + lval df: R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_91>| = R|org/jetbrains/kotlinx/dataframe/api/dataFrameOf|(vararg(String(s))).R|kotlin/let|/Invoke_56>|>( = fun (it: R|org/jetbrains/kotlinx/dataframe/api/DataFrameBuilder|): R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_56>| { local abstract class Invoke_56I : R|kotlin/Any| { @R|org/jetbrains/kotlinx/dataframe/annotations/Order|(order = Int(0)) public abstract val s: R|kotlin/String| public get(): R|kotlin/String| @@ -75,47 +75,47 @@ FILE: moveToLeft.kt ).R|org/jetbrains/kotlinx/dataframe/api/move|/Invoke_68|, R|kotlin/Int|>( = move@fun R|org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl</Invoke_68>|.(it: R|org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl</Invoke_68>|): R|org/jetbrains/kotlinx/dataframe/columns/ColumnsResolver| { ^ (this@R|/box|, this@R|special/anonymous|).R|/Scope0.l| } - ).R|kotlin/let|/Invoke_68, kotlin/Int>|, R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_83>|>( = fun (it: R|org/jetbrains/kotlinx/dataframe/api/MoveClause</Invoke_68, kotlin/Int>|): R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_83>| { - local abstract class Invoke_83I : R|kotlin/Any| { + ).R|kotlin/let|/Invoke_68, kotlin/Int>|, R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_91>|>( = fun (it: R|org/jetbrains/kotlinx/dataframe/api/MoveClause</Invoke_68, kotlin/Int>|): R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_91>| { + local abstract class Invoke_91I : R|kotlin/Any| { @R|org/jetbrains/kotlinx/dataframe/annotations/Order|(order = Int(0)) public abstract val l: R|kotlin/Int| public get(): R|kotlin/Int| @R|org/jetbrains/kotlinx/dataframe/annotations/Order|(order = Int(1)) public abstract val s: R|kotlin/String| public get(): R|kotlin/String| - public constructor(): R|/Invoke_83I| + public constructor(): R|/Invoke_91I| } local final class Scope0 : R|kotlin/Any| { - public final val R|org/jetbrains/kotlinx/dataframe/DataRow</Invoke_83I>|.l: R|kotlin/Int| + public final val R|org/jetbrains/kotlinx/dataframe/DataRow</Invoke_91I>|.l: R|kotlin/Int| public get(): R|kotlin/Int| - public final val R|org/jetbrains/kotlinx/dataframe/ColumnsScope</Invoke_83I>|.l: R|org/jetbrains/kotlinx/dataframe/DataColumn| + public final val R|org/jetbrains/kotlinx/dataframe/ColumnsScope</Invoke_91I>|.l: R|org/jetbrains/kotlinx/dataframe/DataColumn| public get(): R|org/jetbrains/kotlinx/dataframe/DataColumn| - public final val R|org/jetbrains/kotlinx/dataframe/DataRow</Invoke_83I>|.s: R|kotlin/String| + public final val R|org/jetbrains/kotlinx/dataframe/DataRow</Invoke_91I>|.s: R|kotlin/String| public get(): R|kotlin/String| - public final val R|org/jetbrains/kotlinx/dataframe/ColumnsScope</Invoke_83I>|.s: R|org/jetbrains/kotlinx/dataframe/DataColumn| + public final val R|org/jetbrains/kotlinx/dataframe/ColumnsScope</Invoke_91I>|.s: R|org/jetbrains/kotlinx/dataframe/DataColumn| public get(): R|org/jetbrains/kotlinx/dataframe/DataColumn| public constructor(): R|/Scope0| } - local abstract class Invoke_83 : R|/Invoke_83I| { + local abstract class Invoke_91 : R|/Invoke_91I| { @R|org/jetbrains/kotlinx/dataframe/annotations/ScopeProperty|() public abstract val scope0: R|/Scope0| public get(): R|/Scope0| - public constructor(): R|/Invoke_83| + public constructor(): R|/Invoke_91| } - ^ R|/it|.R|org/jetbrains/kotlinx/dataframe/api/toLeft|/Invoke_68|, R|kotlin/Int|>() + ^ R|/it|.R|org/jetbrains/kotlinx/dataframe/api/toStart|/Invoke_68|, R|kotlin/Int|>() } ) - lval df1: R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_97>| = R|org/jetbrains/kotlinx/dataframe/api/dataFrameOf|(vararg(String(s))).R|kotlin/let|/Invoke_56>|>( = fun (it: R|org/jetbrains/kotlinx/dataframe/api/DataFrameBuilder|): R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_56>| { + lval df1: R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_68>| = R|org/jetbrains/kotlinx/dataframe/api/dataFrameOf|(vararg(String(s))).R|kotlin/let|/Invoke_56>|>( = fun (it: R|org/jetbrains/kotlinx/dataframe/api/DataFrameBuilder|): R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_56>| { local abstract class Invoke_56I : R|kotlin/Any| { @R|org/jetbrains/kotlinx/dataframe/annotations/Order|(order = Int(0)) public abstract val s: R|kotlin/String| public get(): R|kotlin/String| @@ -187,44 +187,44 @@ FILE: moveToLeft.kt } ) } - ).R|kotlin/let|/Invoke_68>|, R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_97>|>( = fun (it: R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_68>|): R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_97>| { - local abstract class Invoke_97I : R|kotlin/Any| { + ).R|kotlin/let|/Invoke_68>|, R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_68>|>( = fun (it: R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_68>|): R|org/jetbrains/kotlinx/dataframe/DataFrame</Invoke_68>| { + local abstract class Invoke_68I : R|kotlin/Any| { @R|org/jetbrains/kotlinx/dataframe/annotations/Order|(order = Int(0)) public abstract val l: R|kotlin/Int| public get(): R|kotlin/Int| @R|org/jetbrains/kotlinx/dataframe/annotations/Order|(order = Int(1)) public abstract val s: R|kotlin/String| public get(): R|kotlin/String| - public constructor(): R|/Invoke_97I| + public constructor(): R|/Invoke_68I| } local final class Scope0 : R|kotlin/Any| { - public final val R|org/jetbrains/kotlinx/dataframe/DataRow</Invoke_97I>|.l: R|kotlin/Int| + public final val R|org/jetbrains/kotlinx/dataframe/DataRow</Invoke_68I>|.l: R|kotlin/Int| public get(): R|kotlin/Int| - public final val R|org/jetbrains/kotlinx/dataframe/ColumnsScope</Invoke_97I>|.l: R|org/jetbrains/kotlinx/dataframe/DataColumn| + public final val R|org/jetbrains/kotlinx/dataframe/ColumnsScope</Invoke_68I>|.l: R|org/jetbrains/kotlinx/dataframe/DataColumn| public get(): R|org/jetbrains/kotlinx/dataframe/DataColumn| - public final val R|org/jetbrains/kotlinx/dataframe/DataRow</Invoke_97I>|.s: R|kotlin/String| + public final val R|org/jetbrains/kotlinx/dataframe/DataRow</Invoke_68I>|.s: R|kotlin/String| public get(): R|kotlin/String| - public final val R|org/jetbrains/kotlinx/dataframe/ColumnsScope</Invoke_97I>|.s: R|org/jetbrains/kotlinx/dataframe/DataColumn| + public final val R|org/jetbrains/kotlinx/dataframe/ColumnsScope</Invoke_68I>|.s: R|org/jetbrains/kotlinx/dataframe/DataColumn| public get(): R|org/jetbrains/kotlinx/dataframe/DataColumn| public constructor(): R|/Scope0| } - local abstract class Invoke_97 : R|/Invoke_97I| { + local abstract class Invoke_68 : R|/Invoke_68I| { @R|org/jetbrains/kotlinx/dataframe/annotations/ScopeProperty|() public abstract val scope0: R|/Scope0| public get(): R|/Scope0| - public constructor(): R|/Invoke_97| + public constructor(): R|/Invoke_68| } - ^ R|/it|.R|org/jetbrains/kotlinx/dataframe/api/moveToLeft|/Invoke_68|>( = moveToLeft@fun R|org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl</Invoke_68>|.(it: R|org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl</Invoke_68>|): R|org/jetbrains/kotlinx/dataframe/columns/ColumnsResolver<*>| { + ^ R|/it|.R|org/jetbrains/kotlinx/dataframe/api/moveToStart|/Invoke_68|>( = moveToStart@fun R|org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl</Invoke_68>|.(it: R|org/jetbrains/kotlinx/dataframe/api/ColumnsSelectionDsl</Invoke_68>|): R|org/jetbrains/kotlinx/dataframe/columns/ColumnsResolver<*>| { ^ (this@R|/box|, this@R|special/anonymous|).R|/Scope0.l| } ) diff --git a/plugins/kotlin-dataframe/testData/box/moveToLeft.kt b/plugins/kotlin-dataframe/testData/box/moveToStart.kt similarity index 92% rename from plugins/kotlin-dataframe/testData/box/moveToLeft.kt rename to plugins/kotlin-dataframe/testData/box/moveToStart.kt index 066a51e95e..fcf8eeb784 100644 --- a/plugins/kotlin-dataframe/testData/box/moveToLeft.kt +++ b/plugins/kotlin-dataframe/testData/box/moveToStart.kt @@ -5,7 +5,7 @@ import org.jetbrains.kotlinx.dataframe.api.* import org.jetbrains.kotlinx.dataframe.io.* fun box(): String { - val df = dataFrameOf("s")("str").add("l") { s.length }.move { l }.toLeft() - val df1 = dataFrameOf("s")("str").add("l") { s.length }.moveToLeft { l } + val df = dataFrameOf("s")("str").add("l") { s.length }.move { l }.toStart() + val df1 = dataFrameOf("s")("str").add("l") { s.length }.moveToStart { l } return "OK" } diff --git a/plugins/kotlin-dataframe/tests-gen/org/jetbrains/kotlin/fir/dataframe/DataFrameBlackBoxCodegenTestGenerated.java b/plugins/kotlin-dataframe/tests-gen/org/jetbrains/kotlin/fir/dataframe/DataFrameBlackBoxCodegenTestGenerated.java index c3a858926a..b5291f5d84 100644 --- a/plugins/kotlin-dataframe/tests-gen/org/jetbrains/kotlin/fir/dataframe/DataFrameBlackBoxCodegenTestGenerated.java +++ b/plugins/kotlin-dataframe/tests-gen/org/jetbrains/kotlin/fir/dataframe/DataFrameBlackBoxCodegenTestGenerated.java @@ -347,15 +347,15 @@ public void testMoveInto() { } @Test - @TestMetadata("moveToLeft.kt") - public void testMoveToLeft() { - runTest("testData/box/moveToLeft.kt"); + @TestMetadata("moveToEnd.kt") + public void testMoveToEnd() { + runTest("testData/box/moveToEnd.kt"); } @Test - @TestMetadata("moveToRight.kt") - public void testMoveToRight() { - runTest("testData/box/moveToRight.kt"); + @TestMetadata("moveToStart.kt") + public void testMoveToStart() { + runTest("testData/box/moveToStart.kt"); } @Test