# # Formatting Functions

## # Overview

These functions format numbers, dates, collections, and maps to strings according to the specified format.

## # Reference

Number formatting functions:

Date formatting functions:

## #`formatNumber`

``````  formatNumber(double x, string s) string
``````

Formats number `x` with the specified `DecimalFormat` pattern `s` using the server locale (US/US).

Example:

``````    // returns 3.14
formatNumber(3.14159, '#.##')
``````

## #`formatBytes`

``````  formatBytes(number x, boolean si) string
``````

The function returns the total number of bytes `x` in a human-readable format. The function identifies the largest possible unit (from Byte to Exabyte) such that the number `x` is equal to or exceeds 1 such unit. Units are decimal-based (1000) if the `si` parameter is set to `true`, and binary (1024) otherwise.

For example, if the unit is `1000` (`si` set to `true`):

`````` 999 -> 999.0 B  (unit is byte)
1000 ->   1.0 kB (unit is kilobyte)
``````

The formatted number always contains one fractional digit.

Examples:

``````                        si=false    si=true
0:        0 B        0 B
27:       27 B       27 B
999:      999 B      999 B
1000:     1.0 kB     1000 B
1023:     1.0 kB     1023 B
1024:     1.0 kB    1.0 KiB
1728:     1.7 kB    1.7 KiB
110592:   110.6 kB  108.0 KiB
7077888:     7.1 MB    6.8 MiB
452984832:   453.0 MB  432.0 MiB
28991029248:    29.0 GB   27.0 GiB
1855425871872:     1.9 TB    1.7 TiB
``````

If the `x` argument is a string or an object that cannot be parsed into a number, its value is returned 'as is'.

## #`convert`

``````  convert(number x, string s) string
``````

The function divides the number `x` by the specified measurement unit `s` and formats the returned string with one fractional digit.

The unit is case-insensitive and can be one of the following:

• `K`, `Kb` (1000)
• `Ki`, `KiB` (1024)
• `M`, `Mb` (1000^2)
• `Mi`, `MiB` (1024^2)
• `G`, `Gb` (1000^3)
• `Gi`, `GiB` (1024^3)
• `T`, `Tb` (1000^4)
• `Ti`, `TiB` (1024^4)
• `P`, `Pb` (1000^5)
• `Pi`, `PiB` (1024^5)
• `E`, `Eb` (1000^6)
• `Ei`, `EiB` (1024^6)

Examples:

``````    // Returns 20.0
// same as formatNumber(20480/1024, '#.#')
convert(20480, 'KiB') // 20.0
convert(1000 * 1000, 'M') // 1.0
``````

## #`date_format`

``````  date_format(long t, string p, string z) string
``````

Converts timestamp `t` to a string according to the specified date pattern `p` and the time zone `z`.

The input timestamp is specified as Unix time in milliseconds.

Related date parsing function: `date_parse`.

Example:

``````  /* Return formatted time string  "2018-01-09 15:23:40:000 Europe/Berlin" */
date_format(milliseconds('2018-01-09T14:23:40Z'), "yyyy-MM-dd HH:mm:ss:SSS ZZZ", "Europe/Berlin")
``````

## #`formatInterval`

``````  formatInterval(long interval) string
``````

Converts interval in Unix time measured in milliseconds to a formatted interval consisting of non-zero years, days, hours, minutes, and seconds.

Examples:

``````  /* Returns formatted interval: 2y 139d 16h 47m 15s */
formatInterval(75228435000L)
``````
``````  formatInterval(elapsedTime(milliseconds(tags.last_updated)))
``````

## #`formatIntervalShort`

``````  formatIntervalShort(long interval) string
``````

Converts interval measured in milliseconds to a formatted interval consisting of up to the two highest subsequent non-zero time units, where the unit comprises years, days, hours, minutes, and seconds.

Examples:

``````  /* Returns formatted interval: 2y 139d */
formatIntervalShort(75228435000L)
``````
``````  /* Assuming current time of 2017-08-15T00:01:30Z, returns a short interval of elapsed time: 1m 30s */
formatIntervalShort(elapsedTime("2017-08-15T00:00:00Z"))
``````