This list of API functions is not intended to replace a tutorial.If you are not familiar with the terms used, you may want to study theWikipediaarticle on bitwise operations first.

Loading the BitOp Module

Calls to C functions can be inlined in JIT-compiled code, unlike calls to functions bound via the classic Lua/C API. This page gives a short introduction to the usage of the FFI library. Please use the FFI sub-topics in the navigation bar to learn more. Motivating Example: Calling External C Functions. The Application Program Interface ¶ This section describes the C API for Lua, that is, the set of C functions available to the host program to communicate with Lua. All API functions and related types and constants are declared in the header file lua.h.

The suggested way to use the BitOp module is to add the followingto the start of every Lua file that needs one of its functions:

LUAAPI int luaJITsetmode (luaState.L, int idx, int mode); The returned status is either success (1) or failure (0). The second argument is either 0 or a stack index (similar to the other Lua/C API functions). The third argument specifies the mode, which is 'or'ed with a flag.
To compile under Windows (Visual C GUI) do the following: 1: Create a new project. 2: Add the embed.c file. 3: Add the 2 Lua libraries (.lib) - Standard library and the Core library. 4: Add the locations of the Lua include files to the project options ('Directories tab'). 5: You may also have to add the locations of the library files - the.

This makes the dependency explicit, limits the scope to the current fileand provides faster access to the bit.* functions, too.It's good programming practice not to rely on the global variablebit being set (assuming some other part of your applicationhas already loaded the module). The require function ensuresthe module is only loaded once, in any case.

Defining Shortcuts

It's a common (but not a required) practice to cache often used modulefunctions in locals. This serves as a shortcut to save some typingand also speeds up resolving them (only relevant if called hundreds ofthousands of times).

Remember that and, or and notare reserved keywords in Lua. They cannot be used for variable names orliteral field names. That's why the corresponding bitwise functions havebeen named band, bor, and bnot(and bxor for consistency).

While we are at it: a common pitfall is to use bit as thename of a local temporary variable — well, don't! :-)

About the Examples

The examples below show small Lua one-liners. Their expected outputis shown after -->. This is interpreted as a comment markerby Lua so you can cut & paste the whole line to a Lua promptand experiment with it.

Note that all bit operations return signed 32 bit numbers(rationale). And these printas signed decimal numbers by default.

For clarity the examples assume the definition of a helper functionprintx(). This prints its argument as an unsigned32 bit hexadecimal number on all platforms:

Bit Operations

`y = 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 alreadynormalize all of their input arguments. Check theoperational semantics for details.

(*) See the treatment of hex literalsfor an explanation why the printed numbers in the first two linesdiffer (if your Lua installation uses a double number type).

`y = bit.tohex(x [,n])`

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

`y = bit.bnot(x)`

Returns the bitwise not of its argument.

`y = bit.bor(x1 [,x2...]) y = bit.band(x1 [,x2...]) y = bit.bxor(x1 [,x2...])`

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

`y = bit.lshift(x, n) y = bit.rshift(x, n) y = bit.arshift(x, n)`

Returns either the bitwise logical left-shift,bitwise logical right-shift, or bitwise arithmetic right-shiftof 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 in0-bits. Arithmetic right-shift treats the most-significant bitas a sign bit and replicates it.
Only the lower 5 bits of the shift count are used(reduces to the range [0..31]).

`y = bit.rol(x, n) y = bit.ror(x, n)`

Returns either the bitwise left rotation,or bitwise right rotation of its first argument by thenumber 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]).

`y = bit.bswap(x)`

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

Example Program

This is an implementation of the (naïve) Sieve of Eratosthenesalgorithm. It counts the number of primes up to some maximum number.

A Lua table is used to hold a bit-vector. Every array index has32 bits of the vector. Bitwise operations are used to access andmodify them. Note that the shift counts don't need to be maskedsince this is already done by the BitOp shift and rotate functions.

Lua BitOp is quite fast. This program runs in less than90 milliseconds on a 3 GHz CPU with a standard Lua installation,but performs more than a million calls to bitwise functions.If you're looking for even more speed,check out LuaJIT.

Caveats

Signed Results

Returning signed numbers from bitwise operations may be surprising toprogrammers coming from other programming languages which have bothsigned and unsigned types. But as long as you treat the results ofbitwise operations uniformly everywhere, this shouldn't cause any problems.

Preferably format results with bit.tohex if you want areliable unsigned string representation. Avoid the '%x' or'%u' formats for string.format. They fail on somearchitectures for negative numbers and can return more than 8 hex digitson others.

You may also want to avoid the default number to string coercion,since this is a signed conversion.The coercion is used for string concatenation and all standard libraryfunctions which accept string arguments (such as print() orio.write()).

Conditionals

If you're transcribing some code from C/C++, watch out forbit operations in conditionals. In C/C++ any non-zero valueis implicitly considered as 'true'. E.g. this C code:
if (x & 3) ...
must not be turned into this Lua code:
if band(x, 3) then ... -- wrong!

In Lua all objects except nil and false areconsidered 'true'. This includes all numbers. An explicit comparisonagainst zero is required in this case:
if band(x, 3) ~= 0 then ... -- correct!

Comparing Against Hex Literals

Comparing the results of bitwise operations (signed numbers)against hex literals (unsigned numbers) needs some additional care.The following conditional expression may or may not work right,depending on the platform you run it on:
bit.bor(x, 1) 0xffffffff
E.g. it's never true on a Lua installation with the default number type.Some simple solutions:

Either never use hex literals larger than 0x7fffffff in comparisons:
bit.bor(x, 1) -1
Or convert them with bit.tobit() before comparing:
bit.bor(x, 1) bit.tobit(0xffffffff)
Or use a generic workaround with bit.bxor():
bit.bxor(bit.bor(x, 1), 0xffffffff) 0
Or use a case-specific workaround:
bit.rshift(x, 1) 0x7fffffff

Loading the BitOp Module

Defining Shortcuts

About the Examples

Bit Operations

y = bit.tobit(x)

y = bit.tohex(x [,n])

y = bit.bnot(x)

y = bit.bor(x1 [,x2...])y = bit.band(x1 [,x2...])y = bit.bxor(x1 [,x2...])

y = bit.lshift(x, n)y = bit.rshift(x, n)y = bit.arshift(x, n)

y = bit.rol(x, n)y = bit.ror(x, n)

y = bit.bswap(x)

Lua C Api Functions