Class \Prado\Util\Helpers\TBitHelper

TBitHelper class.

This class contains static functions for bit-wise and byte operations, like color bit shifting, unsigned right bit shift, mirroring the order of bits, flipping endian, and formatting floats into and from smaller float representations like half floats (Fp16, Bf16) and mini floats (Fp8). It also can check for negative floats including negative zero.

Shifting bits for color accuracy requires repeating the bits rather than just adding extra 0/1 bits. colorBitShift properly adds and removes bits to an integer color value by replicating the bits for new bits.

There are specific floating point conversion methods for converting float to:

Fp16 with floatToFp16 and back with fp16ToFloat.
Bf16 with floatToBf16 and back with bf16ToFloat.
Fp8-e5m2 with floatToFp8Range and back with fp8RangeToFloat.
Fp8-e4m3 with floatToFp8Precision and back with fp8PrecisionToFloat. These functions use the general conversion functions floatToFpXX and fpXXToFloat where the number of bits for the exponent and mantissa are parameters. For example, 24 bit floats or 14 bit floats can be created.

mirrorBits can mirror arbitrary runs of bits in an integer. There is quick mirroring for specific exponents of two: mirrorByte for 8 bits, mirrorShort for 16 bits, mirrorLong for 32 bits, and, on 64 bit instances of PHP, mirrorLongLong for 64 bits.

There are endian byte reversal functions: flipEndianShort, flipEndianLong, and, on 64 bit instances of PHP, flipEndianLongLong.

bitCount calculates the number of bits required to represent a specific number. 255 return 8 bits, 256 returns 9 bits.

isNegativeFloat is used to determine if a float has the negative bit set. It will return true on any negative float number, including negative zero. isNegativeZero can check if a float is a negative zero. PHP cannot normally check for negative zero float and requires these special functions to so.

The Levels and Masks are for O(1) time bit reversals of 8, 16, 32, and 64 bit integers. The TBitHelper class automatically adjusts itself for 32 or 64 bit PHP environments.

When quickly mirroring bits or switching endian, the high bits are also converted like the low bits. E.g. When mirroring a Byte, all bytes in the integer are individually mirrored in place. When converting a Short, each short in the integer will be converted in place. In the instance of a Long, for 64 bit systems will convert both Longs -in place- in its LongLong (64 bit) unit integer type. Converting LongLong is only supported in 64 bit PHP environments.

Class hierarchy

\Prado\Util\Helpers\TBitHelper

Author: Brad Anderson <belisoful@icloud.com>
Since: 4.3.0

Methods summary
`public static`	`bf16ToFloat(int $bf16[, null\|int $exponentBias = null ]) : float` This decodes a Bf16 (8 bits exponent, 7 bits mantissa) encoded float into a PHP Float.
`public static`	`bitCount(int $value) : int` This calculates the number of bits required to represent a given number. eg. If there are 256 colors, then the maximum representable number in 8 bits is 255. A $value of 255 returns 8 bits, and 256 returns 9 bits, to represent the number.
`public static`	`colorBitShift(int $value, int $inBits, int $outBits) : int` This method shifts color bits. When removing bits, they are simply dropped. When adding bits, it replicates the existing bits for new bits to create the most accurate higher bit representation of the color.
`public static`	`crc32(mixed $string[, bool\|int $crc = 0 ][, int\|null $crc2 = null ]) : false\|int` This is a CRC32 replacement multi-tool. This acts exactly as crc32 with the added functionality that it accepts file paths (when $crc = true) which computes the CRC32 of the file. This also accepts a $crc computed from existing data and continues to update the $crc with new data form $string as if $string were appended. If an array is passed in $string, [0] is the string data, filepath, or stream resource, element [1] is the size to read, and element [2] is the startOffset. If an array is passed, $crc = true still means that the $string is a FilePath. If the $string is a stream-resource, it reads until fgetc returns false or '', or size is hit. If using this on a file (with $crc = true) then $crc2 can be used for the existing crc32 for continued computation. A continued CRC32 can also be generated with HashContext using , , and , and .
`public static`	`flipEndianLong(int $n) : int` This quickly flips the endian in each [4 byte] long of $n.
`public static`	`flipEndianLongLong(int $n) : int` This quickly fligs the endian of an 8 byte integer. This only works with 64 bit PHP systems. 32 bit systems will treat the bit field as floats and invariably fail. For speed, there is no check to validate that the system is 64 bit PHP. You must do the validation if/when needed with method hasLongLong.
`public static`	`flipEndianShort(int $n) : int` This quickly flips the endian in each [2 byte] short of $n.
`public static`	`floatToBf16(float $value[, null\|int $exponentBias = null ]) : int` This encodes a PHP float into a Bf16 (1 bit sign, 8 bits exponent, 7 bits mantissa) float. This preserves the range of typical 4 byte floats but drops 2 bytes of precision from 23 bits to 7 bits.
`public static`	`floatToFp16(float $value[, null\|int $exponentBias = null ]) : int` This encodes a PHP float into a Fp16 (1 bit sign, 5 bits exponent, 10 bits mantissa) float.
`public static`	`floatToFp8Precision(float $value[, null\|int $exponentBias = null ]) : int` This encodes a PHP float into an FP8 (1 bit sign, 4 bits exponent, 3 bits mantissa) float. The FP8 E4M3 format is for higher precision and lower range.
`public static`	`floatToFp8Range(float $value[, null\|int $exponentBias = null ]) : int` This encodes a PHP float into an FP8 (1 bit sign, 5 bits exponent, 2 bits mantissa) float. The FP8 E5M2 format is for lower precision and higher range.
`public static`	`floatToFpXX(float $value[, int $exponentBits = null ][, int $mantissaBits = null ][, null\|int $exponentBias = null ][, bool $IEEEConformance = true ]) : int` Encodes a PHP float into an N-bit floating point number (in an integer) representation. This function can be configured with arbitrary number of Exponent Bits, Mantissa Bits, Exponent Bias, and IEEE Conformance (for subnormal numbers, INF, -INF, and NAN). The total number of floating point bits to be parsed is "$exponentBits + $mantissaBits + 1". With default parameter values, this functions as floatToFp16.
`public static`	`fp16ToFloat(int $fp16[, null\|int $exponentBias = null ]) : float` This decodes a Fp16 (5 bits exponent, 10 bits mantissa) encoded float into a PHP Float.
`public static`	`fp8PrecisionToFloat(int $fp8[, null\|int $exponentBias = null ]) : float` This decodes a FP8 (4 bits exponent, 3 bits mantissa) encoded float into a PHP Float.
`public static`	`fp8RangeToFloat(int $fp8[, null\|int $exponentBias = null ]) : float` This decodes a FP8 (5 bits exponent, 2 bits mantissa) encoded float into a PHP Float.
`public static`	`fpXXToFloat(int $fpXX[, int $exponentBits = null ][, int $mantissaBits = null ][, null\|int $exponentBias = null ][, bool $IEEEConformance = true ]) : float` Decodes an N-bit floating point encoded as an integer to a PHP floating-point number. This function can be configured with arbitrary number of Exponent Bits, Mantissa Bits, Exponent Bias, and IEEE Conformance (for subnormal numbers, INF, -INF, and NAN). The total number of floating point bits to be parsed is "$exponentBits + $mantissaBits + 1". With default parameter values, this functions as fp16ToFloat.
`public static`	`hasLongLong() : bool`
`public static`	`isNegativeFloat(float $value) : bool` This returns true with all negative floats, including -0.0. Normally "$float < 0" will not include -0.0, where this function does include -0.0.
`public static`	`isNegativeZero(float $value) : bool` This returns true with negative zero (-0.0). Checking for negative zero floats requires this special function because PHP cannot be directly check for negative zero due to '-0.0 === 0.0'.
`public static`	`isSystemBigEndian() : bool` Motorola is Big Endian with the Most Significant Byte first whereas Intel uses Little Endian with the Least Significant Byte first. This mainly only affects the binary reading and writing of data types that are 2 bytes or larger.
`public static`	`mirrorBits(int $value, int $nbit) : int` This mirrors $nbit bits from $value. For example, 0b100 becomes 0b001 @ $nbit = 3 and 0x0100 become 0x0010 @ $nbit = 4.
`public static`	`mirrorByte(int $n) : int` This quickly mirrors the 8 bits in each byte of $n.
`public static`	`mirrorLong(int $n) : int` This quickly mirrors the 32 bits in each [4 byte] long of $n.
`public static`	`mirrorLongLong(int $n) : int` This quickly mirrors the 64 bits of $n. This only works with 64 bit PHP systems. For speed, there is no check to validate that the system is 64 bit PHP. You must do the validation if/when needed with method hasLongLong.
`public static`	`mirrorShort(int $n) : int` This quickly mirrors the 16 bits in each [2 byte] short of $n.
`public static`	`unsignedShift(int $value, int $bits) : int` This does a right bit shift but the signed bit is not replicated in the high bit (with a bit-and). In normal PHP right bit shift, the signed bit is what make up any new bit in the shift.

