Formattimespan

Formattimespan is a function or utility used in time-processing libraries to convert a time duration into a human-readable string according to a specified pattern. It is designed to handle a range of input representations, such as seconds, milliseconds, or language- or library-specific duration objects, and to produce stable, portable textual representations of elapsed time.

The primary purpose of formattimespan is to present durations in a format that is easy to read and locale-aware. It typically supports multiple display modes, including verbose, compact, and ISO-style outputs, and can adapt to different units such as days, hours, minutes, and seconds. By taking a duration and a format specification, it abstracts away manual calculations and formatting logic.

Common formats include full or verbose styles (for example, "1 day, 2 hours, 3 minutes"), short or compact styles (for example, "1d 2h 3m"), and ISO 8601 duration strings (for example, "P1DT2H3M"). Many implementations also offer a locale parameter to apply appropriate pluralization rules and unit labels for different languages, ensuring correct grammar and separators.

Usage typically involves passing a duration value along with a desired format and locale. For instance, formattimespan(90061, format="full", locale="en-US") might yield "1 day, 1 hour, 1 minute, 1 second". Edge cases include negative durations, zero-length spans, and very large spans, which most implementations handle with defined fallback or error behavior.

See also: Time span, Duration, Time formatting, ISO 8601 duration.