agi.foundation.time

(agi.foundation.core-2024r3.jar)

Class Duration

java.lang.Object

agi.foundation.time.Duration

All Implemented Interfaces:

IEquatable<Duration>, ImmutableValueType, ValueType, IEquatableEpsilon<Duration>, Comparable<Duration>

public final class Duration
extends Object
implements Comparable<Duration>, IEquatable<Duration>, IEquatableEpsilon<Duration>, ImmutableValueType

Represents a span of time. This class offers the same precision as the JulianDate type. It stores a number of days as an int and a number of seconds as a double.

Constructor Summary

Constructors

Constructor and Description
Duration() Initializes a new instance.
Duration(Duration timeSpan) Initializes a new Duration from a Duration.
Duration(Duration timeSpan, TimeStandard standard) Initializes a new Duration from a Duration.
Duration(int days, double seconds) Initializes a new instance of Duration from a specified number of days and seconds.
Duration(int days, double seconds, TimeStandard standard) Initializes a new instance of Duration from a specified number of days and seconds.
Duration(int days, int hours, int minutes, double seconds) Initializes a new instance of Duration from a specified number of days, hours, minutes, and seconds.
Duration(int days, int hours, int minutes, double seconds, TimeStandard standard) Initializes a new instance of Duration from a specified number of days, hours, minutes, and seconds.

Method Summary

Modifier and Type	Method and Description
Duration	add(Duration other) Adds the specified Duration to this instance.
static Duration	add(Duration left, Duration right) Adds two specified Duration instances.
Duration	addDays(double days) Adds a specified number of days to this Duration and returns the new Duration.
Duration	addSeconds(double seconds) Adds a specified number of seconds to this Duration and returns the new Duration.
int	compareTo(Duration other) Compares this instance with another instance of the same type.
Duration	divide(double constant) Divides the Duration by a constant.
double	divide(Duration divisor) Divides the Duration by another Duration, yield a constant.
static Duration	divide(Duration dividend, double divisor) Divides the Duration by a constant.
static double	divide(Duration dividend, Duration divisor) Divides the Duration by another duration.
static boolean	equals(Duration left, Duration right) Returns true if two Durations are exactly equal, within the limits of floating point precision.
boolean	equals(Object obj) Returns true if this Duration exactly equals another Duration, within the limits of floating point precision.
boolean	equalsEpsilon(Duration other, double epsilon) Returns true if this Duration is within epsilon seconds of the specified Duration.
boolean	equalsType(Duration other) Returns true if this Duration exactly equals another Duration, within the limits of floating point precision.
static Duration	fromDays(double days) Returns a Duration that represents the specified number of days.
static Duration	fromDays(double days, TimeStandard standard) Returns a Duration that represents the specified number of days using the specified time standard.
static Duration	fromHours(double hours) Returns a Duration that represents the specified number of hours.
static Duration	fromHours(double hours, TimeStandard standard) Returns a Duration that represents the specified number of hours using the specified time standard.
static Duration	fromMinutes(double minutes) Returns a Duration that represents the specified number of minutes.
static Duration	fromMinutes(double minutes, TimeStandard standard) Returns a Duration that represents the specified number of minutes using the specified time standard.
static Duration	fromSeconds(double seconds) Returns a Duration that represents the specified number of seconds.
static Duration	fromSeconds(double seconds, TimeStandard standard) Returns a Duration that represents the specified number of seconds using the specified time standard.
int	getDays() Gets the day component of this Duration.
static Duration	getMaxValue() Gets the largest possible value of a Duration.
static Duration	getMinValue() Gets the smallest possible value of a Duration.
double	getSeconds() Gets the seconds component of this Duration.
TimeStandard	getStandard() Gets the time standard in which this Duration is measured.
double	getTotalDays() Gets the total number of whole and fractional days represented by this Duration.
double	getTotalSeconds() Gets the total number of seconds represented by this Duration, including the seconds that compose the days returned by the Days (get) property.
static Duration	getZero() Gets a Duration of 0 days and seconds.
static boolean	greaterThan(Duration left, Duration right) Returns true if left is longer than right.
static boolean	greaterThanOrEqual(Duration left, Duration right) Returns true if left is longer than or exactly equal to right.
int	hashCode() Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.
static double	hoursMinutesSecondsToSeconds(int hours, int minutes, double seconds) Converts the specified number of hours, minutes, and seconds to total duration in seconds.
static boolean	lessThan(Duration left, Duration right) Returns true if left is shorter than right.
static boolean	lessThanOrEqual(Duration left, Duration right) Returns true if left is shorter than or exactly equal to right.
Duration	multiply(double constant) Multiplies the Duration by a constant.
static Duration	multiply(Duration left, double right) Multiplies the Duration by a constant.
static Duration	negate(Duration value) Inverts a specified Duration.
static boolean	notEquals(Duration left, Duration right) Returns true if two Durations are NOT exactly equal, within the limits of floating point precision.
Duration	subtract(Duration other) Subtracts the specified Duration from this instance.
static Duration	subtract(Duration left, Duration right) Subtracts a specified Duration from another specified Duration.
Duration	toDuration() Returns a Duration equivalent to this Duration.
String	toString() Returns the value of the Duration in Days (get):Seconds (get).

Methods inherited from class java.lang.Object

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

Constructor Detail

Duration

public Duration()

Initializes a new instance.

Duration

public Duration(int days,
                int hours,
                int minutes,
                double seconds)

Initializes a new instance of Duration from a specified number of days, hours, minutes, and seconds. The time standard is not specified, so this Duration will match the time standard of anything it is added to or subtracted from.

Parameters:

days - The number of days in the new Duration.

hours - The number of hours in the new Duration.

minutes - The number of minutes in the new Duration.

seconds - The number of seconds in the new Duration.

Throws:

ArgumentOutOfRangeException - Thrown if the inputs represent a value too large to be stored in a Duration.

Duration

public Duration(int days,
                int hours,
                int minutes,
                double seconds,
                TimeStandard standard)

Initializes a new instance of Duration from a specified number of days, hours, minutes, and seconds. It also specifies that the time is measured using the specified time standard.

Parameters:

days - The number of days in the new Duration.

hours - The number of hours in the new Duration.

minutes - The number of minutes in the new Duration.

seconds - The number of seconds in the new Duration.

standard - The time standard in which the time is measured.

Throws:

ArgumentOutOfRangeException - Thrown if the inputs represent a value too large to be stored in a Duration.

Duration

public Duration(int days,
                double seconds)

Initializes a new instance of Duration from a specified number of days and seconds. The time standard is not specified, so this Duration will match the time standard of anything it is added to or subtracted from.

Parameters:

days - The number of days in the new Duration.

seconds - The number of seconds in the new Duration.

Throws:

ArgumentOutOfRangeException - Thrown if the inputs represent a value too large to be stored in a Duration.

Duration

public Duration(int days,
                double seconds,
                TimeStandard standard)

Initializes a new instance of Duration from a specified number of days and seconds. It also specifies that the time is measured using the specified time standard.

Parameters:

days - The number of days in the new Duration.

seconds - The number of seconds in the new Duration.

standard - The time standard in which the time is measured.

Throws:

ArgumentOutOfRangeException - Thrown if the inputs represent a value too large to be stored in a Duration.

Duration

public Duration(@Nonnull
                Duration timeSpan)

Initializes a new Duration from a Duration. The time standard is not specified, so this Duration will match the time standard of anything it is added to or subtracted from.

Parameters:

timeSpan - The time span.

Duration

public Duration(@Nonnull
                Duration timeSpan,
                TimeStandard standard)

Initializes a new Duration from a Duration. It also specifies that the time is measured using the specified time standard.

Parameters:

timeSpan - The time span.

standard - The time standard in which the span is measured.

Method Detail

hoursMinutesSecondsToSeconds

public static double hoursMinutesSecondsToSeconds(int hours,
                                                  int minutes,
                                                  double seconds)

Converts the specified number of hours, minutes, and seconds to total duration in seconds.

Parameters:

hours - The number of hours.

minutes - The number of minutes.

seconds - The number of seconds.

Returns:

The corresponding duration in seconds.

getMaxValue

@Nonnull
public static Duration getMaxValue()

Gets the largest possible value of a Duration.

The value is Integer.MAX_VALUE days and 86399.0 seconds.

getMinValue

@Nonnull
public static Duration getMinValue()

Gets the smallest possible value of a Duration.

The value is Integer.MIN_VALUE days and -86399.0 seconds.

getZero

@Nonnull
public static Duration getZero()

Gets a Duration of 0 days and seconds.

getDays

public final int getDays()

Gets the day component of this Duration.

