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 faciliate 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 timetable given a timestamp in seconds since the unix epoch of
  32 1970-01-01.
  33
  34 `:normalise ( )` should probably be called before use to resolve to the current time and
  35 date.
  36
  37
  38 ## `:clone ( )`
  39
  40 Returns a new independant instance of an existing timetable object.
  41
  42
  43 ## `:normalise ( )`
  44
  45 Mutates the current object's time and date components so that they lie within 'normal'
  46 ranges e.g. `month` is `1`-`12`; `min` is `0`-`59`
  47
  48
  49 ## `:rfc_3339 ( )` and `__tostring` metamethod
  50
  51 Returns the timetable formatted as an rfc-3339 style string.
  52 The timezone offset (or Z) is not appended.
  53 The ranges of components are not checked, and if you want a valid timestamp, `:normalise
  54 ( )` should be called first.
  55
  56
  57 ## `:timestamp ( )`
  58
  59 Returns the timetable as the number of seconds since unix epoch (1970-01-01) as a lua
  60 number.
  61
  62
  63 ## `:unpack ( )`
  64
  65 Unpacks the timetable object; returns `year`, `month`, `day`, `hour`, `min`, `sec`, `yday`, `wday`