# Math (/docs/es_extended/shared/math)

`ESX.Math` holds a few number and string helpers that ESX uses for money, plates and headings. They work on client and server. In 1.16 they are implemented in [esx_lib](/docs/core/esx_lib) (`xLib.math`) and mapped onto `ESX.Math`.

## Overview [#overview]

| | |
|---|---|
| Resource | `es_extended` (implemented in `esx_lib`) |
| Side | Shared |
| Mapping | `es_extended/shared/compat.lua` |

## Functions [#functions]

### ESX.Math.Round [#esxmathround]

```lua
ESX.Math.Round(value, numDecimalPlaces)
```

Rounds half up (`2.5` becomes `3`).

| Name | Type | Description |
|---|---|---|
| `value` | `number` | Number to round. Must be a number, strings raise an error. |
| `numDecimalPlaces` | `number?` | Decimal places. Default `0`. |

**Returns:** `number`

```lua
print(ESX.Math.Round(5.444)) -- 5
print(ESX.Math.Round(5.456, 1)) -- 5.5
```

`ESX.Round(value, numDecimalPlaces)` is the same function.

### ESX.Math.GroupDigits [#esxmathgroupdigits]

```lua
ESX.Math.GroupDigits(value)
```

Adds a thousands separator. The separator comes from the `locale_digit_grouping_symbol` entry of the active ESX locale.

| Name | Type | Description |
|---|---|---|
| `value` | `number \| string` | Number to format. |

**Returns:** `string`

```lua
local bank = ESX.GetAccount('bank')
ESX.ShowNotification(('Balance: $%s'):format(ESX.Math.GroupDigits(bank.money)))
-- Balance: $1,250,000
```

### ESX.Math.Trim [#esxmathtrim]

```lua
ESX.Math.Trim(value)
```

Removes whitespace at the beginning and end. Spaces in the middle stay. Mostly used for `GetVehicleNumberPlateText`, which pads plates to 8 characters.

| Name | Type | Description |
|---|---|---|
| `value` | `string \| number` | Value to trim. Numbers are converted with `tostring`. |

**Returns:** `string`

```lua
local plate = GetVehicleNumberPlateText(vehicle) -- " ESX 12 "
print(ESX.Math.Trim(plate)) -- "ESX 12"
```

### ESX.Math.Random [#esxmathrandom]

```lua
ESX.Math.Random(minRange, maxRange)
```

| Name | Type | Description |
|---|---|---|
| `minRange` | `number?` | Lower bound. Default `1`. |
| `maxRange` | `number?` | Upper bound. Default `10`. |

**Returns:** `number`, a random integer from `math.random(minRange, maxRange)`.

```lua
local payout = ESX.Math.Random(150, 300)
```

### ESX.Math.GetHeadingFromCoords [#esxmathgetheadingfromcoords]

```lua
ESX.Math.GetHeadingFromCoords(origin, target)
```

Returns the GTA heading (0-360 degrees) that points from `origin` to `target` on the XY plane.

| Name | Type | Description |
|---|---|---|
| `origin` | `table` | Plain table with `x` and `y`. |
| `target` | `table` | Plain table with `x` and `y`. |

**Returns:** `number`

<Callout type="warn">
Both arguments are type-checked as `table`. Passing a `vector3` raises an error. Convert vectors first, for example `{ x = coords.x, y = coords.y }`.
</Callout>

```lua
local from = GetEntityCoords(ESX.PlayerData.ped)
local to = vector3(441.0, -981.0, 30.7)

local heading = ESX.Math.GetHeadingFromCoords({ x = from.x, y = from.y }, { x = to.x, y = to.y })
SetEntityHeading(ESX.PlayerData.ped, heading)
```

<Callout type="info" title="More in esx_lib">
`xLib.math` has more helpers that are not mapped to `ESX.Math`, for example `clamp`, `lerp`, `remap`, `tryNumber`, `toInteger`, `hexToRGBA` and `toHex`. Load `@esx_lib/imports.lua` to use them.
</Callout>

## Related [#related]

- [Shared functions](/docs/es_extended/shared)
- [Table functions](/docs/es_extended/shared/table)
- [Money and accounts guide](/docs/guides/money-and-accounts)
- [esx_lib](/docs/core/esx_lib)