Instant

the instant, not null

Throw:

*	DateTimeException if unable to convert to an {@code Instant}

public static now(clock: Clock): Instant source

Obtains the current instant from the system clock, or if specified the current instant from the specified clock.

This will query the specified clock to obtain the current time.

Params:

Name	Type	Attribute	Description
clock	Clock	optional default: Clock.systemUTC()	the clock to use, defaults to the system clock

Return:

the current instant, not null

public static ofEpochMilli(epochMilli: number): Instant source

Obtains an instance of {@code Instant} using milliseconds from the epoch of 1970-01-01T00:00:00Z.

The seconds and nanoseconds are extracted from the specified milliseconds.

Params:

Name	Type	Attribute	Description
epochMilli	number		the number of milliseconds from 1970-01-01T00:00:00Z

Return:

an instant, not null

Throw:

*	DateTimeException if the instant exceeds the maximum or minimum instant

public static ofEpochSecond(epochSecond: number, nanoAdjustment: number): Instant source

Obtains an instance of {@code Instant} using seconds from the epoch of 1970-01-01T00:00:00Z.

Params:

Name	Type	Attribute	Description
epochSecond	number		the number of seconds from 1970-01-01T00:00:00Z
nanoAdjustment	number		nanoseconds start from the start of epochSecond, if null the nanosecond field is set to zero.

Return:

an instant, not null

Throw:

*	DateTimeException if the instant exceeds the maximum or minimum instant

public static parse(text: string): Instant source

Obtains an instance of {@code Instant} from a text string such as {@code 2007-12-03T10:15:30.000Z}.

The string must represent a valid instant in UTC and is parsed using DateTimeFormatter#ISO_INSTANT.

Params:

Name	Type	Attribute	Description
text	string		the text to parse, not null

Return:

the parsed instant, not null

Throw:

*	DateTimeParseException if the text cannot be parsed

Public Methods

public adjustInto(temporal: Temporal): Temporal source

Adjusts the specified temporal object to have this instant.

This returns a temporal object of the same observable type as the input with the instant changed to be the same as this.

The adjustment is equivalent to using {@link Temporal#with(TemporalField, long)} twice, passing ChronoField#INSTANT_SECONDS and ChronoField#NANO_OF_SECOND as the fields.

In most cases, it is clearer to reverse the calling pattern by using {@link Temporal#with(TemporalAdjuster)}:

  // these two lines are equivalent, but the second approach is recommended
  temporal = thisInstant.adjustInto(temporal);
  temporal = temporal.with(thisInstant);

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
temporal	Temporal	nullable: false	the target object to be adjusted, not null

Return:

Temporal

the adjusted object, not null

Throw:

*	DateTimeException if unable to make the adjustment
*	ArithmeticException if numeric overflow occurs

public compareTo(otherInstant: Instant): number source

Compares this instant to the specified instant.

The comparison is based on the time-line position of the instants. It is "consistent with equals", as defined by Comparable.

Params:

Name	Type	Attribute	Description
otherInstant	Instant		the other instant to compare to, not null

Return:

the comparator value, negative if less, positive if greater

Throw:

*	NullPointerException if otherInstant is null

public epochSecond(): number source

Gets the number of seconds from the Java epoch of 1970-01-01T00:00:00Z.

The epoch second count is a simple incrementing count of seconds where second 0 is 1970-01-01T00:00:00Z. The nanosecond part of the day is returned by {@code getNanosOfSecond}.

Return:

the seconds from the epoch of 1970-01-01T00:00:00Z

public equals(otherInstant: *): boolean source

Checks if this instant is equal to the specified instant.

The comparison is based on the time-line position of the instants.

Params:

Name	Type	Attribute	Description
otherInstant	*		the other instant, null/ undefined returns false

Return:

true if the other instant is equal to this one

public get(field: TemporalField): number source

Gets the value of the specified field from this instant as an {@code int}.

This queries this instant for the value for the specified field. The returned value will always be within the valid range of values for the field. If it is not possible to return the value, because the field is not supported or for some other reason, an exception is thrown.

If the field is a ChronoField then the query is implemented here. The {@link #isSupported(TemporalField) supported fields} will return valid values based on this date-time, except {@code INSTANT_SECONDS} which is too large to fit in an {@code int} and throws a {@code DateTimeException}. All other {@code ChronoField} instances will throw a {@code DateTimeException}.

If the field is not a {@code ChronoField}, then the result of this method is obtained by invoking {@code TemporalField.getFrom(TemporalAccessor)} passing {@code this} as the argument. Whether the value can be obtained, and what the value represents, is determined by the field.

Override:

TemporalAccessor#get

Params:

Name	Type	Attribute	Description
field	TemporalField		the field to get, not null

Return:

the value for the field

Throw:

*	DateTimeException if a value for the field cannot be obtained
*	ArithmeticException if numeric overflow occurs

public getLong(field: TemporalField): number source

Gets the value of the specified field from this instant as a {@code long}.

This queries this instant for the value for the specified field. If it is not possible to return the value, because the field is not supported or for some other reason, an exception is thrown.

If the field is a ChronoField then the query is implemented here. The {@link #isSupported(TemporalField) supported fields} will return valid values based on this date-time. All other {@code ChronoField} instances will throw a {@code DateTimeException}.

Params:

Name	Type	Attribute	Description
field	TemporalField		the field to get, not null

Return:

the value for the field

Throw:

*	DateTimeException if a value for the field cannot be obtained
*	ArithmeticException if numeric overflow occurs

public hashCode(): number source

Returns a hash code for this instant.

Return:

a suitable hash code

public isAfter(otherInstant: Instant): boolean source

Checks if this instant is after the specified instant.

The comparison is based on the time-line position of the instants.

Params:

Name	Type	Attribute	Description
otherInstant	Instant		the other instant to compare to, not null

Return:

true if this instant is after the specified instant

Throw:

*	NullPointerException if otherInstant is null

public isBefore(otherInstant: Instant): boolean source

Checks if this instant is before the specified instant.

The comparison is based on the time-line position of the instants.

Params:

Name	Type	Attribute	Description
otherInstant	Instant		the other instant to compare to, not null

Return:

true if this instant is before the specified instant

Throw:

*	NullPointerException if otherInstant is null

public isSupported(fieldOrUnit: TemporalField | TemporalUnit): boolean source

Checks if the specified field is supported.

This checks if this instant can be queried for the specified field. If false, then calling the {@link #range(TemporalField) range} and {@link #get(TemporalField) get} methods will throw an exception.

If the field is a ChronoField then the query is implemented here. The supported fields are:

{@code NANO_OF_SECOND}
{@code MICRO_OF_SECOND}
{@code MILLI_OF_SECOND}
{@code INSTANT_SECONDS}

All other {@code ChronoField} instances will return false.

If the field is not a {@code ChronoField}, then the result of this method is obtained by invoking {@code TemporalField.isSupportedBy(TemporalAccessor)} passing {@code this} as the argument. Whether the field is supported is determined by the field.

Params:

Name	Type	Attribute	Description
fieldOrUnit	TemporalField \| TemporalUnit		the field to check, null returns false

Return:

true if the field is supported on this instant, false if not

public minus(amount: TemporalAmount | number, unit: TemporalUnit): Instant source

Params:

Name	Type	Attribute	Description
amount	TemporalAmount \| number
unit	TemporalUnit		only required if first param is a TemporalAmount

Return:

public minus1(amount: TemporalAmount): Instant source

Params:

Name	Type	Attribute	Description
amount	TemporalAmount	nullable: false

Return:

Throw:

*	DateTimeException
*	ArithmeticException

public minus2(amountToSubtract: number, unit: TemporalUnit): Instant source

Params:

Name	Type	Attribute	Description
amountToSubtract	number	nullable: false
unit	TemporalUnit	nullable: false

Return:

Throw:

*	DateTimeException
*	ArithmeticException

public minusMillis(millisToSubtract: number): Instant source

Returns a copy of this instant with the specified duration in milliseconds subtracted.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
millisToSubtract	number		the milliseconds to subtract, positive or negative

Return:

an {@code Instant} based on this instant with the specified milliseconds subtracted, not null

Throw:

*	DateTimeException if the result exceeds the maximum or minimum instant
*	ArithmeticException if numeric overflow occurs

public minusNanos(nanosToSubtract: number): Instant source

Returns a copy of this instant with the specified duration in nanoseconds subtracted.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
nanosToSubtract	number		the nanoseconds to subtract, positive or negative

Return:

an {@code Instant} based on this instant with the specified nanoseconds subtracted, not null

Throw:

*	DateTimeException if the result exceeds the maximum or minimum instant
*	ArithmeticException if numeric overflow occurs

public minusSeconds(secondsToSubtract: number): Instant source

Returns a copy of this instant with the specified duration in seconds subtracted.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
secondsToSubtract	number		the seconds to subtract, positive or negative

Return:

an {@code Instant} based on this instant with the specified seconds subtracted, not null

Throw:

*	DateTimeException if the result exceeds the maximum or minimum instant

public nano(): number source

Gets the number of nanoseconds, later along the time-line, from the start of the second.

The nanosecond-of-second value measures the total number of nanoseconds from the second returned by {@code getEpochSecond}.

Return:

the nanoseconds within the second, always positive, never exceeds 999,999,999

public plus(amount: TemporalAmount | number, unit: TemporalUnit): Instant source

Params:

Name	Type	Attribute	Description
amount	TemporalAmount \| number
unit	TemporalUnit		only required if first param is a TemporalAmount

Return:

public plus1(amount: TemporalAmount): Instant source

Params:

Name	Type	Attribute	Description
amount	TemporalAmount	nullable: false

Return:

Throw:

*	DateTimeException
*	ArithmeticException

public plus2(amountToAdd: number, unit: TemporalUnit): Instant source

Params:

Name	Type	Attribute	Description
amountToAdd	number	nullable: false
unit	TemporalUnit	nullable: false

Return:

Throw:

*	DateTimeException
*	ArithmeticException

public plusMillis(millisToAdd: number): Instant source

Returns a copy of this instant with the specified duration in milliseconds added.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
millisToAdd	number		the milliseconds to add, positive or negative

Return:

an {@code Instant} based on this instant with the specified milliseconds added, not null

Throw:

*	DateTimeException if the result exceeds the maximum or minimum instant
*	ArithmeticException if numeric overflow occurs

public plusNanos(nanosToAdd: number): Instant source

Returns a copy of this instant with the specified duration in nanoseconds added.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
nanosToAdd	number		the nanoseconds to add, positive or negative

Return:

an {@code Instant} based on this instant with the specified nanoseconds added, not null

Throw:

*	DateTimeException if the result exceeds the maximum or minimum instant

public plusSeconds(secondsToAdd: number): Instant source

Returns a copy of this instant with the specified duration in seconds added.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
secondsToAdd	number		the seconds to add, positive or negative

Return:

an {@code Instant} based on this instant with the specified seconds added, not null

Throw:

*	DateTimeException if the result exceeds the maximum or minimum instant

public query(query: TemporalQuery): * source

Queries this instant using the specified query.

This queries this instant using the specified query strategy object. The {@code TemporalQuery} object defines the logic to be used to obtain the result. Read the documentation of the query to understand what the result of this method will be.

The result of this method is obtained by invoking the {@link TemporalQuery#queryFrom(TemporalAccessor)} method on the specified query passing {@code this} as the argument.

Override:

TemporalAccessor#query

Params:

Name	Type	Attribute	Description
query	TemporalQuery	nullable: false	the query to invoke, not null

Return:

*	the query result, null may be returned (defined by the query)

Throw:

*	DateTimeException if unable to query (defined by the query)
*	ArithmeticException if numeric overflow occurs (defined by the query)

public range(field: TemporalField): ValueRange source

Gets the range of valid values for the specified field.

The range object expresses the minimum and maximum valid values for a field. This instant is used to enhance the accuracy of the returned range. If it is not possible to return the range, because the field is not supported or for some other reason, an exception is thrown.

If the field is a ChronoField then the query is implemented here. The {@link #isSupported(TemporalField) supported fields} will return appropriate range instances. All other {@code ChronoField} instances will throw a {@code DateTimeException}.

If the field is not a {@code ChronoField}, then the result of this method is obtained by invoking {@code TemporalField.rangeRefinedBy(TemporalAccessor)} passing {@code this} as the argument. Whether the range can be obtained is determined by the field.

Override:

TemporalAccessor#range

Params:

Name	Type	Attribute	Description
field	TemporalField		the field to query the range for, not null

Return:

ValueRange

the range of valid values for the field, not null

Throw:

*	DateTimeException if the range for the field cannot be obtained

public toEpochMilli(): number source

Converts this instant to the number of milliseconds from the epoch of 1970-01-01T00:00:00Z.

If this instant represents a point on the time-line too far in the future or past to fit in a {@code long} milliseconds, then an exception is thrown.

If this instant has greater than millisecond precision, then the conversion will drop any excess precision information as though the amount in nanoseconds was subject to integer division by one million.

Return:

the number of milliseconds since the epoch of 1970-01-01T00:00:00Z

Throw:

*	ArithmeticException if numeric overflow occurs

public toString(): string source

A string representation of this instant using ISO-8601 representation.

The format used is the same as DateTimeFormatter#ISO_INSTANT.

Return:

string

an ISO-8601 representation of this instant, not null

public truncatedTo(unit: TemporalUnit): Instant source

Returns a copy of this {@code Instant} truncated to the specified unit.

Truncating the instant returns a copy of the original with fields smaller than the specified unit set to zero. The fields are calculated on the basis of using a UTC offset as seen in {@code toString}. For example, truncating with the {@link ChronoUnit#MINUTES MINUTES} unit will round down to the nearest minute, setting the seconds and nanoseconds to zero.

The unit must have a {@linkplain TemporalUnit#getDuration() duration} that divides into the length of a standard day without remainder. This includes all supplied time units on ChronoUnit and {@link ChronoUnit#DAYS DAYS}. Other units throw an exception.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
unit	TemporalUnit	nullable: false	the unit to truncate to, not null

Return:

an {@code Instant} based on this instant with the time truncated, not null

Throw:

*	DateTimeException if the unit is invalid for truncation

public until(endExclusive: Temporal, unit: TemporalUnit): number source

Calculates the period between this instant and another instant in terms of the specified unit.

This calculates the period between two instants in terms of a single unit. The start and end points are {@code this} and the specified instant. The result will be negative if the end is before the start. The calculation returns a whole number, representing the number of complete units between the two instants. The {@code Temporal} passed to this method is converted to a {@code Instant} using {@link #from(TemporalAccessor)}. For example, the period in days between two dates can be calculated using {@code startInstant.until(endInstant, SECONDS)}.

This method operates in association with TemporalUnit#between. The result of this method is a {@code long} representing the amount of the specified unit. By contrast, the result of {@code between} is an object that can be used directly in addition/subtraction:

  long period = start.until(end, SECONDS);   // this method
  dateTime.plus(SECONDS.between(start, end));      // use in plus/minus

The calculation is implemented in this method for ChronoUnit. The units {@code NANOS}, {@code MICROS}, {@code MILLIS}, {@code SECONDS}, {@code MINUTES}, {@code HOURS}, {@code HALF_DAYS} and {@code DAYS} are supported. Other {@code ChronoUnit} values will throw an exception.

If the unit is not a {@code ChronoUnit}, then the result of this method is obtained by invoking {@code TemporalUnit.between(Temporal, Temporal)} passing {@code this} as the first argument and the input temporal as the second argument.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
endExclusive	Temporal		the end date, which is converted to an {@code Instant}, not null
unit	TemporalUnit		the unit to measure the period in, not null

Return:

the amount of the period between this date and the end date

Throw:

*	DateTimeException if the period cannot be calculated
*	ArithmeticException if numeric overflow occurs

public with(adjusterOrField: TemporalAdjuster | TemporalField, newValue: number): Instant source

function overloading for Instant.with

if called with 1 argument Instant.withTemporalAdjuster is called otherwise Instant.with2

Params:

Name	Type	Attribute	Description
adjusterOrField	TemporalAdjuster \| TemporalField	nullable: false
newValue	number

Return:

public with2(field: TemporalField, newValue: number): Instant source

Returns a copy of this instant with the specified field set to a new value.

This returns a new {@code Instant}, based on this one, with the value for the specified field changed. If it is not possible to set the value, because the field is not supported or for some other reason, an exception is thrown.

If the field is a ChronoField then the adjustment is implemented here. The supported fields behave as follows:

{@code NANO_OF_SECOND} - Returns an {@code Instant} with the specified nano-of-second. The epoch-second will be unchanged.
{@code MICRO_OF_SECOND} - Returns an {@code Instant} with the nano-of-second replaced by the specified micro-of-second multiplied by 1,000. The epoch-second will be unchanged.
{@code MILLI_OF_SECOND} - Returns an {@code Instant} with the nano-of-second replaced by the specified milli-of-second multiplied by 1,000,000. The epoch-second will be unchanged.
{@code INSTANT_SECONDS} - Returns an {@code Instant} with the specified epoch-second. The nano-of-second will be unchanged.

In all cases, if the new value is outside the valid range of values for the field then a {@code DateTimeException} will be thrown.

All other {@code ChronoField} instances will throw a {@code DateTimeException}.

If the field is not a {@code ChronoField}, then the result of this method is obtained by invoking {@code TemporalField.adjustInto(Temporal, long)} passing {@code this} as the argument. In this case, the field determines whether and how to adjust the instant.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
field	TemporalField		the field to set in the result, not null
newValue	number		the new value of the field in the result

Return:

an {@code Instant} based on {@code this} with the specified field set, not null

Throw:

*	DateTimeException if the field cannot be set
*	ArithmeticException if numeric overflow occurs

public withTemporalAdjuster(adjuster: TemporalAdjuster): Instant source

Returns an adjusted copy of this instant.

This returns a new {@code Instant}, based on this one, with the date adjusted. The adjustment takes place using the specified adjuster strategy object. Read the documentation of the adjuster to understand what adjustment will be made.

The result of this method is obtained by invoking the {@link TemporalAdjuster#adjustInto(Temporal)} method on the specified adjuster passing {@code this} as the argument.

This instance is immutable and unaffected by this method call.

Params:

Name	Type	Attribute	Description
adjuster	TemporalAdjuster	nullable: false	the adjuster to use, not null

Return: