Top Description Fields Constructors Methods
org.threeten.extra

public final Class Months

extends Object
implements TemporalAmount, Comparable<Months>, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, java.lang.Comparable, java.time.temporal.TemporalAmount
Static Imports
java.time.temporal.ChronoUnit.MONTHS

A month-based amount of time, such as '12 months'.

This class models a quantity or amount of time in terms of months. It is a type-safe way of representing a number of months in an application.

The model is of a directed amount, meaning that the amount may be negative.

Implementation Requirements:

This class is immutable and thread-safe.

This class must be treated as a value type. Do not synchronize, rely on the identity hash code or use the distinction between equals() and ==.

Field Summary

Modifier and TypeField and Description
private final int
months

The number of months.

private static final int
MONTHS_PER_YEAR

The number of months per year.

public static final Months
ONE

A constant for one month.

private static final Pattern
PATTERN

The pattern for parsing.

private static final long
serialVersionUID

A serialization identifier for this class.

public static final Months
ZERO

A constant for zero months.

Constructor Summary

AccessConstructor and Description
private
Months(int
the months to use
months
)

Constructs an instance using a specific number of months.

Method Summary

Modifier and TypeMethod and Description
public Months

Returns:

the absolute amount, not null
abs
()

Returns a copy of this duration with a positive length.

public Temporal

Returns:

an object of the same type with the adjustment made, not null
addTo
(Temporal
the temporal object to adjust, not null
temporal
)

Implements java.time.temporal.TemporalAmount.addTo.

Adds this amount to the specified temporal object.

public static Months

Returns:

the number of months between this date and the end date, not null
between
(Temporal
the start date, inclusive, not null
startDateInclusive
,
Temporal
the end date, exclusive, not null
endDateExclusive
)

Obtains a Months consisting of the number of months between two dates.

public int

Returns:

the comparator value, negative if less, positive if greater
compareTo
(Months
the other amount, not null
otherAmount
)

Implements java.lang.Comparable.compareTo.

Compares this amount to the specified Months.

public Months

Returns:

the amount divided by the specified divisor, not null
dividedBy
(int
the amount to divide by, may be negative
divisor
)

Returns an instance with the amount divided by the specified divisor.

public boolean

Returns:

true if the other amount is equal to this one
equals
(Object
the other amount, null returns false
otherAmount
)

Overrides java.lang.Object.equals.

Checks if this amount is equal to the specified Months.

public static Months

Returns:

the equivalent amount, not null
from
(TemporalAmount
the temporal amount to convert, not null
amount
)

Obtains an instance of Months from a temporal amount.

public long

Returns:

the long value of the unit
get
(TemporalUnit
the TemporalUnit for which to return the value
unit
)

Implements java.time.temporal.TemporalAmount.get.

Gets the value of the requested unit.

public int

Returns:

the number of months
getAmount
()

Gets the number of months in this amount.

public List<TemporalUnit>

Returns:

a list containing the months unit, not null
getUnits
()

Implements java.time.temporal.TemporalAmount.getUnits.

Gets the set of units supported by this amount.

public int

Returns:

a suitable hash code
hashCode
()

Overrides java.lang.Object.hashCode.

A hash code for this amount.

public boolean

Returns:

true if the amount is negative, false if the amount is zero or positive
isNegative
()

Checks if the amount is negative.

public boolean

Returns:

true if the amount is positive, false if the amount is zero or negative
isPositive
()

Checks if the amount is positive.

public boolean

Returns:

true if the amount is zero, false if not
isZero
()

Checks if the amount is zero.

public Months

Returns:

a Months based on this instance with the requested amount subtracted, not null
minus
(TemporalAmount
the amount to subtract, not null
amountToSubtract
)

Returns a copy of this amount with the specified amount subtracted.

public Months

Returns:

a Months based on this instance with the requested amount subtracted, not null
minus
(int
the amount of months to add, may be negative
months
)

Returns a copy of this amount with the specified number of months subtracted.

public Months

Returns:

the amount multiplied by the specified scalar, not null
multipliedBy
(int
the scalar to multiply by, not null
scalar
)

Returns an instance with the amount multiplied by the specified scalar.

public Months

Returns:

the negated amount, not null
negated
()

Returns an instance with the amount negated.

public static Months

Returns:

the number of months, not null
of
(int
the number of months, positive or negative
months
)

Obtains a Months representing a number of months.

public static Months

Returns:

the amount with the input years converted to months, not null
ofYears
(int
the number of years, positive or negative
years
)

Obtains a Months representing the number of months equivalent to a number of years.

public static Months

Returns:

the parsed period, not null
parse
(CharSequence
the text to parse, not null
text
)

Obtains a Months from a text string such as PnM.

public Months

Returns:

a Months based on this instance with the requested amount added, not null
plus
(TemporalAmount
the amount to add, not null
amountToAdd
)

Returns a copy of this amount with the specified amount added.

public Months

Returns:

a Months based on this instance with the requested amount added, not null
plus
(int
the amount of months to add, may be negative
months
)

Returns a copy of this amount with the specified number of months added.

private Object

Returns:

the singleton instance
readResolve
()

Resolves singletons.

public Temporal

Returns:

an object of the same type with the adjustment made, not null
subtractFrom
(Temporal
the temporal object to adjust, not null
temporal
)

Implements java.time.temporal.TemporalAmount.subtractFrom.

Subtracts this amount from the specified temporal object.

public Period

Returns:

the equivalent period, not null
toPeriod
()

Gets the number of months as a Period.

public String

Returns:

the number of months in ISO-8601 string format
toString
()

Overrides java.lang.Object.toString.

Returns a string representation of the number of months.

Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAllwaitwaitwait

Field Detail

monthsback to summary
private final int months

The number of months.

MONTHS_PER_YEARback to summary
private static final int MONTHS_PER_YEAR

The number of months per year.

ONEback to summary
public static final Months ONE

A constant for one month.

PATTERNback to summary
private static final Pattern PATTERN

The pattern for parsing.

serialVersionUIDback to summary
private static final long serialVersionUID

A serialization identifier for this class.

ZEROback to summary
public static final Months ZERO

A constant for zero months.

Constructor Detail

Monthsback to summary
private Months(int months)

Constructs an instance using a specific number of months.

Parameters
months:int

the months to use

Method Detail

absback to summary
public Months abs()

Returns a copy of this duration with a positive length.

This method returns a positive duration by effectively removing the sign from any negative total length.

This instance is immutable and unaffected by this method call.

Returns:Months

the absolute amount, not null

Exceptions
ArithmeticException:
if numeric overflow occurs, which only happens if the amount is Long.MIN_VALUE
addToback to summary
public Temporal addTo(Temporal temporal)

Implements java.time.temporal.TemporalAmount.addTo.

Adds this amount to the specified temporal object.

This returns a temporal object of the same observable type as the input with this amount added.

In most cases, it is clearer to reverse the calling pattern by using Temporal#plus(TemporalAmount).

  // these two lines are equivalent, but the second approach is recommended
  dateTime = thisAmount.addTo(dateTime);
  dateTime = dateTime.plus(thisAmount);

Only non-zero amounts will be added.

This instance is immutable and unaffected by this method call.

Parameters
temporal:Temporal

the temporal object to adjust, not null

Returns:Temporal

an object of the same type with the adjustment made, not null

Annotations
@Override
Exceptions
DateTimeException:
if unable to add
UnsupportedTemporalTypeException:
if the MONTHS unit is not supported
ArithmeticException:
if numeric overflow occurs
betweenback to summary
public static Months between(Temporal startDateInclusive, Temporal endDateExclusive)

Obtains a Months consisting of the number of months between two dates.

The start date is included, but the end date is not. The result of this method can be negative if the end is before the start.

Parameters
startDateInclusive:Temporal

the start date, inclusive, not null

endDateExclusive:Temporal

the end date, exclusive, not null

Returns:Months

the number of months between this date and the end date, not null

compareToback to summary
public int compareTo(Months otherAmount)

Implements java.lang.Comparable.compareTo.

Compares this amount to the specified Months.

The comparison is based on the total length of the amounts. It is "consistent with equals", as defined by Comparable.

Parameters
otherAmount:Months

the other amount, not null

Returns:int

the comparator value, negative if less, positive if greater

