Added 3 APIs for Flatten function (#307)

* Added 3 APIs for Flatten function

* Fixed the review

Author: zaleslaw

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

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

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

@@ -1,6 +1,8 @@
 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.junit.Test
 
 class FlattenTests {
@@ -13,6 +15,41 @@ class FlattenTests {
         grouped.add("a") { 0 }.flatten().columnNames() shouldBe listOf("a1", "b", "c", "a")
     }
 
+    @DataSchema
+    interface TestRow {
+        val a: String
+        val b: String
+        val c: String
+    }
+
+    @DataSchema
+    interface Grouped {
+        val d: DataRow<TestRow>
+    }
+
+    @Test
+    fun `flatten access APIs`() {
+        val df = dataFrameOf("a", "b", "c")(1, 2, 3)
+        val grouped = df.group("a", "b").into("d")
+
+        // String API
+        grouped.flatten("d") shouldBe df
+        val castedGroupedDF = grouped.cast<Grouped>()
+
+        // KProperties API
+        castedGroupedDF.flatten(Grouped::d) shouldBe df
+
+        // Extension properties API
+        castedGroupedDF.flatten { d } shouldBe df
+
+        // Column accessors API
+        val d by columnGroup()
+        val a by d.column<String>()
+        val b by d.column<String>()
+        val c by d.column<String>()
+        grouped.flatten(d) shouldBe df
+    }
+
     @Test
     fun `flatten nested`() {
         val df = dataFrameOf("a", "b", "c", "d")(1, 2, 3, 4)

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

@@ -1052,14 +1052,44 @@ class Modify : TestBase() {
     }
 
     @Test
-    fun flatten() {
+    fun flatten_properties() {
         // SampleStart
         // name.firstName -> firstName
         // name.lastName -> lastName
         df.flatten { name }
         // SampleEnd
     }
 
+    @Test
+    fun flatten_strings() {
+        // SampleStart
+        // name.firstName -> firstName
+        // name.lastName -> lastName
+        df.flatten("name")
+        // SampleEnd
+    }
+
+    @Test
+    fun flatten_accessors() {
+        // SampleStart
+        val name by columnGroup()
+        val firstName by name.column<String>()
+        val lastName by name.column<String>()
+        // name.firstName -> firstName
+        // name.lastName -> lastName
+        df.flatten(name)
+        // SampleEnd
+    }
+
+    @Test
+    fun flatten_KProperties() {
+        // SampleStart
+        // name.firstName -> firstName
+        // name.lastName -> lastName
+        df.flatten(df::name)
+        // SampleEnd
+    }
+
     @Test
     fun flattenAll() {
         // SampleStart

docs/StardustDocs/topics/flatten.md

@@ -11,13 +11,36 @@ flatten  [ { columns } ]
 Columns after flattening will keep their original names. Potential column name clashes are resolved by adding minimal possible name prefix from ancestor columns.
 
 <!---FUN flatten-->
+<tabs>
+<tab title="Properties">
 
 ```kotlin
 // name.firstName -> firstName
 // name.lastName -> lastName
 df.flatten { name }
 ```
 
+</tab>
+<tab title="Accessors">
+
+```kotlin
+val name by columnGroup()
+val firstName by name.column<String>()
+val lastName by name.column<String>()
+
+// name.firstName -> firstName
+// name.lastName -> lastName
+df.flatten(name)
+```
+
+</tab>
+<tab title="Strings">
+
+```kotlin
+df.flatten("name")
+```
+
+</tab></tabs>
 <!---END-->
 
 To remove all column groupings in [`DataFrame`](DataFrame.md), invoke `flatten` without parameters: