Module org.threeten.extra

Package org.threeten.extra

Class Minutes

java.lang.Object

org.threeten.extra.Minutes

All Implemented Interfaces:

Serializable, Comparable<Minutes>, TemporalAmount

public final class Minutes
extends Object
implements TemporalAmount, Comparable<Minutes>, Serializable

A minute-based amount of time, such as '8 minutes'.

This class models a quantity or amount of time in terms of minutes. It is a type-safe way of representing a number of minutes 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

Field Summary

Fields

Modifier and Type	Field	Description
static Minutes	ZERO	A constant for zero minutes.

Method Summary

Modifier and Type	Method	Description
Minutes	abs()	Returns a copy of this duration with a positive length.
Temporal	addTo(Temporal temporal)	Adds this amount to the specified temporal object.
static Minutes	between(Temporal startInclusive, Temporal endExclusive)	Obtains a Minutes consisting of the number of minutes between two temporals.
int	compareTo(Minutes otherAmount)	Compares this amount to the specified Minutes.
Minutes	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 specified Minutes.
static Minutes	from(TemporalAmount amount)	Obtains an instance of Minutes from a temporal amount.
long	get(TemporalUnit unit)	Gets the value of the requested unit.
int	getAmount()	Gets the number of minutes 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.
Minutes	minus(int minutes)	Returns a copy of this amount with the specified number of minutes subtracted.
Minutes	minus(TemporalAmount amountToSubtract)	Returns a copy of this amount with the specified amount subtracted.
Minutes	multipliedBy(int scalar)	Returns an instance with the amount multiplied by the specified scalar.
Minutes	negated()	Returns an instance with the amount negated.
static Minutes	of(int minutes)	Obtains a Minutes representing a number of minutes.
static Minutes	ofHours(int hours)	Obtains a Minutes representing the number of minutes equivalent to a number of hours.
static Minutes	parse(CharSequence text)	Obtains a Minutes from a text string such as PTnM.
Minutes	plus(int minutes)	Returns a copy of this amount with the specified number of minutes added.
Minutes	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.
Duration	toDuration()	Gets the number of minutes as a Duration.
String	toString()	Returns a string representation of the number of minutes.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ZERO

public static final Minutes ZERO

A constant for zero minutes.

Method Detail

of

public static Minutes of(int minutes)

Obtains a Minutes representing a number of minutes.

The resulting amount will have the specified minutes.

Parameters:

minutes - the number of minutes, positive or negative

Returns:

the number of minutes, not null

ofHours

public static Minutes ofHours(int hours)

Obtains a Minutes representing the number of minutes equivalent to a number of hours.

The resulting amount will be minute-based, with the number of minutes equal to the number of hours multiplied by 60.

Parameters:

hours - the number of hours, positive or negative

Returns:

the amount with the input hours converted to minutes, not null

Throws:

ArithmeticException - if numeric overflow occurs

from

public static Minutes from(TemporalAmount amount)

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

The result is calculated by looping around each unit in the specified amount. Each amount is converted to minutes 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.

Parameters:

amount - the temporal amount to convert, not null

Returns:

the equivalent amount, not null

Throws:

DateTimeException - if unable to convert to a Minutes

ArithmeticException - if numeric overflow occurs

parse

public static Minutes parse(CharSequence text)

Obtains a Minutes from a text string such as PTnM.

This will parse the string produced by toString() and other related formats based on ISO-8601 PnDTnHnM.

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 three sections consisting of a number and a suffix. There is one section for days suffixed by "D", followed by one section for hours suffixed by "H", followed by one section for minutes suffixed by "M". At least one section must be present. If the hours or minutes section is present it must be prefixed by "T". If the hours or minutes section is omitted the "T" must be omitted. Letters must be in ASCII upper or lower case. 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 days, hours and minutes are not part of the ISO-8601 standard.

For example, the following are valid inputs:

   "PT2M"            -- Minutes.of(2)
   "PT-2M"           -- Minutes.of(-2)
   "-PT2M"           -- Minutes.of(-2)
   "-PT-2M"          -- Minutes.of(2)
   "PT3H"            -- Minutes.of(3 * 60)
   "PT3H-2M"         -- Minutes.of(3 * 60 - 2)
   "P3D"             -- Minutes.of(3 * 24 * 60)
   "P3DT2M"          -- Minutes.of(3 * 24 * 60 + 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 Minutes between(Temporal startInclusive,
                              Temporal endExclusive)

Obtains a Minutes consisting of the number of minutes between two temporals.

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

Parameters:

startInclusive - the start temporal, inclusive, not null

endExclusive - the end temporal, exclusive, not null

Returns:

the number of minutes between the start and end temporals, not null

get

public long get(TemporalUnit unit)

Gets the value of the requested unit.

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

Specified by:

get in interface TemporalAmount

Parameters:

unit - the TemporalUnit 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 MINUTES.

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

Specified by:

getUnits in interface TemporalAmount

Returns:

a list containing the minutes unit, not null

getAmount

public int getAmount()

Gets the number of minutes in this amount.

Returns:

the number of minutes

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 Minutes 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 Minutes based on this instance with the requested amount added, not null

Throws:

DateTimeException - if the specified amount contains an invalid unit

ArithmeticException - if numeric overflow occurs

plus

public Minutes plus(int minutes)

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

This instance is immutable and unaffected by this method call.

Parameters:

minutes - the amount of minutes to add, may be negative

Returns:

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

Throws:

ArithmeticException - if the result overflows an int

minus

public Minutes 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 Minutes based on this instance with the requested amount subtracted, not null

Throws:

DateTimeException - if the specified amount contains an invalid unit

ArithmeticException - if numeric overflow occurs

minus

public Minutes minus(int minutes)

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

This instance is immutable and unaffected by this method call.

Parameters:

minutes - the amount of minutes to add, may be negative

Returns:

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

Throws:

ArithmeticException - if the result overflows an int

multipliedBy

public Minutes 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 Minutes 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 Minutes 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 is Long.MIN_VALUE

abs

public Minutes 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 is Long.MIN_VALUE

toDuration

public Duration toDuration()

Gets the number of minutes as a Duration.

This returns a duration with the same number of minutes.

Returns:

the equivalent duration, 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 interface TemporalAmount

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 add

UnsupportedTemporalTypeException - if the MINUTES unit is not supported

ArithmeticException - 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 interface TemporalAmount

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 subtract

UnsupportedTemporalTypeException - if the MINUTES unit is not supported

ArithmeticException - if numeric overflow occurs

compareTo

public int compareTo(Minutes otherAmount)

Compares this amount to the specified Minutes.

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

Specified by:

compareTo in interface Comparable<Minutes>

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 specified Minutes.

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

Overrides:

equals in class Object

Parameters:

otherAmount - the other amount, null returns false

Returns:

true if the other amount is equal to this one

hashCode

public int hashCode()

A hash code for this amount.

Overrides:

hashCode in class Object

Returns:

a suitable hash code

toString

public String toString()

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

Overrides:

toString in class Object

Returns:

the number of minutes in ISO-8601 string format