Instant

the instant, not null

Throw:

*	DateTimeException if unable to convert to an 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 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 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 Instant from a text string such as 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 Temporal#with 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 Temporal#with:

  // 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 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 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 supported fields (see isSupported) will return valid values based on this date-time, except INSTANT_SECONDS which is too large to fit in an int and throws a DateTimeException. All other ChronoField instances will throw a DateTimeException.

If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.getFrom passing 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 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 supported fields (see isSupported) will return valid values based on this date-time. All other ChronoField instances will throw a 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 range and get will throw an exception.

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

NANO_OF_SECOND
MICRO_OF_SECOND
MILLI_OF_SECOND
INSTANT_SECONDS

All other ChronoField instances will return false.

If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.isSupportedBy passing 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 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 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 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 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 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 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 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 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 TemporalQuery#queryFrom method on the specified query passing 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 supported fields (see isSupported) will return appropriate range instances. All other ChronoField instances will throw a DateTimeException.

If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.rangeRefinedBy passing 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 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 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 toString. For example, truncating with ChronoUnit#MINUTES will round down to the nearest minute, setting the seconds and nanoseconds to zero.

The unit must have a duration (see TemporalUnit#getDuration) that divides into the length of a standard day without remainder. This includes all supplied time units on ChronoUnit and ChronoUnit#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 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 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 Temporal passed to this method is converted to a Instant using from. For example, the period in days between two dates can be calculated using startInstant.until(endInstant, SECONDS).

This method operates in association with TemporalUnit#between. The result of this method is a long representing the amount of the specified unit. By contrast, the result of 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 NANOS, MICROS, MILLIS, SECONDS, MINUTES, HOURS, HALF_DAYS and DAYS are supported. Other ChronoUnit values will throw an exception.

If the unit is not a ChronoUnit, then the result of this method is obtained by invoking TemporalUnit.between passing 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 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 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:

NANO_OF_SECOND - Returns an Instant with the specified nano-of-second. The epoch-second will be unchanged.
MICRO_OF_SECOND - Returns an Instant with the nano-of-second replaced by the specified micro-of-second multiplied by 1,000. The epoch-second will be unchanged.
MILLI_OF_SECOND - Returns an Instant with the nano-of-second replaced by the specified milli-of-second multiplied by 1,000,000. The epoch-second will be unchanged.
INSTANT_SECONDS - Returns an 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 DateTimeException will be thrown.

All other ChronoField instances will throw a DateTimeException.

If the field is not a ChronoField, then the result of this method is obtained by invoking TemporalField.adjustInto passing 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 Instant based on 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 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 TemporalAdjuster#adjustInto method on the specified adjuster passing 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: