Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

rfc3339

Read and write RFC3339-format datetimes.

Overview

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. Prior to Chicken 4.6, seconds->utc-time may not return a zero timezone offset, which will cause the RFC3339 string timezone offset to be that of the local timezone -- even though the time itself is relative to UTC. 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

Author

Jim Ursetto.

Version history
0.1.1
Unknown
0.1
Initial release.

License

BSD.