logo

const class

sys::TimeZone

sys::Obj
  sys::TimeZone
   1  //
   2  // Copyright (c) 2007, Brian Frank and Andy Frank
   3  // Licensed under the Academic Free License version 3.0
   4  //
   5  // History:
   6  //   28 Sep 07  Brian Frank  Creation
   7  //
   8  
   9  **
  10  ** TimeZone represents a region's offset from UTC and its daylight
  11  ** savings time rules.  TimeZones are historical - UTC offset and DST
  12  ** rules may change depending on the year.  The Fan implementation of
  13  ** historical time zones is optimized to handle only year boundaries (so
  14  ** some historical changes which don't occur on year boundaries may
  15  ** not be 100% accurate).
  16  **
  17  ** The Fan time zone database and naming model is based on the
  18  ** [ZoneInfo database]`http://www.twinsun.com/tz/tz-link.htm` used
  19  ** by UNIX and Java (also known as the Olsen database).  All time
  20  ** zones have both a simple `name` and a `fullName`.  The 'fullName'
  21  ** is the full identifier used in the zoneinfo database such as
  22  ** "America/New_York".  The simple name is the city name only
  23  ** such as "New_York".
  24  **
  25  @simple
  26  const class TimeZone
  27  {
  28  
  29    **
  30    ** List the names of all the time zones available in the
  31    ** local time zone database.  This database is stored in
  32    ** "{home}/lib/timezone.ftz" as a binary file.  This
  33    ** list contains only the simple names such as "New_York"
  34    ** and "London".
  35    **
  36    static Str[] listNames()
  37  
  38    **
  39    ** List all zoneinfo (Olsen database) full names of the
  40    ** time zones available in the local time zone database.
  41    ** This list is the full names only such as "America/New_York"
  42    ** and "Europe/London".
  43    **
  44    static Str[] listFullNames()
  45  
  46    **
  47    ** Find a time zone by name from the built-in database.
  48    ** Either the simple name like "New_York" or the zoneinfo
  49    ** full name "America/New_York" may be used.  If the time zone
  50    ** doesn't exist and checked is false then return
  51    ** null, otherwise throw ParseErr.
  52    **
  53    static TimeZone fromStr(Str name, Bool checked := true)
  54  
  55    **
  56    ** Get the time zone which represents UTC.
  57    **
  58    static TimeZone utc()
  59  
  60    **
  61    ** Get the current default TimeZone of the VM.
  62    **
  63    static TimeZone current()
  64  
  65    **
  66    ** Get the identifier of this time zone in the time zone
  67    ** database.  Name is the city name portion of the zoneinfo
  68    ** `fullName` identifier such as "New_York" or "London".
  69    **
  70    Str name()
  71  
  72    **
  73    ** Get the full name of this time zone as defined by the zoneinfo
  74    ** database.  These names are formatted as "contintent/location"
  75    ** where location is a major city within the time zone region.
  76    ** Examples of full names are "America/New_York" and "Europe/London".
  77    **
  78    Str fullName()
  79  
  80    **
  81    ** Get the duration of time added to UTC to compute standard time
  82    ** in this time zone.  The offset is independent of daylight savings
  83    ** time - during daylight savings the actual offset is this value
  84    ** plus `dstOffset`.
  85    **
  86    Duration offset(Int year)
  87  
  88    **
  89    ** Get the duration of time which will be added to local standard
  90    ** time to get wall time during daylight savings time (often 1hr).
  91    ** If daylight savings time is not observed then return null.
  92    **
  93    Duration dstOffset(Int year)
  94  
  95    **
  96    ** Get the abbreviated name during standard time.
  97    **
  98    Str stdAbbr(Int year)
  99  
 100    **
 101    ** Get the abbreviated name during daylight savings time
 102    ** or null if daylight savings time not observed.
 103    **
 104    Str dstAbbr(Int year)
 105  
 106    **
 107    ** Return `name`.
 108    **
 109    override Str toStr()
 110  
 111  }