# convert

> For the complete documentation index, see [llms.txt](https://kotlin.github.io/dataframe/llms.txt).

Returns [DataFrame](dataframe.html) with changed values in some columns. Allows changing column types.

API reference: [convert](https://kotlin.github.io/dataframe/api-docs/core/org.jetbrains.kotlinx.dataframe.api/convert.html)

```TEXT
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: [Update / convert values](updateconvert.html), [convertTo](convertto.html)

> **Tip:**
> This page is for the `DataFrame<*>.convert {}` operation and the `DataColumn<*>.convertTo<ValueType>()` family of functions.
>
>
>
> If you were looking for [DataFrame&lt;*&gt;.convertTo&lt;Schema&gt;()](convertto.html), see [convertTo](convertto.html).

See [column selectors](columnselectors.html) for how to select the columns for this operation and [row expressions](datarow.html#row-expressions) for how to provide new values.

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

[Embedded content](resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.convert.html)

```KOTLIN
df.weight.convertTo<Float?>()
df.age.convertToDouble()
```

ColumnGroup can be converted using DataFrame API, for example:

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

[Embedded content](resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.convertAsFrame.html)

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.

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

[Embedded content](resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.convertAsColumn.html)

`df.convert {}.to<>()` and `col.convertTo<>()` support automatic type conversions between the following types:

* `String`, `Char` (uses [parse](parse.html) to convert from `String` to other types)

* `Boolean`

* `Byte`

* `Short`

* `Int` (and `Char`)

* `Long`

* `Float`

* `Double` (See [parsing doubles](parse.html#parsing-doubles) for `String` to `Double` conversion)

* `BigDecimal` (java.math)

* `BigInteger` (java.math)

* `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)

* `Duration` (kotlin.time, and java.time, to/from `Long`, `Int`, `String`, and each other)

* `DateTimeComponents` (kotlinx.datetime, to any other kotlinx-datetime/java.time type, `Instant`, or `Long`)

* `URL` (java.net, to [IMG](tohtml.html#display-images) or [IFRAME](tohtml.html#embed-pages))

* `enum` classes (by name)

> **Warning:**
> 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()](parse.html) instead, or, in either case, use `String` as intermediary type.

If you miss a type, or conversion, please let us know by creating a [GitHub issue](https://github.com/Kotlin/dataframe/issues/new).

```KOTLIN
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()
```

[Embedded content](resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.convertTo.html)

Notice the `toFloat()` call in the example above. This is a shortcut for `to<Float>()`. DataFrame has a handful of shortcuts like these

ParserOptions:

It is allowed to pass [ParserOptions](parse.html#parser-options) to conversion functions. This will only be used for `String`/`Char` conversions. See [parse](parse.html) for more details.

For example:

```KOTLIN
// String -> Double? conversion
stringDf.convert { value }.to<Double?>(
    parserOptions = ParserOptions(locale = Locale.GERMAN, nullStrings = setOf("-")),
)

// String -> LocalDate conversion
stringDf.convert { date }.to<LocalDate>(
    parserOptions = ParserOptions(
        dateTime = DateTimeParserOptions.Kotlin.withFormat(LocalDate.Formats.ISO),
    ),
)
// shortcut for String -> LocalDate conversion
stringDf.convert { date }.toLocalDate(LocalDate.Formats.ISO)
```

[Embedded content](resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.convertStringTo.html)

Automatic conversion from `String` to [enum classes](https://kotlinlang.org/docs/enum-classes.html#enum-classes.md) is also supported:

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

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

[Embedded content](resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.convertToEnum.html)

And finally, [Value classes](https://kotlinlang.org/docs/inline-classes.html) can be used with `convert` too. Both as conversion source and target:

```KOTLIN
@JvmInline 
value class IntClass(val value: Int)
```

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

[Embedded content](resources/org.jetbrains.kotlinx.dataframe.samples.api.Modify.convertToValueClass.html)