Read and write RFC3339-format datetimes.


rfc3339 allows reading and writing of RFC3339 datetime strings, as well as conversion into other formats, such as seconds since UNIX epoch or Chicken's standard 10-element time vector. These datetimes are represented by rfc3339 record types, which are typically constructed and accessed implicitly by the high-level conversion procedures. However, they can also be created or accessed directly.

Core API

RFC3339 record

[procedure] (make-rfc3339 year month day hours minutes seconds fractions offset)
[procedure] (rfc3339? R)
[procedure] (rfc3339-year R)
[procedure] (rfc3339-month R)
[procedure] (rfc3339-day R)
[procedure] (rfc3339-hours R)
[procedure] (rfc3339-minutes R)
[procedure] (rfc3339-seconds R)
[procedure] (rfc3339-fractions R)
[procedure] (rfc3339-offset R)

A record representing an RFC3339 datetime. The record fields are:

year the year AD 1-9999, e.g. 2010
month the month 1-12, where January = 1
day the day 1-31
hours the hour 0-23
minutes the minutes 0-59
seconds the seconds 0-59
fractions fractions of a second, 0 <= x < 1
offset seconds west of UTC

Record field values may be out of range; no checking is done for validity.

String parsing

[procedure] (string->rfc3339 str)

Parses an RFC3339 format date like yyyy-mm-ddThh:mm:ss(.sss...)(Z|[+-]hh:mm) and returns an rfc3339 record or #f if the parse failed. All fields except the fractional second part are required; if omitted, fractions is set to zero. The parser permits "T" and "Z" to be lowercase.

The parser does not reject numbers that are out of range, as long as the date is formatted correctly; in other words, two-digit fields may range from 0-99. The resulting record is not normalized. However, values will be normalized when converted into seconds since epoch or a time vector.

[procedure] (rfc3339->string R)

Convert rfc3339 record to a RFC3339 string. The "T" and "Z" characters in the result string are always uppercase. All fields are, by definition, present except for fractional seconds, which are omitted if zero.

RFC3339 record values are not normalized before conversion, so some values could be out of range; however values /are/ clamped to the range 0-99 (or 0-9999 for years).

UNIX time objects

[procedure] (rfc3339->seconds R)

Converts an rfc3339 record into seconds since the UNIX epoch (1970-01-01 00:00:00 UTC). Out of range values are allowed on input; the record is normalized during conversion.

[procedure] (time->rfc3339 tm)

Converts a 10-element time vector TM, such as that returned by seconds->utc-time or seconds->local-time, to an rfc3339 record. The timezone offset field is honored. Values are not range-checked.

See utc-time->rfc3339 if you notice that the records have a non-zero timezone offset for UTC.

Convenience functions

[procedure] (rfc3339->vector R)
[procedure] (vector->rfc3339 V)

Convert an RFC3339 record to and from an 8-element vector, '#(year month day hours minutes seconds fractions offset).

[procedure] (rfc3339 obj)

Construct an rfc3339 record based on the type of the argument. If a string, it will use string->rfc3339. If a vector, it will use vector->rfc3339.

[procedure] (seconds->rfc3339 sec)

Convert integer number of seconds since UNIX epoch into an rfc3339 record which is represented as UTC time. In other words, (utc-time->rfc3339 (seconds->utc-time sec)).

[procedure] (rfc3339->utc-time R)
[procedure] (rfc3339->local-time R)

Convert an RFC3339 record into a 10-element time vector. In other words, (seconds->utc-time (rfc3339->seconds R)) and (seconds->local-time (rfc3339->seconds R)).

[procedure] (utc-time->rfc3339 R)

Workaround for an issue with time->rfc3339. This function will force the timezone offset to UTC.

This case can be tested for by running the egg tests during installation time.

About this egg


Jim Ursetto.


This egg is hosted on the CHICKEN Subversion repository:


If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.

Version history

Fix test suite to reflect that rfc3339->seconds returns an exact integer now.
Port to CHICKEN 5.
Initial release.