Explanation of Notation:
- Values separated by a pipe-symbol (
|) can be used interchangeably. For example, if you seestring | array, the function can accept either a string or an array. - A question mark (
?) implies that something is optional. - Characters and words followed by ellipses (
x...) indicate that multiple parameters can be supplied
The word predicate is used frequently in the definitions in this topic. In this context, a predicate is a statement or expression that must evaluate to true or false. For example, an expression comparing Hire Date and Seniority Date to see if they are the same is a predicate. If the dates are the same, the predicate evaluates to true. If they aren’t, the predicate evaluates to false.
Return the absolute value of a number.
`abs(number: number) -> number`
Parameters:
**number** `number` `required`
Example:
abs(-1.23); // => 1.23Determines whether any element in an array satisfies the condition of a predicate. Returns true if at least one element satisfies; if no predicate is provided, then returns true if the array is not empty.
`any(array: any[], predicate?: (item: any) -> boolean) -> boolean`Parameters
**array** `any[]` `required`: The array of elements to check.**predicate** `(item: any) -> boolean` `optional`: A lambda function that defines the condition to check for each element.
Examples:
```
any([1, 2, 3, 4, 5, 6], x => x < 4); // => true
```
```
any([1, 2, 3, 4, 5, 6], x => x > 6); // => false
```Create a block from an array by selecting a key and value from each element in the array. This allows creation of a block with dynamic keys.
`block_from_entries(enumerable: any[], create_key: (item: any) -> string, create_value: (item: any) -> unknown) -> block`
Parameters:
**enumerable** `any[]` `required`**create_key** `(item: any) -> string` `required`**create_value** `(item: any) -> unknown` `required`
Errors:
- When the selected key is not a string.
- When the selected key has already been added to the object.
Example:
block_from_entries([ { k = a"; v = "test"; }, { k = "b"; v = "test2"; }], x => x.k, x => x.v); // => { a = "test"; b = "test2"; }block_type(block) -> stringReturns the type/name of a block. For anonymous blocks (those that are the right-hand side of a field assignment), the key is returned.
`block_type(block: block) -> string`
Parameters:
**block** `block` `required`
Examples:
Block types of named blocks:
```
foo = { bar = 123; }
output_foo = block_type(foo); // => "foo"
```
```
baz { qux = 456; }
output_baz = block_type(baz); // => "baz"
```
Block type of an anonymous block:
named { qux = {}; output = block_type(this.qux); }Return the closest integer greater than or equal to a number.
`ceiling(number: number) -> number`
Parameters:
**number** `number` `required`
Examples:
```
ceiling(2); // => 2
```
```
ceiling(2.0001); // => 3
```
```
ceiling(2.9); // => 3
```
```
ceiling(-2.4); // => -2
```chunk
Split an array into smaller, fixed-size chunks. Returns an array of sub-arrays, where each sub-array contains the specified number of consecutive elements from the original array. If the array length is not evenly divisible by the chunk size, the final chunk will contain the remaining elements.
`chunk(array: any[], size: number) -> unknown[][]`
Parameters:
**array** `any[]` `required`: The array to split into chunks.**size** `number` `required`: The number of elements per chunk. Must be a positive integer.
Errors:
When the size is not a positive integer.
Examples:
```
chunk([1, 2, 3, 4, 5, 6], 2); // => [[1, 2], [3, 4], [5, 6]]
```
```
chunk([1, 2, 3, 4, 5, 6, 7, 8], 3); // => [[1, 2, 3], [4, 5, 6], [7, 8]]
```
```
chunk([1, 2, 3, 4], 1); // => [[1], [2], [3], [4]]
```chunk_while
Given an array and a predicate function, group consecutive elements into chunks based on the predicate. The predicate compares the last element of the current chunk with the next element to determine if they should be in the same chunk. Returns an array of arrays where each sub-array is a chunk of consecutive elements.
`chunk_while(array: any[], lambda: (previous: any, current: any) -> boolean) -> unknown[][]`
Parameters:
**array** `any[]` `required`: An array of elements to chunk. For best results, the array should be sorted by the field used in the predicate.**lambda** `(previous: any, current: any) -> boolean` `required`: A lambda function that takes two consecutive elements and returns a boolean indicating whether they should be in the same chunk. The first parameter is the last element of the current chunk, and the second parameter is the next element.
Example:
chunk_while([1, 2, 3, 5, 6, 10], (a, b) => b == a + 1); // => [[1, 2, 3], [5, 6], [10]]If the value to check is nil, return the given coalescing_value; otherwise, return the value itself.
`coalesce(value: any, coalescing_value: any) -> unknown`
Parameters:
**value** `any` `required`**coalescing_value** `any` `required`
Examples:
```
foo = nil;
coalesce(foo, 0); // => 0
```
```
bar = 123;
coalesce(bar, 0); // => 123
```Concatenate a series of arrays together into a single new array.
`concat(first: any[] | block | nil, ...rest: (any[] | block | nil)[]) -> unknown[] | nil`
Parameters:
**first** `any[] | block | nil` `required`**rest** `any[] | block | nil` `variadic`
Example:
concat([1, 2, 3], [4, 5, 6]); // => [1, 2, 3, 4, 5, 6]Determine whether the given value is an element of the array or a key of the block.
`contains(container: any[] | block, value: any, comparator?: (item: any, value: any) -> boolean) -> boolean`
Parameters:
**container** `any[] | block` `required`**value** `any` `required`**comparator** `(item: any, value: any) -> boolean` `optional`
Errors:
When the comparator returns a non-boolean.
Examples:
```
contains([1, 2, 3], 2); // => true
```
```
contains([1, 2, 3], 7); // => false
```
```
contains({ foo = "bar"; }, "foo"); // => true
```
```
contains({ foo = "bar"; }, "baz"); // => false
```Return a date for the given year, month, and day.
`date(year: number, month: number, day: number) -> date`
Parameters:
**year** `number` `required`
**month** `number` `required`
**day** `number` `required`
Example:
date(year, month, day)date(2023, 4, 13); // => 2023-04-13 -> dateReturns a new date by adding a specified amount of time. Returns nil if the input date is nil.
`date_add(date: date | nil, delta: number, unit: string) -> date | nil`
Parameters:
**date** `date | nil` `required`: A date value to which the time will be added.**delta** `number` `required`: An integer representing the amount of time to add. This value can be positive (to add time) or negative (to subtract time).**unit** `string` `required`: A string representing the unit of time to be added. This can be one of the following: `"years"`, `"months"`, `"days"`, `"hours"`, `"minutes"`, `"seconds"`, `"milliseconds"`. For convenience, you can also use the singular version--e.g. `"day"`--of these units.
Errors:
When `unit` is not one of the recognized strings.
Example:
date_add(date(2023, 1, 3), 1, "day"); // => 2023-01-04date_day_of_week
Return an integer representing the day of the week of a given date.
`date_day_of_week(date: date) -> number`
Parameters:
**date** `date` `required`: The date of which to get the day-of-the-week
Example:
date_day_of_week(date(2024, 1, 14)); // => 2 -- i.e. TuesdayReturn the length of time between two dates in the given unit. There are two sets of units of time that can be used: **Precise Difference** and **Coarse Difference**. **Precise Difference** units (`"days"`, `"hours"`, `"minutes"`, `"seconds"`) can all be converted to seconds without any loss of information and so are suitable for converting exact lengths of time. **Coarse Difference** units (`"years"`, `"months"`) can all be converted to months, but can only be represented as integers with no fractional component because they are not fixed lengths of time—that is, they are not convertible to seconds, rather they are calendar differences. These lengths of time are based around the number of whole months between two dates, where “1 month” has passed when the same day-of-the-month has been reached in another calendar month.
`date_diff(date1: date | nil, date2: date | nil, unit: string) -> number | nil`
Parameters:
**date1** `date | nil` `required`**date2** `date | nil` `required`**unit** `string` `required`: A string representing the unit of time. This can be one of the following: `"years"`, `"months"`, `"days"`, `"hours"`, `"minutes"`, `"seconds"`. For convenience, you can also use the singular version—for example`"day"`—of these units.
Errors:
When unit is not one of the recognized strings: "days", "months", "years", "hours", "minutes", "seconds".
Examples:
Precise Difference
```
date_diff(date(2023, 1, 5), date(2023, 1, 3), "days"); // => 2
```
```
date_diff(nil, date(2023, 1, 3), "days"); // => nil
```
```
date_diff(date(2023, 1, 3), nil, "days"); // => nil
```
```
date_diff(nil, nil, "days"); // => nil
```
```
date_diff(date(2023, 1, 3), date(2023, 1, 5), "days"); // => -2
```
Coarse Difference
```
date_diff(date(2024, 1, 9), date(2021, 3, 18), "months"); // => 33
```
```
date_diff(date(2024, 1, 9), date(2021, 3, 18), "years"); // => 2
```date_ranges_overlap
Determine if the two given date ranges have any overlap. If either range has a `nil` end date then that range is considered to extend into the infinite future.
`date_ranges_overlap(start_date_1: date, end_date_1: date | nil, start_date_2: date, end_date_2: date | nil) -> boolean`
Parameters:
**start_date_1** `date` `required`**end_date_1** `date | nil` `required`**start_date_2** `date` `required`**end_date_2** `date | nil` `required`
Errors:
When the end date precedes start date.
Examples:
```
date_ranges_overlap(date(2024, 1, 1), nil, date(2024, 6, 1), date(2024, 7, 1)); // => true
```
```
date_ranges_overlap(date(2023, 1, 1), date(2023, 12, 31), date(2024, 1, 1), date(2024, 6, 1)); // => false
```Return a date/time for the given year, month, day, hour, minute, second, and millisecond.
`datetime(year: number, month: number, day: number, hour: number, minute: number, second: number, millisecond?: number) -> date`
Parameters:
**year** `number` `required`**month** `number` `required`**day** `number` `required`**hour** `number` `required`**minute** `number` `required`**second** `number` `required`**millisecond** `number` `optional`
Errors:
When a value is out of range.
Example:
datetime(2023, 4, 13, 15, 23, 22); // => 2023-04-13T15:23:22Determine whether the date is within a date range, inclusive of the lower and upper bound. If no upper bound is provided, determine whether the date is within one particular day inclusively.
`date_within(date: date | nil, lower: date, upper?: date) -> boolean`
Parameters:
**date** `date | nil` `required`**lower** `date` `required`- **upper** `date` `optional`
Errors:
When lower bound is greater than upper bound.
Examples:
```
date_within(date(2023, 4, 13, 15, 23, 22), date(2023, 4, 10), date(2023, 4, 16)); // => true
```
```
date_within(date(2023, 4, 13, 15, 23, 22), date(2023, 4, 13)); // => true
```Return the day part (day of the month) of a date.
`day(date: date | nil) -> number | nil`
Parameters:
**date** `date | nil` `required`
Examples:
```
day(date(2023, 4, 13, 15, 23, 22)); // => 13
```
```
day(nil); // => nil
```day_of_week
Given the (English) name of a day of the week, return its integer representation.
`day_of_week(day_name: string) -> number`
Parameters:
**day_name** `string` `required`
Errors:
When the day of week is invalid.
Examples:
```
day_of_week("Sunday"); // => 0
```
```
day_of_week("Thursday"); // => 4
```
```
Raise an error with the given message. This will stop the integration from completing.
`error(message: string) -> void`
Parameters:
**message** `string` `required`
Examples:
error("OH NO");Given a value's path, determine if that value actually exists in the input data. Note that nonexistence is not the same thing as a value being nil.
`exists(object: any) -> boolean`
Parameters:
**object** `any` `required`
Examples:
Important: You still need to have a `?` in your path to prevent an error upon reaching a missing value for example rather than `exists(something.might_not_exist)` you need to write: `exists(something.might_not_exist?)`.
```
data { a = 123; b = nil; }
does_exist = exists(data.a?); // => true
```
```
data { a = 123; b = nil; }
nil_exists = exists(data.b?); // => true
```
```
data { a = 123; b = nil; }
does_not_exist = exists(data.c?); // => false
```
Return the value from the external list of data with the given name.
`external(name: string) -> unknown`
Parameters:
* **name** `string` `required`
Errors:
When the name does not exist in the external list of data.
Examples:
```
ExternalList = { "LAST_SUCCESSFUL_RUN_DATE": 2023-06-22T00:00:00 }
external("LAST_SUCCESSFUL_RUN_DATE"); // => 2023-06-22T00:00:00
```
```
external("NOT_FOUND_NAME"); // => error
```Given a block and the name of a field (as a string), return the value of that field on the object.
`field(block: block, field_name: string) -> unknown`
Parameters
**block** `block` `required`**field_name** `string` `required`
Example:
foo { bar = 123; }
field(foo, "bar"); // => 123Given a block, return an array of key/value pairs for the fields within that object.
`fields(block: block) -> unknown[]`
Parameters:
**block** `block` `required`
Example:
foo {
bar = { a = 111; b = 222; };
baz = fields(foo.bar); // => [{ key = "a"; value = 111; }, { key = "b"; value = 222; }]
}Given an array and a predicate, return an array composed of only those elements from the supplied array for which the predicate evaluated to true.
`filter(array: any[] | block, predicate: (item: any) -> boolean) -> unknown[]`
Parameters:
**array** `any[] | block` `required`**predicate** `(item: any) -> boolean` `required`
Example:
filter([1, 2, 3, 4, 5, 6], x => x < 4); // => [1, 2, 3Given an array and a predicate, return the first item in that array for which the predicate evaluates to `true`, or `nil` if there is no such item.
`find(array: any[] | block, predicate: (item: any) -> boolean) -> unknown | nil`
Parameters:
**array** `any[] | block` `required`**predicate** `(item: any) -> boolean` `required`
Examples:
```
find([
{ id = "123"; name = "John Doe"; },
{ id = "456"; name = "Jane Doe"; },
{ id = "456"; name = "Nobody"; },
], person => person.id == "456"); // => [{ id = "456"; name = "Jane Doe"; }]
```
```
find([
{ id = "123"; name = "John Doe"; },
{ id = "456"; name = "Jane Doe"; },
{ id = "789"; name = "Nobody"; },
], person => person.id == "000"); // => nil
```Given a block and a number of keys (i.e. strings), return the child blocks of the given block such that the child blocks have any of the given types.
`find_children(parent: block, ...child_type: string[]) -> unknown[]`
Parameters:
**parent** `block` `required`**child_type** `string` `variadic`
Example:
foo { bar { baz = 111; } bar { baz = 222; } }
find_children(foo, "bar"); // => bar { baz = 111; } bar { baz = 222; }
Given an array and a predicate, return the only item in that array for which the predicate evaluates to `true`, or `nil` if there is no such item.
`find_single(array: any[] | block, predicate: (item: any) -> boolean) -> unknown | nil`
Parameters:
**array** `any[] | block` `required`**predicate** `(item: any) -> boolean` `required`
Errors:
* When multiple elements satisfy the condition.
Examples:
```
find_single([
{ id = "123"; name = "John Doe"; },
{ id = "456"; name = "Jane Doe"; },
{ id = "456"; name = "Nobody"; },
], person => person.id == "456"); // => { id = "456"; name = "Jane Doe"; }
```
```
find_single([
{ id = "123"; name = "John Doe"; },
{ id = "456"; name = "Jane Doe"; },
{ id = "789"; name = "Nobody"; },
], person => person.id == "000"); // => nil
```
```
find_single([
{ id = "111"; name = "John Doe"; },
{ id = "111"; name = "Jane Doe"; },
{ id = "789"; name = "Nobody"; },
], person => person.id == "111"); // => ERROR
```
Given an array and a predicate, return the first item in that array for which the predicate evaluates to true. If no predicate is given, the first element of the array will be returned.
`first(array: any[] | block, predicate?: (item: any) -> boolean) -> unknown`
Parameters:
**array** `any[] | block` `required`**predicate** `(item: any) -> boolean` `optional`
Errors:
- When predicate is not provided, but the array is empty.
- When predicate is provided, but no elements satisfy the given condition.
Examples:
```
first([
{ id = "123"; name = "John Doe"; },
{ id = "456"; name = "Jane Doe"; },
{ id = "789"; name = "Nobody"; },
], person => person.id == "456"); // => { id = "456"; name = "Jane Doe"; }
```
```
first([3, 1, 4]); // => 3
```Given an array and a lambda that returns a value, return an array such that arrays returned by the lambda are flattened by one level.
`flat_map(array: any[] | block, predicate?: (item: any) -> unknown) -> unknown[]`
Parameters:
**array** `any[] | block` `required`**predicate** `(item: any) -> unknown` `optional`
Examples:
```
flat_map([{ a = [1, 2]; }, { a = [3, 4]; }], x => x.a) // => [1, 2, 3, 4]
```
```
flat_map([[1, 2], [3, 4]]) // => [1, 2, 3, 4]
```Given a block with child blocks with non-overlapping field names, merge the fields of the child blocks into a copy of the parent block and return that.
`flatten(block: block, ...field: string[]) -> block`
Parameters:
**block** `block` `required`**field** `string` `variadic`
Example:
foo {
bar {
baz = { a = 123; };
qux = { b = 456; };
}
quux = flatten(foo.bar); // => { a = 123; b = 456; }
}floor
Return the closest integer smaller than or equal to a number.
`floor(number: number) -> number`
Parameters:
**number** `number` `required`
Examples:
```
floor(2) // => 2
```
```
floor(2.0001) // => 2
```
```
floor(2.9) // => 2
```
```
floor(-2.4) // => 3
```Given a date and a format string, return a string representation of that date, formatted accordingly.
`format_date(date: string | date | nil, format: string) -> nil | string`
Parameters:
**date** `string | date | nil` `required`**format** `string` `required`
Errors:
- When the date argument is a non-empty string.
- When the format is invalid.
:
format_date(date(2023, 1, 3), "MM/dd/yyyy") // => "01/03/2023"Given a number, a number of decimal places, and an optional decimal separator, return a corresponding string representation of that number. Note that decimals will be rounded, not truncated. If a `format_string` is supplied, format the number according to the `.Net` standard.
`format_number(number: number | nil, decimal_places_or_format_string: number | string, decimal_separator?: string) -> nil | string`
Parameters:
**number** `number | nil` `required`**decimal_places_or_format_string** `number | string` `required`**decimal_separator** `string` `optional`
Errors:
When decimal separator is invalid, either '.' or ',' is allowed.
Examples:
```
format_number(123.456, 2); // => 123.46
```
```
format_number(1111.2222, 2, ","); // => 1111,22
```
```
format_number(999.888, "0000.00"); // => 0999.89
```
group_by
Given an array of data, group the data by some key, optionally transforming the data in the process, and then process the grouped data. This can be used to change the structure of an input array.
`group_by(array: any[] | block, create_key: (item: any) -> unknown, create_value: (item: any) -> unknown, process_groups: (key: any, values: any[]) -> unknown) -> nil | unknown[]`
Parameters:
**array** `any[] | block` `required`**create_key** `(item: any) -> unknown` `required`**create_value** `(item: any) -> unknown` `required`**process_groups** `(key: any, values: any[]) -> unknown` `required`
Errors:
When `create_key` returns an array.
### Example(s)
group_by([
{ a = "k1; b = 11; },
{ a = "k2"; b = 22; },
{ a = "k1; b = 33; },
{ a = "k2"; b = 44; }
],
o => o.a,
o => o.b,
(key, values) => {
key = key;
value_sum = sum(values);
}); // => [ { key = "k1"; value_sum = 44; }, { key = "k2"; value_sum = 66; } ]The group-by functionality can also use “composite keys”, or keys made up of multiple “sub-keys.” To do this, use a block value as the key. For example:
group_by([
...
],
o => { k1 = ...; k2 = ...; }, // Composite-key block
o => o,
(keys, values) => {
...
});
If the keys to use in a composite key are from an existing object--e.g. the one from which the key is created, IDL has a short-hand for copying object keys. Here is an example of the syntax:
let obj1 = {a = 111; b = 222; c = 999; };
let obj2 = { obj1.a; obj2.b; c = 333; }; // { a = 111; b = 222; c = 333; };hour
Return the hour part of a date, and return `nil` if the date is `nil`.
`hour(date: date | nil) -> nil | number`
Parameters:
**date** `date | nil` `required`
Examples:
```
hour(date(2023, 4, 13, 15, 23, 22)); // => 15
```
```
hour(nil); // => nil
```Given any value, return that value.
`identity(object: any) -> unknown`
Parameters:
**object** `any` `required`
Examples:
Given any value, return that value. This function isn’t usually useful except internally to IDL.
```
identity(123); // => 123
```
```
identity("test") // => test
```is_alphabetic
Determine whether a character is a letter.
`is_alphabetic(value: string | nil) -> boolean`
Parameters:
**value** `string | nil` `required`
Errors:
* When the value is a string instead of a character.
Examples:
```
is_alphabetic("a"); // => true
```
```
is_alphabetic("1") // => false
```
```
is_alphabetic(nil) // => false
```
```
is_alphabetic("ab") // => ERROR!
```is_alphanumeric
Determine whether a character is a letter or a digit.
`is_alphanumeric(value: string | nil) -> boolean`
Parameters:
**value** `string | nil` `required`
Errors:
When the value is a string instead of a character.
Examples:
```
is_alphabetic("a"); // => true
```
```
is_alphabetic("1") // => true
```
```
is_alphabetic(nil) // => false
```
```
is_alphabetic("@") // => false
```
```
is_alphabetic("ab") // => ERROR!
```Return `false` if the given value is either `nil`, missing from the source, or if the value is an empty container value, otherwise return `true`. Container values are values conceptually composed of sub-values, that is blocks, arrays, or strings (of characters).
`is_material(value: any) -> boolean`
Parameters:
**value** `any` `required`
Examples:
Important: Keep in mind that if you are checking whether a block is missing value, you still need to have a `?` in your path to prevent an error upon reaching the missing value. That is, rather than `is_material(something.might_not_exist)` you need to write `is_material(something.might_not_exist?)`.
```
foo { bar = 123; }
is_material(foo.qux?); // => false
```
```
is_material([]) // => false
```
```
is_material({}) // => false
```
```
is_material(nil) // => false
```
```
is_material("") // => false
```
```
is_material(123) // => true
```
```
is_material("abc") // => true
```Return `true` if the given value is `nil`, otherwise return `false`.
`is_nil(value: any) -> boolean`
Parameters:
**value** `any` `required`
Example:
```
foo { bar = 123; baz = nil; }
output_bar = is_nil(foo.bar); // => false
output_baz = is_nil(foo.baz); // => true
```is_numeric
Determine whether a character is a digit.
`is_numeric(value: string | nil) -> boolean`
Parameters:
**value** `string | nil` `required`
Errors:
When the value is a string instead of a character.
Examples:
```
is_alphabetic("a"); // => false
```
```
is_alphabetic("1") // => true
```
```
is_alphabetic(nil) // => false
```
```
is_alphabetic("ab") // => ERROR!
```Concatenate each element in the array as a string , separated by the given delimiter.
`join(array: any[] | block, delimiter?: string) -> string`
Parameters:
**array** `any[] | block` `required`**delimiter** `string` `optional`
Examples:
```
join([3, 1, 2], ","); // => "3,1,2"
```
```
join(["this", "is", "a", "test"], " ") // => "this is a test"
```Returns the final/last value of an array.
`last(array: any[] | block, predicate?: (item: any) -> boolean) -> unknown`
Parameters:
**array** `any[] | block` `required`**predicate** `(item: any) -> boolean` `optional`
Errors:
- When the predicate did not return a boolean.
- When no item matched the predicate.
Examples:
```
last([1, 2, 3]); // => 3
```
```
last([1, 2, 3, 4, 5, 6], x => x > 3); // => 6
```Return the number of items in an array.
`length(array: any[] | block) -> number`
Parameters:
**array** `any[] | block` `required`
Examples:
```
length([3, 1, 2]); // => 3
```
```
length([]); // => 0
```
Given an array and a lambda function that produces a value, return a new array where every item in the new array is a function of the item in the same index in the given array. This is used to transform one array of values into another and is the usually most fundamental operation in any integration.
`map(array: any[] | block, lambda: (item: any, index: number) -> unknown) -> unknown[]`
Parameters:
**array** `any[] | block` `required`**lambda** `(item: any, index: number) -> unknown` `required`
Examples:
```
map([1, 2, 3], x => x * x); // => [1, 4, 9]
```
```
map([
{ xref = "EMP001"; name = "John"; },
{ xref = "EMP002"; name = "Jane"; },
{ xref = "EMP003"; name = "Alex"; }
], employee => employee.name); // => ["John", "Jane", "Alex"]
```
```
map([
{ xref = "EMP001", first_name = "John"; last_name = "Smith"; },
{ xref = "EMP002", first_name = "Jane"; last_name = "Doe"; }
], emp => {
id = emp.xref;
full_name = concat(emp.first_nam, " ", emp.last_name);
}); // => [{ id = "EMP001"; full_name = "John Smith"; }, { id = "EMP002"; full_name = "Jane Doe"; }]
```
Analogous to map, except it works on a single block rather than an array, and returns `nil` with `nil` input.
`map_single(block: block | nil, lambda: (item: any) -> unknown) -> nil | unknown`
Parameters:
**block** `block | nil` `required`**lambda** `(item: any) -> unknown` `required`
Examples:
```
map_single({ xref = "EMP001", first_name = "John"; last_name = "Smith"; }, emp => {
id = emp.xref;
full_name = concat(emp.first_nam, " ", emp.last_name);
}); // => { id = "EMP001"; full_name = "John Smith"; }
```
```
map_single(nil, emp => {
id = emp.xref;
}); // => nil
```Return the maximum value of an array of comparable items--i.e. strings, numbers, or dates. If provided, the lambda function must return a comparable value. If a lambda value is not provided then the values in the array must be comparable values. Items are ordered as though by the greater-than-or-equal-to operator. For numbers, the largest number is returned. For dates, the latest date is returned. For strings, the last string is returned when sorted alphabetically.
`max(array: any[] | block, lambda?: (item: any) -> number | date | string) -> number | date | string`
Parameters:
**array** `any[] | block` `required`**lambda** `(item: any) -> number | date | string` `optional`
Errors:
- When the array contains no elements.
- When not all array elements have the same type.
Examples:
```
max([3, 1, 2]); // => 3
```
```
max([]); // => ERROR!
```
```
max([{ b = 111; }, { b = 222; }], x => x.b); // => 222
```
Given a series of blocks with non-overlapping sets of keys, merge them into a new block having all the keys and values from the given blocks. If the same key exists in multiple objects, the rightmost one is the final value.
`merge(block1: block, block2: block, ...blocks: block[]) -> block`
Parameters:
**block1** `block` `required`**block2** `block` `required`**blocks** `block` `variadic`
Examples:
```
merge({ a = 1; }, { b = 2; }); // => { a = 1; b = 2; }
```
```
merge({ a = 1; }, { a = 2; }); // => { a = 2; }
```Return the minimum value of an array of comparable items--i.e. strings, numbers, or dates. If provided, the lambda function must return a comparable value. If a lambda value is not provided then the values in the array must be comparable values. Items are ordered as though by the less-than-or-equal-to operator. For numbers, the smallest number is returned. For dates, the earliest date is returned. For strings, the first string is returned when sorted alphabetically.
`min(array: any[] | block, lambda?: (item: any) -> number | date | string) -> number | date | string`
Parameters:
**array** `any[] | block` `required`**lambda** `(item: any) -> number | date | string` `optional`
Errors:
- When the array contains no elements.
- When not all array elements have the same type.
Examples:
```
min([3, 1, 2]); // => 1
```
```
min([]); // => ERROR!
```
```
min([{ b = 111; }, { b = 222; }], x => x.b); // => 111
```minute
Return the minute part of a date, and return `nil` if the date is `nil`.
`minute(date: date | nil) -> nil | number`
Parameters:
**date** `date | nil` `required`
Examples:
```
minute(date(2023, 4, 13, 15, 23, 22)); // => 23
```
```
minute(nil); // => nil
```Given a date, return a date/time value representing the end of that month, at one minute before the first midnight of the following month.
`month_end(date: date | nil) -> nil | date`
Parameters:
**date** `date | nil` `required`
Example:
month_end(date(2023, 1, 20)); // => 2023-01-31T23:59:59month
Return the month part of a date, and return `nil` if the date is `nil`.
`month(date: date | nil) -> nil | number`
Parameters:
**date** `date | nil` `required`
Examples:
```
month(date(2023, 4, 13, 15, 23, 22)); // => 4
```
```
month(nil); // => nil
```Given a date, return a date/time value representing the start of that month, at the first midnight of the month.
`month_start(date: date | nil) -> nil | date`
Parameters:
**date** `date | nil` `required`
Example:
month_end(date(2023, 1, 20)); // => 2023-01-01T00:00:00Return the current date/time, at the time of running the integration. Internally, the time is represented as being in Coordinated Universal Time.
`now() -> date`
Example:
now(); // => e.g. 2023-01-20T09:22:34Return the n-th value (i.e. item at the given index) within an array. The first element of an array is at index 0. If the index is negative, the index is assumed to be from the end of the array such that the item at index -1 is the last element in the array.
`nth(array: any[] | block, index: number) -> nil | unknown`
Parameters:
**array** `any[] | block` `required`**index** `number` `required`
Errors:
When the index is not an integer.
Examples:
```
nth([3, 1, 2], 0); // => 3
```
```
nth([3, 1, 2], 1); // => 1
```
```
nth([3, 1, 2], 2); // => 2
```
```
nth([3, 1, 2], -1); // => 2
```
```
nth([3, 1, 2], -2); // => 1
```Remove the field from the final output. In the below example, the foo block will be empty--i.e. will not have any fields/keys in it--in the output.
`omit() -> missing`
Example:
foo {
bar = omit();
}If the given value is `nil`, remove the resultant field from the output (like the `omit()` function call does); otherwise, return the given value;
`omit_nil(value: any) -> missing | unknown`
Parameters:
**value** `any` `required`
Example:
foo {
bar = omit_nil(nil); // REMOVED
baz = omit_nil(123); // 123
}Given an array and a lambda that will produce a field for any item in the array, return a new array with the items in the original array ordered by the specified field in ascending order. If multiple lambdas are supplied, the ordering is “hierarchical” in that first the input is sorted according to the first lambda, then those items are sorted by the second lambda, and so on. The `order` parameter is “magic” and can be used to switch between ascending (the default) and descending. To use a descending sort, use `desc` as the name of the param--e.g. `order_by(array, x => x.a, (x, desc) => x.b)` will sort by the field `a` ascending, then the field `b` descending.
`order_by(array: any[] | block, ...lambda: ((item: any) -> unknown)[]) -> unknown[]`
Parameters:
**array** `any[] | block` `required`**lambda** `(item: any) -> unknown` `variadic`
Examples:
```
order_by([
{ a = 2; b = 3; },
{ a = 1; b = 2; },
{ a = 1; b = 1; },
{ a = 2; b = 2; }
], x => x.a, x => x.b) // => [{ a = 1; b = 1; }, { a = 1; b = 2; }, { a = 2; b = 2; }, { a = 2; b = 3; }]
```
```
order_by([
{ a = 2; b = 3; },
{ a = 1; b = 2; },
{ a = 1; b = 1; },
{ a = 2; b = 2; }
], x => x.a, (x, desc) => x.b) // => [{ a = 1; b = 2; }, { a = 1; b = 1; }, { a = 2; b = 3; }, { a = 2; b = 2; }]
```order_by_desc
Given an array and a lambda that will produce a field for any item in the array, return a new array with the items in the original array ordered by the specified field in descending order. If multiple lambdas are supplied, the ordering is “hierarchical” in that first the input is sorted according to the first lambda, then those items are sorted by the second lambda, and so on. The `order` parameter is “magic” and can be used to switch between descending and ascending (the default). To use an ascending sort, use `asc` as the name of the param--e.g. `order_by_desc(array, x => x.a, (x, asc) => x.b)` will sort by the field `a` descending, then the field `a` ascending.
`order_by_desc(array: any[] | block, lambda: (item: any) -> unknown) -> unknown[]`
Parameters:
**array** `any[] | block` `required`**lambda** `(item: any) -> unknown` `required`
Examples:
```
order_by_desc([
{ a = 2; b = 3; },
{ a = 1; b = 2; },
{ a = 1; b = 1; },
{ a = 2; b = 2; }
], x => x.a, x => x.b) // => [{ a = 2; b = 3; }, { a = 2; b = 2; }, { a = 1; b = 2; }, { a = 1; b = 1; }]
```
```
order_by_desc([
{ a = 2; b = 3; },
{ a = 1; b = 2; },
{ a = 1; b = 1; },
{ a = 2; b = 2; }
], x => x.a, (x, asc) => x.b) // => [{ a = 2; b = 2; }, { a = 2; b = 3; }, { a = 1; b = 1; }, { a = 1; b = 2; }]
```Given a string, length and padding character, it will produce a new string with padding characters added to the left of the original string.
`pad_left(string: string | nil, length: number, padding_character: string) -> string`
Parameters:
**string** `string | nil` `required`**length** `number` `required`**padding_character** `string` `required`
Errors:
- When the length is not a positive integer.
- When the padding character is a string.
Examples:
```
pad_left(nil, 5, "a"); // => "aaaaa"
```
```
pad_left("testing", 10, "a"); // => "aaatesting"
```
```
pad_left("testing", 4, "a"); // => "testing"
```
```
pad_left("test", 4, "a"); // => "test"
```Given a string, length and padding character, it will produce a new string with padding characters added to the right of the original string.
`pad_right(string: string | nil, length: number, padding_character: string) -> string`
Parameters:
**string** `string | nil` `required`**length** `number` `required`**padding_character** `string` `required`
Errors:
- When the length is not a positive integer.
- When the padding character is a string.
Examples:
```
pad_right(nil, 5, "a"); // => "aaaaa"
```
```
pad_right("testing", 10, "a"); // => "testingaaa"
```
```
pad_right("testing", 4, "a"); // => "testing"
```
```
pad_right("test", 4, "a"); // => "test"
```Given a date formatted as a standard date string, parse that date and return it as an IDL date/time value.
`parse_date(date: string | date | nil) -> date | string | nil`
Parameters:
**date** `string | date | nil` `required`
Errors:
When the date string is invalid.
Example:
parse_date("2023-03-08"); // => 8 March 2023Given a number, formatted as a string, parse that to an IDL number value.
`parse_number(string: string | nil) -> number | nil`
Parameters:
**string** `string | nil` `required`
Errors:
When the number string is invalid.
Example:
parse_number("123.45"); // => 123.45pipe
This function is an alias for `then` function. It returns the result of the given lambda where the lambda’s variable is the input value. It allows you to pipeline things that are not functions and, therefore, cannot normally be pipelined.
`pipe(object: any, lambda: (object: any) -> unknown) -> unknown`
Parameters:
**object** `any` `required`**lambda** `(object: any) -> unknown` `required`
Example:
pipe([1, 2, 3, 4, 5], result => sum(result)); // => 15Given an array and a reducer function, use that function to produce a single value from the array.
`reduce(array: any[] | block, reducer: (accumulator: any, item: any) -> unknown, initial_value: any) -> unknown`
Parameters:
**array** `any[] | block` `required`**reducer** `(accumulator: any, item: any) -> unknown` `required`**initial_value** `any` `required`
Errors:
When the number of arguments of reducer function is not equal to two.
Example:
reduce([1, 2, 3, 4], (product, x) => product * x, 1); // => 24Return a new string such that all instances of the original string have been replaced by the replacement string.
`replace(string: string | nil, original: string, replacement: string) -> nil | string`
Parameters:
**string** `string | nil` `required`**original** `string` `required`**replacement** `string` `required`
Example:
replace("This is a test.", "a test", "the result"); // => "This is the result."resolve
Terminate a pipeline early such that its result is the argument to the resolve function. Note that this function may only be called within function pipelines.
`resolve(value: any) -> unknown`
Parameters:
**value** `any` `required`
Given a number and a number of decimal places, it rounds the number to a specified number of fractional digits. When a number is halfway between two others, it will round towards the nearest number away from zero.
`round(number: number | nil, decimal_places: number) -> nil | number`
Parameters:
**number** `number | nil` `required`**decimal_places** `number` `required`
Examples:
```
round(2.5, 3); // => 2.500
```
```
round(2.51267, 3); // => 2.513
```
```
round(2.51227, 3); // => 2.512
```scan
Process an array as in the reduce function, but instead of returning a single value, return an array of all intermediate values. This produces an array of running values.
`scan(array: any[] | block, reducer: (accumulator: any, item: any) -> unknown, initial_value?: any) -> unknown[]`
Parameters:
**array** `any[] | block` `required`**reducer** `(accumulator: any, item: any) -> unknown` `required`**initial_value** `any` `optional`
Example:
scan([1, 2, 3], (sum, x) => sum + x, 0); // => [0, 1, 3, 6]second
Return the second part of a date, and return `nil` if the date is `nil`.
`second(date: date | nil) -> nil | number`
Parameters:
**date** `date | nil` `required`
Examples:
```
second(date(2023, 4, 13, 15, 23, 22)); // => 22
```
```
second(nil); // => nil
```Given an array and a predicate, return the first item in that array for which the predicate evaluates to true. If zero or multiple elements match the condition, an error is raised. If no predicate is given, the only element of the array will be returned.
`single(array: any[] | block, predicate?: (item: any) -> boolean) -> unknown`
Parameters:
**array** `any[] | block` `required`**predicate** `(item: any) -> boolean` `optional`
Errors:
- When condition did not match any elements in the array.
- When condition matched multiple elements in the array.
Examples:
```
single([
{ id = "123"; name = "John Doe"; },
{ id = "456"; name = "Jane Doe"; },
{ id = "789"; name = "Nobody"; },
], person => person.id == "456"); // => { id = "456"; name = "Jane Doe"; }
```
```
single([3, 1, 4]); // => ERROR!
```Return the remainder of the array, skipping the first n number of items.
`skip(array: any[] | block, count: number) -> unknown[]`
Parameters:
**array** `any[] | block` `required`**count** `number` `required`
Errors:
When the count parameter is not an integer.
Examples:
```
skip([3, 1, 2], 2); // => [2]
```
```
skip([3, 1, 2], 0); // => [3, 1, 2]
```
```
skip([3, 1, 2], 5); // => []
```Given an array and a comparator function, return a new array consisting of the items in the given array, sorted according to the comparator. If no comparator is given, a default sort will be applied. The default sort is equivalent to passing, as the comparator argument, `(a, b) => if a < b { -1 } else { 1 }`
`sort(array: any[] | block, comparator?: (item1: any, item2: any) -> number) -> unknown[]`
Parameters:
**array** `any[] | block` `required`**comparator** `(item1: any, item2: any) -> number` `optional`
Errors:
When the number of arguments of the comparator is not equal to 2.
Examples:
```
sort([2, 1, 3]); // => [1, 2, 3]
```
```
sort([2, 1, 3], (x, y) => if x < y { 1 } else { -1 }); // => [3, 2, 1]
```
Given a string and a delimiter, return an array of strings where each string in the array is a substring of the original string, each substring being separated by the given delimiter.
`split(string: string, separator: string) -> string[]`
Parameters:
**string** `string` `required`**separator** `string` `required`
Example:
split("this,is,a,test", ","); // => ["this", "is", "a", "test"]string_chars
Convert a string into an array of its characters.
`string_chars(string: string | nil) -> nil | string[]`
Parameters:
**string** `string | nil` `required`
Example:
string_chars("test"); // => ["t", "e", "s", "t"]Concatenate a series of strings together into a single string. If a number is used instead of a string, it is stringified using a default conversion. This is safe for integers, but can be problematic for decimals, so decimals should be explicitly formatted. Nil values are ignored.
`string_concat(first: string | number | nil, ...rest: (string | number | nil)[]) -> nil | string`
Parameters:
**first** `string | number | nil` `required`**rest** `string | number | nil` `variadic`
Examples:
```
string_concat("abc", "def"); // => "abcdef"
```
```
string_concat("one", nil, "two"); // => "onetwo"
```
```
string_concat("test", 123, "testing"); // => "test123testing"
```If the substring is contained within the given string, return true and return false otherwise. By default, this function is case-sensitive but this can be changed by passing `true` as the `case_insensitive` parameter.
`string_contains(string: string | nil, substring: string | nil, case_insensitive?: boolean) -> boolean`
Parameters:
**string** `string | nil` `required`**substring** `string | nil` `required`**case_insensitive** `boolean` `optional`
Examples:
```
string_contains("testing", "test"); // => true
```
```
string_contains("testing", "nope"); // => false
```
```
string_contains("testing", "TEST"); // => false
```
```
string_contains("testing, "TeSt", true); // => true
```string_cut
Given a string and a string defining where to cut, return an array of the two substrings around the first instance of that second string.
`string_cut(string: string | nil, cut_at: string, case_insensitive?: boolean) -> nil | string[]`
Parameters:
**string** `string | nil` `required`**cut_at** `string` `required`**case_insensitive** `boolean` `optional`
Example:
string_cut("test_string", "_"); // => ["test", "string"]string_ends_with
Determine whether the end of the string matches the suffix.
`string_ends_with(string: string | nil, suffix: string, case_insensitive?: boolean) -> boolean`
Parameters:
**string** `string | nil` `required`**suffix** `string` `required`**case_insensitive** `boolean` `optional`
Examples:
```
string_ends_with("testing", "ing"); // => true
```
```
string_ends_with("testing", "nope"); // => false
```string_format
Replace the format items in the string with the string representation of objects.
`string_format(string_format: string | nil, ...argument: any[]) -> nil | string`
Parameters:
**string_format** `string | nil` `required`**argument** `any` `variadic`
Examples:
```
string_format("test{0}{1}", 123, true); // => "test123true"
```
```
string_format("test{0}{0}", 123); // => "test123123"
```
```
string_format(nil, 123, true); // => nil
```string_index_of
Given a string and a target string, it returns the `0` based index of the target string within the string, and returns `-1` if the `target` does not exist in the string. By default, this function is case-sensitive but this can be changed by passing true as the `case_insensitive` parameter.
`string_index_of(string: string | nil, target: string, case_insensitive?: boolean) -> nil | number`
Parameters:
**string** `string | nil` `required`**target** `string` `required`**case_insensitive** `boolean` `optional`
Example:
string_index_of("test_string", "_"); // => 4string_last_index_of
Given a string and a target string, it returns the `0` based index of the last target string within the string, and returns `-1` if the `target` does not exist in the string. By default, this function is case-sensitive but this can be changed by passing `true` as the `case_insensitive` parameter.
`string_last_index_of(string: string | nil, target: string, case_insensitive?: boolean) -> nil | number`
Parameters:
**string** `string | nil` `required`**target** `string` `required`**case_insensitive** `boolean` `optional`
Example:
string_last_index_of("test_string_last", "_"); // => 11string_lay_out
Given an input string and a layout string, return a string that lays out the input string according to the supplied format. Note that all non-alphanumeric characters are removed and the number of alphanumeric characters in the input string must equal the number of placeholder characters in the layout string.
`string_lay_out(string: string | nil, layout_string: string, placeholder_character: string) -> nil | string`
Parameters:
**string** `string | nil` `required`**layout_string** `string` `required`**placeholder_character** `string` `required`
Errors:
- When placeholder character is a string with more than one character.
- When the number of alphanumeric characters does not match the number of placeholder characters.
Example:
let phone_number = "1234567890";
string_lay_out(phone_number, "+1 (###) ###-####", "#"); // => +1 (123) 456-7890Return a string containing a specified number of characters from the left side of a string.
`string_left(string: string | nil, length: number) -> nil | string`
Parameters:
**string** `string | nil` `required`**length** `number` `required`
Errors:
When the length is not an integer.
Examples:
```
string_left("testing", 4); // => "test"
```
```
string_left(nil, 4); // => nil
```string_length
Return the length of the string (in UTF-16 codepoints). For most strings this will be equal to the intuitive length of the string, but there are special cases for which the intuitive length will not match the returned length. Emoji, for example, often require 2 UTF-16 codepoints per character meaning that the string "" has length 2. For most human languages, however, the length returned will be what you expect.
`string_length(string: string | nil) -> nil | number`
Parameters:
**string** `string | nil` `required`
Examples:
```
string_length("test"); // => 4
```
```
string_length(""); // => 0
```
```
string_length(nil); // => nil
```
```
string_length("한글"); // => 2
```string_lowercase
Change the case of the given string to lowercase.
`string_lowercase(string: string | nil, locale?: string) -> nil | string`
Parameters:
**string** `string | nil` `required`**locale** `string` `optional`
Errors:
When the locale is invalid.
Examples:
```
string_lowercase("TEST"); // => "test"
```
```
string_lowercase("DİYARBAKIR", "tr-TR"); // => "diyarbakır"
```Return a string containing a specified number of characters from the right side of a string.
`string_right(string: string | nil, length: number) -> nil | string`
Parameters:
**string** `string | nil` `required`**length** `number` `required`
Examples:
```
string_right("testing", 3); // => "ing"
```
```
string_right(nil, 3); // => nil
```string_starts_with
Determine whether the start of the string matches the prefix.
`string_starts_with(string: string | nil, prefix: string, case_insensitive?: boolean) -> boolean`
Parameters:
**string** `string | nil` `required`**prefix** `string` `required`**case_insensitive** `boolean` `optional`
Examples:
```
string_starts_with("testing", "test"); // => true
```
```
string_starts_with("testing", "nope"); // => false
```string_uppercase
Change the case of the given string to uppercase.
`string_uppercase(string: string | nil, locale?: string) -> nil | string`
Parameters:
**string** `string | nil` `required`**locale** `string` `optional`
Errors:
When the locale is invalid.
Examples:
```
string_uppercase("test"); // => "TEST"
```
```
string_uppercase("diyarbakır", "tr-TR"); // => "DİYARBAKIR"
```strip
Remove a specified character from the beginning and end of the given string. If no character is provided, then whitespace is stripped.
`strip(string: string | nil, content_to_strip?: string) -> nil | string`
Parameters:
**string** `string | nil` `required`**content_to_strip** `string` `optional`
Errors:
When the content to stripe contains more than one character.
Examples:
```
strip("__test_", "_") // => "test"
```
```
strip(" test ") // => "test"
```strip_leading
Remove a specified character from the beginning of the given string. If no character is provided, then whitespace is stripped.
`strip_leading(string: string | nil, content_to_strip?: string) -> nil | string`
Parameters:
**string** `string | nil` `required`**content_to_strip** `string` `optional`
Errors:
When the content to stripe contains more than one character.
Examples:
```
strip_leading("__test_", "_") // => "test_"
```
```
strip_leading(" test ") // => "test "
```strip_trailing
Remove a specified character from the end of the given string. If no character is provided, then whitespace is stripped.
`strip_trailing(string: string | nil, content_to_strip?: string) -> nil | string`
Parameters:
**string** `string | nil` `required`**content_to_strip** `string` `optional`
Errors:
When the content to stripe contains more than one character.
Examples:
```
strip_trailing("__test_", "_") // => "__test"
```
```
strip_trailing(" test ") // => " test"
```Return a substring of the given string, starting at the given index and having the given length. If a negative start index is used, the index is counted from the end of the string rather than the beginning. If the indices are out of the bounds of the string, an empty string is returned.
`substring(string: string | nil, start: number, length: number) -> nil | string`
Parameters:
**string** `string | nil` `required`**start** `number` `required`**length** `number` `required`
Examples:
```
substring("testing", 1, 3); // => "est"
```
```
substring("testing", -3, 2); // => "in"
```substring_after
Given a string and a splitter string, return the substring after the first instance of the splitter string.
`substring_after(string: string | nil, splitter: string, case_insensitive?: boolean) -> nil | string`
Parameters:
**string** `string | nil` `required`**splitter** `string` `required`**case_insensitive** `boolean` `optional`
Example:
substring_after("test_string", "_"); // => "string"substring_before
Given a string and a splitter string, return the substring before the first instance of the splitter string.
`substring_before(string: string | nil, splitter: string, case_insensitive?: boolean) -> nil | string`
Parameters:
**string** `string | nil` `required`**splitter** `string` `required`**case_insensitive** `boolean` `optional`
Example:
substring_before("test_string", "_"); // => "test"Return the sum of the items in an array.
`sum(array: any[] | block, lambda?: (item: any) -> number) -> number`
Parameters:
**array** `any[] | block` `required`**lambda** `(item: any) -> number` `optional`
Errors:
- When the lambda function is provided and its result is not a number.
- When the lambda function is not provided and not all elements in the array are number.
Examples:
```
sum([3, 1, 2]); // => 6
```
```
sum([]); // => 0
```
```
sum([{ b = 111; }, { b = 222; }], x => x.b); // => 333
```Return the first n number of items in an array.
`take(array: any[] | block, count: number) -> unknown[]`
Parameters:
**array** `any[] | block` `required`
**count** `number` `required`
Errors:
When the count argument is not an integer.
Examples:
```
take([3, 1, 2], 2); // => [3, 1]
```
```
take([3, 1, 2], 0); // => []
```
```
take([3, 1, 2], 5); // => [3, 1, 2]
```Return the result of the given lambda where the lambda’s variable is the input value. It allows you to pipeline things that are not functions and, therefore, cannot normally be pipelined.
`then(object: any, lambda: (object: any) -> unknown) -> unknown`
Parameters:
**object** `any` `required`**lambda** `(object: any) -> unknown` `required`
Example:
concat("TEST", "_", "ING") |> then(s => if s == "TESTING" { 111 } else { 222 }); // => 222to_array
Convert an enumerable to an array.
`to_array(enumerable: any[]) -> any[]`
Parameters:
**enumerable** `any[]` `required`
to_ascii
Convert supported non-ascii characters to ascii characters. Unsupported non-ascii characters remain unchanged.
`to_ascii(string: string | nil) -> nil | string`
Parameters:
**string** `string | nil` `required`
Examples:
```
to_ascii("À"); // => "A"
```
```
to_ascii("Æ"); // => "AE"
```
```
to_ascii(""); // => "" unsupported non-ascii
```today
Return the current date/time with time being midnight
`today() -> date`
Example:
today(); // => e.g. 2023-01-20T00:00:00to_signed_overpunch
Convert a number to its signed overpunch representation. An optional format string may be provided to allow for the output to have a particular "shape." The format string syntax is the same as that used by `format_number`. Note: The format string character for a "virtual"--i.e. invisible--decimal point is "V".
`to_signed_overpunch(number: number | nil, format?: string) -> nil | string`
Parameters:
**number** `number | nil` `required`**format** `string` `optional`
Example:
to_signed_overpunch(123.456, "0000V00"); // => 012346Convert an arbitrary value into a string representation of itself.
`to_string(value: any) -> string`
Parameters:
**value** `any` `required`
Example:
to_string(123); // => "123"Given an array and a lambda that will produce a field for any item in the array, return a new array with the unique values.
`unique(array: any[] | block, lambda?: (item: any) -> unknown) -> unknown[]`
Parameters:
**array** `any[] | block` `required`
**lambda** `(item: any) -> unknown` `optional`
Example:
```
foo {
bar {
baz = "EMP001";
hire_date = date(2022, 3, 6);
}
bar {
baz = "EMP002";
hire_date = date(2022, 3, 6);
}
bar {
baz = "EMP002";
hire_date = date(2021, 9, 17);
}
w = unique(foo.bar, item => item.baz); // => ["EMP001", "EMP002"]
x = unique(foo.bar, item => item.hire_date); // => [2022-03-06, 2021-09-17]
y = unique([111, 222, 333, 222]); // => [111, 222, 333]
z = unique([111, test, date(2021, 9, 17), 111]); // => [111, "test", 2021-09-17]
}";
```unique_by
Given an array and a lambda that will produce a key for any item in the array, return a new array with the unique values in the array.
`unique_by(array: any[] | block, create_sort_key: (item: any) -> unknown) -> unknown[]`
Parameters:
**array** `any[] | block` `required`**create_sort_key** `(item: any) -> unknown` `required`
Example:
unique_by([{ x = 1; }, { x = 2; }, { x = 1; }], o => o.x); // => [{ x = 1; }, { x = 2; }]IDL does not have variable except for that in lambda functions. The vars function is used to create named variables and a scope in which they exist.
`vars(variables: any[], lambda: (...variable: any[]) -> unknown) -> unknown`
Parameters:
**variables** `any[]` `required`**lambda** `(...variable: any[]) -> unknown` `required`
Example:
foo {
bar = 3;
baz = vars([test.input, 4], (x, y) => x * y); // => baz will be equal to 12
}Return start of the week based on `day_of_week`.
`week_start(date: date | nil, day_of_week: string) -> nil | date`
Parameters:
**date** `date | nil` `required`**day_of_week** `string` `required`
Example:
week_start(date(2023, 4, 12), "Sunday"); // => 2023-04-09T00:00:00windows
Generate an array of sliding windows of the given size from the input array.
`windows(array: any[] | block, window_size: number) -> unknown[][]`
Parameters:
**array** `any[] | block` `required`**window_size** `number` `required`
Errors:
When the window size is not a positive integer.
Examples:
```
windows([1, 2, 3, 4, 5], 2); // => [[1, 2], [2, 3], [3, 4], [4, 5]]
```
```
windows([], 2); // => []
```year
Return the year part of a date, and return `nil` if the date is `nil`.
`year(date: date | nil) -> nil | number`
Parameters:
**date** `date | nil` `required`
Examples:
```
year(date(2023, 4, 13, 15, 23, 22)); // => 2023
```
```
year(nil); // => nil
```zip
Combine two arrays, pairwise, based on the supplied lambda function. The length of the output array is equal to the length of the shorter input array.
`zip(first_array: any[] | block, second_array: any[] | block, lambda: (item1: any, item2: any) -> unknown) -> unknown[]`
Parameters:
**first_array** `any[] | block` `required`**second_array** `any[] | block` `required`**lambda** `(item1: any, item2: any) -> unknown` `required`
Example:
zip([1, 2, 3], [4, 5, 6], (a, b) => a + b); // => [5, 7, 9]