Inherited methods

Constants summary
`public mixed`	`Level1`	`PHP_INT_SIZE >= 8 ? 0x5555555555555555 : 0x55555555`
`public mixed`	`Level2`	`PHP_INT_SIZE >= 8 ? 0x3333333333333333 : 0x33333333`
`public mixed`	`Level3`	`PHP_INT_SIZE >= 8 ? 0xf0f0f0f0f0f0f0f : 0xf0f0f0f`
`public mixed`	`Level4`	`PHP_INT_SIZE >= 8 ? 0xff00ff00ff00ff : 0xff00ff`
`public mixed`	`Level5`	`PHP_INT_SIZE >= 8 ? 0xffff0000ffff : 0xffff`
`public mixed`	`Level6`	`PHP_INT_SIZE >= 8 ? 0xffffffff : -1`
`public mixed`	`Mask1`	`PHP_INT_SIZE >= 8 ? 0x7fffffffffffffff : 0x7fffffff`
`public mixed`	`Mask2`	`self::Mask1 >> 1`
`public mixed`	`Mask3`	`self::Mask1 >> 3`
`public mixed`	`Mask4`	`self::Mask1 >> 7`
`public mixed`	`Mask5`	`self::Mask1 >> 15`
`public mixed`	`Mask6`	`self::Mask1 >> 31`
`public mixed`	`NLevel1`	`~self::Level1`
`public mixed`	`NLevel2`	`~self::Level2`
`public mixed`	`NLevel3`	`~self::Level3`
`public mixed`	`NLevel4`	`~self::Level4`
`public mixed`	`NLevel5`	`~self::Level5`
`public mixed`	`NLevel6`	`~self::Level6`
`public mixed`	`PHP_INT32_MASK`	`PHP_INT_SIZE > 4 ? self::PHP_INT32_UMAX : -1`
`public mixed`	`PHP_INT32_MAX`	`2147483647`
`public mixed`	`PHP_INT32_MIN`	`-2147483648`
`public mixed`	`PHP_INT32_UMAX`	`4294967295`
`public mixed`	`PHP_INT64_MASK`	`-1`
`public mixed`	`PHP_INT64_MAX`	`9223372036854775807`
`public mixed`	`PHP_INT64_MIN`	`-9.223372036854776E+18`
`public mixed`	`PHP_INT64_UMAX`	`1.8446744073709552E+19`

Classes

Interfaces

Traits

Search results

Class \Prado\Util\Helpers\TBitHelper

Class hierarchy