Class: Time

A date and time in a time zone, with the API of the moment library: reading and setting the wall clock fields in the zone (hours(), date()…), formatting (format()), the calendar arithmetic (add(), startOf(), diff()) and the comparisons (isBefore()…), across the daylight saving time changes. The time zone is an IANA name ('Asia/Shanghai'); a new time is in the default zone: the TZ environment variable, else the system's (an invalid TZ gives UTC, as for Date).

A Time is immutable through its own methods: the setters and the arithmetic return a new instance, the time they are called on does not change. It extends Date, so it is accepted where a Date is (toISOString(), toJSON() and getTime() give the instant), but the methods inherited from Date (getHours(), setHours()…) read and modify the time in the process's time zone, not in the instance's, and the setters modify the instance: use the Time methods.

An invalid time (an array field out of its range, NaN) does not throw: its format() gives 'Invalid date' and its getters NaN. An invalid string throws a RangeError.

Example

typescript

import {Time} from 'lakutata'

const departure: Time = new Time('2024-03-09T12:00:00Z').timezone('America/New_York')
console.log(departure.format(), departure.format('dddd, MMMM Do YYYY, h:mm A z'))
//2024-03-09T07:00:00-05:00 Saturday, March 9th 2024, 7:00 AM EST
//Across the daylight saving time change: a day keeps the wall clock, 24 hours do not
console.log(departure.add(1, 'day').format(), departure.add(24, 'hours').format())
//2024-03-10T07:00:00-04:00 2024-03-10T08:00:00-04:00
console.log(departure.timezone('Asia/Shanghai').format('YYYY-MM-DD HH:mm'), departure.startOf('month').format())
//2024-03-09 20:00 2024-03-01T00:00:00-05:00
console.log(new Time('2024-03-31T00:00:00Z').diff('2024-01-15T00:00:00Z', 'months'))
//2

Extends

Date

Constructors

Constructor

new Time(inp?): Time

Create a time, in the default time zone (in the zone of inp when it is a Time). Call timezone() to get it in another zone.

Parameters

inp?

TimeInput

The time (see TimeInput): now when omitted or null, a Time, a Date, milliseconds since the epoch, a date string, or the wall clock fields; a string without offset and the fields are read in the default time zone.

Returns

Time

Throws

When inp is a string which is not a date ('', 'tomorrow').

Overrides

Date.constructor

Properties

getVarDate

getVarDate: () => VarDate

Returns

VarDate

Inherited from

Date.getVarDate

Methods

[toPrimitive]()

Call Signature

[toPrimitive](hint): string

Converts a Date object to a string.

Parameters

hint

"default"

Returns

string

Inherited from

Date.[toPrimitive]

Call Signature

[toPrimitive](hint): string

Converts a Date object to a string.

Parameters

hint

"string"

Returns

string

Inherited from

Date.[toPrimitive]

Call Signature

[toPrimitive](hint): number

Converts a Date object to a number.

Parameters

hint

"number"

Returns

number

Inherited from

Date.[toPrimitive]

Call Signature

[toPrimitive](hint): string | number

Converts a Date object to a string or number.

Parameters

hint

string

The strings "number", "string", or "default" to specify what primitive to return.

Returns

string | number

A number if 'hint' was "number", a string if 'hint' was "string" or "default".

Throws

If 'hint' was given something other than "number", "string", or "default".

Inherited from

Date.[toPrimitive]

add()

add(amount, unit): Time

Add a duration. The years, quarters, months, weeks and days move the wall clock, keeping its time across a daylight saving time change (a day can last 23 or 25 hours), and a month without the day of the month takes its last day (January 31st plus a month is February 29th in 2024). The hours, minutes, seconds and milliseconds move the instant. A wall clock time skipped by a daylight saving time change (02:30 when the clocks jump from 02:00 to 03:00) moves forward by the length of the gap (03:30), whatever the time it comes from.

Parameters

amount

number

The amount, negative to go back. The fractions of the months and the days are rounded half away from zero (1.5 days is 2 days, 0.5 year is 6 months); the other units keep them (1.5 hours is 90 minutes).

unit

DurationConstructor

The unit (see UnitOfTime.DurationConstructor). A unit which is not one returns an unchanged copy.

Returns

Time

A new time; the time it is called on does not change.

clone()

clone(): Time

Copy the time: the same instant in the same time zone.

Returns

Time

A new time.

date()

Call Signature

date(): number

Get the day of the month in the time's zone.

Returns

number

The day of the month, from 1 to 31; NaN for an invalid time.

Call Signature

date(value): Time

Set the day of the month. A value out of the month's days carries over to the months (32 in January is February 1st, 0 the last day of the previous month).

Parameters

value

number

The new value; NaN leaves the time unchanged.

Returns

Time

A new time; the time it is called on does not change.

dayOfYear()

Call Signature

dayOfYear(): number

Get the day of the year in the time's zone.

Returns

number

The day of the year, from 1 to 366; NaN for an invalid time.

Call Signature

dayOfYear(value): Time

Move to another day of the year, keeping the wall clock time. A value out of the year's days carries over to the next or previous years.

Parameters

value

number

The new value, from 1 to 366.

Returns

Time

A new time; the time it is called on does not change.

daysInMonth()

daysInMonth(): number

Get the number of days of the time's month, in its zone.

Returns

number

28 to 31.

diff()

diff(inp, unit?, precise?): number

Get the time elapsed from another time to this one, in a unit: positive when this time is later. The months, quarters and years count calendar months (January 15th to March 15th is 2 months whatever their days); the days and weeks count the wall clock days in this time's zone (a 23-hour day across a daylight saving time change is one day); the hours, minutes, seconds and milliseconds count the elapsed time.

Parameters

inp

TimeInput

The other time (see TimeInput); now when null.

unit?

Diff

The unit (see UnitOfTime.Diff); milliseconds when omitted or not a unit.

precise?

boolean

Whether the result keeps its fraction; by default it is truncated toward zero (2.5 months gives 2, -2.5 gives -2).

Returns

number

The difference.

Throws

When inp is a string which is not a date.

endOf()

endOf(unit): Time

Get the end of the unit holding the time, in its zone: its last millisecond (endOf('day') is 23:59:59.999, endOf('month') the last day of the month at 23:59:59.999).

Parameters

unit

StartOf

The unit (see UnitOfTime.StartOf). 'millisecond', null or a unit which is not one returns an unchanged copy.

Returns

Time

A new time; the time it is called on does not change.

format()

Call Signature

format(): string

Format the time in its zone as ISO 8601 with its offset, to the second: '2024-03-09T07:00:00-05:00', or '2024-03-09T12:00:00Z' at the offset zero.

Returns

string

The formatted time; 'Invalid date' for an invalid time.

Call Signature

format(format): string

Format the time in its zone with the tokens of the moment library (in English):

year YYYY (2024), YY (24); quarter Q; month M (3), MM (03), MMM (Mar), MMMM (March), Mo (3rd);
day of the month D, DD, Do (9th); day of the year DDD, DDDD; day of the week d (0 is Sunday), dd (Sa), ddd (Sat), dddd (Saturday), E (ISO, 1 is Monday); weeks w, ww, ISO weeks W, WW; week years gggg, GGGG;
hours H, HH (0-23), h, hh (1-12), k, kk (1-24); A (AM/PM), a (am/pm); minutes m, mm; seconds s, ss; fractions S to SSSSSSSSS (SSS the milliseconds);
offset Z (-05:00), ZZ (-0500); the zone's abbreviation z (EST, or GMT+8 where English has none); the timestamp X (seconds), x (milliseconds);
the localized formats LT (7:00 AM), LTS, L (03/09/2024), LL (March 9, 2024), LLL, LLLL, and their short forms l, ll, lll, llll.

The text in brackets is kept as is ([at], [T]); the other characters which are not tokens too.

Parameters

format

string

The format ('YYYY-MM-DD HH:mm:ss', 'dddd, MMMM Do YYYY'); an empty string gives the default format.

Returns

string

The formatted time; 'Invalid date' for an invalid time.

get()

get(unit): number

Get a field by its unit: get('hour') is hours(), get('D') is date(), get('day') the day of the week (0 is Sunday), get('weekYear') the year of the week (weeks starting on Sunday).

Parameters

unit

All

The unit of the field (see UnitOfTime.All).

Returns

number

The field's value; NaN for a unit which is not one.

getDate()

getDate(): number

Gets the day-of-the-month, using local time.

Returns

number

Inherited from

Date.getDate

getDay()

getDay(): number

Gets the day of the week, using local time.

Returns

number

Inherited from

Date.getDay

getFullYear()

getFullYear(): number

Gets the year, using local time.

Returns

number

Inherited from

Date.getFullYear

getHours()

getHours(): number

Gets the hours in a date, using local time.

Returns

number

Inherited from

Date.getHours

getMilliseconds()

getMilliseconds(): number

Gets the milliseconds of a Date, using local time.

Returns

number

Inherited from

Date.getMilliseconds

getMinutes()

getMinutes(): number

Gets the minutes of a Date object, using local time.

Returns

number

Inherited from

Date.getMinutes

getMonth()

getMonth(): number

Gets the month, using local time.

Returns

number

Inherited from

Date.getMonth

getSeconds()

getSeconds(): number

Gets the seconds of a Date object, using local time.

Returns

number

Inherited from

Date.getSeconds

getTime()

getTime(): number

Returns the stored time value in milliseconds since midnight, January 1, 1970 UTC.

Returns

number

Inherited from

Date.getTime

getTimezoneOffset()

getTimezoneOffset(): number

