mirror of
https://github.com/rojo-rbx/rojo.git
synced 2026-10-23 14:01:37 +00:00
491 lines
13 KiB
YAML
491 lines
13 KiB
YAML
# This file is automatically generated. Please don't edit it manually.
|
|
# To submit a bug report on the content, see
|
|
# https://devforum.roblox.com/c/bug-reports/documentation-issues/72
|
|
|
|
name: bit32
|
|
type: library
|
|
summary: |
|
|
A library of functions to perform bitwise operations.
|
|
description: |
|
|
This library provides functions to perform bitwise operations.
|
|
|
|
#### Number Limitations
|
|
|
|
This library treats numbers as unsigned 32-bit integers; numbers will be
|
|
converted to this before being used (see image below). Numbers with decimal
|
|
numbers are rounded to the nearest whole number.
|
|
|
|
<img src="../../../assets/engine-api/libraries/bit32/32-Bit-Restriction.png" width="500" alt="32-bit integer conversion (in hexadecimal)" />
|
|
tags: []
|
|
code_samples: []
|
|
properties: []
|
|
functions:
|
|
- name: bit32.arshift
|
|
summary: |
|
|
Returns a number after its bits have been arithmetically shifted to the
|
|
right by a given displacement.
|
|
description: |
|
|
Returns the number `x` shifted `disp` bits to the right. The number `disp`
|
|
may be any representable integer. Negative displacements shift to the
|
|
left.
|
|
|
|
This shift operation is what is called arithmetic shift. Vacant bits on
|
|
the left are filled with copies of the higher bit of `x`; vacant bits on
|
|
the right are filled with zeros. In particular, displacements with
|
|
absolute values higher than 31 result in zero or 0xFFFFFFFF (all original
|
|
bits are shifted out).
|
|
parameters:
|
|
- name: x
|
|
type: number
|
|
default:
|
|
summary: |
|
|
The number whose bits shall be shifted.
|
|
- name: disp
|
|
type: number
|
|
default:
|
|
summary: |
|
|
The integer number of bits to shift by.
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.band
|
|
summary: |
|
|
Returns the bitwise AND of all provided numbers.
|
|
description: |
|
|
Returns the bitwise AND of all provided numbers.
|
|
|
|
Each bit is tested against the following truth table:
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>A</th>
|
|
<th>B</th>
|
|
<th>Output</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>0</td>
|
|
<td>0</td>
|
|
<td>0</td>
|
|
</tr>
|
|
<tr>
|
|
<td>1</td>
|
|
<td>0</td>
|
|
<td>0</td>
|
|
</tr>
|
|
<tr>
|
|
<td>0</td>
|
|
<td>1</td>
|
|
<td>0</td>
|
|
</tr>
|
|
<tr>
|
|
<td>1</td>
|
|
<td>1</td>
|
|
<td>1</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<img src="../../../assets/engine-api/libraries/bit32/AND.png" width="500" alt="Bitwise AND of 3 numbers" />
|
|
parameters:
|
|
- name: numbers
|
|
type: Tuple
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.bnot
|
|
summary: |
|
|
Returns the bitwise negation of a given number.
|
|
description: |
|
|
Returns the bitwise negation of `x`.
|
|
|
|
<img src="../../../assets/engine-api/libraries/bit32/NOT.png" width="500" alt="Negation of a provided number" />
|
|
|
|
For any integer `x`, the following identity holds:
|
|
|
|
```lua
|
|
assert(bit32.bnot(x) == (-1 - x) % 2^32)
|
|
```
|
|
parameters:
|
|
- name: x
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.bor
|
|
summary: |
|
|
Returns the bitwise OR of all provided numbers.
|
|
description: |
|
|
Returns the bitwise OR of all provided numbers.
|
|
|
|
Each bit is tested against the following truth table:
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>A</th>
|
|
<th>B</th>
|
|
<th>Output</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>0</td>
|
|
<td>0</td>
|
|
<td>0</td>
|
|
</tr>
|
|
<tr>
|
|
<td>1</td>
|
|
<td>0</td>
|
|
<td>1</td>
|
|
</tr>
|
|
<tr>
|
|
<td>0</td>
|
|
<td>1</td>
|
|
<td>1</td>
|
|
</tr>
|
|
<tr>
|
|
<td>1</td>
|
|
<td>1</td>
|
|
<td>1</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<img src="../../../assets/engine-api/libraries/bit32/OR.png" width="500" alt="Bitwise OR of 3 numbers" />
|
|
parameters:
|
|
- name: numbers
|
|
type: Tuple
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.btest
|
|
summary: |
|
|
Returns a boolean describing whether the bitwise and of its operands is
|
|
different from zero.
|
|
description: |
|
|
Returns a boolean signalling whether the bitwise _and_ of its operands is
|
|
different from zero.
|
|
parameters:
|
|
- name: numbers
|
|
type: Tuple
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: bool
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.bxor
|
|
summary: |
|
|
Returns the bitwise XOR of all provided numbers.
|
|
description: |
|
|
Returns the bitwise XOR of all provided numbers.
|
|
|
|
Each bit is tested against the following truth table:
|
|
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th>A</th>
|
|
<th>B</th>
|
|
<th>Output</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td>0</td>
|
|
<td>0</td>
|
|
<td>0</td>
|
|
</tr>
|
|
<tr>
|
|
<td>1</td>
|
|
<td>0</td>
|
|
<td>1</td>
|
|
</tr>
|
|
<tr>
|
|
<td>0</td>
|
|
<td>1</td>
|
|
<td>1</td>
|
|
</tr>
|
|
<tr>
|
|
<td>1</td>
|
|
<td>1</td>
|
|
<td>0</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<img src="../../../assets/engine-api/libraries/bit32/XOR.png" width="580" alt="Bitwise XOR of 3 numbers" />
|
|
parameters:
|
|
- name: numbers
|
|
type: Tuple
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.byteswap
|
|
summary: |
|
|
Returns the given number with the order of the bytes swapped.
|
|
description: |
|
|
Returns the given number with the order of the bytes swapped.
|
|
parameters:
|
|
- name: x
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.countlz
|
|
summary: |
|
|
Returns the number of consecutive zero bits in the 32-bit representation
|
|
of the provided number starting from the left-most (most significant) bit.
|
|
description: |
|
|
Returns the number of consecutive zero bits in the 32-bit representation
|
|
of the provided number starting from the left-most (most significant) bit.
|
|
Returns 32 if the provided number is zero.
|
|
parameters:
|
|
- name: 'n'
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.countrz
|
|
summary: |
|
|
Returns the number of consecutive zero bits in the 32-bit representation
|
|
of the provided number starting from the right-most (least significant)
|
|
bit.
|
|
description: |
|
|
Returns the number of consecutive zero bits in the 32-bit representation
|
|
of the provided number starting from the right-most (least significant)
|
|
bit. Returns 32 if the provided number is zero.
|
|
parameters:
|
|
- name: 'n'
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.extract
|
|
summary: |
|
|
Extract a range of bits from a number and return them as an unsigned
|
|
number.
|
|
description: |
|
|
Returns the unsigned number formed by the bits `field` to
|
|
`field + width - 1` from `n`. Bits are numbered from 0 (least significant)
|
|
to 31 (most significant). All accessed bits must be in the range [0, 31].
|
|
The default for `width` is 1.
|
|
parameters:
|
|
- name: 'n'
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
- name: field
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
- name: width
|
|
type: number
|
|
default: 1
|
|
summary: ''
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.replace
|
|
summary: |
|
|
Return a copy of a number with a range of bits replaced by a given value.
|
|
description: |
|
|
Returns a copy of `n` with the bits `field` to `field + width - 1`
|
|
replaced by the value `v`. See `Library.bit32.extract()` for details about
|
|
`field` and `width`.
|
|
parameters:
|
|
- name: 'n'
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
- name: v
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
- name: field
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
- name: width
|
|
type: number
|
|
default: 1
|
|
summary: ''
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.lrotate
|
|
summary: |
|
|
Returns a number after its bits have been rotated to the left by a given
|
|
number of times.
|
|
description: |
|
|
Returns the number `x` rotated `disp` bits to the left. The number `disp`
|
|
may be any representable integer. For any valid displacement, the
|
|
following identity holds:
|
|
|
|
```lua
|
|
assert(bit32.lrotate(x, disp) == bit32.lrotate(x, disp % 32))
|
|
```
|
|
|
|
In particular, negative displacements rotate to the right.
|
|
parameters:
|
|
- name: x
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
- name: disp
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.lshift
|
|
summary: |
|
|
Returns a number whose bits have been logically shifted to the left by a
|
|
given displacement.
|
|
description: |
|
|
Returns the number `x` shifted `disp` bits to the left. The number `disp`
|
|
may be any representable integer. Negative displacements shift to the
|
|
right. In any direction, vacant bits are filled with zeros. In particular,
|
|
displacements with absolute values higher than 31 result in zero (all bits
|
|
are shifted out).
|
|
|
|
<img src="../../../assets/engine-api/libraries/bit32/LSHIFT.png" width="500" alt="Number shifted 3 to the left" />
|
|
|
|
For positive displacements, the following equality holds:
|
|
|
|
```lua
|
|
assert(bit32.lshift(b, disp) == (b * 2^disp) % 2^32)
|
|
```
|
|
parameters:
|
|
- name: x
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
- name: disp
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.rrotate
|
|
summary: |
|
|
Returns a number after its bits have been rotated to the right by a given
|
|
number of times.
|
|
description: |
|
|
Returns the number `x` rotated `disp` bits to the right. The number `disp`
|
|
may be any representable integer.
|
|
|
|
For any valid displacement, the following identity holds:
|
|
|
|
```lua
|
|
assert(bit32.rrotate(x, disp) == bit32.rrotate(x , disp % 32))
|
|
```
|
|
|
|
In particular, negative displacements rotate to the left.
|
|
parameters:
|
|
- name: x
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
- name: disp
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|
|
- name: bit32.rshift
|
|
summary: |
|
|
Returns a number whose bits have been logically shifted to the right by a
|
|
given displacement.
|
|
description: |
|
|
Returns the number `x` shifted `disp` bits to the right. The number `disp`
|
|
may be any representable integer. Negative displacements shift to the
|
|
left. In any direction, vacant bits are filled with zeros. In particular,
|
|
displacements with absolute values higher than 31 result in zero (all bits
|
|
are shifted out).
|
|
|
|
<img src="../../../assets/engine-api/libraries/bit32/RSHIFT.png" width="500" alt="Number shifted 3 to the right" />
|
|
|
|
For positive displacements, the following equality holds:
|
|
|
|
```lua
|
|
assert(bit32.rshift(b, disp) == (b % 2^32 / 2^disp) // 1)
|
|
```
|
|
|
|
This shift operation is what is called logical shift.
|
|
parameters:
|
|
- name: x
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
- name: disp
|
|
type: number
|
|
default:
|
|
summary: ''
|
|
returns:
|
|
- type: number
|
|
summary: ''
|
|
tags: []
|
|
code_samples: []
|
|
deprecation_message: ''
|