Skip to main content
Version: 2.0.0

Class: abstract DateTime

Represents a point in time, encapsulating date and time information. This class cannot be instantiated directly but provides various methods for manipulating and interacting with date-time values.

Properties​

date​

date: LocalDate

The date part of this DateTime.

Example​

const date = dateTime.date; // The date part, e.g. "2024-12-25"

dayOfMonth​

dayOfMonth: number

The day of the month, from 1 to 31.

Example​

const dayOfMonth = dateTime.dayOfMonth; // The day of the month, e.g. 25

dayOfWeek​

dayOfWeek: number

The day of the week, from 1 (Monday) to 7 (Sunday).

Example​

const dayOfWeek = dateTime.dayOfWeek; // The day of the week, e.g. 5 (Friday)

dayOfYear​

dayOfYear: number

The day of the year, from 1 to 365 (or 366 in a leap year).

Example​

const dayOfYear = dateTime.dayOfYear; // The day of the year, e.g. 360

hour​

hour: number

The hour of the day, from 0 to 23.

Example​

const hour = dateTime.hour; // The hour of the day, e.g. 14

minute​

minute: number

The minute of the hour, from 0 to 59.

Example​

const minute = dateTime.minute; // The minute of the hour, e.g. 30

month​

month: number

The month of the year, from 1 (January) to 12 (December).

Example​

const month = dateTime.month; // The month of the year, e.g. 12

nano​

nano: number

The nanosecond of the second, from 0 to 999,999,999.

Example​

const nano = dateTime.nano; // The nanosecond of the second, e.g. 500000000

second​

second: number

The second of the minute, from 0 to 59.

Example​

const second = dateTime.second; // The second of the minute, e.g. 0

time​

time: Time

The time part of this DateTime.

Example​

const time = dateTime.time; // The time part, e.g. "14:30:00"

year​

year: number

The year part of this DateTime.

Example​

const year = dateTime.year; // The year part, e.g. 2024

Methods​

atZone()​

atZone(zone): DateTime

Associates this DateTime with a specific time zone.

Parameters​

zone​

TimeZone

The time zone to associate with.

Returns​

DateTime

A new DateTime instance representing the same moment in time in the specified zone.

Example​

const zonedDateTime = dateTime.atZone(TimeZone.of('America/New_York')); // Same moment in New York

isAfter()​

isAfter(value): boolean

Checks if this DateTime is after the specified DateTime.

Parameters​

value​

DateTime

The DateTime to compare against.

Returns​

boolean

True if this DateTime is after the specified DateTime.

Example​

const isAfter = dateTime.isAfter(anotherDateTime); // True if after

isBefore()​

isBefore(value): boolean

Checks if this DateTime is before the specified DateTime.

Parameters​

value​

DateTime

The DateTime to compare against.

Returns​

boolean

True if this DateTime is before the specified DateTime.

Example​

const isBefore = dateTime.isBefore(anotherDateTime); // True if before

isEqual()​

isEqual(value): boolean

Checks if this DateTime is equal to the specified DateTime.

Parameters​

value​

DateTime

The DateTime to compare against.

Returns​

boolean

True if this DateTime is equal to the specified DateTime.

Example​

const isEqual = dateTime.isEqual(anotherDateTime); // True if equal

minusDays()​

minusDays(days): DateTime

Returns a new DateTime with the specified number of days subtracted.

Parameters​

days​

number

The number of days to subtract.

Returns​

DateTime

A new DateTime instance with the days subtracted.

Example​

const newDateTime = dateTime.minusDays(10); // Ten days

minusHours()​

minusHours(hours): DateTime

Returns a new DateTime with the specified number of hours subtracted.

Parameters​

hours​

number

The number of hours to subtract.

Returns​

DateTime

A new DateTime instance with the hours subtracted.

Example​

const newDateTime = dateTime.minusHours(2); // Two hours

minusMinutes()​

minusMinutes(minutes): DateTime

Returns a new DateTime with the specified number of minutes subtracted.

Parameters​

minutes​

number

The number of minutes to subtract.

Returns​

DateTime

A new DateTime instance with the minutes subtracted.

Example​

const newDateTime = dateTime.minusMinutes(30); // Half an hour