Get the offset of the time's zone as Date gives it: the minutes from the wall clock to UTC, so negative east of Greenwich (-480 in UTC+8, 300 in New York in winter). It changes with the daylight saving time.

Returns

number

The offset in minutes; NaN for an invalid time.

Overrides

Date.getTimezoneOffset

getUTCDate()

getUTCDate(): number

Gets the day-of-the-month, using Universal Coordinated Time (UTC).

Returns

number

Inherited from

Date.getUTCDate

getUTCDay()

getUTCDay(): number

Gets the day of the week using Universal Coordinated Time (UTC).

Returns

number

Inherited from

Date.getUTCDay

getUTCFullYear()

getUTCFullYear(): number

Gets the year using Universal Coordinated Time (UTC).

Returns

number

Inherited from

Date.getUTCFullYear

getUTCHours()

getUTCHours(): number

Gets the hours value in a Date object using Universal Coordinated Time (UTC).

Returns

number

Inherited from

Date.getUTCHours

getUTCMilliseconds()

getUTCMilliseconds(): number

Gets the milliseconds of a Date object using Universal Coordinated Time (UTC).

Returns

number

Inherited from

Date.getUTCMilliseconds

getUTCMinutes()

getUTCMinutes(): number

Gets the minutes of a Date object using Universal Coordinated Time (UTC).

Returns

number

Inherited from

Date.getUTCMinutes

getUTCMonth()

getUTCMonth(): number

Gets the month of a Date object using Universal Coordinated Time (UTC).

Returns

number

Inherited from

Date.getUTCMonth

getUTCSeconds()

getUTCSeconds(): number

Gets the seconds of a Date object using Universal Coordinated Time (UTC).

Returns

number

Inherited from

Date.getUTCSeconds

hours()

Call Signature

hours(): number

Get the hours in the time's zone.

Returns

number

The hours, from 0 to 23; NaN for an invalid time.

Call Signature

hours(value): Time

Set the hours of the wall clock. A value out of 0 to 23 carries over to the days (25 is 01:00 the next day). A wall clock time skipped by a daylight saving time change (02:30 when the clocks jump from 02:00 to 03:00) moves forward by the length of the gap (03:30), whatever the time it is set from; a repeated one (the clocks turned back) keeps the offset of the time when it can, else is the earlier one.

Parameters

value

number

The new value; NaN leaves the time unchanged.

Returns

Time

A new time; the time it is called on does not change.

isAfter()

isAfter(inp?, granularity?): boolean

Tell whether this time is after another one. With a granularity, the unit holding this time must start after the other time: isAfter(other, 'day') is true when this time's day is after the other's.

Parameters

inp?

TimeInput

The other time (see TimeInput); now when omitted or null.

granularity?

StartOf

The unit to compare at (see UnitOfTime.StartOf), in this time's zone; the exact instant when omitted, null or 'millisecond'.

Returns

boolean

true when this time is after; false for an invalid time.

Throws

When inp is a string which is not a date.

isBefore()

isBefore(inp?, granularity?): boolean

Tell whether this time is before another one. With a granularity, the unit holding this time must end before the other time: isBefore(other, 'day') is true when this time's day is before the other's.

Parameters

inp?

TimeInput

The other time (see TimeInput); now when omitted or null.

granularity?

StartOf

The unit to compare at (see UnitOfTime.StartOf), in this time's zone; the exact instant when omitted, null or 'millisecond'.

Returns

boolean

true when this time is before; false for an invalid time.

Throws

When inp is a string which is not a date.

isBetween()

isBetween(a, b, granularity?, inclusivity?): boolean

Tell whether this time is between two others, excluding them by default.

Parameters

a

TimeInput

The start (see TimeInput); now when null. It must be the earlier one: the times are not swapped.

b

TimeInput

The end (see TimeInput); now when null.

granularity?

StartOf

The unit to compare at (see UnitOfTime.StartOf), in this time's zone; the exact instant when omitted, null or 'millisecond'.

inclusivity?

"()" | "[)" | "(]" | "[]"

Whether the start and the end are included: '()' (excluded, the default), '[)' (the start included), '(]' (the end included) or '[]' (both).

Returns

boolean

true when this time is between them.

Throws

When a or b is a string which is not a date.

isLeapYear()

isLeapYear(): boolean

Tell whether the time's year (in its zone) is a leap year.

Returns

boolean

true for a leap year.

isoWeekday()

Call Signature

isoWeekday(): number

Get the ISO day of the week in the time's zone.

Returns

number

The ISO day of the week, from 1 (Monday) to 7 (Sunday); NaN for an invalid time.

Call Signature

isoWeekday(value): Time

Move to another day of the same ISO week (Monday to Sunday), keeping the wall clock time. A value out of 1 to 7 moves to another week (8 is the next Monday).

Parameters

value

number

