This SRFI is currently in final status. Here is an explanation of each status that a SRFI can hold. To provide input on this SRFI, please send email to srfi151@nospamsrfi.schemers.org
. To subscribe to the list, follow these instructions. You can access previous messages via the mailing list archive.
bitfieldany?
and bitfieldevery?
. Removed obsolete test.)integer>list
, list>integer
, and booleans>integer
to reflect the changes made in SRFI 151 from SRFI 142.)This SRFI proposes a coherent and comprehensive set of procedures for performing bitwise logical operations on integers; it is accompanied by a reference implementation of the spec in terms of a set of seven core operators. The sample implementation is portable, as efficient as practical with pure Scheme arithmetic (it is much more efficient to replace the core operators with C or assembly language if possible), and open source.
The precise semantics of these operators is almost never an issue. A
consistent, portable set of names and parameter conventions, however, is.
Hence this SRFI, which is based mainly on SRFI 33, with some changes and additions from Olin's late revisions to SRFI 33 (which were never consummated).
SRFI 60
(based on SLIB) is smaller but has a few procedures of its own;
some of its procedures have both native (often Common Lisp) and SRFI 33 names.
They have been incorporated into this SRFI.
R6RS
is a subset of SRFI 60, except that all procedure names begin with a bitwise
prefix.
A few procedures have been added from
the general vector SRFI 133.
Among the applications of bitwise operations are: hashing, Galoisfield calculations of errordetecting and errorcorrecting codes, cryptography and ciphers, pseudorandom number generation, registertransferlevel modeling of digital logic designs, FastFourier transforms, packing and unpacking numbers in persistent data structures, spacefilling curves with applications to dimension reduction and sparse multidimensional database indexes, and generating approximate seed values for rootfinders and transcendental function algorithms.
This SRFI differs from SRFI 142 in only two ways:
The bitwiseif
function has the argument ordering of
SLIB, SRFI 60, and R6RS rather than the ordering of SRFI 33.
The order in which bits are processed by the procedures listed in the "Bits conversion" section has been clarified and some of the procedures' names have been changed. See "Bit processing order" for details.
bitwiseand
with 3 arguments, for example.
or
is never used by itself, only with modifiers: xor
, ior
, nor
,
orc1
, or orc2
. This is the same rule as Common Lisp.
bitwisecount
, bitwisenor
and the bitfield ops have been included. Settling on a standard
choice of names makes it easier to read
code that uses these sorts of operations. It also means computations
can be clearly expressed using the more powerful ops rather than
synthesized with a snarled mess of bitwiseand
s, bitwiseor
s, and bitwisenot
s.
What we gain is having an agreedupon set of names by which we can refer
to these functions. If you believe in "small is beautiful," then what is your motivation
for including anything beyond bitwisenand
?
The core of this design mirrors the structure of Common Lisp's pretty closely. Here are some differences:
ldb
and dpb
ops),
since they have nothing to do with the store.
boole
has been removed; it is not one with the Way of Scheme. Boolean functions
are directly encoded in Scheme as firstclass functions.
?
to mark a predicate, etc.). Common Lisp's name choices were more
historically motivated, for reasons of backward compatibility with
Maclisp and Zetalisp.
log
has been changed to bitwise
(e.g, lognot
to bitwisenot
),
as the prefix bitwise
more accurately reflects what they do.
bitwisenot
of the left or right arguments, do not appear in this SRFI.
This SRFI contains all the procedures of SRFI 33, and retains their original names with these exceptions:
bitwisemerge
is replaced by bitwiseif
, the name used in SRFI 60 and R6RS.
extractbitfield
(bitfieldextract
in Olin's revisions) is replaced by bitfield
, the name used in SRFI 60 and R6RS.
anybitsset?
and allbitsset?
are replaced by anybitset?
and everybitset?
, in accordance with Olin's revisions.
testbitfield?
has been renamed bitfieldany?
and supplemented with
bitfieldevery?
, in accordance with Olin's revisions.
copybitfield
means different things in SRFI 33 and SRFI 60,
SRFI 33's name copybitfield
(bitfieldcopy
in Olin's revisions)
has been changed to bitfieldreplacesame
.
SRFI 60 includes six procedures that do not have SRFI 33 equivalents. They are incorporated into this SRFI as follows:
rotatebitfield
and reversebitfield
are replaced by bitfieldrotate
and bitfieldreverse
, by analogy with Olin's revisions.
copybit
is incorporated into this SRFI with the same name.
integer>list
and list>integer
are incorporated into this SRFI with the slightly different names integer>bits
and bits>integer
because they are incompatible with SRFI 60.
booleans>integer
is a convenient way to specify a bitwise integer: it accepts an arbitrary number of boolean arguments and returns a nonnegative integer. So in this SRFI it has the short name bits
, roughly analogous to list
, string
, and vector
.
The following procedures are inspired by
SRFI 133:
bitswap
,
bitwisefold
, bitwiseforeach
, bitwiseunfold
.
The procedure bitfieldset
is the counterpart of bitfieldclear
.
The procedures bits>vector
and vector>bits
are inspired by their list counterparts.
The makebitwisegenerator
procedure is a generator constructor similar to those
provided by SRFI 127.
In general, these procedures place the bitstring arguments to be operated on first. Where the operation is not commutative, the "destination" argument that provides the background bits to be operated on is placed before the "source" argument that provides the bits to be transferred to it.
bitwisenand
and bitwisenor
accepted an arbitrary number of arguments
even though they are not commutative. Olin's late revisions made them dyadic, and so
does this SRFI.
bitwiseif
function was defined
with a different argument ordering from SRFI 33's bitwisemerge
, but was provided
under both names, using the SLIB ordering. SRFI 142 adopted the SRFI 33 ordering rather
than the SLIB and R6RS ordering. Since SLIB and R6RS have seen far more usage than
SRFI 33, this SRFI adopts the SRFI 60 ordering instead.
In SLIB and SRFI 60, the the order in which bits were processed by integer>list
and
list>integer
was not clearly specified.
When SRFI 142 was written,
the specification was clarified to process bits from least significant to most
significant, so that (integer>list 6) => (#f #t #t)
.
However, the SLIB and SRFI 60 implementation
processed them from the most significant bit to the leastsignificant bit,
so that (integer>list 6) => (#t #t #f)
.
This SRFI retains the littleendian order,
but renames the procedures to bits>list
and list>bits
to avoid a silent breaking change from SLIB and SRFI 60.
The same is true of the closely analogous integer>vector
, vector>integer
,
and bits
procedures.
bitwisenot bitwiseand bitwiseior bitwisexor bitwiseeqv bitwisenand bitwisenor bitwiseandc1 bitwiseandc2 bitwiseorc1 bitwiseorc2 arithmeticshift bitcount integerlength bitwiseif bitset? copybit bitswap anybitset? everybitset? firstsetbit bitfield bitfieldany? bitfieldevery? bitfieldclear bitfieldset bitfieldreplace bitfieldreplacesame bitfieldrotate bitfieldreverse bits>list list>bits bits>vector vector>bits bits bitwisefold bitwiseforeach bitwiseunfold makebitwisegenerator
In the following procedure specifications all parameters and return values
are exact integers unless otherwise indicated (except that procedures with
names ending in ?
are predicates, as usual). It is
an error to pass values of other types as arguments to these functions.
Bitstrings are represented by exact integers, using a two'scomplement encoding of the bitstring. Thus every integer represents a semiinfinite bitstring, having either a finite number of zeros (negative integers) or a finite number of ones (nonnegative integers). The bits of a bitstring are numbered from the rightmost/leastsignificant bit: bit #0 is the rightmost or 2^{0} bit, bit #1 is the next or 2^{1} bit, and so forth.
(bitwisenot
i)
Returns the bitwise complement of i; that is, all 1 bits are changed to 0 bits and all 0 bits to 1 bits.
(bitwisenot 10) => 11 (bitwisenot 37) => 36
The following ten procedures correspond to the useful set of nontrivial twoargument boolean functions. For each such function, the corresponding bitwise operator maps that function across a pair of bitstrings in a bitwise fashion. The core idea of this group of functions is this bitwise "lifting" of the set of dyadic boolean functions to bitstring parameters.
(bitwiseand
i ...)
(bitwiseior
i ...)
(bitwisexor
i ...)
(bitwiseeqv
i ...)
These operations are associative. When passed no arguments, the procedures return the identity values 1, 0, 0, and 1 respectively.
The bitwiseeqv
procedure produces the
complement of the bitwisexor
procedure. When applied to three
arguments, it does not produce a 1 bit
everywhere that a, b and c all agree. That is, it does not produce
(bitwiseior (bitwiseand a b c) (bitwiseand (bitwisenot a) (bitwisenot b) (bitwisenot c)))
Rather, it produces (bitwiseeqv a (bitwiseeqv b c))
or the equivalent
(bitwiseeqv (bitwiseeqv a b) c)
.
(bitwiseior 3 10) => 11 (bitwiseand 11 26) => 10 (bitwisexor 3 10) => 9 (bitwiseeqv 37 12) => 42 (bitwiseand 37 12) => 4
(bitwisenand
i j)
(bitwisenor
i j)
(bitwiseandc1
i j)
(bitwiseandc2
i j)
(bitwiseorc1
i j)
(bitwiseorc2
i j)
These operations are not associative.
(bitwisenand 11 26) => 11 (bitwisenor 11 26) => 28 (bitwiseandc1 11 26) => 16 (bitwiseandc2 11 26) => 1 (bitwiseorc1 11 26) => 2 (bitwiseorc2 11 26) => 17
(arithmeticshift
i count)
Returns the arithmetic left shift when count>0; right shift when count<0.
(arithmeticshift 8 2) => 32 (arithmeticshift 4 0) => 4 (arithmeticshift 8 1) => 4 (arithmeticshift 100000000000000000000000000000000 100) => 79
(bitcount
i)
Returns the population count of 1's (i >= 0) or 0's (i < 0). The result is always nonnegative.
Compatibility note: The R6RS analogue bitwisebitcount
applies bitwisenot
to the population count before returning it
if i is negative.
(bitcount 0) => 0 (bitcount 1) => 0 (bitcount 7) => 3 (bitcount 13) => 3 ;Two'scomplement binary: ...0001101 (bitcount 13) => 2 ;Two'scomplement binary: ...1110011 (bitcount 30) => 4 ;Two'scomplement binary: ...0011110 (bitcount 30) => 4 ;Two'scomplement binary: ...1100010 (bitcount (expt 2 100)) => 1 (bitcount ( (expt 2 100))) => 100 (bitcount ( (1+ (expt 2 100)))) => 1
(integerlength
i)
The number of bits needed to represent i, i.e.
(ceiling (/ (log (if (negative? integer) ( integer) (+ 1 integer))) (log 2)))
The result is always nonnegative.
For nonnegative i, this is the number of bits needed to
represent i in an unsigned binary representation. For all i,
(+ 1 (integerlength
i))
is the number of bits needed
to represent i in a signed twoscomplement
representation.
(integerlength 0) => 0 (integerlength 1) => 1 (integerlength 1) => 0 (integerlength 7) => 3 (integerlength 7) => 3 (integerlength 8) => 4 (integerlength 8) => 3
(bitwiseif
mask i j)
Merge the bitstrings i and j, with bitstring mask determining from which string to take each bit. That is, if the kth bit of mask is 1, then the kth bit of the result is the kth bit of i, otherwise the kth bit of j.
(bitwiseif 3 1 8) => 9 (bitwiseif 3 8 1) => 0 (bitwiseif 1 1 2) => 3 (bitwiseif #b00111100 #b11110000 #b00001111) => #b00110011
As always, the rightmost/leastsignificant bit in i is bit 0.
(bitset?
index i)
Is bit index set in bitstring i (where index is a nonnegative exact integer)?
Compatibility note: The R6RS analogue bitwisebitset?
accepts its arguments in the opposite order.
(bitset? 1 1) => false (bitset? 0 1) => true (bitset? 3 10) => true (bitset? 1000000 1) => true (bitset? 2 6) => true (bitset? 0 6) => false
(copybit
index i boolean)
Returns an integer the same as i except in the indexth bit,
which is 1 if boolean is #t
and 0 if boolean is #f
.
Compatibility note: The R6RS analogue bitwisecopybit
as originally documented
has a completely different interface.
(bitwisecopybit
dest index source)
replaces the index'th bit of dest with the
index'th bit of source.
It is equivalent to
(bitfieldreplacesame dest source index (+ index 1))
.
However, an erratum made a silent breaking change to interpret the
third argument as 0 for a false bit and 1 for a true bit. Some
R6RS implementations applied this erratum but others did not.
(copybit 0 0 #t) => #b1 (copybit 2 0 #t) => #b100 (copybit 2 #b1111 #f) => #b1011
(bitswap
index_{1} index_{2} i)
Returns an integer the same as i except that the index_{1}th bit and the index_{2}th bit have been exchanged.
(bitswap 0 2 4) => #b1
(anybitset?
testbits i)
(everybitset?
testbits i)
Determines if any/all of the bits set in bitstring testbits are set
in bitstring i. I.e., returns (not (zero? (bitwiseand
testbits i)))
and (=
testbits (bitwiseand
testbits i))) respectively.
(anybitset? 3 6) => #t (anybitset? 3 12) => #f (everybitset? 4 6) => #t (everybitset? 7 6) => #f
(firstsetbit
i)
Return the index of the first (smallest index) 1 bit in bitstring i. Return 1 if i contains no 1 bits (i.e., if i is zero).
(firstsetbit 1) => 0 (firstsetbit 2) => 1 (firstsetbit 0) => 1 (firstsetbit 40) => 3 (firstsetbit 28) => 2 (firstsetbit (expt 2 99)) => 99 (firstsetbit (expt 2 99)) => 99
These functions operate on a contiguous field of bits (a "byte," in Common Lisp parlance) in a given bitstring. The start and end arguments, which are not optional, are nonnegative exact integers specifying the field: it is the endstart bits running from bit start to bit end1.
(bitfield
i start end)
Returns the field from i, shifted down to the leastsignificant position in the result.
(bitfield #b1101101010 0 4) => #b1010 (bitfield #b1101101010 3 9) => #b101101 (bitfield #b1101101010 4 9) => #b10110 (bitfield #b1101101010 4 10) => #b110110 (bitfield 6 0 1) => 0 (bitfield 6 1 3) => 3 (bitfield 6 2 999) => 1 (bitfield #x100000000000000000000000000000000 128 129) => 1
(bitfieldany?
i start end)
Returns true if any of the field's bits are set in bitstring i, and false otherwise.
(bitfieldany? #b1001001 1 6) => #t (bitfieldany? #b1000001 1 6) => #f
(bitfieldevery?
i start end)
Returns false if any of the field's bits are not set in bitstring i, and true otherwise.
(bitfieldevery? #b1011110 1 5) => #t (bitfieldevery? #b1011010 1 5) => #f
(bitfieldclear
i start end)
(bitfieldset
i start end)
Returns i with the field's bits set to all 0s/1s.
(bitfieldclear #b101010 1 4) => #b100000 (bitfieldset #b101010 1 4) => #b101110
(bitfieldreplace
dest source start end)
Returns dest with the field replaced by the leastsignificant endstart bits in source.
(bitfieldreplace #b101010 #b010 1 4) => #b100100 (bitfieldreplace #b110 1 0 1) => #b111 (bitfieldreplace #b110 1 1 2) => #b110
(bitfieldreplacesame
dest source start end)
Returns dest with its field replaced by the corresponding field in source.
(bitfieldreplacesame #b1111 #b0000 1 3) => #b1001
(bitfieldrotate
i count start end)
Returns i with the field cyclically permuted by count bits towards highorder.
Compatibility note: The R6RS analogue bitwiserotatebitfield
uses the argument ordering i start end count.
(bitfieldrotate #b110 0 0 10) => #b110 (bitfieldrotate #b110 0 0 256) => #b110 (bitfieldrotate #x100000000000000000000000000000000 1 0 129) => 1 (bitfieldrotate #b110 1 1 2) => #b110 (bitfieldrotate #b110 1 2 4) => #b1010 (bitfieldrotate #b0111 1 1 4) => #b1011
(bitfieldreverse
i start end)
Returns i with the order of the bits in the field reversed.
(bitfieldreverse 6 1 3) => 6 (bitfieldreverse 6 1 4) => 12 (bitfieldreverse 1 0 32) => #x80000000 (bitfieldreverse 1 0 31) => #x40000000 (bitfieldreverse 1 0 30) => #x20000000 (bitfieldreverse #x140000000000000000000000000000000 0 129) => 5
(bits>list
i [ len ])
(bits>vector
i [ len ])
Returns a list/vector of len booleans corresponding to each bit of the nonnegative integer i,
returning bit #0 as the first element, bit #1 as the second, and so on.
#t
is returned for each 1; #f
for 0.
(bits>list #b1110101) => (#t #f #t #f #t #t #t) (bits>list 3 5) => (#t #t #f #f #f) (bits>list 6 4) => (#f #t #t #f) (bits>vector #b1110101) => #(#t #f #t #f #t #t #t)
(list>bits
list)
(vector>bits
vector)
Returns an integer formed from the booleans in list/vector,
using the first element as bit #0, the second element as bit #1, and so on.
It is an error if list/vector contains nonbooleans.
A 1 bit is coded for each #t
; a 0 bit for #f
.
Note that the result is never a negative integer.
(list>bits '(#t #f #t #f #t #t #t)) => #b1110101 (list>bits '(#f #f #t #f #t #f #t #t #t)) => #b111010100 (list>bits '(#f #t #t)) => 6 (list>bits '(#f #t #t #f)) => 6 (list>bits '(#f #f #t #t)) => 12 (vector>bits '#(#t #f #t #f #t #t #t)) => #b1110101 (vector>bits '#(#f #f #t #f #t #f #t #t #t)) => #b111010100 (vector>bits '#(#f #t #t)) => 6 (vector>bits '#(#f #t #t #f)) => 6 (vector>bits '#(#f #f #t #t)) => 12
For positive integers,
bits>list
and list>bits
are inverses in the sense of equal?
,
and so are bits>vector
and vector>bits
.
(bits
bool ...)
Returns the integer coded by the bool
arguments.
The first argument is bit #0, the second argument is bit #1, and so on.
Note that the result is never a negative integer.
(bits #t #f #t #f #t #t #t) => #b1110101 (bits #f #f #t #f #t #f #t #t #t) => #b111010100
It is an error if the arguments named proc, stop?, mapper, successor are not procedures. The arguments named seed may be any Scheme object.
(bitwisefold
proc seed i)
For each bit b of i from bit #0 (inclusive) to bit (integerlength
i)
(exclusive), proc is called as
(
proc b r)
, where r is the current accumulated result. The initial value of r
is seed, and the value returned by proc becomes the next accumulated result. When
the last bit has been processed, the final accumulated result becomes the result of bitwisefold
.
(bitwisefold cons '() #b1010111) => (#t #f #t #f #t #t #t)
(bitwiseforeach
proc i)
Repeatedly applies proc to the bits of i starting with
bit #0 (inclusive) and ending with bit (integerlength
i)
(exclusive).
The values returned by proc are discarded. Returns
an unspecified value.
(let ((count 0)) (bitwiseforeach (lambda (b) (if b (set! count (+ count 1)))) #b1010111) count)
(bitwiseunfold
stop? mapper successor seed)
Generates a nonnegative integer bit by bit, starting with bit 0. If the result of applying stop? to the current state (whose initial value is seed) is true, return the currently accumulated bits as an integer. Otherwise, apply mapper to the current state to obtain the next bit of the result by interpreting a true value as a 1 bit and a false value as a 0 bit. Then get a new state by applying successor to the current state, and repeat this algorithm.
(bitwiseunfold (lambda (i) (= i 10)) even? (lambda (i) (+ i 1)) 0) => #b101010101
(makebitwisegenerator
i)
Returns a SRFI 121 generator that generates all the bits of i starting with bit #0. Note that the generator is infinite.
(let ((g (makebitwisegenerator #b110))) (test #f (g)) (test #t (g)) (test #t (g)) (test #f (g)))
The implementation is in the repository of this SRFI, and includes the following files:
bitwisecore.scm
 the SRFI 60 sample implementation
of the seven core operators, without dependencies
bitwise33.scm
 SRFI 33 sample implementation, some procedures renamed
bitwise60.scm
 part of SRFI 60 sample implementation, some procedures renamed
bitwiseother.scm
 implementation of other procedures
srfi151.scm
 Chicken module
srfi151.sld
 R7RS library
chibitest.scm
 Chibi tests
chickentest.scm
 Chicken tests
It is very important for performance to provide a C or assembly implementation of the core operators.
There is a condexpand
in srfi151.sld
that can be extended to take
advantage of this.
Currently it contains options for Chibi and Gauche.
In addition, if the R6RS library (rnrs arithmetic bitwise)
is available,
it will be used in place of bitwisecore.scm
.
Temporary note: Chibi assumes a C library named bit
.
The bit.{so,dll}
file can be found in $PREFIX/lib/chibi/srfi/{33,142}
.
Even more temporary note: this is buggy, so the Chibi arm of the conditional is currently commented out.
The following table compares the names of the bitwise (aka logical) functions of Common Lisp, SRFI 33, Olin's revisions, SRFI 60, R6RS, and this SRFI.
Italic procedure names
indicate that the
equivalence is only rough: argument orderings or precise semantics are not
the same as in this SRFI.
Function  CL  SRFI 33  SRFI 33 late revs  SRFI 60  R6RS  This SRFI 

Bitwise NOT  lognot  bitwisenot  bitwisenot  lognot , bitwisenot  bitwisenot  bitwisenot

Bitwise AND  logand  bitwiseand  bitwiseand  logand , bitwiseand  bitwiseand  bitwiseand

Bitwise IOR  logior  bitwiseior  bitwiseior  logior , bitwiseior  bitwiseior  bitwiseior

Bitwise XOR  logxor  bitwisexor  bitwisexor  logxor , bitwisexor  bitwisexor  bitwisexor

Bitwise EQV  logeqv  bitwiseeqv  bitwiseeqv      bitwiseeqv

Bitwise NAND  lognand  bitwisenand  bitwisenand      bitwisenand

Bitwise NOR  lognor  bitwisenor  bitwisenor      bitwisenor

Bitwise AND with NOT of first arg  logandc1  bitwiseandc1  bitwiseandc1      bitwiseandc1

Bitwise AND with NOT of second arg  logandc2  bitwiseandc2  bitwiseandc2      bitwiseandc2

Bitwise OR with NOT of first arg  logorc1  bitwiseorc1  bitwiseorc1      bitwiseorc1

Bitwise OR with NOT of second arg  logorc2  bitwiseorc2  bitwiseorc2      bitwiseorc2

Arithmetic shift  ash  arithmeticshift  arithmeticshift  ash , arithmeticshift  bitwisearithmeticshift  arithmeticshift

Population count  logcount  bitcount  bitcount  logcount , bitcount  bitwisebitcount  bitcount

Integer length  integerlength  integerlength  integerlength  integerlength  bitwiselength  integerlength

Mask selects source of bits    bitwisemerge  bitwisemerge  bitwiseif , bitwisemerge  bitwiseif  bitwiseif

Test single bit  logbitp  bitset?  bitset?  logbit? , bitset?  bitwisebitset?  bitset?

See if any mask bits set  logtest  anybitsset?  anybitset?  logtest , anybitsset?    anybitset?

See if all mask bits set    allbitsset?  everybitset?      everybitset?

Replace single bit      copybit  copybit  bitwisecopybit  copybit

Swap bits            bitswap

Find first bit set    firstsetbit  firstsetbit  log2binaryfactors , firstsetbit  bitwisefirstbitset  firstsetbit

Extract bit field  ldb  extractbitfield  extractbitfield  bitfield  bitwisebitfield  bitfield

Test bit field (any)  ldbtest  testbitfield?  bitfieldany?      bitfieldany?

Test bit field (every)      bitfieldevery?      bitfieldevery?

Clear bit field  maskfield  clearbitfield  bitfieldclear      bitfieldclear

Set bit field            bitfieldset

Replace bit field  dpb  replacebitfield  bitfieldreplace  copybitfield  bitwisecopybitfield  bitfieldreplace

Replace corresponding bit field  depositfield  copybitfield  bitfieldcopy      bitfieldreplacesame

Rotate bit field        rotatebitfield  bitwiserotatebitfield  bitfieldrotate

Reverse bit field        reversebitfield  bitwisereversebitfield  bitfieldreverse

Bits to boolean list        integer>list    bits>list

Bits to boolean vector            bits>vector

Boolean list to bits        list>integer    list>bits

Boolean vector to bits            vector>bits

Booleans to integer        booleans>integer    bits

Bitwise fold            bitwisefold

Bitwise foreach            bitwiseforeach

Bitwise unfold            bitwiseunfold

Bit generator            makebitwisegenerator

This SRFI would not exist without the efforts of Olin Shivers, Aubrey Jaffer, and Taylor Campbell.
Copyright (C) John Cowan (2016). 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.