doc/tzinfo.md

   1 # `luatz.tzinfo`
   2
   3 Provides a metatable for the timezone class.
   4
   5 Created in `luatz.tzfile` and managed by `luatz.tzcache`;
   6 a timezone object contains information about a timezone.
   7 These objects are based on the information available in a "zoneinfo" file.
   8
   9 Timezone objects should be considered opaque and immutable;
  10 so the following details can be skipped over.
  11
  12 ------------------------------------------------------------------------------
  13
  14 The table contains a sequence of tables that describe the timezone at a given point
  15 using a `transition_time`: the unix timestamp (in UTC) that this definition starts, and
  16 a `tt_info` object.
  17
  18 A `tt_info` object contains information about a time offset;
  19 and contains the following fields:
  20
  21   - `gmtoff` (number) The offset from GMT (UTC) in seconds
  22   - `isdst` (boolean): If this change was declared as daylight savings
  23   - `abbrind` (number, abbreviation id)
  24   - `abbr` (string): short name for this gmt offset
  25   - `isstd` (boolean)
  26   - `isgmt` (boolean)
  27
  28
  29 ## `:find_current ( utc_ts )`
  30
  31 Returns the relevant `tt_info` object for the given UTC timestamp in the timezone.
  32
  33
  34 ## `:localise ( utc_ts )` and `:localize ( utc_ts )`
  35
  36 Convert the given UTC timestamp to the timezone.
  37 Returns the number of seconds since unix epoch in the given timezone.
  38
  39
  40 ## `:utctime ( local_ts )`
  41
  42 Convert the given local timestamp (seconds since unix epoch in the time zone) to a UTC timestamp.
  43 This may result in ambigous results, in which case multiple values are returned.
  44
  45 e.g. consider that when daylight savings rewinds your local clock from 3am to 2am there will be two 2:30ams.