Duration (Performetrics 2.4.0 API)

java.lang.Object
- net.obvj.performetrics.util.Duration

All Implemented Interfaces:

Comparable<Duration>
```
public class Duration
extends Object
implements Comparable<Duration>
```
A time-based amount, such as '01:59:59.987654321 (H:M:S.ns)'.

This class models a quantity or amount of time in terms of:
- hours, from 0 to the maximum value that can be held in a long
- minutes within the hour, from 0 to 59
- seconds within the minute, from 0 to 59
- nanoseconds within the second, from 0 to 999,999,999
This class is immutable and thread-safe.
Since:

2.0.0

Author:

oswaldo.bapvic.jr

Field Summary

Fields
Modifier and Type	Field and Description
`static DurationFormat`	`DEFAULT_FORMAT` The default `DurationFormat` to be applied by `toString()` and `parse(String)` operations, if no format is specified.
`static Duration`	`ZERO` Constant for a duration of zero.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`int`	`compareTo(Duration otherDuration)` Compares this duration to the specified `Duration` based on the total length of the durations, as defined by `Comparable`.
`Duration`	`dividedBy(long divisor)` Returns a copy of this duration divided by the specified value.
`boolean`	`equals(Object object)`
`long`	`getHours()` Returns the number of hours in this duration.
`int`	`getMinutes()` Returns the number of minutes within the hour in this duration.
`int`	`getNanoseconds()` Returns the number of nanoseconds within the second in this duration.
`int`	`getSeconds()` Returns the number of seconds within the minute in this duration.
`int`	`hashCode()`
`boolean`	`isZero()` Checks if this duration is zero length.
`static Duration`	`of(long amount, TimeUnit timeUnit)` Obtains a `Duration` representing an amount in the specified time unit.
`static Duration`	`parse(String string)` Obtains a `Duration` from a string in default format.
`static Duration`	`parse(String string, DurationFormat format)` Obtains a `Duration` from a string in a specific `DurationFormat`.
`Duration`	`plus(Duration duration)` Returns a copy of this duration with the specified duration added.
`Duration`	`plus(long amount, TimeUnit timeUnit)` Returns a copy of this duration with the specified duration added.
`static Duration`	`sum(Duration duration1, Duration duration2)` Returns the sum of two durations.
`double`	`toSeconds()` Converts this duration to the total length in seconds and fractional nanoseconds, with a fixed scale of 9, so nanoseconds precision is preserved.
`String`	`toString()` Returns a string representation of this `Duration` in default format.
`String`	`toString(DurationFormat format)` Returns a string representation of this `Duration` with a specific format.
`String`	`toString(DurationFormat format, boolean printLegend)` Returns a string representation of this `Duration` with a specific format.
`double`	`toTimeUnit(TimeUnit timeUnit)` Converts this duration to the total length in a given time unit, with default scale.
`double`	`toTimeUnit(TimeUnit timeUnit, int scale)` Converts this duration to the total length in a given time unit, with a custom scale.

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - ZERO
```
public static final Duration ZERO
```
    Constant for a duration of zero.
  - DEFAULT_FORMAT
```
public static final DurationFormat DEFAULT_FORMAT
```
    The default DurationFormat to be applied by toString() and parse(String) operations, if no format is specified.
- Method Detail
  - of
```
public static Duration of(long amount,
                          TimeUnit timeUnit)
```
    Obtains a Duration representing an amount in the specified time unit.
    For example, calling Duration.of(65, SECONDS) produces an object in which the getters behave according to the example below:
```
 duration.getHours()       //returns: 0
 duration.getMinutes()     //returns: 1
 duration.getSeconds()     //returns: 5
 duration.getNanoseconds() //returns: 0
 
```
    Parameters:
    
    amount - the amount of the duration, measured in terms of the time unit argument, not negative
    
    timeUnit - the unit that the amount argument is measured in, not null
    
    Returns:
    
    a Duration, not null
    
    Throws:
    
    NullPointerException - if the specified time unit is null
    
    IllegalArgumentException - if the specified duration amount is negative
  - parse
```
public static Duration parse(String string)
```
    Obtains a Duration from a string in default format.
    This will parse a textual representation of a duration produced by toString().
    
    Parameters:
    
    string - the string to parse, not null
    
    Returns:
    
    the parsed Duration, not null
    
    Throws:
    
    NullPointerException - if the specified string is null
    
    IllegalArgumentException - if the string cannot be parsed using default format
    
    Since:
    
    2.4.0
  - parse
```
public static Duration parse(String string,
                             DurationFormat format)
```
    Obtains a Duration from a string in a specific DurationFormat.
    This will parse a textual representation of a duration, including the string produced by toString(DurationFormat).
    
    Parameters:
    
    string - the string to parse, not null
    
    format - the DurationFormat in which the string is represented, not null
    
    Returns:
    
    the parsed Duration, not null
    
    Throws:
    
    NullPointerException - if either the specified string or the DurationFormat is null
    
    IllegalArgumentException - if the string cannot be parsed as a duration using the specified DurationFormat
    
    Since:
    
    2.4.0
  - getHours
```
public long getHours()
```
    Returns the number of hours in this duration.
    The hours field is a value from 0 to the maximum value that can be held in a long.
    
    Returns:
    
    the number of hours in this duration
  - getMinutes
```
public int getMinutes()
```
    Returns the number of minutes within the hour in this duration.
    The minutes field is a value from 0 to 59, which is an adjustment to the length in hours, retrieved by calling getHours().
    
    Returns:
    
    the minutes within the hours part of the length of the duration, from 0 to 59
  - getSeconds
```
public int getSeconds()
```
    Returns the number of seconds within the minute in this duration.
    The seconds field is a value from 0 to 59, which is an adjustment to the length in minutes, and hours, each part separately retrieved with their respective getter methods.
    
    Returns:
    
    the seconds within the minutes part of the length of the duration, from 0 to 59
  - getNanoseconds
```
public int getNanoseconds()
```
    Returns the number of nanoseconds within the second in this duration.
    The nanoseconds field is a value from 0 to 999,999,999, which is an adjustment to the length in seconds, minutes, and hours, each part separately retrieved with their respective getter methods.
    
    Returns:
    
    the nanoseconds within the seconds part of the length of the duration, from 0 to 999,999,999
  - isZero
```
public boolean isZero()
```
    Checks if this duration is zero length.
    
    Returns:
    
    true if this duration has a total length equal to zero
    
    Since:
    
    2.2.2
  - equals
```
public boolean equals(Object object)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - toString
```
public String toString()
```
    Returns a string representation of this Duration in default format.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a string representation of this object
  - toString
```
public String toString(DurationFormat format)
```
    Returns a string representation of this Duration with a specific format.
    Note: This is equivalent to calling toString(format, true)
    
    Parameters:
    
    format - the DurationFormat to be applied
    
    Returns:
    
    a string representation of this object in the specified format
  - toString
```
public String toString(DurationFormat format,
                       boolean printLegend)
```
    Returns a string representation of this Duration with a specific format.
    
    Parameters:
    
    format - the DurationFormat to be applied
    
    printLegend - a flag indicating whether or not to include a legend in the generated string
    
    Returns:
    
    a string representation of this object in the specified format
    
    Throws:
    
    NullPointerException - if the specified DurationFormat is null
  - toTimeUnit
```
public double toTimeUnit(TimeUnit timeUnit)
```
    Converts this duration to the total length in a given time unit, with default scale.
    Note: The number of decimal places applied is determined by ConfigurationHolder.getConfiguration().getScale() and may be changed by calling Performetrics.setScale(int).
    
    Parameters:
    
    timeUnit - the target time unit, not null
    
    Returns:
    
    the total length of the duration in the specified time unit, with default scale
    
    Throws:
    
    NullPointerException - if the specified time unit is null
  - toTimeUnit
```
public double toTimeUnit(TimeUnit timeUnit,
                         int scale)
```
    Converts this duration to the total length in a given time unit, with a custom scale.
    
    Parameters:
    
    timeUnit - the target time unit, not null
    
    scale - a positive number indicates the number of decimal places to maintain; if negative, the default scale will be applied
    
    Returns:
    
    the total length of the duration in the specified time unit, with a custom scale, not null
    
    Throws:
    
    NullPointerException - if the specified time unit is null
  - toSeconds
```
public double toSeconds()
```
    Converts this duration to the total length in seconds and fractional nanoseconds, with a fixed scale of 9, so nanoseconds precision is preserved.
    Note: This is equivalent to calling: toTimeUnit(TimeUnit.SECONDS, 9)
    
    Returns:
    
    the total length of the duration in seconds, with a scale of 9, not null
  - plus
```
public Duration plus(Duration duration)
```
    Returns a copy of this duration with the specified duration added.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    
    duration - the duration to add, not null
    
    Returns:
    
    a Duration based on this duration with the specified duration added, not null
    
    Throws:
    
    NullPointerException - if the specified duration is null
    
    ArithmeticException - if numeric overflow occurs
  - plus
```
public Duration plus(long amount,
                     TimeUnit timeUnit)
```
    Returns a copy of this duration with the specified duration added.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    
    amount - the amount to add, measured in terms of the timeUnit argument
    
    timeUnit - the unit that the amount to add is measured in, not null
    
    Returns:
    
    a Duration based on this duration with the specified duration added, not null
    
    Throws:
    
    NullPointerException - if the specified time unit is null
    
    ArithmeticException - if numeric overflow occurs
    
    Since:
    
    2.2.2
  - sum
```
public static Duration sum(Duration duration1,
                           Duration duration2)
```
    Returns the sum of two durations.
    This instances are immutable and unaffected by this method call.
    
    Parameters:
    
    duration1 - the first duration to add, not null
    
    duration2 - the second duration to add, not null
    
    Returns:
    
    a Duration resulting by adding two durations, not null
    
    Throws:
    
    NullPointerException - if the specified duration is null
    
    ArithmeticException - if numeric overflow occurs
  - dividedBy
```
public Duration dividedBy(long divisor)
```
    Returns a copy of this duration divided by the specified value.
    This instance is immutable and unaffected by this method call.
    
    Parameters:
    
    divisor - the value to divide the duration by, positive or negative, not zero
    
    Returns:
    
    a Duration based on this duration divided by the specified divisor, not null
    
    Throws:
    
    ArithmeticException - if the divisor is zero or if numeric overflow occurs
    
    Since:
    
    2.2.0
  - compareTo
```
public int compareTo(Duration otherDuration)
```
    Compares this duration to the specified Duration based on the total length of the durations, as defined by Comparable.
    
    Specified by:
    
    compareTo in interface Comparable<Duration>
    
    Parameters:
    
    otherDuration - the other duration to compare to; not null
    
    Returns:
    
    the comparator value, negative if less, positive if greater
    
    Since:
    
    2.2.3

Class Duration

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ZERO

DEFAULT_FORMAT

Method Detail

of

parse

parse

getHours

getMinutes

getSeconds

getNanoseconds

isZero

equals

hashCode

toString

toString

toString

toTimeUnit

toTimeUnit

toSeconds

plus

plus

sum

dividedBy

compareTo