Dates, Times, and the Calendar Package



Maple 2018 adds new data structures that represent dates and times. There are numerous functions that work with dates and times, including fundamental operations such as date arithmetic and more advanced functionality for working with Calendars. Existing packages including Finance also support the new Date object.

Dates, Times, and Clocks


•

New objects representing dates, times, and clocks were introduced in Maple 2018.

•

The Now method for a clock creates a Time object representing the current time according to the indicated clock. (For more information about other available clock objects, see Clock.)

>

now := Now( SystemUTCClock );

${\mathrm{Time}}{}\left({1519826460130}{\,}{1}{\,}{\mathrm{clock}}{\=}\left({\mathbf{module}}\left({}\right)\phantom{\rule[0.0ex]{0.5em}{0.0ex}}{...}\phantom{\rule[0.0ex]{0.5em}{0.0ex}}{\mathbf{end\; module}}\right)\right)$
 (1) 
•

From a given Time object, you can create a corresponding Date object, as follows.

${\mathrm{Date}}{}\left({2018}{\,}{2}{\,}{28}{\,}{14}{\,}{1}{\,}\frac{{13}}{{100}}{\,}{\mathrm{timezone}}{\=}{''UTC''}{\,}{\mathrm{coefficient}}{\=}{1}\right)$
 (2) 
•

Or, more simply, use the Date constructor without arguments.

${\mathrm{Date}}{}\left({2018}{\,}{2}{\,}{28}{\,}{14}{\,}{1}{\,}\frac{{693}}{{1000}}{\,}{\mathrm{timezone}}{\=}{''UTC''}{\,}{\mathrm{coefficient}}{\=}{1}\right)$
 (3) 
•

Various fields of the Date object are accessible.

•

Arithmetic with Date and Time objects is builtin.

•

To compute the amount of time between two dates represented as Date objects, just subtract them.

>

d1 := Date( 2017, 12, 25 );

${\mathrm{Date}}{}\left({2017}{\,}{12}{\,}{25}{\,}{12}{\,}{0}{\,}{0}{\,}{\mathrm{timezone}}{\=}{''Canada/Eastern''}{\,}{\mathrm{coefficient}}{\=}{1}\right)$
 (7) 
>

d2 := Date( 2000, 12, 25 );

${\mathrm{Date}}{}\left({2000}{\,}{12}{\,}{25}{\,}{12}{\,}{0}{\,}{0}{\,}{\mathrm{timezone}}{\=}{''Canada/Eastern''}{\,}{\mathrm{coefficient}}{\=}{1}\right)$
 (8) 
${t}{\u2254}{536457600000}{}\u27e6{\mathrm{ms}}\u27e7$
 (9) 
>

convert( t, 'units', 'days' );

${6209}{}\u27e6{d}\u27e7$
 (10) 

(For more control over the units used in computing the time between two dates, use the DateDifference command in the Calendar package).

•

In fact, any affine combination of Date objects results in an expression involving units of time.

•

A convex combination of Date objects results in another Date object. For instance, to compute the average value of two Date objects, you can use an expression such as the following one.

${\mathrm{Date}}{}\left({2009}{\,}{6}{\,}{26}{\,}{1}{\,}{0}{\,}{0}{\,}{\mathrm{timezone}}{\=}{''Canada/Eastern''}{\,}{\mathrm{coefficient}}{\=}{1}\right)$
 (11) 
•

You can specify a date in a particular time zone by using the timezone option to the Date constructor. Suppose, for example, that a flight leaves Toronto at $8$ p.m. on March 12, 2007, and arrives in Paris at $9$ a.m. on March 13.

>

depart := Date( 2007, 3, 12, 20, 44, 'timezone' = "America/Toronto" );

${\mathrm{Date}}{}\left({2007}{\,}{3}{\,}{12}{\,}{20}{\,}{44}{\,}{0}{\,}{\mathrm{timezone}}{\=}{''America/Toronto''}{\,}{\mathrm{coefficient}}{\=}{1}\right)$
 (12) 
>

arrive := Date( 2007, 3, 13, 9, 3, 'timezone' = "Europe/Paris" );

${\mathrm{Date}}{}\left({2007}{\,}{3}{\,}{13}{\,}{9}{\,}{3}{\,}{0}{\,}{\mathrm{timezone}}{\=}{''Europe/Paris''}{\,}{\mathrm{coefficient}}{\=}{1}\right)$
 (13) 
•

To compute the flight time, simply subtract the two dates.

>

flight_time := arrive  depart;

${\mathrm{flight\_time}}{\u2254}{26340000}{}\u27e6{\mathrm{ms}}\u27e7$
 (14) 
>

convert( flight_time, 'units', 'hours' );

$\frac{{439}}{{60}}{}\u27e6{h}\u27e7$
 (15) 


The Calendar Package


•

The Calendar package provides a number of useful routines for working with dates.

$\left[{\mathrm{AdjustDateField}}{\,}{\mathrm{DateDifference}}{\,}{\mathrm{DayOfWeek}}{\,}{\mathrm{DayOfYear}}{\,}{\mathrm{DaysInMonth}}{\,}{\mathrm{DaysInYear}}{\,}{\mathrm{HostTimeZone}}{\,}{\mathrm{IsDaylightSavingTime}}{\,}{\mathrm{IsLeapYear}}{\,}{\mathrm{IsWeekend}}{\,}{\mathrm{JulianDayNumber}}{\,}{\mathrm{ModifiedJulianDayNumber}}{\,}{\mathrm{Today}}\right]$
 (16) 
•

For example, you can check whether a year is a leap year.

•

You can compute the day of the week or year for any given date. For example, Christmas of 2017 occurred on a Monday.

>

DayOfWeek( 2017, 12, 25 );

•

And, it was the $359$th day of the year.

>

DayOfYear( 2017, 12, 25 );

•

Since Date objects can be specified with respect to particular time zones, it is useful to be able to determine the time zone of computer on which Maple is running. To do this, use the HostTimeZone command.

${''Canada/Eastern''}$
 (21) 
•

The DateDifference command gives you finer control over the units used to compute the time difference between two dates. For our flight example above, we can compute as follows.

>

DateDifference( depart, arrive, 'units' = 'h' );

$\frac{{439}}{{60}}{}\u27e6{h}\u27e7$
 (22) 
•

It is sometimes more convenient to use "mixed" units in the output, as illustrated here:

>

DateDifference( depart, arrive, 'units' = 'mixed' );

${7}{}\u27e6{h}\u27e7{+}{19}{}\u27e6{\mathrm{min}}\u27e7$
 (23) 
•

The AdjustDateField command provides for the ability to add amounts to individual Date object fields, such as the month or the hour of the day.

>

d := Date( 2000, 1, 14, 10, 55, 3 );

${\mathrm{Date}}{}\left({2000}{\,}{1}{\,}{14}{\,}{10}{\,}{55}{\,}{3}{\,}{\mathrm{timezone}}{\=}{''Canada/Eastern''}{\,}{\mathrm{coefficient}}{\=}{1}\right)$
 (24) 
>

AdjustDateField( d, "minute", 3 );

${\mathrm{Date}}{}\left({2000}{\,}{1}{\,}{14}{\,}{10}{\,}{52}{\,}{3}{\,}{\mathrm{timezone}}{\=}{''Eastern\; Standard\; Time''}{\,}{\mathrm{coefficient}}{\=}{1}\right)$
 (25) 
•

Notice the effect of adding many months to the date here:

>

AdjustDateField( d, "month", 30 );

${\mathrm{Date}}{}\left({2002}{\,}{7}{\,}{14}{\,}{10}{\,}{55}{\,}{3}{\,}{\mathrm{timezone}}{\=}{''Eastern\; Standard\; Time''}{\,}{\mathrm{coefficient}}{\=}{1}\right)$
 (26) 
•

By default, changes to a particular date field can potentially lead to changes to date fields at a higher level of granularity. The method = "roll" option confines modifications to a single field, keeping its values within the valid ranges for that field.

>

AdjustDateField( d, "month", 30, 'method' = "roll" );

${\mathrm{Date}}{}\left({2000}{\,}{7}{\,}{14}{\,}{10}{\,}{55}{\,}{3}{\,}{\mathrm{timezone}}{\=}{''Eastern\; Standard\; Time''}{\,}{\mathrm{coefficient}}{\=}{1}\right)$
 (27) 
•

The default behavior is obtained by using the method = "add" option.

>

AdjustDateField( d, "month", 30, 'method' = "add" );

${\mathrm{Date}}{}\left({2002}{\,}{7}{\,}{14}{\,}{10}{\,}{55}{\,}{3}{\,}{\mathrm{timezone}}{\=}{''Eastern\; Standard\; Time''}{\,}{\mathrm{coefficient}}{\=}{1}\right)$
 (28) 
•

For more information on the Calendar package, see the package overview page.


