[R6RS] comments on proposed bytes SRFI

[William D Clinger]

Comments on draft/bytes/bytes-srfi.html

I'd like to see the 8-bit assumption mentioned early,
as could be accomplished by changing the first paragraph
of the Specification's General remarks to

    Bytes objects are objects of a disjoint type.
    Conceptually, a bytes object represents a sequence
    of 8-bit bytes.

On 3 May we voted to require set-car! etc to return
exactly one specified unspecified value.  IMO this
SRFI is covered by the "etc", so the paragraphs at
the end of the Specification's General remarks should
be changed to

    For procedures that have no "natural" return
    value, this description often uses the sentence

    The return value is unspecified.

    This means the procedure is required to return
    the specific unspecified value that is returned
    by the <code>unspecified</code> procedure.

Furthermore the sentence "The return values are
unspecified." should be changed globally to the
sentence above.

The specification of bytes-u8-ref and bytes-s8-ref
should mention 8 bits, or else describe the range of
possible values that may be returned.

In general, I'd prefer that arguments be passed in
an order that is consistent from left to right rather
than right to left.  For example, I'd prefer to see

    (bytes-s8-ref   bytes k)
    (bytes-s16-ref  bytes k endianness)
    (bytes-sint-ref bytes k endianness size)

Not only do I find left-to-right consistency easier
to read, but it also tends to involve less register
shuffling on register architectures, e.g.

    (define (bytes-s16-ref bytes k endianness)
      (bytes-sint-ref bytes k endianness 2))

Lest someone claim that register architectures don't
matter, I'll note that the IA32 has enough registers
for this to matter, and that implementations can and
do take advantage of those registers, especially when
calling known procedures, as these are likely to be
(thanks to the proposed library system).

I therefore propose the following changes in order of
arguments:

  (bytes-uint-ref bytes k endianness size)
  (bytes-sint-ref bytes k endianness size)
  (bytes-uint-set! bytes k n endianness size)
  (bytes-sint-set! bytes k n endianness size)

  (bytes-u16-ref bytes k endianness)
  (bytes-s16-ref bytes k endianness)
  (bytes-u16-native-ref bytes k)
  (bytes-s16-native-ref bytes k)
  (bytes-u16-set! bytes k n endianness)
  (bytes-s16-set! bytes k n endianness)
  (bytes-u16-native-set! bytes k n)
  (bytes-s16-native-set! bytes k n)

  (bytes-u32-ref bytes k endianness)
  (bytes-s32-ref bytes k endianness)
  (bytes-u32-native-ref bytes k)
  (bytes-s32-native-ref bytes k)
  (bytes-u32-set! bytes k n endianness)
  (bytes-s32-set! bytes k n endianness)
  (bytes-u32-native-set! bytes k n)
  (bytes-s32-native-set! bytes k n)

  (bytes-u64-ref bytes k endianness)
  (bytes-s64-ref bytes k endianness)
  (bytes-u64-native-ref bytes k)
  (bytes-s64-native-ref bytes k)
  (bytes-u64-set! bytes k n endianness)
  (bytes-s64-set! bytes k n endianness)
  (bytes-u64-native-set! bytes k n)
  (bytes-s64-native-set! bytes k n)

  (bytes->uint-list bytes endianness size)
  (bytes->sint-list bytes endianness size)
  (uint-list->bytes list endianness size)
  (sint-list->bytes list endianness size)

The word "octet" that appears in the specification of
bytes-u8-set! will not be as familiar to North Americans
as it is to Europeans, and should be defined as an exact
integer in the interval {0, ..., 255}, much as the word
byte is defined in the specification of bytes-s8-set!.

The specification of bytes=? should say "if and only if".

The specification of bytes->u8-list says the argument
must be a list of bytes.  If byte is defined as in the
specification of bytes-s8-set!, then this means the
elements of that list must lie within the interval
[-128,127], contrary to the interval [0,255] suggested
by the u8 in the name and the specification of
bytes-u8-set!.

I can't tell whether bytes->u8-list and u8-list->bytes
were misnamed or mis-specified.  Perhaps bytes->s8-list
and s8-list->bytes should be added, although there isn't
much need of them given the bytes->sint-list and
sint-list->bytes.  Perhaps bytes->u8-list and its
inverse should just be flushed.

Will