chickadee » integer-map » fxmapping-alter

failure is a procedure of type (* → fxmapping) ([] → fxmapping) → * …. success is a procedure of type fixnum * (* → fxmapping) ([] → fxmapping) → * ….

Updates the association, or lack thereof, for k in fxmap as follows. If the association (k, v) exists in fxmap, then success is invoked in tail context on k, v, and two procedure arguments, replace and delete, and its values are returned.

• Invoking (replace v′) returns a fxmapping with the association (k, v′) as well as all of fxmap's other associations.
• Invoking (delete) returns a fxmapping with all of fxmap's associations except for (k, v).

If no association for k exists in fxmap, then failure is invoked in tail context on two procedure arguments, insert and ignore, and its values are returned.

• Invoking (insert u) returns a fxmapping with all of the associations of fxmap as well as (k, u).
• Invoking (ignore) returns a fxmapping with the same associations as fxmap.

Note that, in contrast to similar Scheme forms, failure and success are not required to tail-call one of their procedure arguments, and that fxmapping-alter simply returns the results of invoking failure or success. Thus, the following is valid:

;; Returns an additional boolean value indicating
;; whether the fxmapping was updated.
(fxmapping-alter (fxmapping 0 'a 1 'b 2 'c)
                 1
                 (lambda (_ins ignore)
                   (values (ignore) #f))
                 (lambda (_k _v replace _del)
                   (values (replace 'z) #t)))
 ⇒ <fxmapping>
   #t

Examples:

;; Insert an association for 4 if it's not present.
(fxmapping->alist
 (fxmapping-alter (fxmapping 0 'a 1 'b)
                  4
                  (lambda (insert _ig) (insert 'e))
                  (lambda (_k v replace _del)
                    (replace v))))  ; keep original value
 ⇒ ((0 . a) (1 . b) (4 . e))
   #t

;; Delete an association for 1 if its value is a symbol.
(fxmapping->alist
 (fxmapping-alter (fxmapping 0 'a 1 'b)
                  1
                  (lambda (_ins ignore) (ignore))
                  (lambda (_k v replace delete)
                    (if (symbol? v)
                        (delete)
                        (replace v)))))
 ⇒ ((0 . a))