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 they lie within 'normal'
  43 ranges e.g. `month` is `1`-`12`; `min` is `0`-`59`
  44
  45
  46 ## `:rfc_3339 ( )` and `__tostring` metamethod
  47
  48 Returns the timetable formatted as an rfc-3339 style string.
  49 The timezone offset (or Z) is not appended.
  50 The ranges of components are not checked, if you want a valid timestamp,
  51 `:normalise ( )` should be called first.
  52
  53
  54 ## `:timestamp ( )`
  55
  56 Returns the timetable as the number of seconds since unix epoch (1970-01-01) as a lua number.
  57
  58
  59 ## `:unpack ( )`
  60
  61 Unpacks the timetable object; returns `year`, `month`, `day`, `hour`, `min`, `sec`, `yday`, `wday`