# 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: ''