Class DateTime

constructor

• new DateTime(): DateTime

• Constructor. Creates current time in local timezone.

  Returns DateTime

  Throws

  nothing

• new DateTime(isoString, timeZone?): DateTime

• Constructor. Parses ISO timestamp string. Non-existing local times are normalized by rounding up to the next DST offset.

  Parameters

  • isoString: string

    String in ISO 8601 format. Instead of ISO time zone, it may include a space and then and IANA time zone. e.g. "2007-04-05T12:30:40.500" (no time zone, naive date) e.g. "2007-04-05T12:30:40.500+01:00" (UTC offset without daylight saving time) or "2007-04-05T12:30:40.500Z" (UTC) or "2007-04-05T12:30:40.500 Europe/Amsterdam" (IANA time zone, with daylight saving time if applicable)
  • Optional timeZone: null | TimeZone

    if given, the date in the string is assumed to be in this time zone. Note that it is NOT CONVERTED to the time zone. Useful for strings without a time zone

  Returns DateTime

  Throws

  timezonecomplete.Argument.S if the given string is invalid

  Throws

  timezonecomplete.Argument.TimeZone if the given time zone is invalid

• new DateTime(dateString, formatString, timeZone?): DateTime

• Constructor. Parses string in given LDML format. NOTE: does not handle eras/quarters/weeks/weekdays. Non-existing local times are normalized by rounding up to the next DST offset.

  Parameters

  • dateString: string

    Date+Time string.
  • formatString: string

    The LDML format that the string is assumed to be in
  • Optional timeZone: null | TimeZone

    if given, the date in the string is assumed to be in this time zone. Note that it is NOT CONVERTED to the time zone. Useful for strings without a time zone

  Returns DateTime

  Throws

  timezonecomplete.ParseError if the given dateTimeString is wrong or not according to the pattern

  Throws

  timezonecomplete.Argument.FormatString if the given format string is invalid

  Throws

  timezonecomplete.Argument.Timezone if the given time zone is invalid

• new DateTime(date, getFuncs, timeZone?): DateTime

• Constructor. You provide a date, then you say whether to take the date.getYear()/getXxx methods or the date.getUTCYear()/date.getUTCXxx methods, and then you state which time zone that date is in. Non-existing local times are normalized by rounding up to the next DST offset. Note that the Date class has bugs and inconsistencies when constructing them with times around DST changes.

  Parameters

  • date: Date

    A date object.
  • getFuncs: DateFunctions
  • Optional timeZone: null | TimeZone

    The time zone that the given date is assumed to be in (may be undefined or null for unaware dates)

  Returns DateTime

  Throws

  timezonecomplete.Argument.GetFuncs if the getFuncs argument is invalid

  Throws

  timezonecomplete.Argument.TimeZone if the time zone argument is invalid

• new DateTime(tm, timeZone?): DateTime

• Get a date from a TimeStruct

  Parameters

  • tm: TimeStruct
  • Optional timeZone: null | TimeZone

  Returns DateTime

  Throws

  timezonecomplete.Argument.TimeZone if the given time zone argument is invalid

• new DateTime(year, month, day, hour?, minute?, second?, millisecond?, timeZone?): DateTime

• Constructor. Note that unlike JavaScript dates we require fields to be in normal ranges. Use the add(duration) or sub(duration) for arithmetic.

  Parameters

  • year: number

    The full year (e.g. 2014)
  • month: number

    The month [1-12] (note this deviates from JavaScript Date)
  • day: number

    The day of the month [1-31]
  • Optional hour: number

    The hour of the day [0-24)
  • Optional minute: number

    The minute of the hour [0-59]
  • Optional second: number

    The second of the minute [0-59]
  • Optional millisecond: number

    The millisecond of the second [0-999]
  • Optional timeZone: null | TimeZone

    The time zone, or null/undefined (for unaware dates)

  Returns DateTime

  Throws

  timezonecomplete.Argument.Year if year invalid

  Throws

  timezonecomplete.Argument.Month if month invalid

  Throws

  timezonecomplete.Argument.Day if day invalid

  Throws

  timezonecomplete.Argument.Hour if hour invalid

  Throws

  timezonecomplete.Argument.Minute if minute invalid

  Throws

  timezonecomplete.Argument.Second if second invalid

  Throws

  timezonecomplete.Argument.Milli if milliseconds invalid