The new value, from 1 (Monday) to 7 (Sunday).

Returns

Time

A new time; the time it is called on does not change.

isoWeeks()

Call Signature

isoWeeks(): number

Get the ISO 8601 week of the year (weeks starting on Monday, week 1 holding the first Thursday) in the time's zone.

Returns

number

The ISO 8601 week of the year (weeks starting on Monday, week 1 holding the first Thursday), from 1 to 53; NaN for an invalid time.

Call Signature

isoWeeks(value): Time

Move to another ISO week, keeping the day of the week and the wall clock time.

Parameters

value

number

The new value, from 1 to 53.

Returns

Time

A new time; the time it is called on does not change.

isoWeeksInYear()

isoWeeksInYear(): number

Get the number of ISO 8601 weeks of the time's calendar year.

Returns

number

52 or 53.

isoWeekYear()

Call Signature

isoWeekYear(): number

Get the ISO 8601 week-numbering year: the year of the ISO week, which differs from the calendar year around January 1st (December 30th 2024 is in the week 1 of 2025).

Returns

number

The ISO week year; NaN for an invalid time.

Call Signature

isoWeekYear(value): Time

Move to another ISO week year, keeping the ISO week (clamped to the weeks of that year), the day of the week and the wall clock time.

Parameters

value

number

The ISO week year.

Returns

Time

A new time; the time it is called on does not change.

isSame()

isSame(inp?, granularity?): boolean

Tell whether this time is the same as another one. With a granularity, whether the other time falls in the same unit: isSame(other, 'day') is the same calendar day in this time's zone.

Parameters

inp?

TimeInput

The other time (see TimeInput); now when omitted or null.

granularity?

StartOf

The unit to compare at (see UnitOfTime.StartOf), in this time's zone; the exact instant when omitted, null or 'millisecond'.

Returns

boolean

true when they are the same; false for an invalid time.

Throws

When inp is a string which is not a date.

isSameOrAfter()

isSameOrAfter(inp?, granularity?): boolean

Tell whether this time is the same as another one or after it (isSame() || isAfter()).

Parameters

inp?

TimeInput

The other time (see TimeInput); now when omitted or null.

granularity?

StartOf

The unit to compare at (see UnitOfTime.StartOf), in this time's zone; the exact instant when omitted, null or 'millisecond'.

Returns

boolean

true when this time is the same or after.

Throws

When inp is a string which is not a date.

isSameOrBefore()

isSameOrBefore(inp?, granularity?): boolean

Tell whether this time is the same as another one or before it (isSame() || isBefore()).

Parameters

inp?

TimeInput

The other time (see TimeInput); now when omitted or null.

granularity?

StartOf

The unit to compare at (see UnitOfTime.StartOf), in this time's zone; the exact instant when omitted, null or 'millisecond'.

Returns

boolean

true when this time is the same or before.

Throws

When inp is a string which is not a date.

max()

static max(...times): Time

Get the latest of several times.

Parameters

times

...Time[]

The times to compare. The invalid times are ignored.

Returns

Time

The latest valid time itself (not a copy), the first of the latest ones; the first time when all are invalid; a new time of now when none is given.

milliseconds()

Call Signature

milliseconds(): number

Get the milliseconds in the time's zone.

Returns

number

The milliseconds, from 0 to 999; NaN for an invalid time.

Call Signature

milliseconds(value): Time

Set the milliseconds. A value out of 0 to 999 carries over to the seconds (1500 is 1.5 seconds later than 0).

Parameters

value

number

The new value; NaN leaves the time unchanged.

Returns

Time

A new time; the time it is called on does not change.

min()

static min(...times): Time

Get the earliest of several times.

Parameters

times

...Time[]

The times to compare. The invalid times are ignored.

Returns

Time

The earliest valid time itself (not a copy), the first of the earliest ones; the first time when all are invalid; a new time of now when none is given.

minutes()

Call Signature

minutes(): number

Get the minutes in the time's zone.

Returns

number

The minutes, from 0 to 59; NaN for an invalid time.

Call Signature

minutes(value): Time

Set the minutes. A value out of 0 to 59 carries over to the hours.

Parameters

value

number

The new value; NaN leaves the time unchanged.

Returns

Time

A new time; the time it is called on does not change.

month()

Call Signature

month(): number

Get the month in the time's zone.

Returns

number

The month, from 0 (January) to 11 (December); NaN for an invalid time.

Call Signature

month(value): Time

Set the month, keeping the day of the month when it exists in it, else taking the month's last day (January 31st set to February gives February 29th in 2024). A value out of 0 to 11 carries over to the years (12 is January of the next year).

Parameters

value

number

The new value, from 0 (January) to 11 (December); NaN leaves the time unchanged.

Returns

Time

A new time; the time it is called on does not change.

now()

static now(): number

Returns the number of milliseconds elapsed since midnight, January 1, 1970 Universal Coordinated Time (UTC).

