13.13. Handling 64-bit Integers
Prev | Chapter 13. Wireshark’s Lua API Reference Manual | Next

## 13.13. Handling 64-bit Integers

Lua uses one single number representation, which is 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
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)

| Note
Lua 5.3 and later adds a second number representation for integers, which is also chosen at compile time. It is usually a 64-bit signed integer type, even on 32-bit platforms. (Lua 5.2 and earlier have an integer type, but this is not used for storing numbers, only for casting, and on 32-bit platforms is 32-bits wide.) Wireshark 4.4 and later will use the Lua integer type where possible, but as storing 64-bit unsigned integers in a Lua Integer can result in signed number overflow, `UInt64` is still necessary. `Int64` is also still available for use.

### 13.13.1. Int64

`Int64` represents a 64 bit signed integer.

Note the caveats listed above.

#### 13.13.1.1. Int64.decode(string, [endian])

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

##### 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.

#### 13.13.1.2. Int64.new([value], [highvalue])

Creates a `Int64` object.

##### 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.

#### 13.13.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.

##### Returns

The new `Int64` object of the maximum value.

#### 13.13.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.

##### Returns

The new `Int64` object of the minimum value.

#### 13.13.1.5. Int64.fromhex(hex)

Creates an `Int64` object from the given hexadecimal string.

##### Arguments

hex
  The hex-ASCII Lua string.

##### Returns

The new `Int64` object.

#### 13.13.1.6. int64:encode([endian])

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

##### 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.

#### 13.13.1.7. int64:__call()

Creates a `Int64` object.

##### Returns

The new `Int64` object.

#### 13.13.1.8. int64:tonumber()

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

##### Returns

The Lua number.

#### 13.13.1.9. int64:tohex([numbytes])

Returns a hexadecimal string of the `Int64` value.

##### Arguments

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

##### Returns

The string hex.

#### 13.13.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.

##### Returns

The Lua number.

#### 13.13.1.11. int64:lower()

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

##### Returns

The Lua number.

#### 13.13.1.12. int64:__tostring()

Converts the `Int64` into a string of decimal digits.

##### Returns

The Lua string.

#### 13.13.1.13. int64:__unm()

Returns the negative of the `Int64` as a new `Int64`.

##### Returns

The new `Int64`.

#### 13.13.1.14. int64:__add()

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

#### 13.13.1.15. int64:__sub()

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

#### 13.13.1.16. int64:__mul()

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

#### 13.13.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.

##### Returns

The `Int64` object.

#### 13.13.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.

##### Returns

The `Int64` object.

#### 13.13.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.

##### Returns

The `Int64` object.

#### 13.13.1.20. int64:__eq()

Returns `true` if both `Int64` are equal.

#### 13.13.1.21. int64:__lt()

Returns `true` if first `Int64` is less than the second.

#### 13.13.1.22. int64:__le()

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

#### 13.13.1.23. int64:bnot()

Returns a `Int64` of the bitwise 'not' operation.

##### Returns

The `Int64` object.

#### 13.13.1.24. int64:band()

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

#### 13.13.1.25. int64:bor()

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

#### 13.13.1.26. int64:bxor()

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

#### 13.13.1.27. int64:lshift(numbits)

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

##### Arguments

numbits
  The number of bits to left-shift by.

##### Returns

The `Int64` object.

#### 13.13.1.28. int64:rshift(numbits)

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

##### Arguments

numbits
  The number of bits to right-shift by.

##### Returns

The `Int64` object.

#### 13.13.1.29. int64:arshift(numbits)

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

##### Arguments

numbits
  The number of bits to right-shift by.

##### Returns

The `Int64` object.

#### 13.13.1.30. int64:rol(numbits)

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

##### Arguments

numbits
  The number of bits to roll left by.

##### Returns

The `Int64` object.

#### 13.13.1.31. int64:ror(numbits)

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

##### Arguments

numbits
  The number of bits to roll right by.

##### Returns

The `Int64` object.

#### 13.13.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.

##### Returns

The `Int64` object.

### 13.13.2. UInt64

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

Note the caveats listed above.

#### 13.13.2.1. UInt64.decode(string, [endian])

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

##### 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.

#### 13.13.2.2. UInt64.new([value], [highvalue])

Creates a `UInt64` object.

##### 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.

#### 13.13.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.

##### Returns

The maximum value.

#### 13.13.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.

##### Returns

The minimum value.

#### 13.13.2.5. UInt64.fromhex(hex)

Creates a `UInt64` object from the given hex string.

##### Arguments

hex
  The hex-ASCII Lua string.

##### Returns

The new `UInt64` object.

#### 13.13.2.6. uint64:encode([endian])

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

##### 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.

#### 13.13.2.7. uint64:__call()

Creates a `UInt64` object.

##### Returns

The new `UInt64` object.

#### 13.13.2.8. uint64:tonumber()

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

##### Returns

The Lua number.

#### 13.13.2.9. uint64:__tostring()

Converts the `UInt64` into a string.

##### Returns

The Lua string.

#### 13.13.2.10. uint64:tohex([numbytes])

Returns a hex string of the `UInt64` value.

##### Arguments

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

##### Returns

The string hex.

#### 13.13.2.11. uint64:higher()

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

##### Returns

The Lua number.

#### 13.13.2.12. uint64:lower()

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

##### Returns

The Lua number.

#### 13.13.2.13. uint64:__unm()

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

##### Returns

The `UInt64` object.

#### 13.13.2.14. uint64:__add()

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

#### 13.13.2.15. uint64:__sub()

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

#### 13.13.2.16. uint64:__mul()

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

#### 13.13.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.

##### Returns

The `UInt64` result.

#### 13.13.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.

##### Returns

The `UInt64` result.

#### 13.13.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.

##### Returns

The `UInt64` object.

#### 13.13.2.20. uint64:__eq()

Returns true if both `UInt64` are equal.

#### 13.13.2.21. uint64:__lt()

Returns true if first `UInt64` is less than the second.

#### 13.13.2.22. uint64:__le()

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

#### 13.13.2.23. uint64:bnot()

Returns a `UInt64` of the bitwise 'not' operation.

##### Returns

The `UInt64` object.

#### 13.13.2.24. uint64:band()

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

#### 13.13.2.25. uint64:bor()

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

#### 13.13.2.26. uint64:bxor()

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

#### 13.13.2.27. uint64:lshift(numbits)

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

##### Arguments

numbits
  The number of bits to left-shift by.

##### Returns

The `UInt64` object.

#### 13.13.2.28. uint64:rshift(numbits)

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

##### Arguments

numbits
  The number of bits to right-shift by.

##### Returns

The `UInt64` object.

#### 13.13.2.29. uint64:arshift(numbits)

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

##### Arguments

numbits
  The number of bits to right-shift by.

##### Returns

The `UInt64` object.

#### 13.13.2.30. uint64:rol(numbits)

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

##### Arguments

numbits
  The number of bits to roll left by.

##### Returns

The `UInt64` object.

#### 13.13.2.31. uint64:ror(numbits)

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

##### Arguments

numbits
  The number of bits to roll right by.

##### Returns

The `UInt64` object.

#### 13.13.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.

##### Returns

The `UInt64` object.

Prev | Up | Next
13.12. Directory Handling Functions | Home | 13.14. Binary encode/decode support