ThreeTen-Extra 1.8.0 · org.threeten.extra.Years · APIdia, the JavaDoc alternative

Modifier and Type	Field and Description
public static final Years	ONE A constant for one year.
private static final Pattern	PATTERN The pattern for parsing.
private static final long	serialVersionUID A serialization identifier for this class.
private final int	years The number of years.
public static final Years	ZERO A constant for zero years.

Access	Constructor and Description
private	Years(int the years to use years) Constructs an instance using a specific number of years.

Method Summary

Modifier and Type	Method and Description
public Years	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 Years	Returns: the number of years 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 `Years` consisting of the number of years between two dates.
public int	Returns: the comparator value, negative if less, positive if greater compareTo(Years the other amount, not null otherAmount) Implements java.lang.Comparable.compareTo. Compares this amount to the specified `Years`.
public Years	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 `Years`.
public static Years	Returns: the equivalent amount, not null from(TemporalAmount the temporal amount to convert, not null amount) Obtains an instance of `Years` 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 years getAmount() Gets the number of years in this amount.
public List<TemporalUnit>	Returns: a list containing the years 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 Years	Returns: a `Years` 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 Years	Returns: a `Years` based on this instance with the requested amount subtracted, not null minus(int the amount of years to add, may be negative years) Returns a copy of this amount with the specified number of years subtracted.
public Years	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 Years	Returns: the negated amount, not null negated() Returns an instance with the amount negated.
public static Years	Returns: the number of years, not null of(int the number of years, positive or negative years) Obtains a `Years` representing a number of years.
public static Years	Returns: the parsed period, not null parse(CharSequence the text to parse, not null text) Obtains a `Years` from a text string such as `PnY`.
public Years	Returns: a `Years` 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 Years	Returns: a `Years` based on this instance with the requested amount added, not null plus(int the amount of years to add, may be negative years) Returns a copy of this amount with the specified number of years 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 years as a `Period`.
public String	Returns: the number of years in ISO-8601 string format toString() Overrides java.lang.Object.toString. Returns a string representation of the number of years.

Inherited from java.lang.Object:: clone finalize getClass notify notifyAll wait wait wait

ONE	back to summary
public static final Years ONE A constant for one year.

PATTERN	back to summary
private static final Pattern PATTERN The pattern for parsing.

serialVersionUID	back to summary
private static final long serialVersionUID A serialization identifier for this class.

years	back to summary
private final int years The number of years.

ZERO	back to summary
public static final Years ZERO A constant for zero years.

Years	back to summary
private Years(int years) Constructs an instance using a specific number of years. Parameters years:int the years to use

Method Detail

abs back to summary

abs	back to summary
public Years 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:Years the absolute amount, not null Exceptions ArithmeticException: if numeric overflow occurs, which only happens if the amount is `Long.MIN_VALUE`

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

the absolute amount, not null

Exceptions

ArithmeticException:: if numeric overflow occurs, which only happens if the amount is Long.MIN_VALUE

addTo back to summary

addTo	back 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 YEARS unit is not supported ArithmeticException: if numeric overflow occurs

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 YEARS unit is not supported
ArithmeticException:: if numeric overflow occurs

between back to summary

between	back to summary
public static Years between(Temporal startDateInclusive, Temporal endDateExclusive) Obtains a `Years` consisting of the number of years 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:Years the number of years between this date and the end date, not null

public static Years between(Temporal startDateInclusive, Temporal endDateExclusive)

Obtains a Years consisting of the number of years 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:Years

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

compareTo back to summary

compareTo	back to summary
public int compareTo(Years otherAmount) Implements java.lang.Comparable.compareTo. Compares this amount to the specified `Years`. The comparison is based on the total length of the amounts. It is "consistent with equals", as defined by `Comparable`. Parameters otherAmount:Years the other amount, not null Returns:int the comparator value, negative if less, positive if greater Annotations @Override

public int compareTo(Years otherAmount)

Implements java.lang.Comparable.compareTo.

Compares this amount to the specified Years.

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

Parameters

otherAmount:Years: the other amount, not null

Returns:int

the comparator value, negative if less, positive if greater

Annotations

@Override

dividedBy	back to summary
public Years 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:Years the amount divided by the specified divisor, not null Exceptions ArithmeticException: if the divisor is zero

dividedBy

back to summary

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

the amount divided by the specified divisor, not null

Exceptions

