1 # <a id="library-reference"></a> Library Reference
3 ## <a id="global-functions"></a> Global functions
5 These functions are globally available in [assign/ignore where expressions](3-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 console](11-cli-commands.md#cli-command-console).
9 You can use the [Icinga 2 console](11-cli-commands.md#cli-command-console)
10 as a sandbox to test these functions before implementing
11 them in your scenarios.
13 ### <a id="global-functions-regex"></a> regex
17 function regex(pattern, text)
19 Returns true if the regular expression matches the text, false otherwise.
20 **Tip**: In case you are looking for regular expression tests try [regex101](https://regex101.com).
25 Icinga 2 (version: v2.6.0)
26 <1> => host.vars.os_type = "Linux/Unix"
28 <2> => regex("^Linux", host.vars.os_type)
30 <3> => regex("^Linux$", host.vars.os_type)
33 ### <a id="global-functions-match"></a> match
37 function match(pattern, text)
39 Returns true if the wildcard (`?*`) pattern matches the text, false otherwise.
44 Icinga 2 (version: v2.6.0)
45 <1> => host.display_name = "NUE-DB-PROD-586"
47 <2> => match("NUE-*", host.display_name)
49 <3> => match("*NUE-*", host.display_name)
51 <4> => match("NUE-*-DEV-*", host.display_name)
54 ### <a id="global-functions-cidr_match"></a> cidr_match
58 function cidr_match(pattern, ip)
60 Returns true if the CIDR pattern matches the IP address, false otherwise.
61 IPv4 addresses are converted to IPv4-mapped IPv6 addresses before being
62 matched against the pattern.
67 Icinga 2 (version: v2.6.0)
68 <1> => host.address = "192.168.56.101"
70 <2> => cidr_match("192.168.56.0/24", host.address)
72 <3> => cidr_match("192.168.56.0/26", host.address)
75 ### <a id="global-functions-range"></a> range
80 function range(start, end)
81 function range(start, end, increment)
83 Returns an array of numbers in the specified range.
84 If you specify one parameter, the first element starts at `0`.
85 The following array numbers are incremented by `1` and stop before
87 If you specify the start and end numbers, the returned array
88 number are incremented by `1`. They start at the specified start
89 number and stop before the end number.
90 Optionally you can specify the incremented step between numbers
96 Icinga 2 (version: v2.6.0)
98 [ 0.000000, 1.000000, 2.000000, 3.000000, 4.000000 ]
100 [ 2.000000, 3.000000 ]
102 [ 2.000000, 4.000000, 6.000000, 8.000000 ]
104 ### <a id="global-functions-len"></a> len
110 Returns the length of the value, i.e. the number of elements for an array
111 or dictionary, or the length of the string in bytes.
113 **Note**: Instead of using this global function you are advised to use the type's
114 prototype method: [Array#len](18-library-reference.md#array-len), [Dictionary#len](18-library-reference.md#dictionary-len) and
115 [String#len](18-library-reference.md#string-len).
120 Icinga 2 (version: v2.6.0)
121 <1> => host.groups = [ "linux-servers", "db-servers" ]
123 <2> => host.groups.len()
125 <3> => host.vars.disks["/"] = {}
127 <4> => host.vars.disks["/var"] = {}
129 <5> => host.vars.disks.len()
131 <6> => host.vars.os_type = "Linux/Unix"
133 <7> => host.vars.os_type.len()
137 ### <a id="global-functions-union"></a> union
141 function union(array, array, ...)
143 Returns an array containing all unique elements from the specified arrays.
148 Icinga 2 (version: v2.6.0)
149 <1> => var dev_notification_groups = [ "devs", "slack" ]
151 <2> => var host_notification_groups = [ "slack", "noc" ]
153 <3> => union(dev_notification_groups, host_notification_groups)
154 [ "devs", "noc", "slack" ]
156 ### <a id="global-functions-intersection"></a> intersection
160 function intersection(array, array, ...)
162 Returns an array containing all unique elements which are common to all
168 Icinga 2 (version: v2.6.0)
169 <1> => var dev_notification_groups = [ "devs", "slack" ]
171 <2> => var host_notification_groups = [ "slack", "noc" ]
173 <3> => intersection(dev_notification_groups, host_notification_groups)
176 ### <a id="global-functions-keys"></a> keys
182 Returns an array containing the dictionary's keys.
184 **Note**: Instead of using this global function you are advised to use the type's
185 prototype method: [Dictionary#keys](18-library-reference.md#dictionary-keys).
190 Icinga 2 (version: v2.6.0)
191 <1> => host.vars.disks["/"] = {}
193 <2> => host.vars.disks["/var"] = {}
195 <3> => host.vars.disks.keys()
198 ### <a id="global-functions-string"></a> string
202 function string(value)
204 Converts the value to a string.
206 **Note**: Instead of using this global function you are advised to use the type's
209 * [Number#to_string](18-library-reference.md#number-to_string)
210 * [Boolean#to_string](18-library-reference.md#boolean-to_string)
211 * [String#to_string](18-library-reference.md#string-to_string)
212 * [Object#to_string](18-library-reference.md#object-to-string) for Array and Dictionary types
213 * [DateTime#to_string](18-library-reference.md#datetime-tostring)
218 Icinga 2 (version: v2.6.0)
221 <2> => false.to_string()
223 <3> => "abc".to_string()
225 <4> => [ "dev", "slack" ].to_string()
226 "[ \"dev\", \"slack\" ]"
227 <5> => { "/" = {}, "/var" = {} }.to_string()
228 "{\n\t\"/\" = {\n\t}\n\t\"/var\" = {\n\t}\n}"
229 <6> => DateTime(2016, 11, 25).to_string()
230 "2016-11-25 00:00:00 +0100"
232 ### <a id="global-functions-number"></a> number
236 function number(value)
238 Converts the value to a number.
243 Icinga 2 (version: v2.6.0)
249 ### <a id="global-functions-bool"></a> bool
255 Converts the value to a bool.
260 Icinga 2 (version: v2.6.0)
266 ### <a id="global-functions-random"></a> random
272 Returns a random value between 0 and RAND\_MAX (as defined in stdlib.h).
275 Icinga 2 (version: v2.6.0)
281 ### <a id="global-functions-log"></a> log
287 Writes a message to the log. Non-string values are converted to a JSON string.
291 function log(severity, facility, value)
293 Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`,
294 `LogInformation`, `LogWarning`, and `LogCritical`.
296 Non-string values are converted to a JSON string.
301 Icinga 2 (version: v2.6.0)
302 <1> => log(LogCritical, "Console", "First line")
303 critical/Console: First line
305 <2> => var groups = [ "devs", "slack" ]
307 <3> => log(LogCritical, "Console", groups)
308 critical/Console: ["devs","slack"]
311 ### <a id="global-functions-typeof"></a> typeof
315 function typeof(value)
317 Returns the [Type](18-library-reference.md#type-type) object for a value.
322 Icinga 2 (version: v2.6.0)
323 <1> => typeof(3) == Number
325 <2> => typeof("str") == String
327 <3> => typeof(true) == Boolean
329 <4> => typeof([ 1, 2, 3]) == Array
331 <5> => typeof({ a = 2, b = 3}) == Dictionary
333 ### <a id="global-functions-get_time"></a> get_time
339 Returns the current UNIX timestamp as floating point number.
344 Icinga 2 (version: v2.6.0)
350 ### <a id="global-functions-parse_performance_data"></a> parse_performance_data
354 function parse_performance_data(pd)
356 Parses a performance data string and returns an array describing the values.
361 Icinga 2 (version: v2.6.0)
362 <1> => var pd = "'time'=1480074205.197363;;;"
364 <2> => parse_performance_data(pd)
371 type = "PerfdataValue"
373 value = 1480074205.197363
377 ### <a id="global-functions-dirname"></a> dirname
381 function dirname(path)
383 Returns the directory portion of the specified path.
388 Icinga 2 (version: v2.6.0)
389 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
392 "/etc/icinga2/scripts"
394 ### <a id="global-functions-basename"></a> basename
398 function basename(path)
400 Returns the filename portion of the specified path.
405 Icinga 2 (version: v2.6.0)
406 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
408 <2> => basename(path)
409 "xmpp-notification.pl"
411 ### <a id="global-functions-escape_shell_arg"></a> escape_shell_arg
415 function escape_shell_arg(text)
417 Escapes a string for use as a single shell argument.
422 Icinga 2 (version: v2.6.0)
423 <1> => escape_shell_arg("'$host.name$' '$service.name$'")
424 "''\\''$host.name$'\\'' '\\''$service.name$'\\'''"
426 ### <a id="global-functions-escape_shell_cmd"></a> escape_shell_cmd
430 function escape_shell_cmd(text)
432 Escapes shell meta characters in a string.
437 Icinga 2 (version: v2.6.0)
438 <1> => escape_shell_cmd("/bin/echo 'shell test' $ENV")
439 "/bin/echo 'shell test' \\$ENV"
441 ### <a id="global-functions-escape_create_process_arg"></a> escape_create_process_arg
445 function escape_create_process_arg(text)
447 Escapes a string for use as an argument for CreateProcess(). Windows only.
449 ### <a id="global-functions-sleep"></a> sleep
453 function sleep(interval)
455 Sleeps for the specified amount of time (in seconds).
457 ## <a id="object-accessor-functions"></a> Object Accessor Functions
459 These functions can be used to retrieve a reference to another object by name.
461 ### <a id="objref-get_check_command"></a> get_check_command
465 function get_check_command(name);
467 Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists.
469 ### <a id="objref-get_event_command"></a> get_event_command
473 function get_event_command(name);
475 Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists.
477 ### <a id="objref-get_notification_command"></a> get_notification_command
481 function get_notification_command(name);
483 Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists.
485 ### <a id="objref-get_host"></a> get_host
489 function get_host(host_name);
491 Returns the Host object with the specified name, or `null` if no such Host object exists.
494 ### <a id="objref-get_service"></a> get_service
498 function get_service(host_name, service_name);
500 Returns the Service object with the specified name, or `null` if no such Service object exists.
503 ### <a id="objref-get_user"></a> get_user
507 function get_user(name);
509 Returns the User object with the specified name, or `null` if no such User object exists.
511 ### <a id="objref-get_host_group"></a> get_host_group
515 function get_host_group(name);
517 Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists.
520 ### <a id="objref-get_service_group"></a> get_service_group
524 function get_service_group(name);
526 Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists.
528 ### <a id="objref-get_user_group"></a> get_user_group
532 function get_user_group(name);
534 Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists.
537 ### <a id="objref-get_time_period"></a> get_time_period
541 function get_time_period(name);
543 Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists.
546 ### <a id="objref-get_object"></a> get_object
550 function get_object(type, name);
552 Returns the object with the specified type and name, or `null` if no such object exists. `type` must refer
556 ### <a id="objref-get_objects"></a> get_objects
560 function get_objects(type);
562 Returns an array of objects whose type matches the specified type. `type` must refer
566 ## <a id="math-object"></a> Math object
568 The global `Math` object can be used to access a number of mathematical constants
571 ### <a id="math-e"></a> Math.E
575 ### <a id="math-ln2"></a> Math.LN2
577 Natural logarithm of 2.
579 ### <a id="math-ln10"></a> Math.LN10
581 Natural logarithm of 10.
583 ### <a id="math-log2e"></a> Math.LOG2E
585 Base 2 logarithm of E.
587 ### <a id="math-pi"></a> Math.PI
589 The mathematical constant Pi.
591 ### <a id="math-sqrt1_2"></a> Math.SQRT1_2
595 ### <a id="math-sqrt2"></a> Math.SQRT2
599 ### <a id="math-abs"></a> Math.abs
605 Returns the absolute value of `x`.
607 ### <a id="math-acos"></a> Math.acos
613 Returns the arccosine of `x`.
615 ### <a id="math-asin"></a> Math.asin
621 Returns the arcsine of `x`.
623 ### <a id="math-atan"></a> Math.atan
629 Returns the arctangent of `x`.
631 ### <a id="math-atan2"></a> Math.atan2
635 function atan2(y, x);
637 Returns the arctangent of the quotient of `y` and `x`.
639 ### <a id="math-ceil"></a> Math.ceil
645 Returns the smallest integer value not less than `x`.
647 ### <a id="math-cos"></a> Math.cos
653 Returns the cosine of `x`.
655 ### <a id="math-exp"></a> Math.exp
661 Returns E raised to the `x`th power.
663 ### <a id="math-floor"></a> Math.floor
669 Returns the largest integer value not greater than `x`.
671 ### <a id="math-isinf"></a> Math.isinf
677 Returns whether `x` is infinite.
679 ### <a id="math-isnan"></a> Math.isnan
685 Returns whether `x` is NaN (not-a-number).
687 ### <a id="math-log"></a> Math.log
693 Returns the natural logarithm of `x`.
695 ### <a id="math-max"></a> Math.max
701 Returns the largest argument. A variable number of arguments can be specified.
702 If no arguments are given, -Infinity is returned.
704 ### <a id="math-min"></a> Math.min
710 Returns the smallest argument. A variable number of arguments can be specified.
711 If no arguments are given, +Infinity is returned.
713 ### <a id="math-pow"></a> Math.pow
719 Returns `x` raised to the `y`th power.
721 ### <a id="math-random"></a> Math.random
727 Returns a pseudo-random number between 0 and 1.
729 ### <a id="math-round"></a> Math.round
735 Returns `x` rounded to the nearest integer value.
737 ### <a id="math-sign"></a> Math.sign
743 Returns -1 if `x` is negative, 1 if `x` is positive
746 ### <a id="math-sin"></a> Math.sin
752 Returns the sine of `x`.
754 ### <a id="math-sqrt"></a> Math.sqrt
760 Returns the square root of `x`.
762 ### <a id="math-tan"></a> Math.tan
768 Returns the tangent of `x`.
770 ## <a id="json-object"></a> Json object
772 The global `Json` object can be used to encode and decode JSON.
774 ### <a id="json-encode"></a> Json.encode
780 Encodes an arbitrary value into JSON.
782 ### <a id="json-decode"></a> Json.decode
788 Decodes a JSON string.
790 ## <a id="number-type"></a> Number type
792 ### <a id="number-to_string"></a> Number#to_string
796 function to_string();
798 The `to_string` method returns a string representation of the number.
803 example.to_string() /* Returns "7" */
805 ## <a id="boolean-type"></a> Boolean type
807 ### <a id="boolean-to_string"></a> Boolean#to_string
811 function to_string();
813 The `to_string` method returns a string representation of the boolean value.
818 example.to_string() /* Returns "true" */
820 ## <a id="string-type"></a> String type
822 ### <a id="string-find"></a> String#find
826 function find(str, start);
828 Returns the zero-based index at which the string `str` was found in the string. If the string
829 was not found, -1 is returned. `start` specifies the zero-based index at which `find` should
830 start looking for the string (defaults to 0 when not specified).
834 "Hello World".find("World") /* Returns 6 */
836 ### <a id="string-contains"></a> String#contains
840 function contains(str);
842 Returns `true` if the string `str` was found in the string. If the string
843 was not found, `false` is returned. Use [find](18-library-reference.md#string-find)
844 for getting the index instead.
848 "Hello World".contains("World") /* Returns true */
850 ### <a id="string-len"></a> String#len
856 Returns the length of the string in bytes. Note that depending on the encoding type of the string
857 this is not necessarily the number of characters.
861 "Hello World".len() /* Returns 11 */
863 ### <a id="string-lower"></a> String#lower
869 Returns a copy of the string with all of its characters converted to lower-case.
873 "Hello World".lower() /* Returns "hello world" */
875 ### <a id="string-upper"></a> String#upper
881 Returns a copy of the string with all of its characters converted to upper-case.
885 "Hello World".upper() /* Returns "HELLO WORLD" */
887 ### <a id="string-replace"></a> String#replace
891 function replace(search, replacement);
893 Returns a copy of the string with all occurences of the string specified in `search` replaced
894 with the string specified in `replacement`.
896 ### <a id="string-split"></a> String#split
900 function split(delimiters);
902 Splits a string into individual parts and returns them as an array. The `delimiters` argument
903 specifies the characters which should be used as delimiters between parts.
907 "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
909 ### <a id="string-substr"></a> String#substr
913 function substr(start, len);
915 Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins.
916 The optional `len` argument specifies the length of the part ("until the end of the string" if omitted).
920 "Hello World".substr(6) /* Returns "World" */
922 ### <a id="string-to_string"></a> String#to_string
926 function to_string();
928 Returns a copy of the string.
930 ### <a id="string-reverse"></a> String#reverse
936 Returns a copy of the string in reverse order.
938 ### <a id="string-trim"></a> String#trim
944 Removes trailing whitespaces and returns the string.
946 ## <a id="object-type"></a> Object type
948 This is the base type for all types in the Icinga application.
950 ### <a id="object-clone"></a> Object#clone
956 Returns a copy of the object. Note that for object elements which are
957 reference values (e.g. objects such as arrays or dictionaries) the entire
958 object is recursively copied.
960 ### <a id="object-to-string"></a> Object#to_string
964 function to_string();
966 Returns a string representation for the object. Unless overridden this returns a string
967 of the format "Object of type '<typename>'" where <typename> is the name of the
972 [ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */
974 ### <a id="object-type-field"></a> Object#type
980 Returns the object's type name. This attribute is read-only.
984 get_host("localhost").type /* Returns "Host" */
986 ## <a id="type-type"></a> Type type
988 Inherits methods from the [Object type](18-library-reference.md#object-type).
990 The `Type` type provides information about the underlying type of an object or scalar value.
992 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.
994 ### <a id="type-base"></a> Type#base
1000 Returns a reference to the type's base type. This attribute is read-only.
1004 Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */
1006 ### <a id="type-name"></a> Type#name
1012 Returns the name of the type.
1014 ### <a id="type-prototype"></a> Type#prototype
1020 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.
1022 The prototype functionality is used to implement methods.
1026 3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */
1028 ## <a id="array-type"></a> Array type
1030 Inherits methods from the [Object type](18-library-reference.md#object-type).
1032 ### <a id="array-add"></a> Array#add
1036 function add(value);
1038 Adds a new value after the last element in the array.
1040 ### <a id="array-clear"></a> Array#clear
1046 Removes all elements from the array.
1048 ### <a id="array-shallow-clone"></a> Array#shallow_clone
1050 function shallow_clone();
1052 Returns a copy of the array. Note that for elements which are reference values (e.g. objects such
1053 as arrays and dictionaries) only the references are copied.
1055 ### <a id="array-contains"></a> Array#contains
1059 function contains(value);
1061 Returns true if the array contains the specified value, false otherwise.
1063 ### <a id="array-len"></a> Array#len
1069 Returns the number of elements contained in the array.
1071 ### <a id="array-remove"></a> Array#remove
1075 function remove(index);
1077 Removes the element at the specified zero-based index.
1079 ### <a id="array-set"></a> Array#set
1083 function set(index, value);
1085 Sets the element at the zero-based index to the specified value. The `index` must refer to an element
1086 which already exists in the array.
1088 ### <a id="array-get"></a> Array#get
1092 function get(index);
1094 Retrieves the element at the specified zero-based index.
1096 ### <a id="array-sort"></a> Array#sort
1100 function sort(less_cmp);
1102 Returns a copy of the array where all items are sorted. The items are
1103 compared using the `<` (less-than) operator. A custom comparator function
1104 can be specified with the `less_cmp` argument.
1106 ### <a id="array-join"></a> Array#join
1110 function join(separator);
1112 Joins all elements of the array using the specified separator.
1114 ### <a id="array-reverse"></a> Array#reverse
1120 Returns a new array with all elements of the current array in reverse order.
1122 ### <a id="array-map"></a> Array#map
1128 Calls `func(element)` for each of the elements in the array and returns
1129 a new array containing the return values of these function calls.
1131 ### <a id="array-reduce"></a> Array#reduce
1135 function reduce(func);
1137 Reduces the elements of the array into a single value by calling the provided
1138 function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array
1139 or results from previous function calls.
1141 ### <a id="array-filter"></a> Array#filter
1145 function filter(func);
1147 Returns a copy of the array containing only the elements for which `func(element)`
1150 ### <a id="array-unique"></a> Array#unique
1156 Returns a copy of the array with all duplicate elements removed. The original order
1157 of the array is not preserved.
1159 ## <a id="dictionary-type"></a> Dictionary type
1161 Inherits methods from the [Object type](18-library-reference.md#object-type).
1163 ### <a id="dictionary-shallow-clone"></a> Dictionary#shallow_clone
1167 function shallow_clone();
1169 Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such
1170 as arrays and dictionaries) only the references are copied.
1172 ### <a id="dictionary-contains"></a> Dictionary#contains
1176 function contains(key);
1178 Returns true if a dictionary item with the specified `key` exists, false otherwise.
1180 ### <a id="dictionary-len"></a> Dictionary#len
1186 Returns the number of items contained in the dictionary.
1188 ### <a id="dictionary-remove"></a> Dictionary#remove
1192 function remove(key);
1194 Removes the item with the specified `key`. Trying to remove an item which does not exist
1197 ### <a id="dictionary-set"></a> Dictionary#set
1201 function set(key, value);
1203 Creates or updates an item with the specified `key` and `value`.
1205 ### <a id="dictionary-get"></a> Dictionary#get
1211 Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist
1214 ### <a id="dictionary-keys"></a> Dictionary#keys
1220 Returns a list of keys for all items that are currently in the dictionary.
1222 ## <a id="scriptfunction-type"></a> Function type
1224 Inherits methods from the [Object type](18-library-reference.md#object-type).
1226 ### <a id="scriptfunction-call"></a> Function#call
1230 function call(thisArg, ...);
1232 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1233 scope for the function. All other arguments are passed directly to the function.
1237 function set_x(val) {
1243 set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
1245 ### <a id="scriptfunction-callv"></a> Function#callv
1249 function callv(thisArg, args);
1251 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1252 scope for the function. The items in the `args` array are passed to the function as individual arguments.
1256 function set_x(val) {
1264 set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */
1266 ## <a id="datetime-type"></a> DateTime type
1268 Inherits methods from the [Object type](18-library-reference.md#object-type).
1270 ### <a id="datetime-ctor"></a> DateTime constructor
1275 function DateTime(unixTimestamp)
1276 function DateTime(year, month, day)
1277 function DateTime(year, month, day, hours, minutes, seconds)
1279 Constructs a new DateTime object. When no arguments are specified for the constructor a new
1280 DateTime object representing the current time is created.
1284 var d1 = DateTime() /* current time */
1285 var d2 = DateTime(2016, 5, 21) /* midnight April 21st, 2016 (local time) */
1287 ### <a id="datetime-arithmetic"></a> DateTime arithmetic
1289 Subtracting two DateTime objects yields the interval between them, in seconds.
1293 var delta = DateTime() - DateTime(2016, 5, 21) /* seconds since midnight April 21st, 2016 */
1295 Subtracting a number from a DateTime object yields a new DateTime object that is further in the past:
1299 var dt = DateTime() - 2 * 60 * 60 /* Current time minus 2 hours */
1301 Adding a number to a DateTime object yields a new DateTime object that is in the future:
1305 var dt = DateTime() + 24 * 60 60 /* Current time plus 24 hours */
1307 ### <a id="datetime-format"></a> DateTime#format
1311 function format(fmt)
1313 Returns a string representation for the DateTime object using the specified format string.
1314 The format string may contain format conversion placeholders as specified in strftime(3).
1318 var s = DateTime(2016, 4, 21).format("%A") /* Sets s to "Thursday". */
1320 ### <a id="datetime-tostring"></a> DateTime#to_string
1324 function to_string()
1326 Returns a string representation for the DateTime object. Uses a suitable default format.
1330 var s = DateTime(2016, 4, 21).to_string() /* Sets s to "2016-04-21 00:00:00 +0200". */