You can edit this page using wiki syntax for markup.

Article contents:== Outdated egg! This is an egg for CHICKEN 3, the unsupported old release. You're almost certainly looking for [[/eggref/4/srfi-60|the CHICKEN 4 version of this egg]], if it exists. If it does not exist, there may be equivalent functionality provided by another egg; have a look at the [[https://wiki.call-cc.org/chicken-projects/egg-index-4.html|egg index]]. Otherwise, please consider porting this egg to the current version of CHICKEN. [[tags: egg]] == srfi-60 [[toc:]] === Description [[http://srfi.schemers.org/srfi-60/srfi-60.html|SRFI-60]]: Integers as bits === Author Aubrey Jaffer === Requirements None === Download [[http://code.call-cc.org/legacy-eggs/3/srfi-60.egg|srfi-60.egg]] === Documentation Treating integers as two's-complement strings of bits is an arcane but important domain of computer science. It is used for: * hashing; * Galois-field[2] calculations of error-detecting and error-correcting codes; * cryptography and ciphers; * pseudo-random number generation; * register-transfer-level modeling of digital logic designs; * Fast-Fourier transforms; * packing and unpacking numbers in persistant data structures; * space-filling curves with applications to dimension reduction and sparse multi-dimensional database indexes; and * generating approximate seed values for root-finders and transcendental function algorithms. ==== Bits and Complements A 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. The reference implementation is written using only Scheme integer operations. Thus the only exposure of the underlying representation is the ranges of fixnums. The ''complement'' describes the representation of negative integers. With one's-complement fixnums, the range of integers is <nowiki>-(2^<i>n</i>) to 2^<i>n</i></nowiki>, and there are two possible representations of 0. With two's-complement fixnums, the range of integers is <nowiki>-(2^<i>n</i>+1) to 2^<i>n</i></nowiki>. Since 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: (define (lognot n) (- -1 n)) ==== Bitwise Operations and Integer Properties The {{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. In 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. Although 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}}. {{bitwise-if}} is what SRFI-33 calls {{bitwise-merge}}. The SRFI-33 aliases: {{bitwise-ior}}, {{bitwise-xor}}, {{bitwise-and}}, {{bitwise-not}}, {{bitwise-merge}}, {{any-bits-set?}}, and {{bit-count}} are also provided. {{log2-binary-factors}} (alias {{first-set-bit}}) is a useful function which is simple but non-obvious: (define (log2-binary-factors n) (+ -1 (integer-length (logand n (- n))))) ==== Bit Within Word and Field of Bits The ''Bit Within Word'' and ''Field of Bits'' procedures are used for modeling digital logic and accessing binary data structures in software. I 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}}. These {{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 {{copy-bit-field}}; the arguments and purposes being incompatible. A 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. Another 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: (lognot (ash -1 {{k}})) The {{bit-reverse}} procedure was then the only one which took a {{width}} argument. So I replaced it with {{reverse-bit-field}}. The ''Lamination'' and ''Gray-code'' functions were moved to [[http://savannah.gnu.org/cgi-bin/viewcvs/*checkout*/slib/slib/phil-spc.scm?rev=HEAD&amp;content-type=text/vnd.viewcvs-markup|slib/phil-spc.scm]] ==== Bits as Booleans ''Bits as Booleans'' provides the procedures to convert between integers and lists of booleans. There is no comparable facility in SRFI-33. ==== Specification To access the following bindings use the extensions "srfi-60-aliases": * arithmetic-shift * bitwise-ior * bitwise-xor * bitwise-and * bitwise-not * bit-count * bit-set? * any-bits-set? * first-set-bit * bitwise-merge Further, the following are aliases for builtin Chicken procedures: ; *arithmetic-shift : arithmetic-shift ; *bitwise-ior : bitwise-ior ; *bitwise-xor : bitwise-xor ; *bitwise-and : bitwise-and ; *bitwise-not : bitwise-not ; *bit-set? : bit-set? ===== 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: (number->string (logand #b1100 #b1010) 2) => "1000" <procedure>(logior n1 ...)</procedure> <procedure>(bitwise-ior n1 ...)</procedure> Returns the integer which is the bit-wise OR of the integer arguments. Example: (number->string (logior #b1100 #b1010) 2) => "1110" <procedure>(logxor n1 ...)</procedure> <procedure>(bitwise-xor n1 ...)</procedure> Returns the integer which is the bit-wise XOR of the integer arguments. Example: (number->string (logxor #b1100 #b1010) 2) => "110" <procedure>(lognot n)</procedure> <procedure>(bitwise-not n)</procedure> Returns the integer which is the one's-complement of the integer argument. Example: (number->string (lognot #b10000000) 2) => "-10000001" (number->string (lognot #b0) 2) => "-1" <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> (logtest j k) == (not (zero? (logand j k))) (logtest #b0100 #b1011) => #f (logtest #b0100 #b0111) => #t ===== 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: (logcount #b10101010) => 4 (logcount 0) => 0 (logcount -2) => 1 <procedure>(integer-length n)</procedure> Returns the number of bits neccessary to represent {{n}}. Example: (integer-length #b10101010) => 8 (integer-length 0) => 0 (integer-length #b1111) => 4 <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}}. (require 'printf) (do ((idx 0 (+ 1 idx))) ((> idx 16)) (printf "%s(%3d) ==> %-5d %s(%2d) ==> %-5d\n" 'log2-binary-factors (- idx) (log2-binary-factors (- idx)) 'log2-binary-factors idx (log2-binary-factors idx))) -| log2-binary-factors( 0) ==> -1 log2-binary-factors( 0) ==> -1 log2-binary-factors( -1) ==> 0 log2-binary-factors( 1) ==> 0 log2-binary-factors( -2) ==> 1 log2-binary-factors( 2) ==> 1 log2-binary-factors( -3) ==> 0 log2-binary-factors( 3) ==> 0 log2-binary-factors( -4) ==> 2 log2-binary-factors( 4) ==> 2 log2-binary-factors( -5) ==> 0 log2-binary-factors( 5) ==> 0 log2-binary-factors( -6) ==> 1 log2-binary-factors( 6) ==> 1 log2-binary-factors( -7) ==> 0 log2-binary-factors( 7) ==> 0 log2-binary-factors( -8) ==> 3 log2-binary-factors( 8) ==> 3 log2-binary-factors( -9) ==> 0 log2-binary-factors( 9) ==> 0 log2-binary-factors(-10) ==> 1 log2-binary-factors(10) ==> 1 log2-binary-factors(-11) ==> 0 log2-binary-factors(11) ==> 0 log2-binary-factors(-12) ==> 2 log2-binary-factors(12) ==> 2 log2-binary-factors(-13) ==> 0 log2-binary-factors(13) ==> 0 log2-binary-factors(-14) ==> 1 log2-binary-factors(14) ==> 1 log2-binary-factors(-15) ==> 0 log2-binary-factors(15) ==> 0 log2-binary-factors(-16) ==> 4 log2-binary-factors(16) ==> 4 ===== Bit Within Word <procedure>(logbit? index n)</procedure> <procedure>(bit-set? index n)</procedure> (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 <procedure>(copy-bit index from bit)</procedure> Returns an integer the same as {{from}} except in the {{index}}th bit, which is 1 if {{bit}} is {{#t}} and 0 if {{bit}} is {{#f}}. Example: (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" ===== 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: (number->string (bit-field #b1101101010 0 4) 2) => "1010" (number->string (bit-field #b1101101010 4 9) 2) => "10110" <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: (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" <procedure>(ash n count)</procedure> <procedure>(arithmetic-shift n count)</procedure> Returns an integer equivalent to {{(inexact>exact (floor (* n (expt 2 count))))}} Example: (number->string (ash #b1 3) 2) => "1000" (number->string (ash #b1010 -1) 2) => "101" <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: (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" <procedure>(reverse-bit-field n start end)</procedure> Returns {{n}} with the order of bits {{start}} to {{end}} reversed. (number->string (reverse-bit-field #xa7 0 8) 16) => "e5" ===== 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 given integer. {{#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. === License Copyright (C) Aubrey Jaffer Permission to copy this software, to modify it, to redistribute it, to distribute modified versions, and to use it for any purpose is granted, subject to the following restrictions and understandings. 1. Any copy made of this software must include this copyright notice in full. 2. I have made no warranty or representation that the operation of this software will be error-free, and I am under no obligation to provide any services, by way of maintenance, update, or otherwise. 3. In conjunction with products arising from the use of this material, there shall be no use of my name in any advertising, promotional, or sales literature without prior written consent in each case. Description of your changes:

I would like to authenticate

Spam control

What do you get when you subtract 23 from 10?