Interval
A new attribute type, Interval, represents time intervals and durations. The default value is a string "00:00" representing zero minutes and zero seconds. Longer durations, of over one hour are supported—see below—but the general designed/expected usage is for durations shorter than an hour. For example, the interval value
01:30
represents one minute and thirty seconds. Note that minute and second values do not need zero-padding, entering "4:2" results in a displayed value of "04:02"
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.
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 attributes. They may multiplied or divided by constants or numeric attributes, and may be compared for equality using == and != or for magnitude using < and >.
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() operator (which returns Interval-type data). 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 us 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
From v9.5.0, 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: