11.12. Handling 64-bit Integers

Lua uses one single number representation which can be chosen at compile time and since it is often set to IEEE 754 double precision floating point, one cannot store 64 bit integers with full precision.

Lua numbers are stored as floating point (doubles) internally, not integers; thus while they can represent incredibly large numbers, above 2^53 they lose integral precision — they can’t represent every whole integer value. For example if you set a lua variable to the number 9007199254740992 and tried to increment it by 1, you’d get the same number because it can’t represent 9007199254740993 (only the even number 9007199254740994).

Therefore, in order to count higher than 2^53 in integers, we need a true integer type. The way this is done is with an explicit 'Int64' or 'UInt64' object (i.e., Lua userdata). This object has metamethods for all of the math and comparison operators, so you can handle it like any number variable. For the math operators, it can even be mixed with plain Lua numbers.

For example 'my64num = my64num + 1' will work even if 'my64num' is a Int64 or UInt64 object. Note that comparison operators ('==','<=','>', etc.) will not work with plain numbers — only other Int64/UInt64 objects. This is a limitation of Lua itself, in terms of how it handles operator overloading.

[Warning]Warning

Many of the UInt64/Int64 functions accept a Lua number as an argument. You should be very careful to never use Lua numbers bigger than 32 bits (i.e., the number value 4,294,967,295 or the literal 0xFFFFFFFF) for such arguments, because Lua itself does not handle bigger numbers consistently across platforms (32-bit vs. 64-bit systems), and because a Lua number is a C-code double which cannot have more than 53 bits of precision. Instead, use a Int64 or UInt64 for the argument.

For example, do this…​

    local mynum = UInt64(0x2b89dd1e, 0x3f91df0b)

…​instead of this:

    -- Bad. Leads to inconsistent results across platforms
    local mynum = UInt64(0x3f91df0b2b89dd1e)

And do this…​

    local masked = mynum:band(UInt64(0, 0xFFFFFFFF))

…​instead of this:

    -- Bad. Leads to inconsistent results across platforms
    local masked = mynum:band(0xFFFFFFFF00000000)

11.12.1. Int64

Int64 represents a 64 bit signed integer.

Note the caveats listed above.

11.12.1.1. Int64.decode(string, [endian])

Decodes an 8-byte Lua string, using the given endianness, into a new Int64 object.

Since: 1.11.3

Arguments
string
The Lua string containing a binary 64-bit integer.
endian (optional)
If set to true then little-endian is used, if false then big-endian; if missing or nil, native host endian.
Returns

The Int64 object created, or nil on failure.

11.12.1.2. Int64.new([value], [highvalue])

Creates a Int64 Object.

Since: 1.11.3

Arguments
value (optional)
A number, UInt64, Int64, or string of ASCII digits to assign the value of the new Int64. Default is 0.
highvalue (optional)
If this is a number and the first argument was a number, then the first will be treated as a lower 32 bits, and this is the high-order 32 bit number.
Returns

The new Int64 object.

11.12.1.3. Int64.max()

Creates an Int64 of the maximum possible positive value. In other words, this should return an Int64 object of the number 9,223,372,036,854,775,807.

Since: 1.11.3

Returns

The new Int64 object of the maximum value.

11.12.1.4. Int64.min()

Creates an Int64 of the minimum possible negative value. In other words, this should return an Int64 object of the number -9,223,372,036,854,775,808.

Since: 1.11.3

Returns

The new Int64 object of the minimum value.

11.12.1.5. Int64.fromhex(hex)

Creates an Int64 object from the given hexadecimal string.

Since: 1.11.3

Arguments
hex
The hex-ASCII Lua string.
Returns

The new Int64 object.

11.12.1.6. int64:encode([endian])

Encodes the Int64 number into an 8-byte Lua string using the given endianness.

Since: 1.11.3

Arguments
endian (optional)
If set to true then little-endian is used, if false then big-endian; if missing or nil, native host endian.
Returns

The Lua string.

11.12.1.7. int64:__call()

Creates a Int64 object.

Since: 1.11.3

Returns

The new Int64 object.

11.12.1.8. int64:tonumber()

Returns a Lua number of the Int64 value. Note that this may lose precision.

Since: 1.11.3

Returns

The Lua number.

11.12.1.9. int64:tohex([numbytes])

Returns a hexadecimal string of the Int64 value.

Since: 1.11.3

Arguments
numbytes (optional)
The number of hex chars/nibbles to generate. A negative value generates uppercase. Default is 16.
Returns

The string hex.

11.12.1.10. int64:higher()

Returns a Lua number of the higher 32 bits of the Int64 value. A negative Int64 will return a negative Lua number.

Since: 1.11.3

Returns

The Lua number.

11.12.1.11. int64:lower()

Returns a Lua number of the lower 32 bits of the Int64 value. This will always be positive.

Since: 1.11.3

Returns

The Lua number.

11.12.1.12. int64:__tostring()

Converts the Int64 into a string of decimal digits.

Returns

The Lua string.

11.12.1.13. int64:__unm()

