Merge pull request #1837 from Kotlin/rename-to

API change: Rename to

Author: Jolanrensen

core/api/core.api

@@ -3937,6 +3937,8 @@ public final class org/jetbrains/kotlinx/dataframe/api/RenameKt {
 	public static final fun rename (Lorg/jetbrains/kotlinx/dataframe/columns/ColumnReference;Lorg/jetbrains/kotlinx/dataframe/columns/ColumnAccessor;)Lorg/jetbrains/kotlinx/dataframe/columns/ColumnReference;
 	public static final fun renameToCamelCase (Lorg/jetbrains/kotlinx/dataframe/DataFrame;)Lorg/jetbrains/kotlinx/dataframe/DataFrame;
 	public static final fun renameToCamelCase (Lorg/jetbrains/kotlinx/dataframe/columns/ColumnReference;)Lorg/jetbrains/kotlinx/dataframe/columns/ColumnReference;
+	public static final fun to (Lorg/jetbrains/kotlinx/dataframe/api/RenameClause;Lkotlin/jvm/functions/Function1;)Lorg/jetbrains/kotlinx/dataframe/DataFrame;
+	public static final fun to (Lorg/jetbrains/kotlinx/dataframe/api/RenameClause;[Ljava/lang/String;)Lorg/jetbrains/kotlinx/dataframe/DataFrame;
 	public static final fun toCamelCase (Lorg/jetbrains/kotlinx/dataframe/api/RenameClause;)Lorg/jetbrains/kotlinx/dataframe/DataFrame;
 }
 

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/rename.kt

@@ -27,6 +27,7 @@ import org.jetbrains.kotlinx.dataframe.impl.columnName
 import org.jetbrains.kotlinx.dataframe.impl.columns.renamedColumn
 import org.jetbrains.kotlinx.dataframe.impl.toCamelCaseByDelimiters
 import org.jetbrains.kotlinx.dataframe.util.DEPRECATED_ACCESS_API
+import org.jetbrains.kotlinx.dataframe.util.RENAME_INTO
 import kotlin.reflect.KProperty
 
 // region DataFrame
@@ -38,8 +39,8 @@ import kotlin.reflect.KProperty
  * returns a [RenameClause],
  * which serves as an intermediate step.
  * The [RenameClause] object provides methods to rename selected columns using:
- * - [into(name)][RenameClause.into] - renames selected columns to the specified names.
- * - [into { nameExpression }][RenameClause.into] - renames selected columns using a provided
+ * - [to(name)][RenameClause.to] - renames selected columns to the specified names.
+ * - [to { nameExpression }][RenameClause.to] - renames selected columns using a provided
  * expression assuming column with its path and returning a new name.
  * - [toCamelCase()][RenameClause.toCamelCase] - renames all selected columns to "camelCase".
  *
@@ -72,10 +73,10 @@ internal interface RenameDocs {
      * [**`rename`**][rename]**`  { `**`columnsSelector: `[`ColumnsSelector`][ColumnsSelector]`  `**`}`**
      *
      * {@include [Indent]}
-     * `| `__`.`__[**`into`**][RenameClause.into]**`(`**`name: `[`String`][String]**`)`**
+     * `| `__`.`__[**`to`**][RenameClause.to]**`(`**`newNames: `[`String`][String]**`, ..)`**
      *
      * {@include [Indent]}
-     * `| `__`.`__[**`into`**][RenameClause.into]**`  { `**`nameExpression: (`[`ColumnWithPath`][ColumnWithPath]`) -> `[String]` `**`}`**
+     * `| `__`.`__[**`to`**][RenameClause.to]**`  { `**`nameExpression: (`[`ColumnWithPath`][ColumnWithPath]`) -> `[String]` `**`}`**
      *
      * {@include [Indent]}
      * `| `__`.`__[**`toCamelCase`**][RenameClause.toCamelCase]**`()`**
@@ -115,18 +116,18 @@ private typealias CommonRenameDocs = Nothing
 @Interpretable("RenameMapping")
 public fun <T> DataFrame<T>.rename(vararg mappings: Pair<String, String>): DataFrame<T> =
     rename { mappings.map { it.first.toColumnAccessor() }.toColumnSet() }
-        .into(*mappings.map { it.second }.toTypedArray())
+        .to(*mappings.map { it.second }.toTypedArray())
 
 /**
  * @include [CommonRenameDocs]
  * @include [SelectingColumns.ColumnsSelectionDsl] {@include [SetRenameOperationArg]}
  * ### Examples:
  * ```kotlin
  * // Rename "col1" to "width" and "col2" to "length"
- * df.rename { col1 and col2 }.into("width", "length")
+ * df.rename { col1 and col2 }.to("width", "length")
  *
  * // Rename all columns using their full path, delimited by "->"
- * df.rename { colsAtAnyDepth() }.into { it.path.joinToString("->") }
+ * df.rename { colsAtAnyDepth() }.to { it.path.joinToString("->") }
  *
  * // Renames all numeric columns to "camelCase"
  * df.rename { colsOf<Number>() }.toCamelCase()
@@ -151,7 +152,7 @@ public fun <T, C> DataFrame<T>.rename(vararg cols: KProperty<C>): RenameClause<T
  * ### Examples:
  * ```kotlin
  * // Rename "col1" to "width" and "col2" to "length"
- * df.rename("col1", "col2").into("width", "length")
+ * df.rename("col1", "col2").to("width", "length")
  *
  * // Renames "arrival_date" and "passport-ID" columns to "camelCase"
  * df.rename("arrival_date", "passport-ID").toCamelCase()
@@ -172,8 +173,8 @@ public fun <T> DataFrame<T>.rename(vararg cols: String): RenameClause<T, Any?> =
  * in the [DataFrame], but their names will be changed.
  *
  * Use the following methods to perform the conversion:
- * - [into(name)][RenameClause.into] — renames selected columns to the specified names.
- * - [into { nameExpression }][RenameClause.into] — renames selected columns using a custom expression,
+ * - [to(name)][RenameClause.to] — renames selected columns to the specified names.
+ * - [to { nameExpression }][RenameClause.to] — renames selected columns using a custom expression,
  *   which takes the column and its path and returns a new name.
  * - [toCamelCase()][RenameClause.toCamelCase] — renames all selected columns to `camelCase`.
  *
@@ -226,9 +227,12 @@ public fun <T> DataFrame<T>.renameToCamelCase(): DataFrame<T> =
 @Deprecated(DEPRECATED_ACCESS_API)
 @AccessApiOverload
 public fun <T, C> RenameClause<T, C>.into(vararg newColumns: ColumnReference<*>): DataFrame<T> =
-    into(*newColumns.map { it.name() }.toTypedArray())
+    to(*newColumns.map { it.name() }.toTypedArray())
 
 /**
+ * __NOTE:__ While you can keep using 'into', we recommend using [to][RenameClause.to] for
+ *  * better readability and more natural English.
+ *
  * Renames the columns selected with [rename] to the specified [newNames],
  * preserving their values and positions within the [DataFrame].
  *
@@ -254,14 +258,46 @@ public fun <T, C> RenameClause<T, C>.into(vararg newColumns: ColumnReference<*>)
  */
 @Refine
 @Interpretable("RenameInto")
+@Deprecated(message = RENAME_INTO, replaceWith = ReplaceWith("to(*newNames)"))
 public fun <T, C> RenameClause<T, C>.into(vararg newNames: String): DataFrame<T> = renameImpl(newNames)
 
+/**
+ * Renames the columns selected with [rename] to the specified [newNames],
+ * preserving their values and positions within the [DataFrame].
+ *
+ * The mapping is positional: [newNames] are applied in the order
+ * the columns were selected — the first selected column is renamed to the first name,
+ * the second to the second, and so on.
+ *
+ * For more information: {@include [DocumentationUrls.Rename]}
+ *
+ * Check out [Grammar][RenameDocs.Grammar].
+ *
+ * ### Examples:
+ * ```kotlin
+ * // Rename "col1" to "width" and "col2" to "length"
+ * df.rename("col1", "col2").to("width", "length")
+ *
+ * // Rename "col1" to "width" and "col2" to "length"
+ * df.rename { col1 and col2 }.to("width", "length")
+ * ```
+ *
+ * @param newNames The new names for the selected columns, applied in order of selecting.
+ * @return A new [DataFrame] with the columns renamed.
+ */
+@Refine
+@Interpretable("RenameInto")
+public fun <T, C> RenameClause<T, C>.to(vararg newNames: String): DataFrame<T> = renameImpl(newNames)
+
 @Deprecated(DEPRECATED_ACCESS_API)
 @AccessApiOverload
 public fun <T, C> RenameClause<T, C>.into(vararg newNames: KProperty<*>): DataFrame<T> =
-    into(*newNames.map { it.name }.toTypedArray())
+    to(*newNames.map { it.name }.toTypedArray())
 
 /**
+ * __NOTE:__ While you can keep using 'into', we recommend using [to][RenameClause.to] for
+ * better readability and more natural English.
+ *
  * Renames the columns selected with [rename] by applying the [transform] expression
  * to each of them. This expression receives the column together with its full path
  * (as [ColumnWithPath]) and must return the new name for that column.
@@ -286,9 +322,37 @@ public fun <T, C> RenameClause<T, C>.into(vararg newNames: KProperty<*>): DataFr
  */
 @Refine
 @Interpretable("RenameIntoLambda")
+@Deprecated(message = RENAME_INTO, replaceWith = ReplaceWith("to(transform)"))
 public fun <T, C> RenameClause<T, C>.into(transform: (ColumnWithPath<C>) -> String): DataFrame<T> =
     renameImpl(transform)
 
+/**
+ * Renames the columns selected with [rename] by applying the [transform] expression
+ * to each of them. This expression receives the column together with its full path
+ * (as [ColumnWithPath]) and must return the new name for that column.
+ * The operation preserves the original columns’ values and their positions within the [DataFrame].
+ *
+ * For more information: {@include [DocumentationUrls.Rename]}
+ *
+ * Check out [Grammar][RenameDocs.Grammar] for more details.
+ *
+ * ### Examples:
+ * ```kotlin
+ * // Rename all columns using their full path, delimited by "->"
+ * df.rename { colsAtAnyDepth() }.to { it.path.joinToString("->") }
+ *
+ * // Rename all `String` columns with uppercase
+ * df.rename { colsOf<String>() }.to { it.name.uppercase() }
+ * ```
+ *
+ * @param transform A function that takes a [ColumnWithPath] for each selected column
+ * and returns the new column name.
+ * @return A new [DataFrame] with the columns renamed.
+ */
+@Refine
+@Interpretable("RenameIntoLambda")
+public fun <T, C> RenameClause<T, C>.to(transform: (ColumnWithPath<C>) -> String): DataFrame<T> = renameImpl(transform)
+
 /**
  * Renames the columns, previously selected with [rename] to "camelCase" format.
  *
@@ -321,7 +385,7 @@ public fun <T, C> RenameClause<T, C>.into(transform: (ColumnWithPath<C>) -> Stri
  */
 @Refine
 @Interpretable("RenameToCamelCaseClause")
-public fun <T, C> RenameClause<T, C>.toCamelCase(): DataFrame<T> = into { it.renameToCamelCase().name() }
+public fun <T, C> RenameClause<T, C>.toCamelCase(): DataFrame<T> = to { it.renameToCamelCase().name() }
 
 // endregion
 

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/GroupByImpl.kt

@@ -18,6 +18,7 @@ import org.jetbrains.kotlinx.dataframe.api.isColumnGroup
 import org.jetbrains.kotlinx.dataframe.api.pathOf
 import org.jetbrains.kotlinx.dataframe.api.remove
 import org.jetbrains.kotlinx.dataframe.api.rename
+import org.jetbrains.kotlinx.dataframe.api.to
 import org.jetbrains.kotlinx.dataframe.columns.FrameColumn
 import org.jetbrains.kotlinx.dataframe.impl.aggregation.AggregatableInternal
 import org.jetbrains.kotlinx.dataframe.impl.aggregation.GroupByReceiverImpl
@@ -63,7 +64,7 @@ internal class GroupByImpl<T, G>(
         if (groupedColumnName == null || groupedColumnName == groups.name()) {
             df
         } else {
-            df.rename(groups).into(groupedColumnName)
+            df.rename(groups).to(groupedColumnName)
         }
 }
 

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/util/deprecationMessages.kt

@@ -304,4 +304,8 @@ internal const val ALL_COLS_EXCEPT_REPLACE = "this.allColsExcept { other }"
 internal const val ALL_COLS_EXCEPT_REPLACE_VARARG = "this.allColsExcept { others.toColumnSet() }"
 internal const val EXCEPT_REPLACE = "this.except { other }"
 internal const val EXCEPT_REPLACE_VARARG = "this.except { others.toColumnSet() }"
+
+internal const val RENAME_INTO =
+    "'into' has been replaced with 'to', because 'rename to' is more common in English. You can keep using 'into', but we advise using 'to'."
+
 // endregion

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/api/allExcept.kt

@@ -18,7 +18,7 @@ class AllExceptTests : ColumnsSelectionDslTests() {
 
     @Test
     fun `issue 761`() {
-        val renamed = df.rename { colsAtAnyDepth() except name.firstName }.into { it.name.uppercase() }
+        val renamed = df.rename { colsAtAnyDepth() except name.firstName }.to { it.name.uppercase() }
         renamed.columnNames() shouldBe listOf("NAME", "AGE", "CITY", "WEIGHT", "ISHAPPY")
         renamed.getColumnGroup("NAME").columnNames() shouldBe listOf("firstName", "LASTNAME")
 

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/api/constructors.kt

@@ -304,7 +304,7 @@ class ConstructorsTests {
 
                 else -> error("Unexpected column name: $it")
             }
-        }.rename { all() }.into { names[it.name.toInt() - 1] }
+        }.rename { all() }.to { names[it.name.toInt() - 1] }
 
         val df4 = dataFrameOf(names).invoke {
             when (it) {

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/api/flatten.kt

@@ -3,6 +3,7 @@ package org.jetbrains.kotlinx.dataframe.api
 import io.kotest.matchers.shouldBe
 import org.jetbrains.kotlinx.dataframe.DataRow
 import org.jetbrains.kotlinx.dataframe.annotations.DataSchema
+import org.jetbrains.kotlinx.dataframe.api.to
 import org.junit.Test
 
 @Suppress("ktlint:standard:argument-list-wrapping")
@@ -72,7 +73,7 @@ class FlattenTests {
         val grouped = df
             .group("a", "b").into("e")
             .group("e", "c").into("f")
-            .rename { "f"["e"] }.into("a")
+            .rename { "f"["e"] }.to("a")
         val flattened = grouped.flatten { "f"["a"] }
         flattened.getColumnGroup("f").columnNames() shouldBe listOf("a", "b", "c")
         flattened.ungroup("f") shouldBe df

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/api/format.kt

@@ -5,6 +5,7 @@ import io.kotest.matchers.shouldNotBe
 import org.jetbrains.kotlinx.dataframe.api.FormattingDsl.blue
 import org.jetbrains.kotlinx.dataframe.api.FormattingDsl.red
 import org.jetbrains.kotlinx.dataframe.api.FormattingDsl.rgb
+import org.jetbrains.kotlinx.dataframe.api.to
 import org.jetbrains.kotlinx.dataframe.io.DisplayConfiguration
 import org.jetbrains.kotlinx.dataframe.samples.api.TestBase
 import org.jetbrains.kotlinx.dataframe.samples.api.age
@@ -329,7 +330,7 @@ class FormatTests : TestBase() {
             .groupBy("city").toDataFrame()
             .add("cityCopy") { "city"<String>() }
             .group("city").into("cityGroup")
-            .rename("cityCopy").into("city")
+            .rename("cityCopy").to("city")
 
         val formatted = df.format("city").with { bold and italic and textColor(green) }
         val html = formatted.toHtml().toString()

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/api/rename.kt

@@ -3,6 +3,7 @@ package org.jetbrains.kotlinx.dataframe.api
 import io.kotest.assertions.asClue
 import io.kotest.assertions.throwables.shouldNotThrowAny
 import io.kotest.matchers.shouldBe
+import org.jetbrains.kotlinx.dataframe.api.to
 import org.jetbrains.kotlinx.dataframe.impl.columns.asAnyFrameColumn
 import org.jetbrains.kotlinx.dataframe.samples.api.age
 import org.junit.Test
@@ -27,8 +28,8 @@ class RenameTests : ColumnsSelectionDslTests() {
             4, 5, 6,
         )
 
-        simpleDf.rename { all() }.into { it.name + "_renamed" } shouldBe renamedDf
-        simpleDf.rename { all() }.into("a_renamed", "b_renamed", "c_renamed") shouldBe renamedDf
+        simpleDf.rename { all() }.to { it.name + "_renamed" } shouldBe renamedDf
+        simpleDf.rename { all() }.to("a_renamed", "b_renamed", "c_renamed") shouldBe renamedDf
     }
 
     @Test
@@ -54,7 +55,7 @@ class RenameTests : ColumnsSelectionDslTests() {
 
         groupedDf
             .rename { "group" and "group"["a"] }
-            .into { it.name + "_renamed" } shouldBe renamedDf
+            .to { it.name + "_renamed" } shouldBe renamedDf
     }
 
     @Test
@@ -66,7 +67,7 @@ class RenameTests : ColumnsSelectionDslTests() {
 
         groupedDf
             .rename { colsAtAnyDepth() }
-            .into { it.name + "_renamed" } shouldBe renamedDf
+            .to { it.name + "_renamed" } shouldBe renamedDf
     }
 
     @Test
@@ -80,7 +81,7 @@ class RenameTests : ColumnsSelectionDslTests() {
 
         doubleGroupedDf
             .rename { colsAtAnyDepth() }
-            .into { it.name + "_renamed" } shouldBe renamedDf
+            .to { it.name + "_renamed" } shouldBe renamedDf
     }
 
     interface Person2 {

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/samples/api/Join.kt

@@ -16,6 +16,7 @@ import org.jetbrains.kotlinx.dataframe.api.leftJoin
 import org.jetbrains.kotlinx.dataframe.api.rename
 import org.jetbrains.kotlinx.dataframe.api.rightJoin
 import org.jetbrains.kotlinx.dataframe.api.select
+import org.jetbrains.kotlinx.dataframe.api.to
 import org.jetbrains.kotlinx.dataframe.columns.ColumnGroup
 import org.jetbrains.kotlinx.dataframe.explainer.TransformDataFrameExpressions
 import org.junit.Test
@@ -55,7 +56,7 @@ class Join : TestBase() {
     @Test
     @TransformDataFrameExpressions
     fun joinWithMatch_properties() {
-        val other = other.rename { name }.into("fullName").cast<Right>()
+        val other = other.rename { name }.to("fullName").cast<Right>()
         val joined =
             // SampleStart
             df.join(other) { name match right.fullName }