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

edit docs for gen:set methods

Browse Source 
- classify methods into 3 categories:
  - no fallbacks
  - fallbacks that require an "implementation" of another method,
    ie not another fallback
  - fallbacks that require "support" of another method
    --- can be another fallback
This commit is contained in:
Stephen Chang 2013-08-05 19:21:19 -04:00 committed by Carl Eastlund
parent a496cb5a17
commit 766761f6b4
1 changed files with 61 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
pkgs/racket-pkgs/racket-doc/scribblings/reference/sets.scrbl
View File

@ -225,7 +225,7 @@ A @tech{generic interface} (see @secref["struct-generics"]) that
supplies set method implementations for a structure type via the supplies set method implementations for a structure type via the
@racket[#:methods] option of @racket[struct] definitions. This interface can @racket[#:methods] option of @racket[struct] definitions. This interface can
be used to implement any of the methods documented as be used to implement any of the methods documented as
@secref["primitive-set-methods"] and @secref["derived-set-methods"]. @secref["set-methods"].
@examples[ @examples[
#:eval set-eval #:eval set-eval
@ -252,58 +252,71 @@ bset
} }
@subsection[#:tag "primitive-set-methods"]{Primitive Set Methods} @subsection[#:tag "set-methods"]{Set Methods}
These methods of @racket[gen:set] have no fallback implementations; they are The methods of @racket[gen:set] can be classified into three categories, as determined by their fallback implementations:
only supported for set types that directly implement them.
@itemlist[#:style 'ordered
@item{methods with no fallbacks,}
@item{methods whose fallbacks depend on other, non-fallback methods,}
@item{and methods whose fallbacks can depend on either fallback or non-fallback methods.}]
In the method descriptions below, if a fallback requires a non-fallback method of a set, we say that the set must @deftech{implement} that method. If a fallback can use another fallback method, then we say that the set has to @deftech{support} that method.
As an example, implementing the following methods would guarantee that all the methods in @racket[gen:set] would at least have a fallback method:
@itemlist[@item{@racket[set-member]}
@item{@racket[set-add]}
@item{@racket[set-add!]}
@item{@racket[set-remove]}
@item{@racket[set-remove!]}
@item{@racket[set-first]}
@item{@racket[set-empty?]}]
There may be other such subsets of methods that would guarantee at least a fallback for every method.
@defproc[(set-member? [st set?] [v any/c]) boolean?]{ @defproc[(set-member? [st set?] [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is in @racket[st], @racket[#f] Returns @racket[#t] if @racket[v] is in @racket[st], @racket[#f]
otherwise. otherwise. Has no fallback.
} }
@defproc[(set-add [st set?] [v any/c]) set?]{ @defproc[(set-add [st set?] [v any/c]) set?]{
Produces a set that includes @racket[v] plus all elements of Produces a set that includes @racket[v] plus all elements of
@racket[st]. This operation runs in constant time for @tech{hash sets}. @racket[st]. This operation runs in constant time for @tech{hash sets}. Has no fallback.
} }
@defproc[(set-add! [st set?] [v any/c]) void?]{ @defproc[(set-add! [st set?] [v any/c]) void?]{
Adds the element @racket[v] to @racket[st]. This operation runs in constant Adds the element @racket[v] to @racket[st]. This operation runs in constant
time for @tech{hash sets}. time for @tech{hash sets}. Has no fallback.
} }
@defproc[(set-remove [st set?] [v any/c]) set?]{ @defproc[(set-remove [st set?] [v any/c]) set?]{
Produces a set that includes all elements of @racket[st] except Produces a set that includes all elements of @racket[st] except
@racket[v]. This operation runs in constant time for @tech{hash sets}. @racket[v]. This operation runs in constant time for @tech{hash sets}. Has no fallback.
} }
@defproc[(set-remove! [st set?] [v any/c]) void?]{ @defproc[(set-remove! [st set?] [v any/c]) void?]{
Adds the element @racket[v] to @racket[st]. This operation runs in constant Adds the element @racket[v] to @racket[st]. This operation runs in constant
time for @tech{hash sets}. time for @tech{hash sets}. Has no fallback.
} }
@subsection[#:tag "derived-set-methods"]{Derived Set Methods}
These methods of @racket[gen:set] have fallback implementations in terms of
the other methods; they may be supported even by set types that do not
directly implement them.
@defproc[(set-empty? [st set?]) boolean?]{ @defproc[(set-empty? [st set?]) boolean?]{
Returns @racket[#t] if @racket[st] has no members; returns @racket[#f] Returns @racket[#t] if @racket[st] has no members; returns @racket[#f]
otherwise. otherwise.
Supported for any @racket[st] that implements @racket[set->stream] or Supported for any @racket[st] that @tech{implements} @racket[set->stream] or
@racket[set-count]. @racket[set-count].
} }
@ -312,7 +325,7 @@ Supported for any @racket[st] that implements @racket[set->stream] or
Returns the number of elements in @racket[st]. Returns the number of elements in @racket[st].
Supported for any @racket[st] that supports @racket[set->stream]. Supported for any @racket[st] that @tech{supports} @racket[set->stream].
} }
@ -321,7 +334,7 @@ Supported for any @racket[st] that supports @racket[set->stream].
Produces an unspecified element of @racket[st]. Multiple uses of Produces an unspecified element of @racket[st]. Multiple uses of
@racket[set-first] on @racket[st] produce the same result. @racket[set-first] on @racket[st] produce the same result.
Supported for any @racket[st] that implements @racket[set->stream]. Supported for any @racket[st] that @tech{implements} @racket[set->stream].
} }
@ -331,7 +344,7 @@ Supported for any @racket[st] that implements @racket[set->stream].
Produces a set that includes all elements of @racket[st] except Produces a set that includes all elements of @racket[st] except
@racket[(set-first st)]. @racket[(set-first st)].
Supported for any @racket[st] that implements @racket[set-remove] and either Supported for any @racket[st] that @tech{implements} @racket[set-remove] and either
@racket[set-first] or @racket[set->stream]. @racket[set-first] or @racket[set->stream].
} }
@ -340,10 +353,13 @@ Supported for any @racket[st] that implements @racket[set-remove] and either
Produces a stream containing the elements of @racket[st]. Produces a stream containing the elements of @racket[st].
Supported for any @racket[st] that implements @racket[set->list], or Supported for any @racket[st] that @tech{implements}:
@racket[set-empty?], @racket[set-first], and either @racket[set-rest] or @itemlist[@item{@racket[set->list]}
@racket[set-remove]. @item{@racket[in-set]}
@item{@racket[set-empty?], @racket[set-first], @racket[set-rest]}
@item{@racket[set-empty?], @racket[set-first], @racket[set-remove]}
@item{@racket[set-count], @racket[set-first], @racket[set-rest]}
@item{@racket[set-count], @racket[set-first], @racket[set-remove]}]
} }
@defproc[(set-copy [st set?]) set?]{ @defproc[(set-copy [st set?]) set?]{
@ -351,8 +367,8 @@ Supported for any @racket[st] that implements @racket[set->list], or
Produces a new, mutable set of the same type and with the same elements as Produces a new, mutable set of the same type and with the same elements as
@racket[st]. @racket[st].
Supported for any @racket[st] that implements @racket[set-clear] and Supported for any @racket[st] that @tech{implements} @racket[set-clear] and
@racket[set-add!]. @racket[set-add!], and @tech{supports} @racket[set->stream].
} }
@ -361,7 +377,7 @@ Supported for any @racket[st] that implements @racket[set-clear] and
Produces a new, empty set of the same type, mutability, and key strength as Produces a new, empty set of the same type, mutability, and key strength as
@racket[st]. @racket[st].
Supported for any @racket[st] that implements @racket[set-remove] and supports Supported for any @racket[st] that @tech{implements} @racket[set-remove] and @tech{supports}
@racket[set->stream]. @racket[set->stream].
} }
@ -370,9 +386,8 @@ Supported for any @racket[st] that implements @racket[set-remove] and supports
Removes all elements from @racket[st]. Removes all elements from @racket[st].
Supported for any @racket[st] that implements @racket[set-remove] and either Supported for any @racket[st] that @tech{implements} @racket[set-remove] and either
supports @racket[set->stream] or implements @racket[set-count] and @tech{supports} @racket[set->stream] or @tech{implements} @racket[set-first] and either @racket[set-count] or @racket[set-empty?].
@racket[set-first].
} }
@ -396,7 +411,7 @@ of the resulting set (list, hash set, etc.). If there is a case where
@racket[set-union] may be applied to zero arguments, instead pass an empty set @racket[set-union] may be applied to zero arguments, instead pass an empty set
of the intended type as the first argument. of the intended type as the first argument.
Supported for any @racket[st] that implements @racket[set-add]. Supported for any @racket[st] that @tech{implements} @racket[set-add] and @tech{supports} @racket[set->stream].
@examples[#:eval set-eval @examples[#:eval set-eval
(set-union (set)) (set-union (set))
@ -416,7 +431,7 @@ If @racket[st0] is a @tech{hash set}, each @racket[st] must also be a
sets may differ. This operation runs on hash sets in time proportional to the sets may differ. This operation runs on hash sets in time proportional to the
total size of the @racket[st]s. total size of the @racket[st]s.
Supported for any @racket[st] that implements @racket[set-add!]. Supported for any @racket[st] that @tech{implements} @racket[set-add!] and @tech{supports} @racket[set->stream].
} }
@ -435,8 +450,8 @@ If @racket[st0] is a @tech{hash set}, each @racket[st] must also be a
sets may differ. This operation runs on hash sets in time proportional to the sets may differ. This operation runs on hash sets in time proportional to the
size of the smallest immutable set. size of the smallest immutable set.
Supported for any @racket[st] that implements either @racket[set-remove] or Supported for any @racket[st] that @tech{implements} either @racket[set-remove] or
both @racket[set-clear] and @racket[set-add]. both @racket[set-clear] and @racket[set-add], and @tech{supports} @racket[set->stream].
} }
@ -451,7 +466,7 @@ If @racket[st0] is a @tech{hash set}, each @racket[st] must also be a
sets may differ. This operation runs on hash sets in time proportional to the sets may differ. This operation runs on hash sets in time proportional to the
size of @racket[st0]. size of @racket[st0].
Supported for any @racket[st] that implements @racket[set-remove!]. Supported for any @racket[st] that @tech{implements} @racket[set-remove!] and @tech{supports} @racket[set->stream].
} }
@ -470,8 +485,8 @@ If @racket[st0] is a @tech{hash set}, each @racket[st] must also be a
sets may differ. This operation runs on hash sets in time proportional to the sets may differ. This operation runs on hash sets in time proportional to the
size of @racket[st0]. size of @racket[st0].
Supported for any @racket[st] that implements either @racket[set-remove] or Supported for any @racket[st] that @tech{implements} either @racket[set-remove] or
both @racket[set-clear] and @racket[set-add]. both @racket[set-clear] and @racket[set-add], and @tech{supports} @racket[set->stream].
} }
@ -486,7 +501,7 @@ If @racket[st0] is a @tech{hash set}, each @racket[st] must also be a
sets may differ. This operation runs on hash sets in time proportional to the sets may differ. This operation runs on hash sets in time proportional to the
size of @racket[st0]. size of @racket[st0].
Supported for any @racket[st] that implements @racket[set-remove!]. Supported for any @racket[st] that @tech{implements} @racket[set-remove!] and @tech{supports} @racket[set->stream].
} }
@ -506,8 +521,7 @@ If @racket[st0] is a @tech{hash set}, each @racket[st] must also be a
sets may differ. This operation runs on hash sets in time proportional to the sets may differ. This operation runs on hash sets in time proportional to the
total size of all of the sets except the largest immutable set. total size of all of the sets except the largest immutable set.
Supported for any @racket[st] that implements @racket[set-member?] and either Supported for any @racket[st] that @tech{implements} @racket[set-remove] or both @racket[set-clear] and @racket[set-add], and @tech{supports} @racket[set->stream].
@racket[set-remove] or both @racket[set-clear] and @racket[set-add].
@examples[#:eval set-eval @examples[#:eval set-eval
(set-symmetric-difference (set 1) (set 1 2) (set 1 2 3)) (set-symmetric-difference (set 1) (set 1 2) (set 1 2 3))
@ -527,7 +541,7 @@ If @racket[st0] is a @tech{hash set}, each @racket[st] must also be a
sets may differ. This operation runs on hash sets in time proportional to the sets may differ. This operation runs on hash sets in time proportional to the
total size of the @racket[st]s. total size of the @racket[st]s.
Supported for any @racket[st] that implements @racket[set-remove!]. Supported for any @racket[st] that @tech{implements} @racket[set-remove!] and @tech{supports} @racket[set->stream].
} }
@ -546,8 +560,8 @@ If @racket[st0] is a @tech{hash set}, each @racket[st] must also be a
sets may differ. This operation runs on hash sets in time proportional to the sets may differ. This operation runs on hash sets in time proportional to the
size of @racket[st] plus the size of @racket[st2]. size of @racket[st] plus the size of @racket[st2].
Supported for any @racket[st] and @racket[st2] that both support Supported for any @racket[st] and @racket[st2] that both @tech{support}
@racket[subset?]; also supported for any if @racket[st2] that implements @racket[subset?]; also supported for any if @racket[st2] that @tech{implements}
@racket[set=?] regardless of @racket[st]. @racket[set=?] regardless of @racket[st].
@examples[#:eval set-eval @examples[#:eval set-eval
@ -577,7 +591,7 @@ If @racket[st0] is a @tech{hash set}, each @racket[st] must also be a
sets may differ. This operation runs on hash sets in time proportional to the sets may differ. This operation runs on hash sets in time proportional to the
size of @racket[st]. size of @racket[st].
Supported for any @racket[st] that supports @racket[set->stream]. Supported for any @racket[st] that @tech{supports} @racket[set->stream].
@examples[#:eval set-eval @examples[#:eval set-eval
(subset? (set 1) (set 1 2 3)) (subset? (set 1) (set 1 2 3))
@ -602,7 +616,7 @@ If @racket[st0] is a @tech{hash set}, each @racket[st] must also be a
sets may differ. This operation runs on hash sets in time proportional to the sets may differ. This operation runs on hash sets in time proportional to the
size of @racket[st] plus the size of @racket[st2]. size of @racket[st] plus the size of @racket[st2].
Supported for any @racket[st] and @racket[st2] that both support Supported for any @racket[st] and @racket[st2] that both @tech{support}
@racket[subset?]. @racket[subset?].
@examples[#:eval set-eval @examples[#:eval set-eval
@ -617,7 +631,7 @@ Supported for any @racket[st] and @racket[st2] that both support
Produces a list containing the elements of @racket[st]. Produces a list containing the elements of @racket[st].
Supported for any @racket[st] that supports @racket[set->stream]. Supported for any @racket[st] that @tech{supports} @racket[set->stream].
} }
@ -629,7 +643,7 @@ Applies the procedure @racket[proc] to each element in
@racket[st] in an unspecified order, accumulating the results @racket[st] in an unspecified order, accumulating the results
into a list. into a list.
Supported for any @racket[st] that supports @racket[set->stream]. Supported for any @racket[st] that @tech{supports} @racket[set->stream].
} }
@ -641,7 +655,7 @@ Supported for any @racket[st] that supports @racket[set->stream].
Applies @racket[proc] to each element in @racket[st] (for the Applies @racket[proc] to each element in @racket[st] (for the
side-effects of @racket[proc]) in an unspecified order. side-effects of @racket[proc]) in an unspecified order.
Supported for any @racket[st] that supports @racket[set->stream]. Supported for any @racket[st] that @tech{supports} @racket[set->stream].
} }
@ -650,7 +664,7 @@ Supported for any @racket[st] that supports @racket[set->stream].
Explicitly converts a set to a sequence for use with @racket[for] and Explicitly converts a set to a sequence for use with @racket[for] and
other forms. other forms.
Supported for any @racket[st] that supports @racket[set->stream]. Supported for any @racket[st] that @tech{supports} @racket[set->stream].
} }