11.7.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]{srfi.19} UTC time. Gauche’s built-in current-time always returns this type (see Time).

Constant: time-tai ¶

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

Constant: time-monotonic ¶

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

Constant: time-duration ¶

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

Constant: time-process ¶

[SRFI-19]{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]{srfi.19} CPU time in current thread. In the current implementation, this is the same as time-process.

---

11.7.2 Time queries

Function: current-time :optional time-type ¶

[SRFI-19]{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 Time types.

Function: current-date :optional tz-offset ¶

[SRFI-19]{srfi.19} Returns the current date as an instance of <date> class (see 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]{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]{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 :optional type ¶

[SRFI-19]{srfi.19} Returns clock resolution of the time type type in nanoseconds, as an exact positive integer. If type is omitted, time-utc is assumed.

Note: In the current implementation, the return value isn’t actual resolution, but a value that’s guaranteed to be equal to or greater than the actual resolution.

---

11.7.3 Time procedures

Function: make-time type nanoseconds seconds ¶

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

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]{srfi.19} Getter and setter of <time> object slots.

Function: copy-time time ¶

[SRFI-19]{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]{srfi.19} Compares two times. Types of both times must match.

Function: time-difference time0 time1 ¶

Function: time-difference! time0 time1 ¶

[SRFI-19]{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]{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.

See also seconds+ (Time).

---

11.7.4 Date

Class: <date> ¶

{srfi.19} 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]{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]{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]{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]{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]{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]{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]{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]{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]{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]{srfi.19} Conversions from time-utc to various date/time types.

---

11.7.5 Date reader and writer

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

[SRFI-19+]{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 ~.

~a

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

~A

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

~b

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

~B

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

~c

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

~d

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

~D

Date (mm/dd/yy).

~e

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

~f

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

~h

Same as ~b.

~H

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

~I

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

~j

Day of year, zero padded.

~k

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

~l

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

~m

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

~M

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

~n

New line.

~N

Nanosecond, zero padded.

~p

Locale’s AM or PM.

~r

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

~s

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

~S

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

~t

Horizontal tab.

~T

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

~U

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

~V

ISO8601 Week number of year with Monday as first day of week. The week with the first Thursday is week 01. If there’s a partial week before that, it becomes week 52 or 53 of the preceding year (01...53).

~w

Day of week (0...6).

~W

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

~x

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

~X

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

~y

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

~Y

Year.

~z

Time zone in RFC-822 style.

~1

ISO-8601 year-month-day format, e.g. "2001-02-03".

~2

ISO-8601 hour-minute-second-timezone format, e.g. "04:56:12-1000".

~3

ISO-8601 hour-minute-second format, e.g. "04:56:12".

~4

ISO-8601 year-month-day-hour-minute-second-timezone format, e.g. "2001-02-03T04:56:12-1000".

~5

ISO-8601 year-month-day-hour-minute-second format, e.g. "2001-02-03T04:56:12".

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 ¶

[SRFI-19]{srfi.19}