Menu

Reference

Reference / Manticore\Ds

ByteBuffer

finalclass
final class ByteBuffer<T> extends IntTypedArray

A resizable run of bytes: a UInt8Array ($b[$i], push, fill, …) with typed reads and writes at a BYTE offset, little-endian unless $bigEndian. An access that runs past the end is an OutOfBoundsException; an integer that does not fit its width is a ValueError.

Use it to build or parse binary formats without pack() / unpack(): setUInt16() and friends write a multi-byte number at a byte offset, getUInt16() and friends read one back, and toString() / fromString() convert to and from a PHP byte string. The offsets are byte offsets, not element indexes, and the multi-byte accessors do not need alignment. Floats are stored as IEEE-754 binary32 / binary64. There is no unsigned 64-bit accessor; getInt64() returns the bits as a signed int.

Type parameters

T
= int

Example

use Manticore\Ds\ByteBuffer;

// A tiny binary record: u16 id, i32 delta, f64 score.
$b = new ByteBuffer(14);
$b->setUInt16(0, 0xBEEF);
$b->setInt32(2, -5);
$b->setFloat64(6, 2.5);

echo bin2hex($b->toString()), "\n";           // little-endian by default
echo dechex($b->getUInt16(0)), "\n";
echo $b->getInt32(2), "\n";
echo $b->getFloat64(6), "\n";
echo dechex($b->getUInt16(0, true)), "\n";    // the same bytes, big-endian

$c = ByteBuffer::fromString("ABC");
echo $c[1], ' ', $c->toString(1, 2), "\n";

try {
    $b->getUInt32(12);                         // runs past the end
} catch (OutOfBoundsException $e) {
    echo $e->getMessage(), "\n";
}
try {
    $b->setUInt16(0, 70000);
} catch (ValueError $e) {
    echo $e->getMessage(), "\n";
}

Output

efbefbffffff0000000000000440
beef
-5
2.5
efbe
66 BC
Index invalid or out of range
Value 70000 is out of range for uint16 (0..65535)

Methods

fromString()Builds a buffer holding the bytes of $bytes.
toString()The bytes [$offset, $offset + $length) as a string; to the end when $length is null.
write()Copies $bytes over the buffer at $offset.
getUInt8()Reads a unsigned 8-bit integer at byte $offset.
getInt8()Reads a signed 8-bit integer at byte $offset.
getUInt16()Reads a unsigned 16-bit integer at byte $offset.
getInt16()Reads a signed 16-bit integer at byte $offset.
getUInt32()Reads a unsigned 32-bit integer at byte $offset.
getInt32()Reads a signed 32-bit integer at byte $offset.
getInt64()Reads a signed 64-bit integer at byte $offset.
getFloat32()Reads a 32-bit float at byte $offset.
getFloat64()Reads a 64-bit float at byte $offset.
setUInt8()Writes a unsigned 8-bit integer at byte $offset.
setInt8()Writes a signed 8-bit integer at byte $offset.
setUInt16()Writes a unsigned 16-bit integer at byte $offset.
setInt16()Writes a signed 16-bit integer at byte $offset.
setUInt32()Writes a unsigned 32-bit integer at byte $offset.
setInt32()Writes a signed 32-bit integer at byte $offset.
setInt64()Writes a signed 64-bit integer at byte $offset.
setFloat32()Writes a 32-bit float (rounded to binary32) at byte $offset.
setFloat64()Writes a 64-bit float at byte $offset.

fromString()#source

static function fromString(string $bytes): self

Builds a buffer holding the bytes of $bytes.

Parameters

$bytes string
the source bytes

Returns

self — a new buffer of strlen($bytes) bytes

toString()#source

function toString(int $offset = 0, ?int $length = null): string

The bytes [$offset, $offset + $length) as a string; to the end when $length is null.

Parameters

$offset int = 0
the first byte
$length ?int = null
how many bytes; up to the end when null

Returns

string — the bytes (empty when $offset is the size)

Throws

\OutOfBoundsException
when the range is not inside the buffer

write()#source

function write(int $offset, string $bytes): void

Copies $bytes over the buffer at $offset. The buffer does not grow.

Parameters

$offset int
the first byte to overwrite
$bytes string
the bytes to write

Throws

\OutOfBoundsException
when the bytes do not fit before the end

getUInt8()#source