Annotations
@Override
dividedByback to summary
public Months dividedBy(int divisor)

Returns an instance with the amount divided by the specified divisor.

The calculation uses integer division, thus 3 divided by 2 is 1.

This instance is immutable and unaffected by this method call.

Parameters
divisor:int

the amount to divide by, may be negative

Returns:Months

the amount divided by the specified divisor, not null

Exceptions
ArithmeticException:
if the divisor is zero
equalsback to summary
public boolean equals(Object otherAmount)

Overrides java.lang.Object.equals.

Checks if this amount is equal to the specified Months.

The comparison is based on the total length of the durations.

Parameters
otherAmount:Object

the other amount, null returns false

Returns:boolean

true if the other amount is equal to this one

Annotations
@Override
fromback to summary
public static Months from(TemporalAmount amount)

Obtains an instance of Months from a temporal amount.

This obtains an instance based on the specified amount. A TemporalAmount represents an amount of time, which may be date-based or time-based, which this factory extracts to a Months.

The result is calculated by looping around each unit in the specified amount. Each amount is converted to months using Temporals#convertAmount. If the conversion yields a remainder, an exception is thrown. If the amount is zero, the unit is ignored.

Parameters
amount:TemporalAmount

the temporal amount to convert, not null

Returns:Months

the equivalent amount, not null

Exceptions
DateTimeException:
if unable to convert to a Months
ArithmeticException:
if numeric overflow occurs
getback to summary
public long get(TemporalUnit unit)

Implements java.time.temporal.TemporalAmount.get.

Gets the value of the requested unit.

This returns a value for the supported unit - MONTHS. All other units throw an exception.

Parameters
unit:TemporalUnit

the TemporalUnit for which to return the value

Returns:long

the long value of the unit

Annotations
@Override
Exceptions
UnsupportedTemporalTypeException:
if the unit is not supported
getAmountback to summary
public int getAmount()

Gets the number of months in this amount.

Returns:int

the number of months

getUnitsback to summary
public List<TemporalUnit> getUnits()

Implements java.time.temporal.TemporalAmount.getUnits.

Gets the set of units supported by this amount.

The single supported unit is MONTHS.

This set can be used in conjunction with get(TemporalUnit) to access the entire state of the amount.

Returns:List<TemporalUnit>

a list containing the months unit, not null

Annotations
@Override
hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

A hash code for this amount.

Returns:int

a suitable hash code

Annotations
@Override
isNegativeback to summary
public boolean isNegative()

Checks if the amount is negative.

Returns:boolean

true if the amount is negative, false if the amount is zero or positive

isPositiveback to summary
public boolean isPositive()

Checks if the amount is positive.

Returns:boolean

true if the amount is positive, false if the amount is zero or negative

isZeroback to summary
public boolean isZero()

Checks if the amount is zero.

Returns:boolean

true if the amount is zero, false if not

minusback to summary
public Months minus(TemporalAmount amountToSubtract)

Returns a copy of this amount with the specified amount subtracted.

The parameter is converted using Months#from(TemporalAmount).

This instance is immutable and unaffected by this method call.

Parameters
amountToSubtract:TemporalAmount

the amount to subtract, not null

Returns:Months

a Months based on this instance with the requested amount subtracted, not null

Exceptions
DateTimeException:
if the specified amount contains an invalid unit
ArithmeticException:
if numeric overflow occurs
minusback to summary
public Months minus(int months)

Returns a copy of this amount with the specified number of months subtracted.

This instance is immutable and unaffected by this method call.

Parameters
months:int

the amount of months to add, may be negative

Returns:Months

a Months based on this instance with the requested amount subtracted, not null

Exceptions
ArithmeticException:
if the result overflows an int
multipliedByback to summary
public Months multipliedBy(int scalar)

Returns an instance with the amount multiplied by the specified scalar.

This instance is immutable and unaffected by this method call.

Parameters
scalar:int

the scalar to multiply by, not null

Returns:Months

the amount multiplied by the specified scalar, not null

Exceptions
ArithmeticException:
if numeric overflow occurs
negatedback to summary
public Months negated()

Returns an instance with the amount negated.

This instance is immutable and unaffected by this method call.

Returns:Months

the negated amount, not null

