== SRFI 60: Integers as Bits

This egg provides the SRFI 60 bitwise library, implemented as a very
thin wrapper on top of [[bitwise-utils]].  Every form that appears here
can be found in bitwise-utils under a different name, and [[srfi-151]]
provides many operations not found in either egg.  There's not much reason
to use this library.

[[toc:]]

== SRFI description

This page is intended to document the forms provided by this egg.
For a full description of SRFI 60, see
[[https://srfi.schemers.org/srfi-60/|the SRFI document]].

== Specification

=== Bitwise Operations

<procedure>(logand n1 ...)</procedure>
<procedure>(bitwise-and n1 ...)</procedure>

Returns the integer which is the bit-wise AND of the integer arguments.

Example:

<enscript highlight="scheme">
(number->string (logand #b1100 #b1010) 2)
    ; => "1000"
</enscript>

<procedure>(logior n1 ...)</procedure>
<procedure>(bitwise-ior n1 ...)</procedure>

Returns the integer which is the bit-wise OR of the integer arguments.

Example:

<enscript highlight="scheme">
(number->string (logior #b1100 #b1010) 2)
    ; => "1110"
</enscript>

<procedure>(logxor n1 ...)</procedure>
<procedure>(bitwise-xor n1 ...)</procedure>

Returns the integer which is the bit-wise XOR of the integer arguments.

Example:

<enscript highlight="scheme">
(number->string (logxor #b1100 #b1010) 2)
    ; => "110"
</enscript>

<procedure>(lognot n)</procedure>
<procedure>(bitwise-not n)</procedure>

Returns the integer which is the one's-complement of the integer argument.

Example:

<enscript highlight="scheme">
(number->string (lognot #b10000000) 2)
    ; => "-10000001"
(number->string (lognot #b0) 2)
    ; => "-1"
</enscript>

<procedure>(bitwise-if mask n0 n1)</procedure>
<procedure>(bitwise-merge mask n0 n1)</procedure>

Returns an integer composed of some bits from integer ''n0'' and some
from integer ''n1''. A bit of the result is taken from ''n0'' if the
corresponding bit of integer mask is 1 and from ''n1'' if that bit of
mask is 0.

<procedure>(logtest j k)</procedure>
<procedure>(any-bits-set? j k)</procedure>

<enscript highlight="scheme">
(logtest j k) == (not (zero? (logand j k)))

(logtest #b0100 #b1011) ; => #f
(logtest #b0100 #b0111) ; => #t
</enscript>

=== Integer Properties

<procedure>(logcount n)</procedure>
<procedure>(bit-count n)</procedure>

Returns the number of bits in integer ''n''. If integer is positive,
the 1-bits in its binary representation are counted. If negative, the
0-bits in its two's-complement binary representation are counted. If 0,
0 is returned.

Example:

<enscript highlight="scheme">
(logcount #b10101010)
   ; => 4
(logcount 0)
   ; => 0
(logcount -2)
   ; => 1
</enscript>

<procedure>(integer-length n)</procedure>

Returns the number of bits neccessary to represent ''n''.

Example:

<enscript highlight="scheme">
(integer-length #b10101010)
   ; => 8
(integer-length 0)
   ; => 0
(integer-length #b1111)
   ; => 4
</enscript>

<procedure>(log2-binary-factors n)</procedure>
<procedure>(first-set-bit n)</procedure>

Returns the number of factors of two of integer ''n''. This value is
also the bit-index of the least-significant 1-bit in ''n''.

==== Bit Within Word

<procedure>(logbit? index n)</procedure>
<procedure>(bit-set? index n)</procedure>

Example:

<enscript highlight="scheme">
(logbit? index n) == (logtest (expt 2 index) n)

(logbit? 0 #b1101) ; => #t
(logbit? 1 #b1101) ; => #f
(logbit? 2 #b1101) ; => #t
(logbit? 3 #b1101) ; => #t
(logbit? 4 #b1101) ; => #f
</enscript>

<procedure>(copy-bit index from bit)</procedure>

Returns an integer the same as from except in the indexth bit,
which is 1 if ''bit'' is {{#t}} and 0 if ''bit'' is {{#f}}.

Example:

<enscript highlight="scheme">
(number->string (copy-bit 0 0 #t) 2)      ; => "1"
(number->string (copy-bit 2 0 #t) 2)      ; => "100"
(number->string (copy-bit 2 #b1111 #f) 2) ; => "1011"
</enscript>

==== Field of Bits

<procedure>(bit-field n start end)</procedure>

Returns the integer composed of the ''start'' (inclusive) through
''end'' (exclusive) bits of ''n''. The ''start''th bit becomes the
0-th bit in the result.

Example:

<enscript highlight="scheme">
(number->string (bit-field #b1101101010 0 4) 2)
   ; => "1010"
(number->string (bit-field #b1101101010 4 9) 2)
   ; => "10110"
</enscript>

<procedure>(copy-bit-field to from start end)</procedure>

Returns an integer the same as to except possibly in the ''start''
(inclusive) through ''end'' (exclusive) bits, which are the same
as those of from. The 0-th bit of from becomes the ''start''th bit
of the result.

Example:

<enscript highlight="scheme">
(number->string (copy-bit-field #b1101101010 0 0 4) 2)
   ; => "1101100000"
(number->string (copy-bit-field #b1101101010 -1 0 4) 2)
   ; => "1101101111"
(number->string (copy-bit-field #b110100100010000 -1 5 9) 2)
   ; => "110100111110000"
</enscript>

<procedure>(ash n count)</procedure>
<procedure>(arithmetic-shift n count)</procedure>

Returns an integer equivalent to
{{(inexact->exact (floor (* n (expt 2 count))))}}.

Example:

<enscript highlight="scheme">
(number->string (ash #b1 3) 2)
   ; => "1000"
(number->string (ash #b1010 -1) 2)
   ; => "101"
</enscript>

<procedure>(rotate-bit-field n count start end)</procedure>

Returns ''n'' with the bit-field from ''start'' to ''end'' cyclically
permuted by count bits towards high-order.

Example:

<enscript highlight="scheme">
(number->string (rotate-bit-field #b0100 3 0 4) 2)
   ; => "10"
(number->string (rotate-bit-field #b0100 -1 0 4) 2)
   ; => "10"
(number->string (rotate-bit-field #b110100100010000 -1 5 9) 2)
   ; => "110100010010000"
(number->string (rotate-bit-field #b110100100010000 1 5 9) 2)
   ; => "110100000110000"
</enscript>

<procedure>(reverse-bit-field n start end)</procedure>

Returns ''n'' with the order of bits ''start'' to ''end'' reversed.

Example:

<enscript highlight="scheme">
(number->string (reverse-bit-field #xa7 0 8) 16)
   ; => "e5"
</enscript>

=== Bits as Booleans

<procedure>(integer->list k len)</procedure>
<procedure>(integer->list k)</procedure>

{{integer->list}} returns a list of ''len'' booleans corresponding to
each bit of the non-negative integer ''k''. {{#t}} is coded for each 1;
{{#f}} for 0. The ''len'' argument defaults to {{(integer-length k)}}

<procedure>(list->integer list)</procedure>

{{list->integer}} returns an integer formed from the booleans in the list
list, which must be a list of booleans. A 1 bit is coded for each {{#t}};
a 0 bit for {{#f}}.

{{integer->list}} and {{list->integer}} are inverses so far as {{equal?}}
is concerned.

<procedure>(booleans->integer bool1 ...)</procedure>

Returns the integer coded by the ''bool1'' ... arguments.

== About this egg

=== Author

Aubrey Jaffer

Originally ported to hygienic Chicken 3 with test suite by
Peter Danenberg.  Ported to Chicken 5 by Sergey Goldgaber.

=== Maintainer

Wolfgang Corcoran-Mathe

Contact: {{wcm at sigwinch dot xyzzy minus the zy}}

=== Repository

[[https://github.com/Zipheir/srfi-60|GitHub]]

=== Version history

; 0.7 : Registered the srfi-60 feature, linked to source code
; 0.6 : Replaced srfi-60 implementation with that from bitwise-utils
; 0.5 : Using (chicken bitwise) procedures, where possible
; 0.4 : Ported to Chicken 5
; 0.3 : release version 0.3
; 0.2 : adopting trunk/tags directory layout.  Tagging version 0.2.

=== License

Copyright (C) Aubrey Jaffer (2004, 2005). All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.