1 # Library Reference <a id="library-reference"></a>
3 ## Global functions <a id="global-functions"></a>
5 These functions are globally available in [assign/ignore where expressions](03-monitoring-basics.md#using-apply-expressions),
6 [functions](17-language-reference.md#functions), [API filters](12-icinga2-api.md#icinga2-api-filters)
7 and the [Icinga 2 debug console](11-cli-commands.md#cli-command-console).
9 You can use the [Icinga 2 debug console](11-cli-commands.md#cli-command-console)
10 as a sandbox to test these functions before implementing
11 them in your scenarios.
13 ### regex <a id="global-functions-regex"></a>
17 function regex(pattern, value, mode)
19 Returns true if the regular expression `pattern` matches the `value`, false otherwise.
20 The `value` can be of the type [String](#string-type) or [Array](#array-type) (which
21 contains string elements).
23 The `mode` argument is optional and can be either `MatchAll` (in which case all elements
24 for an array have to match) or `MatchAny` (in which case at least one element has to match).
25 The default mode is `MatchAll`.
27 **Tip**: In case you are looking for regular expression tests try [regex101](https://regex101.com).
29 Example for string values:
32 Icinga 2 (version: v2.7.0)
33 <1> => host.vars.os_type = "Linux/Unix"
35 <2> => regex("^Linux", host.vars.os_type)
37 <3> => regex("^Linux$", host.vars.os_type)
40 Example for an array of string values:
43 Icinga 2 (version: v2.7.0)
44 <1> => host.vars.databases = [ "db-prod1", "db-prod2", "db-dev" ]
46 <2> => regex("^db-prod\\d+", host.vars.databases, MatchAny)
48 <3> => regex("^db-prod\\d+", host.vars.databases, MatchAll)
52 ### match <a id="global-functions-match"></a>
56 function match(pattern, text, mode)
58 Returns true if the wildcard (`?*`) `pattern` matches the `value`, false otherwise.
59 The `value` can be of the type [String](#string-type) or [Array](#array-type) (which
60 contains string elements).
62 The `mode` argument is optional and can be either `MatchAll` (in which case all elements
63 for an array have to match) or `MatchAny` (in which case at least one element has to match).
64 The default mode is `MatchAll`.
66 Example for string values:
69 Icinga 2 (version: v2.7.0)
70 <1> => var name = "db-prod-sfo-657"
72 <2> => match("*prod-sfo*", name)
74 <3> => match("*-dev-*", name)
77 Example for an array of string values:
80 Icinga 2 (version: v2.7.0-28)
81 <1> => host.vars.application_types = [ "web-wp", "web-rt", "db-local" ]
83 <2> => match("web-*", host.vars.application_types, MatchAll)
85 <3> => match("web-*", host.vars.application_types, MatchAny)
89 ### cidr_match <a id="global-functions-cidr_match"></a>
93 function cidr_match(pattern, ip, mode)
95 Returns true if the CIDR pattern matches the IP address, false otherwise.
97 IPv4 addresses are converted to IPv4-mapped IPv6 addresses before being
98 matched against the pattern. The `mode` argument is optional and can be
99 either `MatchAll` (in which case all elements for an array have to match) or `MatchAny`
100 (in which case at least one element has to match). The default mode is `MatchAll`.
103 Example for a single IP address:
106 Icinga 2 (version: v2.7.0)
107 <1> => host.address = "192.168.56.101"
109 <2> => cidr_match("192.168.56.0/24", host.address)
111 <3> => cidr_match("192.168.56.0/26", host.address)
114 Example for an array of IP addresses:
117 Icinga 2 (version: v2.7.0)
118 <1> => host.vars.vhost_ips = [ "192.168.56.101", "192.168.56.102", "10.0.10.99" ]
120 <2> => cidr_match("192.168.56.0/24", host.vars.vhost_ips, MatchAll)
122 <3> => cidr_match("192.168.56.0/24", host.vars.vhost_ips, MatchAny)
125 ### range <a id="global-functions-range"></a>
130 function range(start, end)
131 function range(start, end, increment)
133 Returns an array of numbers in the specified range.
134 If you specify one parameter, the first element starts at `0`.
135 The following array numbers are incremented by `1` and stop before
137 If you specify the start and end numbers, the returned array
138 number are incremented by `1`. They start at the specified start
139 number and stop before the end number.
140 Optionally you can specify the incremented step between numbers
146 Icinga 2 (version: v2.7.0)
148 [ 0.000000, 1.000000, 2.000000, 3.000000, 4.000000 ]
150 [ 2.000000, 3.000000 ]
152 [ 2.000000, 4.000000, 6.000000, 8.000000 ]
154 ### len <a id="global-functions-len"></a>
160 Returns the length of the value, i.e. the number of elements for an array
161 or dictionary, or the length of the string in bytes.
163 **Note**: Instead of using this global function you are advised to use the type's
164 prototype method: [Array#len](18-library-reference.md#array-len), [Dictionary#len](18-library-reference.md#dictionary-len) and
165 [String#len](18-library-reference.md#string-len).
170 Icinga 2 (version: v2.7.0)
171 <1> => host.groups = [ "linux-servers", "db-servers" ]
173 <2> => host.groups.len()
175 <3> => host.vars.disks["/"] = {}
177 <4> => host.vars.disks["/var"] = {}
179 <5> => host.vars.disks.len()
181 <6> => host.vars.os_type = "Linux/Unix"
183 <7> => host.vars.os_type.len()
187 ### union <a id="global-functions-union"></a>
191 function union(array, array, ...)
193 Returns an array containing all unique elements from the specified arrays.
198 Icinga 2 (version: v2.7.0)
199 <1> => var dev_notification_groups = [ "devs", "slack" ]
201 <2> => var host_notification_groups = [ "slack", "noc" ]
203 <3> => union(dev_notification_groups, host_notification_groups)
204 [ "devs", "noc", "slack" ]
206 ### intersection <a id="global-functions-intersection"></a>
210 function intersection(array, array, ...)
212 Returns an array containing all unique elements which are common to all
218 Icinga 2 (version: v2.7.0)
219 <1> => var dev_notification_groups = [ "devs", "slack" ]
221 <2> => var host_notification_groups = [ "slack", "noc" ]
223 <3> => intersection(dev_notification_groups, host_notification_groups)
226 ### keys <a id="global-functions-keys"></a>
232 Returns an array containing the dictionary's keys.
234 **Note**: Instead of using this global function you are advised to use the type's
235 prototype method: [Dictionary#keys](18-library-reference.md#dictionary-keys).
240 Icinga 2 (version: v2.7.0)
241 <1> => host.vars.disks["/"] = {}
243 <2> => host.vars.disks["/var"] = {}
245 <3> => host.vars.disks.keys()
248 ### string <a id="global-functions-string"></a>
252 function string(value)
254 Converts the value to a string.
256 **Note**: Instead of using this global function you are advised to use the type's
259 * [Number#to_string](18-library-reference.md#number-to_string)
260 * [Boolean#to_string](18-library-reference.md#boolean-to_string)
261 * [String#to_string](18-library-reference.md#string-to_string)
262 * [Object#to_string](18-library-reference.md#object-to-string) for Array and Dictionary types
263 * [DateTime#to_string](18-library-reference.md#datetime-tostring)
268 Icinga 2 (version: v2.7.0)
271 <2> => false.to_string()
273 <3> => "abc".to_string()
275 <4> => [ "dev", "slack" ].to_string()
276 "[ \"dev\", \"slack\" ]"
277 <5> => { "/" = {}, "/var" = {} }.to_string()
278 "{\n\t\"/\" = {\n\t}\n\t\"/var\" = {\n\t}\n}"
279 <6> => DateTime(2016, 11, 25).to_string()
280 "2016-11-25 00:00:00 +0100"
282 ### number <a id="global-functions-number"></a>
286 function number(value)
288 Converts the value to a number.
293 Icinga 2 (version: v2.7.0)
299 ### bool <a id="global-functions-bool"></a>
305 Converts the value to a bool.
310 Icinga 2 (version: v2.7.0)
316 ### random <a id="global-functions-random"></a>
322 Returns a random value between 0 and RAND\_MAX (as defined in stdlib.h).
325 Icinga 2 (version: v2.7.0)
331 ### log <a id="global-functions-log"></a>
337 Writes a message to the log. Non-string values are converted to a JSON string.
341 function log(severity, facility, value)
343 Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`,
344 `LogInformation`, `LogWarning`, and `LogCritical`.
346 Non-string values are converted to a JSON string.
351 Icinga 2 (version: v2.7.0)
352 <1> => log(LogCritical, "Console", "First line")
353 critical/Console: First line
355 <2> => var groups = [ "devs", "slack" ]
357 <3> => log(LogCritical, "Console", groups)
358 critical/Console: ["devs","slack"]
361 ### typeof <a id="global-functions-typeof"></a>
365 function typeof(value)
367 Returns the [Type](18-library-reference.md#type-type) object for a value.
372 Icinga 2 (version: v2.7.0)
373 <1> => typeof(3) == Number
375 <2> => typeof("str") == String
377 <3> => typeof(true) == Boolean
379 <4> => typeof([ 1, 2, 3]) == Array
381 <5> => typeof({ a = 2, b = 3 }) == Dictionary
384 ### get_time <a id="global-functions-get_time"></a>
390 Returns the current UNIX timestamp as floating point number.
395 Icinga 2 (version: v2.7.0)
401 ### parse_performance_data <a id="global-functions-parse_performance_data"></a>
405 function parse_performance_data(pd)
407 Parses a performance data string and returns an array describing the values.
412 Icinga 2 (version: v2.7.0)
413 <1> => var pd = "'time'=1480074205.197363;;;"
415 <2> => parse_performance_data(pd)
422 type = "PerfdataValue"
424 value = 1480074205.197363
428 ### dirname <a id="global-functions-dirname"></a>
432 function dirname(path)
434 Returns the directory portion of the specified path.
439 Icinga 2 (version: v2.7.0)
440 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
443 "/etc/icinga2/scripts"
445 ### basename <a id="global-functions-basename"></a>
449 function basename(path)
451 Returns the filename portion of the specified path.
456 Icinga 2 (version: v2.7.0)
457 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
459 <2> => basename(path)
460 "xmpp-notification.pl"
462 ### escape_shell_arg <a id="global-functions-escape_shell_arg"></a>
466 function escape_shell_arg(text)
468 Escapes a string for use as a single shell argument.
473 Icinga 2 (version: v2.7.0)
474 <1> => escape_shell_arg("'$host.name$' '$service.name$'")
475 "''\\''$host.name$'\\'' '\\''$service.name$'\\'''"
477 ### escape_shell_cmd <a id="global-functions-escape_shell_cmd"></a>
481 function escape_shell_cmd(text)
483 Escapes shell meta characters in a string.
488 Icinga 2 (version: v2.7.0)
489 <1> => escape_shell_cmd("/bin/echo 'shell test' $ENV")
490 "/bin/echo 'shell test' \\$ENV"
492 ### escape_create_process_arg <a id="global-functions-escape_create_process_arg"></a>
496 function escape_create_process_arg(text)
498 Escapes a string for use as an argument for CreateProcess(). Windows only.
500 ### sleep <a id="global-functions-sleep"></a>
504 function sleep(interval)
506 Sleeps for the specified amount of time (in seconds).
508 ## Object Accessor Functions <a id="object-accessor-functions"></a>
510 These functions can be used to retrieve a reference to another object by name.
512 ### get_check_command <a id="objref-get_check_command"></a>
516 function get_check_command(name);
518 Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists.
520 ### get_event_command <a id="objref-get_event_command"></a>
524 function get_event_command(name);
526 Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists.
528 ### get_notification_command <a id="objref-get_notification_command"></a>
532 function get_notification_command(name);
534 Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists.
536 ### get_host <a id="objref-get_host"></a>
540 function get_host(host_name);
542 Returns the Host object with the specified name, or `null` if no such Host object exists.
545 ### get_service <a id="objref-get_service"></a>
549 function get_service(host_name, service_name);
551 Returns the Service object with the specified name, or `null` if no such Service object exists.
554 ### get_user <a id="objref-get_user"></a>
558 function get_user(name);
560 Returns the User object with the specified name, or `null` if no such User object exists.
562 ### get_host_group <a id="objref-get_host_group"></a>
566 function get_host_group(name);
568 Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists.
571 ### get_service_group <a id="objref-get_service_group"></a>
575 function get_service_group(name);
577 Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists.
579 ### get_user_group <a id="objref-get_user_group"></a>
583 function get_user_group(name);
585 Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists.
588 ### get_time_period <a id="objref-get_time_period"></a>
592 function get_time_period(name);
594 Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists.
597 ### get_object <a id="objref-get_object"></a>
601 function get_object(type, name);
603 Returns the object with the specified type and name, or `null` if no such object exists. `type` must refer
607 ### get_objects <a id="objref-get_objects"></a>
611 function get_objects(type);
613 Returns an array of objects whose type matches the specified type. `type` must refer
617 ## Math object <a id="math-object"></a>
619 The global `Math` object can be used to access a number of mathematical constants
622 ### Math.E <a id="math-e"></a>
626 ### Math.LN2 <a id="math-ln2"></a>
628 Natural logarithm of 2.
630 ### Math.LN10 <a id="math-ln10"></a>
632 Natural logarithm of 10.
634 ### Math.LOG2E <a id="math-log2e"></a>
636 Base 2 logarithm of E.
638 ### Math.PI <a id="math-pi"></a>
640 The mathematical constant Pi.
642 ### Math.SQRT1_2 <a id="math-sqrt1_2"></a>
646 ### Math.SQRT2 <a id="math-sqrt2"></a>
650 ### Math.abs <a id="math-abs"></a>
656 Returns the absolute value of `x`.
658 ### Math.acos <a id="math-acos"></a>
664 Returns the arccosine of `x`.
666 ### Math.asin <a id="math-asin"></a>
672 Returns the arcsine of `x`.
674 ### Math.atan <a id="math-atan"></a>
680 Returns the arctangent of `x`.
682 ### Math.atan2 <a id="math-atan2"></a>
686 function atan2(y, x);
688 Returns the arctangent of the quotient of `y` and `x`.
690 ### Math.ceil <a id="math-ceil"></a>
696 Returns the smallest integer value not less than `x`.
698 ### Math.cos <a id="math-cos"></a>
704 Returns the cosine of `x`.
706 ### Math.exp <a id="math-exp"></a>
712 Returns E raised to the `x`th power.
714 ### Math.floor <a id="math-floor"></a>
720 Returns the largest integer value not greater than `x`.
722 ### Math.isinf <a id="math-isinf"></a>
728 Returns whether `x` is infinite.
730 ### Math.isnan <a id="math-isnan"></a>
736 Returns whether `x` is NaN (not-a-number).
738 ### Math.log <a id="math-log"></a>
744 Returns the natural logarithm of `x`.
746 ### Math.max <a id="math-max"></a>
752 Returns the largest argument. A variable number of arguments can be specified.
753 If no arguments are given, -Infinity is returned.
755 ### Math.min <a id="math-min"></a>
761 Returns the smallest argument. A variable number of arguments can be specified.
762 If no arguments are given, +Infinity is returned.
764 ### Math.pow <a id="math-pow"></a>
770 Returns `x` raised to the `y`th power.
772 ### Math.random <a id="math-random"></a>
778 Returns a pseudo-random number between 0 and 1.
780 ### Math.round <a id="math-round"></a>
786 Returns `x` rounded to the nearest integer value.
788 ### Math.sign <a id="math-sign"></a>
794 Returns -1 if `x` is negative, 1 if `x` is positive
797 ### Math.sin <a id="math-sin"></a>
803 Returns the sine of `x`.
805 ### Math.sqrt <a id="math-sqrt"></a>
811 Returns the square root of `x`.
813 ### Math.tan <a id="math-tan"></a>
819 Returns the tangent of `x`.
821 ## Json object <a id="json-object"></a>
823 The global `Json` object can be used to encode and decode JSON.
825 ### Json.encode <a id="json-encode"></a>
831 Encodes an arbitrary value into JSON.
833 ### Json.decode <a id="json-decode"></a>
839 Decodes a JSON string.
841 ## Number type <a id="number-type"></a>
843 ### Number#to_string <a id="number-to_string"></a>
847 function to_string();
849 The `to_string` method returns a string representation of the number.
854 example.to_string() /* Returns "7" */
856 ## Boolean type <a id="boolean-type"></a>
858 ### Boolean#to_string <a id="boolean-to_string"></a>
862 function to_string();
864 The `to_string` method returns a string representation of the boolean value.
869 example.to_string() /* Returns "true" */
871 ## String type <a id="string-type"></a>
873 ### String#find <a id="string-find"></a>
877 function find(str, start);
879 Returns the zero-based index at which the string `str` was found in the string. If the string
880 was not found, -1 is returned. `start` specifies the zero-based index at which `find` should
881 start looking for the string (defaults to 0 when not specified).
885 "Hello World".find("World") /* Returns 6 */
887 ### String#contains <a id="string-contains"></a>
891 function contains(str);
893 Returns `true` if the string `str` was found in the string. If the string
894 was not found, `false` is returned. Use [find](18-library-reference.md#string-find)
895 for getting the index instead.
899 "Hello World".contains("World") /* Returns true */
901 ### String#len <a id="string-len"></a>
907 Returns the length of the string in bytes. Note that depending on the encoding type of the string
908 this is not necessarily the number of characters.
912 "Hello World".len() /* Returns 11 */
914 ### String#lower <a id="string-lower"></a>
920 Returns a copy of the string with all of its characters converted to lower-case.
924 "Hello World".lower() /* Returns "hello world" */
926 ### String#upper <a id="string-upper"></a>
932 Returns a copy of the string with all of its characters converted to upper-case.
936 "Hello World".upper() /* Returns "HELLO WORLD" */
938 ### String#replace <a id="string-replace"></a>
942 function replace(search, replacement);
944 Returns a copy of the string with all occurences of the string specified in `search` replaced
945 with the string specified in `replacement`.
947 ### String#split <a id="string-split"></a>
951 function split(delimiters);
953 Splits a string into individual parts and returns them as an array. The `delimiters` argument
954 specifies the characters which should be used as delimiters between parts.
958 "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
960 ### String#substr <a id="string-substr"></a>
964 function substr(start, len);
966 Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins.
967 The optional `len` argument specifies the length of the part ("until the end of the string" if omitted).
971 "Hello World".substr(6) /* Returns "World" */
973 ### String#to_string <a id="string-to_string"></a>
977 function to_string();
979 Returns a copy of the string.
981 ### String#reverse <a id="string-reverse"></a>
987 Returns a copy of the string in reverse order.
989 ### String#trim <a id="string-trim"></a>
995 Removes trailing whitespaces and returns the string.
997 ## Object type <a id="object-type"></a>
999 This is the base type for all types in the Icinga application.
1001 ### Object#clone <a id="object-clone"></a>
1007 Returns a copy of the object. Note that for object elements which are
1008 reference values (e.g. objects such as arrays or dictionaries) the entire
1009 object is recursively copied.
1011 ### Object#to_string <a id="object-to-string"></a>
1015 function to_string();
1017 Returns a string representation for the object. Unless overridden this returns a string
1018 of the format "Object of type '<typename>'" where <typename> is the name of the
1023 [ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */
1025 ### Object#type <a id="object-type-field"></a>
1031 Returns the object's type name. This attribute is read-only.
1035 get_host("localhost").type /* Returns "Host" */
1037 ## Type type <a id="type-type"></a>
1039 Inherits methods from the [Object type](18-library-reference.md#object-type).
1041 The `Type` type provides information about the underlying type of an object or scalar value.
1043 All types are registered as global variables. For example, in order to obtain a reference to the `String` type the global variable `String` can be used.
1045 ### Type#base <a id="type-base"></a>
1051 Returns a reference to the type's base type. This attribute is read-only.
1055 Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */
1057 ### Type#name <a id="type-name"></a>
1063 Returns the name of the type.
1065 ### Type#prototype <a id="type-prototype"></a>
1071 Returns the prototype object for the type. When an attribute is accessed on an object that doesn't exist the prototype object is checked to see if an attribute with the requested name exists. If it does, the attribute's value is returned.
1073 The prototype functionality is used to implement methods.
1077 3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */
1079 ## Array type <a id="array-type"></a>
1081 Inherits methods from the [Object type](18-library-reference.md#object-type).
1083 ### Array#add <a id="array-add"></a>
1087 function add(value);
1089 Adds a new value after the last element in the array.
1091 ### Array#clear <a id="array-clear"></a>
1097 Removes all elements from the array.
1099 ### Array#shallow_clone <a id="array-shallow-clone"></a>
1101 function shallow_clone();
1103 Returns a copy of the array. Note that for elements which are reference values (e.g. objects such
1104 as arrays and dictionaries) only the references are copied.
1106 ### Array#contains <a id="array-contains"></a>
1110 function contains(value);
1112 Returns true if the array contains the specified value, false otherwise.
1114 ### Array#len <a id="array-len"></a>
1120 Returns the number of elements contained in the array.
1122 ### Array#remove <a id="array-remove"></a>
1126 function remove(index);
1128 Removes the element at the specified zero-based index.
1130 ### Array#set <a id="array-set"></a>
1134 function set(index, value);
1136 Sets the element at the zero-based index to the specified value. The `index` must refer to an element
1137 which already exists in the array.
1139 ### Array#get <a id="array-get"></a>
1143 function get(index);
1145 Retrieves the element at the specified zero-based index.
1147 ### Array#sort <a id="array-sort"></a>
1151 function sort(less_cmp);
1153 Returns a copy of the array where all items are sorted. The items are
1154 compared using the `<` (less-than) operator. A custom comparator function
1155 can be specified with the `less_cmp` argument.
1157 ### Array#join <a id="array-join"></a>
1161 function join(separator);
1163 Joins all elements of the array using the specified separator.
1165 ### Array#reverse <a id="array-reverse"></a>
1171 Returns a new array with all elements of the current array in reverse order.
1173 ### Array#map <a id="array-map"></a>
1179 Calls `func(element)` for each of the elements in the array and returns
1180 a new array containing the return values of these function calls.
1182 ### Array#reduce <a id="array-reduce"></a>
1186 function reduce(func);
1188 Reduces the elements of the array into a single value by calling the provided
1189 function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array
1190 or results from previous function calls.
1192 ### Array#filter <a id="array-filter"></a>
1196 function filter(func);
1198 Returns a copy of the array containing only the elements for which `func(element)`
1201 ### Array#any <a id="array-any"></a>
1207 Returns true if the array contains at least one element for which `func(element)`
1208 is true, false otherwise.
1210 ### Array#all <a id="array-all"></a>
1216 Returns true if the array contains only elements for which `func(element)`
1217 is true, false otherwise.
1219 ### Array#unique <a id="array-unique"></a>
1225 Returns a copy of the array with all duplicate elements removed. The original order
1226 of the array is not preserved.
1228 ## Dictionary type <a id="dictionary-type"></a>
1230 Inherits methods from the [Object type](18-library-reference.md#object-type).
1232 ### Dictionary#shallow_clone <a id="dictionary-shallow-clone"></a>
1236 function shallow_clone();
1238 Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such
1239 as arrays and dictionaries) only the references are copied.
1241 ### Dictionary#contains <a id="dictionary-contains"></a>
1245 function contains(key);
1247 Returns true if a dictionary item with the specified `key` exists, false otherwise.
1249 ### Dictionary#len <a id="dictionary-len"></a>
1255 Returns the number of items contained in the dictionary.
1257 ### Dictionary#remove <a id="dictionary-remove"></a>
1261 function remove(key);
1263 Removes the item with the specified `key`. Trying to remove an item which does not exist
1266 ### Dictionary#set <a id="dictionary-set"></a>
1270 function set(key, value);
1272 Creates or updates an item with the specified `key` and `value`.
1274 ### Dictionary#get <a id="dictionary-get"></a>
1280 Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist
1283 ### Dictionary#keys <a id="dictionary-keys"></a>
1289 Returns a list of keys for all items that are currently in the dictionary.
1291 ### Dictionary#values <a id="dictionary-values"></a>
1297 Returns a list of values for all items that are currently in the dictionary.
1299 ## Function type <a id="scriptfunction-type"></a>
1301 Inherits methods from the [Object type](18-library-reference.md#object-type).
1303 ### Function#call <a id="scriptfunction-call"></a>
1307 function call(thisArg, ...);
1309 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1310 scope for the function. All other arguments are passed directly to the function.
1314 function set_x(val) {
1320 set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
1322 ### Function#callv <a id="scriptfunction-callv"></a>
1326 function callv(thisArg, args);
1328 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1329 scope for the function. The items in the `args` array are passed to the function as individual arguments.
1333 function set_x(val) {
1341 set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */
1343 ## DateTime type <a id="datetime-type"></a>
1345 Inherits methods from the [Object type](18-library-reference.md#object-type).
1347 ### DateTime constructor <a id="datetime-ctor"></a>
1352 function DateTime(unixTimestamp)
1353 function DateTime(year, month, day)
1354 function DateTime(year, month, day, hours, minutes, seconds)
1356 Constructs a new DateTime object. When no arguments are specified for the constructor a new
1357 DateTime object representing the current time is created.
1361 var d1 = DateTime() /* current time */
1362 var d2 = DateTime(2016, 5, 21) /* midnight April 21st, 2016 (local time) */
1364 ### DateTime arithmetic <a id="datetime-arithmetic"></a>
1366 Subtracting two DateTime objects yields the interval between them, in seconds.
1370 var delta = DateTime() - DateTime(2016, 5, 21) /* seconds since midnight April 21st, 2016 */
1372 Subtracting a number from a DateTime object yields a new DateTime object that is further in the past:
1376 var dt = DateTime() - 2 * 60 * 60 /* Current time minus 2 hours */
1378 Adding a number to a DateTime object yields a new DateTime object that is in the future:
1382 var dt = DateTime() + 24 * 60 60 /* Current time plus 24 hours */
1384 ### DateTime#format <a id="datetime-format"></a>
1388 function format(fmt)
1390 Returns a string representation for the DateTime object using the specified format string.
1391 The format string may contain format conversion placeholders as specified in strftime(3).
1395 var s = DateTime(2016, 4, 21).format("%A") /* Sets s to "Thursday". */
1397 ### DateTime#to_string <a id="datetime-tostring"></a>
1401 function to_string()
1403 Returns a string representation for the DateTime object. Uses a suitable default format.
1407 var s = DateTime(2016, 4, 21).to_string() /* Sets s to "2016-04-21 00:00:00 +0200". */