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](18-library-reference.md#string-type) or [Array](18-library-reference.md#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](18-library-reference.md#string-type) or [Array](18-library-reference.md#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 ### path\_exists <a id="global-functions-path-exists"></a>
466 function path_exists(path)
468 Returns true if the specified path exists, false otherwise.
473 Icinga 2 (version: v2.7.0)
474 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
476 <2> => path_exists(path)
479 ### glob <a id="global-functions-glob"></a>
483 function glob(pathSpec, type)
485 Returns an array containing all paths which match the
488 The `type` argument is optional and specifies which types
489 of paths are matched. This can be a combination of the `GlobFile`
490 and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
493 Icinga 2 (version: v2.7.0)
494 <1> => var pathSpec = "/etc/icinga2/conf.d/*.conf"
496 <2> => glob(pathSpec)
497 [ "/etc/icinga2/conf.d/app.conf", "/etc/icinga2/conf.d/commands.conf", ... ]
499 ### glob\_recursive <a id="global-functions-glob-recursive"></a>
503 function glob_recursive(path, pattern, type)
505 Recursively descends into the specified directory and returns an array containing
506 all paths which match the `pattern` argument.
508 The `type` argument is optional and specifies which types
509 of paths are matched. This can be a combination of the `GlobFile`
510 and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
513 Icinga 2 (version: v2.7.0)
514 <1> => var path = "/etc/icinga2/zones.d/"
516 <2> => var pattern = "*.conf"
518 <3> => glob_recursive(path, pattern)
519 [ "/etc/icinga2/zones.d/global-templates/templates.conf", "/etc/icinga2/zones.d/master/hosts.conf", ... ]
521 ### escape_shell_arg <a id="global-functions-escape_shell_arg"></a>
525 function escape_shell_arg(text)
527 Escapes a string for use as a single shell argument.
532 Icinga 2 (version: v2.7.0)
533 <1> => escape_shell_arg("'$host.name$' '$service.name$'")
534 "''\\''$host.name$'\\'' '\\''$service.name$'\\'''"
536 ### escape_shell_cmd <a id="global-functions-escape_shell_cmd"></a>
540 function escape_shell_cmd(text)
542 Escapes shell meta characters in a string.
547 Icinga 2 (version: v2.7.0)
548 <1> => escape_shell_cmd("/bin/echo 'shell test' $ENV")
549 "/bin/echo 'shell test' \\$ENV"
551 ### escape_create_process_arg <a id="global-functions-escape_create_process_arg"></a>
555 function escape_create_process_arg(text)
557 Escapes a string for use as an argument for CreateProcess(). Windows only.
559 ### sleep <a id="global-functions-sleep"></a>
563 function sleep(interval)
565 Sleeps for the specified amount of time (in seconds).
567 ## Object Accessor Functions <a id="object-accessor-functions"></a>
569 These functions can be used to retrieve a reference to another object by name.
571 ### get_check_command <a id="objref-get_check_command"></a>
575 function get_check_command(name);
577 Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists.
579 ### get_event_command <a id="objref-get_event_command"></a>
583 function get_event_command(name);
585 Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists.
587 ### get_notification_command <a id="objref-get_notification_command"></a>
591 function get_notification_command(name);
593 Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists.
595 ### get_host <a id="objref-get_host"></a>
599 function get_host(host_name);
601 Returns the Host object with the specified name, or `null` if no such Host object exists.
604 ### get_service <a id="objref-get_service"></a>
608 function get_service(host_name, service_name);
609 function get_service(host, service_name);
611 Returns the Service object with the specified host name or object and service name pair,
612 or `null` if no such Service object exists.
614 Example in the [debug console](11-cli-commands.md#cli-command-console)
615 which fetches the `disk` service object from the current Icinga 2 node:
618 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
619 Icinga 2 (version: v2.7.0)
621 <1> => get_service(NodeName, "disk")
622 <2> => get_service(NodeName, "disk").__name
623 "icinga2-master1.localdomain!disk"
625 <3> => get_service(get_host(NodeName), "disk").__name
626 "icinga2-master1.localdomain!disk"
629 ### get_services <a id="objref-get_services"></a>
633 function get_services(host_name);
634 function get_services(host);
636 Returns an [array](17-language-reference.md#array) of service objects for the specified host name or object,
637 or `null` if no such host object exists.
639 Example in the [debug console](11-cli-commands.md#cli-command-console)
640 which fetches all service objects from the current Icinga 2 node:
643 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
644 Icinga 2 (version: v2.7.0)
646 <1> => get_services(NodeName).map(s => s.name)
647 [ "disk", "disk /", "http", "icinga", "load", "ping4", "ping6", "procs", "ssh", "users" ]
650 Note: [map](18-library-reference.md#array-map) takes a [lambda function](17-language-reference.md#lambdas) as argument. In this example
651 we only want to collect and print the `name` attribute with `s => s.name`.
653 This works in a similar fashion for a host object where you can extract all service states
654 in using the [map](18-library-reference.md#array-map) functionality:
657 <2> => get_services(get_host(NodeName)).map(s => s.state)
658 [ 2.000000, 2.000000, 2.000000, 0.000000, 0.000000, 0.000000, 2.000000, 0.000000, 0.000000, 1.000000, 0.000000, 0.000000 ]
661 ### get_user <a id="objref-get_user"></a>
665 function get_user(name);
667 Returns the User object with the specified name, or `null` if no such User object exists.
669 ### get_host_group <a id="objref-get_host_group"></a>
673 function get_host_group(name);
675 Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists.
678 ### get_service_group <a id="objref-get_service_group"></a>
682 function get_service_group(name);
684 Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists.
686 ### get_user_group <a id="objref-get_user_group"></a>
690 function get_user_group(name);
692 Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists.
695 ### get_time_period <a id="objref-get_time_period"></a>
699 function get_time_period(name);
701 Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists.
704 ### get_object <a id="objref-get_object"></a>
708 function get_object(type, name);
710 Returns the object with the specified type and name, or `null` if no such object exists. `type` must refer
714 ### get_objects <a id="objref-get_objects"></a>
718 function get_objects(type);
720 Returns an array of objects whose type matches the specified type. `type` must refer
724 ## Math object <a id="math-object"></a>
726 The global `Math` object can be used to access a number of mathematical constants
729 ### Math.E <a id="math-e"></a>
733 ### Math.LN2 <a id="math-ln2"></a>
735 Natural logarithm of 2.
737 ### Math.LN10 <a id="math-ln10"></a>
739 Natural logarithm of 10.
741 ### Math.LOG2E <a id="math-log2e"></a>
743 Base 2 logarithm of E.
745 ### Math.PI <a id="math-pi"></a>
747 The mathematical constant Pi.
749 ### Math.SQRT1_2 <a id="math-sqrt1_2"></a>
753 ### Math.SQRT2 <a id="math-sqrt2"></a>
757 ### Math.abs <a id="math-abs"></a>
763 Returns the absolute value of `x`.
765 ### Math.acos <a id="math-acos"></a>
771 Returns the arccosine of `x`.
773 ### Math.asin <a id="math-asin"></a>
779 Returns the arcsine of `x`.
781 ### Math.atan <a id="math-atan"></a>
787 Returns the arctangent of `x`.
789 ### Math.atan2 <a id="math-atan2"></a>
793 function atan2(y, x);
795 Returns the arctangent of the quotient of `y` and `x`.
797 ### Math.ceil <a id="math-ceil"></a>
803 Returns the smallest integer value not less than `x`.
805 ### Math.cos <a id="math-cos"></a>
811 Returns the cosine of `x`.
813 ### Math.exp <a id="math-exp"></a>
819 Returns E raised to the `x`th power.
821 ### Math.floor <a id="math-floor"></a>
827 Returns the largest integer value not greater than `x`.
829 ### Math.isinf <a id="math-isinf"></a>
835 Returns whether `x` is infinite.
837 ### Math.isnan <a id="math-isnan"></a>
843 Returns whether `x` is NaN (not-a-number).
845 ### Math.log <a id="math-log"></a>
851 Returns the natural logarithm of `x`.
853 ### Math.max <a id="math-max"></a>
859 Returns the largest argument. A variable number of arguments can be specified.
860 If no arguments are given, -Infinity is returned.
862 ### Math.min <a id="math-min"></a>
868 Returns the smallest argument. A variable number of arguments can be specified.
869 If no arguments are given, +Infinity is returned.
871 ### Math.pow <a id="math-pow"></a>
877 Returns `x` raised to the `y`th power.
879 ### Math.random <a id="math-random"></a>
885 Returns a pseudo-random number between 0 and 1.
887 ### Math.round <a id="math-round"></a>
893 Returns `x` rounded to the nearest integer value.
895 ### Math.sign <a id="math-sign"></a>
901 Returns -1 if `x` is negative, 1 if `x` is positive
904 ### Math.sin <a id="math-sin"></a>
910 Returns the sine of `x`.
912 ### Math.sqrt <a id="math-sqrt"></a>
918 Returns the square root of `x`.
920 ### Math.tan <a id="math-tan"></a>
926 Returns the tangent of `x`.
928 ## Json object <a id="json-object"></a>
930 The global `Json` object can be used to encode and decode JSON.
932 ### Json.encode <a id="json-encode"></a>
938 Encodes an arbitrary value into JSON.
940 ### Json.decode <a id="json-decode"></a>
946 Decodes a JSON string.
948 ## Number type <a id="number-type"></a>
950 ### Number#to_string <a id="number-to_string"></a>
954 function to_string();
956 The `to_string` method returns a string representation of the number.
961 example.to_string() /* Returns "7" */
963 ## Boolean type <a id="boolean-type"></a>
965 ### Boolean#to_string <a id="boolean-to_string"></a>
969 function to_string();
971 The `to_string` method returns a string representation of the boolean value.
976 example.to_string() /* Returns "true" */
978 ## String type <a id="string-type"></a>
980 ### String#find <a id="string-find"></a>
984 function find(str, start);
986 Returns the zero-based index at which the string `str` was found in the string. If the string
987 was not found, -1 is returned. `start` specifies the zero-based index at which `find` should
988 start looking for the string (defaults to 0 when not specified).
992 "Hello World".find("World") /* Returns 6 */
994 ### String#contains <a id="string-contains"></a>
998 function contains(str);
1000 Returns `true` if the string `str` was found in the string. If the string
1001 was not found, `false` is returned. Use [find](18-library-reference.md#string-find)
1002 for getting the index instead.
1006 "Hello World".contains("World") /* Returns true */
1008 ### String#len <a id="string-len"></a>
1014 Returns the length of the string in bytes. Note that depending on the encoding type of the string
1015 this is not necessarily the number of characters.
1019 "Hello World".len() /* Returns 11 */
1021 ### String#lower <a id="string-lower"></a>
1027 Returns a copy of the string with all of its characters converted to lower-case.
1031 "Hello World".lower() /* Returns "hello world" */
1033 ### String#upper <a id="string-upper"></a>
1039 Returns a copy of the string with all of its characters converted to upper-case.
1043 "Hello World".upper() /* Returns "HELLO WORLD" */
1045 ### String#replace <a id="string-replace"></a>
1049 function replace(search, replacement);
1051 Returns a copy of the string with all occurences of the string specified in `search` replaced
1052 with the string specified in `replacement`.
1054 ### String#split <a id="string-split"></a>
1058 function split(delimiters);
1060 Splits a string into individual parts and returns them as an array. The `delimiters` argument
1061 specifies the characters which should be used as delimiters between parts.
1065 "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
1067 ### String#substr <a id="string-substr"></a>
1071 function substr(start, len);
1073 Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins.
1074 The optional `len` argument specifies the length of the part ("until the end of the string" if omitted).
1078 "Hello World".substr(6) /* Returns "World" */
1080 ### String#to_string <a id="string-to_string"></a>
1084 function to_string();
1086 Returns a copy of the string.
1088 ### String#reverse <a id="string-reverse"></a>
1094 Returns a copy of the string in reverse order.
1096 ### String#trim <a id="string-trim"></a>
1102 Removes trailing whitespaces and returns the string.
1104 ## Object type <a id="object-type"></a>
1106 This is the base type for all types in the Icinga application.
1108 ### Object#clone <a id="object-clone"></a>
1114 Returns a copy of the object. Note that for object elements which are
1115 reference values (e.g. objects such as arrays or dictionaries) the entire
1116 object is recursively copied.
1118 ### Object#to_string <a id="object-to-string"></a>
1122 function to_string();
1124 Returns a string representation for the object. Unless overridden this returns a string
1125 of the format "Object of type '<typename>'" where <typename> is the name of the
1130 [ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */
1132 ### Object#type <a id="object-type-field"></a>
1138 Returns the object's type name. This attribute is read-only.
1142 get_host("localhost").type /* Returns "Host" */
1144 ## Type type <a id="type-type"></a>
1146 Inherits methods from the [Object type](18-library-reference.md#object-type).
1148 The `Type` type provides information about the underlying type of an object or scalar value.
1150 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.
1152 ### Type#base <a id="type-base"></a>
1158 Returns a reference to the type's base type. This attribute is read-only.
1162 Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */
1164 ### Type#name <a id="type-name"></a>
1170 Returns the name of the type.
1172 ### Type#prototype <a id="type-prototype"></a>
1178 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.
1180 The prototype functionality is used to implement methods.
1184 3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */
1186 ## Array type <a id="array-type"></a>
1188 Inherits methods from the [Object type](18-library-reference.md#object-type).
1190 ### Array#add <a id="array-add"></a>
1194 function add(value);
1196 Adds a new value after the last element in the array.
1198 ### Array#clear <a id="array-clear"></a>
1204 Removes all elements from the array.
1206 ### Array#shallow_clone <a id="array-shallow-clone"></a>
1208 function shallow_clone();
1210 Returns a copy of the array. Note that for elements which are reference values (e.g. objects such
1211 as arrays and dictionaries) only the references are copied.
1213 ### Array#contains <a id="array-contains"></a>
1217 function contains(value);
1219 Returns true if the array contains the specified value, false otherwise.
1221 ### Array#len <a id="array-len"></a>
1227 Returns the number of elements contained in the array.
1229 ### Array#remove <a id="array-remove"></a>
1233 function remove(index);
1235 Removes the element at the specified zero-based index.
1237 ### Array#set <a id="array-set"></a>
1241 function set(index, value);
1243 Sets the element at the zero-based index to the specified value. The `index` must refer to an element
1244 which already exists in the array.
1246 ### Array#get <a id="array-get"></a>
1250 function get(index);
1252 Retrieves the element at the specified zero-based index.
1254 ### Array#sort <a id="array-sort"></a>
1258 function sort(less_cmp);
1260 Returns a copy of the array where all items are sorted. The items are
1261 compared using the `<` (less-than) operator. A custom comparator function
1262 can be specified with the `less_cmp` argument.
1264 ### Array#join <a id="array-join"></a>
1268 function join(separator);
1270 Joins all elements of the array using the specified separator.
1272 ### Array#reverse <a id="array-reverse"></a>
1278 Returns a new array with all elements of the current array in reverse order.
1280 ### Array#map <a id="array-map"></a>
1286 Calls `func(element)` for each of the elements in the array and returns
1287 a new array containing the return values of these function calls.
1289 ### Array#reduce <a id="array-reduce"></a>
1293 function reduce(func);
1295 Reduces the elements of the array into a single value by calling the provided
1296 function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array
1297 or results from previous function calls.
1299 ### Array#filter <a id="array-filter"></a>
1303 function filter(func);
1305 Returns a copy of the array containing only the elements for which `func(element)`
1308 ### Array#any <a id="array-any"></a>
1314 Returns true if the array contains at least one element for which `func(element)`
1315 is true, false otherwise.
1317 ### Array#all <a id="array-all"></a>
1323 Returns true if the array contains only elements for which `func(element)`
1324 is true, false otherwise.
1326 ### Array#unique <a id="array-unique"></a>
1332 Returns a copy of the array with all duplicate elements removed. The original order
1333 of the array is not preserved.
1335 ## Dictionary type <a id="dictionary-type"></a>
1337 Inherits methods from the [Object type](18-library-reference.md#object-type).
1339 ### Dictionary#shallow_clone <a id="dictionary-shallow-clone"></a>
1343 function shallow_clone();
1345 Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such
1346 as arrays and dictionaries) only the references are copied.
1348 ### Dictionary#contains <a id="dictionary-contains"></a>
1352 function contains(key);
1354 Returns true if a dictionary item with the specified `key` exists, false otherwise.
1356 ### Dictionary#len <a id="dictionary-len"></a>
1362 Returns the number of items contained in the dictionary.
1364 ### Dictionary#remove <a id="dictionary-remove"></a>
1368 function remove(key);
1370 Removes the item with the specified `key`. Trying to remove an item which does not exist
1373 ### Dictionary#set <a id="dictionary-set"></a>
1377 function set(key, value);
1379 Creates or updates an item with the specified `key` and `value`.
1381 ### Dictionary#get <a id="dictionary-get"></a>
1387 Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist
1390 ### Dictionary#keys <a id="dictionary-keys"></a>
1396 Returns a list of keys for all items that are currently in the dictionary.
1398 ### Dictionary#values <a id="dictionary-values"></a>
1404 Returns a list of values for all items that are currently in the dictionary.
1406 ## Function type <a id="scriptfunction-type"></a>
1408 Inherits methods from the [Object type](18-library-reference.md#object-type).
1410 ### Function#call <a id="scriptfunction-call"></a>
1414 function call(thisArg, ...);
1416 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1417 scope for the function. All other arguments are passed directly to the function.
1421 function set_x(val) {
1427 set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
1429 ### Function#callv <a id="scriptfunction-callv"></a>
1433 function callv(thisArg, args);
1435 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1436 scope for the function. The items in the `args` array are passed to the function as individual arguments.
1440 function set_x(val) {
1448 set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */
1450 ## DateTime type <a id="datetime-type"></a>
1452 Inherits methods from the [Object type](18-library-reference.md#object-type).
1454 ### DateTime constructor <a id="datetime-ctor"></a>
1459 function DateTime(unixTimestamp)
1460 function DateTime(year, month, day)
1461 function DateTime(year, month, day, hours, minutes, seconds)
1463 Constructs a new DateTime object. When no arguments are specified for the constructor a new
1464 DateTime object representing the current time is created.
1468 var d1 = DateTime() /* current time */
1469 var d2 = DateTime(2016, 5, 21) /* midnight April 21st, 2016 (local time) */
1471 ### DateTime arithmetic <a id="datetime-arithmetic"></a>
1473 Subtracting two DateTime objects yields the interval between them, in seconds.
1477 var delta = DateTime() - DateTime(2016, 5, 21) /* seconds since midnight April 21st, 2016 */
1479 Subtracting a number from a DateTime object yields a new DateTime object that is further in the past:
1483 var dt = DateTime() - 2 * 60 * 60 /* Current time minus 2 hours */
1485 Adding a number to a DateTime object yields a new DateTime object that is in the future:
1489 var dt = DateTime() + 24 * 60 60 /* Current time plus 24 hours */
1491 ### DateTime#format <a id="datetime-format"></a>
1495 function format(fmt)
1497 Returns a string representation for the DateTime object using the specified format string.
1498 The format string may contain format conversion placeholders as specified in strftime(3).
1502 var s = DateTime(2016, 4, 21).format("%A") /* Sets s to "Thursday". */
1504 ### DateTime#to_string <a id="datetime-tostring"></a>
1508 function to_string()
1510 Returns a string representation for the DateTime object. Uses a suitable default format.
1514 var s = DateTime(2016, 4, 21).to_string() /* Sets s to "2016-04-21 00:00:00 +0200". */