Returns

number

Inherited from

Date.now

parse()

static parse(s): number

Parses a string containing a date, and returns the number of milliseconds between that date and midnight, January 1, 1970.

Parameters

s

string

A date string

Returns

number

Inherited from

Date.parse

quarters()

Call Signature

quarters(): number

Get the quarter in the time's zone.

Returns

number

The quarter, from 1 to 4; NaN for an invalid time.

Call Signature

quarters(value): Time

Move to another quarter of the year, keeping the month's position in its quarter and the day of the month when it exists (May 15th set to quarter 1 gives February 15th).

Parameters

value

number

The new value, from 1 to 4.

Returns

Time

A new time; the time it is called on does not change.

seconds()

Call Signature

seconds(): number

Get the seconds in the time's zone.

Returns

number

The seconds, from 0 to 59; NaN for an invalid time.

Call Signature

seconds(value): Time

Set the seconds. A value out of 0 to 59 carries over to the minutes.

Parameters

value

number

The new value; NaN leaves the time unchanged.

Returns

Time

A new time; the time it is called on does not change.

set()

set(unit, value): Time

Set a field by its unit: set('hour', 8) is hours(8), set('day', 1) moves to the Monday of the week.

Parameters

unit

All

The unit of the field (see UnitOfTime.All). A unit which is not one returns an unchanged copy.

value

number

The new value, with the rules of the field's setter.

Returns

Time

A new time; the time it is called on does not change.

setDate()

setDate(date): number

Sets the numeric day-of-the-month value of the Date object using local time.

Parameters

date

number

A numeric value equal to the day of the month.

Returns

number

Inherited from

Date.setDate

setFullYear()

setFullYear(year, month?, date?): number

Sets the year of the Date object using local time.

Parameters

year

number

A numeric value for the year.

month?

number

A zero-based numeric value for the month (0 for January, 11 for December). Must be specified if numDate is specified.

date?

number

A numeric value equal for the day of the month.

Returns

number

Inherited from

Date.setFullYear

setHours()

setHours(hours, min?, sec?, ms?): number

Sets the hour value in the Date object using local time.

Parameters

hours

number

A numeric value equal to the hours value.

min?

number

A numeric value equal to the minutes value.

sec?

number

A numeric value equal to the seconds value.

ms?

number

A numeric value equal to the milliseconds value.

Returns

number

Inherited from

Date.setHours

setMilliseconds()

setMilliseconds(ms): number

Sets the milliseconds value in the Date object using local time.

Parameters

ms

number

A numeric value equal to the millisecond value.

Returns

number

Inherited from

Date.setMilliseconds

setMinutes()

setMinutes(min, sec?, ms?): number

Sets the minutes value in the Date object using local time.

Parameters

min

number

A numeric value equal to the minutes value.

sec?

number

A numeric value equal to the seconds value.

ms?

number

A numeric value equal to the milliseconds value.

Returns

number

Inherited from

Date.setMinutes

setMonth()

setMonth(month, date?): number

Sets the month value in the Date object using local time.

Parameters

month

number

A numeric value equal to the month. The value for January is 0, and other month values follow consecutively.

date?

number

A numeric value representing the day of the month. If this value is not supplied, the value from a call to the getDate method is used.

Returns

number

Inherited from

Date.setMonth

setSeconds()

setSeconds(sec, ms?): number

Sets the seconds value in the Date object using local time.

Parameters

sec

number

A numeric value equal to the seconds value.

ms?

number

A numeric value equal to the milliseconds value.

Returns

number

Inherited from

Date.setSeconds

setTime()

setTime(time): number

Sets the date and time value in the Date object.

Parameters

time

number

A numeric value representing the number of elapsed milliseconds since midnight, January 1, 1970 GMT.

Returns

number

Inherited from

Date.setTime

setUTCDate()

setUTCDate(date): number

Sets the numeric day of the month in the Date object using Universal Coordinated Time (UTC).

Parameters

date

number

A numeric value equal to the day of the month.

Returns

number

Inherited from

Date.setUTCDate

setUTCFullYear()

setUTCFullYear(year, month?, date?): number

Sets the year value in the Date object using Universal Coordinated Time (UTC).

Parameters

year

number

A numeric value equal to the year.

month?

number

A numeric value equal to the month. The value for January is 0, and other month values follow consecutively. Must be supplied if numDate is supplied.

date?

number

A numeric value equal to the day of the month.

Returns

number

Inherited from

Date.setUTCFullYear

setUTCHours()

setUTCHours(hours, min?, sec?, ms?): number

Sets the hours value in the Date object using Universal Coordinated Time (UTC).

Parameters

hours

number

A numeric value equal to the hours value.

min?

number

A numeric value equal to the minutes value.

sec?

number

A numeric value equal to the seconds value.

ms?

number

A numeric value equal to the milliseconds value.

Returns

number

Inherited from

Date.setUTCHours

setUTCMilliseconds()

setUTCMilliseconds(ms): number

Sets the milliseconds value in the Date object using Universal Coordinated Time (UTC).

Parameters

ms

number

A numeric value equal to the millisecond value.

Returns

number

Inherited from

Date.setUTCMilliseconds

setUTCMinutes()

setUTCMinutes(min, sec?, ms?): number

Sets the minutes value in the Date object using Universal Coordinated Time (UTC).

Parameters

min

number

A numeric value equal to the minutes value.

sec?

number

A numeric value equal to the seconds value.

ms?

number

A numeric value equal to the milliseconds value.

Returns

number

Inherited from

Date.setUTCMinutes

setUTCMonth()

setUTCMonth(month, date?): number

Sets the month value in the Date object using Universal Coordinated Time (UTC).

Parameters

month

number

A numeric value equal to the month. The value for January is 0, and other month values follow consecutively.

date?

number

A numeric value representing the day of the month. If it is not supplied, the value from a call to the getUTCDate method is used.

Returns

number

Inherited from

Date.setUTCMonth

setUTCSeconds()

setUTCSeconds(sec, ms?): number

Sets the seconds value in the Date object using Universal Coordinated Time (UTC).

Parameters

sec

number

A numeric value equal to the seconds value.

ms?

number

A numeric value equal to the milliseconds value.

Returns

number

Inherited from

Date.setUTCSeconds

startOf()

startOf(unit): Time

Get the start of the unit holding the time, in its zone: startOf('day') is midnight (or the first time of the day when the clocks skip midnight), startOf('week') the Sunday, startOf('isoWeek') the Monday, startOf('month') the 1st, startOf('hour') the hour with zero minutes.

Parameters

unit

StartOf

The unit (see UnitOfTime.StartOf). 'millisecond', null or a unit which is not one returns an unchanged copy.

Returns

Time

A new time; the time it is called on does not change.

subtract()

subtract(amount, unit): Time

Subtract a duration: subtract(n, unit) is add(-n, unit) (see add for the daylight saving time changes and the month ends).

Parameters

amount

number

The amount, negative to go forward.

unit

DurationConstructor

The unit (see UnitOfTime.DurationConstructor). A unit which is not one returns an unchanged copy.

Returns

Time

A new time; the time it is called on does not change.

timezone()

Call Signature

timezone(): string

Get the time zone's IANA name ('Asia/Shanghai').

Returns

string

The name of the time zone.

Call Signature

timezone(tz): Time

Get the same instant in another time zone: the wall clock fields change, the instant does not.

Parameters

tz

string

