Bitwise operations API documentation

Version: alpha

FUNCTION
bit.tobit() normalize number to the numeric range for bit operations
bit.tohex() convert number to a hex string
bit.bnot() bitwise not
bit.bor() bitwise or
bit.band() bitwise and
bit.bxor() bitwise xor
bit.lshift() bitwise logical left-shift
bit.rshift() bitwise logical right-shift
bit.arshift() bitwise arithmetic right-shift
bit.rol() bitwise left rotation
bit.ror() bitwise right rotation
bit.bswap() bitwise swap

Functions

bit.tobit()

bit.tobit(x)

Normalizes a number to the numeric range for bit operations and returns it. This function is usually not needed since all bit operations already normalize all of their input arguments.

PARAMETERS

x number to normalize

RETURNS

y normalized number

EXAMPLES

print(0xffffffff)                --> 4294967295 (*)
print(bit.tobit(0xffffffff))     --> -1
printx(bit.tobit(0xffffffff))    --> 0xffffffff
print(bit.tobit(0xffffffff + 1)) --> 0
print(bit.tobit(2^40 + 1234))    --> 1234
(*) See the treatment of hex literals for an explanation why the printed numbers in the first two lines differ (if your Lua installation uses a double number type).

bit.tohex()

bit.tohex(x,n)

Converts its first argument to a hex string. The number of hex digits is given by the absolute value of the optional second argument. Positive numbers between 1 and 8 generate lowercase hex digits. Negative numbers generate uppercase hex digits. Only the least-significant 4*|n| bits are used. The default is to generate 8 lowercase hex digits.

PARAMETERS

x number to convert
n number of hex digits to return

RETURNS

s hexadecimal string

EXAMPLES

print(bit.tohex(1))              --> 00000001
print(bit.tohex(-1))             --> ffffffff
print(bit.tohex(0xffffffff))     --> ffffffff
print(bit.tohex(-1, -8))         --> FFFFFFFF
print(bit.tohex(0x21, 4))        --> 0021
print(bit.tohex(0x87654321, 4))  --> 4321

bit.bnot()

bit.bnot(x)

Returns the bitwise not of its argument.

PARAMETERS

x number

RETURNS

y bitwise not of number x

EXAMPLES

print(bit.bnot(0))            --> -1
printx(bit.bnot(0))           --> 0xffffffff
print(bit.bnot(-1))           --> 0
print(bit.bnot(0xffffffff))   --> 0
printx(bit.bnot(0x12345678))  --> 0xedcba987

bit.bor()

bit.bor(x1,[x2...])

Returns the bitwise or of all of its arguments. Note that more than two arguments are allowed.

PARAMETERS

x1 number
[x2...] number(s)

RETURNS

y bitwise or of the provided arguments

EXAMPLES

print(bit.bor(1, 2, 4, 8))                --> 15

bit.band()

bit.band(x1,[x2...])

Returns the bitwise and of all of its arguments. Note that more than two arguments are allowed.

PARAMETERS

x1 number
[x2...] number(s)

RETURNS

y bitwise and of the provided arguments

EXAMPLES

printx(bit.band(0x12345678, 0xff))        --> 0x00000078

bit.bxor()

bit.bxor(x1,[x2...])

Returns the bitwise xor of all of its arguments. Note that more than two arguments are allowed.

PARAMETERS

x1 number
[x2...] number(s)

RETURNS

y bitwise xor of the provided arguments

EXAMPLES

printx(bit.bxor(0xa5a5f0f0, 0xaa55ff00))  --> 0x0ff00ff0

bit.lshift()

bit.lshift(x,n)

Returns the bitwise logical left-shift of its first argument by the number of bits given by the second argument. Logical shifts treat the first argument as an unsigned number and shift in 0-bits. Only the lower 5 bits of the shift count are used (reduces to the range [0..31]).

PARAMETERS

x number
n number of bits

RETURNS

y bitwise logical left-shifted number

EXAMPLES

print(bit.lshift(1, 0))              --> 1
print(bit.lshift(1, 8))              --> 256
print(bit.lshift(1, 40))             --> 256
printx(bit.lshift(0x87654321, 12))   --> 0x54321000

bit.rshift()

bit.rshift(x,n)

Returns the bitwise logical right-shift of its first argument by the number of bits given by the second argument. Logical shifts treat the first argument as an unsigned number and shift in 0-bits. Only the lower 5 bits of the shift count are used (reduces to the range [0..31]).

PARAMETERS

x number
n number of bits

RETURNS

y bitwise logical right-shifted number

EXAMPLES

print(bit.rshift(256, 8))            --> 1
print(bit.rshift(-256, 8))           --> 16777215
printx(bit.rshift(0x87654321, 12))   --> 0x00087654

bit.arshift()

bit.arshift(x,n)

Returns the bitwise arithmetic right-shift of its first argument by the number of bits given by the second argument. Arithmetic right-shift treats the most-significant bit as a sign bit and replicates it. Only the lower 5 bits of the shift count are used (reduces to the range [0..31]).

PARAMETERS

x number
n number of bits

RETURNS

y bitwise arithmetic right-shifted number

EXAMPLES

print(bit.arshift(256, 8))           --> 1
print(bit.arshift(-256, 8))          --> -1
printx(bit.arshift(0x87654321, 12))  --> 0xfff87654

bit.rol()

bit.rol(x,n)

Returns the bitwise left rotation of its first argument by the number of bits given by the second argument. Bits shifted out on one side are shifted back in on the other side. Only the lower 5 bits of the rotate count are used (reduces to the range [0..31]).

PARAMETERS

x number
n number of bits

RETURNS

y bitwise left-rotated number

EXAMPLES

printx(bit.rol(0x12345678, 12))   --> 0x45678123

bit.ror()

bit.ror(x,n)

Returns the bitwise right rotation of its first argument by the number of bits given by the second argument. Bits shifted out on one side are shifted back in on the other side. Only the lower 5 bits of the rotate count are used (reduces to the range [0..31]).

PARAMETERS

x number
n number of bits

RETURNS

y bitwise right-rotated number

EXAMPLES

printx(bit.ror(0x12345678, 12))   --> 0x67812345

bit.bswap()

bit.bswap(x)

Swaps the bytes of its argument and returns it. This can be used to convert little-endian 32 bit numbers to big-endian 32 bit numbers or vice versa.

PARAMETERS

x number

RETURNS

y bitwise swapped number

EXAMPLES

printx(bit.bswap(0x12345678)) --> 0x78563412
printx(bit.bswap(0x78563412)) --> 0x12345678