# rell.time · Chromia Docs (concept)

> The rell.time namespace formats and parses UTC dates and times. Its central type, rell.time.format, holds a format pattern and converts between Unix timestamps…

Source: https://docs.chromia.com/rell/language-features/systemlib/namespaces/time/

# rell.time

On this page

* [Format specifiers](#format-specifiers)
* [Constructor](#constructor)
* [Methods](#methods)
* [Static functions](#static-functions)
* [Examples](#examples)

The `rell.time` namespace formats and parses UTC dates and times. Its central type,
[`rell.time.format`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.time/format/), holds a
format pattern and converts between Unix timestamps in milliseconds and text.

## Format specifiers

| Specifier | Meaning |
| --- | --- |
| `y` | Year |
| `M` | Month in the year |
| `w` | Week in the year |
| `W` | Week in the month |
| `D` | Day in the year |
| `d` | Day in the month |
| `E` | Day name in the week |
| `u` | Day number in the week |
| `a` | AM/PM specifier |
| `H` | Hour in the day (0-23) |
| `h` | Hour in the am/pm (1-12) |
| `m` | Minute in the hour |
| `s` | Second in the minute |
| `S` | Milliseconds in the second |

Non-interpreted text may be included within single quotes. A single quote is escaped with a second single quote (`''`).

## Constructor

`rell.time.format(pattern: text)` constructs a `rell.time.format` value from the given time format pattern.

## Methods

| Method | Description |
| --- | --- |
| `.ms_to_text(ms: integer): text` | Formats a Unix timestamp according to this format value. |
| `.text_to_ms(text): integer` | Parses a Unix timestamp from text formatted according to this format value. Throws an error on failure. |
| `.text_to_ms_or_null(text): integer?` | Same as `.text_to_ms()`, but returns `null` on failure. |
| `.to_text(): text` | Returns the format pattern of this format value. |

## Static functions

Each static function takes the pattern as its first argument and is equivalent to constructing a `rell.time.format` and
calling the corresponding method:

| Function | Equivalent to |
| --- | --- |
| [`rell.time.ms_to_text(pattern, ms): text`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.time/ms_to_text/) | `rell.time.format(pattern).ms_to_text(ms)` |
| [`rell.time.text_to_ms(pattern, text): integer`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.time/text_to_ms/) | `rell.time.format(pattern).text_to_ms(text)` |
| [`rell.time.text_to_ms_or_null(pattern, text): integer?`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/rell.time/text_to_ms_or_null/) | `rell.time.format(pattern).text_to_ms_or_null(text)` |

## Examples

Rell

```
rell.time.format('yyyy.MM.dd \'at\' HH:mm:ss').text_to_ms('2001.07.04 at 11:08:56'); // 994244936000
rell.time.format('EEE, MMM d, \'\'yy').text_to_ms('Wed, Jul 4, \'01');               // 994204800000
rell.time.format('h:mm a').text_to_ms('11:08 AM');                                   // 40080000
rell.time.format('hh \'o\'\'clock\' a').text_to_ms('11 o\'clock AM');                // 39600000

val ms: integer = 994244936235;
rell.time.format('hh:mm a').ms_to_text(ms);                        // '11:08 AM'
rell.time.format('yyyyy.MMMMM.dd hh:mm aaa').ms_to_text(ms);       // '02001.July.04 11:08 AM'
rell.time.format('yyyy-MM-dd\'T\'HH:mm:ss.SSS').ms_to_text(ms);    // '2001-07-04T11:08:56.235'
rell.time.format('yyyy-\'W\'ww-u').ms_to_text(ms);                 // '2001-W27-3'
```

note

The `rell.time` namespace is available from Rell 0.14.14.

[View this page on docs.chromia.com](https://docs.chromia.com/rell/language-features/systemlib/namespaces/time/)Content mirrored from the live docs
