For Gauche 0.9.5

Next: , Previous: , Up: Library modules - SRFIs   [Contents][Index]

11.8 srfi-19 - Time data types and procedures

Module: srfi-19

This SRFI defines various representations of time and date, and conversion methods among them.

On Gauche, time object is supported natively by <time> class (see Time). Date object is supported by <date> class described below.

Next: , Previous: , Up: Time data types and procedures   [Contents][Index]

11.8.1 Time types

Time type is represented by a symbol. This module defines the following constant variables that is bound to its name, for convenience.

Constant: time-utc

[SRFI-19] UTC time. Gauche’s built-in current-time always returns this type (see Time).

Constant: time-tai

[SRFI-19] International Atomic Time. This time is a bit larger than UTC, due to the leap seconds.

Constant: time-monotonic

[SRFI-19] Implementation-dependent monotonically increasing time. In Gauche, this is the same as time-tai.

Constant: time-duration

[SRFI-19] Duration between two absolute time points.

Constant: time-process

[SRFI-19] CPU time in current process. Gauche calculates this from user time and system time returned by POSIX times(3).

Constant: time-thread

[SRFI-19] CPU time in current thread. In the current implementation, this is the same as time-process.

Next: , Previous: , Up: Time data types and procedures   [Contents][Index]

11.8.2 Time queries

Function: current-time :optional time-type

[SRFI-19] Extends Gauche built-in current-time (see Time) to take optional time-type argument to specify the desired time type. time-type must be one of the types described in SRFI-19 Time types.

Function: current-date :optional tz-offset

[SRFI-19] Returns the current date as an instance of <date> class (see SRFI-19 Date). If tz-offset is given, it must be an offset from UTC in number of seconds. If tz-offset is not given, returns the date in local time zone.

Function: current-julian-day

[SRFI-19] Returns the current julian day, a point in time as a real number of days since -4714-11-24T12:00:00Z (November 24, -4714 at noon, UTC).

Function: current-modified-julian-day

[SRFI-19] Returns the current modified julian day, a point in time as a real number of days since 1858-11-17T00:00:00Z (November 17, 1858 at midnight, UTC).

Function: time-resolution


Next: , Previous: , Up: Time data types and procedures   [Contents][Index]

11.8.3 Time procedures

Function: make-time type nanoseconds seconds

[SRFI-19] Returns an instance of <time> class with specified initial values. Equivalent to (make <time> :type type :second seconds :nanosecond nanoseconds).

(This function had been defined incorrectly before release 0.6.8; the arguments seconds and nanoseconds were switched. Please check your code if it uses make-time).

Function: time-type time
Function: time-second time
Function: time-nanosecond time
Function: set-time-type! time type
Function: set-time-second! time second
Function: set-time-nanosecond! time nanosecond

[SRFI-19] Getter and setter of <time> object slots.

Function: copy-time time

[SRFI-19] Returns a new instance of <time> whose content is the same as given time

Function: time=? time0 time1
Function: time<? time0 time1
Function: time<=? time0 time1
Function: time>? time0 time1
Function: time>=? time0 time1

[SRFI-19] Compares two times. Types of both times must match.

Function: time-difference time0 time1
Function: time-difference! time0 time1

[SRFI-19] Returns the difference of two times, in time-duration time. Types of both times must match. Time-difference! modifies time0 to store the result.

Function: add-duration time0 time-duration
Function: add-duration! time0 time-duration
Function: subtract-duration time0 time-duration
Function: subtract-duration! time0 time-duration

[SRFI-19] Adds or subtracts time-duration to or from time0. Type of returned time is the same as time0. Type of time-duration must be time-duration. add-duration! and subtract-duration! reuse time0 to store the result.

Next: , Previous: , Up: Time data types and procedures   [Contents][Index]

11.8.4 Date

Class: <date>

Represents a date.

Instance Variable of <date>: nanosecond

Nanosecond portion of the date by an integer between 0 and 999,999,999, inclusive.

Instance Variable of <date>: second

Second portion of the date by an integer between 0 and 60, inclusive. (60 for leap second).

Instance Variable of <date>: minute

Minute portion of the date by an integer between 0 and 59, inclusive.

Instance Variable of <date>: hour

Hour portion of the date by an integer between 0 and 23, inclusive.

Instance Variable of <date>: day

Day portion of the date by an integer between 0 and 31, inclusive. The actual upper bound of the day is determined by the year and the month. (Note: 1 is for the first day; 0 is allowed by the specification, but I don’t see why).

Instance Variable of <date>: month

Month portion of the date by an integer between 1 and 12, inclusive. 1 for January, 2 for February, and so on. (Note: this is different from POSIX’s <sys-tm> convention).

Instance Variable of <date>: year

Year portion of the date.

Instance Variable of <date>: zone-offset

The number of seconds east of GMT for this timezone, by an integer.

Function: make-date nanosecond second minute hour day month year zone-offset

[SRFI-19] Makes a <date> object from the given values. Note: this procedure does not check if the values are in the valid range.

Function: date? obj

[SRFI-19] Returns true iff obj is a <date> object.

Function: date-nanosecond date
Function: date-second date
Function: date-minute date
Function: date-hour date
Function: date-day date
Function: date-month date
Function: date-year date
Function: date-zone-offset date

[SRFI-19] Accessors.

Function: date-year-day date
Function: date-week-day date
Function: date-week-number date day-of-week-starting-week

[SRFI-19] Calculates the day number in the year (1 for January 1st), the day number in the week (0 for Sunday, 1 for Monday, ...), and the ordinal week of the year which holds this date, ignoring a first partial week, respectively.

Day-of-week-starting-week is the integer corresponding to the day of the week which is to be considered the first day of the week (Sunday=0, Monday=1, etc.).

Function: date->julian-day date
Function: date->modified-julian-day date
Function: date->time-monotonic date
Function: date->time-tai date
Function: date->time-utc date

[SRFI-19] Conversions from date to various date/time types.

Function: julian-day->date jd :optional tz-offset
Function: julian-day->time-monotonic jd
Function: julian-day->time-tai jd
Function: julian-day->time-utc jd

[SRFI-19] Conversions from julian-day to various date/time types.

Function: modified-julian-day->date jd :optional tz-offset
Function: modified-julian-day->time-monotonic jd
Function: modified-julian-day->time-tai jd
Function: modified-julian-day->time-utc jd

[SRFI-19] Conversions from modified julian-day to various date/time types.

Function: time-monotonic->date time :optional tz-offset
Function: time-monotonic->julian-day time
Function: time-monotonic->modified-julian-day time
Function: time-monotonic->time-tai time
Function: time-monotonic->time-tai! time
Function: time-monotonic->time-utc time
Function: time-monotonic->time-utc! time

[SRFI-19] Conversions from time-monotonic to various date/time types.

Function: time-tai->date time :optional tz-offset
Function: time-tai->julian-day time
Function: time-tai->modified-julian-day time
Function: time-tai->time-monotonic time
Function: time-tai->time-monotonic! time
Function: time-tai->time-utc time
Function: time-tai->time-utc! time

[SRFI-19] Conversions from time-tai to various date/time types.

Function: time-utc->date time :optional tz-offset
Function: time-utc->julian-day time
Function: time-utc->modified-julian-day time
Function: time-utc->time-monotonic time
Function: time-utc->time-monotonic! time
Function: time-utc->time-tai time
Function: time-utc->time-tai! time

[SRFI-19] Conversions from time-utc to various date/time types.

Previous: , Up: Time data types and procedures   [Contents][Index]

11.8.5 Date reader and writer

Function: date->string date :optional format-string

[SRFI-19+] Converts a <date> object to a string, according to the format specified by format-string. If format-string is omitted, "~c" is assumed.

A format string is copied to output, except a sequence begins with ~ which is replaced with the following rules:


A literal ~.


Locale’s abbreviated weekday name (Sun...Sat).


Locale’s full weekday name (Sunday...Saturday).


Locale’s abbreviate month name (Jan...Dec).


Locale’s full month name (January...December).


Locale’s date and time (e.g., "Fri Jul 14 20:28:42-0400 2000").


Day of month, zero padded (01...31).


Date (mm/dd/yy).


Day of month, blank padded ( 1...31).


Seconds+fractional seconds, using locale’s decimal separator (e.g. 5.2).


Same as ~b.


Hour, zero padded, 24-hour clock (00...23).


Hour, zero padded, 12-hour clock (01...12).


Day of year, zero padded.


Hour, blank padded, 24-hour clock ( 0...23).


Hour, blank padded, 12-hour clock ( 1...12).


Month, zero padded (01...12).


Minute, zero padded (00...59).


New line.


Nanosecond, zero padded.


Locale’s AM or PM.


Time, 12 hour clock, same as "~I:~M:~S ~p".


Number of full seconds since "the epoch" (in UTC).


Second, zero padded (00...60).


Horizontal tab.


Time, 24 hour clock, same as "~H:~M:~S".


Week number of year with Sunday as first day of week (01...53).


Week number of year with Monday as first day of week (00...52).


Day of week (0...6).


Week number of year with Monday as first day of week (00...52).


Locale’s date representation, for example: "07/31/00".


Locale’s time representation, for example: "06:51:44".


Last two digits of year (00...99).




Time zone in RFC-822 style.


ISO-8601 year-month-day format.


ISO-8601 hour-minute-second-timezone format.


ISO-8601 hour-minute-second format.


ISO-8601 year-month-day-hour-minute-second-timezone format.


ISO-8601 year-month-day-hour-minute-second format.

Note: currently Gauche doesn’t honor process’s locale setting, and it always formats the date as if the locale is "C". It may be changed in future, so you shouldn’t rely on, for example, ~a always formatted as "Sun".."Sat".

There’s no portable way to ensure you’ll get "C" locale formats since there’s no standard way to set process’s locale yet. However, Gauche provides a way to ensure the locale to be "C", as an extension to srfi-19. Insert @ between ~ and the directive character, such as ~@a.

Function: string->date string template-string


Previous: , Up: Time data types and procedures   [Contents][Index]