1 | // Type definitions for D3JS d3-format module 2.0
|
2 | // Project: https://github.com/d3/d3-format/, https://d3js.org/d3-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 | // denisname <https://github.com/denisname>
|
7 | // Nathan Bierema <https://github.com/Methuselah96>
|
8 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
9 |
|
10 | // Last module patch version validated against: 2.0.0
|
11 |
|
12 | /**
|
13 | * Specification of locale to use when creating a new FormatLocaleObject
|
14 | */
|
15 | export interface FormatLocaleDefinition {
|
16 | /**
|
17 | * The decimal point (e.g., ".")
|
18 | */
|
19 | decimal: string;
|
20 | /**
|
21 | * The group separator (e.g., ","). Note that the thousands property is a misnomer, as
|
22 | * the grouping definition allows groups other than thousands.
|
23 | */
|
24 | thousands: string;
|
25 | /**
|
26 | * The array of group sizes (e.g., [3]), cycled as needed.
|
27 | */
|
28 | grouping: number[];
|
29 | /**
|
30 | * The currency prefix and suffix (e.g., ["$", ""]).
|
31 | */
|
32 | currency: [string, string];
|
33 | /**
|
34 | * An optional array of ten strings to replace the numerals 0-9.
|
35 | */
|
36 | numerals?: string[];
|
37 | /**
|
38 | * An optional symbol to replace the `percent` suffix; the percent suffix (defaults to "%").
|
39 | */
|
40 | percent?: string;
|
41 | /**
|
42 | * Optional; the minus sign (defaults to "−").
|
43 | */
|
44 | minus?: string;
|
45 | /**
|
46 | * Optional; the not-a-number value (defaults "NaN").
|
47 | */
|
48 | nan?: string;
|
49 | }
|
50 |
|
51 | /**
|
52 | * A Format Locale Object
|
53 | */
|
54 | export interface FormatLocaleObject {
|
55 | /**
|
56 | * Returns a new format function for the given string specifier. The returned function
|
57 | * takes a number as the only argument, and returns a string representing the formatted number.
|
58 | *
|
59 | * @param specifier A Specifier string.
|
60 | * @throws Error on invalid format specifier.
|
61 | */
|
62 | format(specifier: string): (n: number | { valueOf(): number }) => string;
|
63 |
|
64 | /**
|
65 | * Returns a new format function for the given string specifier. The returned function
|
66 | * takes a number as the only argument, and returns a string representing the formatted number.
|
67 | * The returned function will convert values to the units of the appropriate SI prefix for the
|
68 | * specified numeric reference value before formatting in fixed point notation.
|
69 | *
|
70 | * @param specifier A Specifier string.
|
71 | * @param value The reference value to determine the appropriate SI prefix.
|
72 | * @throws Error on invalid format specifier.
|
73 | */
|
74 | formatPrefix(specifier: string, value: number): (n: number | { valueOf(): number }) => string;
|
75 | }
|
76 |
|
77 | /**
|
78 | * A Format Specifier
|
79 | *
|
80 | * For details see: {@link https://github.com/d3/d3-format#locale_format}
|
81 | */
|
82 | export interface FormatSpecifierObject {
|
83 | /**
|
84 | * fill can be any character. The presence of a fill character is signaled by the align character following it.
|
85 | */
|
86 | fill?: string;
|
87 | /**
|
88 | * Alignment used for format, as set by choosing one of the following:
|
89 | *
|
90 | * '>' - Forces the field to be right-aligned within the available space. (Default behavior).
|
91 | * '<' - Forces the field to be left-aligned within the available space.
|
92 | * '^' - Forces the field to be centered within the available space.
|
93 | * '=' - Like '>', but with any sign and symbol to the left of any padding.
|
94 | */
|
95 | align?: string;
|
96 | /**
|
97 | * The sign can be:
|
98 | *
|
99 | * '-' - nothing for positive and a minus sign for negative. (Default behavior.)
|
100 | * '+' - a plus sign for positive and a minus sign for negative.
|
101 | * '(' - nothing for positive and parentheses for negative.
|
102 | * ' ' (space) - a space for positive and a minus sign for negative.
|
103 | *
|
104 | */
|
105 | sign?: string;
|
106 | /**
|
107 | * The symbol can be:
|
108 | *
|
109 | * '$' - apply currency symbols per the locale definition.
|
110 | * '#' - for binary, octal, or hexadecimal notation, prefix by 0b, 0o, or 0x, respectively.
|
111 | * '' (none) - no symbol. (Default behavior.)
|
112 | */
|
113 | symbol?: string;
|
114 | /**
|
115 | * The zero (0) option enables zero-padding; this implicitly sets fill to 0 and align to =.
|
116 | */
|
117 | zero?: string;
|
118 | /**
|
119 | * The width defines the minimum field width;
|
120 | * if not specified, then the width will be determined by the content.
|
121 | */
|
122 | width?: string;
|
123 | /**
|
124 | * The comma (,) option enables the use of a group separator, such as a comma for thousands.
|
125 | */
|
126 | comma?: string;
|
127 | /**
|
128 | * Depending on the type, the precision either indicates the number of digits that follow the decimal point (types 'f' and '%'),
|
129 | * or the number of significant digits (types '' (none), 'e', 'g', 'r', 's' and 'p'). If the precision is not specified,
|
130 | * it defaults to 6 for all types except '' (none), which defaults to 12.
|
131 | * Precision is ignored for integer formats (types 'b', 'o', 'd', 'x', 'X' and 'c').
|
132 | *
|
133 | * See precisionFixed and precisionRound for help picking an appropriate precision.
|
134 | */
|
135 | precision?: string;
|
136 | /**
|
137 | * The '~' option trims insignificant trailing zeros across all format types.
|
138 | * This is most commonly used in conjunction with types 'r', 'e', 's' and '%'.
|
139 | */
|
140 | trim?: string;
|
141 | /**
|
142 | * The available type values are:
|
143 | *
|
144 | * 'e' - exponent notation.
|
145 | * 'f' - fixed point notation.
|
146 | * 'g' - either decimal or exponent notation, rounded to significant digits.
|
147 | * 'r' - decimal notation, rounded to significant digits.
|
148 | * 's' - decimal notation with an SI prefix, rounded to significant digits.
|
149 | * '%' - multiply by 100, and then decimal notation with a percent sign.
|
150 | * 'p' - multiply by 100, round to significant digits, and then decimal notation with a percent sign.
|
151 | * 'b' - binary notation, rounded to integer.
|
152 | * 'o' - octal notation, rounded to integer.
|
153 | * 'd' - decimal notation, rounded to integer.
|
154 | * 'x' - hexadecimal notation, using lower-case letters, rounded to integer.
|
155 | * 'X' - hexadecimal notation, using upper-case letters, rounded to integer.
|
156 | * 'c' - converts the integer to the corresponding unicode character before printing.
|
157 | *
|
158 | * The type '' (none) is also supported as shorthand for '~g' (with a default precision of 12 instead of 6), and
|
159 | * the type 'n' is shorthand for ',g'. For the 'g', 'n' and '' (none) types,
|
160 | * decimal notation is used if the resulting string would have precision or fewer digits; otherwise, exponent notation is used.
|
161 | */
|
162 | type?: string;
|
163 | }
|
164 |
|
165 | /**
|
166 | * Create a new locale-based object which exposes format(...) and formatPrefix(...)
|
167 | * methods for the specified locale.
|
168 | *
|
169 | * @param locale A Format locale definition.
|
170 | */
|
171 | export function formatLocale(locale: FormatLocaleDefinition): FormatLocaleObject;
|
172 |
|
173 | /**
|
174 | * Create a new locale-based object which exposes format(...) and formatPrefix(...)
|
175 | * methods for the specified locale definition. The specified locale definition will be
|
176 | * set as the new default locale definition.
|
177 | *
|
178 | * @param defaultLocale A Format locale definition to be used as default.
|
179 | */
|
180 | export function formatDefaultLocale(defaultLocale: FormatLocaleDefinition): FormatLocaleObject;
|
181 |
|
182 | /**
|
183 | * Returns a new format function for the given string specifier. The returned function
|
184 | * takes a number as the only argument, and returns a string representing the formatted number.
|
185 | *
|
186 | * Uses the current default locale.
|
187 | *
|
188 | * The general form of a specifier is [[fill]align][sign][symbol][0][width][,][.precision][~][type].
|
189 | * For reference, an explanation of the segments of the specifier string, refer to the FormatSpecifier interface properties.
|
190 | *
|
191 | * @param specifier A Specifier string.
|
192 | * @throws Error on invalid format specifier.
|
193 | */
|
194 | export function format(specifier: string): (n: number | { valueOf(): number }) => string;
|
195 |
|
196 | /**
|
197 | * Returns a new format function for the given string specifier. The returned function
|
198 | * takes a number as the only argument, and returns a string representing the formatted number.
|
199 | * The returned function will convert values to the units of the appropriate SI prefix for the
|
200 | * specified numeric reference value before formatting in fixed point notation.
|
201 | *
|
202 | * Uses the current default locale.
|
203 | *
|
204 | * The general form of a specifier is [[fill]align][sign][symbol][0][width][,][.precision][~][type].
|
205 | * For reference, an explanation of the segments of the specifier string, refer to the FormatSpecifier interface properties.
|
206 | *
|
207 | * @param specifier A Specifier string.
|
208 | * @param value The reference value to determine the appropriate SI prefix.
|
209 | * @throws Error on invalid format specifier.
|
210 | */
|
211 | export function formatPrefix(specifier: string, value: number): (n: number | { valueOf(): number }) => string;
|
212 |
|
213 | /**
|
214 | * A Format Specifier
|
215 | *
|
216 | * For details see: {@link https://github.com/d3/d3-format#locale_format}
|
217 | */
|
218 | export class FormatSpecifier {
|
219 | /**
|
220 | * Given the specified specifier object, returning an object with exposed fields that correspond to the format specification mini-language and a toString method that reconstructs the specifier.
|
221 | * @param specifier A specifier object.
|
222 | */
|
223 | constructor(specifier: FormatSpecifierObject);
|
224 | /**
|
225 | * fill can be any character. The presence of a fill character is signaled by the align character following it.
|
226 | */
|
227 | fill: string;
|
228 | /**
|
229 | * Alignment used for format, as set by choosing one of the following:
|
230 | *
|
231 | * '>' - Forces the field to be right-aligned within the available space. (Default behavior).
|
232 | * '<' - Forces the field to be left-aligned within the available space.
|
233 | * '^' - Forces the field to be centered within the available space.
|
234 | * '=' - Like '>', but with any sign and symbol to the left of any padding.
|
235 | */
|
236 | align: '>' | '<' | '^' | '=';
|
237 | /**
|
238 | * The sign can be:
|
239 | *
|
240 | * '-' - nothing for positive and a minus sign for negative. (Default behavior.)
|
241 | * '+' - a plus sign for positive and a minus sign for negative.
|
242 | * '(' - nothing for positive and parentheses for negative.
|
243 | * ' ' (space) - a space for positive and a minus sign for negative.
|
244 | *
|
245 | */
|
246 | sign: '-' | '+' | '(' | ' ';
|
247 | /**
|
248 | * The symbol can be:
|
249 | *
|
250 | * '$' - apply currency symbols per the locale definition.
|
251 | * '#' - for binary, octal, or hexadecimal notation, prefix by 0b, 0o, or 0x, respectively.
|
252 | * '' (none) - no symbol. (Default behavior.)
|
253 | */
|
254 | symbol: '$' | '#' | '';
|
255 | /**
|
256 | * The zero (0) option enables zero-padding; this implicitly sets fill to 0 and align to =.
|
257 | */
|
258 | zero: boolean;
|
259 | /**
|
260 | * The width defines the minimum field width;
|
261 | * if not specified, then the width will be determined by the content.
|
262 | */
|
263 | width: number | undefined;
|
264 | /**
|
265 | * The comma (,) option enables the use of a group separator, such as a comma for thousands.
|
266 | */
|
267 | comma: boolean;
|
268 | /**
|
269 | * Depending on the type, the precision either indicates the number of digits that follow the decimal point (types 'f' and '%'),
|
270 | * or the number of significant digits (types '' (none), 'e', 'g', 'r', 's' and 'p'). If the precision is not specified,
|
271 | * it defaults to 6 for all types except '' (none), which defaults to 12.
|
272 | * Precision is ignored for integer formats (types 'b', 'o', 'd', 'x', 'X' and 'c').
|
273 | *
|
274 | * See precisionFixed and precisionRound for help picking an appropriate precision.
|
275 | */
|
276 | precision: number | undefined;
|
277 | /**
|
278 | * The '~' option trims insignificant trailing zeros across all format types.
|
279 | * This is most commonly used in conjunction with types 'r', 'e', 's' and '%'.
|
280 | */
|
281 | trim: boolean;
|
282 | /**
|
283 | * The available type values are:
|
284 | *
|
285 | * 'e' - exponent notation.
|
286 | * 'f' - fixed point notation.
|
287 | * 'g' - either decimal or exponent notation, rounded to significant digits.
|
288 | * 'r' - decimal notation, rounded to significant digits.
|
289 | * 's' - decimal notation with an SI prefix, rounded to significant digits.
|
290 | * '%' - multiply by 100, and then decimal notation with a percent sign.
|
291 | * 'p' - multiply by 100, round to significant digits, and then decimal notation with a percent sign.
|
292 | * 'b' - binary notation, rounded to integer.
|
293 | * 'o' - octal notation, rounded to integer.
|
294 | * 'd' - decimal notation, rounded to integer.
|
295 | * 'x' - hexadecimal notation, using lower-case letters, rounded to integer.
|
296 | * 'X' - hexadecimal notation, using upper-case letters, rounded to integer.
|
297 | * 'c' - converts the integer to the corresponding unicode character before printing.
|
298 | *
|
299 | * The type '' (none) is also supported as shorthand for '~g' (with a default precision of 12 instead of 6), and
|
300 | * the type 'n' is shorthand for ',g'. For the 'g', 'n' and '' (none) types,
|
301 | * decimal notation is used if the resulting string would have precision or fewer digits; otherwise, exponent notation is used.
|
302 | */
|
303 | type: 'e' | 'f' | 'g' | 'r' | 's' | '%' | 'p' | 'b' | 'o' | 'd' | 'x' | 'X' | 'c' | '' | 'n';
|
304 | /**
|
305 | * Return the object as a specifier string.
|
306 | */
|
307 | toString(): string;
|
308 | }
|
309 |
|
310 | /**
|
311 | * Parses the specified specifier, returning an object with exposed fields that correspond to the
|
312 | * format specification mini-language and a toString method that reconstructs the specifier.
|
313 | *
|
314 | * The general form of a specifier is [[fill]align][sign][symbol][0][width][,][.precision][~][type].
|
315 | * For reference, an explanation of the segments of the specifier string, refer to the FormatSpecifier interface properties.
|
316 | *
|
317 | * @param specifier A specifier string.
|
318 | * @throws Error on invalid format specifier.
|
319 | */
|
320 | export function formatSpecifier(specifier: string): FormatSpecifier;
|
321 |
|
322 | /**
|
323 | * Returns a suggested decimal precision for fixed point notation given the specified numeric step value.
|
324 | *
|
325 | * @param step The step represents the minimum absolute difference between values that will be formatted.
|
326 | * (This assumes that the values to be formatted are also multiples of step.)
|
327 | */
|
328 | export function precisionFixed(step: number): number;
|
329 |
|
330 | /**
|
331 | * Returns a suggested decimal precision for use with locale.formatPrefix given the specified
|
332 | * numeric step and reference value.
|
333 | *
|
334 | * @param step The step represents the minimum absolute difference between values that will be formatted.
|
335 | * (This assumes that the values to be formatted are also multiples of step.)
|
336 | * @param value Reference value determines which SI prefix will be used.
|
337 | */
|
338 | export function precisionPrefix(step: number, value: number): number;
|
339 |
|
340 | /**
|
341 | * Returns a suggested decimal precision for format types that round to significant digits
|
342 | * given the specified numeric step and max values.
|
343 | *
|
344 | * @param step The step represents the minimum absolute difference between values that will be formatted.
|
345 | * (This assumes that the values to be formatted are also multiples of step.)
|
346 | * @param max max represents the largest absolute value that will be formatted.
|
347 | */
|
348 | export function precisionRound(step: number, max: number): number;
|