Exceptions
ArithmeticException:
if numeric overflow occurs, which only happens if the amount is Long.MIN_VALUE
ofback to summary
public static Months of(int months)

Obtains a Months representing a number of months.

The resulting amount will have the specified months.

Parameters
months:int

the number of months, positive or negative

Returns:Months

the number of months, not null

ofYearsback to summary
public static Months ofYears(int years)

Obtains a Months representing the number of months equivalent to a number of years.

The resulting amount will be month-based, with the number of months equal to the number of years multiplied by 12.

Parameters
years:int

the number of years, positive or negative

Returns:Months

the amount with the input years converted to months, not null

Exceptions
ArithmeticException:
if numeric overflow occurs
parseback to summary
public static Months parse(CharSequence text)

Obtains a Months from a text string such as PnM.

This will parse the string produced by toString() which is based on the ISO-8601 period format PnYnM.

The string starts with an optional sign, denoted by the ASCII negative or positive symbol. If negative, the whole amount is negated. The ASCII letter "P" is next in upper or lower case. There are then two sections, each consisting of a number and a suffix. At least one of the two sections must be present. The sections have suffixes in ASCII of "Y" and "M" for years and months, accepted in upper or lower case. The suffixes must occur in order. The number part of each section must consist of ASCII digits. The number may be prefixed by the ASCII negative or positive symbol. The number must parse to an int.

The leading plus/minus sign, and negative values for years and months are not part of the ISO-8601 standard.

For example, the following are valid inputs:

  "P2M"             -- Months.of(2)
  "P-2M"            -- Months.of(-2)
  "-P2M"            -- Months.of(-2)
  "-P-2M"           -- Months.of(2)
  "P3Y"             -- Months.of(3 * 12)
  "P3Y-2M"          -- Months.of(3 * 12 - 2)
Parameters
text:CharSequence

the text to parse, not null

Returns:Months

the parsed period, not null

Annotations
@FromString
Exceptions
DateTimeParseException:
if the text cannot be parsed to a period
plusback to summary
public Months plus(TemporalAmount amountToAdd)

Returns a copy of this amount with the specified amount added.

The parameter is converted using Months#from(TemporalAmount).

This instance is immutable and unaffected by this method call.

Parameters
amountToAdd:TemporalAmount

the amount to add, not null

Returns:Months

a Months based on this instance with the requested amount added, not null

Exceptions
DateTimeException:
if the specified amount contains an invalid unit
ArithmeticException:
if numeric overflow occurs
plusback to summary
public Months plus(int months)

Returns a copy of this amount with the specified number of months added.

This instance is immutable and unaffected by this method call.

Parameters
months:int

the amount of months to add, may be negative

Returns:Months

a Months based on this instance with the requested amount added, not null

Exceptions
ArithmeticException:
if the result overflows an int
readResolveback to summary
private Object readResolve()

Resolves singletons.

Returns:Object

the singleton instance

subtractFromback to summary
public Temporal subtractFrom(Temporal temporal)

Implements java.time.temporal.TemporalAmount.subtractFrom.

Subtracts this amount from the specified temporal object.

This returns a temporal object of the same observable type as the input with this amount subtracted.

In most cases, it is clearer to reverse the calling pattern by using Temporal#minus(TemporalAmount).

  // these two lines are equivalent, but the second approach is recommended
  dateTime = thisAmount.subtractFrom(dateTime);
  dateTime = dateTime.minus(thisAmount);

Only non-zero amounts will be subtracted.

This instance is immutable and unaffected by this method call.

Parameters
temporal:Temporal

the temporal object to adjust, not null

Returns:Temporal

an object of the same type with the adjustment made, not null

Annotations
@Override
Exceptions
DateTimeException:
if unable to subtract
UnsupportedTemporalTypeException:
if the MONTHS unit is not supported
ArithmeticException:
if numeric overflow occurs
toPeriodback to summary
public Period toPeriod()

Gets the number of months as a Period.

This returns a period with the same number of months.

Returns:Period

the equivalent period, not null

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns a string representation of the number of months. This will be in the format 'PnM' where n is the number of months.

Returns:String

the number of months in ISO-8601 string format

Annotations
@Override
@ToString