---
title: Dealing with dates, times and durations
slug: v111/dealing-with-dates-times-and-durations
icon: {"faIcon":"fa-solid fa-calendar"}
docTags: 
createdAt: 2025-06-10T06:44:31.749Z
---

:::hint{type="warning"}
This article requires Javascript knowledge.
:::

# Dates and times

***

Servicely comes with an object called **DateTime**. There is one static instance of this object that can be used to access contants (see below). A new DateTime object can be created by using this construct:

```text
var d = DateTime();
```

DateTime comes with many *[withXXX()](#)* modifiers that can be chained because they all return the same DateTime object. This makes the initialisation of a new object quite easy because we can put that kind of constructs together:

```text
var d = DateTime().withDate(1997, 7, 26).withTimeAtStartOfDay().withLang('fr').withZone('Europe/Brussels');
```

DateTime also comes with many very useful functions to manipulate and display dates and times. They are all explained in the following chapters.

### Note

In all the examples of this section we will use this date and time as an example:
April 6th, 1968 at 18:25:32 (or 6:25:32 PM) and 678 milliseconds.

The ISO-8601 string representation of this date/time is:
1968-04-06T18:25:32.678

## Static constants

Servicely comes with a static global DateTime object and a set of constants that can be used to make the source code more readable.

| Constant                                       | Value       | Represents                        |
| ---------------------------------------------- | ----------- | --------------------------------- |
| DateTime.JANUARY                               | 1           | The month of January              |
| DateTime.FEBRUARY                              | 2           | The month of February             |
| DateTime.MARCH                                 | 3           | The month of March                |
| DateTime.APRIL                                 | 4           | The month of April                |
| DateTime.MAY                                   | 5           | The month of May                  |
| DateTime.JUNE                                  | 6           | The month of June                 |
| DateTime.JULY                                  | 7           | The month of July                 |
| DateTime.AUGUST                                | 8           | The month of August               |
| DateTime.SEPTEMBER                             | 9           | The month of September            |
| DateTime.OCTOBER                               | 10          | The month of October              |
| DateTime.NOVEMBER                              | 11          | The month of November             |
| DateTime.DECEMBER                              | 12          | The month of December             |
| DateTime.MONDAY                                | 1           | The day of the week Monday        |
| DateTime.TUESDAY                               | 2           | The day of the week Tuesday       |
| DateTime.WEDNESDAY                             | 3           | The day of the week Wednesday     |
| DateTime.THURSDAY                              | 4           | The day of the week Thursday      |
| DateTime.FRIDAY                                | 5           | The day of the week Friday        |
| DateTime.SATURDAY                              | 6           | The day of the week Saturday      |
| DateTime.SUNDAY                                | 7           | The day of the week Sunday        |
| [DateTime.AM](http://DateTime.AM)              | 0           | The morning                       |
| [DateTime.PM](http://DateTime.PM)              | 1           | The afternoon                     |
| DateTime.BC DateTime.BCE                       | 0           | Before Christ Before Common Era   |
| [DateTime.AD](http://DateTime.AD) DateTime.CE  | 1           | Anno Domini Common Era            |
| DateTime.MILLIS\_PER\_SECOND                   | 1,000       | Number of milliseconds per second |
| DateTime.MILLIS\_PER\_MINUTE                   | 60,000      | Number of milliseconds per hour   |
| DateTime.MILLIS\_PER\_HOUR                     | 3,600,000   | Number of milliseconds per hour   |
| DateTime.MILLIS\_PER\_DAY                      | 86,400,000  | Number of milliseconds per day    |
| DateTime.MILLIS\_PER\_WEEK                     | 604,800,000 | Number of milliseconds per week   |
| DateTime.SECONDS\_PER\_MINUTE                  | 60          | Number of seconds per minute      |
| DateTime.SECONDS\_PER\_HOUR                    | 3,600       | Number of seconds per hour        |
| DateTime.SECONDS\_PER\_DAY                     | 86,400      | Number of seconds per day         |
| DateTime.SECONDS\_PER\_WEEK                    | 604,800     | Number of seconds per week        |
| DateTime.MINUTES\_PER\_HOUR                    | 60          | Number of minutes per hour        |
| DateTime.MINUTES\_PER\_DAY                     | 1,440       | Number of minutes per day         |
| DateTime.MINUTES\_PER\_WEEK                    | 10,080      | Number of minutes per week        |
| DateTime.HOURS\_PER\_DAY                       | 24          | Number of hours per day           |
| DateTime.HOURS\_PER\_WEEK                      | 168         | Number of hours per week          |
| DateTime.DAYS\_PER\_WEEK                       | 7           | Number of days per week           |

## Available functions

| Function                                                | Returns  | Description                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ***Getters***                                           |          |                                                                                                                                                                                                                                                                                                                                           |
| getYear()                                               | Integer  | Returns the year of the given DateTime object.                                                                                                                                                                                                                                                                                            |
| getMonthOfYear()                                        | Integer  | Returns the month of the given DateTime object. Note that January has the value of 1.                                                                                                                                                                                                                                                     |
| getDayOfMonth()                                         | Integer  | Returns the day of the month of the given DateTime object.                                                                                                                                                                                                                                                                                |
| getHourOfDay()                                          | Integer  | Returns the hour of the given DateTime object.                                                                                                                                                                                                                                                                                            |
| getMinuteOfHour()                                       | Integer  | Returns the minute number of the given DateTime object.                                                                                                                                                                                                                                                                                   |
| getSecondOfMinute()                                     | Integer  | Returns the second number of the given DateTime object.                                                                                                                                                                                                                                                                                   |
| getMillisOfSecond()                                     | Integer  | Returns the millisecond number of the given DateTime object.                                                                                                                                                                                                                                                                              |
| getZone()                                               | String   | Returns the current time zone of the given DateTime object. Returns an empty string if no specific time zone has been set for this object - see *[withZone()](#)* function.                                                                                                                                                               |
| ***withXXX()***\*\* modifiers\*\*                       |          |                                                                                                                                                                                                                                                                                                                                           |
| withDate(\_year, \_month, \_day)                        | DateTime | Sets the date to the one corresponding *\_year*, *\_month* and *\_day* and returns the modified object. Calling *withDate()* with no parameters defaults the date to 31 December 1900. Note that it leaves the time untouched.                                                                                                            |
| withTime(\_hour, \_minute, \_second, \_millisecond      | DateTime | Sets the time to the one corresponding to *\_hour*, *\_minutes*, *\_second, \_millisecond*. Any ommited parameter will be defaulted to 0. Calling *withTime()* with no parameters at all will default the time to 00:00:00.000. Note that it leaves the date untouched.                                                                   |
| withYear(\_year)                                        | DateTime | Sets the year to *\_year* and returns the modified object.                                                                                                                                                                                                                                                                                |
| withMonthOfYear(\_month)                                | DateTime | Sets the month to *\_month* and returns the modified object.                                                                                                                                                                                                                                                                              |
| withDayOfMonth(\_day)                                   | DateTime | Sets the day to *\_day* and returns the modified object.                                                                                                                                                                                                                                                                                  |
| withHourOfDay(\_hour)                                   | DateTime | Sets the hour to *\_hour* and returns the modified object.                                                                                                                                                                                                                                                                                |
| withMinuteOfHour(\_minute)                              | DateTime | Sets the day to *\_minute* and returns the modified object.                                                                                                                                                                                                                                                                               |
| withSecondsOfMinute(\_seconds)                          | DateTime | Sets the minute to \_*seconds* and returns the modified object.                                                                                                                                                                                                                                                                           |
| withMillisOfSecond(\_milliseconds)                      | DateTime | Sets the millisecond to *\_milliseconds* and returns the modified object.                                                                                                                                                                                                                                                                 |
| withTimeAtStartOfDay()                                  | DateTime | Sets the time of the DateTime object to the start of the day, that is 00:00:00.000 in the object current time zone.                                                                                                                                                                                                                       |
| withLang(\_language)                                    | DateTime | Sets the language of the DateTime to *\_language*. We use the ISO 639-1 two-letter codes for representing the language; the list can be found [here](http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).                                                                                                                               |
| withZone(\_timeZone)                                    | DateTime | Sets the time zone of the DateTime. See section [About the time zone](#) for more information about the time zone and the DateTime object.                                                                                                                                                                                                |
| ***Date and time comparisons***                         |          |                                                                                                                                                                                                                                                                                                                                           |
| isEqual(\_dateTime)                                     | Boolean  | Returns *true* if *\_dateTime* has exactly the same date *and* time of the object, *false* otherwise.                                                                                                                                                                                                                                     |
| isAfter(\_dateTime)                                     | Boolean  | Returns \*true \*if *\_dateTime* if strictly after the date and time of the object, *false* otherwise.                                                                                                                                                                                                                                    |
| isBefore(\_dateTime)                                    | Boolean  | Returns \*true \*if *\_dateTime* if strictly before the date and time of the object, *false* otherwise.                                                                                                                                                                                                                                   |
| isAfterOrEqualTo(\_dateTime)                            | Boolean  | Returns \*true \*if *\_dateTime* if after or equal the date and time of the object, *false* otherwise.                                                                                                                                                                                                                                    |
| isBeforeOrEqualTo(\_dateTime)                           | Boolean  | Returns \*true \*if *\_dateTime* if before or equal the date and time of the object, *false* otherwise.                                                                                                                                                                                                                                   |
| isSameDay(\_dateTime)                                   | Boolean  | Returns \*true \*if *\_dateTime* has the same date of the object, regardless of the time. Return *false* otherwise.                                                                                                                                                                                                                       |
| isLeapYear()                                            | Boolean  | Returns *true* if *\_dateTime* is in a leap year.                                                                                                                                                                                                                                                                                         |
| isDaylightSavings()                                     | Boolean  | Returns true if *\_dateTime* is in daylight savings time.                                                                                                                                                                                                                                                                                 |
| ***Doing your math!***                                  |          |                                                                                                                                                                                                                                                                                                                                           |
| plusYears(\_years) minusYears(\_years)                  | DateTime | Adds or substracts the number of *\_years* to the DateTime object and returns it.                                                                                                                                                                                                                                                         |
| plusMonths(\_months) minusMonths(\_months)              | DateTime | Adds or substracts the number of *\_months* to the DateTime object and returns it.                                                                                                                                                                                                                                                        |
| plusWeeks(\_weeks) minusWeeks(\_weeks)                  | DateTime | Adds or substracts the number of *\_weeks* to the DateTime object and returns it.                                                                                                                                                                                                                                                         |
| plusDays(\_days) minusDays(\_days)                      | DateTime | Adds or substracts the number of *\_days* to the DateTime object and returns it.                                                                                                                                                                                                                                                          |
| plusHours(\_hours) minusHours(\_hours)                  | DateTime | Adds or substracts the number of *\_hours* to the DateTime object and returns it.                                                                                                                                                                                                                                                         |
| plusMinutes(\_minutes) minusMinutes(\_minutes)          | DateTime | Adds or substracts the number of *\_minutes* to the DateTime object and returns it.                                                                                                                                                                                                                                                       |
| plusSeconds(\_seconds) minusSeconds(\_seconds)          | DateTime | Adds or substracts the number of *\_seconds* to the DateTime object and returns it.                                                                                                                                                                                                                                                       |
| plusMillis(\_milliseconds) minusMillis(\_milliseconds)  | DateTime | Adds or substracts the number of *\_milliseconds* to the DateTime object and returns it.                                                                                                                                                                                                                                                  |
| plusDuration(duration)minusDuration(duration)           | Duration | Adds or subtracts the Duration from the DateTime object and returns it.                                                                                                                                                                                                                                                                   |
|                                                         |          |                                                                                                                                                                                                                                                                                                                                           |
| ***Formatting***                                        |          |                                                                                                                                                                                                                                                                                                                                           |
| format(\_formatter)                                     | String   | Format and returns the date/time using the pattern specified by the *\_formatter*. See section [Formatting date and time output](https://docs-servicely.atlassian.net/wiki/spaces/SD/pages/2140209155/Dealing+with+dates+times+and+durations#%5BinlineExtension%5DFormatting-the-date-and-time-output) for more information this subject. |
| toISOFormat()                                           | String   | Returns the ISO 8601 format of the date and time. More information about this format can be found [here](http://en.wikipedia.org/wiki/ISO_8601).                                                                                                                                                                                          |
| toString()                                              | String   | Returns an ISO 8601 formatted string of the date/time. *toString()* is similar to *toISOFormat()* with the exception of the time offset representation: if there is none the letter "Z" will be displayed instead of +00:00.  \`\`\`                                                                                                      |
| DateTime().withZone('GMT').toString();                  |          |                                                                                                                                                                                                                                                                                                                                           |
| \`\`\`> \`2013-11-20T10:08:14.363Z\`\`\`\`              |          |                                                                                                                                                                                                                                                                                                                                           |
| DateTime().withZone('GMT').toISOFormat();               |          |                                                                                                                                                                                                                                                                                                                                           |
| \`\`\`> `2013-11-20T10:08:14.363+00:00`                 |          |                                                                                                                                                                                                                                                                                                                                           |
| fromNow()                                               | String   | Returns a string indicating the elapsed time between now and the DateTime object. The string can be one of those patterns:- ***in** \<litteral\_number> year(s) \| month(s) \| day(s) \| hour(s) \| minute(s) \| second(s)*                                                                                                               |

- *\<litteral\_number> year(s) | month(s) | day(s) | hour(s) | minute(s) | second(s) **ago***
- ***in** a few seconds*
- *a few seconds*\* ago\*\*\*Depending on whether the current time is before or after the DateTime object. The string patterns above are in English but note that they are localised; therefore you will obtain a different string if you have changed the language with *[withLang()](#)*. |
  \| ***Truncating times***                                  |          |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
  \| truncateHours()                                         | DateTime | Returns a DateTime with the hours, minutes, seconds, and milliseconds components zeroed out.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
  \| truncateMinutes()                                       | DateTime | Returns a DateTime with the minutes, seconds, and milliseconds components zeroed out.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
  \| truncateSeconds()                                       | DateTime | Returns a DateTime with the seconds and milliseconds components zeroed out.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
  \| truncateMillis()                                        | DateTime | Returns a DateTime with the milliseconds component zeroed out.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
  \| toStartOfDay()                                          | DateTime | Returns a DateTime with the Time component set to 00:00:00.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
  \| toEndOfDay()                                            | DateTime | Returns a DateTime with the Time component set to 23:59:59.999                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

If you don’t see the DateTime you need, we have other less used API options found [here](docId\:g6K-LF0tzPi4HyvWkqoKM).

## About the time zone

When dealing with dates and times, it is very important to always consider what time zone we work in. By default, DateTime parses and displays in local time, that is the time of the system Servicely runs on.

We can use function *[withZone()](#)* to change the time zone we work against:

```text
DateTime().withZone('Europe/Paris');
```

We use the [TZ database](http://en.wikipedia.org/wiki/Tz_database) naming convention which is in the form of "Area/Location", e.g. "America/New\_York". Punctuation is omitted and the underscore character is used in place of spaces. Hyphens are used where they appear in the name of a location. The list of the currently supported time zones can be found [here](#).

It is vital for the DateTime object to always work with the proper time zone. Besides indicating the time difference, the time zone also has important properties like daylight savings. Not setting the correct time zone may result in improper date conversions and calculations.

## Getting current date and time

To get the current date and time, just create a new `DateTime()` with no parameters.

```text
var now = DateTime();
```

## Getting a specific date and time

To obtain a DateTime object set with a date time of your choice, pass an array of the date/time elements to the constructor:

```text
var d = DateTime( [ 1968, DateTime.APRIL, 6, 18, 25, 32, 678 ] );
```

The above returns a DateTime object set to November 27th, 1968 with time 18:25:32 and 678 milliseconds.

The structure of the array is:
\[ year, month, day, hour, minute, second, millisecond ] 

Where *year* and *month* are mandatory. Any other elements will be defaulted by the constructor should they be missing: the day will be defaulted to 1 and all the time elements will be defaulted to 0.

Another way of initializing a date/time object is to use a combination of *withDate()* and *withTime()* functions. Setting the a DateTime object to the same value than above would be achieved by this construct:

```text
var d = DateTime().withDate(1968, DateTime.APRIL, 6).withTime(18, 25, 32, 678);
```

Finally, we can go one level down and call each specific modifier function for each element of the date/time. This (very unlikely) construct would be like this:

```text
var d = DateTime().
    withYear(1968).
    withMonthOfYear(DateTime.APRIL).
    withDayOfMonth(6).
    withHourOfDay(18).
    withMinuteOfHour(25).
    withSecondsOfMinute(32).
    withMillisOfSecond(678);
```

## Formatting the date and time output

A DateTime object can be printed in any desired format by using the *format()* function. It takes a formatter string made of tokens and replaces them with their corresponding values.

The table below lists the available tokens:

| &#x20;                |           |                                        |
| --------------------- | --------- | -------------------------------------- |
| **Date/time element** | **Token** | **Output**                             |
| **Month**             | M         | 1 2 ... 11 12                          |
|                       | Mo        | 1st 2nd ... 11th 12th                  |
|                       | MM        | 01 02 ... 11 12                        |
|                       | MMM       | Jan Feb ... Nov Dec                    |
|                       | MMMM      | January February ... November December |
| **Day of month**      | D         | 1 2 ... 30 31                          |
|                       | Do        | 1st 2nd ... 30th 31st                  |
|                       | DD        | 01 02 ... 30 31                        |
| **Day of year**       | DDD       | 1 2 ... 364 365                        |
|                       | DDDo      | 1st 2nd ... 364th 365th                |
|                       | DDDD      | 001 002 ... 364 365                    |
| **Day of week**       | d         | 0 1 ... 5 6                            |
|                       | do        | 0th 1st ... 5th 6th                    |
|                       | dd        | Su Mo ... Fr Sa                        |
|                       | ddd       | Sun Mon ... Fri Sat                    |
|                       | dddd      | Sunday Monday ... Friday Saturday      |
| **Week of year**      | w         | 1 2 ... 52 53                          |
|                       | wo        | 1st 2nd ... 52nd 53rd                  |
|                       | ww        | 01 02 ... 52 53                        |
| **Year**              | YY        | 70 71 ... 29 30                        |
|                       | YYYY      | 1970 1971 ... 2029 2030                |
| **AM/PM**             | A         | AM PM                                  |
|                       | a         | am pm                                  |
| **Hour**              | H         | 0 1 ... 22 23                          |
|                       | HH        | 00 01 ... 22 23                        |
|                       | h         | 1 2 ... 11 12                          |
|                       | hh        | 01 02 ... 11 12                        |
| **Minute**            | m         | 0 1 ... 58 59                          |
|                       | mm        | 00 01 ... 58 59                        |
| **Second**            | s         | 0 1 ... 58 59                          |
|                       | ss        | 00 01 ... 58 59                        |
| **Fractional second** | S         | 0 1 ... 8 9                            |
|                       | SS        | 0 1 ... 98 99                          |
|                       | SSS       | 0 1 ... 998 999                        |
| **Time zone**         | Z         | -07:00 -06:00 ... +06:00 +07:00        |
|                       | ZZ        | -0700 -0600 ... +0600 +0700            |
| **Unix timestamp**    | X         | 1360013296                             |

Note that using *format()* with no formatter will return the ISO format string, without the milliseconds:

```text
DateTime().format();
```

:::BlockQuote
`2013-11-20T10:14:46+10:00`
:::

### Pre-built formatters

DateTime comes with prebuilt formatters, summarised in the table below:

| &#x20;                                                |               |                                |
| ----------------------------------------------------- | ------------- | ------------------------------ |
| **Date/time element**                                 | **Formatter** | **Example output**             |
| **Time**                                              | LT            | 6:25 PM                        |
| **Month numeral, day of month, year**                 | L             | 04/06/1968                     |
|                                                       | l             | 4/6/1968                       |
| **Month name, day of month, year**                    | LL            | April 6 1968                   |
|                                                       | ll            | Apr 6 1968                     |
| **Month name, day of month, year, time**              | LLL           | April 6 1968 6:25 PM           |
|                                                       | lll           | Apr 6 1968 6:25 PM             |
| **Month name, day of month, day of week, year, time** | LLLL          | Saturday, April 6 1968 6:25 PM |
|                                                       | llll          | Sat, Apr 6 1968 6:25 PM        |

### Localising DateTime output

Any output will be localised, assuming the proper language has been set by using the *[withLang()](#)* function. 

For example: 

```text
DateTime( [ 1968, DateTime.APRIL, 6, 18, 25, 32, 678 ] ).format('llll');
```

:::BlockQuote
Sat, Apr 6 1968 6:25 PM
:::

Whereas:

```text
DateTime( [ 1968, DateTime.APRIL, 6, 18, 25, 32, 678 ] ).withLang('fr').format('llll');
```

:::BlockQuote
sam. 6 avr. 1968 18:25
:::

The following tokens and formatters are impacted by the localisation:

- All prebuilt formatters
- Mo, MMM, MMMM
- Do, DDDo
- do, ddd, dddd
- wo

### Escaping substrings

Any substrings in the formatter can be escaped by using square brackets, for example:

```text
DateTime( [ 1968, DateTime.APRIL, 6, 18, 25, 32, 678 ] ).format('LLL[ was a ]dddd[ and was the ]DDDo[day of the year.]');
```

:::BlockQuote
April 6 1968 6:25 PM was a Saturday and was the 97th day of the year.
:::

# Durations

***

Servicely uses ISO 8601 format for representing durations. It is a string made of a series of *value/capital letter* pairs. The capital letter designates the date and time element, using this convention: **P\[n]Y\[n]M\[n]DT\[n]H\[n]M\[n]S** where n represents the value for each of the date and time elements:

- *P* is the duration designator *always* placed at the start of the string, even there are no date elements in the duration;
- *Y* represents the years;
- *M* represents the months;
- *W* represents the weeks;
- *D* represents the days;
- *T* represents the time designator that precedes the time components of the representation. The time designator is present only if the duration has time elements in it;
- *H* represents the hours;
- *M* represents the minutes;
- *S* represents the seconds. Milliseconds are also represented using the "S" letter but with a decimal value. For example 400 milliseconds will be displayed using this notation: *PT0.400S*.

Examples:

- "P3Y6M4DT12H30M5S" represents\* three years, six months, four days, twelve hours, thirty minutes, and five seconds\*.
- "P6DT40S" represents\* six days and 40 seconds\*.
- "P1M" represents *one month*.
- "PT1M" represents *one minute*.

### Getting a brand new duration

A new duration can easily be created by instantiating a new Period object and using one of the *withXxx()* methods. Note that those function can be chained to build the exact wanted duration:

```text
var p = Period().withDays(5).withHours(10).withMinutes(25).withSeconds(40).withMillis(350);
log.info(p.toString());
```

This will display:

:::BlockQuote
`P5DT10H25M40.350S`
:::

### Getting a duration from two date-time's

An easy way of initializing a new duration is to take dates (possibly with time) and get the difference in a period format:

```text
var now = DateTime();
var earlier = DateTime().withDate(2020, 1, 1).withTime(15,30,0);
var duration = Duration(earlier, now);
var period = Period(duration);
period;
```

Would return something like that (depending on which day is today):

:::BlockQuote
`P6Y1M1W6DT13H59M26.849S`
:::

## Available functions

| Function                            | Returns  | Description                                                                                                               |
| ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| ***Getters***                       |          |                                                                                                                           |
| getStandardDays()                   | Integer  | Returns number of standardized days represented by the Duration                                                           |
| getStandardHours()                  | Integer  | Returns number of standardized hours represented by the Duration                                                          |
| getStandardMinutes()                | Integer  | Returns number of standardized minutes represented by the Duration                                                        |
| getStandardSeconds()                | Integer  | Returns number of standardized seconds represented by the Duration                                                        |
| getMillis()                         | Integer  | Returns number of milliseconds represented by the Duration                                                                |
| ***Methods***                       |          |                                                                                                                           |
| plus(duration \| period \| number)  | Duration | Adds the supplied Duration, Period, or Number (milliseconds) to the duration and returns it (original is immutable).      |
| minus(duration \| period \| number) | Duration | Subtracts the supplied Duration, Period, or Number (milliseconds) to the duration and returns it (original is immutable). |
| plusDays(number)                    | Duration | Adds the number of days to the duration (negative to subtract)                                                            |
| plusHours(number)                   | Duration | Adds the number of hours to the duration (negative to subtract)                                                           |
| plusMinutes(number)                 | Duration | Adds the number of minutes to the duration (negative to subtract)                                                         |
| plusSeconds(number)                 | Duration | Adds the number of hours to the duration (negative to subtract)                                                           |
| plusMillis(number)                  | Duration | Adds the number of milliseconds to the duration (negative to subtract)                                                    |
| minusDays(number)                   | Duration | Subtracts the number of days to the duration (requires release 1.5)                                                       |
| minusHours(number)                  | Duration | Subtracts the number of hours to the duration (requires release 1.5)                                                      |
| minusMinutes(number)                | Duration | Subtracts the number of minutes to the duration (requires release 1.5)                                                    |
| minusSeconds(number)                | Duration | Subtracts the number of hours to the duration (requires release 1.5)                                                      |
| minusMillis(number)                 | Duration | Subtracts the number of milliseconds to the duration (requires release 1.5)                                               |

# The PeriodCalculator object

***

# The LeaveCalculator object

***

# Addendum

***

### List of supported languages

| Language code | Language                                |
| ------------- | --------------------------------------- |
| ar            | Arabic                                  |
| ar-ma         | Moroccan Arabic                         |
| bg            | Bulgarian                               |
| ca            | Catalan                                 |
| cz            | Czech                                   |
| cv            | Chuvash                                 |
| da            | Danish                                  |
| de            | German                                  |
| el            | Modern Greek                            |
| en-ca         | Canadian English                        |
| en-gb         | Great Britain English                   |
| eo            | Esperanto                               |
| es            | Spanish                                 |
| et            | Estonian                                |
| eu            | Euskara                                 |
| fi            | Finnish                                 |
| fr            | French                                  |
| fr-ca         | Canadian French                         |
| gl            | Galician                                |
| he            | Hebrew                                  |
| hi            | Hindi                                   |
| hu            | Hungarian                               |
| id            | Bahasa Indonesia                        |
| is            | Icelandic                               |
| it            | Italian                                 |
| ja            | Japanese                                |
| ko            | Korean                                  |
| la            | Latvian                                 |
| ms-my         | Bahasa Malaysia                         |
| nb            | Norwegian Bokmål                        |
| ne            | Nepali/Nepalese                         |
| nl            | Dutch                                   |
| pl            | Polish                                  |
| pt            | Portuguese                              |
| pt-br         | Brazilian Portuguese                    |
| ro            | Romanian                                |
| ru            | Russian                                 |
| sl            | Slovenian                               |
| sv            | Swedish                                 |
| th            | Thai                                    |
| tr            | Turkish                                 |
| tzm           | Morocco Central Atlas Tamaziɣt          |
| tzm-la        | Morocco Central Atlas Tamaziɣt in Latin |
| uk            | Ukrainian                               |
| zh-cn         | Chinese                                 |
| zh-tw         | Traditional Chinese                     |

### List of time zones

Africa/Abidjan - Greenwich Mean Time
Africa/Accra - Ghana Mean Time
Africa/Addis Ababa - Eastern African Time
Africa/Algiers - Central European Time
Africa/Asmara - Eastern African Time
Africa/Asmera - Eastern African Time
Africa/Bamako - Greenwich Mean Time
Africa/Bangui - Western African Time
Africa/Banjul - Greenwich Mean Time
Africa/Bissau - Greenwich Mean Time
Africa/Blantyre - Central African Time
Africa/Brazzaville - Western African Time
Africa/Bujumbura - Central African Time
Africa/Cairo - Eastern European Time
Africa/Casablanca - Western European Time
Africa/Ceuta - Central European Time
Africa/Conakry - Greenwich Mean Time
Africa/Dakar - Greenwich Mean Time
Africa/Dar es Salaam - Eastern African Time
Africa/Djibouti - Eastern African Time
Africa/Douala - Western African Time
Africa/El Aaiun - Western European Time
Africa/Freetown - Greenwich Mean Time
Africa/Gaborone - Central African Time
Africa/Harare - Central African Time
Africa/Johannesburg - South Africa Standard Time
Africa/Kampala - Eastern African Time
Africa/Khartoum - Eastern African Time
Africa/Kigali - Central African Time
Africa/Kinshasa - Western African Time
Africa/Lagos - Western African Time
Africa/Libreville - Western African Time
Africa/Lome - Greenwich Mean Time
Africa/Luanda - Western African Time
Africa/Lubumbashi - Central African Time
Africa/Lusaka - Central African Time
Africa/Malabo - Western African Time
Africa/Maputo - Central African Time
Africa/Maseru - South Africa Standard Time
Africa/Mbabane - South Africa Standard Time
Africa/Mogadishu - Eastern African Time
Africa/Monrovia - Greenwich Mean Time
Africa/Nairobi - Eastern African Time
Africa/Ndjamena - Western African Time
Africa/Niamey - Western African Time
Africa/Nouakchott - Greenwich Mean Time
Africa/Ouagadougou - Greenwich Mean Time
Africa/Porto-Novo - Western African Time
Africa/Sao Tome - Greenwich Mean Time
Africa/Timbuktu - Greenwich Mean Time
Africa/Tripoli - Eastern European Time
Africa/Tunis - Central European Time
Africa/Windhoek - Western African Time
America/Adak - Hawaii-Aleutian Standard Time
America/Anchorage - Alaska Standard Time
America/Anguilla - Atlantic Standard Time
America/Antigua - Atlantic Standard Time
America/Araguaina - Brasilia Time
America/Argentina/Buenos Aires - Argentine Time
America/Argentina/Catamarca - Argentine Time
America/Argentina/ComodRivadavia - Argentine Time
America/Argentina/Cordoba - Argentine Time
America/Argentina/Jujuy - Argentine Time
America/Argentina/La Rioja - Argentine Time
America/Argentina/Mendoza - Argentine Time
America/Argentina/Rio Gallegos - Argentine Time
America/Argentina/Salta - Argentine Time
America/Argentina/San Juan - Argentine Time
America/Argentina/San Luis - Argentine Time
America/Argentina/Tucuman - Argentine Time
America/Argentina/Ushuaia - Argentine Time
America/Aruba - Atlantic Standard Time
America/Asuncion - Paraguay Time
America/Atikokan - Eastern Standard Time
America/Atka - Hawaii-Aleutian Standard Time
America/Bahia - Brasilia Time
America/Barbados - Atlantic Standard Time
America/Belem - Brasilia Time
America/Belize - Central Standard Time
America/Blanc-Sablon - Atlantic Standard Time
America/Boa Vista - Amazon Time
America/Bogota - Colombia Time
America/Boise - Mountain Standard Time
America/Buenos Aires - Argentine Time
America/Cambridge Bay - Mountain Standard Time
America/Campo Grande - Amazon Time
America/Cancun - Central Standard Time
America/Caracas - Venezuela Time
America/Catamarca - Argentine Time
America/Cayenne - French Guiana Time
America/Cayman - Eastern Standard Time
America/Chicago - Central Standard Time
America/Chihuahua - Mountain Standard Time
America/Coral Harbour - Eastern Standard Time
America/Cordoba - Argentine Time
America/Costa Rica - Central Standard Time
America/Cuiaba - Amazon Time
America/Curacao - Atlantic Standard Time
America/Danmarkshavn - Greenwich Mean Time
America/Dawson - Pacific Standard Time
America/Dawson Creek - Mountain Standard Time
America/Denver - Mountain Standard Time
America/Detroit - Eastern Standard Time
America/Dominica - Atlantic Standard Time
America/Edmonton - Mountain Standard Time
America/Eirunepe - Amazon Time
America/El Salvador - Central Standard Time
America/Ensenada - Pacific Standard Time
America/Fort Wayne - Eastern Standard Time
America/Fortaleza - Brasilia Time
America/Glace Bay - Atlantic Standard Time
America/Godthab - Western Greenland Time
America/Goose Bay - Atlantic Standard Time
America/Grand Turk - Eastern Standard Time
America/Grenada - Atlantic Standard Time
America/Guadeloupe - Atlantic Standard Time
America/Guatemala - Central Standard Time
America/Guayaquil - Ecuador Time
America/Guyana - Guyana Time
America/Halifax - Atlantic Standard Time
America/Havana - Cuba Standard Time
America/Hermosillo - Mountain Standard Time
America/Indiana/Indianapolis - Eastern Standard Time
America/Indiana/Knox - Central Standard Time
America/Indiana/Marengo - Eastern Standard Time
America/Indiana/Petersburg - Eastern Standard Time
America/Indiana/Tell City - Central Standard Time
America/Indiana/Vevay - Eastern Standard Time
America/Indiana/Vincennes - Eastern Standard Time
America/Indiana/Winamac - Eastern Standard Time
America/Indianapolis - Eastern Standard Time
America/Inuvik - Mountain Standard Time
America/Iqaluit - Eastern Standard Time
America/Jamaica - Eastern Standard Time
America/Jujuy - Argentine Time
America/Juneau - Alaska Standard Time
America/Kentucky/Louisville - Eastern Standard Time
America/Kentucky/Monticello - Eastern Standard Time
America/Knox IN - Central Standard Time
America/La Paz - Bolivia Time
America/Lima - Peru Time
America/Los Angeles - Pacific Standard Time
America/Louisville - Eastern Standard Time
America/Maceio - Brasilia Time
America/Managua - Central Standard Time
America/Manaus - Amazon Time
America/Marigot - Atlantic Standard Time
America/Martinique - Atlantic Standard Time
America/Mazatlan - Mountain Standard Time
America/Mendoza - Argentine Time
America/Menominee - Central Standard Time
America/Merida - Central Standard Time
America/Mexico City - Central Standard Time
America/Miquelon - Pierre & Miquelon Standard Time
America/Moncton - Atlantic Standard Time
America/Monterrey - Central Standard Time
America/Montevideo - Uruguay Time
America/Montreal - Eastern Standard Time
America/Montserrat - Atlantic Standard Time
America/Nassau - Eastern Standard Time
America/New York - Eastern Standard Time
America/Nipigon - Eastern Standard Time
America/Nome - Alaska Standard Time
America/Noronha - Fernando de Noronha Time
America/North Dakota/Center - Central Standard Time
America/North Dakota/New Salem - Central Standard Time
America/Panama - Eastern Standard Time
America/Pangnirtung - Eastern Standard Time
America/Paramaribo - Suriname Time
America/Phoenix - Mountain Standard Time
America/Port-au-Prince - Eastern Standard Time
America/Port of Spain - Atlantic Standard Time
America/Porto Acre - Amazon Time
America/Porto Velho - Amazon Time
America/Puerto Rico - Atlantic Standard Time
America/Rainy River - Central Standard Time
America/Rankin Inlet - Central Standard Time
America/Recife - Brasilia Time
America/Regina - Central Standard Time
America/Resolute - Eastern Standard Time
America/Rio Branco - Amazon Time
America/Rosario - Argentine Time
America/Santarem - Brasilia Time
America/Santiago - Chile Time
America/Santo Domingo - Atlantic Standard Time
America/Sao Paulo - Brasilia Time
America/Scoresbysund - Eastern Greenland Time
America/Shiprock - Mountain Standard Time
America/St Barthelemy - Atlantic Standard Time
America/St Johns - Newfoundland Standard Time
America/St Kitts - Atlantic Standard Time
America/St Lucia - Atlantic Standard Time
America/St Thomas - Atlantic Standard Time
America/St Vincent - Atlantic Standard Time
America/Swift Current - Central Standard Time
America/Tegucigalpa - Central Standard Time
America/Thule - Atlantic Standard Time
America/Thunder Bay - Eastern Standard Time
America/Tijuana - Pacific Standard Time
America/Toronto - Eastern Standard Time
America/Tortola - Atlantic Standard Time
America/Vancouver - Pacific Standard Time
America/Virgin - Atlantic Standard Time
America/Whitehorse - Pacific Standard Time
America/Winnipeg - Central Standard Time
America/Yakutat - Alaska Standard Time
America/Yellowknife - Mountain Standard Time
Asia/Aden - Arabia Standard Time
Asia/Almaty - Alma-Ata Time
Asia/Amman - Eastern European Time
Asia/Anadyr - Anadyr Time
Asia/Aqtau - Aqtau Time
Asia/Aqtobe - Aqtobe Time
Asia/Ashgabat - Turkmenistan Time
Asia/Ashkhabad - Turkmenistan Time
Asia/Baghdad - Arabia Standard Time
Asia/Bahrain - Arabia Standard Time
Asia/Baku - Azerbaijan Time
Asia/Bangkok - Indochina Time
Asia/Beirut - Eastern European Time
Asia/Bishkek - Kirgizstan Time
Asia/Brunei - Brunei Time
Asia/Calcutta - India Standard Time
Asia/Choibalsan - Choibalsan Time
Asia/Chongqing - China Standard Time
Asia/Chungking - China Standard Time
Asia/Colombo - India Standard Time
Asia/Dacca - Bangladesh Time
Asia/Damascus - Eastern European Time
Asia/Dhaka - Bangladesh Time
Asia/Dili - Timor-Leste Time
Asia/Dubai - Gulf Standard Time
Asia/Dushanbe - Tajikistan Time
Asia/Gaza - Eastern European Time
Asia/Harbin - China Standard Time
Asia/Ho Chi Minh - Indochina Time
Asia/Hong Kong - Hong Kong Time
Asia/Hovd - Hovd Time
Asia/Irkutsk - Irkutsk Time
Asia/Istanbul - Eastern European Time
Asia/Jakarta - West Indonesia Time
Asia/Jayapura - East Indonesia Time
Asia/Jerusalem - Israel Standard Time
Asia/Kabul - Afghanistan Time
Asia/Kamchatka - Petropavlovsk-Kamchatski Time
Asia/Karachi - Pakistan Time
Asia/Kashgar - China Standard Time
Asia/Katmandu - Nepal Time
Asia/Kolkata - India Standard Time
Asia/Krasnoyarsk - Krasnoyarsk Time
Asia/Kuala Lumpur - Malaysia Time
Asia/Kuching - Malaysia Time
Asia/Kuwait - Arabia Standard Time
Asia/Macao - China Standard Time
Asia/Macau - China Standard Time
Asia/Magadan - Magadan Time
Asia/Makassar - Central Indonesia Time
Asia/Manila - Philippines Time
Asia/Muscat - Gulf Standard Time
Asia/Nicosia - Eastern European Time
Asia/Novosibirsk - Novosibirsk Time
Asia/Omsk - Omsk Time
Asia/Oral - Oral Time
Asia/Phnom Penh - Indochina Time
Asia/Pontianak - West Indonesia Time
Asia/Pyongyang - Korea Standard Time
Asia/Qatar - Arabia Standard Time
Asia/Qyzylorda - Qyzylorda Time
Asia/Rangoon - Myanmar Time
Asia/Riyadh - Arabia Standard Time
Asia/Riyadh87 - GMT+03:07
Asia/Riyadh88 - GMT+03:07
Asia/Riyadh89 - GMT+03:07
Asia/Saigon - Indochina Time
Asia/Sakhalin - Sakhalin Time
Asia/Samarkand - Uzbekistan Time
Asia/Seoul - Korea Standard Time
Asia/Shanghai - China Standard Time
Asia/Singapore - Singapore Time
Asia/Taipei - China Standard Time
Asia/Tashkent - Uzbekistan Time
Asia/Tbilisi - Georgia Time
Asia/Tehran - Iran Standard Time
Asia/Tel Aviv - Israel Standard Time
Asia/Thimbu - Bhutan Time
Asia/Thimphu - Bhutan Time
Asia/Tokyo - Japan Standard Time
Asia/Ujung Pandang - Central Indonesia Time
Asia/Ulaanbaatar - Ulaanbaatar Time
Asia/Ulan Bator - Ulaanbaatar Time
Asia/Urumqi - China Standard Time
Asia/Vientiane - Indochina Time
Asia/Vladivostok - Vladivostok Time
Asia/Yakutsk - Yakutsk Time
Asia/Yekaterinburg - Yekaterinburg Time
Asia/Yerevan - Armenia Time
Atlantic/Azores - Azores Time
Atlantic/Bermuda - Atlantic Standard Time
Atlantic/Canary - Western European Time
Atlantic/Cape Verde - Cape Verde Time
Atlantic/Faeroe - Western European Time
Atlantic/Faroe - Western European Time
Atlantic/Jan Mayen - Central European Time
Atlantic/Madeira - Western European Time
Atlantic/Reykjavik - Greenwich Mean Time
Atlantic/South Georgia - South Georgia Standard Time
Atlantic/St Helena - Greenwich Mean Time
Atlantic/Stanley - Falkland Is. Time
Australia/ACT - Eastern Standard Time (New South Wales)
Australia/Adelaide - Central Standard Time (South Australia)
Australia/Brisbane - Eastern Standard Time (Queensland)
Australia/Broken Hill - Central Standard Time (South Australia/New South Wales)
Australia/Canberra - Eastern Standard Time (New South Wales)
Australia/Currie - Eastern Standard Time (New South Wales)
Australia/Darwin - Central Standard Time (Northern Territory)
Australia/Eucla - Central Western Standard Time (Australia)
Australia/Hobart - Eastern Standard Time (Tasmania)
Australia/LHI - Lord Howe Standard Time
Australia/Lindeman - Eastern Standard Time (Queensland)
Australia/Lord Howe - Lord Howe Standard Time
Australia/Melbourne - Eastern Standard Time (Victoria)
Australia/NSW - Eastern Standard Time (New South Wales)
Australia/North - Central Standard Time (Northern Territory)
Australia/Perth - Western Standard Time (Australia)
Australia/Queensland - Eastern Standard Time (Queensland)
Australia/South - Central Standard Time (South Australia)
Australia/Sydney - Eastern Standard Time (New South Wales)
Australia/Tasmania - Eastern Standard Time (Tasmania)
Australia/Victoria - Eastern Standard Time (Victoria)
Australia/West - Western Standard Time (Australia)
Australia/Yancowinna - Central Standard Time (South Australia/New South Wales)
Europe/Amsterdam - Central European Time
Europe/Andorra - Central European Time
Europe/Athens - Eastern European Time
Europe/Belfast - Greenwich Mean Time
Europe/Belgrade - Central European Time
Europe/Berlin - Central European Time
Europe/Bratislava - Central European Time
Europe/Brussels - Central European Time
Europe/Bucharest - Eastern European Time
Europe/Budapest - Central European Time
Europe/Chisinau - Eastern European Time
Europe/Copenhagen - Central European Time
Europe/Dublin - Greenwich Mean Time
Europe/Gibraltar - Central European Time
Europe/Guernsey - Greenwich Mean Time
Europe/Helsinki - Eastern European Time
Europe/Isle of Man - Greenwich Mean Time
Europe/Istanbul - Eastern European Time
Europe/Jersey - Greenwich Mean Time
Europe/Kaliningrad - Eastern European Time
Europe/Kiev - Eastern European Time
Europe/Lisbon - Western European Time
Europe/Ljubljana - Central European Time
Europe/London - Greenwich Mean Time
Europe/Luxembourg - Central European Time
Europe/Madrid - Central European Time
Europe/Malta - Central European Time
Europe/Mariehamn - Eastern European Time
Europe/Minsk - Eastern European Time
Europe/Monaco - Central European Time
Europe/Moscow - Moscow Standard Time
Europe/Nicosia - Eastern European Time
Europe/Oslo - Central European Time
Europe/Paris - Central European Time
Europe/Podgorica - Central European Time
Europe/Prague - Central European Time
Europe/Riga - Eastern European Time
Europe/Rome - Central European Time
Europe/Samara - Samara Time
Europe/San Marino - Central European Time
Europe/Sarajevo - Central European Time
Europe/Simferopol - Eastern European Time
Europe/Skopje - Central European Time
Europe/Sofia - Eastern European Time
Europe/Stockholm - Central European Time
Europe/Tallinn - Eastern European Time
Europe/Tirane - Central European Time
Europe/Tiraspol - Eastern European Time
Europe/Uzhgorod - Eastern European Time
Europe/Vaduz - Central European Time
Europe/Vatican - Central European Time
Europe/Vienna - Central European Time
Europe/Vilnius - Eastern European Time
Europe/Volgograd - Volgograd Time
Europe/Warsaw - Central European Time
Europe/Zagreb - Central European Time
Europe/Zaporozhye - Eastern European Time
Europe/Zurich - Central European Time
Indian/Antananarivo - Eastern African Time
Indian/Chagos - Indian Ocean Territory Time
Indian/Christmas - Christmas Island Time
Indian/Cocos - Cocos Islands Time
Indian/Comoro - Eastern African Time
Indian/Kerguelen - French Southern & Antarctic Lands Time
Indian/Mahe - Seychelles Time
Indian/Maldives - Maldives Time
Indian/Mauritius - Mauritius Time
Indian/Mayotte - Eastern African Time
Indian/Reunion - Reunion Time
Pacific/Apia - West Samoa Time
Pacific/Auckland - New Zealand Standard Time
Pacific/Chatham - Chatham Standard Time
Pacific/Easter - Easter Is. Time
Pacific/Efate - Vanuatu Time
Pacific/Enderbury - Phoenix Is. Time
Pacific/Fakaofo - Tokelau Time
Pacific/Fiji - Fiji Time
Pacific/Funafuti - Tuvalu Time
Pacific/Galapagos - Galapagos Time
Pacific/Gambier - Gambier Time
Pacific/Guadalcanal - Solomon Is. Time
Pacific/Guam - Chamorro Standard Time
Pacific/Honolulu - Hawaii Standard Time
Pacific/Johnston - Hawaii Standard Time
Pacific/Kiritimati - Line Is. Time
Pacific/Kosrae - Kosrae Time
Pacific/Kwajalein - Marshall Islands Time
Pacific/Majuro - Marshall Islands Time
Pacific/Marquesas - Marquesas Time
Pacific/Midway - Samoa Standard Time
Pacific/Nauru - Nauru Time
Pacific/Niue - Niue Time
Pacific/Norfolk - Norfolk Time
Pacific/Noumea - New Caledonia Time
Pacific/Pago Pago - Samoa Standard Time
Pacific/Palau - Palau Time
Pacific/Pitcairn - Pitcairn Standard Time
Pacific/Ponape - Ponape Time
Pacific/Port Moresby - Papua New Guinea Time
Pacific/Rarotonga - Cook Is. Time
Pacific/Saipan - Chamorro Standard Time
Pacific/Samoa - Samoa Standard Time
Pacific/Tahiti - Tahiti Time
Pacific/Tarawa - Gilbert Is. Time
Pacific/Tongatapu - Tonga Time
Pacific/Truk - Truk Time
Pacific/Wake - Wake Time
Pacific/Wallis - Wallis & Futuna Time
Pacific/Yap - Truk Time
