com.agi.moxie.api.time

Class Duration

java.lang.Object

com.agi.moxie.api.time.Duration

All Implemented Interfaces:

Comparable<Duration>

public final class Duration
extends Object
implements Comparable<Duration>

Represents a span of time.

This class offers the same precision as the JulianTime 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(int days, double seconds) 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.

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	fromHours(double hours) Returns a Duration that represents the specified number of hours.
static Duration	fromMinutes(double minutes) Returns a Duration that represents the specified number of minutes.
static Duration	fromSeconds(double seconds) Returns a Duration that represents the specified number of seconds.
int	getDayCount() 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	getSecondsOfDay() Gets the seconds component of this Duration.
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	toJavaDuration() 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. This is equivalent to getZero().

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:

IllegalArgumentException - 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:

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

Duration

public Duration(@NotNull
                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.

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

@NotNull
public static Duration getMaxValue()

Gets the largest possible value of a Duration.

The value is Integer.MAX_VALUE days and 86399.0 seconds.

Returns:

The largest possible value for a duration.

getMinValue

@NotNull
public static Duration getMinValue()

Gets the smallest possible value of a Duration.

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

Returns:

The smallest possible value for a duration (including negative values).

getZero

@NotNull
public static Duration getZero()

Gets a Duration of 0 days and seconds.

Returns:

The value for a singular instant of time.

getDayCount

public final int getDayCount()

Gets the day component of this Duration.

Returns:

The whole number of days represented by this duration.

getSecondsOfDay

public final double getSecondsOfDay()

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.

Returns:

The whole and fractional seconds represented in addition to the getDayCount().

getTotalDays

public final double getTotalDays()

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

Returns:

The total value of this duration in units of days.

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.

Returns:

The total value of this duration in units of seconds.

toJavaDuration

@NotNull
public final Duration toJavaDuration()

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.

equalsType

public final boolean equalsType(@NotNull
                                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) properties must be identical 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:

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) 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.

equalsEpsilon

public final boolean equalsEpsilon(@NotNull
                                   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.

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(@NotNull
                           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, in the same sense as Comparable.compareTo(Object)

add

@NotNull
public final Duration add(@NotNull
                                    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 IllegalArgumentException.

Parameters:

other - The Duration to add to this instance.

Returns:

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

subtract

@NotNull
public final Duration subtract(@NotNull
                                         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 IllegalArgumentException.

Parameters:

other - The Duration to subtract from this instance.

Returns:

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

multiply

@NotNull
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:

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

divide

public final double divide(@NotNull
                           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

@NotNull
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:

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

addSeconds

@NotNull
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:

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

addDays

@NotNull
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:

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

equals

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

Returns true if two Durations are exactly equal, within the limits of floating point precision. To be considered equal, the Days (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(@NotNull
                                Duration left,
                                @NotNull
                                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) 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(@NotNull
                               Duration left,
                               @NotNull
                               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(@NotNull
                                  Duration left,
                                  @NotNull
                                  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(@NotNull
                                      Duration left,
                                      @NotNull
                                      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(@NotNull
                                         Duration left,
                                         @NotNull
                                         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

@NotNull
public static Duration add(@NotNull
                                     Duration left,
                                     @NotNull
                                     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

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

Subtracts a specified Duration from another specified Duration.

Parameters:

left - The subtrahend.

right - The minuend.

Returns:

The difference left minus right.

negate

@NotNull
public static Duration negate(@NotNull
                                        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

@NotNull
public static Duration multiply(@NotNull
                                          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(@NotNull
                            Duration dividend,
                            @NotNull
                            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

@NotNull
public static Duration divide(@NotNull
                                        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

@NotNull
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:

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

fromSeconds

@NotNull
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:

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

fromHours

@NotNull
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:

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

fromMinutes

@NotNull
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:

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