The IANA name of the time zone ('America/New_York', 'UTC', 'Etc/GMT-8'). An empty string is the default time zone (the TZ environment variable, else the system's).

Returns

Time

A new time in that zone.

Throws

When the runtime does not know the time zone (Invalid time zone: …).

timezones()

static timezones(): string[]

List the time zones of the runtime, by their current IANA names ('Asia/Kolkata'), plus 'UTC' and the fixed offsets 'Etc/GMT-14' to 'Etc/GMT+12', sorted. timezone() also accepts the former names not listed ('Asia/Calcutta').

Returns

string[]

A new array of names.

toArray()

toArray(): [number, number, number, number, number, number, number]

Get the wall clock fields in the time's zone, in the order of the Date constructor. Passed back to new Time(), they are read in the default time zone: the instant differs when the zones differ; passed to a comparison of this time (isSame(time.toArray())), they are read in its zone.

Returns

[number, number, number, number, number, number, number]

[year, month, date, hours, minutes, seconds, milliseconds], the month from 0 (January) to 11.

toDate()

toDate(): Date

Convert the time into a plain Date of the same instant (a Date has no time zone: its local methods use the process's zone).

Returns

Date

A new Date.

toDateString()

toDateString(): string

Format the date in its zone as Date does: 'Fri Mar 01 2024'.

Returns

string

The formatted date; 'Invalid date' for an invalid time.

Overrides

Date.toDateString

toISOString()

toISOString(): string

Returns a date as a string value in ISO format.

Returns

string

Inherited from

Date.toISOString

toJSON()

toJSON(key?): string

Used by the JSON.stringify method to enable the transformation of an object's data for JavaScript Object Notation (JSON) serialization.

Parameters

key?

any

Returns

string

Inherited from

Date.toJSON

toLocaleDateString()

Call Signature

toLocaleDateString(): string

Returns a date as a string value appropriate to the host environment's current locale.

Returns

string

Inherited from

Date.toLocaleDateString

Call Signature

toLocaleDateString(locales?, options?): string

Converts a date to a string by using the current or specified locale.

Parameters

locales?

string | string[]

A locale string or array of locale strings that contain one or more language or locale tags. If you include more than one locale string, list them in descending order of priority so that the first entry is the preferred locale. If you omit this parameter, the default locale of the JavaScript runtime is used.

options?

DateTimeFormatOptions

An object that contains one or more properties that specify comparison options.

Returns

string

Inherited from

Date.toLocaleDateString

Call Signature

toLocaleDateString(locales?, options?): string

Converts a date to a string by using the current or specified locale.

Parameters

locales?

LocalesArgument

A locale string, array of locale strings, Intl.Locale object, or array of Intl.Locale objects that contain one or more language or locale tags. If you include more than one locale string, list them in descending order of priority so that the first entry is the preferred locale. If you omit this parameter, the default locale of the JavaScript runtime is used.

options?

DateTimeFormatOptions

An object that contains one or more properties that specify comparison options.

Returns

string

Inherited from

Date.toLocaleDateString

toLocaleString()

Call Signature

toLocaleString(): string

Returns a value as a string value appropriate to the host environment's current locale.

Returns

string

Inherited from

Date.toLocaleString

Call Signature

toLocaleString(locales?, options?): string

Converts a date and time to a string by using the current or specified locale.

Parameters

locales?

string | string[]

options?

DateTimeFormatOptions

An object that contains one or more properties that specify comparison options.

Returns

string

Inherited from

Date.toLocaleString

Call Signature

toLocaleString(locales?, options?): string

Converts a date and time to a string by using the current or specified locale.

Parameters

locales?

LocalesArgument

options?

DateTimeFormatOptions

An object that contains one or more properties that specify comparison options.

Returns

string

Inherited from

Date.toLocaleString

toLocaleTimeString()

Call Signature

toLocaleTimeString(): string

Returns a time as a string value appropriate to the host environment's current locale.

Returns

string

Inherited from

Date.toLocaleTimeString

Call Signature

toLocaleTimeString(locales?, options?): string

Converts a time to a string by using the current or specified locale.

Parameters

locales?

string | string[]

options?

DateTimeFormatOptions

An object that contains one or more properties that specify comparison options.

Returns

string

Inherited from

Date.toLocaleTimeString

Call Signature

toLocaleTimeString(locales?, options?): string

Converts a time to a string by using the current or specified locale.

Parameters

locales?

LocalesArgument

options?

DateTimeFormatOptions

An object that contains one or more properties that specify comparison options.

Returns

string

Inherited from

Date.toLocaleTimeString

toObject()

toObject(): TimeObject

Get the wall clock fields in the time's zone, by name.

Returns

TimeObject

The year, the month (from 0), the day of the month, the hours, minutes, seconds and milliseconds.

toString()

toString(): string

Format the time in its zone as Date does, without the zone's name: 'Fri Mar 01 2024 07:30:00 GMT+0800'.

Returns

string

The formatted time; 'Invalid date' for an invalid time (Date gives 'Invalid Date').

Overrides

Date.toString

toTimeString()

toTimeString(): string

Format the time of the day in its zone as Date does: '07:30:00 GMT+0800 (China Standard Time)'.

Returns

string

The formatted time; 'Invalid Date' for an invalid time.

Overrides

Date.toTimeString

toUTCString()

toUTCString(): string

Returns a date converted to a string using Universal Coordinated Time (UTC).

Returns

string

Inherited from

Date.toUTCString

unix()

unix(): number

Get the Unix timestamp: the whole seconds since the Unix epoch, rounded down (-1.5 seconds gives -2).

Returns

number

The seconds; NaN for an invalid time.

UTC()

Call Signature

static UTC(year, monthIndex, date?, hours?, minutes?, seconds?, ms?): number

Returns the number of milliseconds between midnight, January 1, 1970 Universal Coordinated Time (UTC) (or GMT) and the specified date.

Parameters

year

number

The full year designation is required for cross-century date accuracy. If year is between 0 and 99 is used, then year is assumed to be 1900 + year.

monthIndex

number

The month as a number between 0 and 11 (January to December).

date?

number

The date as a number between 1 and 31.

hours?

number

Must be supplied if minutes is supplied. A number from 0 to 23 (midnight to 11pm) that specifies the hour.

minutes?

number

Must be supplied if seconds is supplied. A number from 0 to 59 that specifies the minutes.

seconds?

number

Must be supplied if milliseconds is supplied. A number from 0 to 59 that specifies the seconds.

ms?

number

A number from 0 to 999 that specifies the milliseconds.

Returns

number

Inherited from

Date.UTC

Call Signature

static UTC(year, monthIndex?, date?, hours?, minutes?, seconds?, ms?): number

Returns the number of milliseconds between midnight, January 1, 1970 Universal Coordinated Time (UTC) (or GMT) and the specified date.

Parameters

year

number

The full year designation is required for cross-century date accuracy. If year is between 0 and 99 is used, then year is assumed to be 1900 + year.

monthIndex?

number

The month as a number between 0 and 11 (January to December).

date?

number

The date as a number between 1 and 31.

hours?

number

Must be supplied if minutes is supplied. A number from 0 to 23 (midnight to 11pm) that specifies the hour.

minutes?

number

Must be supplied if seconds is supplied. A number from 0 to 59 that specifies the minutes.

seconds?

number

Must be supplied if milliseconds is supplied. A number from 0 to 59 that specifies the seconds.

ms?

number

A number from 0 to 999 that specifies the milliseconds.

Returns

number

Inherited from

Date.UTC

utcOffset()

utcOffset(): number

Get the offset of the time's zone from UTC at this instant, in minutes: positive east of Greenwich (480 in UTC+8, -300 in New York in winter, -240 in summer).

Returns

number

The offset in minutes; NaN for an invalid time.

valueOf()

valueOf(): number

Returns the stored time value in milliseconds since midnight, January 1, 1970 UTC.

Returns

number

Inherited from

Date.valueOf

weekday()

Call Signature

weekday(): number

Get the day of the week (weeks starting on Sunday) in the time's zone.

Returns

number

The day of the week (weeks starting on Sunday), from 0 (Sunday) to 6 (Saturday); NaN for an invalid time.

Call Signature

weekday(value): Time

Move to another day of the same week (Sunday to Saturday), keeping the wall clock time. A value out of 0 to 6 moves to another week (7 is the next Sunday, -1 the previous Saturday).

Parameters

value

number

The new value, from 0 (Sunday) to 6 (Saturday).

Returns

Time

A new time; the time it is called on does not change.

weeks()

Call Signature

weeks(): number

Get the week of the year (weeks starting on Sunday, week 1 holding January 1st) in the time's zone.

Returns

number

The week of the year (weeks starting on Sunday, week 1 holding January 1st), from 1 to 53; NaN for an invalid time.

Call Signature

weeks(value): Time

Move to another week of the year, keeping the day of the week and the wall clock time (weeks(w) adds w - weeks() weeks).

Parameters

value

number

The new value, from 1 to 53.

Returns

Time

A new time; the time it is called on does not change.

weeksInYear()

weeksInYear(): number

Get the number of weeks of the time's year, the weeks starting on Sunday (see weeks()).

Returns

number

52 or 53.

year()

Call Signature

year(): number

Get the year in the time's zone.

Returns

number

The year, such as 2024; NaN for an invalid time.

Call Signature

year(value): Time

Set the year, keeping the month and the day; February 29th becomes February 28th in a year which is not a leap year.

Parameters

value

number

The new value, within the range of Date (about ±270,000); NaN leaves the time unchanged.

Returns

Time

A new time; the time it is called on does not change.

Class: Time ​

Example ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

inp? ​

Returns ​

Throws ​

Overrides ​

Properties ​

getVarDate ​

Returns ​

Inherited from ​

Methods ​

[toPrimitive]() ​

Call Signature ​

Parameters ​

hint ​

Returns ​

Inherited from ​

Call Signature ​

Parameters ​

hint ​

Returns ​

Inherited from ​

Call Signature ​

Parameters ​

hint ​

Returns ​

Inherited from ​

Call Signature ​

Parameters ​

hint ​

Returns ​

Throws ​

Inherited from ​

add() ​

Parameters ​

amount ​

unit ​

Returns ​

clone() ​

Returns ​

date() ​

Call Signature ​

Returns ​

Call Signature ​

Parameters ​

value ​

Returns ​

dayOfYear() ​

Call Signature ​

Returns ​

Call Signature ​

Parameters ​

value ​

Returns ​

daysInMonth() ​

Returns ​

diff() ​

Parameters ​

inp ​

unit? ​

precise? ​

Returns ​

Throws ​

endOf() ​

Parameters ​

unit ​

Returns ​

format() ​

Call Signature ​

Returns ​

Call Signature ​

Parameters ​

format ​

Returns ​

get() ​

Parameters ​

Class: Time

Example

Extends

Constructors

Constructor

Parameters

inp?

Returns

Throws

Overrides

Properties

getVarDate

Returns

Inherited from

Methods

[toPrimitive]()

Call Signature

Parameters

hint

Returns

Inherited from

Call Signature

Parameters

hint

Returns

Inherited from

Call Signature

Parameters

hint

Returns

Inherited from

Call Signature

Parameters

hint

Returns

Throws

Inherited from

add()

Parameters

amount

unit

Returns

clone()

Returns

date()

Call Signature

Returns

Call Signature

Parameters

value

Returns

dayOfYear()

Call Signature

Returns

Call Signature

Parameters

value

Returns

daysInMonth()

Returns

diff()

Parameters

inp

unit?

precise?

Returns

Throws

endOf()

Parameters

unit

Returns

format()

Call Signature

Returns

Call Signature

Parameters

format

Returns

get()

Parameters