timezonecomplete
Version:
DateTime, TimeZone, Duration and Period library aimed at providing a consistent and complete date-time interface, away from the original JavaScript Date class.
386 lines (385 loc) • 17.1 kB
TypeScript
/**
* Copyright(c) 2014 ABB Switzerland Ltd.
*
* Time zone representation and offset calculation
*/
import { TimeStruct } from "./basics";
import { DateFunctions } from "./javascript";
import { NormalizeOption } from "./tz-database";
/**
* The local time zone for a given date as per OS settings. Note that time zones are cached
* so you don't necessarily get a new object each time.
* @throws nothing
*/
export declare function local(): TimeZone;
/**
* Coordinated Universal Time zone. Note that time zones are cached
* so you don't necessarily get a new object each time.
* @throws timezonecomplete.NotFound.Zone if the UTC zone is not present in the time zone database
*/
export declare function utc(): TimeZone;
/**
* @param offset offset w.r.t. UTC in minutes, e.g. 90 for +01:30. Note that time zones are cached
* so you don't necessarily get a new object each time.
* @returns a time zone with the given fixed offset
* @throws timezonecomplete.Argument.Offset if the given offset is not within -24h...+24h (in minutes)
*/
export declare function zone(offset: number): TimeZone;
/**
* Time zone for an offset string or an IANA time zone string. Note that time zones are cached
* so you don't necessarily get a new object each time.
* @param s "localtime" for local time,
* a TZ database time zone name (e.g. Europe/Amsterdam),
* or an offset string (either +01:30, +0130, +01, Z). For a full list of names, see:
* https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
* @param dst Optional, default true: adhere to Daylight Saving Time if applicable. Note for
* "localtime", timezonecomplete will adhere to the computer settings, the DST flag
* does not have any effect.
* @throws timezonecomplete.Argument.S if s cannot be parsed
* @throws timezonecomplete.NotFound.Zone if the zone name doesn't exist in the time zone database
*/
export declare function zone(name: string, dst?: boolean): TimeZone;
/**
* The type of time zone
*/
export declare enum TimeZoneKind {
/**
* Local time offset as determined by JavaScript Date class.
*/
Local = 0,
/**
* Fixed offset from UTC, without DST.
*/
Offset = 1,
/**
* IANA timezone managed through Olsen TZ database. Includes
* DST if applicable.
*/
Proper = 2
}
/**
* Time zone. The object is immutable because it is cached:
* requesting a time zone twice yields the very same object.
* Note that we use time zone offsets inverted w.r.t. JavaScript Date.getTimezoneOffset(),
* i.e. offset 90 means +01:30.
*
* Time zones come in three flavors: the local time zone, as calculated by JavaScript Date,
* a fixed offset ("+01:30") without DST, or a IANA timezone ("Europe/Amsterdam") with DST
* applied depending on the time zone rules.
*/
export declare class TimeZone {
/**
* Allow not using instanceof
*/
classKind: string;
/**
* Time zone identifier:
* "localtime" string for local time
* E.g. "-01:30" for a fixed offset from UTC
* E.g. "UTC" or "Europe/Amsterdam" for an Olsen TZ database time
*/
private _name;
/**
* Adhere to Daylight Saving Time if applicable
*/
private _dst;
/**
* The kind of time zone specified by _name
*/
private _kind;
/**
* Only for fixed offsets: the offset in minutes
*/
private _offset;
/**
* The local time zone for a given date. Note that
* the time zone varies with the date: amsterdam time for
* 2014-01-01 is +01:00 and amsterdam time for 2014-07-01 is +02:00
* @throws nothing
*/
static local(): TimeZone;
/**
* The UTC time zone.
* @throws timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database
*/
static utc(): TimeZone;
/**
* Time zone with a fixed offset
* @param offset offset w.r.t. UTC in minutes, e.g. 90 for +01:30
* @throws timezonecomplete.Argument.Offset if the offset is not within -24h...+24h (in minutes)
*/
static zone(offset: number): TimeZone;
/**
* Time zone for an offset string or an IANA time zone string. Note that time zones are cached
* so you don't necessarily get a new object each time.
* @param s "localtime" for local time,
* a TZ database time zone name (e.g. Europe/Amsterdam),
* or an offset string (either +01:30, +0130, +01, Z). For a full list of names, see:
* https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
* TZ database zone name may be suffixed with " without DST" to indicate no DST should be applied.
* In that case, the dst parameter is ignored.
* @param dst Optional, default true: adhere to Daylight Saving Time if applicable. Note for
* "localtime", timezonecomplete will adhere to the computer settings, the DST flag
* does not have any effect.
* @throws timezonecomplete.Argument.S if s cannot be parsed
* @throws timezonecomplete.NotFound.Zone if the zone name doesn't exist in the time zone database
*/
static zone(s: string, dst?: boolean): TimeZone;
/**
* Do not use this constructor, use the static
* TimeZone.zone() method instead.
* @param name NORMALIZED name, assumed to be correct
* @param dst Adhere to Daylight Saving Time if applicable, ignored for local time and fixed offsets
* @throws timezonecomplete.NotFound.Zone if the given zone name doesn't exist
* @throws timezonecomplete.InvalidTimeZoneData if the time zone database is invalid
*/
private constructor();
/**
* Makes this class appear clonable. NOTE as time zone objects are immutable you will NOT
* actually get a clone but the same object.
* @throws nothing
*/
clone(): TimeZone;
/**
* The time zone identifier. Can be an offset "-01:30" or an
* IANA time zone name "Europe/Amsterdam", or "localtime" for
* the local time zone.
* @throws nothing
*/
name(): string;
/**
* Whether DST is enabled
* @throws nothing
*/
dst(): boolean;
/**
* The kind of time zone (Local/Offset/Proper)
* @throws nothing
*/
kind(): TimeZoneKind;
/**
* Equality operator. Maps zero offsets and different names for UTC onto
* each other. Other time zones are not mapped onto each other.
* @throws timezonecomplete.InvalidTimeZoneData if the global time zone data is invalid
*/
equals(other: TimeZone): boolean;
/**
* Returns true iff the constructor arguments were identical, so UTC !== GMT
* @throws nothing
*/
identical(other: TimeZone): boolean;
/**
* Is this zone equivalent to UTC?
* @throws timezonecomplete.InvalidTimeZoneData if the global time zone data is invalid
*/
isUtc(): boolean;
/**
* Does this zone have Daylight Saving Time at all?
* @throws timezonecomplete.InvalidTimeZoneData if the global time zone data is invalid
*/
hasDst(): boolean;
/**
* Calculate timezone offset including DST from a UTC time.
* @return the offset of this time zone with respect to UTC at the given time, in minutes.
* @throws timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid
*/
offsetForUtc(offsetForUtc: TimeStruct): number;
/**
* Calculate timezone offset including DST from a UTC time.
* @param year
* @param month 1-12
* @param day
* @param hour
* @param minute
* @param second
* @param milli
* @return the offset of this time zone with respect to UTC at the given time, in minutes.
* @throws timezonecomplete.Argument.Year for invalid year
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.Day for invalid day
* @throws timezonecomplete.Argument.Hour for invalid hour
* @throws timezonecomplete.Argument.Minute for invalid minute
* @throws timezonecomplete.Argument.Second for invalid second
* @throws timezonecomplete.Argument.Milli for invalid milliseconds
* @throws timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid
*/
offsetForUtc(year?: number, month?: number, day?: number, hour?: number, minute?: number, second?: number, milli?: number): number;
/**
* Calculate timezone standard offset excluding DST from a UTC time.
* @return the standard offset of this time zone with respect to UTC at the given time, in minutes.
* @throws timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid
*/
standardOffsetForUtc(offsetForUtc: TimeStruct): number;
/**
* Calculate timezone standard offset excluding DST from a UTC time.
* @return the standard offset of this time zone with respect to UTC at the given time, in minutes.
* @param year
* @param month 1-12
* @param day
* @param hour
* @param minute
* @param second
* @param milli
* @throws timezonecomplete.Argument.Year for invalid year
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.Day for invalid day
* @throws timezonecomplete.Argument.Hour for invalid hour
* @throws timezonecomplete.Argument.Minute for invalid minute
* @throws timezonecomplete.Argument.Second for invalid second
* @throws timezonecomplete.Argument.Milli for invalid milliseconds
* @throws timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid
*/
standardOffsetForUtc(year?: number, month?: number, day?: number, hour?: number, minute?: number, second?: number, milli?: number): number;
/**
* Calculate timezone offset from a zone-local time (NOT a UTC time).
* @param localTime the local time
* @return the offset of this time zone with respect to UTC at the given time, in minutes.
* @throws timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid
*/
offsetForZone(localTime: TimeStruct): number;
/**
* Calculate timezone offset from a zone-local time (NOT a UTC time).
* @param year local full year
* @param month local month 1-12 (note this deviates from JavaScript date)
* @param day local day of month 1-31
* @param hour local hour 0-23
* @param minute local minute 0-59
* @param second local second 0-59
* @param millisecond local millisecond 0-999
* @return the offset of this time zone with respect to UTC at the given time, in minutes.
* @throws timezonecomplete.Argument.Year for invalid year
* @throws timezonecomplete.Argument.Month for invalid month
* @throws timezonecomplete.Argument.Day for invalid day
* @throws timezonecomplete.Argument.Hour for invalid hour
* @throws timezonecomplete.Argument.Minute for invalid minute
* @throws timezonecomplete.Argument.Second for invalid second
* @throws timezonecomplete.Argument.Milli for invalid milliseconds
* @throws timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid
*/
offsetForZone(year?: number, month?: number, day?: number, hour?: number, minute?: number, second?: number, milli?: number): number;
/**
* Note: will be removed in version 2.0.0
*
* Convenience function, takes values from a Javascript Date
* Calls offsetForUtc() with the contents of the date
*
* @param date: the date
* @param funcs: the set of functions to use: get() or getUTC()
* @throws timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid
*/
offsetForUtcDate(date: Date, funcs: DateFunctions): number;
/**
* Note: will be removed in version 2.0.0
*
* Convenience function, takes values from a Javascript Date
* Calls offsetForUtc() with the contents of the date
*
* @param date: the date
* @param funcs: the set of functions to use: get() or getUTC()
* @throws timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid
*/
offsetForZoneDate(date: Date, funcs: DateFunctions): number;
/**
* Zone abbreviation at given UTC timestamp e.g. CEST for Central European Summer Time.
*
* @param year Full year
* @param month Month 1-12 (note this deviates from JavaScript date)
* @param day Day of month 1-31
* @param hour Hour 0-23
* @param minute Minute 0-59
* @param second Second 0-59
* @param millisecond Millisecond 0-999
* @param dstDependent (default true) set to false for a DST-agnostic abbreviation
*
* @return "local" for local timezone, the offset for an offset zone, or the abbreviation for a proper zone.
* @throws timezonecomplete.NotFound.Zone if zone name not found or a linked zone not found
* @throws timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid
*/
abbreviationForUtc(year?: number, month?: number, day?: number, hour?: number, minute?: number, second?: number, milli?: number, dstDependent?: boolean): string;
/**
* Zone abbreviation at given UTC timestamp e.g. CEST for Central European Summer Time.
*
* @param utcTime
* @param dstDependent
* @throws timezonecomplete.NotFound.Zone if zone name not found or a linked zone not found
* @throws timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid
*/
abbreviationForUtc(utcTime: TimeStruct, dstDependent?: boolean): string;
/**
* Normalizes non-existing local times by adding a forward offset change.
* During a forward standard offset change or DST offset change, some amount of
* local time is skipped. Therefore, this amount of local time does not exist.
* This function adds the amount of forward change to any non-existing time. After all,
* this is probably what the user meant.
*
* @param localTime zone time timestamp as unix milliseconds
* @param opt (optional) Round up or down? Default: up
*
* @returns unix milliseconds in zone time, normalized.
* @throws timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid
*/
normalizeZoneTime(localUnixMillis: number, opt?: NormalizeOption): number;
/**
* Normalizes non-existing local times by adding a forward offset change.
* During a forward standard offset change or DST offset change, some amount of
* local time is skipped. Therefore, this amount of local time does not exist.
* This function adds the amount of forward change to any non-existing time. After all,
* this is probably what the user meant.
*
* @param localTime zone time timestamp
* @param opt (optional) Round up or down? Default: up
*
* @returns time struct in zone time, normalized.
* @throws timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid
*/
normalizeZoneTime(localTime: TimeStruct, opt?: NormalizeOption): TimeStruct;
/**
* The time zone identifier (normalized).
* Either "localtime", IANA name, or "+hh:mm" offset.
* @throws nothing
*/
toString(): string;
/**
* Convert an offset number into an offset string
* @param offset The offset in minutes from UTC e.g. 90 minutes
* @return the offset in ISO notation "+01:30" for +90 minutes
* @throws Argument.Offset if offset is not a finite number or not within -24 * 60 ... +24 * 60 minutes
*/
static offsetToString(offset: number): string;
/**
* String to offset conversion.
* @param s Formats: "-01:00", "-0100", "-01", "Z"
* @return offset w.r.t. UTC in minutes
* @throws timezonecomplete.Argument.S if s cannot be parsed
*/
static stringToOffset(s: string): number;
/**
* Time zone cache.
*/
private static _cache;
/**
* Find in cache or create zone
* @param name Time zone name
* @param dst Adhere to Daylight Saving Time?
* @throws timezonecomplete.NotFound.Zone if the zone doesn't exist in the time zone database
*/
private static _findOrCreate;
/**
* Normalize a string so it can be used as a key for a cache lookup
* @throws Argument.S if s is empty
*/
private static _normalizeString;
/**
* Returns true iff the first non-whitespace character of s is +, -, or Z
* @param s
* @throws nothing
*/
private static _isOffsetString;
}
/**
* Checks if a given object is of type TimeZone. Note that it does not work for sub classes. However, use this to be robust
* against different versions of the library in one process instead of instanceof
* @param value Value to check
* @throws nothing
*/
export declare function isTimeZone(value: any): value is TimeZone;