public final class PeriodFields extends Object implements PeriodProvider, Iterable<PeriodField>, Serializable
PeriodFields
is an immutable period that stores an amount of human-scale
time for a number of units. For example, humans typically measure periods of time
in units of years, months, days, hours, minutes and seconds. These concepts are
defined by instances of PeriodUnit
in the chronology classes. This class
allows an amount to be specified for a number of the units, such as '3 Days and 65 Seconds'.
Basic mathematical operations are provided - plus(), minus(), multipliedBy(), dividedBy() and negated(), all of which return a new instance
A value of zero can also be stored for any unit. This means that a
period of zero hours is not equal to a period of zero minutes.
However, an empty instance constant exists to represent zero irrespective of unit.
The withZeroesRemoved()
method removes zero values.
PeriodFields
can store units of any kind which makes it usable with
any calendar system.
PeriodFields is immutable and thread-safe.
Modifier and Type | Field and Description |
---|---|
static PeriodFields |
ZERO
A constant for a period of zero.
|
Modifier and Type | Method and Description |
---|---|
boolean |
contains(PeriodUnit unit)
Checks whether this period contains an amount for the unit.
|
PeriodFields |
dividedBy(long divisor)
Returns a copy of this period with each amount in this period divided
by the specified value.
|
boolean |
equals(Object obj)
Checks if this instance equal to the specified period.
|
PeriodField |
get(PeriodUnit unit)
Gets the period for the specified unit.
|
long |
getAmount(PeriodUnit unit)
Gets the amount of this period for the specified unit.
|
int |
getAmountInt(PeriodUnit unit)
Gets the amount of this period for the specified unit converted
to an
int . |
int |
hashCode()
Returns the hash code for this period.
|
boolean |
isPositive()
Checks if this period is fully positive, excluding zero.
|
boolean |
isPositiveOrZero()
Checks if this period is fully positive, including zero.
|
boolean |
isZero()
Checks if this period is zero-length.
|
Iterator<PeriodField> |
iterator()
Iterates through all the single-unit periods in this period.
|
PeriodFields |
minus(long amount,
PeriodUnit unit)
Returns a copy of this period with the specified period subtracted.
|
PeriodFields |
minus(PeriodProvider periodProvider)
Returns a copy of this period with the specified period subtracted.
|
PeriodFields |
multipliedBy(long scalar)
Returns a copy of this period with each amount in this period multiplied
by the specified scalar.
|
PeriodFields |
negated()
Returns a copy of this period with each amount in this period negated.
|
PeriodFields |
normalized()
Returns a copy of this period with the amounts normalized.
|
PeriodFields |
normalizedTo(PeriodUnit... units)
Returns a copy of this period with the amounts normalized to the specified units.
|
static PeriodFields |
of(Duration duration)
Obtains a
PeriodFields from a Duration based on the standard
durations of seconds and nanoseconds. |
static PeriodFields |
of(long amount,
PeriodUnit unit)
Obtains a
PeriodFields from an amount and unit. |
static PeriodFields |
of(PeriodField... periods)
Obtains a
PeriodFields from an array of single-unit periods. |
static PeriodFields |
of(PeriodField period)
Obtains a
PeriodFields from a single-unit period. |
static PeriodFields |
of(PeriodProvider periodProvider)
Obtains a
PeriodFields from a PeriodProvider . |
static PeriodFields |
ofTotal(PeriodProvider... periodProviders)
Obtains a
PeriodFields by totalling the amounts in a list of
PeriodProvider instances. |
PeriodFields |
plus(long amount,
PeriodUnit unit)
Returns a copy of this period with the specified period added.
|
PeriodFields |
plus(PeriodProvider periodProvider)
Returns a copy of this period with the specified period added.
|
PeriodFields |
remainder(PeriodField period)
Returns a copy of this period with the modular division remainder of each field
calculated with respect to the specified period.
|
PeriodFields |
retain(PeriodUnit... units)
Returns a copy of this period with the specified units retained.
|
PeriodFields |
retainConvertible(PeriodUnit... units)
Returns a copy of this period with only those units that can be converted to
the specified units.
|
int |
size()
Returns the size of the set of units in this period.
|
Duration |
toDuration()
Calculates the accurate duration of this period.
|
PeriodFields |
toEquivalent(PeriodUnit... units)
Converts this period to one containing only the units specified.
|
Duration |
toEstimatedDuration()
Estimates the duration of this period.
|
SortedMap<PeriodUnit,PeriodField> |
toMap()
Returns a
Map equivalent to this period. |
PeriodFields |
toPeriodFields()
Converts this period to a
PeriodFields , trivially
returning this . |
String |
toString()
Returns a string representation of the period, such as '[6 Days, 13 Hours]'.
|
PeriodField |
toTotal(PeriodUnit unit)
Totals this period in terms of a single unit.
|
PeriodFields |
with(long amount,
PeriodUnit unit)
Returns a copy of this period with the specified amount for the unit.
|
PeriodFields |
with(PeriodProvider periodProvider)
Returns a copy of this period with the specified values altered.
|
PeriodFields |
without(PeriodUnit unit)
Returns a copy of this period with the specified unit removed.
|
PeriodFields |
withZeroesRemoved()
Returns a copy of this period with all zero amounts removed.
|
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
forEach, spliterator
public static final PeriodFields ZERO
public static PeriodFields of(long amount, PeriodUnit unit)
PeriodFields
from an amount and unit.
The parameters represent the two parts of a phrase like '6 Days'.
amount
- the amount of create with, positive or negativeunit
- the period unit, not nullPeriodFields
instance, never nullpublic static PeriodFields of(PeriodField period)
PeriodFields
from a single-unit period.period
- the single-unit period, not nullPeriodFields
instance, never nullpublic static PeriodFields of(PeriodField... periods)
PeriodFields
from an array of single-unit periods.
The period fields must all have different units.
periods
- the array of single-unit periods, not nullPeriodFields
instance, never nullIllegalArgumentException
- if the same period unit occurs twicepublic static PeriodFields of(PeriodProvider periodProvider)
PeriodFields
from a PeriodProvider
.
This method provides null-checking around PeriodProvider.toPeriodFields()
.
periodProvider
- the provider to create from, not nullPeriodFields
instance, never nullNullPointerException
- if the period provider is null or returns nullpublic static PeriodFields ofTotal(PeriodProvider... periodProviders)
PeriodFields
by totalling the amounts in a list of
PeriodProvider
instances.
This method returns a period with all the unit-amount pairs from the providers totalled. Thus a period of '2 Months and 5 Days' combined with a period of '7 Days and 21 Hours' will yield a result of '2 Months, 12 Days and 21 Hours'.
periodProviders
- the providers to total, not nullPeriodFields
instance, never nullNullPointerException
- if any period provider is null or returns nullpublic static PeriodFields of(Duration duration)
PeriodFields
from a Duration
based on the standard
durations of seconds and nanoseconds.
The conversion will create an instance with two units - the ISOChronology
seconds and nanoseconds units. This matches the toDuration()
method.
duration
- the duration to create from, not nullPeriodFields
instance, never nullpublic boolean isZero()
This checks whether all the amounts in this period are zero.
public boolean isPositive()
This checks whether all the amounts in this period are positive, defined as greater than zero.
public boolean isPositiveOrZero()
This checks whether all the amounts in this period are positive, defined as greater than or equal to zero.
public int size()
This returns the number of different units that are stored.
public Iterator<PeriodField> iterator()
This method fulfills the Iterable
interface and allows looping
around the contained single-unit periods using the for-each loop.
iterator
in interface Iterable<PeriodField>
public boolean contains(PeriodUnit unit)
unit
- the unit to query, null returns falsepublic PeriodField get(PeriodUnit unit)
This method allows the period to be queried by unit, like a map.
If the unit is not found then null
is returned.
unit
- the unit to query, not nullpublic long getAmount(PeriodUnit unit)
This method allows the amount to be queried by unit, like a map. If the unit is not found then zero is returned.
unit
- the unit to query, not nullCalendricalException
- if there is no amount for the unitpublic int getAmountInt(PeriodUnit unit)
int
.
This method allows the amount to be queried by unit, like a map. If the unit is not found then zero is returned.
unit
- the unit to query, not nullCalendricalException
- if there is no amount for the unitArithmeticException
- if the amount is too large to be returned in an intpublic PeriodFields withZeroesRemoved()
This instance is immutable and unaffected by this method call.
PeriodFields
based on this period with zero amounts removed, never nullpublic PeriodFields with(long amount, PeriodUnit unit)
If this period already contains an amount for the unit then the amount is replaced. Otherwise, the unit-amount pair is added.
This instance is immutable and unaffected by this method call.
amount
- the amount to store in terms of the unit, positive or negativeunit
- the unit to store not nullPeriodFields
based on this period with the specified period overlaid, never nullpublic PeriodFields with(PeriodProvider periodProvider)
This method operates on each unit in the input in turn. If this period already contains an amount for the unit then the amount is replaced. Otherwise, the unit-amount pair is added.
For example, '6 Years, 7 Months' with '2 Months 3 Days' will return '6 Years, 2 Months, 3 Days'.
This instance is immutable and unaffected by this method call.
periodProvider
- the period to merge over this period, not nullPeriodFields
based on this period with the specified period overlaid, never nullpublic PeriodFields without(PeriodUnit unit)
If this period already contains an amount for the unit then the amount is removed. Otherwise, no action occurs.
This instance is immutable and unaffected by this method call.
unit
- the unit to remove, not nullPeriodFields
based on this period with the specified unit removed, never nullpublic PeriodFields plus(PeriodProvider periodProvider)
The returned period will take each unit in the provider and add the value to the amount already stored in this period, returning a new one. If this period does not contain an amount for the unit then the unit and amount are simply returned directly in the result. The result will have the union of the units in this instance and the units in the specified instance.
This instance is immutable and unaffected by this method call.
periodProvider
- the period to add, not nullPeriodFields
based on this period with the specified period added, never nullArithmeticException
- if the calculation overflowspublic PeriodFields plus(long amount, PeriodUnit unit)
The result will contain the units and amounts from this period plus the specified unit and amount. The specified unit will always be in the result even if the amount is zero.
This instance is immutable and unaffected by this method call.
amount
- the amount to add, measured in the specified unit, positive or negativeunit
- the unit defining the amount, not nullPeriodFields
based on this period with the specified period added, never nullArithmeticException
- if the calculation overflowspublic PeriodFields minus(PeriodProvider periodProvider)
The returned period will take each unit in the provider and subtract the value from the amount already stored in this period, returning a new one. If this period does not contain an amount for the unit then the unit and amount are simply returned directly in the result. The result will have the union of the units in this instance and the units in the specified instance.
This instance is immutable and unaffected by this method call.
periodProvider
- the period to subtract, not nullPeriodFields
based on this period with the specified period subtracted, never nullArithmeticException
- if the calculation overflowspublic PeriodFields minus(long amount, PeriodUnit unit)
The result will contain the units and amounts from this period minus the specified unit and amount. The specified unit will always be in the result even if the amount is zero.
This instance is immutable and unaffected by this method call.
amount
- the amount to subtract, measured in the specified unit, positive or negativeunit
- the unit defining the amount, not nullPeriodFields
based on this period with the specified period subtracted, never nullArithmeticException
- if the calculation overflowspublic PeriodFields multipliedBy(long scalar)
scalar
- the scalar to multiply by, not nullPeriodFields
based on this period with the amounts multiplied by the scalar, never nullArithmeticException
- if the calculation overflowspublic PeriodFields dividedBy(long divisor)
divisor
- the value to divide by, not null, not zeroPeriodFields
based on this period with the amounts divided by the divisor, never nullArithmeticException
- if dividing by zeropublic PeriodFields negated()
PeriodFields
based on this period with the amounts negated, never nullArithmeticException
- if the calculation overflowspublic PeriodFields retain(PeriodUnit... units)
This method will return a new period that only has the specified units. All units not present in the input will not be present in the result. In most cases, the result will not be equivalent to this period.
This instance is immutable and unaffected by this method call.
units
- the units to retain, not altered, not null, no nullsPeriodFields
based on this period with the specified units retained, never nullpublic PeriodFields retainConvertible(PeriodUnit... units)
This method will return a new period where every field can be converted to one of the specified units. In the result, each of the retained periods will have the same amount as they do in this period - no conversion or normalization occurs.
For example, if this period is '2 Days, 5 Hours, 7 Minutes' and the specified unit array contains 'Seconds' then the output will be '5 Hours, 7 Minutes'. The 'Days' unit is not retained as it cannot be converted to 'Seconds'.
This instance is immutable and unaffected by this method call.
units
- the units to retain, not altered, not null, no nullsPeriodFields
based on this period with the specified units retained, never nullpublic PeriodFields remainder(PeriodField period)
This method will return a new period where every field represents a period less than the specified period. If this period contains a period that cannot be converted to the specified unit then an exception is thrown.
For example, if this period is '37 Hours, 7 Minutes' and the specified period is '24 Hours' then the output will be '13 Hours, 7 Minutes'.
This method requires this period to be convertible to the specified period.
To ensure this is true, call retainConvertible(javax.time.calendar.PeriodUnit...)
, with the base unit of the
period passed into this method, before calling this method.
This instance is immutable and unaffected by this method call.
period
- the period to calculate the remainder against, not nullPeriodFields
based on this period with the remainder, never nullCalendricalException
- if any field cannot be converted to the unit of the periodpublic PeriodFields normalized()
The calculation examines each pair of units in this period that have a fixed conversion factor. Each pair is adjusted so that the amount in the smaller unit does not exceed the amount of the fixed conversion factor.
For example, a period of '2 Decades, 2 Years, 17 Months' normalized using 'Years' and 'Months' will return '23 Years, 5 Months'.
The result will always contain all the units present in this period, even if they are zero. The result will be equivalent to this period.
ArithmeticException
- if the calculation overflowspublic PeriodFields normalizedTo(PeriodUnit... units)
This will normalize the period around the specified units. The calculation examines each pair of units that have a fixed conversion factor. Each pair is adjusted so that the amount in the smaller unit does not exceed the amount of the fixed conversion factor. At least one unit must be specified for this method to have any effect.
For example, a period of '2 Decades, 2 Years, 17 Months' normalized using 'Years' and 'Months' will return '23 Years, 5 Months'.
Any part of this period that cannot be converted to one of the specified units will be unaffected in the result.
The result will always contain all the specified units, even if they are zero. The result will be equivalent to this period.
units
- the unit array to normalize to, not altered, not null, no nullsArithmeticException
- if the calculation overflowspublic PeriodField toTotal(PeriodUnit unit)
This will take each of the stored PeriodField
instances and
convert them to the specified unit. The result will be the total of these
converted periods.
For example, '3 Hours, 34 Minutes' can be totalled to minutes resulting in '214 Minutes'.
unit
- the unit to total in, not nullCalendricalException
- if this period cannot be converted to the unitArithmeticException
- if the calculation overflowspublic PeriodFields toEquivalent(PeriodUnit... units)
This converts this period to one measured in the specified units. It operates by looping through the individual parts of this period, converting each in turn to one of the specified units. These converted periods are then combined to form the result.
No normalization is performed on the result.
This means that an amount in a smaller unit cannot be converted to an amount in a larger unit.
If you need to do this, call normalized()
before calling this method.
This method uses PeriodField.toEquivalent(PeriodUnit...)
and as such,
it is recommended to specify the units from largest to smallest.
For example, '3 Hours' can normally be converted to both minutes and seconds. If the units array contains both 'Minutes' and 'Seconds', then the result will be measured in whichever is first in the array.
units
- the required unit array, not altered, not null, no nullsCalendricalException
- if this period cannot be converted to any of the unitsArithmeticException
- if the calculation overflowspublic Duration toEstimatedDuration()
Each PeriodUnit
contains an estimated duration for that unit.
The per-unit estimate allows an estimate to be calculated for the whole period
including fields of variable duration. The estimate will equal the
accurate
calculation if all the fields are based on seconds.
ArithmeticException
- if the calculation overflowspublic Duration toDuration()
The conversion is based on the ISOChronology
definition of the seconds and
nanoseconds units. If all the fields in this period can be converted to either seconds
or nanoseconds then the conversion will succeed, subject to calculation overflow.
If any field cannot be converted to these fields above then an exception is thrown.
ISOChronology
fields, never nullArithmeticException
- if the calculation overflowspublic SortedMap<PeriodUnit,PeriodField> toMap()
Map
equivalent to this period.
The map will connect the unit to the single field period. The sort order is from largest unit to smallest unit.
public PeriodFields toPeriodFields()
PeriodFields
, trivially
returning this
.toPeriodFields
in interface PeriodProvider
this
, never nullpublic boolean equals(Object obj)
Two PeriodFields
instances are equal if all the contained
PeriodField
instances are equal.
public int hashCode()
Copyright © 2014. All rights reserved.