getSeconds

public final double getSeconds()

Gets the seconds component of this Duration. This is the number of seconds represented by this Duration in addition to the Days (get), so it will always be less than TimeConstants.SecondsPerDay.

getStandard

public final TimeStandard getStandard()

Gets the time standard in which this Duration is measured.

getTotalDays

public final double getTotalDays()

Gets the total number of whole and fractional days represented by this Duration.

getTotalSeconds

public final double getTotalSeconds()

Gets the total number of seconds represented by this Duration, including the seconds that compose the days returned by the Days (get) property.

toDuration

@Nonnull
public final Duration toDuration()

Returns a Duration equivalent to this Duration.

Returns:

The time span.

toString

public String toString()

Returns the value of the Duration in Days (get):Seconds (get).

Overrides:

toString in class Object

Returns:

The string.

hashCode

public int hashCode()

Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.

Overrides:

hashCode in class Object

Returns:

A hash code for the current object.

See Also:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

equalsType

public final boolean equalsType(@Nonnull
                                Duration other)

Returns true if this Duration exactly equals another Duration, within the limits of floating point precision. To be considered equal, the Days (get) and Standard (get) properties must be identical (or one must be null) and the difference between the Seconds (get) properties must be less than 1.0e-10.

This method returns false if the two instances have different time standards, even if the values would be the same when converted to the same time standard.

Specified by:

equalsType in interface IEquatable<Duration>

Parameters:

other - The other Duration.

Returns:

true if this Duration exactly equals the other Duration, within the limits of floating point precision.

equals

public boolean equals(Object obj)

Returns true if this Duration exactly equals another Duration, within the limits of floating point precision. To be considered equal, the Days (get) and Standard (get) properties must be identical (or one must be null) and the difference between the Seconds (get) properties must be less than 1.0e-10.

This method returns false if the two instances have different time standards, even if the values would be the same when converted to the same time standard.

Overrides:

equals in class Object

Parameters:

obj - The other Duration.

Returns:

true if this Duration exactly equals the obj Duration, within the limits of floating point precision.

See Also:

Object.hashCode(), HashMap

equalsEpsilon

public final boolean equalsEpsilon(@Nonnull
                                   Duration other,
                                   double epsilon)

Returns true if this Duration is within epsilon seconds of the specified Duration. That is, in order for the Durations to be considered equal (and for this function to return true), the absolute value of the difference between them, in seconds, must be less than or equal to epsilon.

Specified by:

equalsEpsilon in interface IEquatableEpsilon<Duration>

Parameters:

other - The Duration to compare to this Duration.

epsilon - The largest difference between the Durations, in seconds, such that they will be considered equal.

Returns:

true if the dates are equal as defined by the epsilon value.

compareTo

public final int compareTo(@Nonnull
                           Duration other)

Compares this instance with another instance of the same type.

Specified by:

compareTo in interface Comparable<Duration>

Parameters:

other - An object to compare with this instance.

Returns:

A value indicating the relative order of the objects being compared. The return value has these meanings:

Value	Meaning
Less than zero	This instance is less than other.
Zero	This instance is equal to other.
Greater than zero	This instance is greater than other.

Throws:

ArgumentException - Thrown when comparing this object to a Duration defined in a different TimeStandard.

add

@Nonnull
public final Duration add(@Nonnull
                                    Duration other)

Adds the specified Duration to this instance.

The two Durations must have the same time standard, or one of the time standards must be null. Attempting to add two Duration instances with different time standards will result in an ArgumentException.

Parameters:

other - The Duration to add to this instance.

Returns:

A Duration that represents the value of this instance plus the value of other.

Throws:

ArgumentException - Thrown if this Duration and other have different TimeStandards.

ArgumentOutOfRangeException - Thrown if the result represents a value that cannot be stored in a Duration.

subtract

@Nonnull
public final Duration subtract(@Nonnull
                                         Duration other)

Subtracts the specified Duration from this instance.

The two Durations must have the same time standard, or one of the time standards must be null. Attempting to add two Duration instances with different time standards will result in an ArgumentException.

Parameters:

other - The Duration to subtract from this instance.

Returns:

A Duration that represents the value of this instance minus the value of other.

Throws:

ArgumentException - Thrown if this Duration and other have different TimeStandards.

ArgumentOutOfRangeException - Thrown if the result represents a value too large to be stored in a Duration.

multiply

@Nonnull
public final Duration multiply(double constant)

Multiplies the Duration by a constant.

Parameters:

constant - The constant by which to multiply the Duration.

Returns:

A Duration that represents the value of this instance multiplied by the constant.

Throws:

ArgumentOutOfRangeException - Thrown if the result represents a value too large to be stored in a Duration.

divide

public final double divide(@Nonnull
                           Duration divisor)

Divides the Duration by another Duration, yield a constant.

Parameters:

divisor - The Duration by which to divide this Duration.

Returns:

The result of dividing this Duration by another.

divide

@Nonnull
public final Duration divide(double constant)

Divides the Duration by a constant.

Parameters:

constant - The constant by which to divide the Duration.

Returns:

A Duration that represents the value of this instance divided by the constant.

Throws:

ArgumentOutOfRangeException - Thrown if the result represents a value too large to be stored in a Duration.

addSeconds

@Nonnull
public final Duration addSeconds(double seconds)

Adds a specified number of seconds to this Duration and returns the new Duration.

Parameters:

seconds - The number of seconds to add.

Returns:

A new Duration which is the sum of the original Duration and the specified number of seconds.

Throws:

ArgumentOutOfRangeException - Thrown if the result represents a value too large to be stored in a Duration.

addDays

@Nonnull
public final Duration addDays(double days)

Adds a specified number of days to this Duration and returns the new Duration.

Parameters:

days - The number of days to add.

Returns:

A new Duration which is the sum of the original Duration and the specified number of days.

Throws:

ArgumentOutOfRangeException - Thrown if the result represents a value too large to be stored in a Duration.

equals

public static boolean equals(@Nonnull
                             Duration left,
                             @Nonnull
                             Duration right)

Returns true if two Durations are exactly equal, within the limits of floating point precision. To be considered equal, the Days (get) and Standard (get) properties must be identical (or one must be null) and the difference between the Seconds (get) properties must be less than 1.0e-10.

This method returns false if the two instances have different time standards, even if the values would be the same when converted to the same time standard.

Parameters:

left - The left Duration.

right - The second Duration.

Returns:

true if the Durations are equal; otherwise false.

notEquals

public static boolean notEquals(@Nonnull
                                Duration left,
                                @Nonnull
                                Duration right)

Returns true if two Durations are NOT exactly equal, within the limits of floating point precision. To be considered equal, the Days (get) and Standard (get) properties must be identical (or one must be null) and the difference between the Seconds (get) properties must be less than 1.0e-10.

This method returns false if the two instances have different time standards, even if the values would be the same when converted to the same time standard.

Parameters:

left - The first Duration.

right - The second Duration.

Returns:

true if the Durations are not equal; otherwise false.

lessThan

public static boolean lessThan(@Nonnull
                               Duration left,
                               @Nonnull
                               Duration right)

Returns true if left is shorter than right.

Parameters:

left - The left Duration.

right - The right Duration.

Returns:

true if left is less than right; otherwise false.

greaterThan

public static boolean greaterThan(@Nonnull
                                  Duration left,
                                  @Nonnull
                                  Duration right)

Returns true if left is longer than right.

Parameters:

left - The left Duration.

right - The right Duration.

Returns:

true if left is greater than right; otherwise false.

lessThanOrEqual

public static boolean lessThanOrEqual(@Nonnull
                                      Duration left,
                                      @Nonnull
                                      Duration right)

Returns true if left is shorter than or exactly equal to right.

Parameters:

left - The left Duration.

right - The right Duration.

Returns:

true if left is less than or equal to right; otherwise false.

greaterThanOrEqual

public static boolean greaterThanOrEqual(@Nonnull
                                         Duration left,
                                         @Nonnull
                                         Duration right)

Returns true if left is longer than or exactly equal to right.

Parameters:

left - The left Duration.

right - The right Duration.

Returns:

true if left is greater than or equal to right; otherwise false.

add

@Nonnull
public static Duration add(@Nonnull
                                     Duration left,
                                     @Nonnull
                                     Duration right)

Adds two specified Duration instances.

Parameters:

left - The first Duration to add.

right - The second Duration to add.

Returns:

The sum of left and right.

subtract

@Nonnull
public static Duration subtract(@Nonnull
                                          Duration left,
                                          @Nonnull
                                          Duration right)

Subtracts a specified Duration from another specified Duration.

Parameters:

left - The subtrahend.

right - The minuend.

Returns:

The difference left minus right.

negate

@Nonnull
public static Duration negate(@Nonnull
                                        Duration value)

Inverts a specified Duration. For example, if the value represents a positive quantity of time, the returned Duration will be a negative quantity of time.

Parameters:

value - The value to invert.

Returns:

The inverted Duration.

multiply

@Nonnull
public static Duration multiply(@Nonnull
                                          Duration left,
                                          double right)

Multiplies the Duration by a constant.

Parameters:

left - The Duration to multiply.

right - The constant by which to multiply the Duration.

Returns:

A Duration that represents the value of this instance multiplied by the constant.

divide

public static double divide(@Nonnull
                            Duration dividend,
                            @Nonnull
                            Duration divisor)

Divides the Duration by another duration.

Parameters:

dividend - The Duration to divide.

divisor - The Duration by which to divide the Duration.

Returns:

The result of dividing the dividend by the divisor.

divide

@Nonnull
public static Duration divide(@Nonnull
                                        Duration dividend,
                                        double divisor)

Divides the Duration by a constant.

Parameters:

dividend - The Duration to divide.

divisor - The constant by which to divide the Duration.

Returns:

The result of dividing the dividend by the divisor.

fromDays

@Nonnull
public static Duration fromDays(double days)

Returns a Duration that represents the specified number of days.

Parameters:

days - The number of days to be represented by the returned Duration.

Returns:

A Duration representing the specified number of days.

Throws:

ArgumentOutOfRangeException - Thrown if the result represents a value too large to be stored in a Duration.

fromDays

@Nonnull
public static Duration fromDays(double days,
                                          TimeStandard standard)

Returns a Duration that represents the specified number of days using the specified time standard.

Parameters:

days - The number of days to be represented by the returned Duration.

standard - The time standard of the new Duration.

Returns:

A Duration representing the specified number of days.

Throws:

ArgumentOutOfRangeException - Thrown if the result represents a value too large to be stored in a Duration.

fromSeconds

@Nonnull
public static Duration fromSeconds(double seconds)

Returns a Duration that represents the specified number of seconds.

Parameters:

seconds - The number of seconds to be represented by the returned Duration.

Returns:

A Duration representing the specified number of seconds.

Throws:

ArgumentOutOfRangeException - Thrown if the result represents a value too large to be stored in a Duration.

fromSeconds

@Nonnull
public static Duration fromSeconds(double seconds,
                                             TimeStandard standard)

Returns a Duration that represents the specified number of seconds using the specified time standard.

Parameters:

seconds - The number of seconds to be represented by the returned Duration.

standard - The time standard of the new Duration.

Returns:

A Duration representing the specified number of seconds.

Throws:

ArgumentOutOfRangeException - Thrown if the result represents a value too large to be stored in a Duration.

fromHours

@Nonnull
public static Duration fromHours(double hours)

Returns a Duration that represents the specified number of hours.

Parameters:

hours - The number of hours to be represented by the returned Duration.

Returns:

A Duration representing the specified number of hours.

Throws:

ArgumentOutOfRangeException - Thrown if the result represents a value too large to be stored in a Duration.

fromHours

@Nonnull
public static Duration fromHours(double hours,
                                           TimeStandard standard)

Returns a Duration that represents the specified number of hours using the specified time standard.

Parameters:

hours - The number of hours to be represented by the returned Duration.

standard - The time standard of the new Duration.

Returns:

A Duration representing the specified number of hours.

Throws:

ArgumentOutOfRangeException - Thrown if the result represents a value too large to be stored in a Duration.

fromMinutes

@Nonnull
public static Duration fromMinutes(double minutes)

Returns a Duration that represents the specified number of minutes.

Parameters:

minutes - The number of minutes to be represented by the returned Duration.

Returns:

A Duration representing the specified number of minutes.

Throws:

ArgumentOutOfRangeException - Thrown if the result represents a value too large to be stored in a Duration.

fromMinutes

@Nonnull
public static Duration fromMinutes(double minutes,
                                             TimeStandard standard)

Returns a Duration that represents the specified number of minutes using the specified time standard.

Parameters:

minutes - The number of minutes to be represented by the returned Duration.

standard - The time standard of the new Duration.

Returns:

A Duration representing the specified number of minutes.

Throws:

ArgumentOutOfRangeException - Thrown if the result represents a value too large to be stored in a Duration.