Time formatter
Format a TimeSpan, DateTime, or DateTimeOffset as human-readable text.
The Time formatter turns a duration into readable text, such as 1 day 6 hours. It accepts a TimeSpan, or a DateTime or DateTimeOffset measured against the current time. Apply it explicitly with the name time.
flowchart TD
full["{value:time(options)}"]
full --> p1["value"]
full --> p2["time"]
full --> p3["options"]
p1 --> d1["Any value"]
p2 --> d2["Formatter name: time"]
p3 --> d3["Time span<br/>format options"]
classDef code fill:#F5F5F5,stroke:#BDBDBD,color:#111;
classDef orange fill:none,stroke:none,color:#F37021;
classDef green fill:none,stroke:none,color:#67BC6B;
classDef pink fill:none,stroke:none,color:#EB417A;
class full code;
class p1,d1 orange;
class p2,d2 green;
class p3,d3 pink;
linkStyle default stroke:#2196F3,stroke-width:1.5px;
The format part holds the options, separated by spaces. The optional parentheses hold a culture name, for example {0:time(en):abbr}. When no culture is given, the formatter uses the culture passed to Smart.Format. If no culture is provided, it uses the active culture, and falls back to English.
// "1 day 6 hours"
Smart.Format("{0:time:less d h}", new TimeSpan(1, 6, 0, 0));
// "1 day 1 hour 1 minute 1 second" (active culture en)
Smart.Format("{0:time:}", new TimeSpan(1, 1, 1, 1, 1));
Combine options by separating them with spaces. The following options are available:
| Option | Description |
|---|---|
w, week, weeks
|
Include weeks in the range. |
d, day, days
|
Include days in the range. |
h, hour, hours
|
Include hours in the range. |
m, minute, minutes
|
Include minutes in the range. |
s, second, seconds
|
Include seconds in the range. |
ms, millisecond, milliseconds
|
Include milliseconds in the range. |
short |
Display the highest non-zero value in the range. For example 00.23:00:59.000 is 23 hours. |
auto |
Display all non-zero values in the range. For example 00.23:00:59.000 is 23 hours 59 minutes. |
fill |
Display the highest non-zero value and all lesser values in the range. For example 00.23:00:59.000 is 23 hours 0 minutes 59 seconds 0 milliseconds. |
full |
Display all values in the range. For example 00.23:00:59.000 is 0 days 23 hours 0 minutes 59 seconds 0 milliseconds. |
abbr |
Abbreviate units, for example 1d 2h 3m 4s 5ms. |
noabbr |
Don’t abbreviate units, for example 1 day 2 hours 3 minutes 4 seconds 5 milliseconds. |
less |
Display “less than 1 (unit)” when the value is smaller than the minimum range. |
noless |
Display “0 (units)” when the value is smaller than the minimum range. |
Use two range options to set the minimum and maximum unit. For example, d shows days only, while h s shows hours down to seconds.
When no options are given, the defaults are noabbr less auto seconds days.
Output is localized through the resolved culture, for example en, de, or fr. The fallback culture is English. Set TimeFormatter.FallbackLanguage to change the fallback, or set it to an empty string to disable the fallback.
The Time formatter can’t handle nested formats. Applying it to an unsupported type throws a FormatException.
| Smart String | Argument | Result |
|---|---|---|
{0:time:abbr} |
new TimeSpan(451, 6, 22, 5) |
451d 6h 22m 5s |
{0:time:full} |
new TimeSpan(451, 6, 22, 5) |
451 days 6 hours 22 minutes 5 seconds |
{0:time:less weeks} |
new TimeSpan(1, 6, 0, 0) |
less than 1 week |
{0:time:less d h} |
new TimeSpan(1, 6, 0, 0) |
1 day 6 hours |
A DateTime or DateTimeOffset argument is formatted as the duration between it and the current time. A TimeSpan is formatted directly.