Class TimeZone

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.

Properties

classKind

Methods

abbreviationForUtc clone dst equals hasDst identical isUtc kind name normalizeZoneTime offsetForUtc offsetForUtcDate offsetForZone offsetForZoneDate standardOffsetForUtc toString local offsetToString stringToOffset utc zone

Properties

classKind

classKind: string = "TimeZone"

Allow not using instanceof

Methods

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

    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

    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

    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

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

    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

    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

    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

    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

    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

    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

Settings

Member Visibility

Theme

On This Page

classKindabbreviationForUtcclonedstequalshasDstidenticalisUtckindnamenormalizeZoneTimeoffsetForUtcoffsetForUtcDateoffsetForZoneoffsetForZoneDatestandardOffsetForUtctoStringlocaloffsetToStringstringToOffsetutczone

Generated using TypeDoc