Amap constructors (MIT/GNU Scheme 11.2)

Next: Amap predicates, Previous: Associative Maps, Up: Associative Maps [Contents][Index]

#### 11.8.1 Amap constructors

All associative-map constructors take a comparator argument followed by a list of additional specification arguments. In all cases, the comparator is used to compare keys in the map, while the additional arguments specify the implementation and/or features of the map being created.

procedure: make-amap comparator arg …

  Creates a new mutable associative map as specified by comparator and args.

procedure: alist->amap alist comparator arg …

  Creates a new associative map as specified by comparator and args, and which contains the associations in alist.

procedure: amap-unfold stop? mapper successor seed comparator arg …

  Creates a new associative map as specified by comparator and args. The associations in the resulting map are generated using the additional arguments.

  The stop? argument is a unary predicate that takes a state value and returns `#t` if generation is complete, otherwise `#f`. The mapper argument is a unary procedure that takes a state value and returns two values: a key and a value. The successor argument is a unary procedure that takes a state value and returns a new state value. And seed is the initial state value.

  The process by which the generator adds associations to the map is this:

      (let loop ((state seed))
        (if (stop? state)
            result
            (let-values (((key value) (mapper state)))
              (amap-set! result key value)
              (loop (successor state)))))

The arguments passed to a constructor can be divided into categories:

- Each backing implementation has an associated name, which can be passed as one of the arguments. At present this includes `alist`, `hash-table`, `red/black-tree`, etc.

  There must be at most one such name; it is an error to pass two or more implementation names. If an implementation name is given, then the remaining arguments must be supported by that implementation.

- The arguments `weak-keys`, `weak-values`, `ephemeral-keys`, and `ephemeral-values` specify how associations interact with garbage collection. Not all implementations support these arguments, and those that do may support only some of them. Some combinations are not allowed: for example, `weak-keys` and `ephemeral-keys` are mutually exclusive.
- Additional arguments are used to guide the choice of implementation when it is not explicitly specified. The desired time complexity can be specified: `linear-time`, `log-time`, `amortized-constant-time`, and `sublinear-time`. The argument `ordered-by-key` specifies that the map keeps its associations ordered.
- The argument `thread-safe` specifies that the implementation is safe to use in a multi-threaded environment. At present none of the implementations are thread-safe.
- Finally, an exact non-negative integer argument specifies the initial size of the map.

This is a complex set of possible arguments. In order to help explore what arguments can be used, and in what combinations, we provide some utility procedures:

procedure: amap-implementation-names

  Returns a list of the supported implementation names.

procedure: amap-implementation-supported-args name

  Returns a list of the arguments supported by the implementation specified by name. This list can include the procedure `exact-nonnegative-integer?` if the implementation supports an initial size.

procedure: amap-implementation-supports-args? name args

  Returns `#t` if the implementation specified by name supports args, otherwise returns `#f`.

An implementation may support a limited set of comparators. For example, a hash table requires a comparator that satisfies `comparator-hashable?`, while a binary tree requires one satisfying `comparator-ordered?`.

procedure: amap-implementation-supports-comparator? name comparator

  Returns `#t` if the implementation specified by name supports comparator, otherwise returns `#f`.

Next: Amap predicates, Previous: Associative Maps, Up: Associative Maps [Contents][Index]