# Formatting with tokens

## Consider alternatives

You should avoid using ad-hoc custom date formats.

- You should generally use ISO 8601 (or similar) when creating machine-parsable dates and Luxon already provides first-class facilities for creating those. See the DateTime#toISO method.
- You should use DateTime#toLocaleString to create human readable, localized dates. Otherwise, you may put the elements (say, the month and the day) in an order that is wrong in some locales.

However, Luxon provides method for applying ad-hoc formats to DateTimes for two reasons:

- `DateTime#toLocaleString` can be unwieldy. By providing some "macro" formats (see D, t, T, f, and F below) we can simplify commonly used localized formats
- Some systems require you to provide dates in specific formats and it is convenient to have a straightforward way of constructing those strings.

## toFormat

See DateTime#toFormat for the API signature. As a brief motivating example:

    DateTime.fromISO('2014-08-06T13:07:04.054').toFormat('yyyy LLL dd') //=> '2014 Aug 06'

The supported tokens are described in the table below.

## Intl

All of the strings (e.g. month names and weekday names) are internationalized by introspecting strings generated by the Intl API. Thus they exact strings you get are implementation-specific.

    DateTime.fromISO('2014-08-06T13:07:04.054').setLocale('fr').toFormat('yyyy LLL dd') //=> '2014 août 06'

## Escaping

You may escape strings using single quotes:

    DateTime.local().toFormat("HH 'hours and' mm 'minutes'") //=> '20 hours and 55 minutes'

## Standalone vs format tokens

Some tokens have a "standalone" and "format" version. Some languages require different forms of a word based on whether it is part of a longer phrase or just by itself (e.g. "Monday the 22nd" vs "Monday"). Use them accordingly.

    var d = DateTime.fromISO('2014-08-06T13:07:04.054').setLocale('ru');
    d.toFormat("MMMM"); //=> 'августа'
    d.toFormat("LLLL") //=> 'август'

## Macro tokens

Some of the formats are "macros", meaning they correspond to multiple components. These use the native Intl API and will order their constituent parts in a locale-friendly way.

    DateTime.fromISO('2014-08-06T13:07:04.054').toFormat('ff') //=> 'Aug 6, 2014, 1:07 PM'

## Table of tokens

(Examples below given for 2014-08-06T13:07:04.054 considered as a local time in America/New_York).

Standlone token | Format token | Description | Example
--- | --- | --- | ---
S |  | millisecond, no padding | 54
SSS |  | millisecond, padded to 3 | 054
s |  | second, no padding | 4
ss |  | second, padded to 2 padding | 04
m |  | minute, no padding | 7
mm |  | minute, padded to 2 | 07
h |  | hour in 12-hour time, no padding | 1
hh |  | hour in 12-hour time, padded to 2 | 01
H |  | hour in 24-hour time, padded to 2 | 9
HH |  | hour in 24-hour time, padded to 2 | 13
Z |  | narrow offset | +5
ZZ |  | short offset | +05:00
ZZZ |  | techie offset | +0500
ZZZZ |  | abbreviated named offset | EST
ZZZZZ |  | unabbreviated named offset | Eastern Standard Time
z |  | IANA zone | America/New_York
a |  | meridiem | AM
d |  | day of the month, no padding | 6
dd |  | day of the month, padded to 2 | 06
E | c | day of the week, as number from 1-7 (Monday is 1, Sunday is 7) | 3
EEE | ccc | day of the week, as an abbreviate localized string | Wed
EEEE | cccc | day of the week, as an unabbreviated localized string | Wednesday
EEEEE | ccccc | day of the week, as a single localized letter | W
M | L | month as an unpadded number | 8
MM | LL | month as an padded number | 08
MMM | LLL | month as an abbreviated localized string | Aug
MMMM | LLLL | month as an unabbreviated localized string | August
MMMMM | LLLLL | month as a single localized letter | A
y |  | year, unpadded | 2014
yy |  | two-digit year | 14
yyyy |  | four-digit year | 2014
G |  | abbreviated localized era | AD
GG |  | unabbreviated localized era | Anno Domini
GGGGG |  | one-letter localized era | A
kk |  | ISO week year, unpadded | 17
kkkk |  | ISO week year, padded to 4 | 2014
W |  | ISO week number, unpadded | 32
WW |  | ISO week number, padded to 2 | 32
o |  | ordinal (day of year), unpadded | 218
ooo |  | ordinal (day of year), padded to 3 | 218
D |  | localized numeric date | 9/4/2017
DD |  | localized date with abbreviated month | Aug 6, 2014
DDD |  | localized date with full month | August 6, 2014
DDDD |  | localized date with full month and weekday | Wednesday, August 6, 2014
t |  | localized time | 9:07 AM
tt |  | localized time with seconds | 1:07:04 PM
ttt |  | localized time with seconds and abbreviated offset | 1:07:04 PM EDT
tttt |  | localized time with seconds and full offset | 1:07:04 PM Eastern Daylight Time
T |  | localized 24-hour time | 13:07
TT |  | localized 24-hour time with seconds | 13:07:04
TTT |  | localized 24-hour time with seconds and abbreviated offset | 13:07:04 EDT
TTTT |  | localized 24-hour time with seconds and full offset | 13:07:04 Eastern Daylight Time
f |  | short localized date and time | 8/6/2014, 1:07 PM
ff |  | less short localized date and time | Aug 6, 2014, 1:07 PM
fff |  | verbose localized date and time | August 6, 2014, 1:07 PM EDT
ffff |  | extra verbose localized date and time | Wednesday, August 6, 2014, 1:07 PM Eastern Daylight Time
F |  | short localized date and time with seconds | 8/6/2014, 1:07:04 PM
FF |  | less short localized date and time with seconds | Aug 6, 2014, 1:07:04 PM
FFF |  | verbose localized date and time with seconds | August 6, 2014, 1:07:04 PM EDT
FFFF |  | extra verbose localized date and time with seconds | Wednesday, August 6, 2014, 1:07:04 PM Eastern Daylight Time