Unsigned

Fixed length unsigned arithmetic emulation for PHP.

Installation

composer require 'arokettu/unsigned'

Documentation

Data Type

Explanation and Compatibility

The main data type is a fixed length string with binary data. Length in bytes can be arbitrary but in binary operations both arguments must be of the same length.

Strings contain integers in binary little endian form. It is interoperable with GMP and brick/math like so:

<?php

$u = \Arokettu\Unsigned\from_int(123, 16);

var_dump(gmp_import($u, 1, GMP_LITTLE_ENDIAN | GMP_LSW_FIRST)); // 123
var_dump(\Brick\Math\BigInteger::fromBytes(
    strrev($u), // brick/math is big endian
    false       // arokettu/unsigned is always unsigned
)); // 123

PHP Operators

Note

https://www.php.net/manual/en/language.operators.bitwise.php

Bitwise operators (except for shifts) work on strings and this was the main idea behind this library.

<?php

$a = from_int(0b1111000011110000, 3);
$b = from_int(0b1100110011001100, 3);

var_dump(decbin(to_int($a | $b))); // 1111110011111100
var_dump(decbin(to_int($a & $b))); // 1100000011000000
var_dump(decbin(to_int($a ^ $b))); // 0011110000111100, strings must have same length
var_dump(decbin(to_int(~$a))); // 111111110000111100001111

Type conversion

To working string

from_int(int $value, int $sizeof) → string

Imports a regular PHP int.

Parameters

• $value (int) – The value. Negative values are accepted but they will be cast to unsigned

• $sizeof (int) – Length of the unsigned number in bytes.

Returns

Binary string in the form this library accepts

If $sizeof <= PHP_INT_SIZE, value may be truncated. (but do you really need this lib then?)

from_hex(string $value, int $sizeof) → string

Imports a number written as a hexadecimal string.

Parameters

• $value (int) – String of hex digits

• $sizeof (int) – Length of the unsigned number in bytes

Returns

Binary string in the form this library accepts

If strlen($value) >= $sizeof * 2, value may be truncated.

From working string

fits_into_int(string $value) → bool

Parameters

• $value (string) – Binary string in the form this library accepts

Returns

If value can be represented as a native PHP integer value, i.e. less than PHP_INT_MAX.

to_int(string $value) → int

Parameters

• $value (string) – Binary string in the form this library accepts

Returns

The int representation

to_signed_int(string $value) → int

If the most significant bit is set, return value as a negative int.

Parameters

• $value (string) – Binary string in the form this library accepts

Returns

The int representation

to_hex(string $value) → bool

Exports a number to a hexadecimal string.

Parameters

• $value (string) – Binary string in the form this library accepts

Returns

String of hex digits

Arithmetic

Bit Shifts

shift_left(string $value, int $shift) → string

$value << $shift

shift_right(string $value, int $shift) → string

$value >> $shift

Addition and Subtraction

add(string $a, string $b) → string

$a + $b

add_int(string $a, int $b) → string

$a + $b optimized for small integers

sub(string $a, string $b) → string

$a - $b

sub_int(string $a, int $b) → string

$a - $b optimized for small subtrahends

sub_int_rev(int $a, string $b) → string

$a - $b optimized for small minuends

Multiplication

mul(string $a, string $b) → string

$a * $b

mul_int(string $a, int $b) → string

$a * $b optimized for small integers

Division

div_mod(string $a, string $b) → [string, string]

$a /% $b

Returns

[quotient, remainder]

div_mod_int(string $a, int $b) → [string, int]

$a /% $b optimized for small divisors

Returns

[quotient, remainder]

div(string $a, string $b) → string

$a / $b

div_int(string $a, int $b) → string

$a / $b optimized for small divisors

mod(string $a, string $b) → string

$a % $b

mod_int(string $a, int $b) → int

$a % $b optimized for small divisors

Returns

Result is integer because if $b can be represented as native integer, remainder can be too

Comparison

compare(string $a, compare $b) → int

$a <=> $b

Returns

Same values as the spaceship operator

Bit manipulation

is_bit_set(string $a, int $bit) → bool

Parameters

• $bit (int) – Bit number, 0 is the least significant bit

Returns

If $bit’th bit is set

set_bit(string $a, int $bit) → string

Set $bit’th bit to 1

Parameters

• $bit (int) – Bit number, 0 is the least significant bit

unset_bit(string $a, int $bit) → string

Set $bit’th bit to 0

Parameters

• $bit (int) – Bit number, 0 is the least significant bit

License

The library is available as open source under the terms of the 2-Clause BSD License.