Interval-Type Attributes

Interval

The attribute type, Interval, represents time intervals and durations. The general designed/expected usage is for durations shorter than an hour, but intervals of hours or even days are possible—see below.

Reflecting the basic expectation, the default value is a string "00:00" representing zero minutes and zero seconds. For example, the interval value

01:30

represents one minute and thirty seconds whilst

02:01:00

represents two hours, one minute and zero seconds. Note the need to include the seconds element (in both input and output) to differentiate the NN:NN form as mm:ss and not hh:mm.

Creating Interval-type data

This is achieved using the interval() operator. The input is a string (see interval(dataStr)). Note that minute and second values do not need zero-padding, inputting "4:2" results in a displayed/exported value of "04:02".

If a time element is supplied is larger than its normal count (e.g. more than 59 minutes or seconds, the input is re-parsed into normally sized units. So "90:70" mm:ss will get parsed as "01:31:10". This effect is useful if creating inputs from dynamic values and avoids the need to re-parse number before input. This applies to hours, minute and seconds inputs.

When reading/copying Interval type data, it is always in String form, i.e. "22:09", even though the Interval data is stored internally (in the running app) in a different form. As a result, an Interval can be passed directly to a string attribute without needing modification. So, adding an interval to a string:

"The answer is:" + $MyInterval returns a string.

Creating an Interval from Dates

A variant of interval() enables returning the time between two Date-type objects as an Interval: see interval(startDate,endDate).

Using intervals of an hour or more

Although originally intended for short (sub 1 hour) durations, Intervals can accept hour or day inputs. For long intervals note that hours and days are accepted units: year or month scope inputs are not understood by the interval parser.

Thus the duration

01:01:00

represents a duration of one hour, one minute, and thirty seconds. The seconds cannot be omitted, even if '00' as the above written as "01:01" would be parsed as one minute and one second. Only "01:01:00" ensures the hour element is detected correctly.

Days are defined using the word 'day(s)':

2 days 01:00:00 represents 49 hours

Duration components larger than a day (of 24 hours), e.g. months or years, are not supported, though is is possible to use large day values:

62 days 01:30:10

representing an interval of over two months' duration. The maximum length of an interval but it is not advised to exceed 1 year (but specified in days, i.e. 365 days) but ideally intervals are used for a few days or less. If the duration of the interval is desired in whole days only, use normal Date-type arithmetic and store the duration as a Number-type.

Formatting Interval data

Using, Interval.format() only accepts a limited range—two choices—of formatting string options, i.e. not the full range of Date formats. The displayed format of Intervals, in Displayed Attributes and Get Info cannot be modified. If passing the data for use elsewhere, e.g. for export, the string representation can be modified using normal String manipulation operators.

Negative values

An interval may have negative duration, "-05:30":

-05:30

represents a negative duration of 5 minutes and 30 seconds. This can be useful when doing short duration date arithmetic (as below).

Use in Date arithmetic

Intervals may be added or subtracted from Date-type attributes or variables. They may multiplied or divided by constants or numeric attributes, and may be compared for equality using == and != or for magnitude using < and >.

For directly altering a Date's time element, the time() operator is normally a simpler and more convenient choice.

Note: subtracting two dates does not currently return an interval; rather, it returns the number of days between the two dates in accordance with pre-existing Date-type attribute behaviour. To get the interval between two Dates, use the interval(startDate,endDate) operator syntax. Thus to get the interval between the $StartDate of note "Session 1' and $StarDate of "Session 2":

$MyInterval = interval($StartDate("Session 1"),$StartDate("Session 2"));

Intervals can be added to/subtracted from Dates. If $MyInterval is "-05:30" and $MyDate is 24/10/2022 12:00:00 (midday on 24 October 2022):

$MyDate = $MyDate + $MyInterval;

results in $MyDate being 24/10/2022 11:54:30. By accepting negative intervals the same action code can deal with positive and negative durations. So to find the number of (whole) minutes in the interval:

$MyNumberOfMinutes = minutes($MyDate,$MyDate+$MyInterval);

A more generalised approach to the last:

$MyNumberOfMinutes = minutes(date("now"),date("now")+$MyInterval);

Here minutes are tested but the method could test days, hours or seconds (not bigger units as Interval data is usually a few days at biggest and generally less than a whole day).

Alternative syntax

Some alternative syntax is supported, including an 'h' suffix/separator for hours and 'd' for days. Thus the duration

1h30

represents one hour and thirty minutes, whilst:

1 day 01:00:00 represents 25 hours

2d2h30 represents two days, two hours and 30 minutes

whilst:

2d5

is treated as 2 days, 5 hours, as hours is the next smaller duration measure than days.

The 'd' marker is always resaved/displayed as 'day(s)':

2d5 is resaved as "2 days 05:00:00

1d5 is resaved as "1 day 05:00:00

Note that whilst 'm' and 's' suffixes are understood for minutes and seconds; the 's' is superfluous anyway as it is always the last segment if used. If a duration is entered as "3m20" Tinderbox will re-save the value in the default format of "03:20" so use of 'm' is deprecated. Thus a duration entered as follows will be understood:

1h30m10s

but it is treated as one hour, thirty minutes and 10 seconds but will be re-saved as:

1:30:10

Note slight variations in accepted abbreviations compared to pre-existing Date-type attribute date arithmetic usage.

Use of floating point (decimal) numbers

Assigning a floating point (i.e. 'decimal') number to an interval is supported, and interpreted as a number in seconds; the numbers after the decimal point are discarded—no rounding up/down occurs. This can be useful as time codes, e.g. as in offsets within audio or video files, may be given with a decimal element: '45.3' vs. '45'. Thus:

$MyInterval = 5406;

gives in interval of "01:30:06". Note however that

$MyInterval = 5406.8;

gives the same result of "01:30:06". The '0.8' of a second in the input value does not cause the seconds element of the interval to round up to ':07'. This latter is the equivalent of a floor() operation where a decimal number is always rounds down the the existing whole integer:

$MyInterval = floor(5406.8); (returns integer '5406')

Default/Empty value

The string "00:00" (zero hours:minutes).

Sorting order

Increasing duration, so unset ("00:00") values list first.

Coercing interval data

Interval-type System attributes

Built-in attributes of the file data type are listed below:

$MyInterval

See also—notes linking to here: