luau-lang/luau
1
0
Fork 0
mirror of https://github.com/luau-lang/luau.git synced 2025-05-04 10:33:46 +01:00
Code Issues Projects Releases Packages Wiki Activity

Update function-bit32-clz-ctz.md

Browse source 
Rename to countlz/countrz
This commit is contained in:
Arseny Kapoulkine 2021-10-27 08:30:51 -07:00 • committed by GitHub
parent 68ec52a17c
commit 668e82b70b
Signed by: DevComp
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 12 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
rfcs/function-bit32-clz-ctz.md
View file

@ -1,8 +1,8 @@
# bit32.clz/ctz
# bit32.countlz/countrz
## Summary
Add bit32.clz (count leading zeroes) and bit32.ctz (count trailing zeroes) to accelerate bit scanning
Add bit32.countlz (count left zeroes) and bit32.countrz (count right zeroes) to accelerate bit scanning
## Motivation
@ -12,28 +12,27 @@ All CPUs have instructions to determine the position of first/last set bit in an
- Scanning set bits in an integer, which allows efficient traversal of compact representation of bitmaps
- Allocating bits out of a bitmap quickly
Today it's possible to approximate `clz` using `floor` and `log` but this approximation is relatively slow; approximating `ctz` is difficult without iterating through each bit.
Today it's possible to approximate `countlz` using `floor` and `log` but this approximation is relatively slow; approximating `ccountrz` is difficult without iterating through each bit.
## Design
`bit32` library will gain two new functions, `clz` and `ctz`:
`bit32` library will gain two new functions, `countlz` and `countrz`:
```
function bit32.clz(n: number): number
function bit32.ctz(n: number): number
function bit32.countlz(n: number): number
function bit32.countrz(n: number): number
```
`clz` takes an integer number (converting the input number to a 32-bit unsigned integer as all other `bit32` functions do), and returns the number of leading zero bits - that is,
the number of most significant zero bits in a 32-bit number until the first 1. The result is in `[0, 32]` range.
`countlz` takes an integer number (converting the input number to a 32-bit unsigned integer as all other `bit32` functions do), and returns the number of consecutive left-most zero bits - that is, the number of most significant zero bits in a 32-bit number until the first 1. The result is in `[0, 32]` range.
For example, when the input number is `0`, it's `32`. When the input number is `2^k`, the result is `31-k`.
`ctz` takes an integer number (converting the input number to a 32-bit unsigned integer as all other `bit32` functions do), and returns the number of trailing zero bits - that is,
`countrz` takes an integer number (converting the input number to a 32-bit unsigned integer as all other `bit32` functions do), and returns the number of consecutive right-most zero bits - that is,
the number of least significant zero bits in a 32-bit number until the first 1. The result is in `[0, 32]` range.
For example, when the input number is `0`, it's `32`. When the input number is `2^k`, the result is `k`.
> Non-normative: a proof of concept implementation shows that a polyfill for `clz` takes ~34 ns per loop iteration when computing `clz` for an increasing number sequence, whereas
> Non-normative: a proof of concept implementation shows that a polyfill for `countlz` takes ~34 ns per loop iteration when computing `countlz` for an increasing number sequence, whereas
> a builtin implementation takes ~4 ns.
## Drawbacks
@ -46,4 +45,6 @@ These functions can be alternatively specified as "find the position of the most
can be more immediately useful since the bit position is usually more important than the number of bits. However, the bit position is undefined when the input number is zero,
returning a sentinel such as -1 seems non-idiomatic, and returning `nil` seems awkward for calling code. Counting functions don't have this problem.
Of the two functions, `clz` is vastly more useful than `ctz`; we could implement just `clz`, but having both is nice for symmetry.
An early version of this proposal suggested `clz`/`ctz` (leading/trailing) as names; however, using a full verb is more consistent with other operations like shift/rotate, and left/right may be easier to understand intuitively compared to leading/trailing. left/right are used by C++20.
Of the two functions, `countlz` is vastly more useful than `countrz`; we could implement just `countlz`, but having both is nice for symmetry.