granicus.if.org Git - icinga2/blob - doc/18-library-reference.md

   1 # Library Reference <a id="library-reference"></a>
   2
   3 ## Global functions <a id="global-functions"></a>
   4
   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).
   8
   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.
  12
  13 ### regex <a id="global-functions-regex"></a>
  14
  15 Signature:
  16
  17 ```
  18 function regex(pattern, value, mode)
  19 ```
  20
  21 Returns true if the regular expression `pattern` matches the `value`, false otherwise.
  22 The `value` can be of the type [String](18-library-reference.md#string-type) or [Array](18-library-reference.md#array-type) (which
  23 contains string elements).
  24
  25 The `mode` argument is optional and can be either `MatchAll` (in which case all elements
  26 for an array have to match) or `MatchAny` (in which case at least one element has to match).
  27 The default mode is `MatchAll`.
  28
  29 **Tip**: In case you are looking for regular expression tests try [regex101](https://regex101.com).
  30
  31 Example for string values:
  32
  33 ```
  34 $ icinga2 console
  35 Icinga 2 (version: v2.11.0)
  36 <1> => host.vars.os_type = "Linux/Unix"
  37 null
  38 <2> => regex("^Linux", host.vars.os_type)
  39 true
  40 <3> => regex("^Linux$", host.vars.os_type)
  41 false
  42 ```
  43
  44 Example for an array of string values:
  45
  46 ```
  47 $ icinga2 console
  48 Icinga 2 (version: v2.11.0)
  49 <1> => host.vars.databases = [ "db-prod1", "db-prod2", "db-dev" ]
  50 null
  51 <2> => regex("^db-prod\\d+", host.vars.databases, MatchAny)
  52 true
  53 <3> => regex("^db-prod\\d+", host.vars.databases, MatchAll)
  54 false
  55 ```
  56
  57 ### match <a id="global-functions-match"></a>
  58
  59 Signature:
  60
  61 ```
  62 function match(pattern, text, mode)
  63 ```
  64
  65 Returns true if the wildcard (`?*`) `pattern` matches the `value`, false otherwise.
  66 The `value` can be of the type [String](18-library-reference.md#string-type) or [Array](18-library-reference.md#array-type) (which
  67 contains string elements).
  68
  69 The `mode` argument is optional and can be either `MatchAll` (in which case all elements
  70 for an array have to match) or `MatchAny` (in which case at least one element has to match).
  71 The default mode is `MatchAll`.
  72
  73 Example for string values:
  74
  75 ```
  76 $ icinga2 console
  77 Icinga 2 (version: v2.11.0)
  78 <1> => var name = "db-prod-sfo-657"
  79 null
  80 <2> => match("*prod-sfo*", name)
  81 true
  82 <3> => match("*-dev-*", name)
  83 false
  84 ```
  85
  86 Example for an array of string values:
  87
  88 ```
  89 $ icinga2 console
  90 Icinga 2 (version: v2.11.0-28)
  91 <1> => host.vars.application_types = [ "web-wp", "web-rt", "db-local" ]
  92 null
  93 <2> => match("web-*", host.vars.application_types, MatchAll)
  94 false
  95 <3> => match("web-*", host.vars.application_types, MatchAny)
  96 true
  97 ```
  98
  99 ### cidr_match <a id="global-functions-cidr_match"></a>
 100
 101 Signature:
 102
 103 ```
 104 function cidr_match(pattern, ip, mode)
 105 ```
 106
 107 Returns true if the CIDR pattern matches the IP address, false otherwise.
 108
 109 IPv4 addresses are converted to IPv4-mapped IPv6 addresses before being
 110 matched against the pattern. The `mode` argument is optional and can be
 111 either `MatchAll` (in which case all elements for an array have to match) or `MatchAny`
 112 (in which case at least one element has to match). The default mode is `MatchAll`.
 113
 114
 115 Example for a single IP address:
 116
 117 ```
 118 $ icinga2 console
 119 Icinga 2 (version: v2.11.0)
 120 <1> => host.address = "192.168.56.101"
 121 null
 122 <2> => cidr_match("192.168.56.0/24", host.address)
 123 true
 124 <3> => cidr_match("192.168.56.0/26", host.address)
 125 false
 126 ```
 127
 128 Example for an array of IP addresses:
 129
 130 ```
 131 $ icinga2 console
 132 Icinga 2 (version: v2.11.0)
 133 <1> => host.vars.vhost_ips = [ "192.168.56.101", "192.168.56.102", "10.0.10.99" ]
 134 null
 135 <2> => cidr_match("192.168.56.0/24", host.vars.vhost_ips, MatchAll)
 136 false
 137 <3> => cidr_match("192.168.56.0/24", host.vars.vhost_ips, MatchAny)
 138 true
 139 ```
 140
 141 ### range <a id="global-functions-range"></a>
 142
 143 Signature:
 144
 145 ```
 146 function range(end)
 147 function range(start, end)
 148 function range(start, end, increment)
 149 ```
 150
 151 Returns an array of numbers in the specified range.
 152 If you specify one parameter, the first element starts at `0`.
 153 The following array numbers are incremented by `1` and stop before
 154 the specified end.
 155 If you specify the start and end numbers, the returned array
 156 number are incremented by `1`. They start at the specified start
 157 number and stop before the end number.
 158 Optionally you can specify the incremented step between numbers
 159 as third parameter.
 160
 161 Example:
 162
 163 ```
 164 $ icinga2 console
 165 Icinga 2 (version: v2.11.0)
 166 <1> => range(5)
 167 [ 0.000000, 1.000000, 2.000000, 3.000000, 4.000000 ]
 168 <2> => range(2,4)
 169 [ 2.000000, 3.000000 ]
 170 <3> => range(2,10,2)
 171 [ 2.000000, 4.000000, 6.000000, 8.000000 ]
 172 ```
 173
 174 ### len <a id="global-functions-len"></a>
 175
 176 Signature:
 177
 178 ```
 179 function len(value)
 180 ```
 181
 182 Returns the length of the value, i.e. the number of elements for an array
 183 or dictionary, or the length of the string in bytes.
 184
 185 **Note**: Instead of using this global function you are advised to use the type's
 186 prototype method: [Array#len](18-library-reference.md#array-len), [Dictionary#len](18-library-reference.md#dictionary-len) and
 187 [String#len](18-library-reference.md#string-len).
 188
 189 Example:
 190
 191 ```
 192 $ icinga2 console
 193 Icinga 2 (version: v2.11.0)
 194 <1> => host.groups = [ "linux-servers", "db-servers" ]
 195 null
 196 <2> => host.groups.len()
 197 2.000000
 198 <3> => host.vars.disks["/"] = {}
 199 null
 200 <4> => host.vars.disks["/var"] = {}
 201 null
 202 <5> => host.vars.disks.len()
 203 2.000000
 204 <6> => host.vars.os_type = "Linux/Unix"
 205 null
 206 <7> => host.vars.os_type.len()
 207 10.000000
 208 ```
 209
 210 ### union <a id="global-functions-union"></a>
 211
 212 Signature:
 213
 214 ```
 215 function union(array, array, ...)
 216 ```
 217
 218 Returns an array containing all unique elements from the specified arrays.
 219
 220 Example:
 221 ```
 222 $ icinga2 console
 223 Icinga 2 (version: v2.11.0)
 224 <1> => var dev_notification_groups = [ "devs", "slack" ]
 225 null
 226 <2> => var host_notification_groups = [ "slack", "noc" ]
 227 null
 228 <3> => union(dev_notification_groups, host_notification_groups)
 229 [ "devs", "noc", "slack" ]
 230 ```
 231
 232 ### intersection <a id="global-functions-intersection"></a>
 233
 234 Signature:
 235
 236 ```
 237 function intersection(array, array, ...)
 238 ```
 239
 240 Returns an array containing all unique elements which are common to all
 241 specified arrays.
 242
 243 Example:
 244
 245 ```
 246 $ icinga2 console
 247 Icinga 2 (version: v2.11.0)
 248 <1> => var dev_notification_groups = [ "devs", "slack" ]
 249 null
 250 <2> => var host_notification_groups = [ "slack", "noc" ]
 251 null
 252 <3> => intersection(dev_notification_groups, host_notification_groups)
 253 [ "slack" ]
 254 ```
 255
 256 ### keys <a id="global-functions-keys"></a>
 257
 258 Signature:
 259
 260 ```
 261 function keys(dict)
 262 ```
 263
 264 Returns an array containing the dictionary's keys.
 265
 266 **Note**: Instead of using this global function you are advised to use the type's
 267 prototype method: [Dictionary#keys](18-library-reference.md#dictionary-keys).
 268
 269 Example:
 270
 271 ```
 272 $ icinga2 console
 273 Icinga 2 (version: v2.11.0)
 274 <1> => host.vars.disks["/"] = {}
 275 null
 276 <2> => host.vars.disks["/var"] = {}
 277 null
 278 <3> => host.vars.disks.keys()
 279 [ "/", "/var" ]
 280 ```
 281
 282 ### string <a id="global-functions-string"></a>
 283
 284 Signature:
 285
 286 ```
 287 function string(value)
 288 ```
 289
 290 Converts the value to a string.
 291
 292 **Note**: Instead of using this global function you are advised to use the type's
 293 prototype method:
 294
 295 * [Number#to_string](18-library-reference.md#number-to_string)
 296 * [Boolean#to_string](18-library-reference.md#boolean-to_string)
 297 * [String#to_string](18-library-reference.md#string-to_string)
 298 * [Object#to_string](18-library-reference.md#object-to-string) for Array and Dictionary types
 299 * [DateTime#to_string](18-library-reference.md#datetime-tostring)
 300
 301 Example:
 302
 303 ```
 304 $ icinga2 console
 305 Icinga 2 (version: v2.11.0)
 306 <1> => 5.to_string()
 307 "5"
 308 <2> => false.to_string()
 309 "false"
 310 <3> => "abc".to_string()
 311 "abc"
 312 <4> => [ "dev", "slack" ].to_string()
 313 "[ \"dev\", \"slack\" ]"
 314 <5> => { "/" = {}, "/var" = {} }.to_string()
 315 "{\n\t\"/\" = {\n\t}\n\t\"/var\" = {\n\t}\n}"
 316 <6> => DateTime(2016, 11, 25).to_string()
 317 "2016-11-25 00:00:00 +0100"
 318 ```
 319
 320 ### number <a id="global-functions-number"></a>
 321
 322 Signature:
 323
 324 ```
 325 function number(value)
 326 ```
 327
 328 Converts the value to a number.
 329
 330 Example:
 331
 332 ```
 333 $ icinga2 console
 334 Icinga 2 (version: v2.11.0)
 335 <1> => number(false)
 336 0.000000
 337 <2> => number("78")
 338 78.000000
 339 ```
 340
 341 ### bool <a id="global-functions-bool"></a>
 342
 343 Signature:
 344
 345 ```
 346 function bool(value)
 347 ```
 348
 349 Converts the value to a bool.
 350
 351 Example:
 352
 353 ```
 354 $ icinga2 console
 355 Icinga 2 (version: v2.11.0)
 356 <1> => bool(1)
 357 true
 358 <2> => bool(0)
 359 false
 360 ```
 361
 362 ### random <a id="global-functions-random"></a>
 363
 364 Signature:
 365
 366 ```
 367 function random()
 368 ```
 369
 370 Returns a random value between 0 and RAND\_MAX (as defined in stdlib.h).
 371
 372 ```
 373 $ icinga2 console
 374 Icinga 2 (version: v2.11.0)
 375 <1> => random()
 376 1263171996.000000
 377 <2> => random()
 378 108402530.000000
 379 ```
 380
 381 ### log <a id="global-functions-log"></a>
 382
 383 Signature:
 384
 385 ```
 386 function log(value)
 387 ```
 388
 389 Writes a message to the log. Non-string values are converted to a JSON string.
 390
 391 Signature:
 392
 393 ```
 394 function log(severity, facility, value)
 395 ```
 396
 397 Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`,
 398 `LogInformation`, `LogWarning`, and `LogCritical`.
 399
 400 Non-string values are converted to a JSON string.
 401
 402 Example:
 403
 404 ```
 405 $ icinga2 console
 406 Icinga 2 (version: v2.11.0)
 407 <1> => log(LogCritical, "Console", "First line")
 408 critical/Console: First line
 409 null
 410 <2> => var groups = [ "devs", "slack" ]
 411 null
 412 <3> => log(LogCritical, "Console", groups)
 413 critical/Console: ["devs","slack"]
 414 null
 415 ```
 416
 417 ### typeof <a id="global-functions-typeof"></a>
 418
 419 Signature:
 420
 421 ```
 422 function typeof(value)
 423 ```
 424
 425 Returns the [Type](18-library-reference.md#type-type) object for a value.
 426
 427 Example:
 428
 429 ```
 430 $ icinga2 console
 431 Icinga 2 (version: v2.11.0)
 432 <1> => typeof(3) == Number
 433 true
 434 <2> => typeof("str") == String
 435 true
 436 <3> => typeof(true) == Boolean
 437 true
 438 <4> => typeof([ 1, 2, 3]) == Array
 439 true
 440 <5> => typeof({ a = 2, b = 3 }) == Dictionary
 441 true
 442 ```
 443
 444 ### get_time <a id="global-functions-get_time"></a>
 445
 446 Signature:
 447
 448 ```
 449 function get_time()
 450 ```
 451
 452 Returns the current UNIX timestamp as floating point number.
 453
 454 Example:
 455
 456 ```
 457 $ icinga2 console
 458 Icinga 2 (version: v2.11.0)
 459 <1> => get_time()
 460 1480072135.633008
 461 <2> => get_time()
 462 1480072140.401207
 463 ```
 464
 465 ### parse_performance_data <a id="global-functions-parse_performance_data"></a>
 466
 467 Signature:
 468
 469 ```
 470 function parse_performance_data(pd)
 471 ```
 472
 473 Parses a performance data string and returns an array describing the values.
 474
 475 Example:
 476
 477 ```
 478 $ icinga2 console
 479 Icinga 2 (version: v2.11.0)
 480 <1> => var pd = "'time'=1480074205.197363;;;"
 481 null
 482 <2> => parse_performance_data(pd)
 483 {
 484         counter = false
 485         crit = null
 486         label = "time"
 487         max = null
 488         min = null
 489         type = "PerfdataValue"
 490         unit = ""
 491         value = 1480074205.197363
 492         warn = null
 493 }
 494 ```
 495
 496 ### getenv <a id="global-functions-getenv"></a>
 497
 498 Signature:
 499
 500 ```
 501 function getenv(key)
 502 ```
 503
 504 Returns the value from the specified environment variable key.
 505
 506 Example:
 507
 508 ```
 509 $ MY_ENV_VAR=icinga2 icinga2 console
 510 Icinga 2 (version: v2.11.0)
 511 Type $help to view available commands.
 512 <1> => getenv("MY_ENV_VAR")
 513 "icinga2"
 514 ```
 515
 516 ### dirname <a id="global-functions-dirname"></a>
 517
 518 Signature:
 519
 520 ```
 521 function dirname(path)
 522 ```
 523
 524 Returns the directory portion of the specified path.
 525
 526 Example:
 527
 528 ```
 529 $ icinga2 console
 530 Icinga 2 (version: v2.11.0)
 531 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
 532 null
 533 <2> => dirname(path)
 534 "/etc/icinga2/scripts"
 535 ```
 536
 537 ### basename <a id="global-functions-basename"></a>
 538
 539 Signature:
 540
 541 ```
 542 function basename(path)
 543 ```
 544
 545 Returns the filename portion of the specified path.
 546
 547 Example:
 548
 549 ```
 550 $ icinga2 console
 551 Icinga 2 (version: v2.11.0)
 552 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
 553 null
 554 <2> => basename(path)
 555 "xmpp-notification.pl"
 556 ```
 557
 558 ### path\_exists <a id="global-functions-path-exists"></a>
 559
 560 Signature:
 561
 562 ```
 563 function path_exists(path)
 564 ```
 565
 566 Returns true if the specified path exists, false otherwise.
 567
 568 Example:
 569
 570 ```
 571 $ icinga2 console
 572 Icinga 2 (version: v2.11.0)
 573 <1> => var path = "/etc/icinga2/scripts/xmpp-notification.pl"
 574 null
 575 <2> => path_exists(path)
 576 true
 577 ```
 578
 579 ### glob <a id="global-functions-glob"></a>
 580
 581 Signature:
 582
 583 ```
 584 function glob(pathSpec, type)
 585 ```
 586
 587 Returns an array containing all paths which match the
 588 `pathSpec` argument.
 589
 590 The `type` argument is optional and specifies which types
 591 of paths are matched. This can be a combination of the `GlobFile`
 592 and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
 593
 594 ```
 595 $ icinga2 console
 596 Icinga 2 (version: v2.11.0)
 597 <1> => var pathSpec = "/etc/icinga2/conf.d/*.conf"
 598 null
 599 <2> => glob(pathSpec)
 600 [ "/etc/icinga2/conf.d/app.conf", "/etc/icinga2/conf.d/commands.conf", ... ]
 601 ```
 602
 603 ### glob\_recursive <a id="global-functions-glob-recursive"></a>
 604
 605 Signature:
 606
 607 ```
 608 function glob_recursive(path, pattern, type)
 609 ```
 610
 611 Recursively descends into the specified directory and returns an array containing
 612 all paths which match the `pattern` argument.
 613
 614 The `type` argument is optional and specifies which types
 615 of paths are matched. This can be a combination of the `GlobFile`
 616 and `GlobDirectory` constants. The default value is `GlobFile | GlobDirectory`.
 617
 618 ```
 619 $ icinga2 console
 620 Icinga 2 (version: v2.11.0)
 621 <1> => var path = "/etc/icinga2/zones.d/"
 622 null
 623 <2> => var pattern = "*.conf"
 624 null
 625 <3> => glob_recursive(path, pattern)
 626 [ "/etc/icinga2/zones.d/global-templates/templates.conf", "/etc/icinga2/zones.d/master/hosts.conf", ... ]
 627 ```
 628
 629 ### escape_shell_arg <a id="global-functions-escape_shell_arg"></a>
 630
 631 Signature:
 632
 633 ```
 634 function escape_shell_arg(text)
 635 ```
 636
 637 Escapes a string for use as a single shell argument.
 638
 639 Example:
 640
 641 ```
 642 $ icinga2 console
 643 Icinga 2 (version: v2.11.0)
 644 <1> => escape_shell_arg("'$host.name$' '$service.name$'")
 645 "''\\''$host.name$'\\'' '\\''$service.name$'\\'''"
 646 ```
 647
 648 ### escape_shell_cmd <a id="global-functions-escape_shell_cmd"></a>
 649
 650 Signature:
 651
 652 ```
 653 function escape_shell_cmd(text)
 654 ```
 655
 656 Escapes shell meta characters in a string.
 657
 658 Example:
 659
 660 ```
 661 $ icinga2 console
 662 Icinga 2 (version: v2.11.0)
 663 <1> => escape_shell_cmd("/bin/echo 'shell test' $ENV")
 664 "/bin/echo 'shell test' \\$ENV"
 665 ```
 666
 667 ### escape_create_process_arg <a id="global-functions-escape_create_process_arg"></a>
 668
 669 Signature:
 670
 671 ```
 672 function escape_create_process_arg(text)
 673 ```
 674
 675 Escapes a string for use as an argument for CreateProcess(). Windows only.
 676
 677 ### sleep <a id="global-functions-sleep"></a>
 678
 679 Signature:
 680
 681 ```
 682 function sleep(interval)
 683 ```
 684
 685 Sleeps for the specified amount of time (in seconds).
 686
 687
 688 ## Scoped Functions <a id="scoped-functions"></a>
 689
 690 This chapter describes functions which are only available
 691 in a specific scope.
 692
 693 ### macro <a id="scoped-functions-macro"></a>
 694
 695 Signature:
 696
 697 ```
 698 function macro("$macro_name$")
 699 ```
 700
 701 The `macro` function can be used to resolve [runtime macro](03-monitoring-basics.md#runtime-macros)
 702 strings into their values.
 703 The returned value depends on the attribute value which is resolved
 704 from the specified runtime macro.
 705
 706 This function is only available in runtime evaluated functions, e.g.
 707 for [custom attributes](03-monitoring-basics.md#custom-attributes-functions) which
 708 use the [abbreviated lambda syntax](17-language-reference.md#nullary-lambdas).
 709
 710 This example sets the `snmp_address` custom attribute
 711 based on `$address$` and `$address6$`.
 712
 713 ```
 714   vars.snmp_address = {{
 715     var addr_v4 = macro("$address$")
 716     var addr_v6 = macro("$address6$")
 717
 718     if (addr_v4) {
 719         return addr_v4
 720     } else {
 721         return "udp6:[" + addr_v6 + "]"
 722     }
 723   }}
 724 ```
 725
 726 More reference examples are available inside the [Icinga Template Library](10-icinga-template-library.md#icinga-template-library)
 727 and the [object accessors chapter](08-advanced-topics.md#access-object-attributes-at-runtime).
 728
 729 ## Object Accessor Functions <a id="object-accessor-functions"></a>
 730
 731 These functions can be used to retrieve a reference to another object by name.
 732
 733 ### get_check_command <a id="objref-get_check_command"></a>
 734
 735 Signature:
 736
 737 ```
 738 function get_check_command(name);
 739 ```
 740
 741 Returns the CheckCommand object with the specified name, or `null` if no such CheckCommand object exists.
 742
 743 ### get_event_command <a id="objref-get_event_command"></a>
 744
 745 Signature:
 746
 747 ```
 748 function get_event_command(name);
 749 ```
 750
 751 Returns the EventCommand object with the specified name, or `null` if no such EventCommand object exists.
 752
 753 ### get_notification_command <a id="objref-get_notification_command"></a>
 754
 755 Signature:
 756
 757 ```
 758 function get_notification_command(name);
 759 ```
 760
 761 Returns the NotificationCommand object with the specified name, or `null` if no such NotificationCommand object exists.
 762
 763 ### get_host <a id="objref-get_host"></a>
 764
 765 Signature:
 766
 767 ```
 768 function get_host(host_name);
 769 ```
 770
 771 Returns the Host object with the specified name, or `null` if no such Host object exists.
 772
 773
 774 ### get_service <a id="objref-get_service"></a>
 775
 776 Signature:
 777
 778 ```
 779 function get_service(host_name, service_name);
 780 function get_service(host, service_name);
 781 ```
 782
 783 Returns the Service object with the specified host name or object and service name pair,
 784 or `null` if no such Service object exists.
 785
 786 Example in the [debug console](11-cli-commands.md#cli-command-console)
 787 which fetches the `disk` service object from the current Icinga 2 node:
 788
 789 ```
 790 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
 791 Icinga 2 (version: v2.11.0)
 792
 793 <1> => get_service(NodeName, "disk")
 794 <2> => get_service(NodeName, "disk").__name
 795 "icinga2-master1.localdomain!disk"
 796
 797 <3> => get_service(get_host(NodeName), "disk").__name
 798 "icinga2-master1.localdomain!disk"
 799 ```
 800
 801 ### get_services <a id="objref-get_services"></a>
 802
 803 Signature:
 804
 805 ```
 806 function get_services(host_name);
 807 function get_services(host);
 808 ```
 809
 810 Returns an [array](17-language-reference.md#array) of service objects for the specified host name or object,
 811 or `null` if no such host object exists.
 812
 813 Example in the [debug console](11-cli-commands.md#cli-command-console)
 814 which fetches all service objects from the current Icinga 2 node:
 815
 816 ```
 817 $ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
 818 Icinga 2 (version: v2.11.0)
 819
 820 <1> => get_services(NodeName).map(s => s.name)
 821 [ "disk", "disk /", "http", "icinga", "load", "ping4", "ping6", "procs", "ssh", "users" ]
 822 ```
 823
 824 Note: [map](18-library-reference.md#array-map) takes a [lambda function](17-language-reference.md#lambdas) as argument. In this example
 825 we only want to collect and print the `name` attribute with `s => s.name`.
 826
 827 This works in a similar fashion for a host object where you can extract all service states
 828 in using the [map](18-library-reference.md#array-map) functionality:
 829
 830 ```
 831 <2> => get_services(get_host(NodeName)).map(s => s.state)
 832 [ 2.000000, 2.000000, 2.000000, 0.000000, 0.000000, 0.000000, 2.000000, 0.000000, 0.000000, 1.000000, 0.000000, 0.000000 ]
 833 ```
 834
 835 ### get_user <a id="objref-get_user"></a>
 836
 837 Signature:
 838
 839 ```
 840 function get_user(name);
 841 ```
 842
 843 Returns the User object with the specified name, or `null` if no such User object exists.
 844
 845 ### get_host_group <a id="objref-get_host_group"></a>
 846
 847 Signature:
 848
 849 ```
 850 function get_host_group(name);
 851 ```
 852
 853 Returns the HostGroup object with the specified name, or `null` if no such HostGroup object exists.
 854
 855
 856 ### get_service_group <a id="objref-get_service_group"></a>
 857
 858 Signature:
 859
 860 ```
 861 function get_service_group(name);
 862 ```
 863
 864 Returns the ServiceGroup object with the specified name, or `null` if no such ServiceGroup object exists.
 865
 866 ### get_user_group <a id="objref-get_user_group"></a>
 867
 868 Signature:
 869
 870 ```
 871 function get_user_group(name);
 872 ```
 873
 874 Returns the UserGroup object with the specified name, or `null` if no such UserGroup object exists.
 875
 876
 877 ### get_time_period <a id="objref-get_time_period"></a>
 878
 879 Signature:
 880
 881 ```
 882 function get_time_period(name);
 883 ```
 884
 885 Returns the TimePeriod object with the specified name, or `null` if no such TimePeriod object exists.
 886
 887
 888 ### get_object <a id="objref-get_object"></a>
 889
 890 Signature:
 891
 892 ```
 893 function get_object(type, name);
 894 ```
 895
 896 Returns the object with the specified type and name, or `null` if no such object exists. `type` must refer
 897 to a type object.
 898
 899
 900 ### get_objects <a id="objref-get_objects"></a>
 901
 902 Signature:
 903
 904 ```
 905 function get_objects(type);
 906 ```
 907
 908 Returns an array of objects whose type matches the specified type. `type` must refer
 909 to a type object.
 910
 911
 912 ## Math object <a id="math-object"></a>
 913
 914 The global `Math` object can be used to access a number of mathematical constants
 915 and functions.
 916
 917 ### Math.E <a id="math-e"></a>
 918
 919 Euler's constant.
 920
 921 ### Math.LN2 <a id="math-ln2"></a>
 922
 923 Natural logarithm of 2.
 924
 925 ### Math.LN10 <a id="math-ln10"></a>
 926
 927 Natural logarithm of 10.
 928
 929 ### Math.LOG2E <a id="math-log2e"></a>
 930
 931 Base 2 logarithm of E.
 932
 933 ### Math.PI <a id="math-pi"></a>
 934
 935 The mathematical constant Pi.
 936
 937 ### Math.SQRT1_2 <a id="math-sqrt1_2"></a>
 938
 939 Square root of 1/2.
 940
 941 ### Math.SQRT2 <a id="math-sqrt2"></a>
 942
 943 Square root of 2.
 944
 945 ### Math.abs <a id="math-abs"></a>
 946
 947 Signature:
 948
 949 ```
 950 function abs(x);
 951 ```
 952
 953 Returns the absolute value of `x`.
 954
 955 ### Math.acos <a id="math-acos"></a>
 956
 957 Signature:
 958
 959 ```
 960 function acos(x);
 961 ```
 962
 963 Returns the arccosine of `x`.
 964
 965 ### Math.asin <a id="math-asin"></a>
 966
 967 Signature:
 968
 969 ```
 970 function asin(x);
 971 ```
 972
 973 Returns the arcsine of `x`.
 974
 975 ### Math.atan <a id="math-atan"></a>
 976
 977 Signature:
 978
 979 ```
 980 function atan(x);
 981 ```
 982
 983 Returns the arctangent of `x`.
 984
 985 ### Math.atan2 <a id="math-atan2"></a>
 986
 987 Signature:
 988
 989 ```
 990 function atan2(y, x);
 991 ```
 992 Returns the arctangent of the quotient of `y` and `x`.
 993
 994 ### Math.ceil <a id="math-ceil"></a>
 995
 996 Signature:
 997
 998 ```
 999 function ceil(x);
1000 ```
1001
1002 Returns the smallest integer value not less than `x`.
1003
1004 ### Math.cos <a id="math-cos"></a>
1005
1006 Signature:
1007
1008 ```
1009 function cos(x);
1010 ```
1011
1012 Returns the cosine of `x`.
1013
1014 ### Math.exp <a id="math-exp"></a>
1015
1016 Signature:
1017
1018 ```
1019 function exp(x);
1020 ```
1021
1022 Returns E raised to the `x`th power.
1023
1024 ### Math.floor <a id="math-floor"></a>
1025
1026 Signature:
1027
1028 ```
1029 function floor(x);
1030 ```
1031
1032 Returns the largest integer value not greater than `x`.
1033
1034 ### Math.isinf <a id="math-isinf"></a>
1035
1036 Signature:
1037
1038 ```
1039 function isinf(x);
1040 ```
1041
1042 Returns whether `x` is infinite.
1043
1044 ### Math.isnan <a id="math-isnan"></a>
1045
1046 Signature:
1047
1048 ```
1049 function isnan(x);
1050 ```
1051
1052 Returns whether `x` is NaN (not-a-number).
1053
1054 ### Math.log <a id="math-log"></a>
1055
1056 Signature:
1057
1058 ```
1059 function log(x);
1060 ```
1061
1062 Returns the natural logarithm of `x`.
1063
1064 ### Math.max <a id="math-max"></a>
1065
1066 Signature:
1067
1068 ```
1069 function max(...);
1070 ```
1071
1072 Returns the largest argument. A variable number of arguments can be specified.
1073 If no arguments are given, -Infinity is returned.
1074
1075 ### Math.min <a id="math-min"></a>
1076
1077 Signature:
1078
1079 ```
1080 function min(...);
1081 ```
1082
1083 Returns the smallest argument. A variable number of arguments can be specified.
1084 If no arguments are given, +Infinity is returned.
1085
1086 ### Math.pow <a id="math-pow"></a>
1087
1088 Signature:
1089
1090 ```
1091 function pow(x, y);
1092 ```
1093
1094 Returns `x` raised to the `y`th power.
1095
1096 ### Math.random <a id="math-random"></a>
1097
1098 Signature:
1099
1100 ```
1101 function random();
1102 ```
1103
1104 Returns a pseudo-random number between 0 and 1.
1105
1106 ### Math.round <a id="math-round"></a>
1107
1108 Signature:
1109
1110 ```
1111 function round(x);
1112 ```
1113
1114 Returns `x` rounded to the nearest integer value.
1115
1116 ### Math.sign <a id="math-sign"></a>
1117
1118 Signature:
1119
1120 ```
1121 function sign(x);
1122 ```
1123
1124 Returns -1 if `x` is negative, 1 if `x` is positive
1125 and 0 if `x` is 0.
1126
1127 ### Math.sin <a id="math-sin"></a>
1128
1129 Signature:
1130
1131 ```
1132 function sin(x);
1133 ```
1134
1135 Returns the sine of `x`.
1136
1137 ### Math.sqrt <a id="math-sqrt"></a>
1138
1139 Signature:
1140
1141 ```
1142 function sqrt(x);
1143 ```
1144
1145 Returns the square root of `x`.
1146
1147 ### Math.tan <a id="math-tan"></a>
1148
1149 Signature:
1150
1151 ```
1152 function tan(x);
1153 ```
1154
1155 Returns the tangent of `x`.
1156
1157 ## Json object <a id="json-object"></a>
1158
1159 The global `Json` object can be used to encode and decode JSON.
1160
1161 ### Json.encode <a id="json-encode"></a>
1162
1163 Signature:
1164
1165 ```
1166 function encode(x);
1167 ```
1168
1169 Encodes an arbitrary value into JSON.
1170
1171 ### Json.decode <a id="json-decode"></a>
1172
1173 Signature:
1174
1175 ```
1176 function decode(x);
1177 ```
1178
1179 Decodes a JSON string.
1180
1181 ## Number type <a id="number-type"></a>
1182
1183 ### Number#to_string <a id="number-to_string"></a>
1184
1185 Signature:
1186
1187 ```
1188 function to_string();
1189 ```
1190
1191 The `to_string` method returns a string representation of the number.
1192
1193 Example:
1194
1195 ```
1196 var example = 7
1197         example.to_string() /* Returns "7" */
1198 ```
1199
1200 ## Boolean type <a id="boolean-type"></a>
1201
1202 ### Boolean#to_string <a id="boolean-to_string"></a>
1203
1204 Signature:
1205
1206 ```
1207 function to_string();
1208 ```
1209
1210 The `to_string` method returns a string representation of the boolean value.
1211
1212 Example:
1213
1214 ```
1215 var example = true
1216         example.to_string() /* Returns "true" */
1217 ```
1218
1219 ## String type <a id="string-type"></a>
1220
1221 ### String#find <a id="string-find"></a>
1222
1223 Signature:
1224
1225 ```
1226 function find(str, start);
1227 ```
1228
1229 Returns the zero-based index at which the string `str` was found in the string. If the string
1230 was not found, -1 is returned. `start` specifies the zero-based index at which `find` should
1231 start looking for the string (defaults to 0 when not specified).
1232
1233 Example:
1234
1235 ```
1236 "Hello World".find("World") /* Returns 6 */
1237 ```
1238
1239 ### String#contains <a id="string-contains"></a>
1240
1241 Signature:
1242
1243 ```
1244 function contains(str);
1245 ```
1246
1247 Returns `true` if the string `str` was found in the string. If the string
1248 was not found, `false` is returned. Use [find](18-library-reference.md#string-find)
1249 for getting the index instead.
1250
1251 Example:
1252
1253 ```
1254 "Hello World".contains("World") /* Returns true */
1255 ```
1256
1257 ### String#len <a id="string-len"></a>
1258
1259 Signature
1260
1261 ```
1262 function len();
1263 ```
1264
1265 Returns the length of the string in bytes. Note that depending on the encoding type of the string
1266 this is not necessarily the number of characters.
1267
1268 Example:
1269
1270 ```
1271 "Hello World".len() /* Returns 11 */
1272 ```
1273
1274 ### String#lower <a id="string-lower"></a>
1275
1276 Signature:
1277
1278 ```
1279 function lower();
1280 ```
1281
1282 Returns a copy of the string with all of its characters converted to lower-case.
1283
1284 Example:
1285
1286 ```
1287 "Hello World".lower() /* Returns "hello world" */
1288 ```
1289
1290 ### String#upper <a id="string-upper"></a>
1291
1292 Signature:
1293
1294 ```
1295 function upper();
1296 ```
1297
1298 Returns a copy of the string with all of its characters converted to upper-case.
1299
1300 Example:
1301
1302 ```
1303 "Hello World".upper() /* Returns "HELLO WORLD" */
1304 ```
1305
1306 ### String#replace <a id="string-replace"></a>
1307
1308 Signature:
1309
1310 ```
1311 function replace(search, replacement);
1312 ```
1313
1314 Returns a copy of the string with all occurences of the string specified in `search` replaced
1315 with the string specified in `replacement`.
1316
1317 ### String#split <a id="string-split"></a>
1318
1319 Signature:
1320
1321 ```
1322 function split(delimiters);
1323 ```
1324
1325 Splits a string into individual parts and returns them as an array. The `delimiters` argument
1326 specifies the characters which should be used as delimiters between parts.
1327
1328 Example:
1329
1330 ```
1331 "x-7,y".split("-,") /* Returns [ "x", "7", "y" ] */
1332 ```
1333
1334 ### String#substr <a id="string-substr"></a>
1335
1336 Signature:
1337
1338 ```
1339 function substr(start, len);
1340 ```
1341
1342 Returns a part of a string. The `start` argument specifies the zero-based index at which the part begins.
1343 The optional `len` argument specifies the length of the part ("until the end of the string" if omitted).
1344
1345 Example:
1346
1347 ```
1348 "Hello World".substr(6) /* Returns "World" */
1349 ```
1350
1351 ### String#to_string <a id="string-to_string"></a>
1352
1353 Signature:
1354
1355 ```
1356 function to_string();
1357 ```
1358
1359 Returns a copy of the string.
1360
1361 ### String#reverse <a id="string-reverse"></a>
1362
1363 Signature:
1364
1365 ```
1366 function reverse();
1367 ```
1368
1369 Returns a copy of the string in reverse order.
1370
1371 ### String#trim <a id="string-trim"></a>
1372
1373 Signature:
1374
1375 ```
1376 function trim();
1377 ```
1378
1379 Removes trailing whitespaces and returns the string.
1380
1381 ## Object type <a id="object-type"></a>
1382
1383 This is the base type for all types in the Icinga application.
1384
1385 ### Object#clone <a id="object-clone"></a>
1386
1387 Signature:
1388
1389 ```
1390  function clone();
1391 ```
1392
1393 Returns a copy of the object. Note that for object elements which are
1394 reference values (e.g. objects such as arrays or dictionaries) the entire
1395 object is recursively copied.
1396
1397 ### Object#to_string <a id="object-to-string"></a>
1398
1399 Signature:
1400
1401 ```
1402 function to_string();
1403 ```
1404
1405 Returns a string representation for the object. Unless overridden this returns a string
1406 of the format "Object of type '<typename>'" where <typename> is the name of the
1407 object's type.
1408
1409 Example:
1410
1411 ```
1412 [ 3, true ].to_string() /* Returns "[ 3.000000, true ]" */
1413 ```
1414
1415 ### Object#type <a id="object-type-field"></a>
1416
1417 Signature:
1418
1419 String type;
1420
1421 Returns the object's type name. This attribute is read-only.
1422
1423 Example:
1424
1425 ```
1426 get_host("localhost").type /* Returns "Host" */
1427 ```
1428
1429 ## Type type <a id="type-type"></a>
1430
1431 Inherits methods from the [Object type](18-library-reference.md#object-type).
1432
1433 The `Type` type provides information about the underlying type of an object or scalar value.
1434
1435 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.
1436
1437 ### Type#base <a id="type-base"></a>
1438
1439 Signature:
1440
1441 ```
1442 Type base;
1443 ```
1444
1445 Returns a reference to the type's base type. This attribute is read-only.
1446
1447 Example:
1448
1449 ```
1450 Dictionary.base == Object /* Returns true, because the Dictionary type inherits directly from the Object type. */
1451 ```
1452
1453 ### Type#name <a id="type-name"></a>
1454
1455 Signature:
1456
1457 ```
1458 String name;
1459 ```
1460
1461 Returns the name of the type.
1462
1463 ### Type#prototype <a id="type-prototype"></a>
1464
1465 Signature:
1466
1467 ```
1468 Object prototype;
1469 ```
1470
1471 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.
1472
1473 The prototype functionality is used to implement methods.
1474
1475 Example:
1476
1477 ```
1478 3.to_string() /* Even though '3' does not have a to_string property the Number type's prototype object does. */
1479 ```
1480
1481 ## Array type <a id="array-type"></a>
1482
1483 Inherits methods from the [Object type](18-library-reference.md#object-type).
1484
1485 ### Array#add <a id="array-add"></a>
1486
1487 Signature:
1488
1489 ```
1490 function add(value);
1491 ```
1492
1493 Adds a new value after the last element in the array.
1494
1495 ### Array#clear <a id="array-clear"></a>
1496
1497 Signature:
1498
1499 ```
1500 function clear();
1501 ```
1502
1503 Removes all elements from the array.
1504
1505 ### Array#shallow_clone <a id="array-shallow-clone"></a>
1506
1507 ```
1508 function shallow_clone();
1509 ```
1510
1511 Returns a copy of the array. Note that for elements which are reference values (e.g. objects such
1512 as arrays and dictionaries) only the references are copied.
1513
1514 ### Array#contains <a id="array-contains"></a>
1515
1516 Signature:
1517
1518 ```
1519 function contains(value);
1520 ```
1521
1522 Returns true if the array contains the specified value, false otherwise.
1523
1524 ### Array#freeze <a id="array-freeze"></a>
1525
1526 Signature:
1527
1528 ```
1529 function freeze()
1530 ```
1531
1532 Disallows further modifications to this array. Trying to modify the array will result in an exception.
1533
1534 ### Array#len <a id="array-len"></a>
1535
1536 Signature:
1537
1538 ```
1539 function len();
1540 ```
1541
1542 Returns the number of elements contained in the array.
1543
1544 ### Array#remove <a id="array-remove"></a>
1545
1546 Signature:
1547
1548 ```
1549 function remove(index);
1550 ```
1551
1552 Removes the element at the specified zero-based index.
1553
1554 ### Array#set <a id="array-set"></a>
1555
1556 Signature:
1557
1558 ```
1559 function set(index, value);
1560 ```
1561
1562 Sets the element at the zero-based index to the specified value. The `index` must refer to an element
1563 which already exists in the array.
1564
1565 ### Array#get <a id="array-get"></a>
1566
1567 Signature:
1568
1569 ```
1570 function get(index);
1571 ```
1572
1573 Retrieves the element at the specified zero-based index.
1574
1575 ### Array#sort <a id="array-sort"></a>
1576
1577 Signature:
1578
1579 ```
1580 function sort(less_cmp);
1581 ```
1582
1583 Returns a copy of the array where all items are sorted. The items are
1584 compared using the `<` (less-than) operator. A custom comparator function
1585 can be specified with the `less_cmp` argument.
1586
1587 ### Array#join <a id="array-join"></a>
1588
1589 Signature:
1590
1591 ```
1592 function join(separator);
1593 ```
1594
1595 Joins all elements of the array using the specified separator.
1596
1597 ### Array#reverse <a id="array-reverse"></a>
1598
1599 Signature:
1600
1601 ```
1602 function reverse();
1603 ```
1604
1605 Returns a new array with all elements of the current array in reverse order.
1606
1607 ### Array#map <a id="array-map"></a>
1608
1609 Signature:
1610
1611 ```
1612 function map(func);
1613 ```
1614
1615 Calls `func(element)` for each of the elements in the array and returns
1616 a new array containing the return values of these function calls.
1617
1618 ### Array#reduce <a id="array-reduce"></a>
1619
1620 Signature:
1621
1622 ```
1623 function reduce(func);
1624 ```
1625
1626 Reduces the elements of the array into a single value by calling the provided
1627 function `func` as `func(a, b)` repeatedly where `a` and `b` are elements of the array
1628 or results from previous function calls.
1629
1630 ### Array#filter <a id="array-filter"></a>
1631
1632 Signature:
1633
1634 ```
1635 function filter(func);
1636 ```
1637
1638 Returns a copy of the array containing only the elements for which `func(element)`
1639 is true.
1640
1641 ### Array#any <a id="array-any"></a>
1642
1643 Signature:
1644
1645 ```
1646 function any(func);
1647 ```
1648
1649 Returns true if the array contains at least one element for which `func(element)`
1650 is true, false otherwise.
1651
1652 ### Array#all <a id="array-all"></a>
1653
1654 Signature:
1655
1656 ```
1657 function all(func);
1658 ```
1659
1660 Returns true if the array contains only elements for which `func(element)`
1661 is true, false otherwise.
1662
1663 ### Array#unique <a id="array-unique"></a>
1664
1665 Signature:
1666
1667 ```
1668 function unique();
1669 ```
1670
1671 Returns a copy of the array with all duplicate elements removed. The original order
1672 of the array is not preserved.
1673
1674 ## Dictionary type <a id="dictionary-type"></a>
1675
1676 Inherits methods from the [Object type](18-library-reference.md#object-type).
1677
1678 ### Dictionary#shallow_clone <a id="dictionary-shallow-clone"></a>
1679
1680 Signature:
1681
1682 ```
1683 function shallow_clone();
1684 ```
1685
1686 Returns a copy of the dictionary. Note that for elements which are reference values (e.g. objects such
1687 as arrays and dictionaries) only the references are copied.
1688
1689 ### Dictionary#contains <a id="dictionary-contains"></a>
1690
1691 Signature:
1692
1693 ```
1694 function contains(key);
1695 ```
1696
1697 Returns true if a dictionary item with the specified `key` exists, false otherwise.
1698
1699 ### Dictionary#freeze <a id="dictionary-freeze"></a>
1700
1701 Signature:
1702
1703 ```
1704 function freeze()
1705 ```
1706
1707 Disallows further modifications to this dictionary. Trying to modify the dictionary will result in an exception.
1708
1709 ### Dictionary#len <a id="dictionary-len"></a>
1710
1711 Signature:
1712
1713 ```
1714 function len();
1715 ```
1716
1717 Returns the number of items contained in the dictionary.
1718
1719 ### Dictionary#remove <a id="dictionary-remove"></a>
1720
1721 Signature:
1722
1723 ```
1724 function remove(key);
1725 ```
1726
1727 Removes the item with the specified `key`. Trying to remove an item which does not exist
1728 is a no-op.
1729
1730 ### Dictionary#clear <a id="dictionary-clear"></a>
1731
1732 Signature:
1733
1734 ```
1735 function clear();
1736 ```
1737
1738 Removes all items from the dictionary.
1739
1740 ### Dictionary#set <a id="dictionary-set"></a>
1741
1742 Signature:
1743
1744 ```
1745 function set(key, value);
1746 ```
1747
1748 Creates or updates an item with the specified `key` and `value`.
1749
1750 ### Dictionary#get <a id="dictionary-get"></a>
1751
1752 Signature:
1753
1754 ```
1755 function get(key);
1756 ```
1757
1758 Retrieves the value for the specified `key`. Returns `null` if they `key` does not exist
1759 in the dictionary.
1760
1761 ### Dictionary#keys <a id="dictionary-keys"></a>
1762
1763 Signature:
1764
1765 ```
1766 function keys();
1767 ```
1768
1769 Returns a list of keys for all items that are currently in the dictionary.
1770
1771 ### Dictionary#values <a id="dictionary-values"></a>
1772
1773 Signature:
1774
1775 ```
1776 function values();
1777 ```
1778
1779 Returns a list of values for all items that are currently in the dictionary.
1780
1781 ## Function type <a id="scriptfunction-type"></a>
1782
1783 Inherits methods from the [Object type](18-library-reference.md#object-type).
1784
1785 ### Function#call <a id="scriptfunction-call"></a>
1786
1787 Signature:
1788
1789 ```
1790 function call(thisArg, ...);
1791 ```
1792
1793 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1794 scope for the function. All other arguments are passed directly to the function.
1795
1796 Example:
1797
1798 ```
1799 function set_x(val) {
1800   this.x = val
1801 }
1802
1803 dict = {}
1804
1805 set_x.call(dict, 7) /* Invokes set_x using `dict` as `this` */
1806 ```
1807
1808 ### Function#callv <a id="scriptfunction-callv"></a>
1809
1810 Signature:
1811
1812 ```
1813 function callv(thisArg, args);
1814 ```
1815
1816 Invokes the function using an alternative `this` scope. The `thisArg` argument specifies the `this`
1817 scope for the function. The items in the `args` array are passed to the function as individual arguments.
1818
1819 Example:
1820
1821 ```
1822 function set_x(val) {
1823   this.x = val
1824 }
1825
1826 var dict = {}
1827
1828 var args = [ 7 ]
1829
1830 set_x.callv(dict, args) /* Invokes set_x using `dict` as `this` */
1831 ```
1832
1833 ## DateTime type <a id="datetime-type"></a>
1834
1835 Inherits methods from the [Object type](18-library-reference.md#object-type).
1836
1837 ### DateTime constructor <a id="datetime-ctor"></a>
1838
1839 Signature:
1840
1841 ```
1842 function DateTime()
1843 function DateTime(unixTimestamp)
1844 function DateTime(year, month, day)
1845 function DateTime(year, month, day, hours, minutes, seconds)
1846 ```
1847
1848 Constructs a new DateTime object. When no arguments are specified for the constructor a new
1849 DateTime object representing the current time is created.
1850
1851 Example:
1852
1853 ```
1854 var d1 = DateTime() /* current time */
1855 var d2 = DateTime(2016, 5, 21) /* midnight April 21st, 2016 (local time) */
1856 ```
1857
1858 ### DateTime arithmetic <a id="datetime-arithmetic"></a>
1859
1860 Subtracting two DateTime objects yields the interval between them, in seconds.
1861
1862 Example:
1863
1864 ```
1865 var delta = DateTime() - DateTime(2016, 5, 21) /* seconds since midnight April 21st, 2016 */
1866 ```
1867
1868 Subtracting a number from a DateTime object yields a new DateTime object that is further in the past:
1869
1870 Example:
1871
1872 ```
1873 var dt = DateTime() - 2 * 60 * 60 /* Current time minus 2 hours */
1874 ```
1875
1876 Adding a number to a DateTime object yields a new DateTime object that is in the future:
1877
1878 Example:
1879
1880 ```
1881 var dt = DateTime() + 24 * 60 * 60 /* Current time plus 24 hours */
1882 ```
1883
1884 ### DateTime#format <a id="datetime-format"></a>
1885
1886 Signature:
1887
1888 ```
1889 function format(fmt)
1890 ```
1891
1892 Returns a string representation for the DateTime object using the specified format string.
1893 The format string may contain format conversion placeholders as specified in strftime(3).
1894
1895 Example:
1896
1897 ```
1898 var s = DateTime(2016, 4, 21).format("%A") /* Sets s to "Thursday". */
1899 ```
1900
1901 ### DateTime#to_string <a id="datetime-tostring"></a>
1902
1903 Signature:
1904
1905 ```
1906 function to_string()
1907 ```
1908
1909 Returns a string representation for the DateTime object. Uses a suitable default format.
1910
1911 Example:
1912
1913 ```
1914 var s = DateTime(2016, 4, 21).to_string() /* Sets s to "2016-04-21 00:00:00 +0200". */
1915 ```