> ## Documentation Index
> Fetch the complete documentation index at: https://gocharting.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How to format a time as text

> Turning a bar's time into a readable string with str.format_time, which takes seconds, a layout written as the reference date, and an optional time zone.

`str.format_time(time_value, format, timezone)` returns a time as a string. Two things differ from what you may expect: the time is in
**seconds**, while `time`, `time_close` and `timenow` are in milliseconds, and the format is a layout, not a list of letter codes.

```lipi theme={"languages":{"custom":["/languages/lipi.json","/languages/lipi-invalid.json"]}}
//@lipi=2
indicator("Last bar time", overlay=true)
if barstate.islast {
    stamp = str.format_time(math.floor(time / 1000), "2006-01-02 15:04", "UTC")
    label.new(bar_index, high, stamp)
}
```

## Seconds, not milliseconds

Divide a Lipi time by 1000 and round down: `math.floor(time / 1000)`. Passing `time` itself compiles, because it is an integer, but
the result is a date tens of thousands of years from now: the function reads the number as seconds.

```lipi theme={"languages":{"custom":["/languages/lipi.json","/languages/lipi-invalid.json"]}}
//@lipi=2
indicator("Time in milliseconds", overlay=true)
if barstate.islast {
    label.new(bar_index, high, str.format_time(time, "2006-01-02 15:04"))
}
```

That script compiles and shows the wrong year. Nothing in the compiler flags it.

## The layout

Write the layout as the date 2006-01-02 15:04:05 (a Monday, January 2, 2006, 3:04:05 PM) would appear in the format you want. The parts
of that reference date are the codes:

| Part | Code | Part | Code |
| - | - | - | - |
| year | `2006` | hour, 24-hour | `15` |
| month number | `01` | hour, 12-hour | `03` |
| month name | `Jan` or `January` | minute | `04` |
| day of month | `02` | second | `05` |
| weekday name | `Mon` or `Monday` | AM/PM | `PM` |

So `"2006-01-02 15:04"` gives `2026-10-25 14:30`, `"02 Jan 15:04"` gives `25 Oct 14:30` and `"Mon 03:04 PM"` gives `Sun 02:30 PM`.

## The time zone

The third argument is optional and defaults to `"UTC"`. Give it as `"UTC+3"`, `"UTC-5"` or `"GMT+0530"` (hours, or hours and minutes), or as an
IANA name such as `"America/New_York"`. `syminfo.timezone` is the instrument's own zone. An unknown zone makes the result `na`, not an
error.

```lipi wrap theme={"languages":{"custom":["/languages/lipi.json","/languages/lipi-invalid.json"]}}
//@lipi=2
indicator("Time in the exchange zone", overlay=true)
if barstate.islast {
    label.new(bar_index, high, str.format_time(math.floor(time / 1000), "02 Jan 15:04", syminfo.timezone) + " " + syminfo.timezone)
}
```

## The mistake to avoid

Passing the milliseconds of `time` straight in, as above. Divide by 1000 first. See [Sessions and intervals](https://gocharting.com/docs/scripting/market-data/sessions-and-intervals.md)
and [Text and markers](https://gocharting.com/docs/scripting/chart-output/text-and-markers.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.