Bitwise Operations

A pure-Lua implementation of common bit-manipulation functions

Bitwise Operations is a pure-Lua implementation of various bit-manipulation functions, including conversion to and from strings and numbers via binary notation as well as an additional binary option to string.format().

Bitwise Operations may be installed either as a Minetest mod or as a standalone library for use in command-line scripts. The usage instructions below apply the same in either scenario.

For numeric bit operations, the following functions are available globally:

All other library functions can be accessed via the 'bitwise' namespace. For improvedperformance, you may want to localize the functions to bits_<func>.

local bits_format = bitwise.format
local bits_unpack = bitwise.unpack
local bits_pack = bitwise.pack
local bits_to_string = bitwise.to_string
local bits_from_string = bitwise.from_string
local bits_pack_string = bitwise.pack_string
local bits_not = bitwise.NOT
local bits_and = bitwise.AND
local bits_or = bitwise.OR
local bits_xor = bitwise.XOR
local bits_lshift = bitwise.LSHIFT
local bits_rshift = bitwise.RSHIFT
local bits_new = bitwise.new

All of these functions can prove useful when debugging, or any application where you need to examine and manipulate individual bits of either numbers or strings.

bitwise.format( str, ... )
Extends the string.format( ) function with an additional %b format specifier for outputting numbers in binary notation. The str is a string that consists of one or more format specifiers, each associated with an argument for substitution.

%[flag][field-width][:group-width]b

The %b format specifier accepts a flag of either 0 to pad the field with leading zeroes or to left-justify the field. With no flag, the field will be padded with leading spaces instead. If no field width is specified then the only the minimumdigits necessary to represent the number in binary notation will be shown, with no leading spaces or zeros. If the field is not wide enough to accommodate the entire number in binary notation, then it will be extended (no digits will be truncated). Sets of bits may also be evenly spaced provided an optional group width.

print( bitwise.format( "%032:4b", 65000 ) )
--> 0000 0000 0000 0000 1111 1101 1110 1000

bitwise.new( size, value )
Creates a new bit field (boolean array) for easily working with individual bits on the fly using Lua's builtin boolean operators.

**bitwise.new( 4, true )**
==> { true, true, true, true }

bitwise.unpack( val, size )
Unpacks a number into a bit field.

bitwise.unpack( 16, 150 )
==> { true, false, false, true, false, true, true, false }

bitwise.pack( bits )
Packs a bit field into a number.

print( bitwise.pack( { true, false, false, false, false, false, false, false } )
--> 128

bitwise.pack_string( bits )
Packs a bit field of arbitrary length into a string. Each set of 8 elements will produce an additional ASCII character.

print( bitwise.pack_string( { false, true, true, true, false, true, true, true } ) )
--> w

bitwise.to_string( bits, div )
Transforms a bit field of arbitrary length into a binary-notation string.

print( bitwise.to_string( { true, false, true, true, false, true, true, true }, 4 ) )
--> 1011 0111

bitwise.from_string( str )
Parses a binary-notation string and transforms it into a bit field.

bitwise.from_string( "1001" )
==> { true, false, false, true }

bitwise.binary( str )
Parses a binary-notation string and converts it into a number.

bitwise.binary( "00010010101110010001" )
==> 76689

AND( num1, num2 )
Performs a logical bitwise AND operation on two numbers.

OR( num1, num2 ) Performs a logical bitwise OR operation on two numbers. The number with the most significant bit set will determine the resulting bit pattern's length.

XOR( num1, num2 ) Performs a logical bitwise XOR operation on two numbers. The number with the most significant bit set will determine the resulting bit pattern's length.

NOT( num )
Performs a logical bitwise NOT operation on a number.

For finer grained control of the resulting bit-pattern length, you can provide a mask with the XOR() functions rather than using the NOT() function:

NOT( 0x0F )
==> 0x00
XOR( 0x0F, 0xFF )
==> 0xF0

NOT16( num )
Performs a logical bitwise NOT operation on a 16-bit number.

The result is undefined for numbers larger than 16-bits, so be sure to mask the input using the AND() function if in doubt.

NOT32( num )
Performs a logical bitwise NOT operation on a 32-bit number.

The result is undefined for numbers larger than 32-bits, so be sure to mask the input using the AND() function if in doubt.