tamaki.mes.utils.formatDuration

Description

Formats a numeric duration into an HH:MM:SS.mmm time string. The input value is interpreted using units, which accepts hours, minutes, seconds, or milliseconds (and common aliases). The conversion uses integer millisecond math to avoid floating-point rounding errors.

Returns the string "N/A" if value is None, cannot be converted to a number, or units is not recognised.

Syntax

tamaki.mes.utils.formatDuration(value, units='s', showMillis=True)

Parameters

Parameter	Type	Nullable	Description
value	Number	True	The duration to format. Returns "N/A" if None or non-numeric.
units	String	True	The units of value: hours (h, hr, hrs, hour, hours), minutes (m, min, mins, minute, minutes), seconds (s, sec, secs, second, seconds), or milliseconds (ms, msec, msecs, millisecond, milliseconds). Defaults to 's'.
showMillis	Boolean	True	Whether to include the .mmm milliseconds portion. Defaults to True.

Returns

A String formatted as HH:MM:SS.mmm (or HH:MM:SS when showMillis is False), or "N/A" for invalid input.

Code Examples

# In a binding script transform: format a millisecond duration as HH:MM:SS (no milliseconds)
return tamaki.mes.utils.formatDuration(value, 'ms', False)

# Direct calls
tamaki.mes.utils.formatDuration(3661, 's')                      # '01:01:01.000'
tamaki.mes.utils.formatDuration(90000, 'ms', showMillis=False)  # '00:01:30'