*bit.rshift()*
y = bit.arshift(x, n)                                           *bit.arshift()*
    Returns either the bitwise `logical left-shift`, bitwise `logical`
    `right-shift`, or bitwise `arithmetic 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. 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]).

    Example: >lua
        print(bit.lshift(1, 0))              --> 1
        print(bit.lshift(1, 8))              --> 256
        print(bit.lshift(1, 40))             --> 256
        print(bit.rshift(256, 8))            --> 1
        print(bit.rshift(-256, 8))           --> 16777215
        print(bit.arshift(256, 8))           --> 1
        print(bit.arshift(-256, 8))          --> -1
        printx(bit.lshift(0x87654321, 12))   --> 0x54321000
        printx(bit.rshift(0x87654321, 12))   --> 0x00087654
        printx(bit.arshift(0x87654321, 12))  --> 0xfff87654
<
y = bit.rol(x, n)                                               *bit.rol()*
y = bit.ror(x, n)                                               *bit.ror()*
    Returns either the bitwise `left rotation`, or 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]).

    Example: >lua
        printx(bit.rol(0x12345678, 12))   --> 0x45678123
        printx(bit.ror(0x12345678, 12))   --> 0x67812345
<
y = 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.

    Example: >lua
        printx(bit.bswap(0x12345678)) --> 0x78563412
        printx(bit.bswap(0x78563412)) --> 0x12345678
<
------------------------------------------------------------------------------
Example Program

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

A Lua table is used to hold a bit-vector. Every array index has 32 bits of the
vector. Bitwise operations are used to access and modify them. Note that the
shift counts don't need to be masked since this is already done by the BitOp
shift and rotate functions.
>lua
    local bit = require("bit")
    local band, bxor = bit.band, bit.bxor
    local rshift, rol = bit.rshift, bit.rol

    local m = tonumber(arg and arg[1]) or 100000
    if m < 2 then m = 2 end
    local count = 0
    local p = {}

    for i=0,(m+31)/32 do p[i] = -1 end

    for i=2,m do
      if band(rshift(p[rshift(i, 5)], i), 1) ~= 0 then
        count = count + 1
        for j=i+i,m,i do
          local jx = rshift(j, 5)
          p[jx] = band(p[jx], rol(-2, j))
        end
      end
    end

    io.write(string.format("Found %d primes up to %d\n", count, m))
<
Lua BitOp is quite fast. This program runs in less than 90 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
|lua-luajit|.

------------------------------------------------------------------------------
Caveats                                                      *lua-bit-caveats*

Signed Results ~

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

Preferably format results with `bit.tohex` if you want a reliable unsigned
string representation. Avoid the `"%x"` or `"%u"` formats for