Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Time formatter

Format a TimeSpan, DateTime, or DateTimeOffset as human-readable text.
Read time 3 minutesLast updated 5 days ago
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
.

Anatomy of the time formatter syntax.

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.

Additional resources