Interval

Available since: v4.0.0

This page contains built-in functions for working with interval values. An interval holds three separate parts: whole months, whole days, and a time part in microseconds. The functions below build an interval, read its parts, and move amounts between the parts.

Interval functions

interval::make

The interval::make function builds an interval from years, months, weeks, days, hours, minutes and seconds. Every argument is optional and defaults to 0.

interval::make(option<number>, option<number>, option<number>, option<number>, option<number>, option<number>, option<number>) -> interval

The arguments, in order, are years, months, weeks, days, hours, minutes and seconds. Years and months make up the months part, weeks and days make up the days part, and hours, minutes and seconds make up the time part.

interval::make(1, 2, 1, 3, 4, 5, 6.5);

interval'P1Y2M10DT4H5M6.5S'

Years, months, weeks and days must be whole numbers. Hours, minutes and seconds can have a fraction, which is rounded to the nearest microsecond.

interval::make(0, 0, 0, 0, 1.5);
//- interval'PT1H30M'

interval::make(0.5);
//- 'Incorrect arguments for function interval::make(). The years must be an integer.'

To build an interval with a fraction of a day, give the time as hours instead, as in interval::make(0, 0, 0, 1, 12) for one and a half days.

interval::years

The interval::years function returns the number of whole years in the months part of an interval.

interval::years(interval) -> int

The following example shows this function, and its output:

interval::years(interval'3 years 14 mons');

4

interval::months

The interval::months function returns the months in the months part of an interval that are left over after the whole years, from 0 to 11 for a positive interval.

interval::months(interval) -> int

The following example shows this function, and its output:

interval::months(interval'3 years 14 mons');

2

interval::days

The interval::days function returns the days part of an interval. The days part is separate from the months part, so a month is not counted as days.

interval::days(interval) -> int

The following example shows this function, and its output:

interval::days(interval'1 mon 5 days');

5

interval::hours

The interval::hours function returns the number of whole hours in the time part of an interval. The time part is not limited to 24 hours.

interval::hours(interval) -> int

The following example shows this function, and its output:

interval::hours(interval'50:30:15.5');

50

interval::mins

The interval::mins function returns the minutes in the time part of an interval that are left over after the whole hours.

interval::mins(interval) -> int

The following example shows this function, and its output:

interval::mins(interval'50:30:15.5');

30

interval::secs

The interval::secs function returns the seconds in the time part of an interval that are left over after the whole minutes, as a decimal that keeps the fraction of a second.

interval::secs(interval) -> decimal

The following example shows this function, and its output:

interval::secs(interval'50:30:15.5');

15.5dec

interval::micros

The interval::micros function returns the seconds in the time part of an interval that are left over after the whole minutes, in microseconds.

interval::micros(interval) -> int

The following example shows this function, and its output:

interval::micros(interval'50:30:15.5');

15500000

interval::justify_hours

The interval::justify_hours function moves each whole 24 hours of the time part into the days part.

interval::justify_hours(interval) -> interval

The following example shows this function, and its output:

interval::justify_hours(interval'1 day 50:00:00');

interval'P3DT2H'

interval::justify_days

The interval::justify_days function moves each whole 30 days of the days part into the months part.

interval::justify_days(interval) -> interval

The following example shows this function, and its output:

interval::justify_days(interval'45 days 02:00:00');

interval'P1M15DT2H'

interval::justify_interval

The interval::justify_interval function applies interval::justify_hours and then interval::justify_days, and then makes the signs of the parts agree, so that an interval does not mix a positive part with a negative one.

interval::justify_interval(interval) -> interval

The following example shows this function, and its output:

interval::justify_interval(interval'45 days 50:00:00');
//- interval'P1M17DT2H'

interval::justify_interval(interval'1 mon -1 day');
//- interval'P29D'

interval::justify_interval(interval'1 day -02:00:00');
//- interval'PT22H'

The justified interval is equal to the original under the interval comparison, which already counts a month as 30 days and a day as 24 hours. It changes how the interval is stored and displayed, and how it behaves in date arithmetic, where one month and 30 days give different results.

Method chaining

Method chaining allows functions to be called using the . dot operator on a value of a certain type instead of the full path of the function followed by the value.

-- Traditional syntax
interval::justify_hours(interval'1 day 50:00:00');

-- Method chaining syntax
interval'1 day 50:00:00'.justify_hours();

interval'P3DT2H'

The method form is available for every function on this page except interval::make, which does not take an interval.