java.io.Serializable
, java.lang.Comparable<Seconds>
, java.time.temporal.TemporalAmount
public final class Seconds extends java.lang.Object implements java.time.temporal.TemporalAmount, java.lang.Comparable<Seconds>, java.io.Serializable
This class models a quantity or amount of time in terms of seconds.
It is a type-safe way of representing a number of seconds in an application.
Note that Duration
also models time in terms of seconds, but that
class allows nanoseconds, which this class does not.
The model is of a directed amount, meaning that the amount may be negative.
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 ==.
Modifier and Type | Field | Description |
---|---|---|
static Seconds |
ZERO |
A constant for zero seconds.
|
Modifier and Type | Method | Description |
---|---|---|
Seconds |
abs() |
Returns a copy of this duration with a positive length.
|
java.time.temporal.Temporal |
addTo(java.time.temporal.Temporal temporal) |
Adds this amount to the specified temporal object.
|
static Seconds |
between(java.time.temporal.Temporal startInclusive,
java.time.temporal.Temporal endExclusive) |
Obtains a
Seconds consisting of the number of seconds between two temporals. |
int |
compareTo(Seconds otherAmount) |
Compares this amount to the specified
Seconds . |
Seconds |
dividedBy(int divisor) |
Returns an instance with the amount divided by the specified divisor.
|
boolean |
equals(java.lang.Object otherAmount) |
Checks if this amount is equal to the specified
Seconds . |
static Seconds |
from(java.time.temporal.TemporalAmount amount) |
Obtains an instance of
Seconds from a temporal amount. |
long |
get(java.time.temporal.TemporalUnit unit) |
Gets the value of the requested unit.
|
int |
getAmount() |
Gets the number of seconds in this amount.
|
java.util.List<java.time.temporal.TemporalUnit> |
getUnits() |
Gets the set of units supported by this amount.
|
int |
hashCode() |
A hash code for this amount.
|
Seconds |
minus(int seconds) |
Returns a copy of this amount with the specified number of seconds subtracted.
|
Seconds |
minus(java.time.temporal.TemporalAmount amountToAdd) |
Returns a copy of this amount with the specified amount subtracted.
|
Seconds |
multipliedBy(int scalar) |
Returns an instance with the amount multiplied by the specified scalar.
|
Seconds |
negated() |
Returns an instance with the amount negated.
|
static Seconds |
of(int seconds) |
Obtains a
Seconds representing a number of seconds. |
static Seconds |
ofHours(int hours) |
Obtains a
Seconds representing the number of seconds
equivalent to a number of hours. |
static Seconds |
ofMinutes(int minutes) |
Obtains a
Seconds representing the number of seconds
equivalent to a number of hours. |
static Seconds |
parse(java.lang.CharSequence text) |
Obtains a
Seconds from a text string such as PTnS . |
Seconds |
plus(int seconds) |
Returns a copy of this amount with the specified number of seconds added.
|
Seconds |
plus(java.time.temporal.TemporalAmount amountToAdd) |
Returns a copy of this amount with the specified amount added.
|
java.time.temporal.Temporal |
subtractFrom(java.time.temporal.Temporal temporal) |
Subtracts this amount from the specified temporal object.
|
java.time.Duration |
toDuration() |
Gets the number of seconds as a
Duration . |
java.lang.String |
toString() |
Returns a string representation of the number of seconds.
|
public static final Seconds ZERO
public static Seconds of(int seconds)
Seconds
representing a number of seconds.
The resulting amount will have the specified seconds.
seconds
- the number of seconds, positive or negativepublic static Seconds ofHours(int hours)
Seconds
representing the number of seconds
equivalent to a number of hours.
The resulting amount will be second-based, with the number of seconds equal to the number of hours multiplied by 3600.
hours
- the number of hours, positive or negativejava.lang.ArithmeticException
- if numeric overflow occurspublic static Seconds ofMinutes(int minutes)
Seconds
representing the number of seconds
equivalent to a number of hours.
The resulting amount will be second-based, with the number of seconds equal to the number of minutes multiplied by 60.
minutes
- the number of minutes, positive or negativejava.lang.ArithmeticException
- if numeric overflow occurspublic static Seconds from(java.time.temporal.TemporalAmount amount)
Seconds
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 Seconds
.
The result is calculated by looping around each unit in the specified amount.
Each amount is converted to seconds 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.
amount
- the temporal amount to convert, not nulljava.time.DateTimeException
- if unable to convert to a Seconds
java.lang.ArithmeticException
- if numeric overflow occurspublic static Seconds parse(java.lang.CharSequence text)
Seconds
from a text string such as PTnS
.
This will parse the string produced by toString()
and other
related formats based on ISO-8601 PnDTnHnMnS
.
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 four 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",
followed by one section for seconds suffixed by "S".
At least one section must be present.
If the hours, minutes or seconds section is present it must be prefixed by "T".
If the hours, minutes or seconds 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, minutes and seconds are not part of the ISO-8601 standard.
For example, the following are valid inputs:
"PT2S" -- Seconds.of(2) "PT-2S" -- Seconds.of(-2) "-PT2S" -- Seconds.of(-2) "-PT-2S" -- Seconds.of(2) "PT3S" -- Seconds.of(3 * 60) "PT3H-2M7S" -- Seconds.of(3 * 3600 - 2 * 60 + 7) "P2D" -- Seconds.of(2 * 86400) "P2DT3H" -- Seconds.of(2 * 86400 + 3 * 3600)
text
- the text to parse, not nulljava.time.format.DateTimeParseException
- if the text cannot be parsed to a periodpublic static Seconds between(java.time.temporal.Temporal startInclusive, java.time.temporal.Temporal endExclusive)
Seconds
consisting of the number of seconds 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.
startInclusive
- the start temporal, inclusive, not nullendExclusive
- the end temporal, exclusive, not nullpublic long get(java.time.temporal.TemporalUnit unit)
This returns a value for the supported unit - SECONDS
.
All other units throw an exception.
get
in interface java.time.temporal.TemporalAmount
unit
- the TemporalUnit
for which to return the valuejava.time.temporal.UnsupportedTemporalTypeException
- if the unit is not supportedpublic java.util.List<java.time.temporal.TemporalUnit> getUnits()
The single supported unit is SECONDS
.
This set can be used in conjunction with get(TemporalUnit)
to
access the entire state of the amount.
getUnits
in interface java.time.temporal.TemporalAmount
public int getAmount()
public Seconds plus(java.time.temporal.TemporalAmount amountToAdd)
The parameter is converted using from(TemporalAmount)
.
This instance is immutable and unaffected by this method call.
amountToAdd
- the amount to add, not nullSeconds
based on this instance with the requested amount added, not nulljava.time.DateTimeException
- if the specified amount contains an invalid unitjava.lang.ArithmeticException
- if numeric overflow occurspublic Seconds plus(int seconds)
This instance is immutable and unaffected by this method call.
seconds
- the amount of seconds to add, may be negativeSeconds
based on this instance with the requested amount added, not nulljava.lang.ArithmeticException
- if the result overflows an intpublic Seconds minus(java.time.temporal.TemporalAmount amountToAdd)
The parameter is converted using from(TemporalAmount)
.
This instance is immutable and unaffected by this method call.
amountToAdd
- the amount to add, not nullSeconds
based on this instance with the requested amount subtracted, not nulljava.time.DateTimeException
- if the specified amount contains an invalid unitjava.lang.ArithmeticException
- if numeric overflow occurspublic Seconds minus(int seconds)
This instance is immutable and unaffected by this method call.
seconds
- the amount of seconds to add, may be negativeSeconds
based on this instance with the requested amount subtracted, not nulljava.lang.ArithmeticException
- if the result overflows an intpublic Seconds multipliedBy(int scalar)
This instance is immutable and unaffected by this method call.
scalar
- the scalar to multiply by, not nulljava.lang.ArithmeticException
- if numeric overflow occurspublic Seconds dividedBy(int divisor)
The calculation uses integer division, thus 3 divided by 2 is 1.
This instance is immutable and unaffected by this method call.
divisor
- the amount to divide by, may be negativejava.lang.ArithmeticException
- if the divisor is zeropublic Seconds negated()
This instance is immutable and unaffected by this method call.
java.lang.ArithmeticException
- if numeric overflow occurs, which only happens if
the amount is Long.MIN_VALUE
public Seconds abs()
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.
java.lang.ArithmeticException
- if numeric overflow occurs, which only happens if
the amount is Long.MIN_VALUE
public java.time.Duration toDuration()
Duration
.
This returns a duration with the same number of seconds.
public java.time.temporal.Temporal addTo(java.time.temporal.Temporal temporal)
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.
addTo
in interface java.time.temporal.TemporalAmount
temporal
- the temporal object to adjust, not nulljava.time.DateTimeException
- if unable to addjava.time.temporal.UnsupportedTemporalTypeException
- if the SECONDS unit is not supportedjava.lang.ArithmeticException
- if numeric overflow occurspublic java.time.temporal.Temporal subtractFrom(java.time.temporal.Temporal temporal)
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.
subtractFrom
in interface java.time.temporal.TemporalAmount
temporal
- the temporal object to adjust, not nulljava.time.DateTimeException
- if unable to subtractjava.time.temporal.UnsupportedTemporalTypeException
- if the SECONDS unit is not supportedjava.lang.ArithmeticException
- if numeric overflow occurspublic int compareTo(Seconds otherAmount)
Seconds
.
The comparison is based on the total length of the amounts.
It is "consistent with equals", as defined by Comparable
.
compareTo
in interface java.lang.Comparable<Seconds>
otherAmount
- the other amount, not nullpublic boolean equals(java.lang.Object otherAmount)
Seconds
.
The comparison is based on the total length of the durations.
equals
in class java.lang.Object
otherAmount
- the other amount, null returns falsepublic int hashCode()
hashCode
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object
Copyright © 2010–2018 ThreeTen.org. All rights reserved.