Package org.kiwiproject.time

Class KiwiInstants

java.lang.Object

org.kiwiproject.time.KiwiInstants

public 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):

• ChronoUnit.NANOS
• ChronoUnit.MICROS
• ChronoUnit.MILLIS
• ChronoUnit.SECONDS
• ChronoUnit.MINUTES
• ChronoUnit.HOURS
• ChronoUnit.HALF_DAYS
• ChronoUnit.DAYS

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).

Constructor Summary

Constructors

Constructor	Description
KiwiInstants()

Method Summary

Modifier and Type	Method	Description
static int	getDayOfMonth(Instant instant)	Return the value of the day of the month from instant.
static int	getHour(Instant instant)	Return the value of the hour from instant.
static int	getMinute(Instant instant)	Return the value of the minute from instant.
static Month	getMonth(Instant instant)	Return the Month from instant.
static int	getMonthValue(Instant instant)	Return the value of the month (1-12) from instant.
static int	getSecond(Instant instant)	Return the value of the second from instant.
static int	getYear(Instant instant)	Return the value of the year from instant.
static Instant	minusDays(Instant instant, long days)	Return an Instant that is the given number of days before instant.
static Instant	minusHours(Instant instant, long hours)	Return an Instant that is the given number of hours before instant.
static Instant	minusMinutes(Instant instant, long minutes)	Return an Instant that is the given number of minutes before instant.
static Instant	minusMonths(Instant instant, long months)	Return an Instant that is the given number of months before instant.
static Instant	minusUsingZDT(Instant instant, long amountToSubtract, TemporalUnit unit)	Subtract any given amountToSubtract of type TemporalUnit from the given instant.
static Instant	minusYears(Instant instant, long years)	Return an Instant that is the given number of years before instant.
static Instant	plusDays(Instant instant, long days)	Return an Instant that is the given number of days after instant.
static Instant	plusHours(Instant instant, long hours)	Return an Instant that is the given number of hours after instant.
static Instant	plusMinutes(Instant instant, long minutes)	Return an Instant that is the given number of minutes after instant.
static Instant	plusMonths(Instant instant, long months)	Return an Instant that is the given number of months after instant.
static Instant	plusUsingZDT(Instant instant, long amountToAdd, TemporalUnit unit)	Add any given amountToAdd of type TemporalUnit from the given instant.
static Instant	plusYears(Instant instant, long years)	Return an Instant that is the given number of years after instant.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KiwiInstants

public KiwiInstants()

Method Detail

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