Rename new() into newValue for AddDataRow receiver. Add KDocs and fibonacci sample.

Author: nikitinas

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

@@ -81,11 +81,18 @@ public fun <T> DataFrame<T>.addAll(dataFrames: Iterable<AnyFrame>): DataFrame<T>
 // region Create and add a single column
 
 /**
- * Receiver that is used in [add] and [update] operations to access new (added or updated) column value in preceding row
+ * Receiver that is used in [add] and [update] operations to access new (added or updated) column value in preceding row.
  */
 public interface AddDataRow<out T> : DataRow<T> {
 
-    public fun <C> AnyRow.new(): C
+    /**
+     * Returns a new value that was already computed for some preceding row during current [add] or [update] column operation.
+     *
+     * Can be used to compute series of values with recurrence relations, e.g. fibonacci.
+     *
+     * @throws IndexOutOfBoundsException when called on a successive row that doesn't have new value yet
+     */
+    public fun <C> AnyRow.newValue(): C
 }
 
 public typealias AddExpression<T, C> = Selector<AddDataRow<T>, C>

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

@@ -46,7 +46,7 @@ internal class AddDataRowImpl<T>(index: Int, owner: DataFrame<T>, private val co
     DataRowImpl<T>(index, owner),
     AddDataRow<T> {
 
-    override fun <C> AnyRow.new() = container[index] as C
+    override fun <C> AnyRow.newValue() = container[index] as C
 }
 
 @PublishedApi

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/puzzles/HardTests.kt

@@ -18,11 +18,11 @@ class HardTests {
         val y = columnOf(1, 2, 0, 1, 2, 3, 4, 0, 1, 2).named("Y")
 
         df.mapToColumn("Y") {
-            if (it[x] == 0) 0 else (prev()?.new() ?: 0) + 1
+            if (it[x] == 0) 0 else (prev()?.newValue() ?: 0) + 1
         } shouldBe y
 
         df.mapToColumn("Y") {
-            if (it["X"] == 0) 0 else (prev()?.new() ?: 0) + 1
+            if (it["X"] == 0) 0 else (prev()?.newValue() ?: 0) + 1
         } shouldBe y
     }
 

docs/StardustDocs/topics/add.md

@@ -42,6 +42,19 @@ df.add("year of birth") { 2021 - "age"<Int>() }
 
 See [row expressions](DataRow.md#row-expressions)
 
+You can use `newValue()` function to access value that was already calculated for preceding row. It is helpful for recurrent computations:
+
+<!---FUN addRecurrent-->
+
+```kotlin
+df.add("fibonacci") {
+    if(index() < 2) 1
+    else prev()!!.newValue<Int>() + prev()!!.prev()!!.newValue<Int>()
+}
+```
+
+<!---END-->
+
 **Create and add several columns to `DataFrame`:**
 
 ```kotlin

examples/jupyter-notebooks/puzzles/40 puzzles.ipynb

@@ -1985,7 +1985,11 @@
   {
    "cell_type": "code",
    "execution_count": 37,
-   "metadata": {},
+   "metadata": {
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   },
    "outputs": [
     {
      "data": {
@@ -2022,7 +2026,7 @@
    ],
    "source": [
     "df.mapToColumn(\"Y\") {\n",
-    "    if(it.X == 0) 0 else (prev()?.new() ?: 0) + 1\n",
+    "    if(it.X == 0) 0 else (prev()?.newValue() ?: 0) + 1\n",
     "}"
    ]
   },
@@ -3094,9 +3098,13 @@
   },
   {
    "cell_type": "markdown",
-   "metadata": {},
+   "metadata": {
+    "pycharm": {
+     "name": "#%% md\n"
+    }
+   },
    "source": [
-    "The DataFrame looks much better now!"
+    "The DataFrame looks much better now!\n"
    ]
   }
  ],
@@ -3118,4 +3126,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 1
-}
+}

tests/src/test/kotlin/org/jetbrains/kotlinx/dataframe/api/add.kt

@@ -1,5 +1,6 @@
 package org.jetbrains.kotlinx.dataframe.api
 
+import io.kotest.assertions.throwables.shouldThrow
 import io.kotest.matchers.shouldBe
 import org.junit.Test
 
@@ -9,8 +10,17 @@ class AddTests {
     fun `add with new`() {
         val x by columnOf(7, 2, 0, 3, 4, 2, 5, 0, 3, 4)
         val df = dataFrameOf(x)
-        val added = df.add("Y") { if (x() == 0) 0 else (prev()?.new() ?: 0) + 1 }
+        val added = df.add("Y") { if (x() == 0) 0 else (prev()?.newValue() ?: 0) + 1 }
         val expected = listOf(1, 2, 0, 1, 2, 3, 4, 0, 1, 2)
         added["Y"].values() shouldBe expected
     }
+
+    @Test
+    fun `throw for newValue at the next row`() {
+        val x by columnOf(7, 2, 0, 3, 4, 2, 5, 0, 3, 4)
+        val df = dataFrameOf(x)
+        shouldThrow<IndexOutOfBoundsException> {
+            df.add("y") { next()?.newValue() ?: 1 }
+        }
+    }
 }

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

@@ -692,6 +692,16 @@ class Modify : TestBase() {
         // SampleEnd
     }
 
+    @Test
+    fun addRecurrent() {
+        // SampleStart
+        df.add("fibonacci") {
+            if(index() < 2) 1
+            else prev()!!.newValue<Int>() + prev()!!.prev()!!.newValue<Int>()
+        }
+        // SampleEnd
+    }
+
     @Test
     fun addExisting() {
         // SampleStart