summaryrefslogtreecommitdiff
path: root/doc/api/libdate/formatting.txt
blob: c09f2cbbf9f55f390f32a21191efc6d40ce87abb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
{
	title: Formatting
	description: Libdate API documentation.
}

Date and Time Formatting
---------------------

Formatting in libdate is done through the standard formatting
functionality, and there are actually no functions exposed by libdate.
Instead, you would write something like:

```{runmyr stdfmt1}
use date

const main = {
	std.put("{}\n", date.now())
}
```

Custom formatting is done with a format option passed to std.format that
looks like `f=dateformat`. The format strings used resemble the strings
provided in strptime. Any characters preceded with a '%' are format
characters, otherwise they are copied to the output stream directly.

The format strings used to control formatting are also used to control parsing.

An example would look like:

```{runmyr stdfmt1}
use date

const main = {
	std.put("{f=year is %Y, the day is %d}\n", date.now())
}


There are a number of short format options installed, specifically, `d`,
`D`, and `t`, which respectively map to the default date format, the
default date and time format, and the default time only format.

```{runmyr stdfmt1}
use date

const main = {
	std.put("{d}\n", date.now())
	std.put("{D}\n", date.now())
	std.put("{T}\n", date.now())
}
```

Date and Time Formatting
---------------------

Both parsing and formatting use the same format strings. The
modifiers that are supported by libdate are listed below.

When possible, the default format verbs `D`, `d`, or `t`
should be used for formatting, and the default constants
`Datefmt`, `Datetimefmt`, or `Timefmt` should be used for
parsing.


Char  | Meaning
------|----------------------------------------------
_%a_  | Abbreviated day of week: Mon, Tues, etc
_%A_  | Full day of week: Monday, Tuesday, Wednesday, etc
_%b_  | Abbreviated month of year: Jan, Feb, Mar, etc.
_%B_  | Full month of year: January, February, etc
_%c_  | Short for %Y-%m-%d %H:%M:%S %z (ISO 8601)
_%C_  | Century number of year, as two digit integer.
_%d_  | Day of month as a decimal number, 00 to 31.
_%D_  | Short for "%m/%d/%y (wtf america)"
_%e_  | Same as d, but space padded instead of zero padded.
_%F_  | Short for ISO 8601 date format %Y-%m-%d
_%h_  | Same as '%b'.
_%H_  | Hour number using the 24 hour clock, zero padded.
_%I_  | Hour number using the 12 hour clock, zero padded.
_%j_  | Day of year as a decimal number, 001 to 366.
_%k_  | Hour number using the 24 hour clock, space padded.
_%l_  | Hour number using the 12 hour clock, space padded.
_%m_  | The month number, zero padded.
_%M_  | The minute number, zero padded.
_%p_  | AM or PM, according to the time provided.
_%P_  | am or pm, according to the time provided.
_%r_  | 12 hour time: %I:%M %p
_%R_  | 24 hour time: %H:%M
_%s_  | The number of seconds since the Epoch
_%S_  | The second number, zero padded. 0 to 60.
_%T_  | The time including seconds in 24 hour format.
_%u_  | The day of the week in decimal, 0 to 7.
_%x_  | The date without the time. Same as %F
_%X_  | The date with the time. Same as %c
_%y_  | The final two digits of year.
_%Y_  | The full year, including century. BC dates are negative.
_%z_  | Timezone offset.
_%Z_  | Timezone name or abbreviation. Offset if this is not available.
_%%_  | A literal '%'