source: project/wiki/eggref/5/srfi-60 @ 39268

Last change on this file since 39268 was 39268, checked in by gnosis, 6 months ago

SRFI-60 documentation update to version 0.7

File size: 15.1 KB
Line 
1== Integers as Bits
2=== Abstract
3Treating integers as two's-complement strings of bits is an arcane but important domain of computer science.
4==== It is used for:
5* hashing
6* Galois-field[2] calculations of error-detecting and error-correcting codes
7* cryptography and ciphers
8* pseudo-random number generation
9* register-transfer-level modeling of digital logic designs
10* Fast-Fourier transforms
11* packing and unpacking numbers in persistant data structures
12* space-filling curves with applications to dimension reduction and sparse multi-dimensional database indexes; and
13* generating approximate seed values for root-finders and transcendental function algorithms.
14==== For more information see:
15[[https://srfi.schemers.org/srfi-60/|SRFI 60: Integers as Bits]]
16=== Rationale
17This proposal describes the [[http://swiss.csail.mit.edu/~jaffer/SLIB|SLIB]] module [[http://swiss.csail.mit.edu/~jaffer/slib_5.html#SEC88|logical]], which has been used for those purposes listed above.
18
19The discussions of the withdrawn [[https://srfi.schemers.org/srfi-33/|SRFI-33: "Integer Bitwise-operation Library"]] seemed to founder on consistency of procedure names and arity; and on perceived competition with the boolean arrays of SRFI-47.
20
21I have implemented both logical number operations and boolean arrays; and have not been conflicted as to their application. I used boolean arrays to construct very fast indexes for database tables having millions of records. To avoid running out of RAM, creation of megabit arrays should be explicit; so the boolean array procedures put their results into a passed array. In contrast, these procedures are purely functional.
22=== Bits and Complements
23A bit-index in these descriptions is nonnegative with the least significant bit at index 0. A positive integer has a finite number of "1" bits. A negative integer has a finite number of "0" bits.
24
25The reference implementation is written using only Scheme integer operations. Thus the only exposure of the underlying representation is the ranges of fixnums.
26
27The complement describes the representation of negative integers. With one's-complement fixnums, the range of integers is {{-(2^n)}} to {{2^n}}, and there are two possible representations of 0. With two's-complement fixnums, the range of integers is {{-(2^n+1)}} to {{2^n}}.
28
29Since we treat integers as having two's-complement negations, the two's-complement of an integer is simply its negation. The one's-complement of an integer is computed by {{lognot}}:
30
31<enscript highlight="scheme">
32(define (lognot n) (- -1 n))
33</enscript>
34=== Bitwise Operations and Integer Properties
35The {{logior}}, {{logxor}}, {{logand}}, {{lognot}}, {{logtest}}, {{logbit?}} {{(logbitp)}}, {{ash}}, {{logcount}}, and integer-length procedures are from Common-Lisp. {{Logior}}, {{logxor}}, and {{logand}} have been extended to accept any arity. Opportunities to use an n-ary version of {{logtest}} have not been frequent enough to justify its extension.
36
37In the ```Bitwise Operations```, rather than striving for orthogonal completeness, I have concentrated on a nearly minimal set of bitwise logical functions sufficient to support the uses listed above.
38
39Although any two of {{logior}}, {{logxor}}, and {{logand}} (in combination with {{lognot}}) are sufficient to generate all the two-input logic functions, having these three means that any nontrivial two-input logical function can be synthesized using just one of these two-input primaries with zero or one calls to {{lognot}}.
40
41{{bitwise-if}} is what SRFI-33 calls {{bitwise-merge}}.
42
43The SRFI-33 aliases: {{bitwise-ior}}, {{bitwise-xor}}, {{bitwise-and}}, {{bitwise-not}}, {{bitwise-merge}}, {{any-bits-set?}}, and {{bit-count}} are also provided.
44
45{{log2-binary-factors}} (alias {{first-set-bit}}) is a useful function which is simple but non-obvious:
46
47<enscript highlight="scheme">
48(define (log2-binary-factors n)
49  (+ -1 (integer-length (logand n (- n)))))
50</enscript>
51=== Bit Within Word and Field of Bits
52The ''Bit Within Word and Field of Bits'' procedures are used for modeling digital logic and accessing binary data structures in software.
53
54I have changed to copy-bit-field argument order to be consistent with the other Field of Bits procedures: the {{start}} and {{end}} index arguments are last. This makes them analogous to the argument order to substring and SRFI-47 arrays, which took their cue from substring.
55
56These {{start}} and {{end}} index arguments are not compatible with SRFI-33's size and position arguments (occurring first) in its bit-field procedures. Both define
57copy-bit-field; the arguments and purposes being incompatible.
58
59A procedure in {{slib/logical.scm}}, {{logical:rotate}}, rotated a given number of low-order bits by a given number of bits. This function was quite servicable, but I could not name it adequately. I have replaced it with rotate-bit-field with the addition of a {{start}} argument. This new function rotates a given field (from positions {{start}} to {{end}}) within an integer; leaving the rest unchanged.
60
61Another problematic name was {{logical:ones}}, which generated an integer with the least significant {{k}} bits set. Calls to bit-field could have replaced its uses . But the definition was so short that I just replaced its uses with:
62
63<enscript highlight="scheme">
64(lognot (ash -1 k))
65</enscript>
66
67The {{bit-reverse}} procedure was then the only one which took a width argument. So I replaced it with {{reverse-bit-field}}.
68
69The Lamination and Gray-code functions were moved to [[http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/slib/slib/phil-spc.scm?rev=HEAD&content-type=text/vnd.viewcvs-markup|slib/phil-spc.scm]]
70=== Bits as Booleans
71Bits as Booleans provides the procedures to convert between integers and lists of booleans. There is no comparable facility in SRFI-33.
72=== Specification
73==== Bitwise Operations
74
75<procedure>logand n1 ...</procedure>
76
77
78<procedure>bitwise-and n1 ...</procedure>
79
80Returns the integer which is the bit-wise ```AND``` of the integer arguments.
81====== Example:
82<enscript highlight="scheme">
83(number->string (logand #b1100 #b1010) 2)
84    => "1000"
85</enscript>
86
87<procedure>logior n1 ...</procedure>
88
89
90<procedure>bitwise-ior n1 ...</procedure>
91
92Returns the integer which is the bit-wise ```OR``` of the integer arguments.
93====== Example:
94<enscript highlight="scheme">
95(number->string (logior #b1100 #b1010) 2)
96    => "1110"
97</enscript>
98
99<procedure>logxor n1 ...</procedure>
100
101
102<procedure>bitwise-xor n1 ...</procedure>
103
104Returns the integer which is the bit-wise ```XOR``` of the integer arguments.
105====== Example:
106<enscript highlight="scheme">
107(number->string (logxor #b1100 #b1010) 2)
108    => "110"
109</enscript>
110
111<procedure>lognot n</procedure>
112
113
114<procedure>bitwise-not n</procedure>
115
116Returns the integer which is the ```one's-complement``` of the integer argument.
117====== Example:
118<enscript highlight="scheme">
119(number->string (lognot #b10000000) 2)
120    => "-10000001"
121(number->string (lognot #b0) 2)
122    => "-1"
123</enscript>
124
125<procedure>bitwise-if mask n0 n1</procedure>
126
127
128<procedure>bitwise-merge mask n0 n1</procedure>
129
130Returns 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.
131
132<procedure>logtest j k</procedure>
133
134
135<procedure>any-bits-set? j k</procedure>
136
137<enscript highlight="scheme">
138(logtest j k) == (not (zero? (logand j k)))
139
140(logtest #b0100 #b1011) => #f
141(logtest #b0100 #b0111) => #t
142</enscript>
143==== Integer Properties
144
145<procedure>logcount n</procedure>
146
147
148<procedure>bit-count n</procedure>
149
150Returns 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.
151====== Example:
152<enscript highlight="scheme">
153(logcount #b10101010)
154    => 4
155(logcount 0)
156    => 0
157(logcount -2)
158    => 1
159</enscript>
160
161<procedure>integer-length n</procedure>
162
163Returns the number of bits neccessary to represent {{n}}.
164====== Example:
165<enscript highlight="scheme">
166(integer-length #b10101010)
167    => 8
168(integer-length 0)
169    => 0
170(integer-length #b1111)
171    => 4
172</enscript>
173
174<procedure>log2-binary-factors n</procedure>
175
176
177<procedure>first-set-bit n</procedure>
178
179Returns the number of factors of two of integer {{n}}. This value is also the bit-index of the least-significant `1' bit in {{n}}.
180====== Example
181<enscript highlight="scheme">
182(require 'printf)
183(do ((idx 0 (+ 1 idx)))
184      ((> idx 16))
185    (printf "%s(%3d) ==> %-5d %s(%2d) ==> %-5d\n"
186            'log2-binary-factors
187            (- idx) (log2-binary-factors (- idx))
188            'log2-binary-factors
189            idx (log2-binary-factors idx)))
190-|
191log2-binary-factors(  0) ==> -1    log2-binary-factors( 0) ==> -1
192log2-binary-factors( -1) ==> 0     log2-binary-factors( 1) ==> 0
193log2-binary-factors( -2) ==> 1     log2-binary-factors( 2) ==> 1
194log2-binary-factors( -3) ==> 0     log2-binary-factors( 3) ==> 0
195log2-binary-factors( -4) ==> 2     log2-binary-factors( 4) ==> 2
196log2-binary-factors( -5) ==> 0     log2-binary-factors( 5) ==> 0
197log2-binary-factors( -6) ==> 1     log2-binary-factors( 6) ==> 1
198log2-binary-factors( -7) ==> 0     log2-binary-factors( 7) ==> 0
199log2-binary-factors( -8) ==> 3     log2-binary-factors( 8) ==> 3
200log2-binary-factors( -9) ==> 0     log2-binary-factors( 9) ==> 0
201log2-binary-factors(-10) ==> 1     log2-binary-factors(10) ==> 1
202log2-binary-factors(-11) ==> 0     log2-binary-factors(11) ==> 0
203log2-binary-factors(-12) ==> 2     log2-binary-factors(12) ==> 2
204log2-binary-factors(-13) ==> 0     log2-binary-factors(13) ==> 0
205log2-binary-factors(-14) ==> 1     log2-binary-factors(14) ==> 1
206log2-binary-factors(-15) ==> 0     log2-binary-factors(15) ==> 0
207log2-binary-factors(-16) ==> 4     log2-binary-factors(16) ==> 4
208</enscript>
209==== Bit Within Word
210
211<procedure>logbit? index n</procedure>
212
213
214<procedure>bit-set? index n</procedure>
215
216====== Example
217<enscript highlight="scheme">
218(logbit? index n) == (logtest (expt 2 index) n)
219
220(logbit? 0 #b1101) => #t
221(logbit? 1 #b1101) => #f
222(logbit? 2 #b1101) => #t
223(logbit? 3 #b1101) => #t
224(logbit? 4 #b1101) => #f
225</enscript>
226
227<procedure>copy-bit index from bit</procedure>
228
229Returns an integer the same as from except in the indexth bit, which is 1 if bit is {{#t}} and 0 if bit is {{#f}}.
230====== Example:
231<enscript highlight="scheme">
232(number->string (copy-bit 0 0 #t) 2)       => "1"
233(number->string (copy-bit 2 0 #t) 2)       => "100"
234(number->string (copy-bit 2 #b1111 #f) 2)  => "1011"
235</enscript>
236==== Field of Bits
237
238<procedure>bit-field n start end</procedure>
239
240Returns the integer composed of the {{start}} (inclusive) through {{end}} (exclusive) bits of {{n}}. The startth bit becomes the 0-th bit in the result.
241====== Example:
242<enscript highlight="scheme">
243(number->string (bit-field #b1101101010 0 4) 2)
244    => "1010"
245(number->string (bit-field #b1101101010 4 9) 2)
246    => "10110"
247</enscript>
248
249<procedure>copy-bit-field to from start end</procedure>
250
251Returns 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 startth bit of the result.
252====== Example:
253<enscript highlight="scheme">
254(number->string (copy-bit-field #b1101101010 0 0 4) 2)
255    => "1101100000"
256(number->string (copy-bit-field #b1101101010 -1 0 4) 2)
257    => "1101101111"
258(number->string (copy-bit-field #b110100100010000 -1 5 9) 2)
259    => "110100111110000"
260</enscript>
261
262<procedure>ash n count</procedure>
263
264
265<procedure>arithmetic-shift n count</procedure>
266
267Returns an integer equivalent to {{(inexact->exact (floor (* n (expt 2 count))))}}.
268====== Example:
269<enscript highlight="scheme">
270(number->string (ash #b1 3) 2)
271    => "1000"
272(number->string (ash #b1010 -1) 2)
273    => "101"
274</enscript>
275
276<procedure>rotate-bit-field n count start end</procedure>
277
278Returns {{n}} with the bit-field from {{start}} to {{end}} cyclically permuted by count bits towards high-order.
279====== Example:
280<enscript highlight="scheme">
281(number->string (rotate-bit-field #b0100 3 0 4) 2)
282    => "10"
283(number->string (rotate-bit-field #b0100 -1 0 4) 2)
284    => "10"
285(number->string (rotate-bit-field #b110100100010000 -1 5 9) 2)
286    => "110100010010000"
287(number->string (rotate-bit-field #b110100100010000 1 5 9) 2)
288    => "110100000110000"
289</enscript>
290
291<procedure>reverse-bit-field n start end</procedure>
292
293Returns {{n}} with the order of bits {{start}} to {{end}} reversed.
294====== Example
295<enscript highlight="scheme">
296(number->string (reverse-bit-field #xa7 0 8) 16)
297    => "e5"
298</enscript>
299==== Bits as Booleans
300
301<procedure>integer->list k len</procedure>
302
303
304<procedure>integer->list k</procedure>
305
306{{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}}).
307
308<procedure>list->integer list</procedure>
309
310{{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}}.
311
312{{integer->list}} and {{list->integer}} are inverses so far as equal? is concerned.
313
314<procedure>booleans->integer bool1 ...</procedure>
315
316Returns the integer coded by the {{bool1}} ... arguments.
317=== Implementation
318[[http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/slib/slib/logical.scm?rev=HEAD&content-type=text/vnd.viewcvs-markup|slib/logical.scm]] implements the integers-as-bits procedures for R4RS or R5RS compliant Scheme implementations.
319=== Author
320* Aubrey Jaffer
321* Ported to hygienic Chicken 3 with test suite by Peter Danenberg
322* Ported to Chicken 4 by Sergey Goldgaber
323=== Copyright
324Copyright (C) Aubrey Jaffer (2004, 2005). All Rights Reserved.
325
326Permission 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:
327
328The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
329
330THE 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.
331=== Version history
332*  [[https://github.com/diamond-lizard/srfi-60/releases/tag/0.7|0.7]] - Registered the srfi-60 feature, linked to source code
333*  [[https://github.com/diamond-lizard/srfi-60/releases/tag/0.6|0.6]] - Replaced srfi-60 implementation with that from bitwise-utils
334*  [[https://github.com/diamond-lizard/srfi-60/releases/tag/0.5|0.5]] - Using (chicken bitwise) procedures, where possible
335*  [[https://github.com/diamond-lizard/srfi-60/releases/tag/0.4|0.4]] - Ported to Chicken 5
336* 0.3 - release version 0.3
337* 0.2 - adopting trunk/tags directory layout.  Tagging version 0.2.
Note: See TracBrowser for help on using the repository browser.