- java.lang.Object
-
- org.threeten.extra.Weeks
-
- All Implemented Interfaces:
Serializable
,Comparable<Weeks>
,TemporalAmount
public final class Weeks extends Object implements TemporalAmount, Comparable<Weeks>, Serializable
A week-based amount of time, such as '12 weeks'.This class models a quantity or amount of time in terms of weeks. It is a type-safe way of representing a number of weeks 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 ==.
- See Also:
- Serialized Form
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description Weeks
abs()
Returns a copy of this duration with a positive length.Temporal
addTo(Temporal temporal)
Adds this amount to the specified temporal object.static Weeks
between(Temporal startDateInclusive, Temporal endDateExclusive)
Obtains aWeeks
consisting of the number of weeks between two dates.int
compareTo(Weeks otherAmount)
Compares this amount to the specifiedWeeks
.Weeks
dividedBy(int divisor)
Returns an instance with the amount divided by the specified divisor.boolean
equals(Object otherAmount)
Checks if this amount is equal to the specifiedWeeks
.static Weeks
from(TemporalAmount amount)
Obtains an instance ofWeeks
from a temporal amount.long
get(TemporalUnit unit)
Gets the value of the requested unit.int
getAmount()
Gets the number of weeks in this amount.List<TemporalUnit>
getUnits()
Gets the set of units supported by this amount.int
hashCode()
A hash code for this amount.boolean
isNegative()
Checks if the amount is negative.boolean
isPositive()
Checks if the amount is positive.boolean
isZero()
Checks if the amount is zero.Weeks
minus(int weeks)
Returns a copy of this amount with the specified number of weeks subtracted.Weeks
minus(TemporalAmount amountToSubtract)
Returns a copy of this amount with the specified amount subtracted.Weeks
multipliedBy(int scalar)
Returns an instance with the amount multiplied by the specified scalar.Weeks
negated()
Returns an instance with the amount negated.static Weeks
of(int weeks)
Obtains aWeeks
representing a number of weeks.static Weeks
parse(CharSequence text)
Obtains aWeeks
from a text string such asPnW
.Weeks
plus(int weeks)
Returns a copy of this amount with the specified number of weeks added.Weeks
plus(TemporalAmount amountToAdd)
Returns a copy of this amount with the specified amount added.Temporal
subtractFrom(Temporal temporal)
Subtracts this amount from the specified temporal object.Period
toPeriod()
Gets the number of weeks as aPeriod
.String
toString()
Returns a string representation of the number of weeks.
-
-
-
Method Detail
-
of
public static Weeks of(int weeks)
Obtains aWeeks
representing a number of weeks.The resulting amount will have the specified weeks.
- Parameters:
weeks
- the number of weeks, positive or negative- Returns:
- the number of weeks, not null
-
from
public static Weeks from(TemporalAmount amount)
Obtains an instance ofWeeks
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 aWeeks
.The result is calculated by looping around each unit in the specified amount. Each amount is converted to weeks using
Temporals.convertAmount(long, java.time.temporal.TemporalUnit, java.time.temporal.TemporalUnit)
. If the conversion yields a remainder, an exception is thrown. If the amount is zero, the unit is ignored. For example, "7 days" can be converted to weeks but "6 days" cannot.- Parameters:
amount
- the temporal amount to convert, not null- Returns:
- the equivalent amount, not null
- Throws:
DateTimeException
- if unable to convert to aWeeks
ArithmeticException
- if numeric overflow occurs
-
parse
public static Weeks parse(CharSequence text)
Obtains aWeeks
from a text string such asPnW
.This will parse the string produced by
toString()
which is based on the ISO-8601 period formatsPnW
.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 "W" is next in upper or lower case.
The leading plus/minus sign, and negative values for weeks are not part of the ISO-8601 standard.
For example, the following are valid inputs:
"P2W" -- Weeks.of(2) "P-2W" -- Weeks.of(-2) "-P2W" -- Weeks.of(-2) "-P-2W" -- Weeks.of(2)
- Parameters:
text
- the text to parse, not null- Returns:
- the parsed period, not null
- Throws:
DateTimeParseException
- if the text cannot be parsed to a period
-
between
public static Weeks between(Temporal startDateInclusive, Temporal endDateExclusive)
Obtains aWeeks
consisting of the number of weeks 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
- the start date, inclusive, not nullendDateExclusive
- the end date, exclusive, not null- Returns:
- the number of weeks between this date and the end date, not null
-
get
public long get(TemporalUnit unit)
Gets the value of the requested unit.This returns a value for the supported unit -
WEEKS
. All other units throw an exception.- Specified by:
get
in interfaceTemporalAmount
- Parameters:
unit
- theTemporalUnit
for which to return the value- Returns:
- the long value of the unit
- Throws:
UnsupportedTemporalTypeException
- if the unit is not supported
-
getUnits
public List<TemporalUnit> getUnits()
Gets the set of units supported by this amount.The single supported unit is
WEEKS
.This set can be used in conjunction with
get(TemporalUnit)
to access the entire state of the amount.- Specified by:
getUnits
in interfaceTemporalAmount
- Returns:
- a list containing the weeks unit, not null
-
getAmount
public int getAmount()
Gets the number of weeks in this amount.- Returns:
- the number of weeks
-
isNegative
public boolean isNegative()
Checks if the amount is negative.- Returns:
- true if the amount is negative, false if the amount is zero or positive
-
isZero
public boolean isZero()
Checks if the amount is zero.- Returns:
- true if the amount is zero, false if not
-
isPositive
public boolean isPositive()
Checks if the amount is positive.- Returns:
- true if the amount is positive, false if the amount is zero or negative
-
plus
public Weeks plus(TemporalAmount amountToAdd)
Returns a copy of this amount with the specified amount added.The parameter is converted using
from(TemporalAmount)
.This instance is immutable and unaffected by this method call.
- Parameters:
amountToAdd
- the amount to add, not null- Returns:
- a
Weeks
based on this instance with the requested amount added, not null - Throws:
DateTimeException
- if the specified amount contains an invalid unitArithmeticException
- if numeric overflow occurs
-
plus
public Weeks plus(int weeks)
Returns a copy of this amount with the specified number of weeks added.This instance is immutable and unaffected by this method call.
- Parameters:
weeks
- the amount of weeks to add, may be negative- Returns:
- a
Weeks
based on this instance with the requested amount added, not null - Throws:
ArithmeticException
- if the result overflows an int
-
minus
public Weeks minus(TemporalAmount amountToSubtract)
Returns a copy of this amount with the specified amount subtracted.The parameter is converted using
from(TemporalAmount)
.This instance is immutable and unaffected by this method call.
- Parameters:
amountToSubtract
- the amount to subtract, not null- Returns:
- a
Weeks
based on this instance with the requested amount subtracted, not null - Throws:
DateTimeException
- if the specified amount contains an invalid unitArithmeticException
- if numeric overflow occurs
-
minus
public Weeks minus(int weeks)
Returns a copy of this amount with the specified number of weeks subtracted.This instance is immutable and unaffected by this method call.
- Parameters:
weeks
- the amount of weeks to add, may be negative- Returns:
- a
Weeks
based on this instance with the requested amount subtracted, not null - Throws:
ArithmeticException
- if the result overflows an int
-
multipliedBy
public Weeks 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
- the scalar to multiply by, not null- Returns:
- the amount multiplied by the specified scalar, not null
- Throws:
ArithmeticException
- if numeric overflow occurs
-
dividedBy
public Weeks 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
- the amount to divide by, may be negative- Returns:
- the amount divided by the specified divisor, not null
- Throws:
ArithmeticException
- if the divisor is zero
-
negated
public Weeks negated()
Returns an instance with the amount negated.This instance is immutable and unaffected by this method call.
- Returns:
- the negated amount, not null
- Throws:
ArithmeticException
- if numeric overflow occurs, which only happens if the amount isLong.MIN_VALUE
-
abs
public Weeks 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:
- the absolute amount, not null
- Throws:
ArithmeticException
- if numeric overflow occurs, which only happens if the amount isLong.MIN_VALUE
-
toPeriod
public Period toPeriod()
Gets the number of weeks as aPeriod
.This returns a period with the same number of weeks.
- Returns:
- the equivalent period, not null
-
addTo
public Temporal addTo(Temporal temporal)
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.
- Specified by:
addTo
in interfaceTemporalAmount
- Parameters:
temporal
- the temporal object to adjust, not null- Returns:
- an object of the same type with the adjustment made, not null
- Throws:
DateTimeException
- if unable to addUnsupportedTemporalTypeException
- if the WEEKS unit is not supportedArithmeticException
- if numeric overflow occurs
-
subtractFrom
public Temporal subtractFrom(Temporal temporal)
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.
- Specified by:
subtractFrom
in interfaceTemporalAmount
- Parameters:
temporal
- the temporal object to adjust, not null- Returns:
- an object of the same type with the adjustment made, not null
- Throws:
DateTimeException
- if unable to subtractUnsupportedTemporalTypeException
- if the WEEKS unit is not supportedArithmeticException
- if numeric overflow occurs
-
compareTo
public int compareTo(Weeks otherAmount)
Compares this amount to the specifiedWeeks
.The comparison is based on the total length of the amounts. It is "consistent with equals", as defined by
Comparable
.- Specified by:
compareTo
in interfaceComparable<Weeks>
- Parameters:
otherAmount
- the other amount, not null- Returns:
- the comparator value, negative if less, positive if greater
-
equals
public boolean equals(Object otherAmount)
Checks if this amount is equal to the specifiedWeeks
.The comparison is based on the total length of the durations.
-
hashCode
public int hashCode()
A hash code for this amount.
-
-