Skip to content

Commit cf21ec7

Browse files
ldudzsimldudzsim
committed
Init commit
0 parents  commit cf21ec7

File tree

8 files changed

+1025
-0
lines changed

8 files changed

+1025
-0
lines changed

‎LICENSE.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
2+
## MIT LICENSE
3+
4+
Copyright (C) 2018 Simplito
5+
6+
Permission is hereby granted, free of charge, to any person obtaining a
7+
copy of this software and associated documentation files (the
8+
"Software"), to deal in the Software without restriction, including
9+
without limitation the rights to use, copy, modify, merge, publish,
10+
distribute, sublicense, and/or sell copies of the Software, and to permit
11+
persons to whom the Software is furnished to do so, subject to the
12+
following conditions:
13+
14+
The above copyright notice and this permission notice shall be included
15+
in all copies or substantial portions of the Software.
16+
17+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
18+
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
20+
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
21+
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
22+
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
23+
USE OR OTHER DEALINGS IN THE SOFTWARE.

‎README.md

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
2+
# BigInteger wrapper library for PHP
3+
4+
## Information
5+
6+
This library is a common interface for php_gmp and php_bcmath modules. It automatically detects supported modules and uses the best of them (gmp>bcmath). Gmp is a lot faster, but is also missing on many hosting services -- that is why this wrapper has been created. It is used for example in encryption functions of the [PrivMX WebMail](https://privmx.com) software.
7+
8+
## Installation
9+
10+
You can install this library via Composer:
11+
```
12+
composer require simplito/bigint-wrapper-php
13+
```
14+
15+
## Documentation
16+
17+
If you want to force using a specific implementation, then define constant S_MATH_BIGINTEGER_MODE - set it to "gmp" or "bcmath". If you do not do this, mode of operation and the constant will be set automatically.
18+
19+
If there are no gmp and bcmath modules, an exception will be thrown. If you want to prevent this, then simply define S_MATH_BIGINTEGER_QUIET constant.
20+
21+
All functions of this library are implemented as members of class BigInteger, which is located under BI namespace. Instances of BigInteger are immutable - member functions usually return new instances of the BigInteger class.
22+
23+
24+
### ConvertibleToBi - a placeholder type
25+
26+
To make the below documentation more readable we use the "ConvertibleToBi" type symbol, which in reality can be one of the following types:
27+
- an instance of the BigInteger class
28+
- an integer
29+
- a decimal string
30+
- a gmp resource or class (only when you are in gmp mode)
31+
32+
If you have a non-decimal string and want to use it -- first you have to convert it to BigInteger class using:
33+
```
34+
new BigInteger($myNonDecimalString, $baseOfMyNonDecimalString)
35+
```
36+
37+
### BI\BigInteger class members
38+
39+
#### construct(ConvertibleToBi $value = 0, int $base = 10)
40+
Creates a new instance of BigInteger. If you pass an invalid value, an exception will be thrown. If $base === true then passed $value will be used without any check and conversion. Supported bases: 2, 10, 16, 256.
41+
- **GMP implementation:** gmp_init + bin2hex for 256 base
42+
- **Bcmath implementation:** custom(bcadd + bcmul)
43+
44+
#### static BigInteger|false createSafe(ConvertibleToBi $value = 0, int $base = 10)
45+
Creates a new BigInteger instance in the same way as constructor, but if there is an error, false will be returned instead of throwing an exception.
46+
47+
#### BigInteger add(ConvertibleToBi $x)
48+
Adds numbers
49+
- **GMP implementation:** gmp_add
50+
- **Bcmath implementation:** bcadd
51+
52+
#### BigInteger sub(ConvertibleToBi $x)
53+
Subtracts numbers
54+
- **GMP implementation:** gmp_sub
55+
- **Bcmath implementation:** bcsub
56+
57+
#### BigInteger mul(ConvertibleToBi $x)
58+
Multiplies numbers
59+
- **GMP implementation:** gmp_mul
60+
- **Bcmath implementation:** bcmul
61+
62+
#### BigInteger div(ConvertibleToBi $x)
63+
Divides numbers
64+
- **GMP implementation:** gmp_div_q
65+
- **Bcmath implementation:** bcdiv
66+
67+
#### BigInteger divR(ConvertibleToBi $x)
68+
Returns a remainder of the division of numbers. The remainder has the sign of the divided number.
69+
- **GMP implementation:** gmp_div_r
70+
- **Bcmath implementation:** bcmod
71+
72+
#### array(BigInteger, BigInteger) divQR(ConvertibleToBi $x)
73+
Divides numbers and returns quotient and remainder. Returns an array(), with the first element being quotient, and the second being remainder.
74+
- **GMP implementation:** gmp_div_qr
75+
- **Bcmath implementation:** div + divR
76+
77+
#### BigInteger mod(ConvertibleToBi $x)
78+
The "division modulo" operation. The result is always non-negative, the sign of divider is ignored.
79+
- **GMP implementation:** gmp_mod
80+
- **Bcmath implementation:** custom (bcmod + bcadd)
81+
82+
#### BigInteger gcd(ConvertibleToBi $x)
83+
Calculates greatest common divisor
84+
- **GMP implementation:** gmp_gcd
85+
- **Bcmath implementation:** custom (bccomp + bcdiv + bcsub + bcmul)
86+
87+
#### BigInteger|false modInverse(ConvertibleToBi $x)
88+
Inverses by modulo, returns false if inversion does not exist.
89+
- **GMP implementation:** gmp_invert
90+
- **Bcmath implementation:** custom (gcd)
91+
92+
#### BigInteger pow(ConvertibleToBi $x)
93+
The power function.
94+
- **GMP implementation:** gmp_pow
95+
- **Bcmath implementation:** bcpow
96+
97+
#### BigInteger powMod(ConvertibleToBi $x, ConvertibleToBi $n)
98+
The modular power function.
99+
- **GMP implementation:** gmp_powm
100+
- **Bcmath implementation:** bcpowmod
101+
102+
#### BigInteger abs()
103+
Returns absolute value.
104+
- **GMP implementation:** gmp_abs
105+
- **Bcmath implementation:** check first character
106+
107+
#### BigInteger neg()
108+
Negates the number
109+
- **GMP implementation:** gmp_neg
110+
- **Bcmath implementation:** check first character
111+
112+
#### BigInteger binaryAnd(ConvertibleToBi $x)
113+
Bitwise AND.
114+
- **GMP implementation:** gmp_and
115+
- **Bcmath implementation:** custom (toBytes + php string and)
116+
117+
#### BigInteger binaryOr(ConvertibleToBi $x)
118+
Bitwise OR
119+
- **GMP implementation:** gmp_or
120+
- **Bcmath implementation:** custom (toBytes + php string or)
121+
122+
#### BigInteger binaryXor(ConvertibleToBi $x)
123+
Bitwise XOR
124+
- **GMP implementation:** gmp_xor
125+
- **Bcmath implementation:** custom (toBytes + php string xor)
126+
127+
#### BigInteger setbit($index, $bitOn = true)
128+
Sets bit at given index
129+
- **GMP implementation:** gmp_setbit
130+
- **Bcmath implementation:** custom (toBits)
131+
132+
#### bool testbit($index)
133+
Tests if a bit at given index is set
134+
- **GMP implementation:** gmp_testbit
135+
- **Bcmath implementation:** custom (toBits)
136+
137+
#### int scan0($start)
138+
Scans for 0, and returns index of first found bit
139+
- **GMP implementation:** gmp_scan0
140+
- **Bcmath implementation:** custom (toBits)
141+
142+
#### int scan1($start)
143+
Scans for 1, and returns index of first found bit
144+
- **GMP implementation:** gmp_scan1
145+
- **Bcmath implementation:** custom (toBits)
146+
147+
#### int cmp(ConvertibleToBi $x)
148+
Compares numbers, returns <0, 0, >0
149+
- **GMP implementation:** gmp_cmp
150+
- **Bcmath implementation:** bccomp
151+
152+
#### bool equals(ConvertibleToBi $x)
153+
Checks if numbers are equal
154+
- **GMP implementation:** gmp_cmp
155+
- **Bcmath implementation:** bccomp
156+
157+
#### int sign()
158+
Sign of number, returns -1, 0, 1
159+
- **GMP implementation:** gmp_sign
160+
- **Bcmath implementation:** check first character
161+
162+
#### int toNumber()
163+
Converts to number (use only with small 32/64bit numbers)
164+
- **GMP implementation:** gmp_intval
165+
- **Bcmath implementation:** intval
166+
167+
#### string toDec()
168+
Converts to decimal string
169+
- **GMP implementation:** gmp_strval
170+
- **Bcmath implementation:** just the value
171+
172+
#### string toHex()
173+
Converts to hex string
174+
- **GMP implementation:** gmp_strval
175+
- **Bcmath implementation:** toBytes + bin2hex
176+
177+
#### string toBytes
178+
Converts to binary string
179+
- **GMP implementation:** gmp_strval + hex2bin
180+
- **Bcmath implementation:** custom (bcmod + bcdiv + bccomp)
181+
182+
#### string toBits()
183+
Converts to bits string (0 and 1 characters)
184+
- **GMP implementation:** gmp_strval
185+
- **Bcmath implementation:** toBytes + decbin
186+
187+
#### string toString(int $base = 10)
188+
Converts to string using given base (supported bases 2-62, 256)
189+
- **GMP implementation:** all above toX functions, and for non standard gmp_strval
190+
- **Bcmath implementation:** all above toX functions, and for non standard bcmod + bcdiv + bccomp

‎composer.json

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"name": "simplito/bigint-wrapper-php",
3+
"description": "Common interface for php_gmp and php_bcmath modules",
4+
"license": "MIT",
5+
"authors": [
6+
{
7+
"name": "Simplito Team",
8+
"email": "s.smyczynski@simplito.com",
9+
"homepage": "https://simplito.com"
10+
}
11+
],
12+
"autoload": {
13+
"psr-4": {
14+
"BI\\": "lib/"
15+
}
16+
}
17+
}

0 commit comments

Comments
 (0)