Appendix A: STklos Libraries

This section describes the standard libraries provided by STklos.

A.1. The (scheme …​) libraries

STklos offers all the libraries defined by R7RS:

  • base

  • case-lambda

  • char

  • complex

  • cxr

  • eval

  • file

  • inexact

  • lazy

  • load

  • process-context

  • r5rs

  • read

  • repl

  • time

  • write

See the [R7RS] document for more information.

A.2. The (srfi …​) libraries

All the SRFI supported by STklos are placed under the srfi meta library and their name is SRFI number. Hence, to use the exported symbols of SRFI-1, you’ll have to import the (srfi 1) library.

See Chapter 14 for more information

A.3. The (stklos …​) libraries

This section describes the standard libraries which are placed under the stklos meta library. Note that STklos extensions can add some libraries in the stklos meta library; they will be described in the extension documentation.

A.3.1. (stklos itrie) library

This library was designed by Jerônimo Pellegrini (@jpellegrini).

Small description needed

The symbols exported by (stklos itrie) are described below:

STklos procedure

(alist→fxmapping alist) → fxmapping

Returns a newly allocated fxmapping containing the associations of alist. It is an error if the car of any pair in alist is not a fixnum. If an integer k appears as the key of multiple associations in alist (i.e. as the car of multiple pairs), then the first association for k is preferred.

(fxmapping->alist
  (alist->fxmapping '((1 . b) (0 . a) (2 . c))))
 => ((0 . a) (1 . b) (2 . c))

(fxmapping->alist
  (alist->fxmapping '((-10 . "yar") (-10 . "worf"))))
 => ((-10 . "yar"))

STklos procedure

(fxmapping k1 v1 k2 v2 …​ kn vn)
(constant-fxmapping k1 v1 k2 v2 …​ kn vn)

Builds a fixnum map containing the integer keys k1, k2, …​, kn with respective associated values v1, v2, …​ vn.

It is an error if any of the keys is not an integer, or if the number of arguments is not even.

STklos procedure

(iset n1 n2 …​ nk)
(constant-iset n1 n2 …​ nk)

Builds a fixnum set containing the fixnums n1, n2, …​, nk.

It is an error if any of the keys is not an integer.

STklos procedure

(fxmapping-adjoin fxmap k1 obj1 k2 …​)

Returns a fxmapping containing all of the associations of fxmap as well as the associations (k1, obj1), (k2, obj2), …​ The number of key/value arguments must be even.

If any of the keys already have associations in fxmap, the old associations are preserved.

(fxmapping->alist (fxmapping-adjoin (fxmapping 1 'b) 0 'a))
 => ((0 . a) (1 . b))

STklos procedure

(fxmapping-contains? map element)

Returns true if map contains an association for element, and false otherwise.

STklos procedure

(fxmapping-empty? obj)

Returns #t is obj is an empty fxmapping and #f if it is an fxmapping containing at least one key. If obj is not an fxmapping object, an error is sginaled.

STklos procedure

(fxmapping-height trie)

Returns the height of the internal trie of an fxmap. The expected running time of searches and insertions is proportional to this value.

STklos procedure

(fxmapping-keys fxmap)

Returns the keys of fxmap as a list in ascending numerical order.

(fxmapping-keys (fxmapping 137 'a -24 'b -5072 'c))
 => (-5072 -24 137)

STklos procedure

(fxmapping-mutable? obj)

Returns #t is obj is a mutable fxmapping and #f otherwise.

STklos procedure

(fxmapping-ref/default map k obj)

If an association (k, v) occurs in map, returns v. Otherwise, returns obj.

(fxmapping-ref/default (fxmapping 36864 'zap) 36864 #f) => zap
(fxmapping-ref/default (fxmapping 0 'a) 36864 #f) => #f

STklos procedure

(fxmapping-size trie)

Returns the number of key/value pairs in an fxmap.

STklos procedure

(fxmapping-values fxmap)

Returns the values of fxmap as a list in ascending numerical order of key. That is, if (k1, v1), …​, (kn, vn) are the associations of fxmap ordered so that k1 ⇐ … ⇐ kn, then (fxmapping-values fxmap) produces the list (v1 …​ vn).

(fxmapping-values (fxmapping 0 "picard" 1 "riker" 2 "troi"))
 => ("picard" "riker" "troi")

STklos procedure

(fxmapping-union fxmap1 fxmap2 fxmap3 …​)
(fxmapping-intersection fxmap1 fxmap2 fxmap3 …​)
(fxmapping-difference fxmap1 fxmap2 fxmap3 …​)
(fxmapping-xor fxmap1 fxmap2)

Return a fxmapping whose set of associations is the union, intersection, asymmetric difference, or symmetric difference of the sets of associations of the fxmaps. Asymmetric difference is extended to more than two fxmappings by taking the difference between the first fxmapping and the union of the others. Symmetric difference is not extended beyond two fxmappings. When comparing associations, only the keys are compared. In case of duplicate keys, associations in the result fxmapping are drawn from the first fxmapping in which they appear.

(fxmapping->alist (fxmapping-union (fxmapping 0 'a 2 'c)
                                  (fxmapping 1 'b 3 'd)))
   => ((0 . a) (1 . b) (2 . c) (3 . d))

 (fxmapping->alist
  (fxmapping-intersection (fxmapping 0 'a 2 'c)
                          (fxmapping 1 'b 2 'c 3 'd)
                          (fxmapping 2 'c 4 'e)))
    => ((2 . c))

(fxmapping->alist
 (fxmapping-difference (fxmapping 0 'a 1 'b 2 'c)
                       (fxmapping 2 "worf")
                       (fxmapping 1 "data")))
    => ((0 . a))

STklos procedure

(fxmapping? obj)

Returns #t is obj is an fxmapping object and #f otherwise.

STklos procedure

(iset=? iset1 iset2 iset3 …​)
(iset<? iset1 iset2 iset3 …​)
(iset>? iset1 iset2 iset3 …​)
(iset⇐? iset1 iset2 iset3 …​)
(iset>=? iset1 iset2 iset3 …​)

These procedures return true when each set is equal (iset=?) or a proper subset (iset<?), a proper superset (iset>?), a subset (iset⇐?) or a superset (iset>=?) of the next one.

(iset=? (iset 1 2 3) (iset 3 1 2))           => #t
(iset<? (iset 3 1 2) (iset 4 2 1 3))         => #t
(iset>=? (iset 3 0 1) (iset 0 1) (iset 0 1)) => #t

STklos procedure

(iset→list set)

Returns a newly allocated list containing the members of set in increasing numerical order.

(iset->list (iset 2 3 5 7 11)) => (2 3 5 7 11)

STklos procedure

(iset-adjoin set element1 element2 …​)
(iset-adjoin! set element1 element2 …​)

The iset-adjoin procedure returns a newly allocated iset that contains all the values of set, and in addition each element unless it is already equal to one of the existing or newly added members.

(iset->list (iset-adjoin (iset 1 3 5) 0)) => (0 1 3 5)

The iset-adjoin! procedure is the linear update version of iset-adjoin. In STklos, it is an alias to iset-adjoin.

STklos procedure

(iset-any? pred? set)

Returns true if at least one of the elements of set satisfies pred?. Note that this differs from the SRFI 1 analogue because it does not return an element of the iset.

(iset-any odd? (iset 10 2 -3 4))    => #t
(iset-any odd? (iset 10 2 -8 4 0))  => #f

STklos procedure

(iset-open-interval set low high)
(iset-closed-interval set low high)
(iset-open-closed-interval set low high)
(iset-closed-open-interval set low high)

Procedures that return a subset of set contained in the interval from low to high. The interval may be open, closed, open below and closed above, or open above and closed below.

(iset->list (iset-open-interval (iset 2 3 5 7 11) 2 7))        => (3 5)
(iset->list (iset-closed-interval (iset 2 3 5 7 11) 2 7))      => (2 3 5 7)
(iset->list (iset-open-closed-interval (iset 2 3 5 7 11) 2 7)) => (3 5 7)
(iset->list (iset-closed-open-interval (iset 2 3 5 7 11) 2 7)) => (2 3 5)

STklos procedure

(iset-contains? set element)

Returns true if set contains element, and false otherwise.

STklos procedure

(iset-copy set)

Returns a newly allocated iset containing the elements of set.

STklos procedure

(iset-count pred? set)

Returns the number of elements of set that satisfy pred? as an exact integer.

(iset-count odd? (iset 10 2 1 -3 9 4 3))  => 4

STklos procedure

(iset-delete set element1 element2 …​)
(iset-delete! set element1 element2 …​)
(iset-delete-all set element-list)
(iset-delete-all! set element-list)

The iset-delete procedure returns a newly allocated iset containing all the values of set except for any that are equal to one or more of the elements. Any element that is not equal to some member of the set is ignored.

The iset-delete! procedure is the same as iset-delete. is permitted to mutate and return the iset argument rather than allocating a new iset — but in STklos, it doesn’t.

The iset-delete-all and iset-delete-all! procedures are the same as iset-delete and iset-delete!, except that they accept a single argument which is a list of elements to be deleted.

(iset->list (iset-delete (iset 1 3 5) 3)) => (1 5)
(iset->list (iset-delete-all (iset 2 3 5 7 11)
                             '(3 4 5)))   => (2 7 11)

STklos procedure

(iset-delete-min set)
(iset-delete-min! set)
(iset-delete-max set)
(iset-delete-max! set)

Returns two values: the smallest/largest integer n in set and a newly-allocated iset that contains all elements of set except for n. It is an error if iset is empty.

The iset-delete-min! and iset-delete-max! procedures are the same as iset-delete-min and iset-delete-max, respectively, except that they are permitted to mutate and return the set argument instead of allocating a new iset. In STklos, they do not.

(let-values (((n set) (iset-delete-min (iset 2 3 5 7 11))))
  (list n (iset->list set)))
  => (2 (3 5 7 11))
(let-values (((n set) (iset-delete-max (iset 2 3 5 7 11))))
  (list n (iset->list set)))
  => (11 (2 3 5 7))

STklos procedure

(iset-disjoint? iset1 iset2)

Returns #t if iset1 and iset2 have no elements in common and #f otherwise.

(iset-disjoint? (iset 1 3 5) (iset 0 2 4)) => #t
(iset-disjoint? (iset 1 3 5) (iset 2 3 4)) => #f

STklos procedure

(iset-empty? obj)

Returns #t is obj is an empty iset and #f if it is an iset containing at least one key. If obj is not an iset object, an error is sginaled.

STklos procedure

(iset-every? predicate iset)

Returns #t if every element of set satisfies predicate, or #f otherwise. Note that this differs from the SRFI 1 analogue because it does not return an element of the iset.

(iset-every? (lambda (x) (< x 5)) (iset -2 -1 1 2)) => #t
(iset-every? positive? (iset -2 -1 1 2))            => #f

STklos procedure

(iset-filter predicate set)
(iset-filter! predicate set)

Returns a newly allocated iset containing just the elements of set that satisfy predicate.

(iset->list (iset-filter (lambda (x) (< x 6)) (iset 2 3 5 7 11)))
 => (2 3 5)

iset-filter! is allowed to modify set, but in STklos it does not.

STklos procedure

(iset-find predicate set failure)

Returns the smallest element of set that satisfies predicate, or the result of invoking failure with no arguments if there is none.

(iset-find positive? (iset -1 1) (lambda () #f))  => 1
(iset-find zero?     (iset -1 1) (lambda () #f))  => #f

STklos procedure

(iset-fold proc nil set)
(iset-fold-right proc nil set)

Invokes proc on each member of set in increasing/decreasing numerical order, passing the result of the previous invocation as a second argument. For the first invocation, nil is used as the second argument. Returns the result of the last invocation, or nil if there was no invocation.

(iset-fold + 0 (iset 2 3 5 7 11))            => 28
(iset-fold cons '() (iset 2 3 5 7 11))       => (11 7 5 3 2)
(iset-fold-right cons '() (iset 2 3 5 7 11)) => (2 3 5 7 11)

STklos procedure

(iset-for-each proc set)

Applies proc to set in increasing numerical order, discarding the returned values. Returns an unspecified result.

(let ((sum 0))
  (iset-for-each (lambda (x) (set! sum (+ sum x)))
                 (iset 2 3 5 7 11))
  sum)
=> 28

STklos procedure

(iset-height trie)

Returns the height of the internal trie of an iset. The expected running time of searches and insertions is proportional to this value.

STklos procedure

(iset-map proc set)

Applies proc to each element of set in arbitrary order and returns a newly allocated iset, created as if by iset, which contains the results of the applications. It is an error if proc returns a value that is not an exact integer.

(iset-map (lambda (x) (* 10 x)) (iset 1 11 21))
     => (iset 10 110 210)
(iset-map (lambda (x) (quotient x 2))
         (iset 1 2 3 4 5))
 => (iset 0 1 2)

STklos procedure

(iset-min set)
(iset-max set)

Returns the smallest or largest integer in set, or #f if there is none.

(iset-min (iset 2 3 5 7 11)) => 2
(iset-max (iset 2 3 5 7 11)) => 11
(iset-max (iset))            => #f

STklos procedure

(iset-member element set default)

Returns the element of set that is equal to element. If element is not a member of set, then default is returned.

STklos procedure

(iset-mutable? obj)

Returns #t is obj is a mutable iset and #f otherwise.

STklos procedure

(iset-partition predicate set)
(iset-partition! predicate set)

Returns two values: a newly allocated iset that contains just the elements of set that satisfy predicate and another newly allocated iset that contains just the elements of set that do not satisfy predicate.

(let-values (((low high) (iset-partition (lambda (x) (< x 6))
                                         (iset 2 3 5 7 11))))
  (list (iset->list low) (iset->list high)))
 => ((2 3 5) (7 11))

STklos procedure

(iset-remove predicate set)
(iset-remove! predicate set)

Returns a newly allocated set containing just the elements of set that do not satisfy predicate.

(iset->list (iset-remove (lambda (x) (< x 6)) (iset 2 3 5 7 11)))
 => (7 11)

Iset-remove! is allowed to modify set, but in STklos it does not.

STklos procedure

(iset-search set element failure success)
(iset-search! iset element failure success)

Set is searched from lowest to highest value for element. If it is not found, then the failure procedure is tail-called with two continuation arguments, insert and ignore, and is expected to tail-call one of them. If element is found, then the success procedure is tail-called with the matching element of set and two continuations, update and remove, and is expected to tail-call one of them.

The effects of the continuations are as follows (where obj is any Scheme object):

Invoking (insert obj) causes element to be inserted into iset.

Invoking (ignore obj) causes set to remain unchanged.

Invoking (update new-element obj) causes new-element to be inserted into set in place of element.

Invoking (remove obj) causes the matching element of set to be removed from it.

In all cases, two values are returned: an iset and obj.

The iset-search! procedure is the same as iset-search, except that it is permitted to mutate and return the iset argument rather than allocating a new iset. In STklos, it does not.

STklos procedure

(iset-size set)

Returns the number of fixnums in set.

STklos procedure

(iset-unfold stop? mapper successor seed)

Create a newly allocated iset as if by iset. If the result of applying the predicate stop? to seed is true, return the iset. Otherwise, apply the procedure mapper to seed. The value that mapper returns is added to the iset. Then get a new seed by applying the procedure successor to seed, and repeat this algorithm.

(iset->list (iset-unfold (lambda (n) (> n 64))
                         values
                         (lambda (n) (* n 2))
                         2))
=> (2 4 8 16 32 64)

STklos procedure

(iset-union iset1 iset2 iset3 …​)
(iset-intersection iset1 iset2 iset3 …​)
(iset-difference iset1 iset2 iset3 …​)
(iset-xor iset1 iset2)
(iset-union! iset1 iset2 iset3 …​)
(iset-intersection! iset1 iset2 iset3 …​)
(iset-difference! iset1 iset2 iset3 …​)
(iset-xor! iset1 iset2)

Return a newly allocated iset that is the union, intersection, asymmetric difference, or symmetric difference of the isets. Asymmetric difference is extended to more than two isets by taking the difference between the first iset and the union of the others. Symmetric difference is not extended beyond two isets. Elements in the result iset are drawn from the first iset in which they appear.

(iset->list (iset-union (iset 0 1 3) (iset 0 2 4))) => (0 1 2 3 4)
(iset->list (iset-intersection (iset 0 1 3 4) (iset 0 2 4))) => (0 4)
(iset->list (iset-difference (iset 0 1 3 4) (iset 0 2) (iset 0 4))) => (1 3)
(iset->list (iset-xor (iset 0 1 3) (iset 0 2 4))) => (1 2 3 4)

The procedures whose name end in ! are linear update procedures. The specification says they may or may not alter their argument. In STklos they do not: in fact, they are aliases to the pure functional versions.

STklos procedure

(iset? obj)

Returns #t is obj is an iset and #f otherwise.

STklos procedure

(isubset= set k)
(isubset< set k)
(isubset⇐ set k)
(isubset> set k)
(isubset>= set k)

Procedures that return an integer set containing the elements of set that are equal to, less than, less than or equal to, greater than, or greater than or equal to k. Note that the result of isubset= contains at most one element.

(iset->list (isubset= (iset 2 3 5 7 11) 7))  => (7)
(iset->list (isubset< (iset 2 3 5 7 11) 7))  => (2 3 5)
(iset->list (isubset>= (iset 2 3 5 7 11) 7)) => (7 11)

STklos procedure

(list→iset list)
(list→iset! set list)

Returns a newly allocated iset, created as if by iset, that contains the elements of list. Duplicate elements are omitted.

(list->iset '(-3 -1 0 2)) = (iset -3 -1 0 2)

list→iset! may mutate set rather than allocating a new iset, but in STklos it does not.

(iset->list (list->iset! (iset 2 3 5) '(-3 -1 0)))  (-3 -1 0 2 3 5)

STklos procedure

(make-range-iset start end [step])

Returns a newly allocated iset specified by an inclusive lower bound start, an exclusive upper bound `e`nd, and a step value (default 1), all of which are exact integers. This constructor produces an iset containing the sequence

start, (+ start step), (+ start (* 2 step)), …​, (+ start (* n step)),

where n is the greatest integer such that (+ start (* n step)) < end if step is positive, or such that (+ start (* n step)) > end if step is negative. It is an error if step is zero.

(iset->list (make-range-iset 25 30))    => (25 26 27 28 29)
(iset->list (make-range-iset -10 10 6)) => (-10 -4 2 8)

A.3.2. (stklos preproc) library

This library must be described

1. Documentation about hygienic macros has been stolen in the SLIB manual
1. In fact define-module on a given name defines a new module only the first time it is invoked on this name. By this way, interactively reloading a module does not define a new entity, and the other modules which use it are not altered.
2. This transcript uses the default toplevel loop which displays the name of the current module in the evaluator prompt.
1. Under Unix, you can simply connect to a listening socket with the telnet of netcat command. For the given example, this can be achieved with netcat localhost 12345
2. Port 13, if open, can used for testing: making a connection to it permits to know the distant system’s idea of the time of day.
1. This section is an adaptation of Jeff Dalton’s (J.Dalton@ed.ac.uk) "Brief introduction to CLOS" which can be found at http://www.aiai.ed.ac.uk/~jeff/clos-guide.html