minusMonths()​

minusMonths(months): DateTime

Returns a new DateTime with the specified number of months subtracted.

Parameters​

months​

number

The number of months to subtract.

Returns​

DateTime

A new DateTime instance with the months subtracted.

Example​

const newDateTime = dateTime.minusMonths(3); // Three months

minusNanos()​

minusNanos(nanos): DateTime

Returns a new DateTime with the specified number of nanoseconds subtracted.

Parameters​

nanos​

number

The number of nanoseconds to subtract.

Returns​

DateTime

A new DateTime instance with the nanoseconds subtracted.

Example​

const newDateTime = dateTime.minusNanos(1000000); // One millisecond

minusSeconds()​

minusSeconds(seconds): DateTime

Returns a new DateTime with the specified number of seconds subtracted.

Parameters​

seconds​

number

The number of seconds to subtract.

Returns​

DateTime

A new DateTime instance with the seconds subtracted.

Example​

const newDateTime = dateTime.minusSeconds(45); // Three-quarters of a minute

minusYears()​

minusYears(years): DateTime

Returns a new DateTime with the specified number of years subtracted.

Parameters​

years​

number

The number of years to subtract.

Returns​

DateTime

A new DateTime instance with the years subtracted.

Example​

const newDateTime = dateTime.minusYears(5); // Five years

plusDays()​

plusDays(days): DateTime

Returns a new DateTime with the specified number of days added.

Parameters​

days​

number

The number of days to add.

Returns​

DateTime

A new DateTime instance with the days added.

Example​

const newDateTime = dateTime.plusDays(10); // Ten days

plusHours()​

plusHours(hours): DateTime

Returns a new DateTime with the specified number of hours added.

Parameters​

hours​

number

The number of hours to add.

Returns​

DateTime

A new DateTime instance with the hours added.

Example​

const newDateTime = dateTime.plusHours(2); // Two hours

plusMinutes()​

plusMinutes(minutes): DateTime

Returns a new DateTime with the specified number of minutes added.

Parameters​

minutes​

number

The number of minutes to add.

Returns​

DateTime

A new DateTime instance with the minutes added.

Example​

const newDateTime = dateTime.plusMinutes(30); // Half an hour

plusMonths()​

plusMonths(months): DateTime

Returns a new DateTime with the specified number of months added.

Parameters​

months​

number

The number of months to add.

Returns​

DateTime

A new DateTime instance with the months added.

Example​

const newDateTime = dateTime.plusMonths(3); // Three months

plusNanos()​

plusNanos(nanos): DateTime

Returns a new DateTime with the specified number of nanoseconds added.

Parameters​

nanos​

number

The number of nanoseconds to add.

Returns​

DateTime

A new DateTime instance with the nanoseconds added.

Example​

const newDateTime = dateTime.plusNanos(1000000); // One millisecond

plusSeconds()​

plusSeconds(seconds): DateTime

Returns a new DateTime with the specified number of seconds added.

Parameters​

seconds​

number

The number of seconds to add.

Returns​

DateTime

A new DateTime instance with the seconds added.

Example​

const newDateTime = dateTime.plusSeconds(45); // Three-quarters of a minute

plusYears()​

plusYears(years): DateTime

Returns a new DateTime with the specified number of years added.

Parameters​

years​

number

The number of years to add.

Returns​

DateTime

A new DateTime instance with the years added.

Example​

const newDateTime = dateTime.plusYears(5); // Five years

toEpochMilli()​

toEpochMilli(): number

Converts this DateTime to the number of milliseconds since the epoch (1970-01-01T00:00:00Z).

Returns​

number

The number of milliseconds since the epoch.

Example​

const epochMilli = dateTime.toEpochMilli(); // Number of milliseconds since the epoch

toEpochSecond()​

toEpochSecond(): number

Converts this DateTime to the number of seconds since the epoch (1970-01-01T00:00:00Z).

Returns​

number

The number of seconds since the epoch.

Example​

const epochSecond = dateTime.toEpochSecond(); // Number of seconds since the epoch

toString()​

toString(format?): string

Converts this DateTime to a string representation based on the specified format.

Parameters​

format?​

