duration

Displays the given millisecond value in human-readable time. For example, the value of 604800000 (7 days) is displayed as 7 Days.

A month is treated as 30 days and a year as 365 days.

The unit names are English and the plural is an s, which is a rule only English follows. To write a duration in another language, take it apart with durationParts and hand the pieces to a formatter that knows the language.

Parameters

Name	Type	Required	Default
milliseconds	numbernumfloat	●	–
The duration to format, in milliseconds.
optionsnamedkeyword	DurationOptions	–	–
Formatting options. See the table below.

namedThese parameters are passed as named parameters.

keywordThese parameters are passed as keyword arguments, or as a single dict in their place.

DurationOptions

Name	Type	Required	Default
useShortString	booleanbool	–	falseFalse
Use short unit labels: Years→Y, Months→Mo, Days→D, Hours→H, Minutes→M, Seconds→S, Milliseconds→ms. (Months uses Mo so it does not clash with Minutes (M).)
useSpace	booleanbool	–	trueTrue
Put a space between the value and its unit (e.g. 1Days → 1 Days).
withZeroValue	booleanbool	–	falseFalse
Include zero-valued units below the largest unit (e.g. 1 Day 0 Hours 0 Minutes 0 Seconds).
separator	stringStringstr	–	' '
String placed between units (e.g. - gives 1 Hour-10 Minutes).
withMilliSeconds	booleanbool	–	falseFalse
Include the millisecond unit. When falseFalse, values below one second are omitted.
maxUnitCount	numberint	–	–
Maximum number of units to display, counted from the largest. Omit for unlimited.
unit	stringStringstr	–	–
Express the whole duration with a single unit, allowing fractions (e.g. Hour → 48 Hours, 0.5 Hours). One of Year, Month, Day, Hour, Minute, Second, Millisecond.

Returns

string

String

str

Examples

duration(1234567890); // Returns '14 Days 6 Hours 56 Minutes 7 Seconds'
duration(1234567890, {
	withMilliSeconds: true
}); // Returns '14 Days 6 Hours 56 Minutes 7 Seconds 890 Milliseconds'
duration(34560000000); // Returns '1 Year 1 Month 5 Days'
duration(34560000000, {
	maxUnitCount: 2
}); // Returns '1 Year 1 Month'
duration(172800000, {
	unit: 'Hour'
}); // Returns '48 Hours'
duration(1800000, {
	unit: 'Hour'
}); // Returns '0.5 Hours'
duration(604800000, {
	useSpace: false
}); // Returns '7Days'

duration(1234567890); // Returns '14 Days 6 Hours 56 Minutes 7 Seconds'
duration(1234567890, withMilliSeconds: true); // Returns '14 Days 6 Hours 56 Minutes 7 Seconds 890 Milliseconds'
duration(34560000000); // Returns '1 Year 1 Month 5 Days'
duration(34560000000, maxUnitCount: 2); // Returns '1 Year 1 Month'
duration(172800000, unit: 'Hour'); // Returns '48 Hours'
duration(1800000, unit: 'Hour'); // Returns '0.5 Hours'
duration(604800000, useSpace: false); // Returns '7Days'

duration(1234567890)  # Returns '14 Days 6 Hours 56 Minutes 7 Seconds'
duration(1234567890, {
	'withMilliSeconds': True
})  # Returns '14 Days 6 Hours 56 Minutes 7 Seconds 890 Milliseconds'
duration(34560000000)  # Returns '1 Year 1 Month 5 Days'
duration(34560000000, {
	'maxUnitCount': 2
})  # Returns '1 Year 1 Month'
duration(172800000, {
	'unit': 'Hour'
})  # Returns '48 Hours'
duration(1800000, {
	'unit': 'Hour'
})  # Returns '0.5 Hours'
duration(604800000, {
	'useSpace': False
})  # Returns '7Days'