Package org.kiwiproject.time

Class KiwiInstants

java.lang.Object
org.kiwiproject.time.KiwiInstants
public final class KiwiInstants extends Object
Provides utilities related to Instant.

First, KiwiInstants adds convenience methods for adding and subtracting common time increments to Instant objects in the form of plus<TemporalField> and minus<TemporalField> methods such as plusMinutes(Instant, long) and minusDays(Instant, long).

The Instant class does not support all of the ChronoUnit values via the generic Instant.plus(long, TemporalUnit) and Instant.minus(long, TemporalUnit) methods. Specifically it only supports (as of this writing):

This means Instant does not support any of the other units larger than ChronoUnit.DAYS such as weeks, months, years, etc. This class supports adding and subtracting months and years directly, as well as other units via the plusUsingZDT(Instant, long, TemporalUnit) and minusUsingZDT(Instant, long, TemporalUnit) methods.

Second, KiwiInstants supports adding and subtracting months and years by first converting the Instant to a ZonedDateTime at ZoneOffset.UTC. For example plusMonths(Instant, long). For other TemporalUnit values you can use the plusUsingZDT(Instant, long, TemporalUnit) and minusUsingZDT(Instant, long, TemporalUnit) methods, which will work as long as ZonedDateTime supports the provided TemporalUnit.

Third, KiwiInstants provides utilities to retrieve individual standard parts of an Instant (second, minute, hour, day, month, year) using the various get<TemporalField> methods, for example getHour(Instant).

  • Method Details

    • getSecond

      public static int getSecond(Instant instant)
      Return the value of the second from instant.
      Parameters:
      instant - the Instant
      Returns:
      the value of the second

    • getMinute

      public static int getMinute(Instant instant)
      Return the value of the minute from instant.
      Parameters:
      instant - the Instant
      Returns:
      the value of the minute

    • getHour

      public static int getHour(Instant instant)
      Return the value of the hour from instant.
      Parameters:
      instant - the Instant
      Returns:
      the value of the hour

    • getDayOfMonth

      public static int getDayOfMonth(Instant instant)
      Return the value of the day of the month from instant.
      Parameters:
      instant - the Instant
      Returns:
      the value of the day of the month

    • getMonth

      public static Month getMonth(Instant instant)
      Return the Month from instant.
      Parameters:
      instant - the Instant
      Returns:
      the Month

    • getMonthValue

      public static int getMonthValue(Instant instant)
      Return the value of the month (1-12) from instant.
      Parameters:
      instant - the Instant
      Returns:
      the value the month, i.e. 1-12

    • getYear

      public static int getYear(Instant instant)
      Return the value of the year from instant.
      Parameters:
      instant - the Instant
      Returns:
      the value of the year

    • minusMinutes

      public static Instant minusMinutes(Instant instant, long minutes)
      Return an Instant that is the given number of minutes before instant.
      Parameters:
      instant - the Instant
      minutes - the amount of time to go backward in minutes
      Returns:
      a new Instant appropriately adjusted

    • minusHours

      public static Instant minusHours(Instant instant, long hours)
      Return an Instant that is the given number of hours before instant.
      Parameters:
      instant - the Instant
      hours - the amount of time to go backward in hours
      Returns:
      a new Instant appropriately adjusted

    • minusDays

      public static Instant minusDays(Instant instant, long days)
      Return an Instant that is the given number of days before instant.
      Parameters:
      instant - the Instant
      days - the amount of time to go backward in days
      Returns:
      a new Instant appropriately adjusted

    • minusMonths

      public static Instant minusMonths(Instant instant, long months)
      Return an Instant that is the given number of months before instant.
      Parameters:
      instant - the Instant
      months - the amount of time to go backward in months
      Returns:
      a new Instant appropriately adjusted
      Implementation Note:
      uses ZonedDateTime (at ZoneOffset.UTC) to traverse by month

    • minusYears

      public static Instant minusYears(Instant instant, long years)
      Return an Instant that is the given number of years before instant.
      Parameters:
      instant - the Instant
      years - the amount of time to go backward in years
      Returns:
      a new Instant appropriately adjusted
      Implementation Note:
      uses ZonedDateTime (at ZoneOffset.UTC) to traverse by month

    • minusUsingZDT

      public static Instant minusUsingZDT(Instant instant, long amountToSubtract, TemporalUnit unit)
      Subtract any given amountToSubtract of type TemporalUnit from the given instant. This first converts the Instant into a ZonedDateTime at ZoneOffset.UTC before applying the subtraction.
      Parameters:
      instant - the Instant
      amountToSubtract - the amount of time to go backwards
      unit - the unit for the amount of time to go backwards
      Returns:
      a new Instant appropriately adjusted

    • plusMinutes

      public static Instant plusMinutes(Instant instant, long minutes)
      Return an Instant that is the given number of minutes after instant.
      Parameters:
      instant - the Instant
      minutes - the amount of time to go forward in minutes
      Returns:
      a new Instant appropriately adjusted

    • plusHours

      public static Instant plusHours(Instant instant, long hours)
      Return an Instant that is the given number of hours after instant.
      Parameters:
      instant - the Instant
      hours - the amount of time to go forward in hours
      Returns:
      a new Instant appropriately adjusted

    • plusDays

      public static Instant plusDays(Instant instant, long days)
      Return an Instant that is the given number of days after instant.
      Parameters:
      instant - the Instant
      days - the amount of time to go forward in days
      Returns:
      a new Instant appropriately adjusted

    • plusMonths

      public static Instant plusMonths(Instant instant, long months)
      Return an Instant that is the given number of months after instant.
      Parameters:
      instant - the Instant
      months - the amount of time to go forward in months
      Returns:
      a new Instant appropriately adjusted
      Implementation Note:
      uses ZonedDateTime (at ZoneOffset.UTC) to traverse by month

    • plusYears

      public static Instant plusYears(Instant instant, long years)
      Return an Instant that is the given number of years after instant.
      Parameters:
      instant - the Instant
      years - the amount of time to go forward in years
      Returns:
      a new Instant appropriately adjusted
      Implementation Note:
      uses ZonedDateTime (at ZoneOffset.UTC) to traverse by month

    • plusUsingZDT

      public static Instant plusUsingZDT(Instant instant, long amountToAdd, TemporalUnit unit)
      Add any given amountToAdd of type TemporalUnit from the given instant. This first converts the Instant into a ZonedDateTime at ZoneOffset.UTC before applying the addition.
      Parameters:
      instant - the Instant
      amountToAdd - the amount of time to go forward
      unit - the unit for the amount of time to go forward
      Returns:
      a new Instant appropriately adjusted