Class TimeZone

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.
Defined in: ilib-full-dyn.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	TimeZone(options)

Method Summary
Method Attributes	Method Name and Description
<static>	TimeZone.getAvailableIds(country, sync, onLoad) Return an array of available zone ids that the constructor knows about.
	getCountry() Returns the ISO 3166 code of the country for which this time zone is defined.
	getDisplayName(date, style) Return the abbreviation that is used for the current time zone on the given date.
	getDSTSavings() Return the amount of time in hours:minutes that the clock is advanced during daylight savings time.
	getDSTSavingsStr() Return the amount of time in hours:minutes that the clock is advanced during daylight savings time.
	getId() Return the id used to uniquely identify this time zone.
	getOffset(date) Returns the offset of this time zone from UTC at the given date/time.
	getOffsetMillis(date) Returns the offset of this time zone from UTC at the given date/time expressed in milliseconds.
	getOffsetStr(date) Returns the offset of this time zone from UTC at the given date/time.
	getRawOffset() Gets the offset from UTC for this time zone.
	getRawOffsetMillis() Gets the offset from UTC for this time zone expressed in milliseconds.
	getRawOffsetStr() Gets the offset from UTC for this time zone without DST savings.
	inDaylightTime(date, wallTime) Returns whether or not the given date is in daylight saving time for the current zone.
	useDaylightTime(year) Returns true if this time zone switches to daylight savings time at some point in the year, and false otherwise.

Class Detail

TimeZone(options)

Parameters:
{Object} options: Options guiding the construction of this time zone instance

Method Detail

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

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:
{string|undefined} country: country code for which time zones are being sought
{boolean} sync: whether to find the available ids synchronously (true) or asynchronously (false)
{function(Array.)} onLoad: callback function to call when the data is finished loading

Returns:: {Array.<string>} an array of zone id strings

{string} getCountry()

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

Returns:: {string} the ISO 3166 code of the country for this zone

{string} getDisplayName(date, style)

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:

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"
rfc822 - returns an RFC 822 style time zone specifier, which specifies more explicitly what the offset is from UTC
long - returns the long name of the zone in English

Parameters:
{IDate=} date: a date to determine if it is in daylight time or standard time
{string=} style: one of "standard" or "rfc822". Default if not specified is "standard"

Returns:: {string} the name of the time zone, abbreviated according to the style

{Object.<{h:number|m:number|s:number}>} getDSTSavings()

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

Returns:: {Object.<{h:number|m:number|s:number}>} the amount of time that the clock advances for DST in hours, minutes, and seconds

{string} getDSTSavingsStr()

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

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

{string} getId()

Return the id used to uniquely identify this time zone.

Returns:: {string} a unique id for this time zone

{Object.<{h:number|m:number}>} getOffset(date)

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:
{IDate=} date: the date for which the offset is needed

Returns:: {Object.<{h:number|m:number}>} an object giving the offset for the zone at the given date/time, in hours, minutes, and seconds

{number} getOffsetMillis(date)

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:
{IDate=} date: the date for which the offset is needed, or null for the present date

Returns:: {number} the number of milliseconds of offset from UTC that the given date is

{string} getOffsetStr(date)

Parameters:
{IDate=} date: the date for which the offset is needed

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

{Object.<{h:number|m:number|s:number}>} getRawOffset()

Gets the offset from UTC for this time zone.

Returns:: {Object.<{h:number|m:number|s:number}>} an object giving the offset from UTC for this time zone, in hours, minutes, and seconds

{number} getRawOffsetMillis()

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.

Returns:: {number} an number giving the offset from UTC for this time zone in milliseconds

{string} getRawOffsetStr()

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

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

{boolean} inDaylightTime(date, wallTime)

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:
{IDate=} date: a date for which the info about daylight time is being sought, or undefined to tell whether we are currently in daylight savings time
{boolean=} wallTime: if true, then the given date is in wall time. If false or undefined, it is in the usual UTC time.

Returns:: {boolean} true if the given date is in DST for the current zone, and false otherwise.

{boolean} useDaylightTime(year)

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

Parameters:
{number} year: Whether or not the time zone uses daylight time in the given year. If this parameter is not given, the current year is assumed.

Returns:: {boolean} true if the time zone uses daylight savings time

Classes

Class TimeZone