Returns the negative of the Int64 as a new Int64.

Since: 1.11.3

Returns

The new Int64.

11.12.1.14. int64:__add()

Adds two Int64 together and returns a new one. The value may wrapped.

Since: 1.11.3

11.12.1.15. int64:__sub()

Subtracts two Int64 and returns a new one. The value may wrapped.

Since: 1.11.3

11.12.1.16. int64:__mul()

Multiplies two Int64 and returns a new one. The value may truncated.

Since: 1.11.3

11.12.1.17. int64:__div()

Divides two Int64 and returns a new one. Integer divide, no remainder. Trying to divide by zero results in a Lua error.

Since: 1.11.3

Returns

The Int64 object.

11.12.1.18. int64:__mod()

Divides two Int64 and returns a new one of the remainder. Trying to modulo by zero results in a Lua error.

Since: 1.11.3

Returns

The Int64 object.

11.12.1.19. int64:__pow()

The first Int64 is taken to the power of the second Int64, returning a new one. This may truncate the value.

Since: 1.11.3

Returns

The Int64 object.

11.12.1.20. int64:__eq()

Returns true if both Int64 are equal.

Since: 1.11.3

11.12.1.21. int64:__lt()

Returns true if first Int64 is less than the second.

Since: 1.11.3

11.12.1.22. int64:__le()

Returns true if the first Int64 is less than or equal to the second.

Since: 1.11.3

11.12.1.23. int64:bnot()

Returns a Int64 of the bitwise 'not' operation.

Since: 1.11.3

Returns

The Int64 object.

11.12.1.24. int64:band()

Returns a Int64 of the bitwise 'and' operation with the given number/Int64/UInt64. Note that multiple arguments are allowed.

Since: 1.11.3

11.12.1.25. int64:bor()

Returns a Int64 of the bitwise 'or' operation, with the given number/Int64/UInt64. Note that multiple arguments are allowed.

Since: 1.11.3

11.12.1.26. int64:bxor()

Returns a Int64 of the bitwise 'xor' operation, with the given number/Int64/UInt64. Note that multiple arguments are allowed.

Since: 1.11.3

11.12.1.27. int64:lshift(numbits)

Returns a Int64 of the bitwise logical left-shift operation, by the given number of bits.

Since: 1.11.3

Arguments
numbits
The number of bits to left-shift by.
Returns

The Int64 object.

11.12.1.28. int64:rshift(numbits)

Returns a Int64 of the bitwise logical right-shift operation, by the given number of bits.

Since: 1.11.3

Arguments
numbits
The number of bits to right-shift by.
Returns

The Int64 object.

11.12.1.29. int64:arshift(numbits)

Returns a Int64 of the bitwise arithmetic right-shift operation, by the given number of bits.

Since: 1.11.3

Arguments
numbits
The number of bits to right-shift by.
Returns

The Int64 object.

11.12.1.30. int64:rol(numbits)

Returns a Int64 of the bitwise left rotation operation, by the given number of bits (up to 63).

Since: 1.11.3

Arguments
numbits
The number of bits to roll left by.
Returns

The Int64 object.

11.12.1.31. int64:ror(numbits)

Returns a Int64 of the bitwise right rotation operation, by the given number of bits (up to 63).

Since: 1.11.3

Arguments
numbits
The number of bits to roll right by.
Returns

The Int64 object.

11.12.1.32. int64:bswap()

Returns a Int64 of the bytes swapped. This can be used to convert little-endian 64-bit numbers to big-endian 64 bit numbers or vice versa.

Since: 1.11.3

Returns

The Int64 object.

11.12.2. UInt64

UInt64 represents a 64 bit unsigned integer, similar to Int64.

Note the caveats listed above.

11.12.2.1. UInt64.decode(string, [endian])

Decodes an 8-byte Lua binary string, using given endianness, into a new UInt64 object.

Since: 1.11.3

Arguments
string
The Lua string containing a binary 64-bit integer.
endian (optional)
If set to true then little-endian is used, if false then big-endian; if missing or nil, native host endian.
Returns

The UInt64 object created, or nil on failure.

11.12.2.2. UInt64.new([value], [highvalue])

Creates a UInt64 Object.

Since: 1.11.3

Arguments
value (optional)
A number, UInt64, Int64, or string of digits to assign the value of the new UInt64. Default is 0.
highvalue (optional)
If this is a number and the first argument was a number, then the first will be treated as a lower 32 bits, and this is the high-order 32-bit number.
Returns

The new UInt64 object.

11.12.2.3. UInt64.max()

Creates a UInt64 of the maximum possible value. In other words, this should return an UInt64 object of the number 18,446,744,073,709,551,615.

Since: 1.11.3

Returns

The maximum value.

11.12.2.4. UInt64.min()

Creates a UInt64 of the minimum possible value. In other words, this should return an UInt64 object of the number 0.

Since: 1.11.3

Returns

The minimum value.

11.12.2.5. UInt64.fromhex(hex)

Creates a UInt64 object from the given hex string.

Since: 1.11.3

Arguments
hex
The hex-ASCII Lua string.
Returns

