UNPKG

10 kBTypeScriptView Raw
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 */
14export 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 */
53export 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 */
150export 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 */
159export 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 */
168export 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 */
177export 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 */
186export 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 */
195export 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 */
202export 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 */
210export function isoParse(dateString: string): Date | null;