function getUInt8(int $offset): int

Reads a unsigned 8-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte

Returns

int — the value

Throws

\OutOfBoundsException
when the value does not fit before the end of the buffer

getInt8()#source

function getInt8(int $offset): int

Reads a signed 8-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte

Returns

int — the value

Throws

\OutOfBoundsException
when the value does not fit before the end of the buffer

getUInt16()#source

function getUInt16(int $offset, bool $bigEndian = false): int

Reads a unsigned 16-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Returns

int — the value

Throws

\OutOfBoundsException
when the value does not fit before the end of the buffer

getInt16()#source

function getInt16(int $offset, bool $bigEndian = false): int

Reads a signed 16-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Returns

int — the value

Throws

\OutOfBoundsException
when the value does not fit before the end of the buffer

getUInt32()#source

function getUInt32(int $offset, bool $bigEndian = false): int

Reads a unsigned 32-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Returns

int — the value

Throws

\OutOfBoundsException
when the value does not fit before the end of the buffer

getInt32()#source

function getInt32(int $offset, bool $bigEndian = false): int

Reads a signed 32-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Returns

int — the value

Throws

\OutOfBoundsException
when the value does not fit before the end of the buffer

getInt64()#source

function getInt64(int $offset, bool $bigEndian = false): int

Reads a signed 64-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Returns

int — the value

Throws

\OutOfBoundsException
when the value does not fit before the end of the buffer

getFloat32()#source

function getFloat32(int $offset, bool $bigEndian = false): float

Reads a 32-bit float at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Returns

float — the value

Throws

\OutOfBoundsException
when the value does not fit before the end of the buffer

getFloat64()#source

function getFloat64(int $offset, bool $bigEndian = false): float

Reads a 64-bit float at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Returns

float — the value

Throws

\OutOfBoundsException
when the value does not fit before the end of the buffer

setUInt8()#source

function setUInt8(int $offset, int $value): void

Writes a unsigned 8-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$value int
the value, in 0..255

Throws

\ValueError
when $value is outside the range
\OutOfBoundsException
when the value does not fit before the end of the buffer

setInt8()#source

function setInt8(int $offset, int $value): void

Writes a signed 8-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$value int
the value, in -128..127

Throws

\ValueError
when $value is outside the range
\OutOfBoundsException
when the value does not fit before the end of the buffer

setUInt16()#source

function setUInt16(int $offset, int $value, bool $bigEndian = false): void

Writes a unsigned 16-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$value int
the value, in 0..65535
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Throws

\ValueError
when $value is outside the range
\OutOfBoundsException
when the value does not fit before the end of the buffer

setInt16()#source

function setInt16(int $offset, int $value, bool $bigEndian = false): void

Writes a signed 16-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$value int
the value, in -32768..32767
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Throws

\ValueError
when $value is outside the range
\OutOfBoundsException
when the value does not fit before the end of the buffer

setUInt32()#source

function setUInt32(int $offset, int $value, bool $bigEndian = false): void

Writes a unsigned 32-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$value int
the value, in 0..4294967295
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Throws

\ValueError
when $value is outside the range
\OutOfBoundsException
when the value does not fit before the end of the buffer

setInt32()#source

function setInt32(int $offset, int $value, bool $bigEndian = false): void

Writes a signed 32-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$value int
the value, in -2147483648..2147483647
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Throws

\ValueError
when $value is outside the range
\OutOfBoundsException
when the value does not fit before the end of the buffer

setInt64()#source

function setInt64(int $offset, int $value, bool $bigEndian = false): void

Writes a signed 64-bit integer at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$value int
the value, in the full int range
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Throws

\ValueError
when $value is outside the range
\OutOfBoundsException
when the value does not fit before the end of the buffer

setFloat32()#source

function setFloat32(int $offset, float $value, bool $bigEndian = false): void

Writes a 32-bit float (rounded to binary32) at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$value float
the value
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Throws

\OutOfBoundsException
when the value does not fit before the end of the buffer

setFloat64()#source

function setFloat64(int $offset, float $value, bool $bigEndian = false): void

Writes a 64-bit float at byte $offset.

Parameters

$offset int
the byte offset of the first byte
$value float
the value
$bigEndian bool = false
true for big-endian byte order, false (default) for little-endian

Throws

\OutOfBoundsException
when the value does not fit before the end of the buffer

View source