# Column arithmetics

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

Kotlin DataFrame provides operators for applying simple arithmetic, logical, string, and comparison operations to [DataColumn](datacolumn.html) and `ColumnReference` values. These operations include, for example, adding a value to each cell in a column, multiplying a column by a value, and comparing elements in a column with a value.

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

## When useful

In most transformations, these column operations are usually not the preferred approach in Kotlin DataFrame, because the library provides row-based APIs such as [add](add.html), [update](update.html), and [map](map.html), which are usually recommended.

Also, the [expr](columnselectors.html#expr-column-expression) function is particularly useful in this context, as it allows you to write row expressions inside the [Columns Selection DSL](columnselectors.html). In other words, [expr](columnselectors.html#expr-column-expression) works as an adapter between a column selector and a row expression.

For example,

```KOTLIN
orders.groupBy { status + " orders" }
```

is equivalent to

```KOTLIN
orders.groupBy { expr("status") { status + " orders" } }
```

but in the first case, `status` is used as a [DataColumn](datacolumn.html) of String values, and in the second case, `status` is treated as a String.

However, column arithmetics might still be useful in some cases. For example, when building temporary plotting expressions. If distance is stored in meters, but you need to [plot](https://kotlin.github.io/kandy/welcome.html) it in kilometers, you can convert it directly in the plotting expression without having to create a temporary column in your dataframe just for plotting.

```KOTLIN
df.plot {
    line {
        x(day)
        y((distanceMeters / 1000.0) named "distanceKm")
    }
}
```

## Not

Negates Boolean values in a [DataColumn](datacolumn.html) (`ColumnReference`). Returns a result of the same type.

```KOTLIN
df.select { !isHappy }
// or
!df.isHappy
```

Nullable Boolean columns preserve `null` values.

## Plus

Adding a value to a column and concatenation of a column with a `String` are supported. In all cases, a [DataColumn](datacolumn.html) (`ColumnReference`) is returned.

### Column plus value or value plus column

Adds the value to each element of the column. The value can appear on either side of the operator.

```KOTLIN
transactions.amount + 10
5.0 + transactions.amount
```

`null` values are not changed by this operation.

### Column plus String

Converts each element of the column to a String and concatenates it with the value.

```KOTLIN
weather.select { temperature + " °C" }
// or
weather.temperature + " °C"
```

`null` values are converted to the string `"null"`.

## Minus

### Column minus value

Subtracts the value from each element of the column.

```KOTLIN
transactions.amount - 10.0
```

`null` values are not changed by this operation.

### Value minus column

Subtracts each element of the column from the value and returns a [DataColumn](datacolumn.html) (`ColumnReference`) with the results of the subtractions.

```KOTLIN
100 - transactions.amount
```

`null` values from the original column remain `null` values in the resulting column.

## Unary minus

Flips the sign of each element in the column.

```KOTLIN
-transactions.amount
```

`null` values are not changed by this operation.

## Times

Multiplies each element of the column by the value.

```KOTLIN
routes.distanceKm * 1000.0
products.price * BigDecimal("1.20")
```

`null` values are not changed by this operation.

## Div

Division by zero follows Kotlin semantics of the underlying type.

### Divide column by value

Divides each element of the column by the value.

```KOTLIN
products.weightGrams / 1000.0
```

### Divide value by column

Divides the value by each element of the column and returns a [DataColumn](datacolumn.html) (`ColumnReference`) with the results of the divisions.

```KOTLIN
40 / tasks.hoursPerTask
```

If an element of the column is `null`, the corresponding value in the resulting column is also `null`.

## Compare

`eq`, `neq`, `gt`, and `lt` are available for [DataColumn](datacolumn.html). Each of them returns a [DataColumn](datacolumn.html) of `Boolean` values.

### eq

Compares each element of a [DataColumn](datacolumn.html) with the value for equality using the `==` operator.

```KOTLIN
orders.status eq "canceled"
```

### neq

Compares each element of a [DataColumn](datacolumn.html) with the value for inequality using the `!=` operator.

```KOTLIN
orders.status neq "completed"
```

### gt

Compares each element of a [DataColumn](datacolumn.html) with the value using the `>` operator.

```KOTLIN
orders.cost gt 1000.0
```

### lt

Compares each element of a [DataColumn](datacolumn.html) with the value using the `<` operator.

```KOTLIN
orders.cost lt 20.0
```