1 | // Type definitions for d3JS d3-time-format module 4.0
|
2 | // Project: https://github.com/d3/d3-time-format/, https://d3js.org/d3-time-format
|
3 | // Definitions by: Tom Wanzek <https://github.com/tomwanzek>
|
4 | // Alex Ford <https://github.com/gustavderdrache>
|
5 | // Boris Yankov <https://github.com/borisyankov>
|
6 | // Nathan Bierema <https://github.com/Methuselah96>
|
7 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
8 |
|
9 | // Last module patch version validated against: 4.0.0
|
10 |
|
11 | /**
|
12 | * Specification of time locale to use when creating a new TimeLocaleObject
|
13 | */
|
14 | export interface TimeLocaleDefinition {
|
15 | /**
|
16 | * The date and time (%c) format specifier (e.g., "%a %b %e %X %Y").
|
17 | */
|
18 | dateTime: string;
|
19 | /**
|
20 | * The date (%x) format specifier (e.g., "%m/%d/%Y").
|
21 | */
|
22 | date: string;
|
23 | /**
|
24 | * The time (%X) format specifier (e.g., "%H:%M:%S").
|
25 | */
|
26 | time: string;
|
27 | /**
|
28 | * The A.M. and P.M. equivalents (e.g., ["AM", "PM"]).
|
29 | */
|
30 | periods: [string, string];
|
31 | /**
|
32 | * The full names of the weekdays, starting with Sunday.
|
33 | */
|
34 | days: [string, string, string, string, string, string, string];
|
35 | /**
|
36 | * The abbreviated names of the weekdays, starting with Sunday.
|
37 | */
|
38 | shortDays: [string, string, string, string, string, string, string];
|
39 | /**
|
40 | * The full names of the months (starting with January).
|
41 | */
|
42 | months: [string, string, string, string, string, string, string, string, string, string, string, string];
|
43 | /**
|
44 | * the abbreviated names of the months (starting with January).
|
45 | */
|
46 | shortMonths: [string, string, string, string, string, string, string, string, string, string, string, string];
|
47 | }
|
48 |
|
49 | /**
|
50 | * Interface describing a time-locale-based object which exposes time-formatting/parsing
|
51 | * methods for a specified locale definition.
|
52 | */
|
53 | export interface TimeLocaleObject {
|
54 | /**
|
55 | * Returns a new formatter for the given string specifier. The specifier string may contain the following directives:
|
56 | * - %a - abbreviated weekday name.*
|
57 | * - %A - full weekday name.*
|
58 | * - %b - abbreviated month name.*
|
59 | * - %B - full month name.*
|
60 | * - %c - the locale’s date and time, such as %x, %X.*
|
61 | * - %d - zero-padded day of the month as a decimal number [01,31].
|
62 | * - %e - space-padded day of the month as a decimal number [ 1,31]; equivalent to %_d.
|
63 | * - %f - microseconds as a decimal number [000000, 999999].
|
64 | * - %g - ISO 8601 week-based year without century as a decimal number [00,99].
|
65 | * - %G - ISO 8601 week-based year with century as a decimal number.
|
66 | * - %H - hour (24-hour clock) as a decimal number [00,23].
|
67 | * - %I - hour (12-hour clock) as a decimal number [01,12].
|
68 | * - %j - day of the year as a decimal number [001,366].
|
69 | * - %m - month as a decimal number [01,12].
|
70 | * - %M - minute as a decimal number [00,59].
|
71 | * - %L - milliseconds as a decimal number [000, 999].
|
72 | * - %p - either AM or PM.*
|
73 | * - %q - quarter of the year as a decimal number [1,4].
|
74 | * - %Q - milliseconds since UNIX epoch.
|
75 | * - %s - seconds since UNIX epoch.
|
76 | * - %S - second as a decimal number [00,61].
|
77 | * - %u - Monday-based (ISO) weekday as a decimal number [1,7].
|
78 | * - %U - Sunday-based week of the year as a decimal number [00,53].
|
79 | * - %V - ISO 8601 week number of the year as a decimal number [01, 53].
|
80 | * - %w - Sunday-based weekday as a decimal number [0,6].
|
81 | * - %W - Monday-based week of the year as a decimal number [00,53].
|
82 | * - %x - the locale’s date, such as %-m/%-d/%Y.*
|
83 | * - %X - the locale’s time, such as %-I:%M:%S %p.*
|
84 | * - %y - year without century as a decimal number [00,99].
|
85 | * - %Y - year with century as a decimal number.
|
86 | * - %Z - time zone offset, such as -0700, -07:00, -07, or Z.
|
87 | * - %% - a literal percent sign (%).
|
88 | *
|
89 | * Directives marked with an asterisk (*) may be affected by the locale definition.
|
90 | *
|
91 | * For %U, all days in a new year preceding the first Sunday are considered to be in week 0.
|
92 | * For %W, all days in a new year preceding the first Monday are considered to be in week 0.
|
93 | * Week numbers are computed using 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.
|
94 | * This differs from the ISO week date specification (%V), which uses a more complicated definition!
|
95 | *
|
96 | * For %V,%g and %G, per the strftime man page:
|
97 | *
|
98 | * 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.
|
99 | * 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;
|
100 | * or, the week that has 4 January in it). If the ISO week number belongs to the previous or next year, that year is used instead.
|
101 | *
|
102 | * The % sign indicating a directive may be immediately followed by a padding modifier:
|
103 | *
|
104 | * 1) 0 - zero-padding
|
105 | * 2) _ - space-padding
|
106 | * 3) - disable padding
|
107 | *
|
108 | * If no padding modifier is specified, the default is 0 for all directives except %e, which defaults to _.
|
109 | * (In some implementations of strftime and strptime, a directive may include an optional field width or precision; this feature is not yet implemented.)
|
110 | *
|
111 | * The returned function formats a specified date, returning the corresponding string.
|
112 | *
|
113 | * @param specifier A specifier string for the date format.
|
114 | */
|
115 | format(specifier: string): (date: Date) => string;
|
116 | /**
|
117 | * Returns a new parser for the given string specifier. The specifier string may contain the same directives as locale.format (TimeLocaleObject.format).
|
118 | * The %d and %e directives are considered equivalent for parsing.
|
119 | *
|
120 | * The returned function parses a specified string, returning the corresponding date or null if the string could not be parsed according to this format’s specifier.
|
121 | * Parsing is strict: if the specified string does not exactly match the associated specifier, this method returns null.
|
122 | *
|
123 | * 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,
|
124 | * 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.)
|
125 | * If a more flexible parser is desired, try multiple formats sequentially until one returns non-null.
|
126 | *
|
127 | * @param specifier A specifier string for the date format.
|
128 | */
|
129 | parse(specifier: string): (dateString: string) => (Date | null);
|
130 | /**
|
131 | * Equivalent to locale.format (TimeLocaleObject.format), except all directives are interpreted as Coordinated Universal Time (UTC) rather than local time.
|
132 | *
|
133 | * @param specifier A specifier string for the date format.
|
134 | */
|
135 | utcFormat(specifier: string): (date: Date) => string;
|
136 | /**
|
137 | * Equivalent to locale.parse (TimeLocaleObject.parse), except all directives are interpreted as Coordinated Universal Time (UTC) rather than local time.
|
138 | *
|
139 | * @param specifier A specifier string for the date format.
|
140 | */
|
141 | utcParse(specifier: string): (dateString: string) => (Date | null);
|
142 | }
|
143 |
|
144 | /**
|
145 | * Create a new time-locale-based object which exposes time-formatting
|
146 | * methods for the specified locale definition.
|
147 | *
|
148 | * @param definition A time locale definition.
|
149 | */
|
150 | export function timeFormatLocale(definition: TimeLocaleDefinition): TimeLocaleObject;
|
151 |
|
152 | /**
|
153 | * Create a new time-locale-based object which exposes time-formatting
|
154 | * methods for the specified locale definition. The new time locale definition
|
155 | * will be set as the new default time locale.
|
156 | *
|
157 | * @param definition A time locale definition.
|
158 | */
|
159 | export function timeFormatDefaultLocale(definition: TimeLocaleDefinition): TimeLocaleObject;
|
160 |
|
161 | /**
|
162 | * Returns a new formatter for the given string specifier. The returned function formats a specified date, returning the corresponding string.
|
163 | *
|
164 | * An alias for locale.format (TimeLocaleObject.format) on the default locale.
|
165 | *
|
166 | * @param specifier A specifier string for the date format.
|
167 | */
|
168 | export function timeFormat(specifier: string): (date: Date) => string;
|
169 |
|
170 | /**
|
171 | * Returns a new parser for the given string specifier.
|
172 | *
|
173 | * An alias for locale.parse (TimeLocaleObject.parse) on the default locale.
|
174 | *
|
175 | * @param specifier A specifier string for the date format.
|
176 | */
|
177 | export function timeParse(specifier: string): (dateString: string) => (Date | null);
|
178 |
|
179 | /**
|
180 | * Equivalent to timeFormat, except all directives are interpreted as Coordinated Universal Time (UTC) rather than local time.
|
181 | *
|
182 | * An alias for locale.utcFormat (TimeLocaleObject.utcFormat) on the default locale.
|
183 | *
|
184 | * @param specifier A specifier string for the date format.
|
185 | */
|
186 | export function utcFormat(specifier: string): (date: Date) => string;
|
187 |
|
188 | /**
|
189 | * Equivalent to timeParse, except all directives are interpreted as Coordinated Universal Time (UTC) rather than local time.
|
190 | *
|
191 | * An alias for locale.utcParse (TimeLocaleObject.utcParse) on the default locale.
|
192 | *
|
193 | * @param specifier A specifier string for the date format.
|
194 | */
|
195 | export function utcParse(specifier: string): (dateString: string) => (Date | null);
|
196 |
|
197 | /**
|
198 | * The full ISO 8601 UTC time formatter. Where available, this method will use Date.toISOString to format.
|
199 | *
|
200 | * @param date A date to format.
|
201 | */
|
202 | export function isoFormat(date: Date): string;
|
203 |
|
204 | /**
|
205 | * The full ISO 8601 UTC time parser. Where available, this method will use the Date constructor to parse strings.
|
206 | * If you depend on strict validation of the input format according to ISO 8601, you should construct a UTC parser function using utcParse.
|
207 | *
|
208 | * @param dateString A string encoded date to parse.
|
209 | */
|
210 | export function isoParse(dateString: string): Date | null;
|