# Date and time

This unit provides the concept of "time" as a timestamp from an epoch. When we
refer to time, we refer to an unsigned 32-bit value that represents the number
of seconds elapsed from our epoch, which is the january 1st 2000 at 00:00. Time
before this date is unrepresentable.

This differs from the POSIX epoch, which is in 1970, because this epoch
overflows in 2032 in its signed form. We're building a new system entirely, we
might as well give us some more wiggle room, time-wise.

When dealing with time, we usually want to know what time it is now. This unit
provides "now", but requires drivers such as [drv/pc/rtc] to implement it. Its
default implementation is a dummy one that errors out. It is expected to be
realiased by a RTC driver.

Time values don't imply a timezone. The concept of "now" is by convention a
local time one.

For time measurement ranging from microseconds to minutes, this unit is not what
you want. You want [drv/timer].

## Compose/decompose

Timestamps can be decomposed in those elements (valid range in parens):

* year (2000-2136)
* month (1-12)
* day (1-31)
* hour (0-23)
* minute (0-59)
* second (0-59)

The words "compose" and "decompose" work with static values of the names above
and either decompose a timestamp into them or compose a timestamp out of them.

For example, "0 decompose" would set year=2000, month=1, day=1, rest=0. Another
example is that "0 decompose 1 to minute compose" would yield 60.

"decompose" will always yield correct values, but not "compose". When setting
an invalid combination of decomposed values, "compose" will yield a nonsensical
timestamp.

## Time format

There's only one time format, "<year>/<month>/<day> <hour>:<minute>:<seconds>",
year being 4 digits, all other fields being 2 digits each, prefixed with 0 if
less than 10. This means that formatted timestamps are always 19 characters
long.

## API

### Constants

TIMEFMTSZ   Size in bytes of a formatted timestamp

### Values

year
month
day
hour
minute
second      Static values used for "compose" and "decompose"

### Words

now ( -- time )
  Yield current time.

compose ( -- time )
decompose ( time -- )
  See "Compose/decompose" above.

formattime ( time -- a u )
  Formats time to the time format described above. Clobbers compose/decompose
  values. The range thus yielded is static.

.time ( time -- )
  Shortcut for "formattime rtype".
