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

Returns the total number of bytes x in human-readable format. 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)

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, the function returns the original value x.

convert

convert(number x, string s) string

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"))