integerLuauexperimentaldeprecated

Deprecated

Luau is removing these integers. Luwu will replace them with signed and unsigned integer types that have arithmetic operators.

See Compatibility

The integer library creates and converts 64-bit integers and does their arithmetic, comparisons and bitwise operations.

An integer is a signed 64-bit whole number. A number holds whole numbers exactly only up to 2^53, so IDs, hashes and file offsets past that need an integer. Write one as a literal with an i suffix: 42i, 0xffi or 0b1010i.

Integers have no arithmetic or ordering operators. 1i + 2i and 1i < 2i are runtime errors and every operation goes through this library instead. == and ~= work. An integer never equals a number, and 1i and 1 are different table keys. typeof returns "integer" and tostring prints the value in decimal without the suffix.

Arithmetic wraps around on overflow like two's complement hardware does. Functions with a u prefix read their arguments as unsigned 64-bit integers.

const big = integer.add(integer.maxsigned, 1i)
print(big == integer.minsigned) --> true

const total = integer.mul(1_000_000i, 3_000_000i)
print(total) --> 3000000000000
Summary

Creating and converting

integer.createLuau
Converts a number to an integer
integer.fromstringLuau
Parses a string as an integer in a given base
integer.tonumberLuau
Converts an integer to the nearest number

Limits

integer.maxsignedLuau
Holds the largest integer (2^63 - 1)
integer.minsignedLuau
Holds the smallest integer (-2^63)

Arithmetic

integer.negLuau
Negates an integer
integer.addLuau
Adds two integers and wraps around on overflow
integer.subLuau
Subtracts one integer from another and wraps around on overflow
integer.mulLuau
Multiplies two integers and wraps around on overflow
integer.divLuau
Divides and rounds the quotient toward zero
integer.idivLuau
Divides and rounds the quotient down
integer.remLuau
Returns the remainder of integer.div
integer.modLuau
Returns the remainder of integer.idiv
integer.udivLuau
Divides two integers read as unsigned
integer.uremLuau
Returns the remainder of integer.udiv

Comparison

integer.minLuau
Returns the smallest of its arguments
integer.maxLuau
Returns the largest of its arguments
integer.clampLuau
Limits an integer to a range
integer.ltLuau
Checks whether x < y as signed integers
integer.leLuau
Checks whether x <= y as signed integers
integer.gtLuau
Checks whether x > y as signed integers
integer.geLuau
Checks whether x >= y as signed integers
integer.ultLuau
Checks whether x < y as unsigned integers
integer.uleLuau
Checks whether x <= y as unsigned integers
integer.ugtLuau
Checks whether x > y as unsigned integers
integer.ugeLuau
Checks whether x >= y as unsigned integers

Bitwise operations

integer.bandLuau
Returns the bitwise and of its arguments
integer.borLuau
Returns the bitwise or of its arguments
integer.bxorLuau
Returns the bitwise exclusive or of its arguments
integer.bnotLuau
Flips every bit of an integer
integer.btestLuau
Checks whether the bitwise and of its arguments isn't zero

Shifts and rotations

integer.lshiftLuau
Shifts bits left and fills the vacated bits with zeros
integer.rshiftLuau
Shifts bits right and fills the vacated bits with zeros
integer.arshiftLuau
Shifts bits right and fills the vacated bits with the sign bit
integer.lrotateLuau
Rotates bits left
integer.rrotateLuau
Rotates bits right

Bit fields, counting and byte order

integer.extractLuau
Returns a field of bits as an unsigned value
integer.replaceLuau
Replaces a field of bits with the low bits of a value
integer.countlzLuau
Counts the zero bits above the highest set bit
integer.countrzLuau
Counts the zero bits below the lowest set bit
integer.bswapLuau
Reverses the order of an integer's 8 bytes

Creating and converting

integer.createLuau

function integer.create(x: number): integer?

Converts a number to an integer. It returns nil when x has a fractional part or lies outside the signed 64-bit range.

print(integer.create(7)) --> 7
print(integer.create(2.5)) --> nil
print(integer.create(2^63)) --> nil

The type checker declares the result as integer even though it can be nil.

integer.fromstringLuau

function integer.fromstring(str: string, base: number?): integer?

Parses str as an integer in base. The base defaults to 10 and must be from 2 to 36. It returns nil when the string isn't a valid integer. Surrounding whitespace is allowed.

In base 10 the string may start with a sign or with 0x for hexadecimal, and values beyond the signed range clamp to integer.minsigned or integer.maxsigned. Other bases parse the digits as an unsigned 64-bit value: integer.fromstring("ffffffffffffffff", 16) is -1i.

print(integer.fromstring("-42")) --> -42
print(integer.fromstring("ff", 16)) --> 255
print(integer.fromstring("12i")) --> nil

The type checker declares the result as integer even though it can be nil.

integer.tonumberLuau

function integer.tonumber(x: integer): number

Converts an integer to the nearest number. Values beyond 2^53 lose precision: integer.tonumber(9007199254740993i) is 9007199254740992.

Limits

integer.maxsignedLuau

integer.maxsigned: integer

The largest integer, 9223372036854775807 (2^63 - 1).

integer.minsignedLuau

integer.minsigned: integer

The smallest integer, -9223372036854775808 (-2^63).

Arithmetic

integer.negLuau

function integer.neg(x: integer): integer

Returns -x. Negating integer.minsigned wraps around and returns integer.minsigned.

integer.addLuau

function integer.add(x: integer, y: integer): integer

Returns x + y. The result wraps around on overflow.

integer.subLuau

function integer.sub(x: integer, y: integer): integer

Returns x - y. The result wraps around on overflow.

integer.mulLuau

function integer.mul(x: integer, y: integer): integer

Returns x * y. The result wraps around on overflow.

integer.divLuau

function integer.div(x: integer, y: integer): integer

Divides x by y and rounds the quotient toward zero. A zero divisor throws division by zero and dividing integer.minsigned by -1 throws integer overflow.

print(integer.div(-7i, 2i)) --> -3
print(integer.idiv(-7i, 2i)) --> -4

integer.idivLuau

function integer.idiv(x: integer, y: integer): integer

Divides x by y and rounds the quotient down, like // does for numbers. It throws in the same cases as integer.div.

integer.remLuau

function integer.rem(x: integer, y: integer): integer

Returns the remainder of integer.div(x, y). It has the sign of x. A zero divisor throws division by zero.

print(integer.rem(-7i, 2i)) --> -1
print(integer.mod(-7i, 2i)) --> 1

integer.modLuau

function integer.mod(x: integer, y: integer): integer

Returns the remainder of integer.idiv(x, y). It has the sign of y like % does for numbers. A zero divisor throws division by zero.

integer.udivLuau

function integer.udiv(x: integer, y: integer): integer

Divides x by y with both read as unsigned 64-bit integers. integer.udiv(-1i, 2i) is integer.maxsigned. A zero divisor throws division by zero.

integer.uremLuau

function integer.urem(x: integer, y: integer): integer

Returns the remainder of integer.udiv(x, y). A zero divisor throws division by zero.

Comparison

integer.minLuau

function integer.min(first: integer, ...: integer): integer

Returns the smallest of its arguments. It takes at least one integer.

integer.maxLuau

function integer.max(first: integer, ...: integer): integer

Returns the largest of its arguments. It takes at least one integer.

integer.clampLuau

function integer.clamp(x: integer, min: integer, max: integer): integer

Returns x limited to the range from min to max. It throws when min is greater than max.

integer.ltLuau

function integer.lt(x: integer, y: integer): boolean

Returns whether x < y with both values read as signed 64-bit integers.

integer.leLuau

function integer.le(x: integer, y: integer): boolean

Returns whether x <= y with both values read as signed 64-bit integers.

integer.gtLuau

function integer.gt(x: integer, y: integer): boolean

Returns whether x > y with both values read as signed 64-bit integers.

integer.geLuau

function integer.ge(x: integer, y: integer): boolean

Returns whether x >= y with both values read as signed 64-bit integers.

integer.ultLuau

function integer.ult(x: integer, y: integer): boolean

Returns whether x < y with both values read as unsigned 64-bit integers.

integer.uleLuau

function integer.ule(x: integer, y: integer): boolean

Returns whether x <= y with both values read as unsigned 64-bit integers.

integer.ugtLuau

function integer.ugt(x: integer, y: integer): boolean

Returns whether x > y with both values read as unsigned 64-bit integers.

integer.ugeLuau

function integer.uge(x: integer, y: integer): boolean

Returns whether x >= y with both values read as unsigned 64-bit integers.

Bitwise operations

integer.bandLuau

function integer.band(...: integer): integer

Returns the bitwise and of its arguments. With no arguments it returns -1i (every bit set).

integer.borLuau

function integer.bor(...: integer): integer

Returns the bitwise or of its arguments. With no arguments it returns 0i.

integer.bxorLuau

function integer.bxor(...: integer): integer

Returns the bitwise exclusive or of its arguments. With no arguments it returns 0i.

integer.bnotLuau

function integer.bnot(x: integer): integer

Returns x with every bit flipped.

integer.btestLuau

function integer.btest(...: integer): boolean

Returns whether the bitwise and of its arguments isn't zero. It is equivalent to integer.band(...) ~= 0i.

Shifts and rotations

integer.lshiftLuau

function integer.lshift(x: integer, shift: integer): integer

Shifts the bits of x left by shift and fills the vacated bits with zeros. A negative shift shifts right instead. A shift of 64 or more in either direction returns 0i.

integer.rshiftLuau

function integer.rshift(x: integer, shift: integer): integer

Shifts the bits of x right by shift and fills the vacated bits with zeros. A negative shift shifts left instead. A shift of 64 or more in either direction returns 0i.

integer.arshiftLuau

function integer.arshift(x: integer, shift: integer): integer

Shifts the bits of x right by shift and fills the vacated bits with copies of the sign bit. A negative shift shifts left instead. A right shift of 64 or more returns -1i for a negative x and 0i otherwise.

print(integer.rshift(-256i, 60i)) --> 15
print(integer.arshift(-256i, 4i)) --> -16

integer.lrotateLuau

function integer.lrotate(x: integer, shift: integer): integer

Rotates the bits of x left by shift. Bits that leave the top come back in at the bottom. The rotation is taken modulo 64, and a negative shift rotates right.

integer.rrotateLuau

function integer.rrotate(x: integer, shift: integer): integer

Rotates the bits of x right by shift. Bits that leave the bottom come back in at the top. The rotation is taken modulo 64, and a negative shift rotates left.

Bit fields, counting and byte order

integer.extractLuau

function integer.extract(x: integer, field: integer, width: integer?): integer

Returns the width bits of x starting at bit field as an unsigned value. Bit 0 is the lowest bit and width defaults to 1. field must be from 0 to 63 and width must be positive. A field that reaches past bit 63 throws.

print(integer.extract(0xf0i, 4i, 4i)) --> 15
print(integer.replace(0i, 5i, 4i, 4i)) --> 80

integer.replaceLuau

function integer.replace(x: integer, value: integer, field: integer, width: integer?): integer

Returns x with its width bits starting at bit field replaced by the low bits of value. field and width follow the same rules as in integer.extract.

integer.countlzLuau

function integer.countlz(x: integer): integer

Returns the number of zero bits above the highest set bit of x. It returns 64 for 0i.

integer.countrzLuau

function integer.countrz(x: integer): integer

Returns the number of zero bits below the lowest set bit of x. It returns 64 for 0i.

integer.bswapLuau

function integer.bswap(x: integer): integer

Reverses the order of the 8 bytes of x. It converts between little endian and big endian byte order.