Add documentation and tests for `DataColumnArithmetics.kt` by Allex-Nik · Pull Request #1769 · Kotlin/dataframe

Allex-Nik · 2026-03-26T14:55:03Z

Fixes #530

Added:

KDocs
Tests
Website documentation

for DataColumnArithmetics.kt

Allex-Nik · 2026-03-26T14:59:29Z

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

+ * using the logical `not` operation: `true` becomes `false`, and `false` becomes `true`.}
+ * @set [NOT_RETURN] A [ColumnReference] containing the negated [Boolean] values of this [reference][ColumnReference].
+ */
 public operator fun ColumnReference<Boolean>.not(): ColumnReference<Boolean> = map { !it }


Should we reuse the example for DataColumn (as one of implementations) here and in other cases when ColumnReference is used?

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

Allex-Nik · 2026-03-26T15:10:21Z

docs/StardustDocs/topics/columnArithmetics.md

+
+## When useful
+
+In most transformations, these column operations are usually not the preferred approach in Kotlin DataFrame, 


Not sure if I conveyed the idea in sufficient detail. Is there anything that should be added?

docs/StardustDocs/topics/columnArithmetics.md

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

…ove redundant comment.

Allex-Nik · 2026-03-26T15:40:57Z

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

+ * @include [NumberPlusColumnDocs]
+ * @set [NUMBER_PLUS_COLUMN_NUMBER_TYPE] [Double]
+ * @set [NUMBER_PLUS_COLUMN_EXAMPLE_NUMBER] 10.0
+ * @set [NUMBER_PLUS_COLUMN_SEE_ALSO] [minus][DataColumn.minus], [times][DataColumn.times], [div][DataColumn.div]


This refers to DataColumn<Int>.minus(value: Int): DataColumn<Int>.
Isn't there any way to refer to Double.minus(column: DataColumn<Int>) instead?

[minus][Double.minus] doesn't work because it refers to public final operator fun minus(other: Byte): Double from Kotlin.

nope... [Double.minus] is the closest we can get. If there's multiple matches, the 2026 IDE does give you a list to pick, but there's no way to specify an exact function in KDocs :/ (yet!)

is sort of mentioned here https://youtrack.jetbrains.com/issue/KT-69919/DM-2024-07-23-Revisit-KDoc-design-Ambiguous-KDoc-references and related issues

Jolanrensen

thanks! :D

Jolanrensen · 2026-03-27T14:20:58Z

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

+ * ```kotlin
+ * // Given a DataFrame of financial transactions,
+ * // create a column indicating which transactions failed
+ * val failed = !df.isSuccessful.rename("failed")


hmm, maybe this example could also include an example from inside the selection DSL

actually, it's not often we work with columns outside a dataframe. we could :) but it's probably best to show it inside a dataframe operation first

Jolanrensen · 2026-03-27T14:24:20Z

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


+/**
+ * @include [NotDocs]
+ * @set [NOT_NULL_NOTE] Each `null` value in the original [DataColumn] is preserved.


careful mixing block- and inline tags, you can see when you place your cursor here which text is included by this @set tag. Because it doesn't have {} around it, the {@set } below it becomes part of the [NOT_NULL_NOTE]. (okay in practice, the {@set } will be read first and removed from the KDOC, so nothing of it actually enters [NOT_NULL_NOTE], but mixing scopes it generally only a good idea if it's intentional)

In this case, I would turn them all into block tags (so without {}), then each tag continues until it encounters another or the end of the kdoc is reached. Same as @param and @return :)

the same happens in other places

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

Jolanrensen · 2026-03-27T14:52:18Z

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

+ * @include [NumberPlusColumnDocs]
+ * @set [NUMBER_PLUS_COLUMN_NUMBER_TYPE] [Double]
+ * @set [NUMBER_PLUS_COLUMN_EXAMPLE_NUMBER] 10.0
+ * @set [NUMBER_PLUS_COLUMN_SEE_ALSO] [minus][DataColumn.minus], [times][DataColumn.times], [div][DataColumn.div]


nope... [Double.minus] is the closest we can get. If there's multiple matches, the 2026 IDE does give you a list to pick, but there's no way to specify an exact function in KDocs :/ (yet!)

Jolanrensen · 2026-03-27T14:54:50Z

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

+ * @include [NumberPlusColumnDocs]
+ * @set [NUMBER_PLUS_COLUMN_NUMBER_TYPE] [Double]
+ * @set [NUMBER_PLUS_COLUMN_EXAMPLE_NUMBER] 10.0
+ * @set [NUMBER_PLUS_COLUMN_SEE_ALSO] [minus][DataColumn.minus], [times][DataColumn.times], [div][DataColumn.div]


is sort of mentioned here https://youtrack.jetbrains.com/issue/KT-69919/DM-2024-07-23-Revisit-KDoc-design-Ambiguous-KDoc-references and related issues

Jolanrensen · 2026-03-27T15:13:02Z

docs/StardustDocs/topics/columnArithmetics.md

+<!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.Modify-->
+
+Kotlin DataFrame provides operators for applying simple arithmetic, logical, string, and comparison operations
+to [`DataColumn`](DataColumn.md) and `ColumnReference` values. These operations include, for example, adding a value to a column,


"adding value to each cell in a column"?

docs/StardustDocs/topics/columnArithmetics.md

Jolanrensen · 2026-03-27T15:20:04Z

docs/StardustDocs/topics/columnArithmetics.md

+Converts each element of the column to a String and concatenates it with the value.
+
+```kotlin
+df.amount + "€"


I think only "€" + df.amount would make sense, but that might be something we cannot overload... right?

Jolanrensen · 2026-03-27T15:20:47Z

docs/StardustDocs/topics/columnArithmetics.md

+df.amount + "€"
+```
+
+`null` values are converted to the string `"null"`.


vote to change!!

Allex-Nik added 3 commits March 26, 2026 15:52

Add KDocs for DataColumnArithmetics.kt

19c37f6

Add tests for DataColumnArithmetics.kt

a4276ae

Add website docs for DataColumnArithmetics.kt

3005568

Allex-Nik commented Mar 26, 2026

View reviewed changes

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/api/DataColumnArithmetics.kt Show resolved Hide resolved

Allex-Nik commented Mar 26, 2026

View reviewed changes

core/src/test/kotlin/org/jetbrains/kotlinx/dataframe/api/DataColumnArithmetics.kt Show resolved Hide resolved

Allex-Nik commented Mar 26, 2026

View reviewed changes

docs/StardustDocs/topics/columnArithmetics.md Show resolved Hide resolved

Allex-Nik commented Mar 26, 2026

View reviewed changes

docs/StardustDocs/topics/columnArithmetics.md Show resolved Hide resolved

Allex-Nik commented Mar 26, 2026

View reviewed changes

docs/StardustDocs/topics/columnArithmetics.md Show resolved Hide resolved

Allex-Nik commented Mar 26, 2026

View reviewed changes

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/DataColumnArithmetics.kt Show resolved Hide resolved

Apply ktLintFormat to DataColumnArithmetics.kt and its tests. Rem…

e6cf6f1

…ove redundant comment.

Allex-Nik added documentation Improvements or additions to documentation (not KDocs) KDocs Improvements or additions to KDocs tests Something related to the JUnit tests, integration tests or testing infrastructure labels Mar 26, 2026

Allex-Nik commented Mar 26, 2026

View reviewed changes

Allex-Nik marked this pull request as ready for review March 26, 2026 15:47

Allex-Nik requested review from AndreiKingsley, Jolanrensen and zaleslaw March 26, 2026 15:47

Jolanrensen requested changes Mar 27, 2026

View reviewed changes


		## When useful

		In most transformations, these column operations are usually not the preferred approach in Kotlin DataFrame,

Conversation

Allex-Nik commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Allex-Nik Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jolanrensen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Allex-Nik commented Mar 26, 2026 •

edited

Loading

Allex-Nik Mar 26, 2026 •

edited

Loading