---

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.