Lua BitOp: Modular Arithmetic Details, Restrictions, and Copyright

accept arguments in the signed or the unsigned 32 bit range (and more, see below). Numbers with the same underlying bit pattern are treated the same by all operations. Modular Arithmetic ~ *lua-bit-modular-arith* Arithmetic operations on n-bit integers are usually based on the rules of modular arithmetic modulo 2^n. Numbers wrap around when the mathematical result of operations is outside their defined range. This simplifies hardware implementations and some algorithms actually require this behavior (like many cryptographic functions). E.g. for 32 bit integers the following holds: `0xffffffff + 1 = 0` Arithmetic modulo 2^32 is trivially available if the Lua number type is a 32 bit integer. Otherwise normalization steps must be inserted. Modular arithmetic should work the same across all platforms as far as possible: - For the default number type of double, arguments can be in the range of ±2^51 and still be safely normalized across all platforms by taking their least-significant 32 bits. The limit is derived from the way doubles are converted to integers. - The function bit.tobit can be used to explicitly normalize numbers to implement modular addition or subtraction. E.g. >lua bit.tobit(0xffffffff + 1) returns 0 on all platforms. - The limit on the argument range implies that modular multiplication is usually restricted to multiplying already normalized numbers with small constants. FP numbers are limited to 53 bits of precision, anyway. E.g. (2^30+1)^2 does not return an odd number when computed with doubles. BTW: The `tr_i` function shown here |lua-bit-shortcuts| is one of the non-linear functions of the (flawed) MD5 cryptographic hash and relies on modular arithmetic for correct operation. The result is fed back to other bitwise operations (not shown) and does not need to be normalized until the last step. Restricted and undefined behaviors ~ *lua-bit-restrictions* The following rules are intended to give a precise and useful definition (for the programmer), yet give the implementation (interpreter and compiler) the maximum flexibility and the freedom to apply advanced optimizations. It's strongly advised not to rely on undefined or implementation-defined behavior. - All kinds of floating-point numbers are acceptable to the bitwise operations. None of them cause an error, but some may invoke undefined behavior: - -0 is treated the same as +0 on input and is never returned as a result. - Passing ±Inf, NaN or numbers outside the range of ±2^51 as input yields an undefined result. - Non-integral numbers may be rounded or truncated in an implementation-defined way. This means the result could differ between different BitOp versions, different Lua VMs, on different platforms or even between interpreted vs. compiled code (as in LuaJIT). Avoid passing fractional numbers to bitwise functions. Use `math.floor()` or `math.ceil()` to get defined behavior. - Lua provides auto-coercion of string arguments to numbers by default. This behavior is deprecated for bitwise operations. ============================================================================== COPYRIGHT Lua BitOp is Copyright (C) 2008-2012 Mike Pall. Lua BitOp is free software, released under the MIT license. vim:tw=78:ts=4:sw=4:sts=4:et:ft=help:norl:

This section delves deeper into modular arithmetic within Lua BitOp, explaining the normalization requirements for numbers beyond the 32-bit range and providing examples of how to use `bit.tobit` for modular addition and subtraction. It also outlines the restrictions and undefined behaviors of bitwise operations, such as the treatment of floating-point numbers (including -0, ±Inf, and NaN) and non-integral numbers, advising against relying on undefined or implementation-defined behavior. It concludes with the copyright information for Lua BitOp, stating it is released under the MIT license.