Re: garbled documentation

[Kevin Ryde]

"Rouben Rostamian" <address@hidden> writes:
>
>  - Scheme Procedure: bit-set*! v kv obj
>  - C Function: scm_bit_set_star_x (v, kv, obj)
>
> This description is garbled.  The procedure arguments are listed
> as "v kv obj" while the description refers to "uve, BV, BOOL", etc.

Yep.  It's not really as clear as it could be either.

> In fact, most descriptions under the section "Bit Vectors" suffer from
> the same problem.

I made a bit of a revision:


Bit Vectors
-----------

Bit vectors are a specific type of uniform array: an array of booleans
with a single zero-based index.

They are displayed as a sequence of `0's and `1's prefixed by `#*',
e.g.,

     (make-uniform-vector 8 #t #f) =>
     #*00000000

 - Scheme Procedure: bit-count bool bitvector
 - C Function: scm_bit_count (bool, bitvector)
     Return a count of entries in BITVECTOR equal to BOOL.  For example,

          (bit-count #f #*000111000)  => 6

 - Scheme Procedure: bit-position bool bitvector start
 - C Function: scm_bit_position (bool, bitvector, start)
     Return the index of the first occurrance of BOOL in BITVECTOR,
     starting from START.  If there is no BOOL entry between START and
     the end of BITVECTOR, then return `#f'.  For example,

          (bit-position #t #*000101 0)  => 3
          (bit-position #f #*0001111 3) => #f

 - Scheme Procedure: bit-invert! bitvector
 - C Function: scm_bit_invert_x (bitvector)
     Modify BITVECTOR by replacing each element with its negation.

 - Scheme Procedure: bit-set*! bitvector uvec bool
 - C Function: scm_bit_set_star_x (bitvector, uvec, bool)
     Set entries of BITVECTOR to BOOL, with UVEC selecting the entries
     to change.

     If UVEC is a bit vector, then those entries where it has `#t' are
     the ones in BITVECTOR which are set to BOOL.  When BOOL is `#t'
     it's like UVEC is OR'ed into BITVECTOR.  Or when BOOL is `#f' it
     can be seen as an ANDNOT.

          (define bv #*01000010)
          (bit-set*! bv #*10010001 #t)
          bv
          => #*11010011

     If UVEC is a uniform vector of unsigned long integers, then
     they're indexes into BITVECTOR which are set to BOOL.

          (define bv #*01000010)
          (bit-set*! bv #u(5 2 7) #t)
          bv
          => #*01100111

 - Scheme Procedure: bit-count* bitvector uvec bool
 - C Function: scm_bit_count_star (bitvector, uvec, bool)
     Return a count of entries in BITVECTOR which are equal to BOOL,
     with UVEC selecting the entries to consider.

     UVEC is interpreted in the same way as `bit-set*!' above.  Namely,
     if UVEC is a bit vector then entries which have `#t' there are
     considered in BITVECTOR.  Or if UVEC is a uniform vector of
     unsigned long integers then it's the indexes in BITVECTOR to
     consider.

     For example,

          (bit-count* #*01110111 #*11001101 #t) => 3
          (bit-count* #*01110111 #u(7 0 4) #f)  => 2