forked from vimeo/psalm
/
decimal.phpstub
492 lines (446 loc) · 16.2 KB
/
decimal.phpstub
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
<?php
namespace Decimal;
/**
* Copied from https://github.com/php-decimal/stubs/blob/master/Decimal.php
*
* The MIT License (MIT)
* Copyright (c) 2018 Rudi Theunissen
*
* Permission is hereby granted, free of charge, to any person obtaining a
* copy of this software and associated documentation files (the "Software"),
* to deal in the Software without restriction, including without limitation
* the rights to use, copy, modify, merge, publish, distribute, sublicense,
* and/or sell copies of the Software, and to permit persons to whom the
* Software is furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
* OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH
* THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
final class Decimal implements \JsonSerializable
{
/**
* These constants are for auto-complete only.
*/
const ROUND_UP = 101; /* Round away from zero. */
const ROUND_DOWN = 102; /* Round towards zero. */
const ROUND_CEILING = 103; /* Round towards positive infinity */
const ROUND_FLOOR = 104; /* Round towards negative infinity */
const ROUND_HALF_UP = 105; /* Round to nearest, ties away from zero. */
const ROUND_HALF_DOWN = 106; /* Round to nearest, ties towards zero. */
const ROUND_HALF_EVEN = 107; /* Round to nearest, ties towards even. */
const ROUND_HALF_ODD = 108; /* Round to nearest, ties towards odd. */
const ROUND_TRUNCATE = 109; /* Truncate, keeping infinity. */
const DEFAULT_ROUNDING = Decimal::ROUND_HALF_EVEN;
const DEFAULT_PRECISION = 28;
const MIN_PRECISION = 1;
const MAX_PRECISION = 0; /* This value may change across platforms */
/**
* Constructor
*
* Initializes a new instance using a given value and minimum precision.
*
* @param Decimal|string|int $value
* @param int $precision
*
* @throws \BadMethodCallException if already constructed.
* @throws \TypeError if the value is not a decimal, string, or integer.
* @throws \DomainException is the type is supported but the value could not
* be converted to decimal.
*/
public function __construct($value, int $precision = Decimal::DEFAULT_PRECISION) {}
/**
* Sum
*
* The precision of the result will be the max of all precisions that were
* encountered during the calculation. The given precision should therefore
* be considered the minimum precision of the result.
*
* This method is equivalent to adding each value individually.
*
* @param array|\Traversable $values
* @param int $precision Minimum precision of the sum.
*
* @return Decimal the sum of all given values.
*
* @throws \TypeError if an unsupported type is encountered.
* @throws \ArithmeticError if addition is undefined, eg. INF + -INF
*/
public static function sum($values, int $precision = Decimal::DEFAULT_PRECISION): Decimal {}
/**
* Average
*
* The precision of the result will be the max of all precisions that were
* encountered during the calculation. The given precision should therefore
* be considered the minimum precision of the result.
*
* This method is equivalent to adding each value individually,
* then dividing by the number of values.
*
* @param array|\Traversable $values
* @param int $precision Minimum precision of the average.
*
* @return Decimal the average of all given values.
*
* @throws \TypeError if an unsupported type is encountered.
* @throws \ArithmeticError if addition is undefined, eg. INF + -INF
*/
public static function avg($values, int $precision = Decimal::DEFAULT_PRECISION): Decimal {}
/**
* Copy
*
* @param int $precision The precision of the return value, which defaults
* to the precision of this decimal.
*
* @return Decimal a copy of this decimal.
*/
public function copy(int $precision = null): Decimal {}
/**
* Add
*
* This method is equivalent to the `+` operator.
*
* The precision of the result will be the max of this decimal's precision
* and the given value's precision, where scalar values assume the default.
*
* @param Decimal|string|int $value
*
* @return Decimal the result of adding this decimal to the given value.
*
* @throws \TypeError if the value is not a decimal, string or integer.
*/
public function add($value): Decimal {}
/**
* Subtract
*
* This method is equivalent to the `-` operator.
*
* The precision of the result will be the max of this decimal's precision
* and the given value's precision, where scalar values assume the default.
*
* @param Decimal|string|int $value
*
* @return Decimal the result of subtracting a given value from this decimal.
*
* @throws \TypeError if the value is not a decimal, string or integer.
*/
public function sub($value): Decimal {}
/**
* Multiply
*
* This method is equivalent to the `*` operator.
*
* The precision of the result will be the max of this decimal's precision
* and the given value's precision, where scalar values assume the default.
*
* @param Decimal|string|int $value
*
* @return Decimal the result of multiplying this decimal by the given value.
*
* @throws \TypeError if the given value is not a decimal, string or integer.
*/
public function mul($value): Decimal {}
/**
* Divide
*
* This method is equivalent to the `/` operator.
*
* The precision of the result will be the max of this decimal's precision
* and the given value's precision, where scalar values assume the default.
*
* @param Decimal|string|int $value
*
* @return Decimal the result of dividing this decimal by the given value.
*
* @throws \TypeError if the value is not a decimal, string or integer.
* @throws \DivisionByZeroError if dividing by zero.
* @throws \ArithmeticError if division is undefined, eg. INF / -INF
*/
public function div($value): Decimal {}
/**
* Modulo (integer)
*
* This method is equivalent to the `%` operator.
*
* The precision of the result will be the max of this decimal's precision
* and the given value's precision, where scalar values assume the default.
*
* @see Decimal::rem for the decimal remainder.
*
* @param Decimal|string|int $value
*
* @return Decimal the remainder after dividing the integer value of this
* decimal by the integer value of the given value
*
* @throws \TypeError if the value is not a decimal, string or integer.
* @throws \DivisionByZeroError if the integer value of $value is zero.
* @throws \ArithmeticError if the operation is undefined, eg. INF % -INF
*/
public function mod($value): Decimal {}
/**
* Remainder
*
* The precision of the result will be the max of this decimal's precision
* and the given value's precision, where scalar values assume the default.
*
* @param Decimal|string|int $value
*
* @return Decimal the remainder after dividing this decimal by a given value.
*
* @throws \TypeError if the value is not a decimal, string or integer.
* @throws \DivisionByZeroError if the integer value of $value is zero.
* @throws \ArithmeticError if the operation is undefined, eg. INF, -INF
*/
public function rem($value): Decimal {}
/**
* Power
*
* This method is equivalent to the `**` operator.
*
* The precision of the result will be the max of this decimal's precision
* and the given value's precision, where scalar values assume the default.
*
* @param Decimal|string|int $exponent The power to raise this decimal to.
*
* @return Decimal the result of raising this decimal to a given power.
*
* @throws \TypeError if the exponent is not a decimal, string or integer.
*/
public function pow($exponent): Decimal {}
/**
* Natural logarithm
*
* This method is equivalent in function to PHP's `log`.
*
* @return Decimal the natural logarithm of this decimal (log base e),
* with the same precision as this decimal.
*/
public function ln(): Decimal {}
/**
* Exponent
*
* @return Decimal the exponent of this decimal, ie. e to the power of this,
* with the same precision as this decimal.
*/
public function exp(): Decimal {}
/**
* Base-10 logarithm
*
* @return Decimal the base-10 logarithm of this decimal, with the same
* precision as this decimal.
*/
public function log10(): Decimal {}
/**
* Square root
*
* @return Decimal the square root of this decimal, with the same precision
* as this decimal.
*/
public function sqrt(): Decimal {}
/**
* Floor
*
* @return Decimal the closest integer towards negative infinity.
*/
public function floor(): Decimal {}
/**
* Ceiling
*
* @return Decimal the closest integer towards positive infinity.
*/
public function ceil(): Decimal {}
/**
* Truncate
*
* @return Decimal the integer value of this decimal.
*/
public function truncate(): Decimal {}
/**
* Round
*
* @param int $places The number of places behind the decimal to round to.
* @param int $mode The rounding mode, which are constants of Decimal.
*
* @return Decimal the value of this decimal with the same precision,
* rounded according to the specified number of decimal
* places and rounding mode
*
* @throws \InvalidArgumentException if the rounding mode is not supported.
*/
public function round(int $places = 0, int $mode = Decimal::DEFAULT_ROUNDING): Decimal {}
/**
* Decimal point shift.
*
* @param int $places The number of places to shift the decimal point by.
* A positive shift moves the decimal point to the right,
* a negative shift moves the decimal point to the left.
*
* @return Decimal A copy of this decimal with its decimal place shifted.
*/
public function shift(int $places): Decimal {}
/**
* Trims trailing zeroes.
*
* @return Decimal A copy of this decimal without trailing zeroes.
*/
public function trim(): Decimal {}
/**
* Precision
*
* @return int the precision of this decimal.
*/
public function precision(): int {}
/**
* Signum
*
* @return int 0 if zero, -1 if negative, or 1 if positive.
*/
public function signum(): int {}
/**
* Parity (integer)
*
* @return int 0 if the integer value of this decimal is even, 1 if odd.
* Special numbers like NAN and INF will return 1.
*/
public function parity(): int {}
/**
* Absolute
*
* @return Decimal the absolute (positive) value of this decimal.
*/
public function abs(): Decimal {}
/**
* Negate
*
* @return Decimal the same value as this decimal, but the sign inverted.
*/
public function negate(): Decimal {}
/**
* @return bool TRUE if this decimal is an integer and even, FALSE otherwise.
*/
public function isEven(): bool {}
/**
* @return bool TRUE if this decimal is an integer and odd, FALSE otherwise.
*/
public function isOdd(): bool {}
/**
* @return bool TRUE if this decimal is positive, FALSE otherwise.
*/
public function isPositive(): bool {}
/**
* @return bool TRUE if this decimal is negative, FALSE otherwise.
*/
public function isNegative(): bool {}
/**
* @return bool TRUE if this decimal is not a defined number.
*/
public function isNaN(): bool {}
/**
* @return bool TRUE if this decimal represents infinity, FALSE otherwise.
*/
public function isInf(): bool {}
/**
* @return bool TRUE if this decimal is an integer, ie. does not have
* significant figures behind the decimal point, otherwise FALSE.
*/
public function isInteger(): bool {}
/**
* @return bool TRUE if this decimal is either positive or negative zero.
*/
public function isZero(): bool {}
/**
* @param int $places The number of places behind the decimal point.
* @param bool $commas TRUE if thousands should be separated by a comma.
* @param int $rounding
*
* @return string the value of this decimal formatted to a fixed number of
* decimal places, optionally with thousands comma-separated,
* using a given rounding mode.
*/
public function toFixed(int $places = 0, bool $commas = false, int $rounding = Decimal::DEFAULT_ROUNDING): string {}
/**
* String representation.
*
* This method is equivalent to a cast to string.
*
* This method should not be used as a canonical representation of this
* decimal, because values can be represented in more than one way. However,
* this method does guarantee that a decimal instantiated by its output with
* the same precision will be exactly equal to this decimal.
*
* @return string the value of this decimal represented exactly, in either
* fixed or scientific form, depending on the value.
*/
public function toString(): string {}
/**
* Integer representation.
*
* This method is equivalent to a cast to int.
*
* @return int the integer value of this decimal.
*
* @throws \OverflowException if the value is greater than PHP_INT_MAX.
*/
public function toInt(): int {}
/**
* Binary floating point representation.
*
* This method is equivalent to a cast to float, and is not affected by the
* 'precision' INI setting.
*
* @return float the native PHP floating point value of this decimal.
*
* @throws \OverflowException if the value is greater than PHP_FLOAT_MAX.
* @throws \UnderflowException if the value is smaller than PHP_FLOAT_MIN.
*/
public function toFloat(): float {}
/**
* Equality
*
* This method is equivalent to the `==` operator.
*
* @param mixed $other
*
* @return bool TRUE if this decimal is considered equal to the given value.
* Equal decimal values tie-break on precision.
*/
public function equals($other): bool {}
/**
* Ordering
*
* This method is equivalent to the `<=>` operator.
*
* @param mixed $other
*
* @return int 0 if this decimal is considered is equal to $other,
* -1 if this decimal should be placed before $other,
* 1 if this decimal should be placed after $other.
*/
public function compareTo($other): int {}
/**
* String representation.
*
* This method is equivalent to a cast to string, as well as `toString`.
*
* @return string the value of this decimal represented exactly, in either
* fixed or scientific form, depending on the value.
*/
public function __toString(): string {}
/**
* JSON
*
* This method is only here to honour the interface, and is equivalent to
* `toString`. JSON does not have a decimal type so all decimals are encoded
* as strings in the same format as `toString`.
*
* @return string
*/
public function jsonSerialize() {}
}