ArithmeticException:: if the divisor is zero

equals back to summary

equals	back to summary
public boolean equals(Object otherAmount) Overrides java.lang.Object.equals. Checks if this amount is equal to the specified `Years`. 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

public boolean equals(Object otherAmount)

Overrides java.lang.Object.equals.

Checks if this amount is equal to the specified Years.

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

from back to summary

from	back to summary
public static Years from(TemporalAmount amount) Obtains an instance of `Years` 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 `Years`. The result is calculated by looping around each unit in the specified amount. Each amount is converted to years using `Temporals#convertAmount`. If the conversion yields a remainder, an exception is thrown. If the amount is zero, the unit is ignored. For example, "12 months" can be converted to years but "11 months" cannot. Parameters amount:TemporalAmount the temporal amount to convert, not null Returns:Years the equivalent amount, not null Exceptions DateTimeException: if unable to convert to a `Years` ArithmeticException: if numeric overflow occurs

public static Years from(TemporalAmount amount)

Obtains an instance of Years 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 Years.

The result is calculated by looping around each unit in the specified amount. Each amount is converted to years using Temporals#convertAmount. If the conversion yields a remainder, an exception is thrown. If the amount is zero, the unit is ignored. For example, "12 months" can be converted to years but "11 months" cannot.

Parameters

amount:TemporalAmount: the temporal amount to convert, not null

Returns:Years

the equivalent amount, not null

Exceptions

DateTimeException:: if unable to convert to a Years
ArithmeticException:: if numeric overflow occurs

get back to summary

get	back 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 - `YEARS`. 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

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

getAmount	back to summary
public int getAmount() Gets the number of years in this amount. Returns:int the number of years

getAmount

back to summary

public int getAmount()

Gets the number of years in this amount.

Returns:int: the number of years

getUnits back to summary

getUnits	back 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 `YEARS`. 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 years unit, not null Annotations @Override

public List<TemporalUnit> getUnits()

Implements java.time.temporal.TemporalAmount.getUnits.

Gets the set of units supported by this amount.

The single supported unit is YEARS.

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 years unit, not null

Annotations

@Override

hashCode	back to summary
public int hashCode() Overrides java.lang.Object.hashCode. A hash code for this amount. Returns:int a suitable hash code Annotations @Override

hashCode

back to summary

public int hashCode()

Overrides java.lang.Object.hashCode.

A hash code for this amount.

Returns:int

a suitable hash code

Annotations

@Override

isNegative	back 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

isNegative

back 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

isPositive	back 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

isPositive

back 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

isZero	back to summary
public boolean isZero() Checks if the amount is zero. Returns:boolean true if the amount is zero, false if not

isZero

back to summary

public boolean isZero()

Checks if the amount is zero.

Returns:boolean: true if the amount is zero, false if not

minus back to summary

minus	back to summary
public Years minus(TemporalAmount amountToSubtract) Returns a copy of this amount with the specified amount subtracted. The parameter is converted using `Years#from(TemporalAmount)`. This instance is immutable and unaffected by this method call. Parameters amountToSubtract:TemporalAmount the amount to subtract, not null Returns:Years a `Years` 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

public Years minus(TemporalAmount amountToSubtract)

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

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

This instance is immutable and unaffected by this method call.

Parameters

amountToSubtract:TemporalAmount: the amount to subtract, not null

Returns:Years

a Years 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

minus back to summary

minus	back to summary
public Years minus(int years) Returns a copy of this amount with the specified number of years subtracted. This instance is immutable and unaffected by this method call. Parameters years:int the amount of years to add, may be negative Returns:Years a `Years` based on this instance with the requested amount subtracted, not null Exceptions ArithmeticException: if the result overflows an int

public Years minus(int years)

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

This instance is immutable and unaffected by this method call.

Parameters

years:int: the amount of years to add, may be negative

Returns:Years

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

Exceptions

ArithmeticException:: if the result overflows an int

multipliedBy	back to summary
public Years 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:Years the amount multiplied by the specified scalar, not null Exceptions ArithmeticException: if numeric overflow occurs

multipliedBy

back to summary

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

the amount multiplied by the specified scalar, not null

Exceptions

ArithmeticException:: if numeric overflow occurs

negated back to summary

negated	back to summary
public Years negated() Returns an instance with the amount negated. This instance is immutable and unaffected by this method call. Returns:Years the negated amount, not null Exceptions ArithmeticException: if numeric overflow occurs, which only happens if the amount is `Long.MIN_VALUE`

