Package gov.nasa.jpl.time

Class Duration

java.lang.Object
gov.nasa.jpl.time.Duration
All Implemented Interfaces:
ConvertableFromString, Comparable<Duration>
public class Duration extends Object implements Comparable<Duration>, ConvertableFromString
This class is used to represent Durations of time. It is the complement of the SPICE-backed Time class in the same package - subtracting two Times returns a Duration, for example. It keeps the same backing structure as the time class (TAI tics of 10 nanoseconds each), so doing math between them is extremely easy. It supports many math functions that planning system developers have found useful in the past, and outputs to the JPL-standard duration string format. Even though conceptually a Duration is always a positive value, this class can represent negative Durations as well, since it is a very common use case to offset Times in a negative direction.

  • Field Details

  • Constructor Details

    • Duration

      public Duration(String d)
      The main constructor everyone should be using - given a duration string, returns an equivalent Duration object
      Parameters:
      d - A string in format HH:MM:SS.ssssss (though it is pretty forgiving about not including leading or trailing zeros)

    • Duration

      public Duration()
      This is the empty Duration constructor, which will use 0 tics for the input. It is needed when you need to create Duration objects then assign them a value later (which should be a rare case).

  • Method Details

    • fromTics

      public static Duration fromTics(long tics)
      Takes in a number of tics as a long and returns a corresponding duration. IMPORTANT: only intended for fast deserialization and IO assuming one backing representation of tics and is not portable between programs due to useSpiceForMath and/or backing changes in the future

    • fromMilliseconds

      public static Duration fromMilliseconds(double ms)
      Takes in a number of milliseconds as a double and returns a corresponding duration.
      Parameters:
      ms -
      Returns:

    • fromMilliseconds

      public static Duration fromMilliseconds(long ms)
      Takes in a number of milliseconds as a long and returns a corresponding duration.
      Parameters:
      ms -
      Returns:

    • fromSeconds

      public static Duration fromSeconds(double seconds)
      Takes in a number of seconds as a double and returns a corresponding duration.
      Parameters:
      seconds -
      Returns:

    • fromSeconds

      public static Duration fromSeconds(long seconds)
      Takes in a number of seconds as a long and returns a corresponding duration.
      Parameters:
      seconds -
      Returns:

    • fromMinutes

      public static Duration fromMinutes(double minutes)
      Takes in a number of minutes as a double and returns a corresponding duration.
      Parameters:
      minutes -
      Returns:

    • fromMinutes

      public static Duration fromMinutes(long minutes)
      Takes in a number of minutes as a long and returns a corresponding duration.
      Parameters:
      minutes -
      Returns:

    • fromHours

      public static Duration fromHours(double hours)
      Takes in a number of hours as a double and returns a corresponding duration.
      Parameters:
      hours -
      Returns:

    • fromHours

      public static Duration fromHours(long hours)
      Takes in a number of hours as a long and returns a corresponding duration.
      Parameters:
      hours -
      Returns:

    • fromDays

      public static Duration fromDays(double days)
      Takes in a number of days as a double and returns a corresponding duration.
      Parameters:
      days -
      Returns:

    • fromDays

      public static Duration fromDays(long days)
      Takes in a number of days as a long and returns a corresponding duration.
      Parameters:
      days -
      Returns:

    • fromMarsDur

      public static Duration fromMarsDur(String marsDurString)
      Takes in a Mars duration string of the form ddddMhh:mm:ss.fff or Mhh:mm:ss.fff where dddd is the sol number, hh is the hour, mm is the minutes, and ss.fff is the seconds.
      Parameters:
      marsDurString -
      Returns:

    • fromMatcher

      public static Duration fromMatcher(Matcher parsedDuration)
      Takes a Matcher object and returns a Duration object. IMPORTANT: assumes that find() has already been called, the matcher is queued with the groups to parse, and higher-level nice error messages are available to tell the user why the call failed/will fail. This is for performance reasons - if the calling program is doing its own input validation, you don't want to do it twice

    • getTics

      public long getTics()
      Returns:
      A long, the underlying number of tics that comprise the duration

    • getMicroseconds

      public long getMicroseconds()
      Returns:
      A long, the number of microseconds in the duration. Truncates instead of rounding

    • getMilliseconds

      public long getMilliseconds()
      Returns:
      A long, the number of milliseconds in the duration. Truncates instead of rounding

    • totalSeconds

      public double totalSeconds()
      this one is special because it is a float
      Returns:
      A float representing the fractional seconds in the span of time. Does not round or truncate

    • getSeconds

      public long getSeconds()
      Returns:
      A long, the number of seconds in the duration. Truncates instead of rounding

    • getMinutes

      public long getMinutes()
      Returns:
      A long, the number of minutes in the duration. Truncates instead of rounding

    • getHours

      public long getHours()
      Returns:
      A long, the number of hours in the duration. Truncates instead of rounding

    • getDays

      public long getDays()
      Returns:
      A long, the number of days in the duration. Truncates instead of rounding

    • add

      public Duration add(Duration d2)
      Adds the parameter duration to the calling object.
      Parameters:
      d2 -
      Returns:
      A new Duration object

    • plus

      public Duration plus(Duration d2)
      Syntactic sugar that calls add()
      Parameters:
      d2 -
      Returns:
      A new Duration object

    • plus

      public Time plus(Time t2)
      Allows you to do t2 = d.plus(t1), which could be useful for operator overloading
      Parameters:
      t2 - A time you want to add to
      Returns:
      A new Time object

    • subtract

      public Duration subtract(Duration d2)
      Subtracts the parameter duration from the calling object
      Parameters:
      d2 -
      Returns:
      A new Duration object

    • minus

      public Duration minus(Duration d2)
      Syntactic sugar that calls subtract()
      Parameters:
      d2 -
      Returns:
      A new Duration object

    • multiply

      public Duration multiply(double multiplyBy)
      Multiplies the duration by the input double value. Rounds to the nearest microsecond or double floating point precision, whichever is larger.
      Parameters:
      multiplyBy -
      Returns:
      A new Duration object

    • multiply

      public Duration multiply(long multiplyBy)
      Multiplies the duration by the input long value.
      Parameters:
      multiplyBy -
      Returns:
      A new Duration object

    • multiply

      public Duration multiply(int multiplyBy)
      Multiplies the duration by the input int value.
      Parameters:
      multiplyBy -
      Returns:
      A new Duration object

    • divide

      public Duration divide(double divideBy)
      Divides the duration tics by the input double value and returns a duration. Rounds to the nearest microsecond or double floating point precision, whichever is larger.
      Parameters:
      divideBy -
      Returns:
      A new Duration object

    • div

      public Duration div(double divideBy)
      Syntactic sugar that calls divide(double)
      Parameters:
      divideBy -
      Returns:
      A new Duration object

    • divide

      public Duration divide(long divideBy)
      Divides the duration tics (floating point division) by the input long value and returns a duration. Rounds to the nearest microsecond or double floating point precision, whichever is larger.
      Parameters:
      divideBy -
      Returns:
      A new Duration object

    • div

      public Duration div(long divideBy)
      Syntactic sugar that calls divide(long)
      Parameters:
      divideBy -
      Returns:
      A new Duration object

    • divide

      public Duration divide(int divideBy)
      Divides the duration tics (floating point division) by the input int value and returns a duration. Rounds to the nearest microsecond or double floating point precision, whichever is larger.
      Parameters:
      divideBy -
      Returns:
      A new Duration object

    • div

      public Duration div(int divideBy)
      Syntactic sugar that calls divide(int)
      Parameters:
      divideBy -
      Returns:
      A new Duration object

    • divide

      public double divide(Duration divideByDuration)
      Divides the duration by an input duration and returns a double value.
      Parameters:
      divideByDuration -
      Returns:
      double containing ratio of two Durations

    • div

      public double div(Duration divideBy)
      Syntactic sugar that calls divide(Duration)
      Parameters:
      divideBy -
      Returns:
      double containing ratio of two Durations

    • mod

      public Duration mod(Duration modulus)
      Modulus operator, also known as remainder. Follows Java's built in % operator in terms of behavior with negative values
      Parameters:
      modulus -
      Returns:
      The calling duration mod the input parameter

    • abs

      public Duration abs()
      Returns the absolute value of the duration. i.e. -10:00:00 will become 10:00:00.
      Returns:

    • round

      public Duration round(Duration resolution)
      Rounds the duration to an input resolution.
      Parameters:
      resolution -
      Returns:

    • ceil

      public Duration ceil(Duration resolution)
      Rounds the duration up to an input resolution.
      Parameters:
      resolution -
      Returns:

    • floor

      public Duration floor(Duration resolution)
      Rounds the duration down to an input resolution.
      Parameters:
      resolution -
      Returns:

    • lessThan

      public boolean lessThan(Duration t2)
      Returns true if the calling object is less than (closer to negative infinity) the parameter, false otherwise
      Parameters:
      t2 -
      Returns:
      a boolean

    • greaterThan

      public boolean greaterThan(Duration t2)
      Returns true if the calling object is greater than (closer to positive infinity) the parameter, false otherwise
      Parameters:
      t2 -
      Returns:

    • lessThanOrEqualTo

      public boolean lessThanOrEqualTo(Duration t2)
      Returns true if the calling object is less than or equal to the parameter, false otherwise
      Parameters:
      t2 -
      Returns:
      a boolean

    • greaterThanOrEqualTo

      public boolean greaterThanOrEqualTo(Duration t2)
      Returns true if the calling object is greater than or equal to the parameter, false otherwise
      Parameters:
      t2 -
      Returns:
      a boolean

    • equalToWithin

      public boolean equalToWithin(Duration d2, Duration resolution)
      Compares the duration to another duration object and returns true if d2 is within an input resolution of d1.
      Parameters:
      d2 -
      resolution -
      Returns:

    • min

      public static Duration min(Duration... durs)
      Returns the smallest of a list of Durations. Wraps Collections.min()
      Parameters:
      durs - Duration objects
      Returns:
      A Duration object

    • max

      public static Duration max(Duration... durs)
      Returns the largest of a list of Durations. Wraps Collections.max()
      Parameters:
      durs - Duration objects
      Returns:
      A duration object

    • toString

      public String toString()
      Calls toString() with default precision
      Overrides:
      toString in class Object
      Returns:
      The default String representation of the object

    • toString

      public String toString(int numDecimalPlaces)
      Returns string representation to number of decimal places specified
      Parameters:
      numDecimalPlaces - The number of places to print subseconds to
      Returns:
      A string representation of the duration

    • toMarsDurString

      public String toMarsDurString(int numberDecimalDigits)
      Returns a string representing the duration as a mars duration.
      Parameters:
      numberDecimalDigits -
      Returns:

    • toMarsDurString

      public String toMarsDurString()
      Returns a string representing the duration as a mars duration, using the default decimal precision.
      Returns:

    • format

      public String format(String format)
      Returns string that is the underlying duration formatted according to the format string The format string is defined by the apache commons DurationFormatUtils specification It only returns down to millisecond accuracy, so it cannot be used for fine precision
      Parameters:
      format - Format string, an example of which would be "d 'days' HH 'hours' mm 'minutes' ss 'seconds and' S 'milliseconds'"

    • valueOf

      public void valueOf(String s)
      Given a Duration string, mutates the calling object to represent that duration Implements the convertableFromString interface so engines can call valueOf on whatever object including Durations.
      Specified by:
      valueOf in interface ConvertableFromString
      Parameters:
      s -

    • compareTo

      public int compareTo(Duration t2)
      Specified by:
      compareTo in interface Comparable<Duration>

    • equals

      public boolean equals(Object t2)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • setDefaultOutputPrecision

      public static void setDefaultOutputPrecision(int defaultOutputPrecision)
      Sets the default output decimal precision.
      Parameters:
      defaultOutputPrecision -

    • getDefaultOutputPrecision

      public static int getDefaultOutputPrecision()
      Returns the current default output decimal precision.
      Returns: