doc/timetable.md

   1 # `luatz.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] )`
  25
  26 Returns a new timetable with the given contents.
  27
  28
  29 ### `new_from_timestamp ( 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 ### `:clone ( )`
  36
  37 Returns a new independent instance of an existing timetable object.
  38
  39
  40 ### `: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 ### `:rfc_3339 ( )` and `__tostring` metamethod
  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 ( )` should be called first.
  60
  61
  62 ### `:timestamp ( )`
  63
  64 Returns the timetable as the number of seconds since unix epoch (1970-01-01) as a lua number.
  65
  66
  67 ### `:unpack ( )`
  68
  69 Unpacks the timetable object; returns `year`, `month`, `day`, `hour`, `min`, `sec`, `yday`, `wday`