• new DateTime(unixTimestamp, timeZone?): DateTime

• Constructor

  Parameters

  • unixTimestamp: number

    milliseconds since 1970-01-01T00:00:00.000
  • Optional timeZone: null | TimeZone

    the time zone that the timestamp is assumed to be in (usually UTC).

  Returns DateTime

  Throws

  timezonecomplete.Argument.TimeZone if the given time zone is invalid

  Throws

  timezonecomplete.Argument.UnixMillis if the given unix timestamp is not finite

kind

Static timeSource

add

• add(duration): DateTime

• Add a time duration relative to UTC. Returns a new DateTime

  Parameters

  • duration: Duration

  Returns DateTime

  this + duration

  Throws

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

• add(amount, unit): DateTime

• Add an amount of time relative to UTC, as regularly as possible. Returns a new DateTime

  Adding e.g. 1 hour will increment the utcHour() field, adding 1 month increments the utcMonth() field. Adding an amount of units leaves lower units intact. E.g. adding a month will leave the day() field untouched if possible.

  Note adding Months or Years will clamp the date to the end-of-month if the start date was at the end of a month, i.e. contrary to JavaScript Date#setUTCMonth() it will not overflow into the next month

  In case of DST changes, the utc time fields are still untouched but local time fields may shift.

  Parameters

  • amount: number
  • unit: TimeUnit

  Returns DateTime

  Throws

  Argument.Amount if amount is not a finite number or if you're trying to add a non-integer amount of years or months

  Throws

  Argument.Unit for invalid time unit

  Throws

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

addLocal

• addLocal(duration): DateTime

• Add an amount of time to the zone time, as regularly as possible. Returns a new DateTime

  Adding e.g. 1 hour will increment the hour() field of the zone date by one. In case of DST changes, the time fields may additionally increase by the DST offset, if a non-existing local time would be reached otherwise.

  Adding a unit of time will leave lower-unit fields intact, unless the result would be a non-existing time. Then an extra DST offset is added.

  Note adding Months or Years will clamp the date to the end-of-month if the start date was at the end of a month, i.e. contrary to JavaScript Date#setUTCMonth() it will not overflow into the next month

  Parameters

  • duration: Duration

  Returns DateTime

  Throws

  nothing

• addLocal(amount, unit): DateTime

• Add an amount of time to the zone time, as regularly as possible. Returns a new DateTime

  Adding e.g. 1 hour will increment the hour() field of the zone date by one. In case of DST changes, the time fields may additionally increase by the DST offset, if a non-existing local time would be reached otherwise.

  Adding a unit of time will leave lower-unit fields intact, unless the result would be a non-existing time. Then an extra DST offset is added.

  Note adding Months or Years will clamp the date to the end-of-month if the start date was at the end of a month, i.e. contrary to JavaScript Date#setUTCMonth() it will not overflow into the next month

  Parameters

  • amount: number
  • unit: TimeUnit

  Returns DateTime

  Throws

  Argument.Amount if amount is not a finite number or if you're trying to add a non-integer amount of years or months

  Throws

  Argument.Unit for invalid time unit

clone

• clone(): DateTime

• Returns DateTime

  a copy of this object

  Throws

  nothing

convert

• convert(zone?): DateTime

• Convert this date to the given time zone (in-place).

  Parameters

  • Optional zone: null | TimeZone

  Returns DateTime

  this (for chaining)

  Throws

  timezonecomplete.UnawareToAwareConversion if you try to convert a datetime without a zone to a datetime with a zone

day

• day(): number

• Returns number

  The day of the month 1-31

  Throws

  nothing

dayOfYear

• dayOfYear(): number

• Returns the day number within the year: Jan 1st has number 0, Jan 2nd has number 1 etc.

  Returns number

  the day-of-year [0-366]

  Throws

  nothing

diff

• diff(other): Duration

• Time difference between two DateTimes

  Parameters

  • other: DateTime

  Returns Duration

  this - other

  Throws

  nothing

equals

• equals(other): boolean

• Parameters

  • other: DateTime

  Returns boolean

  True iff this and other represent the same moment in time in UTC

  Throws

  nothing

format

• format(formatString, locale?): string

• Return a string representation of the DateTime according to the specified format. See LDML.md for supported formats.

  Parameters

  • formatString: string

    The format specification (e.g. "dd/MM/yyyy HH:mm:ss")
  • Optional locale: PartialLocale

    Optional, non-english format month names etc.

  Returns string

  The string representation of this DateTime

  Throws

  timezonecomplete.Argument.FormatString for invalid format pattern

