UNPKG

11.7 kBTypeScriptView Raw
1import {List} from 'immutable';
2
3import {Value} from './index';
4
5/**
6 * Sass's [number type](https://sass-lang.com/documentation/values/numbers).
7 *
8 * @category Custom Function
9 */
10export class SassNumber extends Value {
11 /**
12 * Creates a new number with more complex units than just a single numerator.
13 *
14 * Upon construction, any compatible numerator and denominator units are
15 * simplified away according to the conversion factor between them.
16 *
17 * @param value - The number's numeric value.
18 *
19 * @param unit - If this is a string, it's used as the single numerator unit
20 * for the number.
21 *
22 * @param unit.numeratorUnits - If passed, these are the numerator units to
23 * use for the number. This may be either a plain JavaScript array or an
24 * immutable {@link List} from the [`immutable`
25 * package](https://immutable-js.com/).
26 *
27 * @param unit.denominatorUnits - If passed, these are the denominator units
28 * to use for the number. This may be either a plain JavaScript array or an
29 * immutable {@link List} from the [`immutable`
30 * package](https://immutable-js.com/).
31 */
32 constructor(
33 value: number,
34 unit?:
35 | string
36 | {
37 numeratorUnits?: string[] | List<string>;
38 denominatorUnits?: string[] | List<string>;
39 }
40 );
41
42 /** This number's numeric value. */
43 get value(): number;
44
45 /** Whether {@link value} is an integer according to Sass's equality logic. */
46 get isInt(): boolean;
47
48 /**
49 * If {@link value} is an integer according to {@link isInt}, returns {@link
50 * value} rounded to that integer. If it's not an integer, returns `null`.
51 */
52 get asInt(): number | null;
53
54 /**
55 * This number's numerator units as an immutable {@link List} from the
56 * [`immutable` package](https://immutable-js.com/).
57 */
58 get numeratorUnits(): List<string>;
59
60 /**
61 * This number's denominator units as an immutable {@link List} from the
62 * [`immutable` package](https://immutable-js.com/).
63 */
64 get denominatorUnits(): List<string>;
65
66 /** Whether this number has any numerator or denominator units. */
67 get hasUnits(): boolean;
68
69 /**
70 * If {@link value} is an integer according to {@link isInt}, returns it
71 * rounded to that integer. Otherwise, throws an error.
72 *
73 * @param name - The name of the function argument `this` came from (without
74 * the `$`) if it came from an argument. Used for error reporting.
75 */
76 assertInt(name?: string): number;
77
78 /**
79 * Returns {@link value} if it's within `min` and `max`. If {@link value} is
80 * equal to `min` or `max` according to Sass's equality, returns `min` or
81 * `max` respectively. Otherwise, throws an error.
82 *
83 * @param name - The name of the function argument `this` came from (without
84 * the `$`) if it came from an argument. Used for error reporting.
85 */
86 assertInRange(min: number, max: number, name?: string): number;
87
88 /**
89 * If this number has no units, returns it. Otherwise, throws an error.
90 *
91 * @param name - The name of the function argument `this` came from (without
92 * the `$`) if it came from an argument. Used for error reporting.
93 */
94 assertNoUnits(name?: string): SassNumber;
95
96 /**
97 * If this number has `unit` as its only unit (and as a numerator), returns
98 * this number. Otherwise, throws an error.
99 *
100 * @param name - The name of the function argument `this` came from (without
101 * the `$`) if it came from an argument. Used for error reporting.
102 */
103 assertUnit(unit: string, name?: string): SassNumber;
104
105 /** Whether this number has `unit` as its only unit (and as a numerator). */
106 hasUnit(unit: string): boolean;
107
108 /**
109 * Whether this has exactly one numerator unit, and that unit is compatible
110 * with `unit`.
111 */
112 compatibleWithUnit(unit: string): boolean;
113
114 /**
115 * Returns a copy of this number, converted to the units represented by
116 * `newNumerators` and `newDenominators`.
117 *
118 * @throws `Error` if this number's units are incompatible with
119 * `newNumerators` and `newDenominators`; or if this number is unitless and
120 * either `newNumerators` or `newDenominators` are not empty, or vice-versa.
121 *
122 * @param newNumerators - The numerator units to convert this number to. This
123 * may be either a plain JavaScript array or an immutable {@link List} from
124 * the [`immutable` package](https://immutable-js.com/).
125 *
126 * @param newDenominators - The denominator units to convert this number to.
127 * This may be either a plain JavaScript array or an immutable {@link List}
128 * from the [`immutable` package](https://immutable-js.com/).
129 *
130 * @param name - The name of the function argument `this` came from (without
131 * the `$`) if it came from an argument. Used for error reporting.
132 */
133 convert(
134 newNumerators: string[] | List<string>,
135 newDenominators: string[] | List<string>,
136 name?: string
137 ): SassNumber;
138
139 /**
140 * Returns a copy of this number, converted to the same units as `other`.
141 *
142 * @throws `Error` if this number's units are incompatible with `other`'s
143 * units, or if either number is unitless but the other is not.
144 *
145 * @param name - The name of the function argument `this` came from (without
146 * the `$`) if it came from an argument. Used for error reporting.
147 *
148 * @param otherName - The name of the function argument `other` came from
149 * (without the `$`) if it came from an argument. Used for error reporting.
150 */
151 convertToMatch(
152 other: SassNumber,
153 name?: string,
154 otherName?: string
155 ): SassNumber;
156
157 /**
158 * Returns {@link value}, converted to the units represented by
159 * `newNumerators` and `newDenominators`.
160 *
161 * @throws `Error` if this number's units are incompatible with
162 * `newNumerators` and `newDenominators`; or if this number is unitless and
163 * either `newNumerators` or `newDenominators` are not empty, or vice-versa.
164 *
165 * @param newNumerators - The numerator units to convert {@link value} to.
166 * This may be either a plain JavaScript array or an immutable {@link List}
167 * from the [`immutable` package](https://immutable-js.com/).
168 *
169 * @param newDenominators - The denominator units to convert {@link value} to.
170 * This may be either a plain JavaScript array or an immutable {@link List}
171 * from the [`immutable` package](https://immutable-js.com/).
172 *
173 * @param name - The name of the function argument `this` came from (without
174 * the `$`) if it came from an argument. Used for error reporting.
175 */
176 convertValue(
177 newNumerators: string[] | List<string>,
178 newDenominators: string[] | List<string>,
179 name?: string
180 ): number;
181
182 /**
183 * Returns {@link value}, converted to the same units as `other`.
184 *
185 * @throws `Error` if this number's units are incompatible with `other`'s
186 * units, or if either number is unitless but the other is not.
187 *
188 * @param name - The name of the function argument `this` came from (without
189 * the `$`) if it came from an argument. Used for error reporting.
190 *
191 * @param otherName - The name of the function argument `other` came from
192 * (without the `$`) if it came from an argument. Used for error reporting.
193 */
194 convertValueToMatch(
195 other: SassNumber,
196 name?: string,
197 otherName?: string
198 ): number;
199
200 /**
201 * Returns a copy of this number, converted to the units represented by
202 * `newNumerators` and `newDenominators`.
203 *
204 * Unlike {@link convert} this does *not* throw an error if this number is
205 * unitless and either `newNumerators` or `newDenominators` are not empty, or
206 * vice-versa. Instead, it treats all unitless numbers as convertible to and
207 * from all units without changing the value.
208 *
209 * @throws `Error` if this number's units are incompatible with
210 * `newNumerators` and `newDenominators`.
211 *
212 * @param newNumerators - The numerator units to convert this number to. This
213 * may be either a plain JavaScript array or an immutable {@link List} from
214 * the [`immutable` package](https://immutable-js.com/).
215 *
216 * @param newDenominators - The denominator units to convert this number to.
217 * This may be either a plain JavaScript array or an immutable {@link List}
218 * from the [`immutable` package](https://immutable-js.com/).
219 *
220 * @param name - The name of the function argument `this` came from (without
221 * the `$`) if it came from an argument. Used for error reporting.
222 */
223 coerce(
224 newNumerators: string[] | List<string>,
225 newDenominators: string[] | List<string>,
226 name?: string
227 ): SassNumber;
228
229 /**
230 * Returns a copy of this number, converted to the units represented by
231 * `newNumerators` and `newDenominators`.
232 *
233 * Unlike {@link convertToMatch} this does *not* throw an error if this number
234 * is unitless and either `newNumerators` or `newDenominators` are not empty,
235 * or vice-versa. Instead, it treats all unitless numbers as convertible to
236 * and from all units without changing the value.
237 *
238 * @throws `Error` if this number's units are incompatible with `other`'s
239 * units.
240 *
241 * @param name - The name of the function argument `this` came from (without
242 * the `$`) if it came from an argument. Used for error reporting.
243 *
244 * @param otherName - The name of the function argument `other` came from
245 * (without the `$`) if it came from an argument. Used for error reporting.
246 */
247 coerceToMatch(
248 other: SassNumber,
249 name?: string,
250 otherName?: string
251 ): SassNumber;
252
253 /**
254 * Returns {@link value}, converted to the units represented by
255 * `newNumerators` and `newDenominators`.
256 *
257 * Unlike {@link convertValue} this does *not* throw an error if this number
258 * is unitless and either `newNumerators` or `newDenominators` are not empty,
259 * or vice-versa. Instead, it treats all unitless numbers as convertible to
260 * and from all units without changing the value.
261 *
262 * @throws `Error` if this number's units are incompatible with
263 * `newNumerators` and `newDenominators`.
264 *
265 * @param newNumerators - The numerator units to convert {@link value} to.
266 * This may be either a plain JavaScript array or an immutable {@link List}
267 * from the [`immutable` package](https://immutable-js.com/).
268 *
269 * @param newDenominators - The denominator units to convert {@link value} to.
270 * This may be either a plain JavaScript array or an immutable {@link List}
271 * from the [`immutable` package](https://immutable-js.com/).
272 *
273 * @param name - The name of the function argument `this` came from (without
274 * the `$`) if it came from an argument. Used for error reporting.
275 */
276 coerceValue(
277 newNumerators: string[] | List<string>,
278 newDenominators: string[] | List<string>,
279 name?: string
280 ): number;
281
282 /**
283 * Returns {@link value}, converted to the units represented by
284 * `newNumerators` and `newDenominators`.
285 *
286 * Unlike {@link convertValueToMatch} this does *not* throw an error if this
287 * number is unitless and either `newNumerators` or `newDenominators` are not
288 * empty, or vice-versa. Instead, it treats all unitless numbers as
289 * convertible to and from all units without changing the value.
290 *
291 * @throws `Error` if this number's units are incompatible with `other`'s
292 * units.
293 *
294 * @param name - The name of the function argument `this` came from (without
295 * the `$`) if it came from an argument. Used for error reporting.
296 *
297 * @param otherName - The name of the function argument `other` came from
298 * (without the `$`) if it came from an argument. Used for error reporting.
299 */
300 coerceValueToMatch(
301 other: SassNumber,
302 name?: string,
303 otherName?: string
304 ): number;
305}