Package ch.ivyteam.ivy.scripting.objects

Class Duration

java.lang.Object
ch.ivyteam.ivy.scripting.objects.Duration
All Implemented Interfaces:
IIvyDataObject, Serializable, Cloneable, Comparable<Duration>
public final class Duration extends Object implements IIvyDataObject, Comparable<Duration>

Durations are a component of time intervals and define the amount of intervening time in a time interval. So, if you have the time interval between yesterday at noon and today 1 pm, then the corresponding duration is one day and one hour (assuming that daylight saving and timezone did not change). Durations are measured in years, months, days, hours, minutes and seconds.

This implementation uses ISO 8601 for representation which uses the format P[n]Y[n]M[n]DT[n]H[n]M[n]S to represent a duration. Every character in this string is a field descriptor or a separator:

  • P is the duration designator (historically called "period") placed at the start of the duration representation.
  • Y is the year designator that follows the value for the number of years.
  • M is the month designator that follows the value for the number of months.
  • D is the day designator that follows the value for the number of days.
  • T is the time designator that precedes the time components of the representation
  • H or h is the hour designator that follows the value for the number of hours.
  • M or m is the minute designator that follows the value for the number of minutes.
  • S or s is the second designator that follows the value for the number of seconds.

See Also:
API:
This is a public API.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Duration
    INVALID
    An invalid duration object.
    static final Duration
    UNINITIALIZED_DURATION
    An uninitialized duration object.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Duration(int _years, int _monthes, int _days, int _hours, int _minutes, int _seconds)
    Creates a new duration object.
    Duration(long sec)
    Creates a normalized duration with a given amount of seconds.
    Duration(String literal)
    Parses a Duration literal and creates a new corresponding Date object.
    Duration(String fields, int... values)
    Creates a new Duration object.

  • Method Summary

    Modifier and Type
    Method
    Description
    Duration
    add(Duration duration)
    Adds a duration to this date.
    Duration
    clone()
    Creates a clone of this object.
    int
    compareTo(Duration duration)
    Compares two durations lexicograohically.
    Duration
    divide(Number divisor)
    Divides the Duration by a divisor.
    boolean
    equals(Object duration)
    Test two objects for equality.
    int
    getDays()
    Returns the days of the duration.
    int
    getHours()
    Returns the hours of the duration.
    int
    getMinutes()
    Returns the minutes of the duration.
    int
    getMonths()
    Returns the monthes of the duration.
    int
    getSeconds()
    Returns the seconds of the duration.
    int
    getYears()
    Returns the years of the duration.
    int
    hashCode()
    A hashcode; the number of days after 1970-01-01.
    Duration
    minus(Duration duration)
    Subtracts a duration to this date.
    Duration
    multiply(Number factor)
    Multiplies the Duration with a factor.
    Duration
    normalize()
    Returns a normalized duration.
    long
    toNumber()
    Converts this Duration to a Number; this is the number of second in this duration.
    String
    toString()
    Returns the duration as String in the ISO-8601 format, see also toIsoFormat().
    Time
    toTime()
    Converts the time part (hours, minutes and seconds) of this Duration to a Time.

  • Field Details

    • UNINITIALIZED_DURATION

      public static final Duration UNINITIALIZED_DURATION
      An uninitialized duration object.
      API:
      This public API is available in Java.

    • INVALID

      public static final Duration INVALID
      An invalid duration object.
      API:
      This public API is available in Java.

  • Constructor Details

    • Duration

      public Duration(int _years, int _monthes, int _days, int _hours, int _minutes, int _seconds)
      Creates a new duration object.
      Parameters:
      _years - The years of the duration.
      _monthes - The months of the duration.
      _days - The days of the duration.
      _hours - The days of the duration.
      _minutes - The minutes of the duration.
      _seconds - The seconds of the duration.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • Duration

      public Duration(String fields, int... values)
      Creates a new Duration object.

      Example:

      • Duration("YMD", 2,5,3) creates a duration of 2 years, 5 months and 3 days.
      • Duration("DTMS", 2,5,3) creates a duration of 2 days, 5 minutes and 3 seconds.
      Parameters:
      fields - A String describing which fields are set in the following arguments. Every character in this string is a field descriptor or a separator. The following characters are allowed in this string:
      • Y For setting the years.
      • M For setting the months.
      • D For setting the days.
      • H or h For setting the hours.
      • M or m For setting the minutes.
      • S or s For setting the seconds.
      • T
        • This is a separator between the date fields and the time fields.
      The field descriptor M stands for months if it is the first occurrence of M in the argument and it stands not after the separator character T; otherwise, M stands for minutes (i.e. if it is not the first occurrence of M or it stands after the separator character T).
      values - The values of the fields. If the first argument does not contain the separator T the number of values must be equal to the number of non-separator characters in the first argument.
      Throws:
      IllegalArgumentException - if number of field descriptors (excluding T) is not equal to number of values or if an unknown field descriptor is found
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • Duration

      public Duration(String literal)
      Parses a Duration literal and creates a new corresponding Date object.
      Parameters:
      literal - A duration literal literal has the following format: P[n]Y[n]M[n]DT[n]H[n]M[n]S. Elements may be omitted if their value is zero.
      • P stands for Period
      • Y for setting the years.
      • M for setting the monthes.
      • D for setting the days.
      • T is the separator between the date fields and the time fields.
      • H or h for setting the hours.
      • M or m for setting the minutes.
      • S or s for setting the seconds.
      Throws:
      IllegalArgumentException - if the argument has an illegal format.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • Duration

      public Duration(long sec)
      Creates a normalized duration with a given amount of seconds.
      Parameters:
      sec -
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

  • Method Details

    • normalize

      public Duration normalize()
      Returns a normalized duration. A Duration is normalized, if seconds, minutes, hours and days have the same sign, the absolute values of seconds and minutes are smaller than 60 and the absolute value of hours is smaller than 24. Monthes and years are not changed.
      Returns:
      A normalized Duration.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • getYears

      public int getYears()
      Returns the years of the duration.
      Returns:
      The years of the duration.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • getMonths

      public int getMonths()
      Returns the monthes of the duration.
      Returns:
      The monthes of the duration.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • getDays

      public int getDays()
      Returns the days of the duration.
      Returns:
      The days of the duration.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • getHours

      public int getHours()
      Returns the hours of the duration.
      Returns:
      The hours of the duration.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • getMinutes

      public int getMinutes()
      Returns the minutes of the duration.
      Returns:
      The minutes of the duration.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • getSeconds

      public int getSeconds()
      Returns the seconds of the duration.
      Returns:
      The seconds of the duration.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • add

      public Duration add(Duration duration)
      Adds a duration to this date.
      Parameters:
      duration - A duration (in seconds).
      Returns:
      A new date objact translated by the duration.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • minus

      public Duration minus(Duration duration)
      Subtracts a duration to this date.
      Parameters:
      duration - A duration (in seconds).
      Returns:
      A new date objact translated by the duration.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • multiply

      public Duration multiply(Number factor)
      Multiplies the Duration with a factor.
      Parameters:
      factor -
      Returns:
      A multiple of this Duration.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • divide

      public Duration divide(Number divisor)
      Divides the Duration by a divisor.
      Parameters:
      divisor -
      Returns:
      The result of the division.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • toNumber

      public long toNumber()
      Converts this Duration to a Number; this is the number of second in this duration. A month has 30 days and a year has 365 days for this computation.
      Returns:
      Number of seconds corresponding to this duration.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • toTime

      public Time toTime()
      Converts the time part (hours, minutes and seconds) of this Duration to a Time.
      Returns:
      Time of seconds corresponding to this duration time part.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • compareTo

      public int compareTo(Duration duration)
      Compares two durations lexicograohically.
      Parameters:
      duration - Some other duration.
      Returns:
      -1 if the receiver is smaller than the argument,
      0 if the receiver is equal to the argument,
      1 if the receiver is greater than the argument.
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • toString

      public String toString()
      Returns the duration as String in the ISO-8601 format, see also toIsoFormat().
      Returns:
      the duration as String in the ISO-8601 format
      See Also:
      • toIsoFormat()
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • equals

      public boolean equals(Object duration)
      Test two objects for equality.
      Parameters:
      duration - Some object.
      Returns:
      true if the receiver is equal to the argument.
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • hashCode

      public int hashCode()
      A hashcode; the number of days after 1970-01-01.
      Returns:
      A hashcode.
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • clone

      public Duration clone()
      Creates a clone of this object.
      Specified by:
      clone in interface IIvyDataObject
      Returns:
      A shallow clone.
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.