greaterEqual

• greaterEqual(other): boolean

• Parameters

  • other: DateTime

  Returns boolean

  True iff this >= other

  Throws

  nothing

greaterThan

• greaterThan(other): boolean

• Parameters

  • other: DateTime

  Returns boolean

  True iff this > other

  Throws

  nothing

hour

• hour(): number

• Returns number

  The hour 0-23

  Throws

  nothing

identical

• identical(other): boolean

• Parameters

  • other: DateTime

  Returns boolean

  True iff this and other represent the same time and the same zone

  Throws

  nothing

lessEqual

• lessEqual(other): boolean

• Parameters

  • other: DateTime

  Returns boolean

  True iff (this <= other)

  Throws

  nothing

lessThan

• lessThan(other): boolean

• Parameters

  • other: DateTime

  Returns boolean

  True iff (this < other)

  Throws

  nothing

max

• max(other): DateTime

• Parameters

  • other: DateTime

  Returns DateTime

  The maximum of this and other

  Throws

  nothing

millisecond

• millisecond(): number

• Returns number

  the milliseconds 0-999

  Throws

  nothing

min

• min(other): DateTime

• Parameters

  • other: DateTime

  Returns DateTime

  The minimum of this and other

  Throws

  nothing

minute

• minute(): number

• Returns number

  the minutes 0-59

  Throws

  nothing

month

• month(): number

• Returns number

  The month 1-12 (note this deviates from JavaScript Date)

  Throws

  nothing

offset

• offset(): number

• Returns number

  the offset including DST w.r.t. UTC in minutes. Returns 0 for unaware dates and for UTC dates.

  Throws

  nothing

offsetDuration

• offsetDuration(): Duration

• Returns Duration

  the offset including DST w.r.t. UTC as a Duration.

  Throws

  nothing

second

• second(): number

• Returns number

  the seconds 0-59

  Throws

  nothing

secondOfDay

• secondOfDay(): number

• Returns the number of seconds that have passed on the current day Does not consider leap seconds

  Returns number

  seconds [0-86399]

  Throws

  nothing

standardOffsetDuration

• standardOffsetDuration(): Duration

• Returns Duration

  the standard offset WITHOUT DST w.r.t. UTC as a Duration.

  Throws

  nothing

startOfDay

• startOfDay(): DateTime

• Chops off the time part, yields the same date at 00:00:00.000

  Returns DateTime

  a new DateTime

  Throws

  nothing

startOfMonth

• startOfMonth(): DateTime

• Returns the first day of the month at 00:00:00

  Returns DateTime

  a new DateTime

  Throws

  nothing

startOfYear

• startOfYear(): DateTime

• Returns the first day of the year at 00:00:00

  Returns DateTime

  a new DateTime

  Throws

  nothing

sub

• sub(duration): DateTime

• Same as add(-1*duration); Returns a new DateTime

  Parameters

  • duration: Duration

  Returns DateTime

  Throws

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

• sub(amount, unit): DateTime

• Same as add(-1*amount, unit); Returns a new DateTime

  Parameters

  • amount: number
  • unit: TimeUnit

  Returns DateTime

  Throws

  Argument.Amount if amount is not a finite number or if you're trying to add a non-integer amount of years or months

  Throws

  Argument.Unit for invalid time unit

  Throws

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

subLocal

• subLocal(duration): DateTime

• Same as addLocal(-1*amount, unit); Returns a new DateTime

  Parameters

  • duration: Duration

  Returns DateTime

  Throws

  nothing

• subLocal(amount, unit): DateTime

• Same as addLocal(-1*amount, unit); Returns a new DateTime

  Parameters

  • amount: number
  • unit: TimeUnit

  Returns DateTime

  Throws

  Argument.Amount if amount is not a finite number or if you're trying to add a non-integer amount of years or months

  Throws

  Argument.Unit for invalid time unit

toDate

• toDate(): Date

• Convert to JavaScript date with the zone time in the getX() methods. Unless the timezone is local, the Date.getUTCX() methods will NOT be correct. This is because Date calculates getUTCX() from getX() applying local time zone.

  Returns Date

  Throws

  nothing

toExcel

• toExcel(timeZone?): number

