*lua-bit.txt*           Nvim
                                                                *lua-bit*

			  LUA BITOP REFERENCE MANUAL


		   Adapted from <https://bitop.luajit.org>


Lua BitOp is a C extension module for Lua 5.1/5.2 which adds bitwise
operations on numbers.

                                        Type |gO| to see the table of contents.

==============================================================================
API FUNCTIONS                                                    *lua-bit-api*

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 the Wikipedia article
on bitwise operations (https://en.wikipedia.org/wiki/Bitwise_operation) first.

------------------------------------------------------------------------------
Loading the BitOp module
                                                               *lua-bit-module*

The suggested way to use the BitOp module is to add the following to the start
of every Lua file that needs one of its functions: >lua
    local bit = require("bit")
<
This makes the dependency explicit, limits the scope to the current file and
provides faster access to the bit.* functions, too. It's good programming
practice not to rely on the global variable bit being set (assuming some other
part of your application has already loaded the module). The require function
ensures the module is only loaded once, in any case.

------------------------------------------------------------------------------
Defining Shortcuts
                                                            *lua-bit-shortcuts*

It's a common (but not a required) practice to cache often used module
functions in locals. This serves as a shortcut to save some typing and also
speeds up resolving them (only relevant if called hundreds of thousands of
times).
>lua
    local bnot = bit.bnot
    local band, bor, bxor = bit.band, bit.bor, bit.bxor
    local lshift, rshift, rol = bit.lshift, bit.rshift, bit.rol
    -- etc...

    -- Example use of the shortcuts:
    local function tr_i(a, b, c, d, x, s)
      return rol(bxor(c, bor(b, bnot(d))) + a + x, s) + b
    end
<

Remember that `and`, `or` and `not` are reserved keywords in Lua. They cannot
be used for variable names or literal field names. That's why the
corresponding bitwise functions have been named `band`, `bor`, and `bnot` (and
`bxor` for consistency).

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

------------------------------------------------------------------------------
About the Examples

The examples below show small Lua one-liners. Their expected output is shown
after `-->`. This is interpreted as a comment marker by Lua so you can cut &
paste the whole line to a Lua prompt and experiment with it.

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

For clarity the examples assume the definition of a helper function
`printx()`. This prints its argument as an unsigned 32 bit hexadecimal number
on all platforms:
>lua
    function printx(x)
      print("0x"..bit.tohex(x))
    end
<
------------------------------------------------------------------------------
Bit operations
                                                                    *lua-bitop*

y = bit.tobit(x)                                                   *bit.tobit()*
    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. See |lua-bit-semantics|.

    Example: >lua
        print(0xffffffff)                --> 4294967295 (see Note)
        print(bit.tobit(0xffffffff))     --> -1
        printx(bit.tobit(0xffffffff))    --> 0xffffffff
        print(bit.tobit(0xffffffff + 1)) --> 0
        print(bit.tobit(2^40 + 1234))    --> 1234
<
    Note: