chickadee » rfc3339

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

make-rfc3339 year month day hours minutes seconds fractions offsetprocedure

rfc3339? Rprocedure

rfc3339-year Rprocedure

rfc3339-month Rprocedure

rfc3339-day Rprocedure

rfc3339-hours Rprocedure

rfc3339-minutes Rprocedure

rfc3339-seconds Rprocedure

rfc3339-fractions Rprocedure

rfc3339-offset Rprocedure

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

string->rfc3339 strprocedure

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.

rfc3339->string Rprocedure

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

rfc3339->seconds Rprocedure

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.

time->rfc3339 tmprocedure

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

rfc3339->vector Rprocedure

vector->rfc3339 Vprocedure

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

rfc3339 objprocedure

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.

seconds->rfc3339 secprocedure

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)).

rfc3339->utc-time Rprocedure

rfc3339->local-time Rprocedure

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)).

utc-time->rfc3339 Rprocedure

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.