I have gone over all unresolved issues from the old discussions.
Below, the resolutions. I will send the current draft in a following
message; Francisco can install it in the right place at his convenience.
-Olin
-------------------------------------------------------------------------------
Summary:
- NAND & NOR are no longer n-ary. Only associative ops are.
- Sticking with SIZE/POSITION field specs over FROM/TO.
- Staying with "op-curry" convention for param order.
- ANY/ALL lexemes switched to more standard/more-parallel ANY/EVERY for
ANY-BIT-SET?
EVERY-BIT-SET?
- New pair of complementary functions
BIT-FIELD-ANY? BIT-FIELD-EVERY?
replaces unbalanced TEST-BIT-FIELD?.
- "BIT-FIELD" lexeme consistently moved to front of name for
BIT-FIELD-ANY? BIT-FIELD-EVERY?
BIT-FIELD-EXTRACT BIT-FIELD-CLEAR
BIT-FIELD-REPLACE BIT-FIELD-COPY
(Is everyone agreeable to this?)
-------------------------------------------------------------------------------
From: Bengt Kleberg <xxxxxx@cbe.ericsson.se>
i have no objection to the functionality/set of operations offered by
the "Integer Bitwise-operation Library" by Olin Shivers. instead i
would like to change function names and argument order to make them
slightly more reminiscent of the string and vector operations.
1 would it be possible to change
arithmetic-shift i count -> exact-integer
to
bit-shift-left i count -> exact-integer
bit-shift-right i count -> exact-integer
This doesn't seem sufficiently compelling to warrant further stewing around.
I'm going to leave things with the traditional "arithmetic shift"
functionality.
2 would it be possible to change
bit-set? index i -> boolean
any-bits-set? test-bits i -> boolean
all-bits-set? test-bits i -> boolean
first-set-bit i -> exact-integer
to
bit-set? i index -> boolean
bit-set-any? i test-bits -> boolean
bit-set-all? i test-bits -> boolean
bit-set-smallest i -> exact-integer
No, I think this would be a bad idea, since the convention to which you are
suggesting we hew is one that implies we are thus operating on a
data-structure called a "bit set." But we aren't. Sets of bits are a pretty
boring data structure -- there are only four such sets! Rather, we are
checking to see if any bits in a bit string are set.
3 would it be possible to change
extract-bit-field size position i -> exact-integer
test-bit-field? size position i -> boolean
clear-bit-field size position i -> exact-integer
replace-bit-field size position new-field i -> exact-integer
copy-bit-field size position from to -> exact-integer
to
bit-field-extract i size position -> exact-integer
bit-field-test? i size position -> boolean
bit-field-clear i size position -> exact-integer
bit-field-replace i size position new-field -> exact-integer
bit-field-copy from to size position -> exact-integer
Your param order issue is the "op-currying" vs. "data-structure accessor"
parameter convention. See below.
Your names seem more in tune with Scheme conventions, so I am converting to
them. If people don't like this, speak up.
4 i have been unable to find a better name for
integer-length i -> nonnegative-exact-integer
but would really like to have a 'bit' prefix here too.
Nothing leaps to mind for me, either. It is the traditional name.
It works fine.
-------------------------------------------------------------------------------
- Are NAND & NOR n-ary?
I am frankly somewhat divided on this issue.
Given that Al Petrofsky now supports going with the simple
associative-ops-are-the-n-ary-ops design heuristic, I have
gone with this. I don't think it's a big deal, either way.
I have also just noticed that this split is precisely what
Common Lisp does.
- SIZE/POSITION vs. FROM/TO
I went with SIZE/POSITION. Here is the rationale from the SRFI.
SIZE/POSITION vs. FROM/TO field specs
Several functions in this library
extract-bit-field size position i -> integer
test-bit-field? size position i -> boolean
clear-bit-field size position i -> integer
replace-bit-field size position new-field i -> integer
copy-bit-field size position from to -> integer
specify a contiguous "field" of bits in a bitstring. There are two
conventions we might use to do so:
- SIZE/POSITION
E.g., "the 8-bit field beginning at bit 3", and
- FROM/TO
E.g., "the field from bit 3 up to, but not including, bit 11", or, perhaps,
"the field from bit 3 up to bit 10, inclusive."
FROM/TO specs are conventionally and most usefully "half-open" specs, meaning
"all i such that FROM <= i and i < TO" -- the FROM index is included and the
TO index is excluded.
I have chosen to use SIZE/POSITION instead of FROM/TO for this library.
Doing so eliminates any possibility of fencepost errors on the TO endpoint.
It is also the convention chosen by Common Lisp.
It is not, however, a widely-used convention within Scheme. Most ranges
in Scheme are specified with half-open intervals of the [from,to) form
(e.g., (substring s from to)). One might argue that SIZE/POSITION is still
the right thing for bit fields, as they are, in practice, frequently of fixed
size, unlike element ranges in strings or vectors.
- ANY/ALL lexemes -> standard ANY/EVERY lexemes
I have noticed that the ANY-BITS-SET? / ALL-BITS-SET? pair of functions
do not follow the Scheme naming convention of using ANY and EVERY.
Also, ALL is a word that pairs with SOME; ANY pairs with EVERY.
So I have renamed them:
ANY-BITS-SET? => ANY-BIT-SET?
ALL-BITS-SET? => EVERY-BIT-SET?
Notice the "bit-set" lexem is now consistently singular, which is
both more consistent with other names and grammatically correct.
- TEST-BIT-FIELD? => BIT-FIELD-ANY? BIT-FIELD-EVERY?
TEST-BIT-FIELD tests for *any* bit in the field being set; it should be
complemented with a function to test for *all* bits in the field being
set. So I have replaced it with the pair of functions
BIT-FIELD-ANY?
BIT-FIELD-EVERY?
Note that you can also check for any/every bit in the field being clear,
as well, by negating these functions.
This name choice is also closer to Bengt's preferred choices.
