Documentation

Class

TimeZone

TimeZone(options)

Create a time zone instance.

This class reports and transforms information about particular time zones.

The options parameter may contain any of the following properties:

  • id - The id of the requested time zone such as "Europe/London" or "America/Los_Angeles". These are taken from the IANA time zone database. (See http://www.iana.org/time-zones for more information.)

    There is one special time zone that is not taken from the IANA database called simply "local". In this case, this class will attempt to discover the current time zone and daylight savings time settings by calling standard Javascript classes to determine the offsets from UTC.

  • locale - The locale for this time zone.
  • offset - Choose the time zone based on the offset from UTC given in number of minutes (negative is west, positive is east).
  • onLoad - a callback function to call when the data is fully loaded. When the onLoad option is given, this class will attempt to load any missing locale data using the ilib loader callback. When the data is loaded, the onLoad function is called with the current instance as a parameter.
  • sync - tell whether to load any missing locale data synchronously or asynchronously. If this option is given as "false", then the "onLoad" callback must be given, as the instance returned from this constructor will not be usable for a while.
  • loadParams - an object containing parameters to pass to the loader callback function when locale data is missing. The parameters are not interpretted or modified in any way. They are simply passed along. The object may contain any property/value pairs as long as the calling code is in agreement with the loader callback function as to what those parameters mean.

There is currently no way in the ECMAscript standard to tell which exact time zone is currently in use. Choosing the id "locale" or specifying an explicit offset will not give a specific time zone, as it is impossible to tell with certainty which zone the offsets match.

When the id "local" is given or the offset option is specified, this class will have the following behaviours:

  • The display name will always be given as the RFC822 style, no matter what style is requested
  • The id will also be returned as the RFC822 style display name
  • When the offset is explicitly given, this class will assume the time zone does not support daylight savings time, and the offsets will be calculated the same way year round.
  • When the offset is explicitly given, the inDaylightSavings() method will always return false.
  • When the id "local" is given, this class will attempt to determine the daylight savings time settings by examining the offset from UTC on Jan 1 and June 1 of the current year. If they are different, this class assumes that the local time zone uses DST. When the offset for a particular date is requested, it will use the built-in Javascript support to determine the offset for that date.

If a more specific time zone is needed with display names and known start/stop times for DST, use the "id" property instead to specify the time zone exactly. You can perhaps ask the user which time zone they prefer so that your app does not need to guess.

If the id and the offset are both not given, the default time zone for the locale is retrieved from the locale info. If the locale is not specified, the default locale for the library is used.

Because this class was designed for use in web sites, and the vast majority of dates and times being formatted are recent date/times, this class is simplified by not implementing historical time zones. That is, when governments change the time zone rules for a particular zone, only the latest such rule is implemented in this class. That means that determining the offset for a date that is prior to the last change may give the wrong result. Historical time zone calculations may be implemented in a later version of iLib if there is enough demand for it, but it would entail a much larger set of time zone data that would have to be loaded.

Constructor

# new TimeZone(options)

Parameters:
Name Type Description
options Object

Options guiding the construction of this time zone instance

View Source TimeZone.js, line 127

Methods

# getCountry() → {string}

Returns the ISO 3166 code of the country for which this time zone is defined.

View Source TimeZone.js, line 892

the ISO 3166 code of the country for this zone

string

# getDSTSavings() → {Object.<{h:number, m:number, s:number}>}

Return the amount of time in hours:minutes that the clock is advanced during daylight savings time.

View Source TimeZone.js, line 624

the amount of time that the clock advances for DST in hours, minutes, and seconds

Object.<{h:number, m:number, s:number}>

# getDSTSavingsStr() → {string}

Return the amount of time in hours:minutes that the clock is advanced during daylight savings time.

View Source TimeZone.js, line 647

the amount of time that the clock advances for DST in the format "h:m:s"

string

# getDisplayName(date, styleopt) → {string}

Return the abbreviation that is used for the current time zone on the given date. The date may be in DST or during standard time, and many zone names have different abbreviations depending on whether or not the date is falls within DST.

There are two styles that are supported:

  1. standard - returns the 3 to 5 letter abbreviation of the time zone name such as "CET" for "Central European Time" or "PDT" for "Pacific Daylight Time"
  2. rfc822 - returns an RFC 822 style time zone specifier, which specifies more explicitly what the offset is from UTC
  3. long - returns the long name of the zone in English
Parameters:
Name Type Attributes Description
date IDate | Object | JulianDay | Date | string | number

a date to determine if it is in daylight time or standard time
style string <optional>

one of "standard" or "rfc822". Default if not specified is "standard"

View Source TimeZone.js, line 390

the name of the time zone, abbreviated according to the style

string

# getId() → {string}

Return the id used to uniquely identify this time zone.

View Source TimeZone.js, line 367

a unique id for this time zone

string

# getOffset(date) → {Object.<{h:number, m:number}>}

Returns the offset of this time zone from UTC at the given date/time. If daylight saving time is in effect at the given date/time, this method will return the offset value adjusted by the amount of daylight saving.

Parameters:
Name Type Description
date IDate | Object | JulianDay | Date | string | number

the date for which the offset is needed

View Source TimeZone.js, line 488

an object giving the offset for the zone at the given date/time, in hours, minutes, and seconds

Object.<{h:number, m:number}>

# getOffsetMillis(date) → {number}

Returns the offset of this time zone from UTC at the given date/time expressed in milliseconds. If daylight saving time is in effect at the given date/time, this method will return the offset value adjusted by the amount of daylight saving. Negative numbers indicate offsets west of UTC and conversely, positive numbers indicate offset east of UTC.

Parameters:
Name Type Description
date IDate | Object | JulianDay | Date | string | number

the date for which the offset is needed, or null for the present date

View Source TimeZone.js, line 517

the number of milliseconds of offset from UTC that the given date is

number

# getOffsetStr(date) → {string}

Returns the offset of this time zone from UTC at the given date/time. If daylight saving time is in effect at the given date/time, this method will return the offset value adjusted by the amount of daylight saving.

Parameters:
Name Type Description
date IDate | Object | JulianDay | Date | string | number

the date for which the offset is needed

View Source TimeZone.js, line 563

the offset for the zone at the given date/time as a string in the format "h:m:s"

string

# getRawOffset() → {Object.<{h:number, m:number, s:number}>}

Gets the offset from UTC for this time zone.

View Source TimeZone.js, line 585

an object giving the offset from UTC for this time zone, in hours, minutes, and seconds

Object.<{h:number, m:number, s:number}>

# getRawOffsetMillis() → {number}

Gets the offset from UTC for this time zone expressed in milliseconds. Negative numbers indicate zones west of UTC, and positive numbers indicate zones east of UTC.

View Source TimeZone.js, line 605

an number giving the offset from UTC for this time zone in milliseconds

number

# getRawOffsetStr() → {string}

Gets the offset from UTC for this time zone without DST savings.

View Source TimeZone.js, line 613

the offset from UTC for this time zone, in the format "h:m:s"

string

# inDaylightTime(date, wallTimeopt) → {boolean}

Returns whether or not the given date is in daylight saving time for the current zone. Note that daylight savings time is observed for the summer. Because the seasons are reversed, daylight savings time in the southern hemisphere usually runs from the end of the year through New Years into the first few months of the next year. This method will correctly calculate the start and end of DST for any location.

Parameters:
Name Type Attributes Description
date IDate | Object | JulianDay | Date | string | number

a date for which the info about daylight time is being sought, or undefined to tell whether we are currently in daylight savings time
wallTime boolean <optional>

if true, then the given date is in wall time. If false or undefined, it is in the usual UTC time.

View Source TimeZone.js, line 790

true if the given date is in DST for the current zone, and false otherwise.

boolean

# useDaylightTime(year) → {boolean}

Returns true if this time zone switches to daylight savings time at some point in the year, and false otherwise.

Parameters:
Name Type Description
year number

Whether or not the time zone uses daylight time in the given year. If this parameter is not given, the current year is assumed.

View Source TimeZone.js, line 878

true if the time zone uses daylight savings time

boolean

# static getAvailableIds(country, sync, onLoad) → {Array.<string>}

Return an array of available zone ids that the constructor knows about. The country parameter is optional. If it is not given, all time zones will be returned. If it specifies a country code, then only time zones for that country will be returned.

Parameters:
Name Type Description
country string | undefined

country code for which time zones are being sought
sync boolean

whether to find the available ids synchronously (true) or asynchronously (false)
onLoad function

callback function to call when the data is finished loading

View Source TimeZone.js, line 326

an array of zone id strings

Array.<string>