# Time formatter

> Format a TimeSpan, DateTime, or DateTimeOffset as human-readable text.

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](https://learn.microsoft.com/en-us/dotnet/api/system.timespan), or a [DateTime](https://learn.microsoft.com/en-us/dotnet/api/system.datetime) or [DateTimeOffset](https://learn.microsoft.com/en-us/dotnet/api/system.datetimeoffset) measured against the current time. Apply it explicitly with the name `time`.

{ /*  Mermaid source kept for the future doc platform; shown as the static image below until mermaid rendering is supported.  */ }

```mermaid
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;
```


**Anatomy of the time formatter syntax.:**
![](/api/media?file=/engine/6000.7/media/images/smart-strings-time-formatter.svg)

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`](/engine/6000.7/script-reference/unity/smartstrings/smart/format.md). If no culture is provided, it uses the active culture, and falls back to English.

```cs
// "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`](/engine/6000.7/script-reference/unity/smartstrings/extensions/timeformatter/fallbacklanguage.md) 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

* [Choose formatter](/engine/6000.7/manual/scripting/smart-strings/formatters/choose-formatter.md)
* [Sub String formatter](/engine/6000.7/manual/scripting/smart-strings/formatters/substring-formatter.md)
* [Smart Strings](/engine/6000.7/manual/scripting/smart-strings.md)