v2.1

Global

This is the global namespace. Functions are available without having to prepend them with a namespace identifier.

Static properties

Image any

HTML Image.

Methods

NUM

NUM(number: number, numDecimals?: number)

Returns a formatted number as a string. If a culture is specified when executing a ruleset, the formatting of that culture will be used.

Parameters

number number

A numeric value.

numDecimals number

(optional) The number of decimals. Defaults to 0.

Return type

string

Examples

NUM(3)          // => "3"
NUM(3.99)       // => "3.99"
NUM(3.99)       // => "3,99" (when {culture:'nl'} is specified in execution options)
NUM(3.99, 1)    // => "4.0"
NUM(3.99, 0)    // => "4"

CUR

CUR(number: number, numDecimals?: number)

Returns a formatted currency number as a string. If a culture is specified when executing a ruleset, the formatting of that culture will be used.

Parameters

number number

A numeric value.

numDecimals number

(optional) The number of decimals. Defaults to 2.

Return type

string

Examples

CUR(3)          // => "3.00"
CUR(3.99)       // => "3.99" (default)
CUR(3.99)       // => "£3.99"  (when {culture:'en-GB'} is specified in execution options)
CUR(3.99)       // => "$3.99"  (when {culture:'en-US'} is specified in execution options)
CUR(3.99)       // => "€ 3,99" (when {culture:'nl'} is specified in execution options)
CUR(3.99, 1)    // => "4.0"
CUR(3.99, 0)    // => "4"

CURN

CURN(number: number, numDecimals?: number)

Returns a formatted currency number as a string without the currency symbol. If a culture is specified when executing a ruleset, the formatting of that culture will be used.

Parameters

number number

A numeric value.

numDecimals number

(optional) The number of decimals. Defaults to 2.

Return type

string

Examples

CURN(3)          // => "3.00"
CURN(3.99)       // => "3.99" (default)
CURN(3.99)       // => "3,99" (when {culture:'nl'} is specified in execution options)
CURN(3.99, 1)    // => "4.0"
CURN(3.99, 0)    // => "4

DATESTR

DATESTR(date: Date | string, options?: Intl.DateTimeFormatOptions)

Returns a formatted date as a string. If a culture is specified when executing a ruleset, the formatting of that culture will be used. See Intl.DateTimeFormat for more information on the formatting options.

Parameters

date Date | string

A JavaScript Date object or an ISO 8601 formatted string.

options Intl.DateTimeFormatOptions

(optional) The formatting options.

Return type

string

Examples

DATESTR(TODAY())       // => "30-1-2024" (when {culture:'nl'} is specified in execution options)
DATESTR(TODAY())       // => "1/30/2024" (when {culture:'en'} is specified in execution options)

// Custom formatting:
DATESTR(TODAY(), {year:'numeric', month:'long', day:'numeric'})
// => "30 januari 2024" (when {culture:'nl'} is specified in execution options)

DATESTR(TODAY(), {year:'numeric', month:'long', day:'numeric'})
// => "January 30, 2024" (when {culture:'en'} is specified in execution options)

AGE

AGE(birthDate: Date | string)

Returns the amount of full years passed since a given JavaScript Date Object.

Parameters

birthDate Date | string

A JavaScript Date object or an ISO 8601 formatted string.

Return type

number

Examples

AGE(new Date('1980-01-01'))    // => 44
AGE('1986-01-01')              // => 38

DATE

DATE(year: number | string | Date, month?: number, day?: number)

Creates a JavaScript Date Object. Is more reliable than using 'new Date()' to create a date, as DATE() ignores timezones.

Parameters

year number | string | Date

The year or a YYYY-MM-DD string.

month number

(optional) The month. 1-based (1=January, 2=February, etc.).

day number

(optional) The day.

Return type

Date

Examples

DATE(2000, 1, 1)               // => (Date) 2000-01-01T00:00:00.000Z - Note the month is 1-based (1=January)
DATE('2000-01-01')             // => (Date) 2000-01-01T00:00:00.000Z
DATE('2000-01-01T00:00')       // => (Date) 2000-01-01T00:00:00.000Z

