Instant in Java With Examples

The java.time.Instant class is part of new date and time API added in Java 8 that represents a single instantaneous point on the time-line.

Instant is stored in two fields, it stores a long representing epoch-seconds and an int representing nanosecond-of-second, which will always be between 0 and 999,999,999. The epoch-seconds are measured from the standard Java epoch of 1970-01-01T00:00:00Z where instants after the epoch have positive values, and earlier instants have negative values. To initialize these two field there is a private constructor in the Java Instant class-

/**
 * @param epochSecond  the number of seconds from 1970-01-01T00:00:00Z
 * @param nanos  the nanoseconds within the second, must be positive
 */
private Instant(long epochSecond, int nanos) {
  super();
  this.seconds = epochSecond;
  this.nanos = nanos;
}

Instant class is immutable thus thread-safe. Since it is marked as final so can't be extended.

Table of contents

Creating instances of Instant
Getting epoch seconds and nano second values from Instant
Time calculations using Instant
Comparing two Instant Instances in Java

Creating instances of Instant

Instant class doesn't have any public constructors to obtain an instance, you will use a factory method to get an instance.

now()- Obtains the current instant from the system clock.

Instant instant = Instant.now();
System.out.println(instant); //2019-11-07T05:21:04.464715600Z

now(Clock clock)- Obtains the current instant from the specified clock.

Instant instant = Instant.now(Clock.systemDefaultZone());
System.out.println(instant); //2019-11-07T05:36:01.210573Z

ofEpochMilli(long epochMilli)- Obtains an instance of Instant using milliseconds from the epoch of 1970-01-01T00:00:00Z.

Instant instant = Instant.ofEpochMilli(System.currentTimeMillis());
System.out.println(instant); //2019-11-07T05:39:27.853Z

ofEpochSecond(long epochSecond)- Obtains an instance of Instant using seconds from the epoch of 1970-01-01T00:00:00Z.

Instant instant = Instant.ofEpochSecond(System.currentTimeMillis()/1000);
System.out.println(instant); //2019-11-07T05:39:27.853Z

ofEpochSecond(long epochSecond, long nanoAdjustment)- Obtains an instance of Instant using seconds from the epoch of 1970-01-01T00:00:00Z and nanosecond fraction of second.
```
Instant instant = Instant.ofEpochSecond(System.currentTimeMillis()/1000, 235);
System.out.println(instant); //2019-11-07T05:40:55.000000235Z
```
parse(CharSequence text)- Obtains an instance of Instant from a text string such as 2007-12-03T10:15:30.00Z. Using parse method you can convert String to an Instant.
```
Instant instant = Instant.parse("2019-10-28T11:35:15Z");
System.out.println(instant); //2019-10-28T11:35:15Z
```

Getting epoch seconds and nano second values from Instant

Since Instant instance is stored in two fields; epochSecond and nanos so there are methods to extract these two fields from a java.time.Instant instance.

public class InsantExample {
  public static void main(String[] args) {
    Instant instant = Instant.parse("2019-10-28T11:35:15.245Z");
    // epoch seconds
    System.out.println(instant.getEpochSecond());
    // Nanos
    System.out.println(instant.getNano());
  }
}

Output

1572262515
245000000

Time calculations using Instant

There are methods to add or subtract date and time values from an Instant.

Minus methods

minus(long amountToSubtract, TemporalUnit unit)- Returns a copy of this instant with the specified amount subtracted.
minus(TemporalAmount amountToSubtract)- Returns a copy of this instant with the specified amount subtracted.
minusMillis(long millisToSubtract)- Returns a copy of this instant with the specified duration in milliseconds subtracted.
minusNanos(long nanosToSubtract)- Returns a copy of this instant with the specified duration in nanoseconds subtracted.
minusSeconds(long secondsToSubtract)- Returns a copy of this instant with the specified duration in seconds subtracted.

public class InsantExample {
  public static void main(String[] args) {
    Instant instant = Instant.parse("2019-10-28T11:35:15.245Z");
    System.out.println("Instant- " + instant);
    
    System.out.println("Instant second subtraction- " + instant.minusSeconds(15));
    System.out.println("Instant millis subtraction- " + instant.minusMillis(2000));
    System.out.println("Instant nanos subtraction- " + instant.minusNanos(45));
    
    // Uses minus(long amountToSubtract, TemporalUnit unit)
    System.out.println("Instant days subtraction- " + instant.minus(10, ChronoUnit.DAYS));
    // Uses minus(TemporalAmount amountToSubtract)
    System.out.println("Instant days subtraction- " + instant.minus(Period.ofDays(10)));
    System.out.println("Instant Hours subtraction- " + instant.minus(Duration.ofHours(3)));
  }
}

Output

Instant- 2019-10-28T11:35:15.245Z
Instant second subtraction- 2019-10-28T11:35:00.245Z
Instant millis subtraction- 2019-10-28T11:35:13.245Z
Instant nanos subtraction- 2019-10-28T11:35:15.244999955Z
Instant days subtraction- 2019-10-18T11:35:15.245Z
Instant days subtraction- 2019-10-18T11:35:15.245Z
Instant days subtraction- 2019-10-28T08:35:15.245Z

Plus methods

plus(long amountToAdd, TemporalUnit unit)- Returns a copy of this instant with the specified amount added.
plus(TemporalAmount amountToAdd)- Returns a copy of this instant with the specified amount added.
plusMillis(long millisToAdd)- Returns a copy of this instant with the specified duration in milliseconds added.
plusNanos(long nanosToAdd)- Returns a copy of this instant with the specified duration in nanoseconds added.
plusSeconds(long secondsToAdd)- Returns a copy of this instant with the specified duration in seconds added.

public class InsantExample {
  public static void main(String[] args) {
    Instant instant = Instant.parse("2019-10-28T11:35:15.245Z");
    System.out.println("Instant- " + instant);
    
    System.out.println("Instant second addition- " + instant.plusSeconds(15));
    System.out.println("Instant millis addition- " + instant.plusMillis(2000));
    System.out.println("Instant nanos addition- " + instant.plusNanos(45));
    
    // Uses plus(long amountToAdd, TemporalUnit unit)
    System.out.println("Instant days addition- " + instant.plus(10, ChronoUnit.DAYS));
    // Uses plus(TemporalAmount amountToAdd)
    System.out.println("Instant days addition- " + instant.plus(Period.ofDays(10)));
    System.out.println("Instant Hours addition- " + instant.plus(Duration.ofHours(3)));
  }
}

Output

Instant- 2019-10-28T11:35:15.245Z
Instant second addition- 2019-10-28T11:35:30.245Z
Instant millis addition- 2019-10-28T11:35:17.245Z
Instant nanos addition- 2019-10-28T11:35:15.245000045Z
Instant days addition- 2019-11-07T11:35:15.245Z
Instant days addition- 2019-11-07T11:35:15.245Z
Instant Hours addition- 2019-10-28T14:35:15.245Z

Comparing two Instant Instances in Java

compareTo(Instant otherInstant)- Compares this instant to the specified instant. Returns negative if less than the passes Instant instance, positive otherwise.
equals(Object otherInstant)- Checks if this instant is equal to the specified instant. Returns true if the other instant is equal to this one.
isAfter(Instant otherInstant)- Checks if this instant is after the specified instant.
isBefore(Instant otherInstant)- Checks if this instant is before the specified instant.

public class InsantExample {
  public static void main(String[] args) {
    Instant instant1 = Instant.parse("2019-10-28T11:35:15.245Z");
    System.out.println("Instant1- " + instant1);
    
    Instant instant2 = Instant.parse("2019-09-22T16:25:10.245Z");
    System.out.println("Instant2- " + instant2);
    
    // Should return + value
    System.out.println("Instant comparison- " + instant1.compareTo(instant2));
    System.out.println("Instanct Instances equal- " + instant1.equals(instant2));
    System.out.println("Instant After- " + instant1.isAfter(instant2));
    System.out.println("Instant Before- " + instant1.isBefore(instant2));
  }
}

Output

Instant1- 2019-10-28T11:35:15.245Z
Instant2- 2019-09-22T16:25:10.245Z
Instant comparison- 1
Instanct Instances equal- false
Instant After- true
Instant Before- false

That's all for the topic Instant in Java With Examples. If something is missing or you have something to share about the topic please write a comment.

You may also like

KnpCode

December 30, 2022