doc/timetable.md

   1 ## `luatz.timetable` <!-- --> {#timetable}
   2
   3 Provides an class to represent a time and date.
   4 Objects have no concept of timezone or utc offset.
   5
   6 The fields are intentionally compatible with the lua standard library's `os.date` and `os.time`. Objects have fields:
   7
   8   - `year`
   9   - `month`
  10   - `day`
  11   - `hour`
  12   - `min`
  13   - `sec`
  14   - `yday` (optional)
  15   - `wday` (optional)
  16
  17 timetable components may be outside of their standard range (e.g. a month component of
  18 14) to facilitate arithmetic operations on date components. `:normalise()` can be
  19 called to modify components to return to their standard range.
  20
  21 Equality and comparisons should work between timetable objects.
  22
  23
  24 ### `new(year, month, day, hour, min, sec[, yday[, [wday]])` <!-- --> {#timetable.new}
  25
  26 Returns a new timetable with the given contents.
  27
  28
  29 ### `new_from_timestamp(timestamp)` <!-- --> {#timetable.new_from_timestamp}
  30
  31 Returns a new (normalised) timetable, given a timestamp in seconds since the unix epoch of
  32 1970-01-01.
  33
  34
  35 ### `timetable:clone()` <!-- --> {#timetable:clone}
  36
  37 Returns a new independent instance of an existing timetable object.
  38
  39
  40 ### `timetable:normalise()` <!-- --> {#timetable:normalise}
  41
  42 Mutates the current object's time and date components so that are integers within 'normal'
  43 ranges e.g. `month` is `1`-`12`; `min` is `0`-`59`
  44
  45 First, fractional parts are propagated down.
  46 e.g. `.month=6.5` `.day=1` (which could be read as "the first day after the middle of June")
  47 normalises to `.month=2` `.day=16`
  48
  49 Second, any fields outside of their normal ranges are propagated up
  50 e.g. `.hour=10` `.min=100` (100 minutes past 10am)
  51 normalises to `.hour=11` `.min=40`
  52
  53
  54 ### `timetable:rfc_3339()` <!-- --> {#timetable:rfc_3339}
  55
  56 Returns the timetable formatted as an rfc-3339 style string.
  57 The timezone offset (or Z) is not appended.
  58 The ranges of components are not checked, if you want a valid timestamp,
  59 [`:normalise()`](#timetable:normalise) should be called first.
  60
  61 This function is also the `__tostring` metamethod for timetable objects
  62
  63
  64 ### `timetable:timestamp()` <!-- --> {#timetable:timestamp}
  65
  66 Returns the timetable as the number of seconds since unix epoch (1970-01-01) as a lua number.
  67
  68
  69 ### `timetable:unpack()` <!-- --> {#timetable:unpack}
  70
  71 Unpacks the timetable object; returns `year`, `month`, `day`, `hour`, `min`, `sec`, `yday`, `wday`