### 7.1 Data Structures ¶

#### 7.1.1 Arrays ¶

`(require 'array)` or `(require 'srfi-63)`

Function: array? obj ¶

  Returns `#t` if the obj is an array, and `#f` if not.

Note: Arrays are not disjoint from other Scheme types. Vectors and possibly strings also satisfy `array?`. A disjoint array predicate can be written:

    (define (strict-array? obj)
      (and (array? obj) (not (string? obj)) (not (vector? obj))))

Function: equal? obj1 obj2 ¶

  Returns `#t` if obj1 and obj2 have the same rank and dimensions and the corresponding elements of obj1 and obj2 are `equal?`.

  `equal?` recursively compares the contents of pairs, vectors, strings, and arrays, applying `eqv?` on other objects such as numbers and symbols. A rule of thumb is that objects are generally `equal?` if they print the same. `equal?` may fail to terminate if its arguments are circular data structures.

      (equal? 'a 'a)                             ⇒  #t
      (equal? '(a) '(a))                         ⇒  #t
      (equal? '(a (b) c)
              '(a (b) c))                        ⇒  #t
      (equal? "abc" "abc")                       ⇒  #t
      (equal? 2 2)                               ⇒  #t
      (equal? (make-vector 5 'a)
              (make-vector 5 'a))                ⇒  #t
      (equal? (make-array (A:fixN32b 4) 5 3)
              (make-array (A:fixN32b 4) 5 3))    ⇒  #t
      (equal? (make-array '#(foo) 3 3)
              (make-array '#(foo) 3 3))          ⇒  #t
      (equal? (lambda (x) x)
              (lambda (y) y))                    ⇒  unspecified

Function: array-rank obj ¶

  Returns the number of dimensions of obj. If obj is not an array, 0 is returned.

Function: array-dimensions array ¶

  Returns a list of dimensions.

      (array-dimensions (make-array '#() 3 5))
         ⇒ (3 5)

Function: make-array prototype k1 … ¶

  Creates and returns an array of type prototype with dimensions k1, … and filled with elements from prototype. prototype must be an array, vector, or string. The implementation-dependent type of the returned array will be the same as the type of prototype; except if that would be a vector or string with rank not equal to one, in which case some variety of array will be returned.

  If the prototype has no elements, then the initial contents of the returned array are unspecified. Otherwise, the returned array will be filled with the element at the origin of prototype.

Function: create-array prototype k1 … ¶

  `create-array` is an alias for `make-array`.

Function: make-shared-array array mapper k1 … ¶

  `make-shared-array` can be used to create shared subarrays of other arrays. The mapper is a function that translates coordinates in the new array into coordinates in the old array. A mapper must be linear, and its range must stay within the bounds of the old array, but it can be otherwise arbitrary. A simple example:

      (define fred (make-array '#(#f) 8 8))
      (define freds-diagonal
        (make-shared-array fred (lambda (i) (list i i)) 8))
      (array-set! freds-diagonal 'foo 3)
      (array-ref fred 3 3)
         ⇒ FOO
      (define freds-center
        (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j)))
                           2 2))
      (array-ref freds-center 0 0)
         ⇒ FOO

Function: list->array rank proto list ¶

  list must be a rank-nested list consisting of all the elements, in row-major order, of the array to be created.

  `list->array` returns an array of rank rank and type proto consisting of all the elements, in row-major order, of list. When rank is 0, list is the lone array element; not necessarily a list.

      (list->array 2 '#() '((1 2) (3 4)))
                      ⇒ #2A((1 2) (3 4))
      (list->array 0 '#() 3)
                      ⇒ #0A 3

Function: array->list array ¶

  Returns a rank-nested list consisting of all the elements, in row-major order, of array. In the case of a rank-0 array, `array->list` returns the single element.

      (array->list #2A((ho ho ho) (ho oh oh)))
                      ⇒ ((ho ho ho) (ho oh oh))
      (array->list #0A ho)
                      ⇒ ho

Function: vector->array vect proto dim1 … ¶

  vect must be a vector of length equal to the product of exact nonnegative integers dim1, ….

  `vector->array` returns an array of type proto consisting of all the elements, in row-major order, of vect. In the case of a rank-0 array, vect has a single element.

      (vector->array #(1 2 3 4) #() 2 2)
                      ⇒ #2A((1 2) (3 4))
      (vector->array '#(3) '#())
                      ⇒ #0A 3

Function: array->vector array ¶

  Returns a new vector consisting of all the elements of array in row-major order.

      (array->vector #2A ((1 2)( 3 4)))
                      ⇒ #(1 2 3 4)
      (array->vector #0A ho)
                      ⇒ #(ho)

Function: array-in-bounds? array index1 … ¶

  Returns `#t` if its arguments would be acceptable to `array-ref`.

Function: array-ref array k1 … ¶

  Returns the (k1, …) element of array.

Procedure: array-set! array obj k1 … ¶

  Stores obj in the (k1, …) element of array. The value returned by `array-set!` is unspecified.

These functions return a prototypical uniform-array enclosing the optional argument (which must be of the correct type). If the uniform-array type is supported by the implementation, then it is returned; defaulting to the next larger precision type; resorting finally to vector.

Function: A:floC128b z ¶
Function: A:floC128b ¶

  Returns an inexact 128.bit flonum complex uniform-array prototype.

Function: A:floC64b z ¶
Function: A:floC64b ¶

  Returns an inexact 64.bit flonum complex uniform-array prototype.

Function: A:floC32b z ¶
Function: A:floC32b ¶

  Returns an inexact 32.bit flonum complex uniform-array prototype.

Function: A:floC16b z ¶
Function: A:floC16b ¶

  Returns an inexact 16.bit flonum complex uniform-array prototype.

Function: A:floR128b x ¶
Function: A:floR128b ¶

  Returns an inexact 128.bit flonum real uniform-array prototype.

Function: A:floR64b x ¶
Function: A:floR64b ¶

  Returns an inexact 64.bit flonum real uniform-array prototype.

Function: A:floR32b x ¶
Function: A:floR32b ¶

  Returns an inexact 32.bit flonum real uniform-array prototype.

Function: A:floR16b x ¶
Function: A:floR16b ¶

  Returns an inexact 16.bit flonum real uniform-array prototype.

Function: A:floQ128d q ¶
Function: A:floQ128d ¶

  Returns an exact 128.bit decimal flonum rational uniform-array prototype.

Function: A:floQ64d q ¶
Function: A:floQ64d ¶

  Returns an exact 64.bit decimal flonum rational uniform-array prototype.

Function: A:floQ32d q ¶
Function: A:floQ32d ¶

  Returns an exact 32.bit decimal flonum rational uniform-array prototype.

Function: A:fixZ64b n ¶
Function: A:fixZ64b ¶

  Returns an exact binary fixnum uniform-array prototype with at least 64 bits of precision.

Function: A:fixZ32b n ¶
Function: A:fixZ32b ¶

  Returns an exact binary fixnum uniform-array prototype with at least 32 bits of precision.

Function: A:fixZ16b n ¶
Function: A:fixZ16b ¶

  Returns an exact binary fixnum uniform-array prototype with at least 16 bits of precision.

Function: A:fixZ8b n ¶
Function: A:fixZ8b ¶

  Returns an exact binary fixnum uniform-array prototype with at least 8 bits of precision.

Function: A:fixN64b k ¶
Function: A:fixN64b ¶

  Returns an exact non-negative binary fixnum uniform-array prototype with at least 64 bits of precision.

Function: A:fixN32b k ¶
Function: A:fixN32b ¶

  Returns an exact non-negative binary fixnum uniform-array prototype with at least 32 bits of precision.

Function: A:fixN16b k ¶
Function: A:fixN16b ¶

  Returns an exact non-negative binary fixnum uniform-array prototype with at least 16 bits of precision.

Function: A:fixN8b k ¶
Function: A:fixN8b ¶

  Returns an exact non-negative binary fixnum uniform-array prototype with at least 8 bits of precision.

Function: A:bool bool ¶
Function: A:bool ¶

  Returns a boolean uniform-array prototype.

#### 7.1.2 Subarrays ¶

`(require 'subarray)`

Function: subarray array select … ¶

  selects a subset of an array. For 0 <= j < n, select j is either an integer, a list of two integers within the range for the jth index, or #f.

  When select j is a list of two integers, then the jth index is restricted to that subrange in the returned array.

  When select j is #f, then the full range of the jth index is accessible in the returned array. An elided argument is equivalent to #f.

  When select j is an integer, then the rank of the returned array is less than array, and only elements whose jth index equals select j are shared.

      > (define ra '#2A((a b c) (d e f)))
      #<unspecified>
      > (subarray ra 0 #f)
      #1A(a b c)
      > (subarray ra 1 #f)
      #1A(d e f)
      > (subarray ra #f 1)
      #1A(b e)
      > (subarray ra '(0 1) #f)
      #2A((a b c) (d e f))
      > (subarray ra #f '(0 1))
      #2A((a b) (d e))
      > (subarray ra #f '(1 2))
      #2A((b c) (e f))
      > (subarray ra #f '(2 1))
      #2A((c b) (f e))

  Arrays can be reflected (reversed) using `subarray`:

      > (subarray '#1A(a b c d e) '(4 0))
      #1A(e d c b a)

Function: array-trim array trim … ¶

  Returns a subarray sharing contents with array except for slices removed from either side of each dimension. Each of the trims is an exact integer indicating how much to trim. A positive s trims the data from the lower end and reduces the upper bound of the result; a negative s trims from the upper end and increases the lower bound.

  For example:

      (array-trim '#(0 1 2 3 4) 1)  ⇒ #1A(1 2 3 4)
      (array-trim '#(0 1 2 3 4) -1) ⇒ #1A(0 1 2 3)

      (require 'array-for-each)
      (define (centered-difference ra)
        (array-map ra - (array-trim ra 1) (array-trim ra -1)))

      (centered-difference '#(0 1 3 5 9 22))
        ⇒ #(1 2 2 4 13)

#### 7.1.3 Array Mapping ¶

`(require 'array-for-each)`

Procedure: array-map! array0 proc array1 … ¶

  array1, … must have the same number of dimensions as array0 and have a range for each index which includes the range for the corresponding index in array0. proc is applied to each tuple of elements of array1 … and the result is stored as the corresponding element in array0. The value returned is unspecified. The order of application is unspecified.

Function: array-map prototype proc array1 array2 … ¶

  array2, … must have the same number of dimensions as array1 and have a range for each index which includes the range for the corresponding index in array1. proc is applied to each tuple of elements of array1, array2, … and the result is stored as the corresponding element in a new array of type prototype. The new array is returned. The order of application is unspecified.

Function: array-for-each proc array0 … ¶

  proc is applied to each tuple of elements of array0 … in row-major order. The value returned is unspecified.

Function: array-indexes array ¶

  Returns an array of lists of indexes for array such that, if li is a list of indexes for which array is defined, (equal? li (apply array-ref (array-indexes array) li)).

Function: array-index-for-each array proc ¶

  applies proc to the indices of each element of array in turn. The value returned and the order of application are unspecified.

  One can implement array-index-map! as

      (define (array-index-map! ra fun)
        (array-index-for-each
         ra
         (lambda is (apply array-set! ra (apply fun is) is))))

Procedure: array-index-map! array proc ¶

  applies proc to the indices of each element of array in turn, storing the result in the corresponding element. The value returned and the order of application are unspecified.

  One can implement array-indexes as

      (define (array-indexes array)
          (let ((ra (apply make-array '#() (array-dimensions array))))
            (array-index-map! ra (lambda x x))
            ra))

  Another example:

      (define (apl:index-generator n)
          (let ((v (make-vector n 1)))
            (array-index-map! v (lambda (i) i))
            v))

Procedure: array:copy! destination source ¶

  Copies every element from vector or array source to the corresponding element of destination. destination must have the same rank as source, and be at least as large in each dimension. The order of copying is unspecified.

#### 7.1.4 Array Interpolation ¶

`(require 'array-interpolate)`

Function: interpolate-array-ref ra x1 … xj ¶

  ra must be an array of rank j containing numbers. `interpolate-array-ref` returns a value interpolated from the nearest j-dimensional cube of elements of ra.

      (interpolate-array-ref '#2A:fixZ32b((1 2 3) (4 5 6)) 1 0.1)
                                    ==> 4.1
      (interpolate-array-ref '#2A:fixZ32b((1 2 3) (4 5 6)) 0.5 0.25)
                                    ==> 2.75

Procedure: resample-array! ra1 ra2 ¶

  ra1 and ra2 must be numeric arrays of equal rank. `resample-array!` sets ra1 to values interpolated from ra2 such that the values of elements at the corners of ra1 and ra2 are equal.

      (define ra (make-array (A:fixZ32b) 2 2))
      (resample-array! ra '#2A:fixZ32b((1 2 3) (4 5 6)))
      ra              ==>  #2A:fixZ32b((1 3) (4 6))
      (define ra (make-array (A:floR64b) 3 2))
      (resample-array! ra '#2A:fixZ32b((1 2 3) (4 5 6)))
      ra              ==>  #2A:floR64b((1.0 3.0) (2.5 4.5) (4.0 6.0))

#### 7.1.5 Association Lists ¶

`(require 'alist)`

Alist functions provide utilities for treating a list of key-value pairs as an associative database. These functions take an equality predicate, pred, as an argument. This predicate should be repeatable, symmetric, and transitive.

Alist functions can be used with a secondary index method such as hash tables for improved performance.

Function: predicate->asso pred ¶

  Returns an association function (like `assq`, `assv`, or `assoc`) corresponding to pred. The returned function returns a key-value pair whose key is `pred`-equal to its first argument or `#f` if no key in the alist is pred-equal to the first argument.

Function: alist-inquirer pred ¶

  Returns a procedure of 2 arguments, alist and key, which returns the value associated with key in alist or `#f` if key does not appear in alist.

Function: alist-associator pred ¶

  Returns a procedure of 3 arguments, alist, key, and value, which returns an alist with key and value associated. Any previous value associated with key will be lost. This returned procedure may or may not have side effects on its alist argument. An example of correct usage is:

      (define put (alist-associator string-ci=?))
      (define alist '())
      (set! alist (put alist "Foo" 9))

Function: alist-remover pred ¶

  Returns a procedure of 2 arguments, alist and key, which returns an alist with an association whose key is key removed. This returned procedure may or may not have side effects on its alist argument. An example of correct usage is:

      (define rem (alist-remover string-ci=?))
      (set! alist (rem alist "foo"))

Function: alist-map proc alist ¶

  Returns a new association list formed by mapping proc over the keys and values of alist. proc must be a function of 2 arguments which returns the new value part.

Function: alist-for-each proc alist ¶

  Applies proc to each pair of keys and values of alist. proc must be a function of 2 arguments. The returned value is unspecified.

#### 7.1.6 Byte ¶

`(require 'byte)`

Some algorithms are expressed in terms of arrays of small integers. Using Scheme strings to implement these arrays is not portable vis-a-vis the correspondence between integers and characters and non-ascii character sets. These functions abstract the notion of a byte.

Function: byte-ref bytes k ¶

  k must be a valid index of bytes. `byte-ref` returns byte k of bytes using zero-origin indexing.

Procedure: byte-set! bytes k byte ¶

  k must be a valid index of bytes, and byte must be a small nonnegative integer. `byte-set!` stores byte in element k of bytes and returns an unspecified value.

Function: make-bytes k byte ¶
Function: make-bytes k ¶

  `make-bytes` returns a newly allocated byte-array of length k. If byte is given, then all elements of the byte-array are initialized to byte, otherwise the contents of the byte-array are unspecified.

Function: bytes-length bytes ¶

  `bytes-length` returns length of byte-array bytes.

Function: bytes byte … ¶

  Returns a newly allocated byte-array composed of the small nonnegative arguments.

Function: list->bytes bytes ¶

  `list->bytes` returns a newly allocated byte-array formed from the small nonnegative integers in the list bytes.

Function: bytes->list bytes ¶

  `bytes->list` returns a newly allocated list of the bytes that make up the given byte-array.

`Bytes->list` and `list->bytes` are inverses so far as `equal?` is concerned.

Function: bytes->string bytes ¶

  Returns a new string formed from applying `integer->char` to each byte in `bytes->string`. Note that this may signal an error for bytes having values between 128 and 255.

Function: string->bytes string ¶

  Returns a new byte-array formed from applying `char->integer` to each character in `string->bytes`. Note that this may signal an error if an integer is larger than 255.

Function: bytes-copy bytes ¶

  Returns a newly allocated copy of the given bytes.

Function: subbytes bytes start end ¶

  bytes must be a bytes, and start and end must be exact integers satisfying

  0 <= start <= end <= `(bytes-length bytes).`

  `subbytes` returns a newly allocated bytes formed from the bytes of bytes beginning with index start (inclusive) and ending with index end (exclusive).

Procedure: bytes-reverse! bytes ¶

  Reverses the order of byte-array bytes.

Function: bytes-reverse bytes ¶

  Returns a newly allocated bytes-array consisting of the elements of bytes in reverse order.

Input and output of bytes should be with ports opened in binary mode (see Input/Output). Calling `open-file` with ’rb or ’wb modes argument will return a binary port if the Scheme implementation supports it.

Function: write-byte byte port ¶
Function: write-byte byte ¶

  Writes the byte byte (not an external representation of the byte) to the given port and returns an unspecified value. The port argument may be omitted, in which case it defaults to the value returned by `current-output-port`.

Function: read-byte port ¶
Function: read-byte ¶

  Returns the next byte available from the input port, updating the port to point to the following byte. If no more bytes are available, an end-of-file object is returned. port may be omitted, in which case it defaults to the value returned by `current-input-port`.

When reading and writing binary numbers with `read-bytes` and `write-bytes`, the sign of the length argument determines the endianness (order) of bytes. Positive treats them as big-endian, the first byte input or output is highest order. Negative treats them as little-endian, the first byte input or output is the lowest order.

Once read in, SLIB treats byte sequences as big-endian. The multi-byte sequences produced and used by number conversion routines see Byte/Number Conversions are always big-endian.

Function: read-bytes n port ¶
Function: read-bytes n ¶

  `read-bytes` returns a newly allocated bytes-array filled with `(abs n)` bytes read from port. If n is positive, then the first byte read is stored at index 0; otherwise the last byte read is stored at index 0. Note that the length of the returned byte-array will be less than `(abs n)` if port reaches end-of-file.

  port may be omitted, in which case it defaults to the value returned by `current-input-port`.

Function: write-bytes bytes n port ¶
Function: write-bytes bytes n ¶

  `write-bytes` writes `(abs n)` bytes to output-port port. If n is positive, then the first byte written is index 0 of bytes; otherwise the last byte written is index 0 of bytes. `write-bytes` returns an unspecified value.

  port may be omitted, in which case it defaults to the value returned by `current-output-port`.

`subbytes-read!` and `subbytes-write` provide lower-level procedures for reading and writing blocks of bytes. The relative size of start and end determines the order of writing.

Procedure: subbytes-read! bts start end port ¶
Procedure: subbytes-read! bts start end ¶

  Fills bts with up to `(abs (- start end))` bytes read from port. The first byte read is stored at index bts. `subbytes-read!` returns the number of bytes read.

  port may be omitted, in which case it defaults to the value returned by `current-input-port`.

Function: subbytes-write bts start end port ¶
Function: subbytes-write bts start end ¶

  `subbytes-write` writes `(abs (- start end))` bytes to output-port port. The first byte written is index start of bts. `subbytes-write` returns the number of bytes written.

  port may be omitted, in which case it defaults to the value returned by `current-output-port`.

#### 7.1.7 Byte/Number Conversions ¶

`(require 'byte-number)`

The multi-byte sequences produced and used by numeric conversion routines are always big-endian. Endianness can be changed during reading and writing bytes using `read-bytes` and `write-bytes` See read-bytes.

The sign of the length argument to bytes/integer conversion procedures determines the signedness of the number.

Function: bytes->integer bytes n ¶

  Converts the first `(abs n)` bytes of big-endian bytes array to an integer. If n is negative then the integer coded by the bytes are treated as two’s-complement (can be negative).

      (bytes->integer (bytes   0   0   0  15) -4)   ⇒          15
      (bytes->integer (bytes   0   0   0  15)  4)   ⇒          15
      (bytes->integer (bytes 255 255 255 255) -4)   ⇒          -1
      (bytes->integer (bytes 255 255 255 255)  4)   ⇒  4294967295
      (bytes->integer (bytes 128   0   0   0) -4)   ⇒ -2147483648
      (bytes->integer (bytes 128   0   0   0)  4)   ⇒  2147483648

Function: integer->bytes n len ¶

  Converts the integer n to a byte-array of `(abs n)` bytes. If n and len are both negative, then the bytes in the returned array are coded two’s-complement.

      (bytes->list (integer->bytes          15 -4))   ⇒ (0 0 0 15)
      (bytes->list (integer->bytes          15  4))   ⇒ (0 0 0 15)
      (bytes->list (integer->bytes          -1 -4))   ⇒ (255 255 255 255)
      (bytes->list (integer->bytes  4294967295  4))   ⇒ (255 255 255 255)
      (bytes->list (integer->bytes -2147483648 -4))   ⇒ (128 0 0 0)
      (bytes->list (integer->bytes  2147483648  4))   ⇒ (128 0 0 0)

Function: bytes->ieee-float bytes ¶

  bytes must be a 4-element byte-array. `bytes->ieee-float` calculates and returns the value of bytes interpreted as a big-endian IEEE 4-byte (32-bit) number.

    (bytes->ieee-float (bytes    0    0 0 0))  ⇒  0.0
    (bytes->ieee-float (bytes #x80    0 0 0))  ⇒ -0.0
    (bytes->ieee-float (bytes #x40    0 0 0))  ⇒  2.0
    (bytes->ieee-float (bytes #x40 #xd0 0 0))  ⇒  6.5
    (bytes->ieee-float (bytes #xc0 #xd0 0 0))  ⇒ -6.5

    (bytes->ieee-float (bytes    0 #x80 0 0))  ⇒ 11.754943508222875e-39
    (bytes->ieee-float (bytes    0 #x40 0 0))  ⇒  5.877471754111437e-39
    (bytes->ieee-float (bytes    0    0 0 1))  ⇒  1.401298464324817e-45

    (bytes->ieee-float (bytes #xff #x80 0 0))  ⇒ -inf.0
    (bytes->ieee-float (bytes #x7f #x80 0 0))  ⇒ +inf.0
    (bytes->ieee-float (bytes #x7f #x80 0 1))  ⇒  0/0
    (bytes->ieee-float (bytes #x7f #xc0 0 0))  ⇒  0/0

Function: bytes->ieee-double bytes ¶

  bytes must be a 8-element byte-array. `bytes->ieee-double` calculates and returns the value of bytes interpreted as a big-endian IEEE 8-byte (64-bit) number.

    (bytes->ieee-double (bytes    0    0 0 0 0 0 0 0))  ⇒  0.0
    (bytes->ieee-double (bytes #x80    0 0 0 0 0 0 0))  ⇒ -0.0
    (bytes->ieee-double (bytes #x40    0 0 0 0 0 0 0))  ⇒  2.0
    (bytes->ieee-double (bytes #x40 #x1A 0 0 0 0 0 0))  ⇒  6.5
    (bytes->ieee-double (bytes #xC0 #x1A 0 0 0 0 0 0))  ⇒ -6.5

    (bytes->ieee-double (bytes 0 8 0 0 0 0 0 0)) ⇒ 11.125369292536006e-309
    (bytes->ieee-double (bytes 0 4 0 0 0 0 0 0)) ⇒  5.562684646268003e-309
    (bytes->ieee-double (bytes 0 0 0 0 0 0 0 1)) ⇒  4.0e-324

    (bytes->ieee-double (list->bytes '(127 239 255 255 255 255 255 255))) 179.76931348623157e306
    (bytes->ieee-double (bytes #xFF #xF0 0 0 0 0 0 0))  ⇒ -inf.0
    (bytes->ieee-double (bytes #x7F #xF0 0 0 0 0 0 0))  ⇒ +inf.0
    (bytes->ieee-double (bytes #x7F #xF8 0 0 0 0 0 0))  ⇒  0/0

Function: ieee-float->bytes x ¶

  Returns a 4-element byte-array encoding the IEEE single-precision floating-point of x.

    (bytes->list (ieee-float->bytes  0.0))                    ⇒ (0     0 0 0)
    (bytes->list (ieee-float->bytes -0.0))                    ⇒ (128   0 0 0)
    (bytes->list (ieee-float->bytes  2.0))                    ⇒ (64    0 0 0)
    (bytes->list (ieee-float->bytes  6.5))                    ⇒ (64  208 0 0)
    (bytes->list (ieee-float->bytes -6.5))                    ⇒ (192 208 0 0)

    (bytes->list (ieee-float->bytes 11.754943508222875e-39))  ⇒ (  0 128 0 0)
    (bytes->list (ieee-float->bytes  5.877471754111438e-39))  ⇒ (  0  64 0 0)
    (bytes->list (ieee-float->bytes  1.401298464324817e-45))  ⇒ (  0   0 0 1)

    (bytes->list (ieee-float->bytes -inf.0))                  ⇒ (255 128 0 0)
    (bytes->list (ieee-float->bytes +inf.0))                  ⇒ (127 128 0 0)
    (bytes->list (ieee-float->bytes  0/0))                    ⇒ (127 192 0 0)

Function: ieee-double->bytes x ¶

  Returns a 8-element byte-array encoding the IEEE double-precision floating-point of x.

    (bytes->list (ieee-double->bytes  0.0)) ⇒ (0     0 0 0 0 0 0 0)
    (bytes->list (ieee-double->bytes -0.0)) ⇒ (128   0 0 0 0 0 0 0)
    (bytes->list (ieee-double->bytes  2.0)) ⇒ (64    0 0 0 0 0 0 0)
    (bytes->list (ieee-double->bytes  6.5)) ⇒ (64   26 0 0 0 0 0 0)
    (bytes->list (ieee-double->bytes -6.5)) ⇒ (192  26 0 0 0 0 0 0)

    (bytes->list (ieee-double->bytes 11.125369292536006e-309))
                                            ⇒ (  0   8 0 0 0 0 0 0)
    (bytes->list (ieee-double->bytes  5.562684646268003e-309))
                                            ⇒ (  0   4 0 0 0 0 0 0)
    (bytes->list (ieee-double->bytes  4.0e-324))
                                            ⇒ (  0   0 0 0 0 0 0 1)

    (bytes->list (ieee-double->bytes -inf.0)) ⇒ (255 240 0 0 0 0 0 0)
    (bytes->list (ieee-double->bytes +inf.0)) ⇒ (127 240 0 0 0 0 0 0)
    (bytes->list (ieee-double->bytes  0/0)) ⇒ (127 248 0 0 0 0 0 0)

#### Byte Collation Order ¶

The `string<?` ordering of big-endian byte-array representations of fixed and IEEE floating-point numbers agrees with the numerical ordering only when those numbers are non-negative.

Straighforward modification of these formats can extend the byte-collating order to work for their entire ranges. This agreement enables the full range of numbers as keys in indexed-sequential-access-method databases.

Procedure: integer-byte-collate! byte-vector ¶

  Modifies sign bit of byte-vector so that `string<?` ordering of two’s-complement byte-vectors matches numerical order. `integer-byte-collate!` returns byte-vector and is its own functional inverse.

Function: integer-byte-collate byte-vector ¶

  Returns copy of byte-vector with sign bit modified so that `string<?` ordering of two’s-complement byte-vectors matches numerical order. `integer-byte-collate` is its own functional inverse.

Procedure: ieee-byte-collate! byte-vector ¶

  Modifies byte-vector so that `string<?` ordering of IEEE floating-point byte-vectors matches numerical order. `ieee-byte-collate!` returns byte-vector.

Procedure: ieee-byte-decollate! byte-vector ¶

  Given byte-vector modified by `ieee-byte-collate!`, reverses the byte-vector modifications.

Function: ieee-byte-collate byte-vector ¶

  Returns copy of byte-vector encoded so that `string<?` ordering of IEEE floating-point byte-vectors matches numerical order.

Function: ieee-byte-decollate byte-vector ¶

  Given byte-vector returned by `ieee-byte-collate`, reverses the byte-vector modifications.

#### 7.1.8 MAT-File Format ¶

`(require 'matfile)`

http://www.mathworks.com/access/helpdesk/help/pdf_doc/matlab/matfile_format.pdf

This package reads MAT-File Format version 4 (MATLAB) binary data files. MAT-files written from big-endian or little-endian computers having IEEE format numbers are currently supported. Support for files written from VAX or Cray machines could also be added.

The numeric and text matrix types handled; support for sparse matrices awaits a sample file.

Function: matfile:read filename ¶

  filename should be a string naming an existing file containing a MATLAB Version 4 MAT-File. The `matfile:read` procedure reads matrices from the file and returns a list of the results; a list of the name string and array for each matrix.

Function: matfile:load filename ¶

  filename should be a string naming an existing file containing a MATLAB Version 4 MAT-File. The `matfile:load` procedure reads matrices from the file and defines the `string-ci->symbol` for each matrix to its corresponding array. `matfile:load` returns a list of the symbols defined.

#### 7.1.9 Portable Image Files ¶

`(require 'pnm)`

Function: pnm:type-dimensions path ¶

  The string path must name a portable bitmap graphics file. `pnm:type-dimensions` returns a list of 4 items:

  1. A symbol describing the type of the file named by path.
  2. The image width in pixels.
  3. The image height in pixels.
  4. The maximum value of pixels assume in the file.

  The current set of file-type symbols is:

  pbm ¶
  pbm-raw

    Black-and-White image; pixel values are 0 or 1.

  pgm ¶
  pgm-raw

    Gray (monochrome) image; pixel values are from 0 to maxval specified in file header.

  ppm ¶
  ppm-raw

    RGB (full color) image; red, green, and blue interleaved pixel values are from 0 to maxval

Function: pnm:image-file->array path array ¶

  Reads the portable bitmap graphics file named by path into array. array must be the correct size and type for path. array is returned.

Function: pnm:image-file->array path ¶

  `pnm:image-file->array` creates and returns an array with the portable bitmap graphics file named by path read into it.

Function: pnm:array-write type array maxval path comment … ¶

  Writes the contents of array to a type image file named path. The file will have pixel values between 0 and maxval, which must be compatible with type. For ‘`pbm`’ files, maxval must be ‘`1`’. comments are included in the file header.

#### 7.1.10 Collections ¶

`(require 'collect)`

Routines for managing collections. Collections are aggregate data structures supporting iteration over their elements, similar to the Dylan(TM) language, but with a different interface. They have elements indexed by corresponding keys, although the keys may be implicit (as with lists).

New types of collections may be defined as YASOS objects (see Yasos). They must support the following operations:

- `(collection? self)` (always returns `#t`);
- `(size self)` returns the number of elements in the collection;
- `(print self port)` is a specialized print operation for the collection which prints a suitable representation on the given port or returns it as a string if port is `#t`;
- `(gen-elts self)` returns a thunk which on successive invocations yields elements of self in order or gives an error if it is invoked more than `(size self)` times;
- `(gen-keys self)` is like `gen-elts`, but yields the collection’s keys in order.

They might support specialized `for-each-key` and `for-each-elt` operations.

Function: collection? obj ¶

  A predicate, true initially of lists, vectors and strings. New sorts of collections must answer `#t` to `collection?`.

Procedure: map-elts proc collection1 … ¶
Procedure: do-elts proc collection1 … ¶

  proc is a procedure taking as many arguments as there are collections (at least one). The collections are iterated over in their natural order and proc is applied to the elements yielded by each iteration in turn. The order in which the arguments are supplied corresponds to te order in which the collections appear. `do-elts` is used when only side-effects of proc are of interest and its return value is unspecified. `map-elts` returns a collection (actually a vector) of the results of the applications of proc.

  Example:

      (map-elts + (list 1 2 3) (vector 1 2 3))
         ⇒ #(2 4 6)

Procedure: map-keys proc collection1 … ¶
Procedure: do-keys proc collection1 … ¶

  These are analogous to `map-elts` and `do-elts`, but each iteration is over the collections’ keys rather than their elements.

  Example:

      (map-keys + (list 1 2 3) (vector 1 2 3))
         ⇒ #(0 2 4)

Procedure: for-each-key collection proc ¶
Procedure: for-each-elt collection proc ¶

  These are like `do-keys` and `do-elts` but only for a single collection; they are potentially more efficient.

Function: reduce proc seed collection1 … ¶

  A generalization of the list-based `reduce-init` (see Lists as sequences) to collections.

  Examples:

      (reduce + 0 (vector 1 2 3))
         ⇒ 6
      (reduce union '() '((a b c) (b c d) (d a)))
         ⇒ (c b d a).

  `Reduce` called with two arguments will work as does the procedure of the same name from See Common List Functions.

Function: any? pred collection1 … ¶

  A generalization of the list-based `some` (see Lists as sequences) to collections.

  Example:

      (any? odd? (list 2 3 4 5))
         ⇒ #t

Function: every? pred collection1 … ¶

  A generalization of the list-based `every` (see Lists as sequences) to collections.

  Example:

      (every? collection? '((1 2) #(1 2)))
         ⇒ #t

Function: empty? collection ¶

  Returns `#t` iff there are no elements in collection.

  `(empty? collection) ≡ (zero? (size collection))`

Function: size collection ¶

  Returns the number of elements in collection.

Function: Setter list-ref ¶

  See Setters for a definition of setter. N.B. `(setter list-ref)` doesn’t work properly for element 0 of a list.

Here is a sample collection: `simple-table` which is also a `table`.

    (define-predicate TABLE?)
    (define-operation (LOOKUP table key failure-object))
    (define-operation (ASSOCIATE! table key value)) ;; returns key
    (define-operation (REMOVE! table key))          ;; returns value

    (define (MAKE-SIMPLE-TABLE)
      (let ( (table (list)) )
        (object
         ;; table behaviors
         ((TABLE? self) #t)
         ((SIZE self) (size table))
         ((PRINT self port) (format port "#<SIMPLE-TABLE>"))
         ((LOOKUP self key failure-object)
          (cond
           ((assq key table) => cdr)
           (else failure-object)
           ))
         ((ASSOCIATE! self key value)
          (cond
           ((assq key table)
            => (lambda (bucket) (set-cdr! bucket value) key))
           (else
            (set! table (cons (cons key value) table))
            key)
           ))
         ((REMOVE! self key);; returns old value
          (cond
           ((null? table) (slib:error "TABLE:REMOVE! Key not found: " key))
           ((eq? key (caar table))
            (let ( (value (cdar table)) )
              (set! table (cdr table))
              value)
            )
           (else
            (let loop ( (last table) (this (cdr table)) )
              (cond
               ((null? this)
                (slib:error "TABLE:REMOVE! Key not found: " key))
               ((eq? key (caar this))
                (let ( (value (cdar this)) )
                  (set-cdr! last (cdr this))
                  value)
                )
               (else
                (loop (cdr last) (cdr this)))
               ) ) )
           ))

         ;; collection behaviors
         ((COLLECTION? self) #t)
         ((GEN-KEYS self) (collect:list-gen-elts (map car table)))
         ((GEN-ELTS self) (collect:list-gen-elts (map cdr table)))
         ((FOR-EACH-KEY self proc)
          (for-each (lambda (bucket) (proc (car bucket))) table)
          )
         ((FOR-EACH-ELT self proc)
          (for-each (lambda (bucket) (proc (cdr bucket))) table)
          ) ) ) )

#### 7.1.11 Dynamic Data Type ¶

`(require 'dynamic)`

Function: make-dynamic obj ¶

  Create and returns a new dynamic whose global value is obj.

Function: dynamic? obj ¶

  Returns true if and only if obj is a dynamic. No object satisfying `dynamic?` satisfies any of the other standard type predicates.

Function: dynamic-ref dyn ¶

  Return the value of the given dynamic in the current dynamic environment.

Procedure: dynamic-set! dyn obj ¶

  Change the value of the given dynamic to obj in the current dynamic environment. The returned value is unspecified.

Function: call-with-dynamic-binding dyn obj thunk ¶

  Invoke and return the value of the given thunk in a new, nested dynamic environment in which the given dynamic has been bound to a new location whose initial contents are the value obj. This dynamic environment has precisely the same extent as the invocation of the thunk and is thus captured by continuations created within that invocation and re-established by those continuations when they are invoked.

The `dynamic-bind` macro is not implemented.

#### 7.1.12 Hash Tables ¶

`(require 'hash-table)`

Function: predicate->hash pred ¶

  Returns a hash function (like `hashq`, `hashv`, or `hash`) corresponding to the equality predicate pred. pred should be `eq?`, `eqv?`, `equal?`, `=`, `char=?`, `char-ci=?`, `string=?`, or `string-ci=?`.

A hash table is a vector of association lists.

Function: make-hash-table k ¶

  Returns a vector of k empty (association) lists.

Hash table functions provide utilities for an associative database. These functions take an equality predicate, pred, as an argument. pred should be `eq?`, `eqv?`, `equal?`, `=`, `char=?`, `char-ci=?`, `string=?`, or `string-ci=?`.

Function: predicate->hash-asso pred ¶

  Returns a hash association function of 2 arguments, key and hashtab, corresponding to pred. The returned function returns a key-value pair whose key is pred-equal to its first argument or `#f` if no key in hashtab is pred-equal to the first argument.

Function: hash-inquirer pred ¶

  Returns a procedure of 2 arguments, hashtab and key, which returns the value associated with key in hashtab or `#f` if key does not appear in hashtab.

Function: hash-associator pred ¶

  Returns a procedure of 3 arguments, hashtab, key, and value, which modifies hashtab so that key and value associated. Any previous value associated with key will be lost.

Function: hash-remover pred ¶

  Returns a procedure of 2 arguments, hashtab and key, which modifies hashtab so that the association whose key is key is removed.

Function: hash-map proc hash-table ¶

  Returns a new hash table formed by mapping proc over the keys and values of hash-table. proc must be a function of 2 arguments which returns the new value part.

Function: hash-for-each proc hash-table ¶

  Applies proc to each pair of keys and values of hash-table. proc must be a function of 2 arguments. The returned value is unspecified.

Function: hash-rehasher pred ¶

  `hash-rehasher` accepts a hash table predicate and returns a function of two arguments hashtab and new-k which is specialized for that predicate.

  This function is used for nondestrutively resizing a hash table. hashtab should be an existing hash-table using pred, new-k is the size of a new hash table to be returned. The new hash table will have all of the associations of the old hash table.

#### 7.1.13 Macroless Object System ¶

`(require 'object)`

This is the Macroless Object System written by Wade Humeniuk (whumeniu@datap.ca). Conceptual Tributes: Yasos, MacScheme’s %object, CLOS, Lack of R4RS macros.

#### 7.1.14 Concepts ¶

OBJECT

  An object is an ordered association-list (by `eq?`) of methods (procedures). Methods can be added (`make-method!`), deleted (`unmake-method!`) and retrieved (`get-method`). Objects may inherit methods from other objects. The object binds to the environment it was created in, allowing closures to be used to hide private procedures and data.

GENERIC-METHOD

  A generic-method associates (in terms of `eq?`) object’s method. This allows scheme function style to be used for objects. The calling scheme for using a generic method is `(generic-method object param1 param2 ...)`.

METHOD

  A method is a procedure that exists in the object. To use a method get-method must be called to look-up the method. Generic methods implement the get-method functionality. Methods may be added to an object associated with any scheme obj in terms of eq?

GENERIC-PREDICATE

  A generic method that returns a boolean value for any scheme obj.

PREDICATE

  A object’s method asscociated with a generic-predicate. Returns `#t`.

#### 7.1.15 Procedures ¶

Function: make-object ancestor … ¶

  Returns an object. Current object implementation is a tagged vector. ancestors are optional and must be objects in terms of object?. ancestors methods are included in the object. Multiple ancestors might associate the same generic-method with a method. In this case the method of the ancestor first appearing in the list is the one returned by `get-method`.

Function: object? obj ¶

  Returns boolean value whether obj was created by make-object.

Function: make-generic-method exception-procedure ¶

  Returns a procedure which be associated with an object’s methods. If exception-procedure is specified then it is used to process non-objects.

Function: make-generic-predicate ¶

  Returns a boolean procedure for any scheme object.

Function: make-method! object generic-method method ¶

  Associates method to the generic-method in the object. The method overrides any previous association with the generic-method within the object. Using `unmake-method!` will restore the object’s previous association with the generic-method. method must be a procedure.

Function: make-predicate! object generic-preciate ¶

  Makes a predicate method associated with the generic-predicate.

Function: unmake-method! object generic-method ¶

  Removes an object’s association with a generic-method .

Function: get-method object generic-method ¶

  Returns the object’s method associated (if any) with the generic-method. If no associated method exists an error is flagged.

#### 7.1.16 Examples ¶

    (require 'object)

    (define instantiate (make-generic-method))

    (define (make-instance-object . ancestors)
      (define self (apply make-object
                          (map (lambda (obj) (instantiate obj)) ancestors)))
      (make-method! self instantiate (lambda (self) self))
      self)

    (define who (make-generic-method))
    (define imigrate! (make-generic-method))
    (define emigrate! (make-generic-method))
    (define describe (make-generic-method))
    (define name (make-generic-method))
    (define address (make-generic-method))
    (define members (make-generic-method))

    (define society
      (let ()
        (define self (make-instance-object))
        (define population '())
        (make-method! self imigrate!
                      (lambda (new-person)
                        (if (not (eq? new-person self))
                            (set! population (cons new-person population)))))
        (make-method! self emigrate!
                      (lambda (person)
                        (if (not (eq? person self))
                            (set! population
                                  (comlist:remove-if (lambda (member)
                                                       (eq? member person))
                                                     population)))))
        (make-method! self describe
                      (lambda (self)
                        (map (lambda (person) (describe person)) population)))
        (make-method! self who
                      (lambda (self) (map (lambda (person) (name person))
                                          population)))
        (make-method! self members (lambda (self) population))
        self))

    (define (make-person %name %address)
      (define self (make-instance-object society))
      (make-method! self name (lambda (self) %name))
      (make-method! self address (lambda (self) %address))
      (make-method! self who (lambda (self) (name self)))
      (make-method! self instantiate
                    (lambda (self)
                      (make-person (string-append (name self) "-son-of")
                                   %address)))
      (make-method! self describe
                    (lambda (self) (list (name self) (address self))))
      (imigrate! self)
      self)

#### 7.1.16.1 Inverter Documentation ¶

Inheritance:

            <inverter>::(<number> <description>)

Generic-methods

            <inverter>::value      ⇒ <number>::value
            <inverter>::set-value! ⇒ <number>::set-value!
            <inverter>::describe   ⇒ <description>::describe
            <inverter>::help
            <inverter>::invert
            <inverter>::inverter?

#### 7.1.16.2 Number Documention ¶

Inheritance

            <number>::()

Slots

            <number>::<x>

Generic Methods

            <number>::value
            <number>::set-value!

#### 7.1.16.3 Inverter code ¶

    (require 'object)

    (define value (make-generic-method (lambda (val) val)))
    (define set-value! (make-generic-method))
    (define invert (make-generic-method
                    (lambda (val)
                      (if (number? val)
                          (/ 1 val)
                          (error "Method not supported:" val)))))
    (define noop (make-generic-method))
    (define inverter? (make-generic-predicate))
    (define describe (make-generic-method))
    (define help (make-generic-method))

    (define (make-number x)
      (define self (make-object))
      (make-method! self value (lambda (this) x))
      (make-method! self set-value!
                    (lambda (this new-value) (set! x new-value)))
      self)

    (define (make-description str)
      (define self (make-object))
      (make-method! self describe (lambda (this) str))
      (make-method! self help (lambda (this) "Help not available"))
      self)

    (define (make-inverter)
      (let* ((self (make-object
                    (make-number 1)
                    (make-description "A number which can be inverted")))
             (<value> (get-method self value)))
        (make-method! self invert (lambda (self) (/ 1 (<value> self))))
        (make-predicate! self inverter?)
        (unmake-method! self help)
        (make-method! self help
                      (lambda (self)
                        (display "Inverter Methods:") (newline)
                        (display "  (value inverter) ==> n") (newline)))
        self))

    ;;;; Try it out

    (define invert! (make-generic-method))

    (define x (make-inverter))

    (make-method! x invert! (lambda (x) (set-value! x (/ 1 (value x)))))

    (value x)                       ⇒ 1
    (set-value! x 33)               ⇒ undefined
    (invert! x)                     ⇒ undefined
    (value x)                       ⇒ 1/33

    (unmake-method! x invert!)      ⇒ undefined

    (invert! x)                     error→  ERROR: Method not supported: x

#### 7.1.17 Priority Queues ¶

`(require 'priority-queue)`

This algorithm for priority queues is due to Introduction to Algorithms by T. Cormen, C. Leiserson, R. Rivest. 1989 MIT Press.

Function: make-heap pred<? ¶

  Returns a binary heap suitable which can be used for priority queue operations.

Function: heap-length heap ¶

  Returns the number of elements in heap.

Procedure: heap-insert! heap item ¶

  Inserts item into heap. item can be inserted multiple times. The value returned is unspecified.

Procedure: heap-extract-max! heap ¶

  Returns the item which is larger than all others according to the pred<? argument to `make-heap`. If there are no items in heap, an error is signaled.

#### 7.1.18 Queues ¶

`(require 'queue)`

A queue is a list where elements can be added to both the front and rear, and removed from the front (i.e., they are what are often called dequeues). A queue may also be used like a stack.

Function: make-queue ¶

  Returns a new, empty queue.

Function: queue? obj ¶

  Returns `#t` if obj is a queue.

Function: queue-empty? q ¶

  Returns `#t` if the queue q is empty.

Procedure: queue-push! q datum ¶

  Adds datum to the front of queue q.

Procedure: enqueue! q datum ¶

  Adds datum to the rear of queue q.

Procedure: dequeue! q ¶
Procedure: queue-pop! q ¶

  Both of these procedures remove and return the datum at the front of the queue. `queue-pop!` is used to suggest that the queue is being used like a stack.

All of the following functions raise an error if the queue q is empty.

Procedure: dequeue-all! q ¶

  Removes and returns (the list) of all contents of queue q.

Function: queue-front q ¶

  Returns the datum at the front of the queue q.

Function: queue-rear q ¶

  Returns the datum at the rear of the queue q.

#### 7.1.19 Records ¶

`(require 'record)`

The Record package provides a facility for user to define their own record data types.

Function: make-record-type type-name field-names ¶

  Returns a record-type descriptor, a value representing a new data type disjoint from all others. The type-name argument must be a string, but is only used for debugging purposes (such as the printed representation of a record of the new type). The field-names argument is a list of symbols naming the fields of a record of the new type. It is an error if the list contains any duplicates. It is unspecified how record-type descriptors are represented.

Function: record-constructor rtd [field-names] ¶

  Returns a procedure for constructing new members of the type represented by rtd. The returned procedure accepts exactly as many arguments as there are symbols in the given list, field-names; these are used, in order, as the initial values of those fields in a new record, which is returned by the constructor procedure. The values of any fields not named in that list are unspecified. The field-names argument defaults to the list of field names in the call to `make-record-type` that created the type represented by rtd; if the field-names argument is provided, it is an error if it contains any duplicates or any symbols not in the default list.

Function: record-predicate rtd ¶

  Returns a procedure for testing membership in the type represented by rtd. The returned procedure accepts exactly one argument and returns a true value if the argument is a member of the indicated record type; it returns a false value otherwise.

Function: record-accessor rtd field-name ¶

  Returns a procedure for reading the value of a particular field of a member of the type represented by rtd. The returned procedure accepts exactly one argument which must be a record of the appropriate type; it returns the current value of the field named by the symbol field-name in that record. The symbol field-name must be a member of the list of field-names in the call to `make-record-type` that created the type represented by rtd.

Function: record-modifier rtd field-name ¶

  Returns a procedure for writing the value of a particular field of a member of the type represented by rtd. The returned procedure accepts exactly two arguments: first, a record of the appropriate type, and second, an arbitrary Scheme value; it modifies the field named by the symbol field-name in that record to contain the given value. The returned value of the modifier procedure is unspecified. The symbol field-name must be a member of the list of field-names in the call to `make-record-type` that created the type represented by rtd.

In May of 1996, as a product of discussion on the `rrrs-authors` mailing list, I rewrote `record.scm` to portably implement type disjointness for record data types.

As long as an implementation’s procedures are opaque and the `record` code is loaded before other programs, this will give disjoint record types which are unforgeable and incorruptible by R4RS procedures.

As a consequence, the procedures `record?`, `record-type-descriptor`, `record-type-name`.and `record-type-field-names` are no longer supported.