#lang scribble/doc
@(require "common.ss"
          (for-label syntax/id-table)
          (for-label scheme/dict))

@title[#:tag "idtable"]{Identifier dictionaries}

@defmodule[syntax/id-table]

This module provides functionality like that of
@schememodname[syntax/boundmap] but with more operations, standard
names, implementation of the @schememodname[scheme/dict] interface,
and immutable (functionally-updating) variants.

@section{Dictionaries for @scheme[bound-identifier=?]}

Bound-identifier tables implement the dictionary interface of
@scheme[scheme/dict]. Consequently, all of the appropriate generic
functions (@scheme[dict-ref], @scheme[dict-map], etc) can be used on
free-identifier tables.

@deftogether[[
@defproc[(make-bound-id-table [init-dict dict? null]) 
         mutable-bound-id-table?]
@defproc[(make-immutable-bound-id-table [init-dict dict? null])
         immutable-bound-id-table?]]]{

Produces a dictionary mapping syntax identifiers to arbitrary
values. The mapping uses @scheme[bound-identifier=?] to compare keys,
but also uses a hash table based on symbol equality to make the
mapping efficient in the common case. The two procedures produce
mutable and immutable dictionaries, respectively.

The optional @scheme[init-dict] argument provides the initial
mappings. It must be a dictionary, and its keys must all be
identifiers. If the @scheme[init-dict] dictionary has multiple
distinct entries whose keys are @scheme[bound-identifier=?], only one
of the entries appears in the new id-table, and it is not specified
which entry is picked.
}

@defproc[(bound-id-table? [v any/c]) boolean?]{

Returns @scheme[#t] if @scheme[v] was produced by
@scheme[make-bound-id-table] or
@scheme[make-immutable-bound-id-table], @scheme[#f] otherwise.
}

@deftogether[[
@defproc[(mutable-bound-id-table? [v any/c]) boolean?]
@defproc[(immutable-bound-id-table? [v any/c]) boolean?]
]]{

Predicate for the mutable and immutable variants of bound-identifier
tables, respectively.
}

@defproc[(bound-id-table-ref [table bound-id-table?]
                             [id identifier?]
                             [failure any/c
                              (lambda () (raise (make-exn:fail .....)))])
         any]{

Like @scheme[hash-ref] for bound identifier tables. In particular, if
@scheme[id] is not found, the @scheme[failure] argument is applied if
it is a procedure, or simply returned otherwise.
}

@defproc[(bound-id-table-set! [table mutable-bound-id-table?]
                              [id identifier?]
                              [v any/c])
         void?]{

Like @scheme[hash-set!] for mutable bound-identifier tables.
}

@defproc[(bound-id-table-set [table immutable-bound-id-table?]
                             [id identifier?]
                             [v any/c])
         immutable-bound-id-table?]{

Like @scheme[hash-set] for immutable bound-identifier tables.
}

@defproc[(bound-id-table-remove! [table mutable-bound-id-table?]
                              [id identifier?])
         void?]{

Like @scheme[hash-remove!] for mutable bound-identifier tables.
}

@defproc[(bound-id-table-remove [table immutable-bound-id-table?]
                             [id identifier?]
                             [v any/c])
         immutable-bound-id-table?]{

Like @scheme[hash-remove] for immutable bound-identifier tables.
}

@defproc[(bound-id-table-map [table bound-id-table?]
                             [proc (-> identifier? any/c any)])
         list?]{

Like @scheme[hash-map] for bound-identifier tables.
}

@defproc[(bound-id-table-for-each [table bound-id-table?]
                                  [proc (-> identifier? any/c any)])
         void?]{

Like @scheme[hash-for-each] for bound-identifier tables.
}

@defproc[(bound-id-table-count [table bound-id-table?])
         exact-nonnegative-integer?]{

Like @scheme[hash-count] for bound-identifier tables.

}

@;{
@deftogether[[
@defproc[(bound-id-table-iterate-first [table bound-id-table?])
         id-table-position?]
@defproc[(bound-id-table-iterate-next [table bound-id-table?]
                                      [position id-table-position?])
         id-table-position?]
@defproc[(bound-id-table-iterate-key [table bound-id-table?]
                                     [position id-table-position?])
         identifier?]
@defproc[(bound-id-table-iterate-value [table bound-it-table?]
                                       [position id-table-position?])
         identifier?]]]{

Like the corresponding dictionary procedures from
@schememodname[scheme/dict] for for bound-identifier tables.
}
}

@;{----------}
@section{Dictionaries for @scheme[free-identifier=?]}

Free-identifier tables implement the dictionary interface of
@scheme[scheme/dict]. Consequently, all of the appropriate generic
functions (@scheme[dict-ref], @scheme[dict-map], etc) can be used on
free-identifier tables.

@deftogether[[
@defproc[(make-free-id-table [init-dict dict? null])
         mutable-free-id-table?]
@defproc[(make-immutable-free-id-table [init-dict dict? null])
         immutable-free-id-table?]
@defproc[(free-id-table? [v any/c]) boolean?]
@defproc[(mutable-free-id-table? [v any/c]) boolean?]
@defproc[(immutable-free-id-table? [v any/c]) boolean?]
@defproc[(free-id-table-ref [table free-id-table?]
                             [id identifier?]
                             [failure any/c
                              (lambda () (raise (make-exn:fail .....)))])
         any]
@defproc[(free-id-table-set! [table mutable-free-id-table?]
                              [id identifier?]
                              [v any/c])
         void?]
@defproc[(free-id-table-set [table immutable-free-id-table?]
                             [id identifier?]
                             [v any/c])
         immutable-free-id-table?]
@defproc[(free-id-table-remove! [table mutable-free-id-table?]
                              [id identifier?])
         void?]
@defproc[(free-id-table-remove [table immutable-free-id-table?]
                             [id identifier?]
                             [v any/c])
         immutable-free-id-table?]
@defproc[(free-id-table-map [table free-id-table?]
                             [proc (-> identifier? any/c any)])
         list?]
@defproc[(free-id-table-for-each [table free-id-table?]
                                  [proc (-> identifier? any/c any)])
         void?]
@defproc[(free-id-table-count [table free-id-table?])
         exact-nonnegative-integer?]
@;{
@defproc[(free-id-table-iterate-first [table free-id-table?])
         id-table-position?]
@defproc[(free-id-table-iterate-next [table free-id-table?]
                                      [position id-table-position?])
         id-table-position?]
@defproc[(free-id-table-iterate-key [table free-id-table?]
                                     [position id-table-position?])
         identifier?]
@defproc[(free-id-table-iterate-value [table free-it-table?]
                                       [position id-table-position?])
         identifier?]
}]]{

Like the procedures for bound-identifier tables
(@scheme[make-bound-id-table], @scheme[bound-id-table-ref], etc), but
for free-identifier tables, which use @scheme[free-identifier=?] to
compare keys.
}