• Create an Excel timestamp for this datetime converted to the given zone. Does not work for dates < 1900

  Parameters

  • Optional timeZone: null | TimeZone

    Optional. Zone to convert to, default the zone the datetime is already in.

  Returns number

  an Excel date/time number i.e. days since 1-1-1900 where 1900 is incorrectly seen as leap year

  Throws

  timezonecomplete.UnawareToAwareConversion if you try to convert a naive datetime to an aware one.

toIsoString

• toIsoString(): string

• Proper ISO 8601 format string with any IANA zone converted to ISO offset E.g. "2014-01-01T23:15:33+01:00" for Europe/Amsterdam Unaware dates have no zone information at the end.

  Returns string

  Throws

  nothing

toString

• toString(): string

• Modified ISO 8601 format string with IANA name if applicable. E.g. "2014-01-01T23:15:33.000 Europe/Amsterdam"

  Returns string

  Throws

  nothing

toUtcExcel

• toUtcExcel(): number

• Create an Excel timestamp for this datetime converted to UTC Does not work for dates < 1900

  Returns number

  an Excel date/time number i.e. days since 1-1-1900 where 1900 is incorrectly seen as leap year

  Throws

  nothing

toUtcIsoString

• toUtcIsoString(): string

• Convert to UTC and then return ISO string ending in 'Z'. This is equivalent to Date#toISOString() e.g. "2014-01-01T23:15:33 Europe/Amsterdam" becomes "2014-01-01T22:15:33Z". Unaware dates are assumed to be in UTC

  Returns string

  Throws

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

toUtcString

• toUtcString(): string

• Modified ISO 8601 format string in UTC without time zone info

  Returns string

  Throws

  nothing

toZone

• toZone(zone?): DateTime

• Returns this date converted to the given time zone. Unaware dates can only be converted to unaware dates (clone) Converting an unaware date to an aware date throws an exception. Use the constructor if you really need to do that.

  Parameters

  • Optional zone: null | TimeZone

    The new time zone. This may be null or undefined to create unaware date.

  Returns DateTime

  The converted date

  Throws

  timezonecomplete.UnawareToAwareConversion if you try to convert a naive datetime to an aware one.

unixUtcMillis

• unixUtcMillis(): number

• Returns number

  Milliseconds since 1970-01-01T00:00:00.000Z

  Throws

  nothing

utcDay

• utcDay(): number

• Returns number

  The UTC day of the month 1-31

  Throws

  nothing

utcDayOfYear

• utcDayOfYear(): number

• Returns the UTC day number within the year: Jan 1st has number 0, Jan 2nd has number 1 etc.

  Returns number

  the day-of-year [0-366]

  Throws

  nothing

utcHour

• utcHour(): number

• Returns number

  The UTC hour 0-23

  Throws

  nothing

utcMillisecond

• utcMillisecond(): number

• Returns number

  The UTC milliseconds 0-999

  Throws

  nothing

utcMinute

• utcMinute(): number

• Returns number

  The UTC minutes 0-59

  Throws

  nothing

utcMonth

• utcMonth(): number

• Returns number

  The UTC month 1-12 (note this deviates from JavaScript Date)

  Throws

  nothing

utcSecond

• utcSecond(): number

• Returns number

  The UTC seconds 0-59

  Throws

  nothing

utcSecondOfDay

• utcSecondOfDay(): number

• Returns the number of seconds that have passed on the current day Does not consider leap seconds

  Returns number

  seconds [0-86399]

  Throws

  nothing

utcWeekDay

• utcWeekDay(): WeekDay

• Returns WeekDay

  the UTC day-of-week (the enum values correspond to JavaScript week day numbers)

  Throws

  nothing

utcWeekNumber

• utcWeekNumber(): number

• The ISO 8601 UTC week number. Week 1 is the week that has January 4th in it, and it starts on Monday. See https://en.wikipedia.org/wiki/ISO_week_date

  Returns number

  Week number [1-53]

  Throws

  nothing

utcWeekOfMonth

• utcWeekOfMonth(): number

• The week of this month. There is no official standard for this, but we assume the same rules for the weekNumber (i.e. week 1 is the week that has the 4th day of the month in it)

  Returns number

  Week number [1-5]

  Throws

  nothing

utcYear

• utcYear(): number

• Returns number

  The full year e.g. 2014

  Throws

  nothing

valueOf

