suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve documentation for hash update functions

Browse Source 
Changes the prose explanations of `hash-update` and `hash-update!` to more explicitly describe how the hash table is updated, instead of just deferring to the explanations in `hash-ref` and `hash-set` / `hash-set!`. Additionally, adds example code.
This commit is contained in:
Jack Firth 2021-05-02 15:13:08 -07:00 committed by Sam Tobin-Hochstadt
parent d777cd28d7
commit 59100868e0
1 changed files with 52 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
pkgs/racket-doc/scribblings/reference/hashes.scrbl
View File

@ -411,33 +411,69 @@ Returns @racket[#t] if @racket[hash] contains a value for the given
[key any/c]
[updater (any/c . -> . any/c)]
[failure-result failure-result/c
(lambda ()
(raise (make-exn:fail:contract ....)))])
(lambda ()
(raise (make-exn:fail:contract ....)))])
void?]{
Composes @racket[hash-ref] and @racket[hash-set!] to update an
existing mapping in @racket[hash], where the optional
@racket[failure-result] argument is used as in @racket[hash-ref] when
no mapping exists for @racket[key] already. See the caveat above about
concurrent updates.
Updates the value mapped by @racket[key] in @racket[hash] by applying @racket[updater] to the value.
The value returned by @racket[updater] becomes the new mapping for @racket[key], overwriting the
original value in @racket[hash].
@see-also-caveats[]}
@(examples
#:eval the-eval
(eval:no-prompt
(define h (make-hash))
(hash-set! h 'a 5))
(hash-update! h 'a add1)
h)
The optional @racket[failure-result] argument is used when no mapping exists for @racket[key]
already, in the same manner as in @racket[hash-ref].
@(examples
#:eval the-eval
(eval:no-prompt
(define h (make-hash)))
(eval:error (hash-update! h 'b add1))
(hash-update! h 'b add1 0)
h)
@see-also-caveats[]}
@defproc[(hash-update [hash (and/c hash? immutable?)]
[key any/c]
[updater (any/c . -> . any/c)]
[failure-result failure-result/c
(lambda ()
(raise (make-exn:fail:contract ....)))])
(and/c hash? immutable?)]{
(lambda ()
(raise (make-exn:fail:contract ....)))])
(and/c hash? immutable?)]{
Composes @racket[hash-ref] and @racket[hash-set] to functionally
update an existing mapping in @racket[hash], where the optional
@racket[failure-result] argument is used as in @racket[hash-ref] when
no mapping exists for @racket[key] already.
Functionally updates the value mapped by @racket[key] in @racket[hash] by applying @racket[updater]
to the value and returning a new hash table. The value returned by @racket[updater] becomes the new
mapping for @racket[key] in the returned hash table.
@see-also-mutable-key-caveat[]}
@(examples
#:eval the-eval
(eval:no-prompt
(define h (hash 'a 5)))
(hash-update h 'a add1))
The optional @racket[failure-result] argument is used when no mapping exists for @racket[key]
already, in the same manner as in @racket[hash-ref].
@(examples
#:eval the-eval
(eval:no-prompt
(define h (hash)))
(eval:error (hash-update h 'b add1))
(hash-update h 'b add1 0))
@see-also-mutable-key-caveat[]}
@defproc[(hash-remove! [hash (and/c hash? (not/c immutable?))]