1: <?php
2: /**
3: * BN-PHP (https://bitbucket.org/zdenekdrahos/bn-php)
4: * @license New BSD License
5: * @author Zdenek Drahos
6: */
7:
8: namespace BN;
9:
10: /**
11: * Interface for number which is used in expression evaluator. Variables can be
12: * used in evaluator only if they implement this interface. In class which implements
13: * this interface number have to be represented as string and the representation
14: * is accessible via @method __toString().
15: */
16: interface INumber
17: {
18: /**
19: * Gets a new number which is the sum of instance and argument.
20: * @param \BN\INumber $number
21: * @return \BN\INumber
22: */
23: public function add(INumber $number);
24:
25: /**
26: * Gets a new number which is the difference of instance and argument.
27: * @param \BN\INumber $number
28: * @return \BN\INumber
29: */
30: public function subtract(INumber $number);
31:
32: /**
33: * Gets a new number which is the product of instance and argument.
34: * @param \BN\INumber $number
35: * @return \BN\INumber
36: */
37: public function multiply(INumber $number);
38:
39: /**
40: * Gets a new number which is the division of instance and argument.
41: * @example 5 / 2 = 2.5
42: * @param \BN\INumber $number
43: * @return \BN\INumber
44: * @throws \InvalidArgumentException if $number equals 0
45: */
46: public function divide(INumber $number);
47:
48: /**
49: * Gets a new number which is the division of instance and argument without
50: * remainder.
51: * @example 10 \ 3 = 3
52: * @example 10 \ -3 = -3
53: * @example -10 \ 3 = -3
54: * @example -10 \ -3 = 3
55: * @return \BN\INumber
56: * @throws \InvalidArgumentException if $number equals 0
57: */
58: public function quotient(INumber $number);
59:
60: /**
61: * Gets a new number which is the remainder after division of instance by argument.
62: * It supports a decimal remainder (calculated m(x,n) = x - n * floor(x/n)).
63: * See the rules in examples:
64: * @example 10 % 2.1 = 1.6
65: * @example 10 % -2.1 = 1.6
66: * @example -10 % 2.1 = -1.6
67: * @example -10 % 2.1 = -1.6
68: * @param \BN\INumber $number
69: * @return \BN\INumber
70: * @throws \InvalidArgumentException if $number equals 0
71: */
72: public function modulo(INumber $number);
73:
74: /**
75: * Gets a new number which is instance raised to the power of argument.
76: * If power is decimal number and it's not square root (1/2) then numbers
77: * are typed to float (IEEE 754) and then pow function is used. Result can
78: * be influenced by inaccurate floating point precision.
79: * @param \BN\INumber $number
80: * @return \BN\INumber
81: */
82: public function power(INumber $number);
83:
84: /**
85: * Gets a new number which is the square root of instance.
86: * @return \BN\INumber
87: * @throws \InvalidArgumentException if $number is smaller than 0
88: */
89: public function sqrt();
90:
91: /**
92: * Gets a new number which is the absolute value of instance.
93: * @return \BN\INumber
94: */
95: public function abs();
96:
97: /**
98: * Gets a new number which is the negated instance.
99: * @return \BN\INumber
100: */
101: public function negate();
102:
103: /**
104: * Returns true if instance is integer. Number is integer if don't have a
105: * decimal point or if numbers after decimal points are zeros.
106: * @param \BN\INumber $number
107: * @return boolean
108: */
109: public function isInteger();
110:
111: /**
112: * Returns true if instance equal to zero.
113: * @param \BN\INumber $number
114: * @return boolean
115: */
116: public function isZero();
117:
118: /**
119: * Returns true if instance is smaller than zero.
120: * @param \BN\INumber $number
121: * @return boolean
122: */
123: public function isNegative();
124:
125: /**
126: * Returns true if instance is larger than zero.
127: * @param \BN\INumber $number
128: * @return boolean
129: */
130: public function isPositive();
131:
132: /**
133: * Compares instance with argument and returns 0 if number are equal. If
134: * instance is larger than argument it returns 1. Otherwise returns -1.
135: * @param \BN\INumber $number
136: * @return int
137: */
138: public function compare(INumber $number);
139:
140: /**
141: * Returns true if instance and argument are equal numbers.
142: * @param \BN\INumber $number
143: * @return boolean
144: */
145: public function isEqual(INumber $number);
146:
147: /**
148: * Returns true if instance is larger than argument
149: * @param \BN\INumber $number
150: * @return boolean
151: */
152: public function isBiggerThan(INumber $number);
153:
154: /**
155: * Returns true if instance is less than argument.
156: * @param \BN\INumber $number
157: * @return boolean
158: */
159: public function isSmallerThan(INumber $number);
160:
161: /**
162: * Gets a new number which is number rounded to nearest number. Precision is
163: * number of digits before (negative) or after (positive number) the decimal point.
164: * @example 2.56 round 1 = 2.6
165: * @example 74 round -1 = 70
166: * @param int $precision
167: * @return \BN\INumber
168: * @throws \InvalidArgumentException if $precision is not integer
169: */
170: public function round($precision);
171:
172: /**
173: * Gets a new number which is the next integer farthest from zero.
174: * It round fractions up.
175: * @example 8.62 roundUp = 9
176: * @example -3.2 roundUp = -4
177: * @return \BN\INumber
178: */
179: public function roundUp();
180:
181: /**
182: * Gets a new number which is the the next integer closest to zero.
183: * It round fractions down.
184: * @example 8.62 roundDown = 8
185: * @example -3.2 roundDown = -3
186: * @return \BN\INumber
187: */
188: public function roundDown();
189:
190: /**
191: * Gets a new number which is the nearest multiple of precision. If precision
192: * is positive number (round after decimal point) then it at first rounds number
193: * to number of digits in precision.
194: * @example 8.6256 roundTo 20 (= temporary 8.63 roundTo 20) = 8.60
195: * @example 165 roundTo -50 = 150
196: * @param int $precision
197: * @return \BN\INumber
198: * @throws \InvalidArgumentException if $precision is not integer
199: */
200: public function roundToNumber($precision);
201:
202: /**
203: * Sets a local scale used to set number of digits after decimal point in
204: * the result. It's defined only for the instance, all other instances will
205: * use global scale. Be careful about using local scale for methods modulo
206: * and roundToNumber, because they are creating temporary numbers without
207: * local scale.
208: * @param int $scale
209: * @throws \InvalidArgumentException if $scale is not integer or it's smaller than 2
210: */
211: public function setLocalScale($scale);
212:
213: /**
214: * Operation won't use local scale, but global scale (if it's defined).
215: * E.g. in BC Math global scale is defined by function bcscale.
216: */
217: public function resetLocalScale();
218:
219: /**
220: * Gets a string represetation of number.
221: * @return string
222: */
223: public function __toString();
224:
225: /**
226: * Clones the current instance.
227: * @return INumber
228: */
229: public function __clone();
230: }
231: