Convert KDocs #1134

AndrewKis · 2025-04-18T12:56:41Z

Closes #1019.
Closes #1150.

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

Jolanrensen · 2025-04-22T09:37:53Z

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

+ * Converts the values in the specified [columns\] to a target type
+ * or using a custom converter, keeping their original names and positions within the [DataFrame].
+ *
+ * This function does not immediately convert the columns but instead select columns to convert and


Jolanrensen · 2025-04-22T09:38:22Z

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

+ * returns a [Convert],
+ * which serves as an intermediate step.
+ * The [Convert] object allows you to specify how the selected
+ * columns will be converted using methods such as


If you say "such as" I expect a handful of examples, not all of them.

Jolanrensen · 2025-04-22T09:39:41Z

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

+ * [toURL][Convert.toURL],
+ * [toIFrame][Convert.toIFrame],
+ * [toImg][Convert.toImg], and [toDataFrames][Convert.toDataFrames]
+ * that return a new [DataFrame] with updated columns.


What would be nice is a small list of available conversions, like how it is on the website. People can then decide to check the grammar for all the specific overloads or simply use to<Type>()

Like here https://kotlin.github.io/dataframe/convert.html, just a list of supported types

Jolanrensen · 2025-04-22T09:44:48Z

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

+     * {@include [DslGrammarLink]}
+     * {@include [LineBreak]}
+     *
+     * **[`convert`][convert]**` { columnsSelector: `[`ColumnsSelector`][ColumnsSelector]` }`


Please check the cases where you write "backtick, space, something..., space, backtick". It's a rule in markdown that single spaces like this are trimmed away: https://github.github.com/gfm/#code-spans. It doesn't happen in the current markdown renderer in intellij, but I think this is just a matter of time. It can be solved by writing 2 spaces instead of one, like ` { columnsSelector: `. It's not required for cases like ` }`, because it doesn't have a space at the beginning ánd end.

Jolanrensen · 2025-04-22T10:06:22Z

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

@@ -147,9 +499,27 @@ public fun AnyCol.convertTo(newType: KType): AnyCol =
        else -> convertToTypeImpl(newType, null)
    }

+/**
+ * Converts values in this `String` column to the specified type [C].
+ *


hmm maybe we should link to parse? since this is just like parse but with a predefined return type for the values

Jolanrensen · 2025-04-22T10:11:03Z

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

 public fun <T : Any> DataColumn<T?>.convertToBoolean(): DataColumn<Boolean?> = convertTo()

 // region convert URL

+/**
+ * Converts values in the [URL] columns previously selected with [convert] to the [IFRAME],


check the others as well, like "the IMG" -> an IMG

Jolanrensen · 2025-04-22T10:15:36Z

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

 @JvmName("convertToURLFromStringNullable")
 public fun DataColumn<String?>.convertToURL(): DataColumn<URL?> = map { it?.let { URL(it) } }

+/**
+ * Converts values in the [String] columns previously selected with [convert] to the [URL],


no "the" before "URL", either "to a URL" or "to URL"

check the others as well :)

Jolanrensen · 2025-04-22T10:22:34Z

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

+ * where the first element is used as the column name, and the remaining elements as values.
+ *
+ * For more information: {@include [DocumentationUrls.Convert]}
+ *


this could use a visual example likely... But I'm not entirely sure how

something like:

containsColumns = false
[[a, b, c], [1, 2, 3], [4, 5, 6]] ->

containsColumns = true
[[a, 1, 4], [b, 2, 5], [c, 3, 6]] ->

a b c

1 2 3

4 5 6

makes it a bit easier to understand maybe

let's add an example to website doc

Jolanrensen · 2025-04-22T11:01:28Z

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/io/common.kt

+ *
+ * By default, treats the first inner list as a header (column names), and the remaining lists as rows.
+ * If [containsColumns] is `true`, interprets each inner list as a column,
+ * where the first element is used as the column name, and the remaining elements as values.


this could also do with a visual, but I'm not sure how

# Conflicts: # core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt

AndrewKis · 2025-04-28T10:01:54Z

@Jolanrensen regarding supported types reference - for now I've added a link to convert page on website, but when we will change this page, I'll add a section "Supported types" and will refer specifically on it (like `link`#supported_types)

AndrewKis · 2025-04-28T13:15:51Z

@Jolanrensen now it also closes #1150 - to was deleted in a favor to asColumn.

Jolanrensen · 2025-04-29T10:49:21Z

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


-public fun <T, C> Convert<T, C>.to(columnConverter: DataFrame<T>.(DataColumn<C>) -> AnyBaseCol): DataFrame<T> =


We should probably add a @Deprecated annotation here, it can be ERROR right away but we should steer people to convert.asColumn

Jolanrensen · 2025-04-29T11:03:36Z

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

+ * such as [toStr][Convert.toStr], [toDouble][Convert.toDouble], and many others.
+ *
+ * For the full list of supported types,
+ * refer to the [documentation website]({@include [DocumentationUrls.Url]}/convert.html).


please add this urls in the file instead of here in the doc. Makes it easier to refactor if all urls are in 1 place

in all places you use this btw

For the full list of supported types: {@include [DocumentationUrls.Convert]} should probably look fine

Jolanrensen · 2025-04-29T11:04:23Z

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

+     * `| `__`.`__[**`to`**][Convert.to]`(type: `[`KType`][KType]`)`
+     *
+     * {@include [Indent]}
+     * `| `__`.`__[**`to`**][Convert.to]`  { columnConverter: `[`DataFrame`](DataFrame)`.(`[`DataColumn`](DataColumn)`) -> `[`AnyBaseColumn`](AnyBaseColumn)`  }`


this should be removed now

Jolanrensen · 2025-04-29T11:05:50Z

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

+ *
+ * Use the following methods to perform the conversion:
+ * - [to(kType)][to]/[to`<Type`>()][to] – converts columns to a specific type.
+ * - [to { columnConverter }][to] - converts columns using column converter expression.


you removed this

Jolanrensen · 2025-04-29T11:09:25Z

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

+ * // Select columns with json values and convert it to decoded `String`.
+ * df.convert { valueJson }.with { Json.decode(it) }
+ * // Convert all `Int` columns to `Duration`, multiplying each value by the corresponding value from the "coeff" `Double` column before conversion
+ * df.convert { colsOf<Int>() }.with { baseValue -> (baseValue * coeff).toDuration(DurationUnit.MICROSECONDS) }


(baseValue * coeff).microseconds is also a valid Kotlinx datetime notation right? may look less daunting

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

Jolanrensen · 2025-04-29T11:14:57Z

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

@@ -55,7 +55,7 @@ public fun <T, C> ReplaceClause<T, C>.with(newColumns: List<AnyCol>): DataFrame<
 // TODO: Issue #418: breaks if running on ColumnGroup and its child

 /**
- * For an alternative supported in the compiler plugin use [Convert.asColumn]
+ * For an alternative supported in the compiler plugin use [Convert.to]


to doesn't exist anymore

# Conflicts: # core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/parse.kt

Jolanrensen · 2025-04-29T12:45:41Z

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

+     * * [LocalDateTime], [LocalDate], [LocalTime], [Instant] ( (kotlinx.datetime and [java.time]),
+     * * [URL], [IMG], [IFRAME].
+     */
+    interface SupportedTypes


AndreiKingsley added 3 commits April 18, 2025 16:51

convert kdocs

484cf4f

convert ktlint format

12915ce

convert fix

605d1ac

Jolanrensen self-requested a review April 22, 2025 11:01

Jolanrensen requested changes Apr 22, 2025

View reviewed changes

convert kdocs fixes

5b55f58

AndrewKis requested a review from Jolanrensen April 22, 2025 15:04

Merge branch 'master' into convert_kdocs

74b3102

# Conflicts: # core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/api/convert.kt

convert kdocs fixes, covnert to remove

bf44f75

AndreiKingsley added 3 commits April 28, 2025 17:19

convert kdocs small fix

6b9ba8b

convert kdocs replace with fix

7704027

convert kdocs examples fix

2efff53

Jolanrensen reviewed Apr 29, 2025

View reviewed changes

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

Jolanrensen reviewed Apr 29, 2025

View reviewed changes

AndreiKingsley added 3 commits April 29, 2025 16:02

convert kdocs fixes

099c8e2

Merge branch 'master' into convert_kdocs

2bcccac

# Conflicts: # core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/impl/api/parse.kt

parse merge fix

cf14aa5

AndrewKis requested a review from Jolanrensen April 29, 2025 12:05

AndreiKingsley added 2 commits April 29, 2025 16:08

convert fix example

c52d610

fix format

427b59b

Jolanrensen reviewed Apr 29, 2025

View reviewed changes

Jolanrensen approved these changes Apr 29, 2025

View reviewed changes

convert fix

d1ea42d

AndrewKis merged commit 2b1d7c3 into master Apr 29, 2025
4 of 6 checks passed

AndrewKis deleted the convert_kdocs branch April 29, 2025 14:21


		public fun <T, C> Convert<T, C>.to(columnConverter: DataFrame<T>.(DataColumn<C>) -> AnyBaseCol): DataFrame<T> =

Convert KDocs #1134

Convert KDocs #1134

Uh oh!

Conversation

AndrewKis commented Apr 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

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!

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!

AndrewKis commented Apr 28, 2025

Uh oh!

AndrewKis commented Apr 28, 2025

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!

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!

Uh oh!

Uh oh!

AndrewKis commented Apr 18, 2025 •

edited

Loading