Manual page for bitwise-first-bit-set(3scm)

bitwise-first-bit-set, fxfirst-bit-set - first bit set in an integer

LIBRARY

(import (rnrs))                     ;R6RS
(import (rnrs arithmetic bitwise))  ;R6RS
(import (rnrs arithmetic fixnums))  ;R6RS

SYNOPSIS

(bitwise-first-bit-set ei)
(fxfirst-bit-set fx)

DESCRIPTION

Returns the index of the least significant 1 bit in the two's complement representation of the argument. If it is 0, then −1 is returned.

The argument to fxfirst-bit-set must be in the implementation's fixnum range.

RETURN VALUES

Returns a single value; an exact integer.

EXAMPLES

(bitwise-first-bit-set 0)   =>  -1
(bitwise-first-bit-set 1)   =>  0
(bitwise-first-bit-set -4)  =>  2

APPLICATION USAGE

These procedures have a variety of uses, e.g. for using integers to represent sets, and some bit-hacks.

RATIONALE

Some CPUs have an instruction that is similar to this procedure, such as the BSF instruction in the x86 ISA. If it was instead defined by user code then it would be much slower.

COMPATIBILITY

The fixnum variant of this procedure works with the implementation-defined fixnum range.

ERRORS

This procedure can raise exceptions with the following condition types:

&assertion (R6RS): The wrong number of arguments was passed or an argument was outside its domain.

STANDARDS

R4RS, IEEE Scheme, R5RS, R6RS, R7RS, SRFI-60, SRFI-143, SRFI-151

HISTORY

These procedures are new in R6RS.

AUTHORS

This page is part of the scheme-manpages project. It includes materials from the RnRS documents. More information can be found at https://github.com/schemedoc/manpages/.

Markup created by unroff 1.0sc, March 04, 2023.