OLD | NEW |
| (Empty) |
1 // Copyright (c) 2012, the Dart project authors. Please see the AUTHORS file | |
2 // for details. All rights reserved. Use of this source code is governed by a | |
3 // BSD-style license that can be found in the LICENSE file. | |
4 | |
5 part of dart.core; | |
6 | |
7 /** | |
8 * An integer or floating-point number. | |
9 * | |
10 * It is a compile-time error for any type other than [int] or [double] | |
11 * to attempt to extend or implement num. | |
12 */ | |
13 abstract class num implements Comparable<num> { | |
14 /** | |
15 * Test whether this value is numerically equal to `other`. | |
16 * | |
17 * If both operands are doubles, they are equal if they have the same | |
18 * representation, except that: | |
19 * | |
20 * * zero and minus zero (0.0 and -0.0) are considered equal. They | |
21 * both have the numerical value zero. | |
22 * * NaN is not equal to anything, including NaN. If either operand is | |
23 * NaN, the result is always false. | |
24 * | |
25 * If one operand is a double and the other is an int, they are equal if | |
26 * the double has an integer value (finite with no fractional part) and | |
27 * `identical(doubleValue.toInt(), intValue)` is true. | |
28 * | |
29 * If both operands are integers, they are equal if they have the same value. | |
30 * | |
31 * Returns false if `other` is not a [num]. | |
32 * | |
33 * Notice that the behavior for NaN is non-reflexive. This means that | |
34 * equality of double values is not a proper equality relation, as is | |
35 * otherwise required of `operator==`. Using NaN in, e.g., a [HashSet] | |
36 * will fail to work. The behavior is the standard IEEE-754 equality of | |
37 * doubles. | |
38 * | |
39 * If you can avoid NaN values, the remaining doubles do have a proper eqality | |
40 * relation, and can be used safely. | |
41 * | |
42 * Use [compareTo] for a comparison that distinguishes zero and minus zero, | |
43 * and that considers NaN values as equal. | |
44 */ | |
45 bool operator==(Object other); | |
46 | |
47 /** | |
48 * Returns a hash code for a numerical value. | |
49 * | |
50 * The hash code is compatible with equality. It returns the same value | |
51 * for an [int] and a [double] with the same numerical value, and therefore | |
52 * the same value for the doubles zero and minus zero. | |
53 * | |
54 * No guarantees are made about the hash code of NaN. | |
55 */ | |
56 int get hashCode; | |
57 | |
58 /** | |
59 * Compares this to `other`. | |
60 * | |
61 * Returns a negative number if `this` is less than `other`, zero if they are | |
62 * equal, and a positive number if `this` is greater than `other`. | |
63 * | |
64 * The orderding represented by this method is a total ordering of [num] | |
65 * values. All distinct doubles are non-equal, as are all distinct integers, | |
66 * but integers are equal to doubles if they have the same numerical | |
67 * value. | |
68 * | |
69 * For ordering, the double NaN value is considered equal to itself, and | |
70 * greater than any numeric value (unlike its behavior in `operator==`). | |
71 * | |
72 * The double value -0.0 is considered less than 0.0 (and the integer 0), but | |
73 * greater than any non-zero negative value. | |
74 * | |
75 * Positive infinity is greater than any finite value (any value apart from | |
76 * itself and NaN), and negative infinity is less than any other value. | |
77 * | |
78 * All other values are compared using their numeric value. | |
79 */ | |
80 int compareTo(num other); | |
81 | |
82 /** Addition operator. */ | |
83 num operator +(num other); | |
84 | |
85 /** Subtraction operator. */ | |
86 num operator -(num other); | |
87 | |
88 /** Multiplication operator. */ | |
89 num operator *(num other); | |
90 | |
91 /** | |
92 * Euclidean modulo operator. | |
93 * | |
94 * Returns the remainder of the euclidean division. The euclidean division of | |
95 * two integers `a` and `b` yields two integers `q` and `r` such that | |
96 * `a == b * q + r` and `0 <= r < b.abs()`. | |
97 * | |
98 * The euclidean division is only defined for integers, but can be easily | |
99 * extended to work with doubles. In that case `r` may have a non-integer | |
100 * value, but it still verifies `0 <= r < |b|`. | |
101 * | |
102 * The sign of the returned value `r` is always positive. | |
103 * | |
104 * See [remainder] for the remainder of the truncating division. | |
105 */ | |
106 num operator %(num other); | |
107 | |
108 /** Division operator. */ | |
109 double operator /(num other); | |
110 | |
111 /** | |
112 * Truncating division operator. | |
113 * | |
114 * If either operand is a [double] then the result of the truncating division | |
115 * `a ~/ b` is equivalent to `(a / b).truncate().toInt()`. | |
116 * | |
117 * If both operands are [int]s then `a ~/ b` performs the truncating | |
118 * integer division. | |
119 */ | |
120 int operator ~/(num other); | |
121 | |
122 /** Negate operator. */ | |
123 num operator -(); | |
124 | |
125 /** | |
126 * Returns the remainder of the truncating division of `this` by [other]. | |
127 * | |
128 * The result `r` of this operation satisfies: | |
129 * `this == (this ~/ other) * other + r`. | |
130 * As a consequence the remainder `r` has the same sign as the divider `this`. | |
131 */ | |
132 num remainder(num other); | |
133 | |
134 /** Relational less than operator. */ | |
135 bool operator <(num other); | |
136 | |
137 /** Relational less than or equal operator. */ | |
138 bool operator <=(num other); | |
139 | |
140 /** Relational greater than operator. */ | |
141 bool operator >(num other); | |
142 | |
143 /** Relational greater than or equal operator. */ | |
144 bool operator >=(num other); | |
145 | |
146 /** True if the number is the double Not-a-Number value; otherwise, false. */ | |
147 bool get isNaN; | |
148 | |
149 /** | |
150 * True if the number is negative; otherwise, false. | |
151 * | |
152 * Negative numbers are those less than zero, and the double `-0.0`. | |
153 */ | |
154 bool get isNegative; | |
155 | |
156 /** | |
157 * True if the number is positive infinity or negative infinity; otherwise, | |
158 * false. | |
159 */ | |
160 bool get isInfinite; | |
161 | |
162 /** | |
163 * True if the number is finite; otherwise, false. | |
164 * | |
165 * The only non-finite numbers are NaN, positive infinitity and | |
166 * negative infinity. | |
167 */ | |
168 bool get isFinite; | |
169 | |
170 /** Returns the absolute value of this [num]. */ | |
171 num abs(); | |
172 | |
173 /** | |
174 * Returns minus one, zero or plus one depending on the sign and | |
175 * numerical value of the number. | |
176 * | |
177 * Returns minus one if the number is less than zero, | |
178 * plus one if the number is greater than zero, | |
179 * and zero if the number is equal to zero. | |
180 * | |
181 * Returns NaN if the number is the double NaN value. | |
182 * | |
183 * Returns a number of the same type as this number. | |
184 * For doubles, `-0.0.sign == -0.0`. | |
185 | |
186 * The result satisfies: | |
187 * | |
188 * n == n.sign * n.abs() | |
189 * | |
190 * for all numbers `n` (except NaN, because NaN isn't `==` to itself). | |
191 */ | |
192 num get sign; | |
193 | |
194 /** | |
195 * Returns the integer closest to `this`. | |
196 * | |
197 * Rounds away from zero when there is no closest integer: | |
198 * `(3.5).round() == 4` and `(-3.5).round() == -4`. | |
199 * | |
200 * If `this` is not finite (`NaN` or infinity), throws an [UnsupportedError]. | |
201 */ | |
202 int round(); | |
203 | |
204 /** | |
205 * Returns the greatest integer no greater than `this`. | |
206 * | |
207 * If `this` is not finite (`NaN` or infinity), throws an [UnsupportedError]. | |
208 */ | |
209 int floor(); | |
210 | |
211 /** | |
212 * Returns the least integer no smaller than `this`. | |
213 * | |
214 * If `this` is not finite (`NaN` or infinity), throws an [UnsupportedError]. | |
215 */ | |
216 int ceil(); | |
217 | |
218 /** | |
219 * Returns the integer obtained by discarding any fractional | |
220 * digits from `this`. | |
221 * | |
222 * If `this` is not finite (`NaN` or infinity), throws an [UnsupportedError]. | |
223 */ | |
224 int truncate(); | |
225 | |
226 /** | |
227 * Returns the double integer value closest to `this`. | |
228 * | |
229 * Rounds away from zero when there is no closest integer: | |
230 * `(3.5).roundToDouble() == 4` and `(-3.5).roundToDouble() == -4`. | |
231 * | |
232 * If this is already an integer valued double, including `-0.0`, or it is a | |
233 * non-finite double value, the value is returned unmodified. | |
234 * | |
235 * For the purpose of rounding, `-0.0` is considered to be below `0.0`, | |
236 * and `-0.0` is therefore considered closer to negative numbers than `0.0`. | |
237 * This means that for a value, `d` in the range `-0.5 < d < 0.0`, | |
238 * the result is `-0.0`. | |
239 * | |
240 * The result is always a double. | |
241 * If this is a numerically large integer, the result may be an infinite | |
242 * double. | |
243 */ | |
244 double roundToDouble(); | |
245 | |
246 /** | |
247 * Returns the greatest double integer value no greater than `this`. | |
248 * | |
249 * If this is already an integer valued double, including `-0.0`, or it is a | |
250 * non-finite double value, the value is returned unmodified. | |
251 * | |
252 * For the purpose of rounding, `-0.0` is considered to be below `0.0`. | |
253 * A number `d` in the range `0.0 < d < 1.0` will return `0.0`. | |
254 * | |
255 * The result is always a double. | |
256 * If this is a numerically large integer, the result may be an infinite | |
257 * double. | |
258 */ | |
259 double floorToDouble(); | |
260 | |
261 /** | |
262 * Returns the least double integer value no smaller than `this`. | |
263 * | |
264 * If this is already an integer valued double, including `-0.0`, or it is a | |
265 * non-finite double value, the value is returned unmodified. | |
266 * | |
267 * For the purpose of rounding, `-0.0` is considered to be below `0.0`. | |
268 * A number `d` in the range `-1.0 < d < 0.0` will return `-0.0`. | |
269 * | |
270 * The result is always a double. | |
271 * If this is a numerically large integer, the result may be an infinite | |
272 * double. | |
273 */ | |
274 double ceilToDouble(); | |
275 | |
276 /** | |
277 * Returns the double integer value obtained by discarding any fractional | |
278 * digits from the double value of `this`. | |
279 * | |
280 * If this is already an integer valued double, including `-0.0`, or it is a | |
281 * non-finite double value, the value is returned unmodified. | |
282 * | |
283 * For the purpose of rounding, `-0.0` is considered to be below `0.0`. | |
284 * A number `d` in the range `-1.0 < d < 0.0` will return `-0.0`, and | |
285 * in the range `0.0 < d < 1.0` it will return 0.0. | |
286 * | |
287 * The result is always a double. | |
288 * If this is a numerically large integer, the result may be an infinite | |
289 * double. | |
290 */ | |
291 double truncateToDouble(); | |
292 | |
293 /** | |
294 * Returns this [num] clamped to be in the range [lowerLimit]-[upperLimit]. | |
295 * | |
296 * The comparison is done using [compareTo] and therefore takes `-0.0` into | |
297 * account. This also implies that [double.NAN] is treated as the maximal | |
298 * double value. | |
299 */ | |
300 num clamp(num lowerLimit, num upperLimit); | |
301 | |
302 /** Truncates this [num] to an integer and returns the result as an [int]. */ | |
303 int toInt(); | |
304 | |
305 /** | |
306 * Return this [num] as a [double]. | |
307 * | |
308 * If the number is not representable as a [double], an | |
309 * approximation is returned. For numerically large integers, the | |
310 * approximation may be infinite. | |
311 */ | |
312 double toDouble(); | |
313 | |
314 /** | |
315 * Returns a decimal-point string-representation of `this`. | |
316 * | |
317 * Converts `this` to a [double] before computing the string representation. | |
318 * | |
319 * If the absolute value of `this` is greater or equal to `10^21` then this | |
320 * methods returns an exponential representation computed by | |
321 * `this.toStringAsExponential()`. Otherwise the result | |
322 * is the closest string representation with exactly [fractionDigits] digits | |
323 * after the decimal point. If [fractionDigits] equals 0 then the decimal | |
324 * point is omitted. | |
325 * | |
326 * The parameter [fractionDigits] must be an integer satisfying: | |
327 * `0 <= fractionDigits <= 20`. | |
328 * | |
329 * Examples: | |
330 * | |
331 * 1.toStringAsFixed(3); // 1.000 | |
332 * (4321.12345678).toStringAsFixed(3); // 4321.123 | |
333 * (4321.12345678).toStringAsFixed(5); // 4321.12346 | |
334 * 123456789012345678901.toStringAsFixed(3); // 123456789012345683968.000 | |
335 * 1000000000000000000000.toStringAsFixed(3); // 1e+21 | |
336 * 5.25.toStringAsFixed(0); // 5 | |
337 */ | |
338 String toStringAsFixed(int fractionDigits); | |
339 | |
340 /** | |
341 * Returns an exponential string-representation of `this`. | |
342 * | |
343 * Converts `this` to a [double] before computing the string representation. | |
344 * | |
345 * If [fractionDigits] is given then it must be an integer satisfying: | |
346 * `0 <= fractionDigits <= 20`. In this case the string contains exactly | |
347 * [fractionDigits] after the decimal point. Otherwise, without the parameter, | |
348 * the returned string uses the shortest number of digits that accurately | |
349 * represent [this]. | |
350 * | |
351 * If [fractionDigits] equals 0 then the decimal point is omitted. | |
352 * Examples: | |
353 * | |
354 * 1.toStringAsExponential(); // 1e+0 | |
355 * 1.toStringAsExponential(3); // 1.000e+0 | |
356 * 123456.toStringAsExponential(); // 1.23456e+5 | |
357 * 123456.toStringAsExponential(3); // 1.235e+5 | |
358 * 123.toStringAsExponential(0); // 1e+2 | |
359 */ | |
360 String toStringAsExponential([int fractionDigits]); | |
361 | |
362 /** | |
363 * Converts `this` to a double and returns a string representation with | |
364 * exactly [precision] significant digits. | |
365 * | |
366 * The parameter [precision] must be an integer satisfying: | |
367 * `1 <= precision <= 21`. | |
368 * | |
369 * Examples: | |
370 * | |
371 * 1.toStringAsPrecision(2); // 1.0 | |
372 * 1e15.toStringAsPrecision(3); // 1.00+15 | |
373 * 1234567.toStringAsPrecision(3); // 1.23e+6 | |
374 * 1234567.toStringAsPrecision(9); // 1234567.00 | |
375 * 12345678901234567890.toStringAsPrecision(20); // 12345678901234567168 | |
376 * 12345678901234567890.toStringAsPrecision(14); // 1.2345678901235e+19 | |
377 * 0.00000012345.toStringAsPrecision(15); // 1.23450000000000e-7 | |
378 * 0.0000012345.toStringAsPrecision(15); // 0.00000123450000000000 | |
379 */ | |
380 String toStringAsPrecision(int precision); | |
381 | |
382 /** | |
383 * Returns the shortest string that correctly represent the input number. | |
384 * | |
385 * All [double]s in the range `10^-6` (inclusive) to `10^21` (exclusive) | |
386 * are converted to their decimal representation with at least one digit | |
387 * after the decimal point. For all other doubles, | |
388 * except for special values like `NaN` or `Infinity`, this method returns an | |
389 * exponential representation (see [toStringAsExponential]). | |
390 * | |
391 * Returns `"NaN"` for [double.NAN], `"Infinity"` for [double.INFINITY], and | |
392 * `"-Infinity"` for [double.MINUS_INFINITY]. | |
393 * | |
394 * An [int] is converted to a decimal representation with no decimal point. | |
395 * | |
396 * Examples: | |
397 * | |
398 * (0.000001).toString(); // "0.000001" | |
399 * (0.0000001).toString(); // "1e-7" | |
400 * (111111111111111111111.0).toString(); // "111111111111111110000.0" | |
401 * (100000000000000000000.0).toString(); // "100000000000000000000.0" | |
402 * (1000000000000000000000.0).toString(); // "1e+21" | |
403 * (1111111111111111111111.0).toString(); // "1.1111111111111111e+21" | |
404 * 1.toString(); // "1" | |
405 * 111111111111111111111.toString(); // "111111111111111110000" | |
406 * 100000000000000000000.toString(); // "100000000000000000000" | |
407 * 1000000000000000000000.toString(); // "1000000000000000000000" | |
408 * 1111111111111111111111.toString(); // "1111111111111111111111" | |
409 * 1.234e5.toString(); // 123400 | |
410 * 1234.5e6.toString(); // 1234500000 | |
411 * 12.345e67.toString(); // 1.2345e+68 | |
412 * | |
413 * Note: the conversion may round the output if the returned string | |
414 * is accurate enough to uniquely identify the input-number. | |
415 * For example the most precise representation of the [double] `9e59` equals | |
416 * `"899999999999999918767229449717619953810131273674690656206848"`, but | |
417 * this method returns the shorter (but still uniquely identifying) `"9e59"`. | |
418 * | |
419 */ | |
420 String toString(); | |
421 | |
422 /** | |
423 * Parses a string containing a number literal into a number. | |
424 * | |
425 * The method first tries to read the [input] as integer (similar to | |
426 * [int.parse] without a radix). | |
427 * If that fails, it tries to parse the [input] as a double (similar to | |
428 * [double.parse]). | |
429 * If that fails, too, it invokes [onError] with [input], and the result | |
430 * of that invocation becomes the result of calling `parse`. | |
431 * | |
432 * If no [onError] is supplied, it defaults to a function that throws a | |
433 * [FormatException]. | |
434 * | |
435 * For any number `n`, this function satisfies | |
436 * `identical(n, num.parse(n.toString()))` (except when `n` is a NaN `double` | |
437 * with a payload). | |
438 */ | |
439 static num parse(String input, [num onError(String input)]) { | |
440 String source = input.trim(); | |
441 // TODO(lrn): Optimize to detect format and result type in one check. | |
442 num result = int.parse(source, onError: _returnIntNull); | |
443 if (result != null) return result; | |
444 result = double.parse(source, _returnDoubleNull); | |
445 if (result != null) return result; | |
446 if (onError == null) throw new FormatException(input); | |
447 return onError(input); | |
448 } | |
449 | |
450 /** Helper functions for [parse]. */ | |
451 static int _returnIntNull(String _) => null; | |
452 static double _returnDoubleNull(String _) => null; | |
453 } | |
OLD | NEW |