wirebox.system.async.time

Class Period

lucee.Component
    extended by wirebox.system.async.time.Period

A date-based amount of time in the ISO-8601 calendar system, such as '2 years, 3 months and 4 days'. This class models a quantity or amount of time in terms of years, months and days. See Duration for the time-based equivalent to this class. Durations and periods differ in their treatment of daylight savings time when added to ZonedDateTime. A Duration will add an exact number of seconds, thus a duration of one day is always exactly 24 hours. By contrast, a Period will add a conceptual day, trying to maintain the local time. For example, consider adding a period of one day and a duration of one day to 18:00 on the evening before a daylight savings gap. The Period will add the conceptual day and result in a ZonedDateTime at 18:00 the following day. By contrast, the Duration will add exactly 24 hours, resulting in a ZonedDateTime at 19:00 the following day (assuming a one hour DST gap).

Class Attributes:
  • synchronized : false
    •  
  • see : https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/Period.html
    •  
  • accessors : true
    •  
  • persistent : false
    •  
    Constructor Summary
    init([any years='0'], [any months='0'], [any days='0'])
          Initialize to zero date base period.
    Method Summary
    any addTo(any target, [boolean asNative='false'])
         Adds this period to the specified temporal object and return back to you a date/time object.
    Period between(any start, any end)
         Obtains a Duration representing the duration between two temporal date objects.
    any from(Period amount)
         Obtains an instance of Period from another period.
    numeric get([any unit='days'])
         Gets the value of the requested unit in seconds by default (days) or years, months, days.
    any getChronology()
         Gets the chronology of this period, which is the ISO calendar system.
    numeric getDays()
         Gets the number of Days in this period.
    numeric getMonths()
         Gets the number of Months in this period.
    any getNative()
         Get the native java class we proxy to.
    array getUnits()
         Gets the set (array) of units supported by this period.
    numeric getYears()
         Gets the number of Years in this period.
    boolean isEquals(Period otherPeriod)
         Checks if this period is equal to the specified period.
    boolean isNegative()
         Checks if the period is negative, excluding zero.
    boolean isZero()
         Checks if the period is zero length.
    Period minus(Period amountToSubtract)
         Returns a copy of this period with the specified period subtracted.
    Period minusDays(any daysToSubtract)
    Period minusMonths(any monthsToSubtract)
    Period minusYears(any yearsToSubtract)
    Period multipliedBy(any scalar)
    Period negated()
         Returns a copy of this duration with the length negated.
    Period normalized()
         Returns a copy of this period with the years and months normalized.
    Period of([any years='0'], [any months='0'], [any days='0'])
         Obtains a Period representing an amount in the specified arguments.
    Period ofDays(any days)
         Obtains a Period representing a number of days.
    Period ofMonths(any months)
         Obtains a Period representing a number of months.
    Period ofWeeks(any weeks)
         Obtains a Period representing a number of weeks.
    Period ofYears(any years)
         Obtains a Period representing a number of years.
    Period parse(any text)
         Obtains a Period from a text string such as PnYnMnD.
    Period plus(Period amountToAdd)
         Returns a copy of this period with the specified period added.
    Period plusDays(any daysToAdd)
    Period plusMonths(any monthsToAdd)
    Period plusYears(any yearsToAdd)
    any subtractFrom(any target, [boolean asNative='false'])
         Subtracts this period to the specified temporal object and return back to you a date/time object or a Java LocalDate object.
    string toString()
         Outputs this period as a String, such as P6Y3M1D.
    numeric toTotalMonths()
         Gets the total number of months in this period.
    any withDays(any days)
         Returns a copy of this period with the specified amount of days.
    any withMonths(any months)
         Returns a copy of this period with the specified amount of months.
    any withYears(any years)
         Returns a copy of this period with the specified amount of years.
     
    Methods inherited from class lucee.Component
    None
    Constructor Detail

    init

    public init([any years='0'], [any months='0'], [any days='0'])

    Initialize to zero date base period

    Parameters:
    years - The years
    months - The months
    days - The days
    Method Detail

    addTo

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

    Adds this period 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 period into
    asNative - If true, we will give you the java.time.LocalDate object, else a ColdFusion date/time string
    Returns:
    The date/time object with the period added to it or a java LocalDate

    between

    public Period 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

    from

    public any from(Period amount)

    Obtains an instance of Period from another period

    Parameters:
    amount - The period

    get

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

    Gets the value of the requested unit in seconds by default (days) or years, months, days

    Parameters:
    unit - years, months, days
    Throws:
    UnsupportedTemporalTypeException All other units throw an exception.

    getChronology

    public any getChronology()

    Gets the chronology of this period, which is the ISO calendar system.

    Returns:
    java.time.chrono.IsoChronology

    getDays

    public numeric getDays()

    Gets the number of Days in this period.

    getMonths

    public numeric getMonths()

    Gets the number of Months in this period.

    getNative

    public any getNative()

    Get the native java class we proxy to.

    Returns:
    java.time.Period

    getUnits

    public array getUnits()

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

    getYears

    public numeric getYears()

    Gets the number of Years in this period.

    isEquals

    public boolean isEquals(Period otherPeriod)

    Checks if this period is equal to the specified period.

    Parameters:
    otherPeriod - The period to compare against

    isNegative

    public boolean isNegative()

    Checks if the period is negative, excluding zero

    isZero

    public boolean isZero()

    Checks if the period is zero length

    minus

    public Period minus(Period amountToSubtract)

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

    Parameters:
    amountToSubtract - The period to subtract

    minusDays

    public Period minusDays(any daysToSubtract)

    Parameters:
    daysToSubtract

    minusMonths

    public Period minusMonths(any monthsToSubtract)

    Parameters:
    monthsToSubtract

    minusYears

    public Period minusYears(any yearsToSubtract)

    Parameters:
    yearsToSubtract

    multipliedBy

    public Period multipliedBy(any scalar)

    Parameters:
    scalar

    negated

    public Period negated()

    Returns a copy of this duration with the length negated.

    normalized

    public Period normalized()

    Returns a copy of this period with the years and months normalized.

    of

    public Period of([any years='0'], [any months='0'], [any days='0'])

    Obtains a Period representing an amount in the specified arguments

    Parameters:
    years - The years
    months - The months
    days - The days

    ofDays

    public Period ofDays(any days)

    Obtains a Period representing a number of days.

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

    ofMonths

    public Period ofMonths(any months)

    Obtains a Period representing a number of months.

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

    ofWeeks

    public Period ofWeeks(any weeks)

    Obtains a Period representing a number of weeks.

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

    ofYears

    public Period ofYears(any years)

    Obtains a Period representing a number of years.

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

    parse

    public Period parse(any text)

    Obtains a Period from a text string such as PnYnMnD. This will parse the string produced by toString() which is based on the ISO-8601 period formats PnYnMnD and PnW. Examples: "P2Y" -- Period.ofYears(2) "P3M" -- Period.ofMonths(3) "P4W" -- Period.ofWeeks(4) "P5D" -- Period.ofDays(5) "P1Y2M3D" -- Period.of(1, 2, 3) "P1Y2M3W4D" -- Period.of(1, 2, 25) "P-1Y2M" -- Period.of(-1, 2, 0) "-P1Y2M" -- Period.of(-1, -2, 0)

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

    plus

    public Period plus(Period amountToAdd)

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

    Parameters:
    amountToAdd - The period to Add

    plusDays

    public Period plusDays(any daysToAdd)

    Parameters:
    daysToAdd

    plusMonths

    public Period plusMonths(any monthsToAdd)

    Parameters:
    monthsToAdd

    plusYears

    public Period plusYears(any yearsToAdd)

    Parameters:
    yearsToAdd

    subtractFrom

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

    Subtracts this period to the specified temporal object and return back to you a date/time object or a Java LocalDate object

    Parameters:
    target - The date/time object or string to incorporate the period into
    asNative - If true, we will give you the java.time.LocalDate object, else a ColdFusion date/time string
    Returns:
    Return the result either as a date/time string or a java.time.LocalDate object

    toString

    public string toString()

    Outputs this period as a String, such as P6Y3M1D.

    toTotalMonths

    public numeric toTotalMonths()

    Gets the total number of months in this period.

    withDays

    public any withDays(any days)

    Returns a copy of this period with the specified amount of days.

    Parameters:
    days - The days

    withMonths

    public any withMonths(any months)

    Returns a copy of this period with the specified amount of months.

    Parameters:
    months - The months

    withYears

    public any withYears(any years)

    Returns a copy of this period with the specified amount of years.

    Parameters:
    years - The years