The new UInt64 object.

11.12.2.6. uint64:encode([endian])

Encodes the UInt64 number into an 8-byte Lua binary string, using given endianness.

Since: 1.11.3

Arguments
endian (optional)
If set to true then little-endian is used, if false then big-endian; if missing or nil, native host endian.
Returns

The Lua binary string.

11.12.2.7. uint64:__call()

Creates a UInt64 object.

Since: 1.11.3

Returns

The new UInt64 object.

11.12.2.8. uint64:tonumber()

Returns a Lua number of the UInt64 value. This may lose precision.

Since: 1.11.3

Returns

The Lua number.

11.12.2.9. uint64:__tostring()

Converts the UInt64 into a string.

Returns

The Lua string.

11.12.2.10. uint64:tohex([numbytes])

Returns a hex string of the UInt64 value.

Since: 1.11.3

Arguments
numbytes (optional)
The number of hex-chars/nibbles to generate. Negative means uppercase Default is 16.
Returns

The string hex.

11.12.2.11. uint64:higher()

Returns a Lua number of the higher 32 bits of the UInt64 value.

Returns

The Lua number.

11.12.2.12. uint64:lower()

Returns a Lua number of the lower 32 bits of the UInt64 value.

Returns

The Lua number.

11.12.2.13. uint64:__unm()

Returns the UInt64 in a new UInt64, since unsigned integers can’t be negated.

Since: 1.11.3

Returns

The UInt64 object.

11.12.2.14. uint64:__add()

Adds two UInt64 together and returns a new one. This may wrap the value.

Since: 1.11.3

11.12.2.15. uint64:__sub()

Subtracts two UInt64 and returns a new one. This may wrap the value.

Since: 1.11.3

11.12.2.16. uint64:__mul()

Multiplies two UInt64 and returns a new one. This may truncate the value.

Since: 1.11.3

11.12.2.17. uint64:__div()

Divides two UInt64 and returns a new one. Integer divide, no remainder. Trying to divide by zero results in a Lua error.

Since: 1.11.3

Returns

The UInt64 result.

11.12.2.18. uint64:__mod()

Divides two UInt64 and returns a new one of the remainder. Trying to modulo by zero results in a Lua error.

Since: 1.11.3

Returns

The UInt64 result.

11.12.2.19. uint64:__pow()

The first UInt64 is taken to the power of the second UInt64/number, returning a new one. This may truncate the value.

Since: 1.11.3

Returns

The UInt64 object.

11.12.2.20. uint64:__eq()

Returns true if both UInt64 are equal.

Since: 1.11.3

11.12.2.21. uint64:__lt()

Returns true if first UInt64 is less than the second.

Since: 1.11.3

11.12.2.22. uint64:__le()

Returns true if first UInt64 is less than or equal to the second.

Since: 1.11.3

11.12.2.23. uint64:bnot()

Returns a UInt64 of the bitwise 'not' operation.

Since: 1.11.3

Returns

The UInt64 object.

11.12.2.24. uint64:band()

Returns a UInt64 of the bitwise 'and' operation, with the given number/Int64/UInt64. Note that multiple arguments are allowed.

Since: 1.11.3

11.12.2.25. uint64:bor()

Returns a UInt64 of the bitwise 'or' operation, with the given number/Int64/UInt64. Note that multiple arguments are allowed.

Since: 1.11.3

11.12.2.26. uint64:bxor()

Returns a UInt64 of the bitwise 'xor' operation, with the given number/Int64/UInt64. Note that multiple arguments are allowed.

Since: 1.11.3

11.12.2.27. uint64:lshift(numbits)

Returns a UInt64 of the bitwise logical left-shift operation, by the given number of bits.

Since: 1.11.3

Arguments
numbits
The number of bits to left-shift by.
Returns

The UInt64 object.

11.12.2.28. uint64:rshift(numbits)

Returns a UInt64 of the bitwise logical right-shift operation, by the given number of bits.

Since: 1.11.3

Arguments
numbits
The number of bits to right-shift by.
Returns

The UInt64 object.

11.12.2.29. uint64:arshift(numbits)

Returns a UInt64 of the bitwise arithmetic right-shift operation, by the given number of bits.

Since: 1.11.3

Arguments
numbits
The number of bits to right-shift by.
Returns

The UInt64 object.

11.12.2.30. uint64:rol(numbits)

Returns a UInt64 of the bitwise left rotation operation, by the given number of bits (up to 63).

Since: 1.11.3

Arguments
numbits
The number of bits to roll left by.
Returns

The UInt64 object.

11.12.2.31. uint64:ror(numbits)

Returns a UInt64 of the bitwise right rotation operation, by the given number of bits (up to 63).

Since: 1.11.3

Arguments
numbits
The number of bits to roll right by.
Returns

The UInt64 object.

11.12.2.32. uint64:bswap()

Returns a UInt64 of the bytes swapped. This can be used to convert little-endian 64-bit numbers to big-endian 64 bit numbers or vice versa.

Since: 1.11.3

Returns

The UInt64 object.