Class TimeZone

classKind

abbreviationForUtc

• abbreviationForUtc(year?, month?, day?, hour?, minute?, second?, milli?, dstDependent?): string

• Zone abbreviation at given UTC timestamp e.g. CEST for Central European Summer Time.

  Parameters

  • Optional year: number

    Full year
  • Optional month: number

    Month 1-12 (note this deviates from JavaScript date)
  • Optional day: number

    Day of month 1-31
  • Optional hour: number

    Hour 0-23
  • Optional minute: number

    Minute 0-59
  • Optional second: number

    Second 0-59
  • Optional milli: number
  • Optional dstDependent: boolean

    (default true) set to false for a DST-agnostic abbreviation

  Returns string

  "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(utcTime, dstDependent?): string

• Zone abbreviation at given UTC timestamp e.g. CEST for Central European Summer Time.

  Parameters

  • utcTime: TimeStruct
  • Optional dstDependent: boolean

  Returns string

  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

clone

• clone(): TimeZone

• Makes this class appear clonable. NOTE as time zone objects are immutable you will NOT actually get a clone but the same object.

  Returns TimeZone

  Throws

  nothing

dst

• dst(): boolean

• Whether DST is enabled

  Returns boolean

  Throws

  nothing

equals

• equals(other): boolean

• Equality operator. Maps zero offsets and different names for UTC onto each other. Other time zones are not mapped onto each other.

  Parameters

  • other: TimeZone

  Returns boolean

  Throws

  timezonecomplete.InvalidTimeZoneData if the global time zone data is invalid

hasDst

• hasDst(): boolean

• Does this zone have Daylight Saving Time at all?

  Returns boolean

  Throws

  timezonecomplete.InvalidTimeZoneData if the global time zone data is invalid

identical

• identical(other): boolean

• Returns true iff the constructor arguments were identical, so UTC !== GMT

  Parameters

  • other: TimeZone

  Returns boolean

  Throws

  nothing

isUtc

• isUtc(): boolean

• Is this zone equivalent to UTC?

  Returns boolean

  Throws

  timezonecomplete.InvalidTimeZoneData if the global time zone data is invalid

kind

• kind(): TimeZoneKind

• The kind of time zone (Local/Offset/Proper)

  Returns TimeZoneKind

  Throws

  nothing

name

• name(): string

• 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.

  Returns string

  Throws

  nothing

normalizeZoneTime

• normalizeZoneTime(localUnixMillis, opt?): 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.

  Parameters

  • localUnixMillis: number
  • Optional opt: NormalizeOption

    (optional) Round up or down? Default: up

  Returns number

  unix milliseconds in zone time, normalized.

  Throws

  timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

• normalizeZoneTime(localTime, opt?): TimeStruct

• 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.

  Parameters

  • localTime: TimeStruct

    zone time timestamp
  • Optional opt: NormalizeOption

    (optional) Round up or down? Default: up

  Returns TimeStruct

  time struct in zone time, normalized.

  Throws

  timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

offsetForUtc

• offsetForUtc(offsetForUtc): number

• Calculate timezone offset including DST from a UTC time.

  Parameters

  • offsetForUtc: TimeStruct

  Returns number

  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(year?, month?, day?, hour?, minute?, second?, milli?): number

• Calculate timezone offset including DST from a UTC time.

  Parameters

  • Optional year: number
  • Optional month: number

    1-12
  • Optional day: number
  • Optional hour: number
  • Optional minute: number
  • Optional second: number
  • Optional milli: number

  Returns number

  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

offsetForUtcDate

• offsetForUtcDate(date, funcs): 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

  Parameters

  • date: Date
  • funcs: DateFunctions

  Returns number

  Throws

  timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

offsetForZone

• offsetForZone(localTime): number

• Calculate timezone offset from a zone-local time (NOT a UTC time).

  Parameters

  • localTime: TimeStruct

    the local time

  Returns number

  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(year?, month?, day?, hour?, minute?, second?, milli?): number

• Calculate timezone offset from a zone-local time (NOT a UTC time).

  Parameters

  • Optional year: number

    local full year
  • Optional month: number

    local month 1-12 (note this deviates from JavaScript date)
  • Optional day: number

    local day of month 1-31
  • Optional hour: number

    local hour 0-23
  • Optional minute: number

    local minute 0-59
  • Optional second: number

    local second 0-59
  • Optional milli: number

  Returns number

  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

offsetForZoneDate

• offsetForZoneDate(date, funcs): 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

  Parameters

  • date: Date
  • funcs: DateFunctions

  Returns number

  Throws

  timezonecomplete.InvalidTimeZoneData if values in the time zone database are invalid

standardOffsetForUtc

• standardOffsetForUtc(offsetForUtc): number

• Calculate timezone standard offset excluding DST from a UTC time.

  Parameters

  • offsetForUtc: TimeStruct

  Returns number

  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(year?, month?, day?, hour?, minute?, second?, milli?): number

• Calculate timezone standard offset excluding DST from a UTC time.

  Parameters

  • Optional year: number
  • Optional month: number

    1-12
  • Optional day: number
  • Optional hour: number
  • Optional minute: number
  • Optional second: number
  • Optional milli: number

  Returns number

  the standard 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

toString

• toString(): string

• The time zone identifier (normalized). Either "localtime", IANA name, or "+hh:mm" offset.

  Returns string

  Throws

  nothing

Static local

• local(): TimeZone

• 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

  Returns TimeZone

  Throws

  nothing

Static offsetToString

• offsetToString(offset): string

• Convert an offset number into an offset string

  Parameters

  • offset: number

    The offset in minutes from UTC e.g. 90 minutes

  Returns string

  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 stringToOffset

• stringToOffset(s): number

• String to offset conversion.

  Parameters

  • s: string

    Formats: "-01:00", "-0100", "-01", "Z"

  Returns number

  offset w.r.t. UTC in minutes

  Throws

  timezonecomplete.Argument.S if s cannot be parsed

Static utc

• utc(): TimeZone

• The UTC time zone.

  Returns TimeZone

  Throws

  timezonecomplete.NotFound.Zone if the UTC time zone doesn't exist in the time zone database

Static zone

• zone(offset): TimeZone

• Time zone with a fixed offset

  Parameters

  • offset: number

    offset w.r.t. UTC in minutes, e.g. 90 for +01:30

  Returns TimeZone

  Throws

  timezonecomplete.Argument.Offset if the offset is not within -24h...+24h (in minutes)

• zone(s, dst?): 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.

  Parameters

  • s: string

    "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.
  • Optional dst: boolean

    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.

  Returns TimeZone

  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