Adding documentation for SRFI 60

docs/API.md

@@ -37,6 +37,7 @@ Cyclone supports the following [Scheme Requests for Implementation (SRFI)](http:
 - [`srfi 8`](api/srfi/8.md) - [`receive`: Binding to multiple values](http://srfi.schemers.org/srfi-8/srfi-8.html) - Included as part of `scheme base`.
 - [`srfi 18`](api/srfi/18.md) - [Multithreading support](http://srfi.schemers.org/srfi-18/srfi-18.html)
 - [`srfi 27`](api/srfi/27.md) - [Sources of random bits](http://srfi.schemers.org/srfi-27/srfi-27.html)
+- [`srfi 60`](api/srfi/60.md) - [Integers as bits](http://srfi.schemers.org/srfi-60/srfi-60.html)
 - [`srfi 69`](api/srfi/69.md) - [Basic hash tables](http://srfi.schemers.org/srfi-69/srfi-69.html)
 - [`srfi 106`](api/srfi/106.md) - [Basic socket interface](http://srfi.schemers.org/srfi-106/srfi-106.html)
 - [`srfi 111`](api/srfi/111.md) - [Boxes](http://srfi.schemers.org/srfi-111/srfi-111.html)

docs/api/srfi/60.md

@@ -0,0 +1,247 @@
+# SRFI 60 - Integers as bits
+
+Various operations designed to work on integers as strings of bits efficiently.
+
+See the [SRFI document][1] for more information.
+
+## Bitwise operations
+[`logand`](#logand)
+[`logior`](#logior)
+[`logxor`](#logxor)
+[`lognot`](#lognot)
+[`logtest`](#logtest)
+[`bitwise-and`](#bitwise-and)
+[`bitwise-ior`](#bitwise-ior)
+[`bitwise-xor`](#bitwise-xor)
+[`bitwise-not`](#bitwise-not)
+[`bitwise-if`](#bitwise-if)
+[`bitwise-merge`](#bitwise-merge)
+[`any-bits-set?`](#any-bits-set)
+
+## Integer properties
+[`logcount`](#logcount)
+[`log2-binary-factors`](#log2-binary-factors)
+[`bit-count`](#bit-count)
+[`integer-length`](#integer-length)
+[`first-set-bit`](#first-set-bit)
+
+## Bit within word
+[`logbit?`](#logbit)
+[`bit-set?`](#bit-set)
+[`copy-bit`](#copy-bit)
+
+## Field of bits
+[`bit-field`](#bit-field)
+[`copy-bit-field`](#copy-bit-field)
+[`ash`](#ash)
+[`arithmetic-shift`](#ash)
+[`rotate-bit-field`](#rotate-bit-field)
+
+## Bits as booleans
+[`integer->list`](#integer-list)
+[`list->integer`](#list-integer)
+[`booleans->integer`](#booleans-integer)
+
+# logand
+
+    (logand n1 ...)
+
+Returns the integer which is the bitwise-AND of the arguments.
+
+Example: ``(number->string (logand #b1100 #b1010) 2) => "1000"``
+
+# bitwise-and
+
+Synonym for ``logand``.
+
+# logior
+
+    (logior n1 ...)
+
+Returns the integer which is the bitwise-OR of the arguments.
+
+Example: ``(number->string (logior #b1100 #b1010) 2) => "1110"``
+
+# bitwise-ior
+
+Synonym for ``logior``.
+
+# logxor
+
+    (logxor n1 ...)
+
+Returns the integer which is the bitwise-XOR of the arguments.
+
+Example: ``(number->string (logxor #b1100 #b1010) 2) => "110"``
+
+# bitwise-xor
+
+Synonym for ``logxor``.
+
+# lognot
+
+    (lognot n)
+
+Returns the integer which is the one's-complement of the argument.
+
+# bitwise-not
+
+Synonym for ``lognot``.
+
+# bitwise-if
+
+    (bitwise-if mask n0 n1)
+
+Returns an integer composed of some bits from ``n0`` and some bits from ``n1``.
+A bit of the result is taken from ``n0`` if the corresponding bit of ``mask`` is
+1, and from ``n1`` otherwise.
+
+# bitwise-merge
+
+Synonym for ``bitwise-if``.
+
+# logtest
+
+    (logtest j k)
+
+Equivalent to ``(not (zero? (logand j k)))``.
+
+Example: ``(logtest #b0100 #b1011) => #f``
+
+# any-bits-set?
+
+Synonym for ``logtest``.
+
+# logcount
+
+    (logcount n)
+
+Returns the number of bits in ``n``. If ``n`` 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, then 0 is returned.
+
+Example: ``(logcount #b10101010) => 4``
+
+# bit-count
+
+Synonym for ``logcount``.
+
+# integer-length
+
+    (integer-length n)
+
+Returns the number of bits necessary to represent ``n``.
+
+Example: ``(integer-length #b1011) => 4``
+
+# log2-binary-factors
+
+    (log2-binary-factors n)
+
+Returns the bit-index of the least-significant 1-bit in ``n``. If ``n`` contains
+no 1-bits, -1 is returned.
+
+Example: ``(log2-binary-factors 4) => 2``
+
+# first-set-bit
+
+Synonym for ``log2-binary-factors``
+
+# logbit?
+
+    (logbit? index n)
+
+Equivalent to ``(logtest (exact (expt 2 index)) n)``.
+
+Example: ``(logbit? 1 #b1101) => #f``
+
+# bit-set?
+
+Synonym for ``logbit?``.
+
+# copy-bit
+
+    (copy-bit index from bit)
+
+Returns ``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 2 #b1111 #f) 2) => "1011"``
+
+# bit-field
+
+    (bit-field n start end)
+
+Returns the integer composed of the ``start`` (inclusive) through ``end``
+(exclusive) bits of ``n``. The ``start``th bit becomes the 0th bit in the
+result.
+
+Example: ``(number->string (bit-field #b1101101010 0 4) 2) => "1010"``
+
+# copy-bit-field
+
+    (copy-bit-field to from start end)
+
+Returns ``to``, except possibly in the ``start`` (inclusive) through ``end``
+(exclusive) bits, which are the same as those of ``from``. The 0th bit of
+``from`` becomes the ``start``th bit of the result.
+
+Example: ``(number->string (copy-bit-field #b1101101010 0 0 4) 2) =>
+"1101100000"``
+
+# ash
+
+    (ash n count)
+
+Equivalent to ``(exact (floor (* n (expt 2 count))))``.
+
+Example: ``(number->string (ash #b1010 -1) 2) => "101"``
+
+# arithmetic-shift
+
+Synonym for ``ash``.
+
+# rotate-bit-field
+
+    (rotate-bit-field n count start end)
+
+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"``
+
+# reverse-bit-field
+
+    (reverse-bit-field n start end)
+
+Returns ``n`` with the order of bits ``start`` to ``end`` reversed.
+
+Example: ``(number->string (reverse-bit-field #b10100111 0 8) 2) =>
+"11100101")``
+
+# integer->list
+
+    (integer->list k)
+    
+    (integer->list k len)
+
+Returns a list of ``len`` booleans corresponding to each bit of the non-negative
+integer ``k``. ``#t`` is coded for each 1; ``#f`` for each 0. ``len`` defaults
+to ``(integer-length k)``.
+
+# list->integer
+
+    (list->integer list)
+
+Returns an integer formed from the booleans in ``list``, which must consist only
+of booleans. A 1 bit is coded for each ``#t``; a 0 bit for each ``#f``.
+``integer->list`` and ``list->integer`` are inverses up to ``equal?``: thus, for
+any ``x``, ``x == (integer->list (list->integer x))``.
+
+# booleans->integer
+
+    (booleans->integer b1 ...)
+
+Equivalent to ``(list->integer (list b1 ...))``.
+
+[1]: http://srfi.schemers.org/srfi-60/srfi-60.html