• valueOf(): number

• The valueOf() method returns the primitive value of the specified object.

  Returns number

  Throws

  nothing

weekDay

• weekDay(): WeekDay

• Returns WeekDay

  the day-of-week (the enum values correspond to JavaScript week day numbers)

  Throws

  nothing

weekNumber

• weekNumber(): number

• The ISO 8601 week number. Week 1 is the week that has January 4th in it, and it starts on Monday. See https://en.wikipedia.org/wiki/ISO_week_date

  Returns number

  Week number [1-53]

  Throws

  nothing

weekOfMonth

• weekOfMonth(): number

• The week of this month. There is no official standard for this, but we assume the same rules for the weekNumber (i.e. week 1 is the week that has the 4th day of the month in it)

  Returns number

  Week number [1-5]

  Throws

  nothing

withZone

• withZone(zone?): DateTime

• Returns a new DateTime which is the date+time reinterpreted as in the new zone. So e.g. 08:00 America/Chicago can be set to 08:00 Europe/Brussels. No conversion is done, the value is just assumed to be in a different zone. Works for naive and aware dates. The new zone may be null.

  Parameters

  • Optional zone: null | TimeZone

    The new time zone

  Returns DateTime

  A new DateTime with the original timestamp and the new zone.

  Throws

  nothing

year

• year(): number

• Returns number

  The full year e.g. 2014

  Throws

  nothing

zone

• zone(): undefined | TimeZone

• Returns undefined | TimeZone

  The time zone that the date is in. May be undefined for unaware dates.

  Throws

  nothing

zoneAbbreviation

• zoneAbbreviation(dstDependent?): string

• Zone name abbreviation at this time

  Parameters

  • dstDependent: boolean = true

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

  Returns string

  The abbreviation

  Throws

  nothing

Static exists

• exists(year, month?, day?, hour?, minute?, second?, millisecond?, zone?, allowPre1970?): boolean

• Check whether a given date exists in the given time zone. E.g. 2015-02-29 returns false (not a leap year) and 2015-03-29T02:30:00 returns false (daylight saving time missing hour) and 2015-04-31 returns false (April has 30 days). By default, pre-1970 dates also return false since the time zone database does not contain accurate info before that. You can change that with the allowPre1970 flag.

  Parameters

  • year: number
  • month: number = 1
  • day: number = 1
  • hour: number = 0
  • minute: number = 0
  • second: number = 0
  • millisecond: number = 0
  • Optional zone: null | TimeZone
  • allowPre1970: boolean = false

    (optional, default false): return true for pre-1970 dates

  Returns boolean

  Throws

  nothing

Static fromExcel

• fromExcel(n, timeZone?): DateTime

• Create a DateTime from a Lotus 123 / Microsoft Excel date-time value i.e. a double representing days since 1-1-1900 where 1900 is incorrectly seen as leap year Does not work for dates < 1900

  Parameters

  • n: number

    excel date/time number
  • Optional timeZone: null | TimeZone

    Time zone to assume that the excel value is in

  Returns DateTime

  a DateTime

  Throws

  timezonecomplete.Argument.N if n is not a finite number

  Throws

  timezonecomplete.Argument.TimeZone if the given time zone is invalid

Static now

• now(timeZone?): DateTime

• Current date+time in the given time zone

  Parameters

  • timeZone: undefined | null | TimeZone = ...

    The desired time zone (optional, defaults to UTC).

  Returns DateTime

  Throws

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

Static nowLocal

• nowLocal(): DateTime

• Current date+time in local time

  Returns DateTime

  Throws

  nothing

Static nowUtc

• nowUtc(): DateTime

• Current date+time in UTC time

  Returns DateTime

  Throws

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

Static parse

• parse(s, format, zone?, locale?, allowTrailing?): DateTime

• Parse a date in a given format

  Parameters

  • s: string

    the string to parse
  • format: string

    the format the string is in. See LDML.md for supported formats.
  • Optional zone: TimeZone

    Optional, the zone to add (if no zone is given in the string)
  • Optional locale: PartialLocale

    Optional, different settings for constants like 'AM' etc
  • Optional allowTrailing: boolean

    Allow trailing characters in the source string

  Returns DateTime

  Throws

  timezonecomplete.ParseError if the given dateTimeString is wrong or not according to the pattern

  Throws

  timezonecomplete.Argument.FormatString if the given format string is invalid