1 | # d3-time-format
|
2 |
|
3 | This module provides a JavaScript implementation of the venerable [strptime](http://pubs.opengroup.org/onlinepubs/009695399/functions/strptime.html) and [strftime](http://pubs.opengroup.org/onlinepubs/007908799/xsh/strftime.html) functions from the C standard library, and can be used to parse or format [dates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) in a variety of locale-specific representations. To format a date, create a [formatter](#locale_format) from a specifier (a string with the desired format *directives*, indicated by `%`); then pass a date to the formatter, which returns a string. For example, to convert the current date to a human-readable string:
|
4 |
|
5 | ```js
|
6 | var formatTime = d3.timeFormat("%B %d, %Y");
|
7 | formatTime(new Date); // "June 30, 2015"
|
8 | ```
|
9 |
|
10 | Likewise, to convert a string back to a date, create a [parser](#locale_parse):
|
11 |
|
12 | ```js
|
13 | var parseTime = d3.timeParse("%B %d, %Y");
|
14 | parseTime("June 30, 2015"); // Tue Jun 30 2015 00:00:00 GMT-0700 (PDT)
|
15 | ```
|
16 |
|
17 | You can implement more elaborate conditional time formats, too. For example, here’s a [multi-scale time format](http://bl.ocks.org/mbostock/4149176) using [time intervals](https://github.com/d3/d3-time):
|
18 |
|
19 | ```js
|
20 | var formatMillisecond = d3.timeFormat(".%L"),
|
21 | formatSecond = d3.timeFormat(":%S"),
|
22 | formatMinute = d3.timeFormat("%I:%M"),
|
23 | formatHour = d3.timeFormat("%I %p"),
|
24 | formatDay = d3.timeFormat("%a %d"),
|
25 | formatWeek = d3.timeFormat("%b %d"),
|
26 | formatMonth = d3.timeFormat("%B"),
|
27 | formatYear = d3.timeFormat("%Y");
|
28 |
|
29 | function multiFormat(date) {
|
30 | return (d3.timeSecond(date) < date ? formatMillisecond
|
31 | : d3.timeMinute(date) < date ? formatSecond
|
32 | : d3.timeHour(date) < date ? formatMinute
|
33 | : d3.timeDay(date) < date ? formatHour
|
34 | : d3.timeMonth(date) < date ? (d3.timeWeek(date) < date ? formatDay : formatWeek)
|
35 | : d3.timeYear(date) < date ? formatMonth
|
36 | : formatYear)(date);
|
37 | }
|
38 | ```
|
39 |
|
40 | This module is used by D3 [time scales](https://github.com/d3/d3-scale/blob/master/README.md#time-scales) to generate human-readable ticks.
|
41 |
|
42 | ## Installing
|
43 |
|
44 | If you use NPM, `npm install d3-time-format`. Otherwise, download the [latest release](https://github.com/d3/d3-time-format/releases/latest). You can also load directly from [d3js.org](https://d3js.org), either as a [standalone library](https://d3js.org/d3-time-format.v2.min.js) or as part of [D3 4.0](https://github.com/d3/d3). AMD, CommonJS, and vanilla environments are supported. In vanilla, a `d3` global is exported:
|
45 |
|
46 | ```html
|
47 | <script src="https://d3js.org/d3-time.v1.min.js"></script>
|
48 | <script src="https://d3js.org/d3-time-format.v2.min.js"></script>
|
49 | <script>
|
50 |
|
51 | var format = d3.timeFormat("%x");
|
52 |
|
53 | </script>
|
54 | ```
|
55 |
|
56 | Locale files are hosted on [unpkg](https://unpkg.com/) and can be loaded using [d3.json](https://github.com/d3/d3-request/blob/master/README.md#json). For example, to set Russian as the default locale:
|
57 |
|
58 | ```js
|
59 | d3.json("https://unpkg.com/d3-time-format@2/locale/ru-RU.json", function(error, locale) {
|
60 | if (error) throw error;
|
61 |
|
62 | d3.timeFormatDefaultLocale(locale);
|
63 |
|
64 | var format = d3.timeFormat("%c");
|
65 |
|
66 | console.log(format(new Date)); // понедельник, 5 декабря 2016 г. 10:31:59
|
67 | });
|
68 | ```
|
69 |
|
70 | [Try d3-time-format in your browser.](https://tonicdev.com/npm/d3-time-format)
|
71 |
|
72 | ## API Reference
|
73 |
|
74 | <a name="timeFormat" href="#timeFormat">#</a> d3.<b>timeFormat</b>(<i>specifier</i>) [<>](https://github.com/d3/d3-time-format/blob/master/src/defaultLocale.js#L4 "Source")
|
75 |
|
76 | An alias for [*locale*.format](#locale_format) on the [default locale](#timeFormatDefaultLocale).
|
77 |
|
78 | <a name="timeParse" href="#timeParse">#</a> d3.<b>timeParse</b>(<i>specifier</i>) [<>](https://github.com/d3/d3-time-format/blob/master/src/defaultLocale.js#L5 "Source")
|
79 |
|
80 | An alias for [*locale*.parse](#locale_parse) on the [default locale](#timeFormatDefaultLocale).
|
81 |
|
82 | <a name="utcFormat" href="#utcFormat">#</a> d3.<b>utcFormat</b>(<i>specifier</i>) [<>](https://github.com/d3/d3-time-format/blob/master/src/defaultLocale.js#L6 "Source")
|
83 |
|
84 | An alias for [*locale*.utcFormat](#locale_utcFormat) on the [default locale](#timeFormatDefaultLocale).
|
85 |
|
86 | <a name="utcParse" href="#utcParse">#</a> d3.<b>utcParse</b>(<i>specifier</i>) [<>](https://github.com/d3/d3-time-format/blob/master/src/defaultLocale.js#L7 "Source")
|
87 |
|
88 | An alias for [*locale*.utcParse](#locale_utcParse) on the [default locale](#timeFormatDefaultLocale).
|
89 |
|
90 | <a name="isoFormat" href="#isoFormat">#</a> d3.<b>isoFormat</b> [<>](https://github.com/d3/d3-time-format/blob/master/src/isoFormat.js "Source")
|
91 |
|
92 | The full [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC time formatter. Where available, this method will use [Date.toISOString](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Date/toISOString) to format.
|
93 |
|
94 | <a name="isoParse" href="#isoParse">#</a> d3.<b>isoParse</b> [<>](https://github.com/d3/d3-time-format/blob/master/src/isoParse.js "Source")
|
95 |
|
96 | The full [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC time parser. Where available, this method will use the [Date constructor](https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Date) to parse strings. If you depend on strict validation of the input format according to ISO 8601, you should construct a [UTC parser function](#utcParse):
|
97 |
|
98 | ```js
|
99 | var strictIsoParse = d3.utcParse("%Y-%m-%dT%H:%M:%S.%LZ");
|
100 | ```
|
101 |
|
102 | <a name="locale_format" href="#locale_format">#</a> <i>locale</i>.<b>format</b>(<i>specifier</i>) [<>](https://github.com/d3/d3-time-format/blob/master/src/locale.js#L293 "Source")
|
103 |
|
104 | Returns a new formatter for the given string *specifier*. The specifier string may contain the following directives:
|
105 |
|
106 | * `%a` - abbreviated weekday name.*
|
107 | * `%A` - full weekday name.*
|
108 | * `%b` - abbreviated month name.*
|
109 | * `%B` - full month name.*
|
110 | * `%c` - the locale’s date and time, such as `%x, %X`.*
|
111 | * `%d` - zero-padded day of the month as a decimal number [01,31].
|
112 | * `%e` - space-padded day of the month as a decimal number [ 1,31]; equivalent to `%_d`.
|
113 | * `%f` - microseconds as a decimal number [000000, 999999].
|
114 | * `%H` - hour (24-hour clock) as a decimal number [00,23].
|
115 | * `%I` - hour (12-hour clock) as a decimal number [01,12].
|
116 | * `%j` - day of the year as a decimal number [001,366].
|
117 | * `%m` - month as a decimal number [01,12].
|
118 | * `%M` - minute as a decimal number [00,59].
|
119 | * `%L` - milliseconds as a decimal number [000, 999].
|
120 | * `%p` - either AM or PM.*
|
121 | * `%Q` - milliseconds since UNIX epoch.
|
122 | * `%s` - seconds since UNIX epoch.
|
123 | * `%S` - second as a decimal number [00,61].
|
124 | * `%u` - Monday-based (ISO 8601) weekday as a decimal number [1,7].
|
125 | * `%U` - Sunday-based week of the year as a decimal number [00,53].
|
126 | * `%V` - ISO 8601 week of the year as a decimal number [01, 53].
|
127 | * `%w` - Sunday-based weekday as a decimal number [0,6].
|
128 | * `%W` - Monday-based week of the year as a decimal number [00,53].
|
129 | * `%x` - the locale’s date, such as `%-m/%-d/%Y`.*
|
130 | * `%X` - the locale’s time, such as `%-I:%M:%S %p`.*
|
131 | * `%y` - year without century as a decimal number [00,99].
|
132 | * `%Y` - year with century as a decimal number.
|
133 | * `%Z` - time zone offset, such as `-0700`, `-07:00`, `-07`, or `Z`.
|
134 | * `%%` - a literal percent sign (`%`).
|
135 |
|
136 | Directives marked with an asterisk (\*) may be affected by the [locale definition](#localeFormat).
|
137 |
|
138 | For `%U`, all days in a new year preceding the first Sunday are considered to be in week 0. For `%W`, all days in a new year preceding the first Monday are considered to be in week 0. Week numbers are computed using [*interval*.count](https://github.com/d3/d3-time/blob/master/README.md#interval_count). For example, 2015-52 and 2016-00 represent Monday, December 28, 2015, while 2015-53 and 2016-01 represent Monday, January 4, 2016. This differs from the [ISO week date](https://en.wikipedia.org/wiki/ISO_week_date) specification (`%V`), which uses a more complicated definition!
|
139 |
|
140 | For `%V`, per the [strftime man page](http://man7.org/linux/man-pages/man3/strftime.3.html):
|
141 |
|
142 | > In this system, weeks start on a Monday, and are numbered from 01, for the first week, up to 52 or 53, for the last week. Week 1 is the first week where four or more days fall within the new year (or, synonymously, week 01 is: the first week of the year that contains a Thursday; or, the week that has 4 January in it).
|
143 |
|
144 | The `%` sign indicating a directive may be immediately followed by a padding modifier:
|
145 |
|
146 | * `0` - zero-padding
|
147 | * `_` - space-padding
|
148 | * `-` - disable padding
|
149 |
|
150 | If no padding modifier is specified, the default is `0` for all directives except `%e`, which defaults to `_`. (In some implementations of strftime and strptime, a directive may include an optional field width or precision; this feature is not yet implemented.)
|
151 |
|
152 | The returned function formats a specified *[date](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date)*, returning the corresponding string.
|
153 |
|
154 | ```js
|
155 | var formatMonth = d3.timeFormat("%B"),
|
156 | formatDay = d3.timeFormat("%A"),
|
157 | date = new Date(2014, 4, 1); // Thu May 01 2014 00:00:00 GMT-0700 (PDT)
|
158 |
|
159 | formatMonth(date); // "May"
|
160 | formatDay(date); // "Thursday"
|
161 | ```
|
162 |
|
163 | <a name="locale_parse" href="#locale_parse">#</a> <i>locale</i>.<b>parse</b>(<i>specifier</i>) [<>](https://github.com/d3/d3-time-format/blob/master/src/locale.js#L298 "Source")
|
164 |
|
165 | Returns a new parser for the given string *specifier*. The specifier string may contain the same directives as [*locale*.format](#locale_format). The `%d` and `%e` directives are considered equivalent for parsing.
|
166 |
|
167 | The returned function parses a specified *string*, returning the corresponding [date](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Date) or null if the string could not be parsed according to this format’s specifier. Parsing is strict: if the specified <i>string</i> does not exactly match the associated specifier, this method returns null. For example, if the associated specifier is `%Y-%m-%dT%H:%M:%SZ`, then the string `"2011-07-01T19:15:28Z"` will be parsed as expected, but `"2011-07-01T19:15:28"`, `"2011-07-01 19:15:28"` and `"2011-07-01"` will return null. (Note that the literal `Z` here is different from the time zone offset directive `%Z`.) If a more flexible parser is desired, try multiple formats sequentially until one returns non-null.
|
168 |
|
169 | <a name="locale_utcFormat" href="#locale_utcFormat">#</a> <i>locale</i>.<b>utcFormat</b>(<i>specifier</i>) [<>](https://github.com/d3/d3-time-format/blob/master/src/locale.js#L303 "Source")
|
170 |
|
171 | Equivalent to [*locale*.format](#locale_format), except all directives are interpreted as [Coordinated Universal Time (UTC)](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) rather than local time.
|
172 |
|
173 | <a name="locale_utcParse" href="#locale_utcParse">#</a> <i>locale</i>.<b>utcParse</b>(<i>specifier</i>) [<>](https://github.com/d3/d3-time-format/blob/master/src/locale.js#L308 "Source")
|
174 |
|
175 | Equivalent to [*locale*.parse](#locale_parse), except all directives are interpreted as [Coordinated Universal Time (UTC)](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) rather than local time.
|
176 |
|
177 | ### Locales
|
178 |
|
179 | <a name="timeFormatLocale" href="#timeFormatLocale">#</a> d3.<b>timeFormatLocale</b>(<i>definition</i>) [<>](https://github.com/d3/d3-time-format/blob/master/src/locale.js "Source")
|
180 |
|
181 | Returns a *locale* object for the specified *definition* with [*locale*.format](#locale_format), [*locale*.parse](#locale_parse), [*locale*.utcFormat](#locale_utcFormat), [*locale*.utcParse](#locale_utcParse) methods. The *definition* must include the following properties:
|
182 |
|
183 | * `dateTime` - the date and time (`%c`) format specifier (<i>e.g.</i>, `"%a %b %e %X %Y"`).
|
184 | * `date` - the date (`%x`) format specifier (<i>e.g.</i>, `"%m/%d/%Y"`).
|
185 | * `time` - the time (`%X`) format specifier (<i>e.g.</i>, `"%H:%M:%S"`).
|
186 | * `periods` - the A.M. and P.M. equivalents (<i>e.g.</i>, `["AM", "PM"]`).
|
187 | * `days` - the full names of the weekdays, starting with Sunday.
|
188 | * `shortDays` - the abbreviated names of the weekdays, starting with Sunday.
|
189 | * `months` - the full names of the months (starting with January).
|
190 | * `shortMonths` - the abbreviated names of the months (starting with January).
|
191 |
|
192 | For an example, see [Localized Time Axis II](https://bl.ocks.org/mbostock/805115ebaa574e771db1875a6d828949).
|
193 |
|
194 | <a name="timeFormatDefaultLocale" href="#timeFormatDefaultLocale">#</a> d3.<b>timeFormatDefaultLocale</b>(<i>definition</i>) [<>](https://github.com/d3/d3-time-format/blob/master/src/defaultLocale.js "Source")
|
195 |
|
196 | Equivalent to [d3.timeFormatLocale](#timeFormatLocale), except it also redefines [d3.timeFormat](#timeFormat), [d3.timeParse](#timeParse), [d3.utcFormat](#utcFormat) and [d3.utcParse](#utcParse) to the new locale’s [*locale*.format](#locale_format), [*locale*.parse](#locale_parse), [*locale*.utcFormat](#locale_utcFormat) and [*locale*.utcParse](#locale_utcParse). If you do not set a default locale, it defaults to [U.S. English](https://github.com/d3/d3-time-format/blob/master/locale/en-US.json).
|
197 |
|
198 | For an example, see [Localized Time Axis](https://bl.ocks.org/mbostock/6f1cc065d4d172bcaf322e399aa8d62f).
|