libraryDocs / raw / bit

raw.bit

librarysharedsource

Native 32-bit integer only bit library.

Fields

Name	Type	Description
`operators`	`boolean`	Whether the bit operators are available.

Functions

`raw.bit.arshift`	Performs an arithmetic right shift of the specified 32-bit integer by the given number of bits.
`raw.bit.band`	Performs a bitwise AND operation on all the specified 32-bit integers.
`raw.bit.bnot`	Performs a bitwise NOT (one's complement) operation on the specified 32-bit integer.
`raw.bit.bor`	Performs a bitwise OR operation on all the specified 32-bit integers.
`raw.bit.brotate`	Rotates the bits of the specified 32-bit integer.
`raw.bit.bshift`	Performs a logical bit shift of the specified 32-bit integer.
`raw.bit.bswap`	Swaps the byte order (endianness) of the specified 32-bit integer, reversing the order of its four constituent bytes.
`raw.bit.btest`	Performs a bitwise AND operation on all the specified 32-bit integers and returns whether the result is non-zero.
`raw.bit.bxor`	Performs a bitwise XOR (exclusive OR) operation on all the specified 32-bit integers.
`raw.bit.extract`	Extracts a bit field of the given width from the specified 32-bit integer, starting at the given bit position (0-indexe…
`raw.bit.lrotate`	Rotates the bits of the specified 32-bit integer to the left by the given number of bits.
`raw.bit.lshift`	Performs a logical left shift of the specified 32-bit integer by the given number of bits.
`raw.bit.replace`	Replaces a bit field of the given width in the specified 32-bit integer, starting at the given bit position (0-indexed,…
`raw.bit.reverse`	Reverses the order of the lowest bit_count bits of x, so the least significant bit becomes the most significant bit (wi…
`raw.bit.rrotate`	Rotates the bits of the specified 32-bit integer to the right by the given number of bits.
`raw.bit.rshift`	Performs a logical right shift of the specified 32-bit integer by the given number of bits.
`raw.bit.sign`	Converts an unsigned bit_count-bit integer to its signed (two's complement) value, the inverse of rbit.unsign.
`raw.bit.tobit`	Normalizes the specified value to a signed 32-bit integer by wrapping it around modulo 2^32, so values outside the rang…
`raw.bit.tohex`	Returns the lowercase hexadecimal representation of the number, zero-padded to length digits.
`raw.bit.unsign`	Converts a signed bit_count-bit integer to its unsigned value, the inverse of rbit.sign.
`raw.bit.width`	Returns the number of bits needed to store the specified 32-bit integer as unsigned, i.e. the position of its highest s…

#raw.bit.arshift

sharednodiscardsource

function raw.bit.arshift(x: T, disp: integer): T

Performs an arithmetic right shift of the specified 32-bit integer by the given number of bits. Bits shifted out of the bottom are discarded and the sign bit is copied into the vacated high-order bits, preserving the sign of the value.

Parameters

Name	Type	Description
`x`	`T`	The value to be shifted.
`disp`	`integer`	The number of bits to shift right by.

Returns

Type	Name	Description
`T`	`result`	The shifted value, normalized to a signed 32-bit integer.

#raw.bit.band

sharednodiscardsource

function raw.bit.band(x: T, ...: T): T

Performs a bitwise AND operation on all the specified 32-bit integers.

Parameters

Name	Type	Description
`x`	`T`	The first value.
`...`	`T`	Additional values to AND together with the first.

Returns

Type	Name	Description
`T`	`result`	The bitwise AND of all given values, normalized to a signed 32-bit integer.

#raw.bit.bnot

sharednodiscardsource

function raw.bit.bnot(x: T): T

Performs a bitwise NOT (one's complement) operation on the specified 32-bit integer.

Parameters

Name	Type	Description
`x`	`T`	The value to be inverted.

Returns

Type	Name	Description
`T`	`result`	The bitwise complement of the given value, normalized to a signed 32-bit integer.

#raw.bit.bor

sharednodiscardsource

function raw.bit.bor(x: T, ...: T): T

Performs a bitwise OR operation on all the specified 32-bit integers.

Parameters

Name	Type	Description
`x`	`T`	The first value.
`...`	`T`	Additional values to OR together with the first.

Returns

Type	Name	Description
`T`	`result`	The bitwise OR of all given values, normalized to a signed 32-bit integer.

#raw.bit.brotate

sharednodiscardsource

function raw.bit.brotate(x: T, disp: integer): T

Rotates the bits of the specified 32-bit integer. A positive displacement rotates left, a negative displacement rotates right.

Parameters

Name	Type	Description
`x`	`T`	The value to be rotated.
`disp`	`integer`	The number of bits to rotate by. Positive rotates left, negative rotates right.

Returns

Type	Name	Description
`T`	`result`	The rotated value, normalized to a signed 32-bit integer.

#raw.bit.bshift

sharednodiscardsource

function raw.bit.bshift(x: T, disp: integer): T

Performs a logical bit shift of the specified 32-bit integer. A positive displacement shifts left, a negative displacement shifts right.

Parameters

Name	Type	Description
`x`	`T`	The value to be shifted.
`disp`	`integer`	The number of bits to shift by. Positive shifts left, negative shifts right.

Returns

Type	Name	Description
`T`	`result`	The shifted value, normalized to a signed 32-bit integer.

#raw.bit.bswap

sharednodiscardsource

function raw.bit.bswap(x: T): T

Swaps the byte order (endianness) of the specified 32-bit integer, reversing the order of its four constituent bytes.

Parameters

Name	Type	Description
`x`	`T`	The value whose byte order is to be swapped.

Returns

Type	Name	Description
`T`	`result`	The byte-swapped value, normalized to a signed 32-bit integer.

#raw.bit.btest

sharednodiscardsource

function raw.bit.btest(x: T, ...: T): boolean

Performs a bitwise AND operation on all the specified 32-bit integers and returns whether the result is non-zero.

Parameters

Name	Type	Description
`x`	`T`	The first value.
`...`	`T`	Additional values to AND together with the first.

Returns

Type	Name	Description
`boolean`	`result`	`true` if the bitwise AND of all given values is non-zero, `false` otherwise.

#raw.bit.bxor

sharednodiscardsource

function raw.bit.bxor(x: T, ...: T): T

Performs a bitwise XOR (exclusive OR) operation on all the specified 32-bit integers.

Parameters

Name	Type	Description
`x`	`T`	The first value.
`...`	`T`	Additional values to XOR together with the first.

Returns

Type	Name	Description
`T`	`result`	The bitwise XOR of all given values, normalized to a signed 32-bit integer.

#raw.bit.extract

sharednodiscardsource

function raw.bit.extract(x: T, field: integer, width?: integer): T

Extracts a bit field of the given width from the specified 32-bit integer, starting at the given bit position (0-indexed, counted from the least significant bit).

lua

rbit.extract( 0xB4, 2, 3 ) -- 5 (0b10110100 -> 0b101)

Parameters

Name	Type	Description
`x`	`T`	The value to extract the bit field from.
`field`	`integer`	The starting bit position of the field (0-indexed).
`width`optional	`integer`	The number of bits in the field. Defaults to `1`.

Returns

Type	Name	Description
`T`	`result`	The extracted bit field, right-aligned as an unsigned integer.

#raw.bit.lrotate

sharednodiscardsource

function raw.bit.lrotate(x: T, disp: integer): T

Rotates the bits of the specified 32-bit integer to the left by the given number of bits. Bits shifted out of the top are wrapped around and shifted in at the bottom.

Parameters

Name	Type	Description
`x`	`T`	The value to be rotated.
`disp`	`integer`	The number of bits to rotate left by.

Returns

Type	Name	Description
`T`	`result`	The rotated value, normalized to a signed 32-bit integer.

#raw.bit.lshift

sharednodiscardsource

function raw.bit.lshift(x: T, disp: integer): T

Performs a logical left shift of the specified 32-bit integer by the given number of bits. Bits shifted out of the top are discarded and zero bits are shifted in from the bottom.

Parameters

Name	Type	Description
`x`	`T`	The value to be shifted.
`disp`	`integer`	The number of bits to shift left by.

Returns

Type	Name	Description
`T`	`result`	The shifted value, normalized to a signed 32-bit integer.

#raw.bit.replace

sharednodiscardsource

function raw.bit.replace(x: T, extract: T, field: integer, width?: integer): T

Replaces a bit field of the given width in the specified 32-bit integer, starting at the given bit position (0-indexed, counted from the least significant bit), with the bits taken from extract.

Parameters

Name	Type	Description
`x`	`T`	The value whose bit field is to be replaced.
`extract`	`T`	The value providing the replacement bits (only the lowest `width` bits are used).
`field`	`integer`	The starting bit position of the field to replace (0-indexed).
`width`optional	`integer`	The number of bits in the field. Defaults to `1`.

Returns

Type	Name	Description
`T`	`result`	The value of `x` with the specified bit field replaced.

#raw.bit.reverse

sharednodiscardsource

function raw.bit.reverse(x: T, bit_count?: integer): T

Reverses the order of the lowest bit_count bits of x, so the least significant bit becomes the most significant bit (within that range) and vice versa.

lua

rbit.reverse( 0x58, 7 ) -- 13 (0b1011000 -> 0b0001101)

Parameters

Name	Type	Description
`x`	`T`	The value whose bits are to be reversed.
`bit_count`optional	`integer`	The number of low-order bits to reverse. Defaults to `32`.

Returns

Type	Name	Description
`T`	`result`	The value of `x` with its bits reversed.

#raw.bit.rrotate

sharednodiscardsource

function raw.bit.rrotate(x: T, disp: integer): T

Rotates the bits of the specified 32-bit integer to the right by the given number of bits. Bits shifted out of the bottom are wrapped around and shifted in at the top.

Parameters

Name	Type	Description
`x`	`T`	The value to be rotated.
`disp`	`integer`	The number of bits to rotate right by.

Returns

Type	Name	Description
`T`	`result`	The rotated value, normalized to a signed 32-bit integer.

#raw.bit.rshift

sharednodiscardsource

function raw.bit.rshift(x: T, disp: integer): T

Performs a logical right shift of the specified 32-bit integer by the given number of bits. Bits shifted out of the bottom are discarded and zero bits are shifted in from the top, regardless of the sign of the value.

Parameters

Name	Type	Description
`x`	`T`	The value to be shifted.
`disp`	`integer`	The number of bits to shift right by.

Returns

Type	Name	Description
`T`	`result`	The shifted value, normalized to a signed 32-bit integer.

#raw.bit.sign

sharednodiscardsource

function raw.bit.sign(x: T, bit_count?: integer): T

Converts an unsigned bit_count-bit integer to its signed (two's complement) value, the inverse of rbit.unsign.

Every positive x has 2 ^ bit_count subtracted from it, so only pass values that have the sign bit set; zero and negative values are returned unchanged.

lua

rbit.sign( 0xFFFFFFFF ) -- -1
rbit.sign( 0xFF, 8 ) -- -1

Parameters

Name	Type	Description
`x`	`T`	The unsigned integer to convert.
`bit_count`optional	`integer`	The bit width of the integer, `32` by default.

Returns

Type	Name	Description
`T`	`result`	The signed value of the integer.

#raw.bit.tobit

sharednodiscardsource

function raw.bit.tobit(x: (integer | ffi.cdata*)): integer

Normalizes the specified value to a signed 32-bit integer by wrapping it around modulo 2^32, so values outside the range are not clamped.

lua

rbit.tobit( 0xFFFFFFFF ) -- -1
rbit.tobit( 2 ^ 32 + 5 ) -- 5

Parameters

Name	Type	Description
`x`	`(integer \| ffi.cdata*)`	The value to be normalized.

Returns

Type	Name	Description
`integer`	`result`	The normalized value, in the range `-2147483648` to `2147483647`.

#raw.bit.tohex

sharednodiscardsource

function raw.bit.tohex(x: (integer | ffi.cdata*), length?: integer): string

Returns the lowercase hexadecimal representation of the number, zero-padded to length digits.

lua

rbit.tohex( 255 ) -- "000000ff"
rbit.tohex( 255, 2 ) -- "ff"

Parameters

Name	Type	Description
`x`	`(integer \| ffi.cdata*)`	The value to be converted.
`length`optional	`integer`	The number of digits, must be positive. Defaults to `8`.

Returns

Type	Name	Description
`string`	`str`	The hexadecimal representation.

#raw.bit.unsign

sharednodiscardsource

function raw.bit.unsign(x: T, bit_count?: integer): T

Converts a signed bit_count-bit integer to its unsigned value, the inverse of rbit.sign.

Negative values have 2 ^ bit_count added to them; zero and positive values are returned unchanged.

lua

rbit.unsign( -1 ) -- 4294967295
rbit.unsign( -1, 8 ) -- 255

Parameters

Name	Type	Description
`x`	`T`	The signed integer to convert.
`bit_count`optional	`integer`	The bit width of the integer, `32` by default.

Returns

Type	Name	Description
`T`	`result`	The unsigned value of the integer.

#raw.bit.width

sharednodiscardsource

function raw.bit.width(x: integer): integer

Returns the number of bits needed to store the specified 32-bit integer as unsigned, i.e. the position of its highest set bit plus one.

Returns 0 for 0 and 32 for negative values (they are read as unsigned).

lua

rbit.width( 0 ) -- 0
rbit.width( 255 ) -- 8
rbit.width( 256 ) -- 9

Parameters

Name	Type	Description
`x`	`integer`	The value to measure.

Returns

Type	Name	Description
`integer`	`width`	The number of significant bits, from `0` to `32`.