coldbox.system.async.time

Class Duration

lucee.Component
    extended by coldbox.system.async.time.Duration

A time-based amount of time, such as '34.5 seconds'. This class models a quantity or amount of time in terms of seconds and nanoseconds. It can be accessed using other duration-based units, such as minutes and hours. In addition, the DAYS unit can be used and is treated as exactly equal to 24 hours, thus ignoring daylight savings effects. See Period for the date-based equivalent to this class. Static class to map to the Java JDK Duration static class with some CF Goodness

Class Attributes:
  • synchronized : false
    •  
  • see : https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/Duration.html
    •  
  • accessors : true
    •  
  • persistent : false
    •  
    Constructor Summary
    init()
          Initialize to zero.
    Method Summary
    Duration abs()
         Returns a copy of this duration with a positive length.
    any addTo(any target, [boolean asInstant='false'])
         Adds this duration to the specified temporal object and return back to you a date/time object.
    Duration between(any start, any end)
         Obtains a Duration representing the duration between two temporal date objects.
    any compareTo(Duration otherDuration)
         Compares this duration to the specified Duration.
    Duration dividedBy(any divisor)
         Returns a copy of this duration divided by the specified value.
    any from(Duration amount)
         Obtains an instance of Duration from another duration.
    numeric get([any unit='seconds'])
         Gets the value of the requested unit in seconds by default or by nanoseconds.
    numeric getNano()
         Gets the number of nano seconds in this duration.
    any getNative()
         Get the native java class we proxy to.
    numeric getSeconds()
         Gets the number of seconds in this duration.
    array getUnits()
         Gets the set (array) of units supported by this duration.
    boolean isEquals(Duration otherDuration)
         Checks if this duration is equal to the specified Duration.
    boolean isNegative()
         Checks if the duration is negative, excluding zero.
    boolean isZero()
         Checks if the duration is zero length.
    Duration minus(any amountToSubtract, [any unit='seconds'])
         Returns a copy of this duration with the specified duration subtracted.
    Duration minusDays(any daysToSubtract)
    Duration minusHours(any hoursToSubtract)
    Duration minusMillis(any millisToSubtract)
    Duration minusMinutes(any minutesToSubtract)
    Duration minusNanos(any nanosToSubtract)
    Duration minusSeconds(any secondsToSubtract)
    Duration multipliedBy(any multiplicand)
    Duration negated()
         Returns a copy of this duration with the length negated.
    Duration of(any amount, [any unit='seconds'])
         Obtains a Duration representing an amount in the specified unit (seconds).
    Duration ofDays(any days)
         Obtains a Duration representing a number of standard 24 hour days.
    Duration ofHours(any hours)
         Obtains a Duration representing a number of standard hours.
    Duration ofMillis(any millis)
         Obtains a Duration representing a number of standard milliseconds.
    Duration ofMinutes(any minutes)
         Obtains a Duration representing a number of standard minutes.
    Duration ofNanos(any nanos)
         Obtains a Duration representing a number of standard nanoseconds.
    Duration ofSeconds(any seconds, [any nanoAdjustment])
         Obtains a Duration representing a number of seconds and/or an adjustment in nanoseconds.
    Duration parse(any text)
         Obtains a Duration from a text string such as PnDTnHnMn.
    Duration plus(any amountToAdd, [any unit='seconds'])
         Returns a copy of this duration with the specified duration added.
    Duration plusDays(any daysToAdd)
    Duration plusHours(any hoursToAdd)
    Duration plusMillis(any millisToAdd)
    Duration plusMinutes(any minutesToAdd)
    Duration plusNanos(any nanosToAdd)
    Duration plusSeconds(any secondsToAdd)
    any subtractFrom(any target, [boolean asInstant='false'])
         Subtracts this duration to the specified temporal object and return back to you a date/time object.
    numeric toDays()
         Gets the number of days in this duration.
    numeric toDaysPart()
         Extracts the number of days in the duration.
    numeric toHours()
         Gets the number of Hours in this duration.
    numeric toHoursPart()
         Extracts the number of HoursPart in this duration.
    numeric toMillis()
         Gets the number of Millis in this duration.
    numeric toMillisPart()
         Extracts the number of MillisPart in this duration.
    numeric toMinutes()
         Gets the number of Minutes in this duration.
    numeric toMinutesPart()
         Extracts the number of MinutesPart in this duration.
    numeric toNanos()
         Gets the number of Nanos in this duration.
    numeric toNanosPart()
         Extracts the number of NanosPart in this duration.
    numeric toSeconds()
         Gets the number of Seconds in this duration.
    numeric toSecondsPart()
         Extracts the number of SecondsPart in this duration.
    string toString()
         A string representation of this duration using ISO-8601 seconds based representation, such as PT8H6M12.
    any withNanos(any nanoOfSecond)
         Returns a copy of this duration with the specified nano-of-second.
    any withSeconds(any seconds)
         Returns a copy of this duration with the specified amount of seconds.
     
    Methods inherited from class lucee.Component
    None
    Constructor Detail

    init

    public init()

    Initialize to zero

    Method Detail

    abs

    public Duration abs()

    Returns a copy of this duration with a positive length.

    addTo

    public any addTo(any target, [boolean asInstant='false'])

    Adds this duration to the specified temporal object and return back to you a date/time object

    Parameters:
    target - The date/time object or string to incorporate the duration into
    asInstant - Return the result either as a date/time string or a java.time.Instant object
    Returns:
    Return the result either as a date/time string or a java.time.Instant object

    between

    public Duration between(any start, any end)

    Obtains a Duration representing the duration between two temporal date objects. This calculates the duration between two temporal objects. If the objects are of different types, then the duration is calculated based on the type of the first object. For example, if the first argument is a LocalTime then the second argument is converted to a LocalTime.

    Parameters:
    start - The start date/time object
    end - The end date/time object

    compareTo

    public any compareTo(Duration otherDuration)

    Compares this duration to the specified Duration. The comparison is based on the total length of the durations. It is "consistent with equals", as defined by Comparable.

    Parameters:
    otherDuration - the other duration to compare to
    Returns:
    -1 if the duration is less than the otherDuration, 0 if equals, and 1 if greater than

    dividedBy

    public Duration dividedBy(any divisor)

    Returns a copy of this duration divided by the specified value.

    Parameters:
    divisor - Divide by what?

    from

    public any from(Duration amount)

    Obtains an instance of Duration from another duration

    Parameters:
    amount - true

    get

    public numeric get([any unit='seconds'])

    Gets the value of the requested unit in seconds by default or by nanoseconds

    Parameters:
    unit - Seconds or nano
    Throws:
    UnsupportedTemporalTypeException This returns a value for each of the two supported units, SECONDS and NANOS. All other units throw an exception.

    getNano

    public numeric getNano()

    Gets the number of nano seconds in this duration.

    getNative

    public any getNative()

    Get the native java class we proxy to.

    Returns:
    java.time.Duration

    getSeconds

    public numeric getSeconds()

    Gets the number of seconds in this duration.

    getUnits

    public array getUnits()

    Gets the set (array) of units supported by this duration.

    isEquals

    public boolean isEquals(Duration otherDuration)

    Checks if this duration is equal to the specified Duration.

    Parameters:
    otherDuration - The duration to compare against

    isNegative

    public boolean isNegative()

    Checks if the duration is negative, excluding zero

    isZero

    public boolean isZero()

    Checks if the duration is zero length

    minus

    public Duration minus(any amountToSubtract, [any unit='seconds'])

    Returns a copy of this duration with the specified duration subtracted.

    Parameters:
    amountToSubtract - The amount to subtract
    unit - The units to use

    minusDays

    public Duration minusDays(any daysToSubtract)

    Parameters:
    daysToSubtract

    minusHours

    public Duration minusHours(any hoursToSubtract)

    Parameters:
    hoursToSubtract

    minusMillis

    public Duration minusMillis(any millisToSubtract)

    Parameters:
    millisToSubtract

    minusMinutes

    public Duration minusMinutes(any minutesToSubtract)

    Parameters:
    minutesToSubtract

    minusNanos

    public Duration minusNanos(any nanosToSubtract)

    Parameters:
    nanosToSubtract

    minusSeconds

    public Duration minusSeconds(any secondsToSubtract)

    Parameters:
    secondsToSubtract

    multipliedBy

    public Duration multipliedBy(any multiplicand)

    Parameters:
    multiplicand

    negated

    public Duration negated()

    Returns a copy of this duration with the length negated.

    of

    public Duration of(any amount, [any unit='seconds'])

    Obtains a Duration representing an amount in the specified unit (seconds)

    Parameters:
    amount - the amount of the duration, measured in terms of the unit, positive or negative
    unit - The time unit: CENTURIES,DAYS,DECADES,ERAS,FOREVER,HALF_DAYS,HOURS,MICROS,MILLENNIA,MILLIS,MINUTES,MONTHS,NANOS,SECONDS,WEEKS,YEARS

    ofDays

    public Duration ofDays(any days)

    Obtains a Duration representing a number of standard 24 hour days.

    Parameters:
    days - The number of days, positive or negative

    ofHours

    public Duration ofHours(any hours)

    Obtains a Duration representing a number of standard hours.

    Parameters:
    hours - The number of hours, positive or negative

    ofMillis

    public Duration ofMillis(any millis)

    Obtains a Duration representing a number of standard milliseconds

    Parameters:
    millis - The number of millis, positive or negative

    ofMinutes

    public Duration ofMinutes(any minutes)

    Obtains a Duration representing a number of standard minutes

    Parameters:
    minutes - The number of minutes, positive or negative

    ofNanos

    public Duration ofNanos(any nanos)

    Obtains a Duration representing a number of standard nanoseconds

    Parameters:
    nanos - The number of nanos, positive or negative

    ofSeconds

    public Duration ofSeconds(any seconds, [any nanoAdjustment])

    Obtains a Duration representing a number of seconds and/or an adjustment in nanoseconds. This method allows an arbitrary number of nanoseconds to be passed in. The factory will alter the values of the second and nanosecond in order to ensure that the stored nanosecond is in the range 0 to 999,999,999. For example, the following will result in exactly the same duration:

    Parameters:
    seconds - The number of seconds, positive or negative
    nanoAdjustment - the nanosecond adjustment to the number of seconds, positive or negative

    parse

    public Duration parse(any text)

    Obtains a Duration from a text string such as PnDTnHnMn.nS. This will parse a textual representation of a duration, including the string produced by toString(). The formats accepted are based on the ISO-8601 duration format PnDTnHnMn.nS with days considered to be exactly 24 hours. Examples: "PT20.345S" -- parses as "20.345 seconds" "PT15M" -- parses as "15 minutes" (where a minute is 60 seconds) "PT10H" -- parses as "10 hours" (where an hour is 3600 seconds) "P2D" -- parses as "2 days" (where a day is 24 hours or 86400 seconds) "P2DT3H4M" -- parses as "2 days, 3 hours and 4 minutes" "PT-6H3M" -- parses as "-6 hours and +3 minutes" "-PT6H3M" -- parses as "-6 hours and -3 minutes" "-PT-6H+3M" -- parses as "+6 hours and -3 minutes"

    Parameters:
    text - The string to parse and build up to a duration

    plus

    public Duration plus(any amountToAdd, [any unit='seconds'])

    Returns a copy of this duration with the specified duration added.

    Parameters:
    amountToAdd - The amount to add
    unit - The units to use

    plusDays

    public Duration plusDays(any daysToAdd)

    Parameters:
    daysToAdd

    plusHours

    public Duration plusHours(any hoursToAdd)

    Parameters:
    hoursToAdd

    plusMillis

    public Duration plusMillis(any millisToAdd)

    Parameters:
    millisToAdd

    plusMinutes

    public Duration plusMinutes(any minutesToAdd)

    Parameters:
    minutesToAdd

    plusNanos

    public Duration plusNanos(any nanosToAdd)

    Parameters:
    nanosToAdd

    plusSeconds

    public Duration plusSeconds(any secondsToAdd)

    Parameters:
    secondsToAdd

    subtractFrom

    public any subtractFrom(any target, [boolean asInstant='false'])

    Subtracts this duration to the specified temporal object and return back to you a date/time object

    Parameters:
    target - The date/time object or string to subtract the duration from
    asInstant - Return the result either as a date/time string or a java.time.Instant object
    Returns:
    Return the result either as a date/time string or a java.time.Instant object

    toDays

    public numeric toDays()

    Gets the number of days in this duration.

    toDaysPart

    public numeric toDaysPart()

    Extracts the number of days in the duration.

    toHours

    public numeric toHours()

    Gets the number of Hours in this duration.

    toHoursPart

    public numeric toHoursPart()

    Extracts the number of HoursPart in this duration.

    toMillis

    public numeric toMillis()

    Gets the number of Millis in this duration.

    toMillisPart

    public numeric toMillisPart()

    Extracts the number of MillisPart in this duration.

    toMinutes

    public numeric toMinutes()

    Gets the number of Minutes in this duration.

    toMinutesPart

    public numeric toMinutesPart()

    Extracts the number of MinutesPart in this duration.

    toNanos

    public numeric toNanos()

    Gets the number of Nanos in this duration.

    toNanosPart

    public numeric toNanosPart()

    Extracts the number of NanosPart in this duration.

    toSeconds

    public numeric toSeconds()

    Gets the number of Seconds in this duration.

    toSecondsPart

    public numeric toSecondsPart()

    Extracts the number of SecondsPart in this duration.

    toString

    public string toString()

    A string representation of this duration using ISO-8601 seconds based representation, such as PT8H6M12.345S.

    withNanos

    public any withNanos(any nanoOfSecond)

    Returns a copy of this duration with the specified nano-of-second. This returns a duration with the specified nano-of-second, retaining the seconds part of this duration.

    Parameters:
    nanoOfSecond - the nano-of-second to represent, from 0 to 999,999,999

    withSeconds

    public any withSeconds(any seconds)

    Returns a copy of this duration with the specified amount of seconds. This returns a duration with the specified seconds, retaining the nano-of-second part of this duration.

    Parameters:
    seconds - the seconds to represent, may be negative