For comparison:
new Date(2000, 1, 1)           // => (Date) 2000-01-31T23:00:00.000Z - Note the month is 0-based (0=January)
new Date('2000-01-01')         // => (Date) 2000-01-01T00:00:00.000Z
new Date('2000-01-01T00:00')   // => (Date) 1999-12-31T23:00:00.000Z

TODAY

TODAY()

Returns the current date as a JavaScript Date Object at the start of the day (midnight, 00:00).

Parameters

Return type

Date

Examples

TODAY()        // => (Date) 2024-01-30T00:00:00.000Z

NOW

NOW()

Returns the current date and time as a JavaScript Date Object accurate to the millisecond.

Parameters

Return type

Date

Examples

NOW()          // => (Date) 2024-01-30T09:59:01.434Z

DAY

DAY(date: Date | string)

Returns the day of a given JavaScript Date Object.

Parameters

date Date | string

A JavaScript Date object or an ISO 8601 formatted string.

Return type

number

Examples

DAY(TODAY())       // => 30

WEEKDAY

WEEKDAY(date: Date | string)

Returns the day of the week of a given JavaScript Date Object. Differs from JS Date's getDay() method, in that it is 1-based. (e.g. Sunday = 1, instead of 0. Saturday = 7)

Parameters

date Date | string

A JavaScript Date object or an ISO 8601 formatted string.

Return type

number

Examples

WEEKDAY(TODAY())       // => 3 (Tuesday = 3)

MONTH

MONTH(date: Date | string)

Returns the month of a given JavaScript Date Object. Differs from JS Date's getMonth() method, in that it is 1-based. (e.g. January = 1, instead of 0.)

Parameters

date Date | string

A JavaScript Date object or an ISO 8601 formatted string.

Return type

number

Examples

MONTH(TODAY())     // => 1

YEAR

YEAR(date: Date | string)

Returns the year of a given JavaScript Date Object.

Parameters

date Date | string

A JavaScript Date object or an ISO 8601 formatted string.

Return type

number

Examples

YEAR(TODAY())      // => 2024

YEARMONTH

YEARMONTH(date: Date | string)

Returns the year and month of a given JavaScript Date Object.

Parameters

date Date | string

A JavaScript Date object or an ISO 8601 formatted string.

Return type

string

Examples

YEARMONTH(TODAY())     // => "2024-01"

YEARMONTHDAY

YEARMONTHDAY(date: Date | string)

Returns the year, month and day of a given JavaScript Date Object. Note: this is similar to calling .toShortDateString() on a Date. See also:

  • Date.toShortDateString

Parameters

date Date | string

A JavaScript Date object or an ISO 8601 formatted string.

Return type

string

Examples

YEARMONTHDAY(TODAY())          // => "2024-01-30"
TODAY().toShortDateString()    // => "2024-01-30"

MONTHDAY

MONTHDAY(date: Date | string)

Returns the month and day of a given JavaScript Date Object.

Parameters

date Date | string

A JavaScript Date object or an ISO 8601 formatted string.

Return type

string

Examples

MONTHDAY(TODAY())          // => "01-30"

DAYDIFF

DAYDIFF(dateFrom: Date | string, dateTo: Date | string)

Returns the amount of full days between two dates. See also:

  • Date.diff

Parameters

dateFrom Date | string

A JavaScript Date object or an ISO 8601 formatted string.

dateTo Date | string

A JavaScript Date object or an ISO 8601 formatted string.

Return type

number

Examples

DAYDIFF(new Date('2010-01-01'), new Date('2011-01-01'))                    // => 365 
DAYDIFF(new Date('2000-01-01T12:00:00'), new Date('2000-01-02T11:59:59'))  // => 0 
DAYDIFF(new Date('2000-01-01T12:00:00'), new Date('2000-01-02T12:00:00'))  // => 1

SAMEDAY

SAMEDAY(dateA: Date | string, dateB: Date | string)

Returns whether two dates are on the same day. See also:

  • Date.isSameDay

Parameters

dateA Date | string

A JavaScript Date object or an ISO 8601 formatted string.

dateB Date | string

A JavaScript Date object or an ISO 8601 formatted string.

Return type

boolean

Examples

SAMEDAY(new Date('2011-01-01'), new Date('2011-01-01'))                    // => true 
SAMEDAY(new Date('2000-01-01T00:00:00'), new Date('2000-01-01T23:59:59'))  // => true 
SAMEDAY(new Date('2000-01-01'), new Date('2000-01-02'))                    // => false

MONTHDIFF

MONTHDIFF(dateFrom: Date | string, dateTo: Date | string)

Returns the amount of full months between two dates. See also:

  • Date.diff

Parameters

dateFrom Date | string

A JavaScript Date object or an ISO 8601 formatted string.

dateTo Date | string

A JavaScript Date object or an ISO 8601 formatted string.

Return type

number

Examples

MONTHDIFF(new Date('1980-01-01'), new Date('2000-01-01'))          // => 240 
MONTHDIFF(new Date('1980-01-01'), new Date('2000-01-15'))          // => 240 
MONTHDIFF(new Date('1980-01-15'), new Date('2000-01-01'))          // => 239 
MONTHDIFF('2020-04-16T15:37:25.579Z', '2023-06-01T15:37:25.578Z')  // => 37

YEARDIFF

YEARDIFF(dateFrom: Date | string, dateTo: Date | string)

Returns the amount of full years between two dates. See also:

  • Date.diff

Parameters

dateFrom Date | string

A JavaScript Date object or an ISO 8601 formatted string.

dateTo Date | string

A JavaScript Date object or an ISO 8601 formatted string.

Return type

number

Examples

YEARDIFF(new Date('1980-01-01'), new Date('2000-01-01'))      // => 20 
YEARDIFF(new Date('1980-01-02'), new Date('2000-01-01'))      // => 19

DATEDIFF

DATEDIFF(dateFrom: Date | string, dateTo: Date | string, absolute?: boolean)

Returns an object containing the difference between two dates in various units. The output is similar to Date.diff(). See also:

  • Date.diff

Parameters

dateFrom Date | string

A JavaScript Date object or an ISO 8601 formatted string.

dateTo Date | string

A JavaScript Date object or an ISO 8601 formatted string.

absolute boolean

(optional) If true, will return a positive value for the difference.

Return type

DateDiffResult

Examples

DATEDIFF(new Date('1980-01-01'), new Date('2000-01-01'))      // => 
        {
            totalMilliseconds: 631152000000,
            totalSeconds: 631152000,
            totalMinutes: 10519200,
            totalHours: 175320,
            totalDays: 7305,
            totalMonths: 240,                                
            totalYears: 20,
            totalFullSeconds: 631152000,
            totalFullMinutes: 10519200,
            totalFullHours: 175320,
            totalFullDays: 7305,
            totalFullMonths: 240,                                
            totalFullYears: 20
        }

ABS

ABS(x: number)

Shorthand for Math.abs()

Parameters

x number

A number.

Return type

number

Examples

ABS(1)     // => 1
ABS(-1)    // => 1

CEIL

CEIL(x: number, numDecimals?: number)

Returns the smallest integer greater than or equal to a given number.

Parameters

x number

A number.

numDecimals number

(optional) Number of decimals. Can be negative to round down to number of integers.

Return type

number

Examples

CEIL(1)            // => 1
CEIL(1.1)          // => 2
CEIL(1.501, 1)     // => 1.6

// A negative numDecimals will round down to number of integers:
CEIL(1948, -1)     // => 1950
CEIL(1948, -2)     // => 2000
CEIL(1948, -3)     // => 2000

FLOOR

FLOOR(x: number, numDecimals?: number)

Returns the largest integer less than or equal to a given number.

Parameters

x number

A number.

numDecimals number

(optional) Number of decimals. Can be negative to round down to number of integers.

Return type

number

Examples

FLOOR(1)            // => 1
FLOOR(1.9)          // => 1
FLOOR(1.501, 1)     // => 1.5

// A negative numDecimals will round down to number of integers:
FLOOR(1948, -1)     // => 1940
FLOOR(1948, -2)     // => 1900
FLOOR(1948, -3)     // => 1000

ROUND

ROUND(x: number, numDecimals?: number)

Returns the value of a number rounded to the nearest integer. Using the 'Half Away From Zero' rounding mode.

Parameters

x number

A number.

numDecimals number

(optional) Number of decimals. Can be negative to round down to number of integers.

Return type

number

Examples

ROUND(1.4)          // => 1
ROUND(1.5)          // => 2
ROUND(1.501, 1)     // => 1.5

// A negative numDecimals will round down to number of integers:
ROUND(1948, -1)     // => 1950
ROUND(1948, -2)     // => 1900
ROUND(1948, -3)     // => 2000

LOG

LOG(x: number)

Shorthand for Math.log() - returns the natural logarithm (base e) of the given number.

Parameters

x number

A number.

Return type

number

Examples

LOG(8) / LOG(2)    // => 3  (for 2 x 2 x 2 = 8)
LOG(625) / LOG(5)  // => 4  (for 5 x 5 x 5 x 5 = 625)

EXP

EXP(x: number)

Shorthand for Math.exp() - returns ex, where x is the argument, and e is Euler's number (also known as Napier's constant), the base of the natural logarithms.

Parameters

x number

A number.

Return type

number

Examples

EXP(0)     // => 1
EXP(1)     // => 2.718281828459045
EXP(-1)    // => 0.36787944117144233
EXP(2)     // => 7.38905609893065

POW

POW(base: number, exponent: number)

Shorthand for Math.pow() - returns the base to the exponent power. Note: for performance reasons it is better to use the ** operator instead of POW or Math.pow.

Parameters

base number

The base number.

exponent number

The exponent used to raise the base.

Return type

number

Examples

POW(2, 3)      // => 8
POW(4, 0.5)    // => 2
POW(7, -2)     // => 0.020408163265306124 (1/49)

SQRT

SQRT(x: number)

Shorthand for Math.sqrt() - returns the square root of a number.

Parameters

x number

A number.

Return type

number

Examples

SQRT(9)      // => 3
SQRT(2)      // => 1.4142135623730951
SQRT(1)      // => 1

MIN

MIN(...numbers: number[])

Returns the lowest-valued number passed into it.

Parameters

...numbers number[]

Numbers.

Return type

number

Examples

MIN(2, 3)         // => 2
MIN(-2, 3, -1)    // => -2
MIN([-2, 3, -1])  // You can pass in an array of numbers, too => -2

MAX

MAX(...numbers: number[])

Returns the highest-valued number passed into it.

Parameters

...numbers number[]

Numbers.

Return type

number

Examples

MAX(2, 3)          // => 3
MAX(-2, -3, -1)    // => -1
MAX([-2, -3, -1])  // You can pass in an array, too => -1

CLAMP

CLAMP(input: number, min: number, max: number)

Combines the logic of MIN and MAX - Clamps the input number between the min and max values.

Parameters

input number

The input value to be clamped.

min number

Lowest possible value to clamp the input to.

max number

Highest possible value to clamp the input to.

Return type

number

Examples

CLAMP(5, 0, 10)    // => 5 // 5 is between 0 and 10, so value is not clamped
CLAMP(-1, 0, 10)   // => 0 // -1 is lower than 0, so value is clamped to 0
CLAMP(11, 0, 10)   // => 10 // 11 is higher than 10, so value is clamped to 10

MAP

MAP(value: number, startA: number, endA: number, startB: number, endB: number, clamp?: boolean)

Maps a number from one range to another

Parameters

value number

The input value to be mapped.

startA number

Current value range start.

endA number

Current value range end.

startB number

Target range start.

endB number

Target range end.

clamp boolean

(optional) Clamp the mapped value between target range. Defaults to false.

Return type

number

Examples

MAP(50, 0, 100, 0, 1)          // => 0.5   // Map value 50 in range (0-100) to range (0-1)
MAP(50, 0, 100, -100, 100)     // => 0     // Map value 50 in range (0-100) to range (-100-100)
MAP(50, 0, 100, 100, 200)      // => 150   // Map value 50 in range (0-100) to range (100-200)
MAP(101, 0, 100, 0, 1)         // => 1.01  // Map value 101 in range (0-100) to range (0-1)
MAP(101, 0, 100, 0, 1, true)   // => 1     // Map and clamp value 101 in range (0-100) to range (0-1)

SOLVE

SOLVE(fn: (x: number) => number, target: number, start?: number, step?: number, accuracy?: number, maxIterations?: number)

Attempt to find the input value that produces a given target result for a given function.

Parameters

fn (x: number) => number

The function to find the input for. Must have exactly one parameter (number) and must return a number.

target number

The target result value.

start number

(optional) The input to start from. Defaults to 0.

step number

(optional) The initial step size. Defaults to 100.

accuracy number

(optional) The desired accuracy. If 0 is specified, the result must match exactly. Defaults to 1e-15.

maxIterations number

(optional) The maximum number of attempts to solve for the input. Defaults to 100.

Return type

number

Examples

// Solves x + 1 = 5:
SOLVE(x => x + 1, 5) // => 4

// Solves SQRT(x) = 5:
SOLVE(x => SQRT(x), 5) // => 25

// Solves x for result 9 (x * x = 9):
SOLVE(x => x * x, 9) // => 3

// Solves x for result 9 (x * x = 9) with all parameters:
SOLVE(
    x => x * x,       // Function
    9,                // Goal
    0,                // Start
    10,               // Initial step size
    0,                // Accuracy (0 = exact)
    10)               // Max attempts

RANDOM

RANDOM(start?: number, end?: number)

Returns a floating-point, pseudo-random number in the range 0-1 (inclusive of 0, but not 1). If you pass in one parameter, it will return a random number between 0 and that number. When you pass in two parameters, it will return a random number between those two numbers.

Parameters

start number

(optional) The lower limit. Defaults to 0.

end number

(optional) The upper limit. Defaults to 1. The value itself is not included in the range.

Return type

number

Examples

RANDOM()         // => 0.30514532029142893
RANDOM()         // => 0.7147048356767045
RANDOM(100)      // => 38.672216046075626
RANDOM(100)      // => 45.05862773788321
RANDOM(-10, 10)  // => -8.589622952707675
RANDOM(-10, 10)  // => 5.529290806235942

RANDOMINT

RANDOMINT(start: number, end: number)

Returns an integer, pseudo-random number in a given range. It will return a random number between those two numbers, including those two numbers.

Parameters

start number

The lower limit.

end number

The upper limit.

Return type

number

Examples

RANDOMINT(0, 2)     // => 2 (Result can be 0, 1, or 2)
RANDOMINT(0, 100)   // => 90
RANDOMINT(0, 100)   // => 87
RANDOMINT(-10, 10)  // => 4
RANDOMINT(-10, 10)  // => 1

PICK

PICK(array: any[])

Returns an random element from a given array.

Parameters

array any[]

The array.

Return type

any

Examples

PICK([0,1,2])       // => 1 (Result can be 0, 1, or 2)
PICK(cities)        // => "London" (from imaginary list of cities)

PLUCK

PLUCK(array: any[])

Returns an random element from a given array, but also removes that element from it!

Parameters

array any[]

The array.

Return type

any

Examples

// Example 1:
const nums = [0, 1, 2, 3, 4];
PLUCK(nums)       // => 3
                  // nums is now [0, 1, 2, 4]

// Example 2:
let cities = ["London", "Paris", "New York", "Tokyo"];
PLUCK(cities)    // => "New York"
                 // cities is now ["London", "Paris", "Tokyo"]

RANGE

RANGE(start: number, end: number, step?: number)

Creates an array of numbers in a given range.

Parameters

start number

The lower limit.

end number

The upper limit.

step number

(optional) The step size. Defaults to 1.

Return type

number[]

Examples

RANGE(0, 2)         // => [0, 1, 2]
RANGE(2, 0)         // => [2, 1, 0]

// With step size of 2:
RANGE(0, 10, 2)     // => [0, 2, 4, 6, 8, 10]
RANGE(10, 0, 2)     // => [10, 8, 6, 4, 2, 0]

GUID

GUID(fill?: number | string)

Returns a globally unique identifier (GUID). Each call will return a different GUID.

Parameters

fill number | string

(optional) Value to fill the result with.

Return type

string

Examples

GUID()      // => 3fc60027-b39e-43cb-8580-239a1b2b83f4
GUID()      // => 1190795d-f387-487a-8995-49394542821e
GUID(0)     // => 00000000-0000-0000-0000-000000000000
GUID(16)    // => ffffffff-ffff-ffff-ffff-ffffffffffff
GUID('a')   // => aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa

EMPTYGUID

EMPTYGUID()

Returns a zero-filled globally unique identifier (GUID). Equal to calling GUID(0).

Parameters

Return type

string

Examples

EMPTYGUID()     // => 00000000-0000-0000-0000-000000000000

NOT

NOT(boolean: any)

Negates the specified parameter.

Parameters

boolean any

Value to be negated.

Return type

boolean

Examples

NOT(true)       // => false
NOT(false)      // => true

FOR

FOR(start: number, end: number, function: function, step?: number)

Iterates over the specified range and executes the specified function for each value. Returns the number of iterations.

Parameters

start number

The start value (inclusive).

end number

The end value (inclusive).

function function

The function to be executed for each value.

step number

(optional) The step value.

Return type

number

Examples

FOR(1, 5, i => console.log(i))      // Will log: '1', '2', '3', '4', '5'
FOR(1, 5, i => console.log(i), 2)   // Will log: '1', '3', '5'

REPEAT

REPEAT(count: number, function: function)

Repeats the specified function the specified number of times. Returns the number of iterations. REPEAT(x, func) is shorthand for FOR(1, x, func).

Parameters

count number

The number of times to repeat the function.

function function

The function to be executed for iteration. The function will be called with the iteration number as the first parameter, starting with 1 and ending with the count.

Return type

number

Examples

REPEAT(3, i => console.log(i))      // Will log: '1', '2', '3'. Note that the index starts from 1.

CLONE

CLONE(obj: any)

Creates a (deep) copy of a given object.

Parameters

obj any

The object to clone.

Return type

any

Examples

CLONE({ a: 1, b: 'hi' })     // => { a: 1, b: 'hi' }

COERCE

COERCE(str: any)

Tries to convert a string to what it represents.

Parameters

str any

The string to coerce.

Return type

any

Examples

COERCE('1')            // => 1 // Converted to number
COERCE('1.50')         // => 1.5 // Converted to number
COERCE('true')         // => true // Converted to boolean
COERCE('{ "a": 3 }')   // => { a: 3 } // Converted to an object

CSV2JSON

CSV2JSON(csv: string, options?: { separator?: string, lineSeparator?: string, objects?: boolean, skipHeader?: boolean, coerce?: boolean })

Converts a CSV string to a JSON array. Will try to detect the separator automatically. Default newline character is '\n' - can be overriden with the 'lineSeparator' option.

Parameters

csv string

The CSV string to convert.

options { separator?: string, lineSeparator?: string, objects?: boolean, skipHeader?: boolean, coerce?: boolean }

(optional) The options object.

Return type

{ [key: string]: any; }[]

Examples

CSV2JSON('a,b,c \n 1,2,3 \n 4,5,6') // Auto-detects the , separator
// => [{ a: 1, b: 2, c: 3 }, { a: 4, b: 5, c: 6 }]

CSV2JSON('a;b;c \n 1;2;3 \n 4;5;6') // Auto-detects the ; separator
// => [{ a: 1, b: 2, c: 3 }, { a: 4, b: 5, c: 6 }]

CSV2JSON('a,b,c \r 1,2,3 \r 4,5,6', { lineSeparator: '\r' })
// => [{ a: 1, b: 2, c: 3 }, { a: 4, b: 5, c: 6 }]

CSV2JSON('a|b|c\n1|2|3\n4|5|6', { separator: '|' }) // Specify a custom separator
// => [{ a: 1, b: 2, c: 3 }, { a: 4, b: 5, c: 6 }]

CSV2JSON('a,b,c\n1,2,3\n4,5,6', { objects: false }) // Disable parsing to objects (includes header in result too)
// => [ ['a', 'b', 'c'], [1, 2, 3], [4, 5, 6]]

CSV2JSON('a,b,c\n1,2,3\n4,5,6', { objects: false, skipHeader: true }) // Same as previous, but omits the header row
// => [ [1, 2, 3], [4, 5, 6]]

XML2JSON

XML2JSON(xml: string)

Converts an XML string to a JSON object.

Parameters

xml string

The XML string to convert.

Return type

{ [key: string]: any; }

Examples

XML2JSON('<a><b>1</b><c>2</c></a>') // => { a: { b: 1, c: 2 } }

JSON2XML

JSON2XML(json: { [key: string]: any; })

Converts a JSON object to an XML string.

Parameters

json { [key: string]: any; }

The JSON object to convert.

Return type

string

Examples

JSON2XML({ a: { b: 1, c: 2 } }) // => '<a><b>1</b><c>2</c></a>'
PreviousLanguage ReferenceNextFinance