6.7 Dates

Pyxplot has a date object type which simplifies the process of working with dates and times. Pyxplot provides a range of pre-defined functions, in the time module, for creating and manipulating date objects. The functions for creating date objects are as follows:

time.fromCalendar( $year,month,day,hour,min,sec$ )
The time.fromCalendar( $year,month,day,hour,min,sec$ ) function creates a date object from the specified calendar date. It takes six inputs: the year, the month number (1–12), the day of the month (1–31), the hour of day (0–24), the number of minutes (0–59), and the number of seconds (0–59). To enter dates before AD 1, a year of $0$ should be passed to indicate 1 BC, $-1$ should be passed to indicate the year 2 BC, and so forth. The set calendar command is used to change the current calendar.

time.fromJD( $t$ )
The time.fromJD( $t$ ) function creates a date object from the specified numerical Julian date.

time.fromMJD( $t$ )
The time.fromMJD( $t$ ) function creates a date object from the specified numerical modified Julian date.

time.fromUnix( $t$ )
The time.fromUnix( $t$ ) function creates a date object from the specified numerical Unix time.

time.now()
The time.now() function creates a date object representing the present time.

The following example creates a date object representing midnight on 1st January 2000:

pyxplot> print time.fromCalendar(2000,1,1,0,0,0)
Sat 2000 Jan 1 00:00:00 UTC
pyxplot> a = time.fromCalendar(2000,1,1,0,0,0,"Australia/Perth")
pyxplot> print a # Note that this does not use Australian time
Fri 1999 Dec 31 15:59:59 UTC
pyxplot> set timezone "Pacific/Chatham"
pyxplot> print a
Sat 2000 Jan 1 05:45:00 CHADT
pyxplot> set timezone "Antarctica/South_Pole"
pyxplot> print a
Sat 2000 Jan 1 05:00:00 NZDT
pyxplot> print a.toYear() # at the south pole
2000
pyxplot> print a.toYear("Europe/London")
1999

Once created, it is possible to add numbers with physical units of time to dates, as in the following example:

pyxplot> myDate = time.fromCalendar(2012,8,1,0,0,0)
pyxplot> print myDate + unit(7*day)
Wed 2012 Aug 8 00:00:00 UTC
pyxplot> print myDate - unit(2000*day)
Fri 2007 Feb 9 00:00:00 UTC

In addition, if one date is subtracted from another date, the time interval between the two dates is returned as a number with physical dimensions of time:

pyxplot> x = time.fromCalendar(-752,4,21,12,0,0)
pyxplot> y = time.fromCalendar( 476,9, 4,12,0,0)
pyxplot> print y-x
3.8764483e+10 s
pyxplot> print time.interval(y,x)
3.8764483e+10 s
pyxplot> print (y-x)/unit(year)
1228.3986

Standard string representations of calendar dates can be produced with the print command. It is also possible to use the string substitution operator, as in "%s"%(date), or the str method of date objects, as in date.str(). In addition, the time.string function can be used to choose a custom display format for the date; for more information, see Section 4.11.

Several functions are provided for converting date objects back into various numerical forms of timekeeping and components of calendar dates:

toDayOfMonth()
The toDayOfMonth() method returns the day of the month of a date object in the current calendar.

toDayWeekName()
The toDayWeekName() method returns the name of the day of the week of a date object.

toDayWeekNum()
The toDayWeekNum() method returns the day of the week (1–7) of a date object.

toHour()
The toHour() method returns the integer hour component (0–23) of a date object.

toJD()
The toJD() method converts a date object to a numerical Julian date.

toMinute()
The toMinute() method returns the integer minute component (0–59) of a date object.

toMJD()
The toMJD() method converts a date object to a modified Julian date.

toMonthName()
The toMonthName() method returns the name of the month in which a date object falls.

toMonthNum()
The toMonthNum() method returns the number (1–12) of the month in which a date object falls.

toSecond()
The toSecond() method returns the seconds component (0–60) of a date object, including the non-integer component.

toUnix()
The toUnix() method converts a date object to a Unix time.

toYear()
The toYear() method returns the year in which a date object falls in the current calendar.

For example:

pyxplot> a = time.fromCalendar(2000,1,1,0,0,0)
pyxplot> time.string(a)
Sat 2000 Jan 1 00:00:00 UTC
pyxplot> time.string(a,"%d %B %Y")
1 January 2000
pyxplot> set calendar muslim
pyxplot> time.string(a,"%d %B %Y")
21 Dhu l-Qa’da 1389

More information on the manipulation of date objects can be found in Section 4.11.