Resuming SRFI-33 discussion

[shivers@xxxxxxxxxxxxx]

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 <eleberg@xxxxxxxxxxxxxxx>

    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.