string

The format string. If not provided, a default format will be used. See Java Documentation for more information.

Returns​

string

The string representation of this DateTime.

Example​

const dateTimeString = dateTime.toString('uuuu-MM-dd HH:mm:ss'); // Custom format

withDayOfMonth()​

withDayOfMonth(day): DateTime

Returns a new DateTime with the specified day of the month.

Parameters​

day​

number

The day of the month to set.

Returns​

DateTime

A new DateTime instance with the specified day.

Example​

const newDateTime = dateTime.withDayOfMonth(25);

withHour()​

withHour(hour): DateTime

Returns a new DateTime with the specified hour of the day.

Parameters​

hour​

number

The hour of the day to set (0-23).

Returns​

DateTime

A new DateTime instance with the specified hour.

Example​

const newDateTime = dateTime.withHour(14); // 14:00

withMinute()​

withMinute(minute): DateTime

Returns a new DateTime with the specified minute of the hour.

Parameters​

minute​

number

The minute of the hour to set (0-59).

Returns​

DateTime

A new DateTime instance with the specified minute.

Example​

const newDateTime = dateTime.withMinute(45); // Three-quarters of an hour

withMonth()​

withMonth(month): DateTime

Returns a new DateTime with the specified month.

Parameters​

month​

number

The month to set (1 = January, 12 = December).

Returns​

DateTime

A new DateTime instance with the specified month.

Example​

const newDateTime = dateTime.withMonth(12);

withNano()​

withNano(nano): DateTime

Returns a new DateTime with the specified nanosecond of the second.

Parameters​

nano​

number

The nanosecond of the second to set (0-999999999).

Returns​

DateTime

A new DateTime instance with the specified nanosecond.

Example​

const newDateTime = dateTime.withNano(500000000); // Half a second

withSecond()​

withSecond(second): DateTime

Returns a new DateTime with the specified second of the minute.

Parameters​

second​

number

The second of the minute to set (0-59).

Returns​

DateTime

A new DateTime instance with the specified second.

Example​

const newDateTime = dateTime.withSecond(30); // Half a minute

withYear()​

withYear(year): DateTime

Returns a new DateTime with the specified year.

Parameters​

year​

number

The year to set.

Returns​

DateTime

A new DateTime instance with the specified year.

Example​

const newDateTime = dateTime.withYear(2025);

now()​

static now(zone?): DateTime

Returns the current DateTime in the specified time zone.

Parameters​

zone?​

TimeZone

The time zone to use. If not provided, the system default time zone is used.

Returns​

DateTime

The current DateTime in the specified time zone.

Example​

const now = DateTime.now(TimeZone.of('America/New_York')); // Current date and time in New York

of()​

static of(year, month?, day?, hour?, minute?, second?, nano?, zone?): DateTime

Creates a DateTime instance with the specified date and time components.

Parameters​

year​

number

The year to set.

month?​

number

The month to set (1 = January, 12 = December).

day?​

number

The day of the month to set.

hour?​

number

The hour of the day to set (0-23).

minute?​

number

The minute of the hour to set (0-59).

second?​

number

The second of the minute to set (0-59).

nano?​

number

The nanosecond of the second to set (0-999999999).

zone?​

ZoneOffset

The time zone to associate with. If not provided, the system default time zone is used.

Returns​

DateTime

A new DateTime instance with the specified components.

Example​

const dateTime = DateTime.of(2024, 12, 25, 14, 30, 0, 0); // Christmas Day 2024 at 2:30 PM
const dateTime = DateTime.of(2024, 12, 25, 14, 30, 0, 0, ZoneOffset(5, 30)); // Christmas Day 2024 at 2:30 PM +05:30

parse()​

static parse(value, format?): DateTime

Parses a string to create a DateTime instance based on the specified format.

Parameters​

value​

string

The string representation of the date-time.

format?​

string

The format to use for parsing. If not provided, a default format is used. See Java Documentation for more information.

Returns​

DateTime

A new DateTime instance parsed from the string.

Example​

const dateTime = DateTime.parse('2024-12-25 14:30:00', 'uuuu-MM-dd HH:mm:ss'); // Christmas Day 2024 at 2:30 PM