# Formatting

This section covers creating strings to represent a DateTime. There are three types of formatting capabilities:

 1. Technical formats like ISO 8601 and RFC 2822
 2. Internationalizable human-readable formats
 3. Token-based formatting

## Technical formats (strings for computers)

### ISO 8601

[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) is the most widely used set of string formats for dates and times. Luxon can *parse* a wide range of them, but provides direct support for formatting only a few of them:

```js
dt.toISO();         //=> '2017-04-20T11:32:00.000-04:00'
dt.toISODate();     //=> '2017-W17-7'
dt.toISOWeekDate(); //=> '2017-04-20'
dt.toISOTime();     //=> '11:32:00.000-04:00'
```

Generally, you'll want the first one. Use it by default when building or interacting with APIs, communicating times over a wire, etc.

### HTTP and RFC 2822

There are a number of legacy standard date and time formats out there, and Luxon supports some of them. You shouldn't use them unless you have a specific reason to.

```js
dt.toRFC2822(); //=> 'Thu, 20 Apr 2017 11:32:00 -0400'
dt.toHTTP();    //=> 'Thu, 20 Apr 2017 03:32:00 GMT'
```

## toLocaleString (strings for humans)

### The basics

Modern browsers (and other JS environments) provide brought support for human-readable, internationalized strings. Luxon provides convenient support for them, and you should use them anytime you want to display a time to a user. Use [toLocaleString](../class/src/datetime.js~DateTime.html#instance-method-toLocaleString) to do it:

```js
dt.toLocaleString();                                       //=> '4/20/2017'
dt.toLocaleString(DateTime.DATETIME_FULL);                 //=> 'April 20, 2017, 11:32 AM EDT'
dt.setLocale('fr').toLocaleString(DateTime.DATETIME_FULL); //=> '20 avril 2017 à 11:32 UTC−4'
```

### Intl.DateTimeFormat

In the example above, `DateTime.DATETIME_FULL` is one of several convenience formats provided by Luxon. But the arguments are really any object of options that can be provided to [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat). For example:

```js
dt.toLocaleString({ month: 'long', day: 'numeric' }) //=> 'April 20'
```

And that's all the preset is:

```
DateTime.DATETIME_FULL;  //=> {
                         //     year: 'numeric',
                         //     month: 'long',
                         //     day: 'numeric',
                         //     hour: 'numeric',
                         //     minute: '2-digit',
                         //     timeZoneName: 'short'
                         //   }

```

This also means you can modify the presets as you choose:

```js
dt.toLocaleString(DateTime.DATE_SHORT); //=>  '4/20/2017'
var newFormat = Object.assign({ weekday: 'long' }, DateTime.DATE_SHORT);
dt.toLocaleString(newFormat); //=>  'Thursday, 4/20/2017'
```

### Presets

Here's the full set of provided presets using the October 14, 1983 at 13:30:23 as an example.

| Name                        | Description                                                        | Example in EN_US                                           | Example in FR                                            |
| ---                         | ---                                                                | ---                                                        | ---                                                      |
| DATE_SHORT                  | short date                                                         | 10/14/1983                                                 | 14/10/1983                                               |
| DATE_MED                    | abbreviated date                                                   | Oct 14, 1983                                               | 14 oct. 1983                                             |
| DATE_FULL                   | full date                                                          | October 14, 1983                                           | 14 octobre 1983                                          |
| DATE_HUGE                   | full date with weekday                                             | Tuesday, October 14, 1983                                  | vendredi 14 octobre 1983                                 |
| TIME_SIMPLE                 | time                                                               | 1:30 PM                                                    | 13:30                                                    |
| TIME_WITH_SECONDS           | time with seconds                                                  | 1:30:23 PM                                                 | 13:30:23                                                 |
| TIME_WITH_SHORT_OFFSET      | time with seconds and abbreviated named offset                     | 1:30:23 PM EDT                                             | 13:30:23 UTC−4                                           |
| TIME_WITH_LONG_OFFSET       | time with seconds and full named offset                            | 1:30:23 PM Eastern Daylight Time                           | 13:30:23 heure d’été de l’Est                            |
| TIME_24_SIMPLE              | 24-hour time                                                       | 13:30                                                      | 13:30                                                    |
| TIME_24_WITH_SECONDS        | 24-hour time with seconds                                          | 13:30:23                                                   | 13:30:23                                                 |
| TIME_24_WITH_SHORT_OFFSET   | 24-hour time with seconds and abbreviated named offset             | 13:30:23 EDT                                               | 13:30:23 UTC−4                                           |
| TIME_24_WITH_LONG_OFFSET    | 24-hour time with seconds and full named offset                    | 13:30:23 Eastern Daylight Time                             | 13:30:23 heure d’été de l’Est                            |
| DATETIME_SHORT              | short date & time                                                  | 10/14/1983, 1:30 PM                                        | 14/10/1983 à 13:30                                       |
| DATETIME_MED                | abbreviated date & time                                            | Oct 14, 1983, 1:30 PM                                      | 14 oct. 1983 à 13:30                                     |
| DATETIME_FULL               | full date and time with abbreviated named offset                   | 14 octobre 1983 à 13:30 UTC−4                              | 14 octobre 1983 à 13:30 UTC−4                            |
| DATETIME_HUGE               | full date and time with weekday and full named offset              | Friday, October 14, 1983, 1:30 PM Eastern Daylight Time    | vendredi 14 octobre 1983 à 13:30 heure d’été de l’Est    |
| DATETIME_SHORT_WITH_SECONDS | short date & time with seconds                                     | 10/14/1983, 1:30:23 PM                                     | 14/10/1983 à 13:30:23                                    |
| DATETIME_MED_WITH_SECONDS   | abbreviated date & time with seconds                               | Oct 14, 1983, 1:30:23 PM                                   | 14 oct. 1983 à 13:30:23                                  |
| DATETIME_FULL_WITH_SECONDS  | full date and time with abbreviated named offset with seconds      | October 14, 1983, 1:30:23 PM EDT                           | 14 octobre 1983 à 13:30:23 UTC−4                         |
| DATETIME_HUGE_WITH_SECONDS  | full date and time with weekday and full named offset with seconds | Friday, October 14, 1983, 1:30:23 PM Eastern Daylight Time | vendredi 14 octobre 1983 à 13:30:23 heure d’été de l’Est |


### Intl

`toLocaleString`'s behavior is affected by the DateTime's `locale`, `numberingSystem`, and `outputCalendar` properties. See the [Intl](intl.html) section for more.

## Formatting with tokens (strings for Cthulhu)

This section covers generating strings from DateTimes with programmer-specified formats.

### Consider alternatives
You shouldn't create ad-hoc string formats if you can avoid it. If you intend for a computer to read the string, prefer ISO 8601. If a human will read it, prefer `toLocaleString`. Both are covered above. However, if you have some esoteric need where you need some specific format (e.g. because some other software expects it), then `toFormat` is how you do it.
 
### toFormat
 
See [DateTime#toFormat]("../class/src/datetime.js~DateTime.html#instance-method-toFormat") for the API signature. As a brief motivating example:

```js
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.

```js
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:

```js
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. 

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

### 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.

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

The macro options available correspond one-to-one with the preset formats defined for `toLocaleString`.

### 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                                                          |
| c               | E            | day of the week, as number from 1-7 (Monday is 1, Sunday is 7) | 3                                                           |
| ccc             | EEE          | day of the week, as an abbreviate localized string             | Wed                                                         |
| cccc            | EEEE         | day of the week, as an unabbreviated localized string          | Wednesday                                                   |
| ccccc           | EEEEE        | day of the week, as a single localized letter                  | W                                                           |
| L               | M            | month as an unpadded number                                    | 8                                                           |
| LL              | MM           | month as an padded number                                      | 08                                                          |
| LLL             | MMM          | month as an abbreviated localized string                       | Aug                                                         |
| LLLL            | MMMM         | month as an unabbreviated localized string                     | August                                                      |
| LLLLL           | MMMMM        | 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 |
