Home Contents Previous Next

1.37 class date

Class date is a wrapper around Unix's notion of time. It is intended to communicate over creation, last-modification dates, etc. Dates might also be useful for agenda systems and systems that represent some kind of database. For example, this manual tool uses date objects to keep track of the last-modification time of cards.

Unix time is measured in seconds from the Unix epoch: Jan 1, 1970. Therefore, the granularity of a date object is a second. The first date that can be represented is Jan 1, 1970 and the latest date somewhere in the year 2105 (2 to-the-power 32 - 1 seconds from the epoch).

The most important methods are:

1.37.1 Send methods

date ->advance: with=int, unit=[{second,minute,hour,day,week}]
Advance date object with the given amount of the specified unit. The default unit is second. Please note that larger units are omitted due to their unclear semantics. Units are converted to seconds. Given that the fields are in local time, creating a time from fields, date->advance and get the fields may yield strange results. For example: 
?-	new(D, date(0, 0, 0, 30, 10, 2005)),
        send(D, advance, 1, day),
        get(D, string, string(Date))

Date = 'Sun Oct 30 23:00:00 2005'

See also date->month, etc.

date ->after: date
Test if date is after argument. See also date->before and date->equal.
date ->before: date
Test if date is before argument. See also date->equal and date->after.
date ->convert: description=char_array
Conversion of a textual representation of a date into a date object. These methods exploit the GNU-project get_date() library and convert various commonly used representations of a date. Unfortunately this library is undocumented ...
date ->current:
Make the date object reflect the current time.
date ->equal: date
Succeeds if both date objects represent the same point in time. See also date->before, date->after and date<-difference.
date ->initialise: seconds=[0..59], minutes=[0..59], hours=[0..23], day=[1..31], month=[1..12], year=[1970..2050]
Create a date object from its components. Any defaulted value defaults to the current value. Thus 
?- new(D, date(0, 35, 14)).

Represents 14.35h today.

See date->set for details and limitations.

date ->posix_value: real
Communicate the represented time-stamp as a POSIX time stamp, i.e. the number of seconds elapsed since the epoch, Jan 1, 1970.

This value is passed as a float to avoid the limited range supported by the XPCE int type.

Inherits description from: date<-posix_value

date ->set: seconds=[0..59], minutes=[0..59], hours=[0..23], day=[1..31], month=[1..12], year=[1970..2050]
Set all non-default components. This method is also used by date->initialise if arguments are provided.

It uses the mktime() function which appears to have different behaviour on different systems on timestamps before the epoch at Jan. 1, 1970 UTC. On some systems it returns negative values, while on others it returns the error code -1. Note that even on systems with negative values the last second before the epoch cannot be represented. An error is returned if mktime() returns -1.

1.37.2 Get methods

date <-compare: date -> {smaller,equal,larger}
Compare to date objects and return one of smaller (before), equal (same time) or larger (after). May be used by chain->sort. The following example sorts a chain of file objects according to their last modification time: 
send(Files, sort,
         ?(@arg1?time, compare, @arg2?time))
date <-convert: string -> date
Convert a date from textual representation. It uses the public domain getdate.y file converting many commonly used textual representations of date/time.

Before using the getdate.y library it tries to convert the XML-Schema defined dateTime representation. See also date<-string, date<-rfc_string and date<-xml_string.

Inherits description from: date->convert

date <-difference: to=[date], unit=[{second,minute,hour,day,week,year}] -> units=int
Difference relative to the argument date in the specified unit. The value is always rounded downwards. to defaults to the epoch. units defaults to seconds. Note that the result is returned as a PCE integer and the maximum value of a PCE integer is not sufficient to represent all time differences in second units. An error (int_range) is generated on overflow.

See also date->before, date->equal and date->after.

date <-posix_value: -> real
date <-print_name: -> string
Equivalent to date<-string. The methods date<-print_name and date<-convert are used by class text_item to represent and modify objects.
See also
date<-string
date <-rfc_string: -> string
date<-string in RFC compatible format. See also date<-xml_string.
date <-string: -> string
New string object representing date. This method uses the C-library function ctime(). It's format is: 
_Mon Sep 14 17:23:18 1992_

See also date<-rfc_string and date<-xml_string for conversion to other popular representations.

Bugs: There is no way to manipulate the printed representations of a date apart from redefining this method from scratch.

See also
- date<-print_name
- pce<-date
date <-xml_string: -> string
date<-string in the XML-Schema defined dateTime format. The time is always represented in UTZ (ending with a Z). See also date<-rfc_string, date<-string and date<-convert.

This format is defined as CCYY-MM-DDThh:mm:ss[Z|+-hh:mm]. See the XML schema definition for details.