Tinderbox v10 Icon

Interval.format(formatStr)


Operator Type: 

Operator Scope of Action: 

Operator Purpose: 

Data Type Returned: 

Operator First Added: 

Operator in Current Baseline: 

Operator Last Altered: 

 Function  [other Function type actions]

 Item  [operators of similar scope]

 Formatting  [other Formatting operators]

 String [about String data type]

 v6.6.0

 Baseline

 As at baseline


Interval.format(formatStr)

For this data type formatStr strings can use date-type format strings. The function returns Interval as a String formatted as per the quoted date/interval format string formatStr.

This supplements the existing format() function.

When used with Interval-type data, .format() expects the interval to be less than one hour and thus comprising only minutes and seconds data (i.e. 'mm:ss'). Note that the default short Interval form is 'hh:mm' so there is scope for confusion. If passing 'hh:mm' data to .format(), it makes sense to add a blank seconds segment, i.e. 'hh:mm:ss' so the segments of the interval are parsed correctly.

Furthermore, only two date format strings are accepted for formatStr: Interval.format ("l") and Interval.format ("L"), both of which format the hours and minutes of the Interval date the current locale's style. The lower-case "l" format uses the locale's abbreviated form, while "L" gives the interval in a phrase customised to local usage.

If $MyInterval is "12:55:23:"

$MyString = $MyInterval.format("l"); gives "12:55"

$MyString = $MyInterval.format("L"); gives "12 hours, 55 minutes"

An Interval value of "00:00" (minutes:seconds)—i.e. that data type's default—always returns an empty string. This if $MyInterval the default 00:00 then:

$MyString = $MyInterval.format("l"); 

results in "", i.e. no value is set in $MyString.

Formatting Intervals of over one hour

The expectation of input as being only mm:ss only can cause confusion when using .format(). If the value of $MyInterval is "12:55:40" (12 hours, 55 minutes and 14 seconds):

$MyString = $MyInterval.format("l") 

The resulting $MyString value is "12:56", i.e. the seconds are rounded (up or down accordingly) and an hours:minutes string is returned.

As Interval maximum scope is days/hours/minutes/seconds, if the aim is to get the entire interval duration, simply pass the Interval data direct to a string. This if $MyInterval is "1 day 12:55:23":

$MyString = $MyInterval; 

sets $MyString to "1 day 12:55:23". If only part of the source is needed, a different approach is needed. Thus, if $MyInterval is "1 day 12:55:23" and only the number of whole minutes is needed, some string manipulation is required:

$MyString = $MyInterval.extract("(\d{2}):\d{2}$"); 

setting $MyString to "55". Note that regular expressions are very specific. If the closing '$' is omitted from the regex pattern, this results in a $MyString value of "12" instead of "55". Why? Because the latter pattern returns the first pair of digits followed explicitly by a colon and two more digits. Adding the '$' tells the regex that the literal sequence must come at the end of the source string, resulting in "55" being extracted.


See also—notes linking to here: