df-research/dataframe/docs/StardustDocs/topics/convert.md

Returns DataFrame with changed values in some columns. Allows changing column types.

convert { columnsSelector }
    .with { rowExpression } | .asFrame { frameExpression } | .perRowCol { rowColExpression } | to<Type>() | to { colExpression }

rowExpression = DataRow.(OldValue) -> NewValue
rowColExpression = (DataRow, DataColumn) -> NewValue
colExpression = DataFrame.(DataColumn) -> DataColumn
frameExpression: DataFrame.(DataFrame) -> DataFrame

Related operations:

See column selectors for how to select the columns for this operation and row expressions for how to provide new values.

df.convert { age }.with { it.toDouble() }
df.convert { colsAtAnyDepth().colsOf<String>() }.with { it.toCharArray().toList() }

ColumnGroup can be converted using DataFrame API, for example:

df.convert { name }.asFrame { it.add("fullName") { "$firstName $lastName" } }

Similar to replace with operation, columns can be converted in a compiler plugin-friendly fashion whenever you need to perform an operation on the entire column without changing its name. For example, parallel reading.

df.convert { name }.asColumn { col ->
    col.toList().parallelStream().map { it.toString() }.collect(Collectors.toList()).toColumn()
}

convert {}.to<>() supports automatic type conversions between the following types:

• String, Char (uses parse to convert from String to other types)
• Boolean
• Byte
• Short
• Int (and Char)
• Long
• Float
• Double (See parsing doubles for String to Double conversion)
• BigDecimal
• BigInteger
• LocalDateTime (kotlinx.datetime and java.time)
• LocalDate (kotlinx.datetime and java.time)
• LocalTime (kotlinx.datetime and java.time)
• Instant (kotlinx.datetime, kotlin.time, and java.time)
• enum classes (by name)

Note that converting between Char and Int is done by UTF-16 character code. This means the Char '1' becomes the Int 49. To convert Char -> Int the way it is written, use parse() instead, or, in either case, use String as intermediary type. {style="warning"}

If you want to convert Char '1' to the Int 1, use parse() instead, or use String as intermediate type.

df.convert { age }.to<Double>()
df.convert { colsOf<Number>() }.to<String>()
df.convert { name.firstName and name.lastName }.asColumn { col -> col.map { it.length } }
df.convert { weight }.toFloat()

Automatic conversion from String to enum classes is also supported:

enum class Direction { NORTH, SOUTH, WEST, EAST }

dataFrameOf("direction")("NORTH", "WEST")
    .convert("direction").to<Direction>()

And finally, Value classes can be used with convert too. Both as conversion source and target:

@JvmInline 
value class IntClass(val value: Int)

dataFrameOf("value")("1", "2") // note that values are strings; conversion is done automatically
    .convert("value").to<IntClass>()