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:
- AND(), OR(), XOR(), NOT(), LSHIFT() and RSHIFT()
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.
- size is the length of the bit field (required)
- value is the boolean value to assign to each bit (defaults to false)
**bitwise.new( 4, true )**
==> { true, true, true, true }
bitwise.unpack( val, size )
Unpacks a number into a bit field.
- num is the unsigned integer to unpack (required)
- size is the length of the bit field to create, limited to 56-bits (required)
bitwise.unpack( 16, 150 )
==> { true, false, false, true, false, true, true, false }
bitwise.pack( bits )
Packs a bit field into a number.
- bits is the bit field to unpack, limited to 56 elements (required)
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.
- bits is the bit field to unpack (required)
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.
- bits is the bit field to transform into a string (required)
- div is the group width for evenly spacing bits (optional)
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.
- str is the string to transform into a bit field (required)
bitwise.from_string( "1001" )
==> { true, false, false, true }
bitwise.binary( str )
Parses a binary-notation string and converts it into a number.
- str is the string to convert into a number (required)
bitwise.binary( "00010010101110010001" )
==> 76689
AND( num1, num2 )
Performs a logical bitwise AND operation on two numbers.
- num1 is an unsigned integer
- num2 is an unsigned integer
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.
- num1 is an unsigned integer
- num2 is an unsigned integer
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.
- num1 is an unsigned integer
- num2 is an unsigned integer
NOT( num )
Performs a logical bitwise NOT operation on a number.
- num is an unsigned integer
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.
- num is an unsigned integer
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.
- num is an unsigned integer
The result is undefined for numbers larger than 32-bits, so be sure to mask the input using the AND() function if in doubt.