public Years negated()

Returns an instance with the amount negated.

This instance is immutable and unaffected by this method call.

Returns:Years

the negated amount, not null

Exceptions

ArithmeticException:: if numeric overflow occurs, which only happens if the amount is Long.MIN_VALUE

of back to summary

of	back to summary
public static Years of(int years) Obtains a `Years` representing a number of years. The resulting amount will have the specified years. Parameters years:int the number of years, positive or negative Returns:Years the number of years, not null

public static Years of(int years)

Obtains a Years representing a number of years.

The resulting amount will have the specified years.

Parameters

years:int: the number of years, positive or negative

Returns:Years

the number of years, not null

parse back to summary

parse	back to summary
public static Years parse(CharSequence text) Obtains a `Years` from a text string such as `PnY`. This will parse the string produced by `toString()` which is based on the ISO-8601 period formats `PnY`. 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. The ASCII integer amount is next, which may be negative. The ASCII letter "Y" is next in upper or lower case. The leading plus/minus sign, and negative values for years are not part of the ISO-8601 standard. For example, the following are valid inputs: "P2Y" -- Years.of(2) "P-2Y" -- Years.of(-2) "-P2Y" -- Years.of(-2) "-P-2Y" -- Years.of(2) Parameters text:CharSequence the text to parse, not null Returns:Years the parsed period, not null Annotations @FromString Exceptions DateTimeParseException: if the text cannot be parsed to a period

public static Years parse(CharSequence text)

Obtains a Years from a text string such as PnY.

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

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. The ASCII integer amount is next, which may be negative. The ASCII letter "Y" is next in upper or lower case.

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

For example, the following are valid inputs:

  "P2Y"             -- Years.of(2)
  "P-2Y"            -- Years.of(-2)
  "-P2Y"            -- Years.of(-2)
  "-P-2Y"           -- Years.of(2)

Parameters

text:CharSequence: the text to parse, not null

Returns:Years

the parsed period, not null

Annotations

@FromString

Exceptions

DateTimeParseException:: if the text cannot be parsed to a period

plus back to summary

plus	back to summary
public Years plus(TemporalAmount amountToAdd) Returns a copy of this amount with the specified amount added. The parameter is converted using `Years#from(TemporalAmount)`. This instance is immutable and unaffected by this method call. Parameters amountToAdd:TemporalAmount the amount to add, not null Returns:Years a `Years` 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

public Years plus(TemporalAmount amountToAdd)

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

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

This instance is immutable and unaffected by this method call.

Parameters

amountToAdd:TemporalAmount: the amount to add, not null

Returns:Years

a Years 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

plus back to summary

plus	back to summary
public Years plus(int years) Returns a copy of this amount with the specified number of years added. This instance is immutable and unaffected by this method call. Parameters years:int the amount of years to add, may be negative Returns:Years a `Years` based on this instance with the requested amount added, not null Exceptions ArithmeticException: if the result overflows an int

public Years plus(int years)

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

This instance is immutable and unaffected by this method call.

Parameters

years:int: the amount of years to add, may be negative

Returns:Years

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

Exceptions

ArithmeticException:: if the result overflows an int

readResolve	back to summary
private Object readResolve() Resolves singletons. Returns:Object the singleton instance

readResolve

back to summary

private Object readResolve()

Resolves singletons.

Returns:Object: the singleton instance

subtractFrom back to summary

subtractFrom	back 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 YEARS unit is not supported ArithmeticException: if numeric overflow occurs

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 YEARS unit is not supported
ArithmeticException:: if numeric overflow occurs

toPeriod back to summary

toPeriod	back to summary
public Period toPeriod() Gets the number of years as a `Period`. This returns a period with the same number of years. Returns:Period the equivalent period, not null

public Period toPeriod()

Gets the number of years as a Period.

This returns a period with the same number of years.

Returns:Period: the equivalent period, not null

toString	back to summary
public String toString() Overrides java.lang.Object.toString. Returns a string representation of the number of years. This will be in the format 'PnY' where n is the number of years. Returns:String the number of years in ISO-8601 string format Annotations @Override @ToString

toString

back to summary

public String toString()

Overrides java.lang.Object.toString.

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

Returns:String

the number of years in ISO-8601 string format

Annotations

@Override
@ToString

public final Class Years

Implementation Requirements:

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail