-USING: assocs hashtables help.markup help.syntax kernel
-quotations sequences vectors ;
+USING: assocs help.markup help.syntax kernel
+sequences vectors ;
IN: sets
ARTICLE: "sets" "Sets"
-"A set is an unordered list of elements. Words for working with sets are in the " { $vocab-link "sets" } " vocabulary." $nl
+"A set is an unordered collection of elements. Words for working with sets are in the " { $vocab-link "sets" } " vocabulary." $nl
"All sets are instances of a mixin class:"
{ $subsections
set
clear-set
union!
diff!
+ intersect!
}
"To test if a set is the empty set:"
{ $subsections null? }
subset?
set=
}
+"Operations on groups of sets:"
+{ $subsections
+ union-all
+ intersect-all
+}
"An optional generic word for creating sets of the same class as a given set:"
{ $subsections set-like }
"An optional generic word for creating a set with a fast lookup operation, if the set itself has a slow lookup operation:"
}
"Utilities for sets and sequences:"
{ $subsections
- within
- without
+ within
+ without
} ;
ARTICLE: "set-implementations" "Set implementations"
{ $side-effects "set" } ;
HELP: ?adjoin
-{ $values { "elt" object } { "set" set } { "?" "a boolean" } }
-{ $description "A version of " { $link adjoin } " which returns whether the element was added to the set." }
-{ $notes "This is slightly less efficient than " { $link adjoin } " due to the initial membership test." } ;
+{ $values { "elt" object } { "set" set } { "?" boolean } }
+{ $description "A version of " { $link adjoin } " which returns whether the element was added to the set." } ;
HELP: delete
{ $values { "elt" object } { "set" set } }
{ $description "Destructively removes " { $snippet "elt" } " from " { $snippet "set" } ". If the element is not present, this does nothing." $nl "Each mutable set type is expected to implement a method on this generic word." }
{ $side-effects "set" } ;
+HELP: ?delete
+{ $values { "elt" object } { "set" set } { "?" boolean } }
+{ $description "A version of " { $link delete } " which returns whether the element was removed from the set." } ;
+
HELP: clear-set
{ $values { "set" set } }
{ $contract "Removes all entries from the set." }
HELP: members
{ $values { "set" set } { "seq" sequence } }
-{ $description "Creates a sequence with a single copy of each member of the set." $nl "Each set type is expected to implement a method on this generic word." } ;
+{ $description "Creates a sequence with a single copy of each member of the set." $nl "Each set type is expected to implement a method on this generic word." }
+{ $notes "This will preserve the ordering of unique elements when called on a " { $link sequence } "." } ;
HELP: in?
-{ $values { "elt" object } { "set" set } { "?" "a boolean" } }
+{ $values { "elt" object } { "set" set } { "?" boolean } }
{ $description "Tests whether the element is a member of the set." $nl "Each set type is expected to implement a method on this generic word as part of the set protocol." } ;
HELP: adjoin-at
} ;
HELP: all-unique?
-{ $values { "set" set } { "?" "a boolean" } }
+{ $values { "set" set } { "?" boolean } }
{ $description "Tests whether a set contains any repeated elements." }
{ $example
"USING: sets prettyprint ;"
{ $example "USING: sets prettyprint ;" "{ 1 2 3 } { 2 3 4 } intersect ." "{ 2 3 }" }
} ;
-HELP: intersection
-{ $values { "sets" sequence } { "set/f" "a " { $link set } " or " { $link f } } }
-{ $description "Outputs the intersection of all the sets of the sequence " { $snippet "sets" } ", or " { $link f } " if " { $snippet "sets" } " is empty." } ;
-
HELP: union
{ $values { "set1" set } { "set2" set } { "set" set } }
{ $description "Outputs a set consisting of elements present in either " { $snippet "set1" } " or " { $snippet "set2" } " which does not contain duplicate values." $nl "This word has a default definition which works for all sets, but set implementations may override the default for efficiency." }
{ $description "Removes all members from " { $snippet "set1" } " contained in " { $snippet "set2" } "." }
{ $side-effects "set1" } ;
+HELP: intersect!
+{ $values { "set1" set } { "set2" set } }
+{ $description "Removes all members from " { $snippet "set1" } " not contained in " { $snippet "set2" } "." }
+{ $side-effects "set1" } ;
+
HELP: intersects?
-{ $values { "set1" set } { "set2" set } { "?" "a boolean" } }
+{ $values { "set1" set } { "set2" set } { "?" boolean } }
{ $description "Tests if " { $snippet "set1" } " and " { $snippet "set2" } " have any elements in common." }
{ $notes "If one of the sets is empty, the result is always " { $link f } "." } ;
HELP: subset?
-{ $values { "set1" set } { "set2" set } { "?" "a boolean" } }
+{ $values { "set1" set } { "set2" set } { "?" boolean } }
{ $description "Tests if every element of " { $snippet "set1" } " is contained in " { $snippet "set2" } "." }
{ $notes "If " { $snippet "set1" } " is empty, the result is always " { $link t } "." } ;
HELP: set=
-{ $values { "set1" set } { "set2" set } { "?" "a boolean" } }
-{ $description "Tests if both sets contain the same elements, disregrading order and duplicates." } ;
+{ $values { "set1" set } { "set2" set } { "?" boolean } }
+{ $description "Tests if both sets contain the same elements, disregarding order and duplicates." } ;
HELP: gather
{ $values
- { "seq" sequence } { "quot" quotation }
- { "newseq" sequence } }
-{ $description "Maps a quotation onto a sequence, concatenates the results of the mapping, and removes duplicates." } ;
+ { "seq" sequence } { "quot" { $quotation ( ... elt -- ... elts ) } }
+ { "newseq" sequence } }
+{ $description "Maps a quotation over a sequence, concatenates the results of the mapping, and removes duplicates." } ;
HELP: set-like
{ $values { "set" set } { "exemplar" set } { "set'" set } }
{ $description "Returns the subsequence of the given sequence consisting of things that are not members of the set. This may contain duplicates, if the sequence has duplicates." } ;
HELP: null?
-{ $values { "set" set } { "?" "a boolean" } }
+{ $values { "set" set } { "?" boolean } }
{ $description "Tests whether the given set is empty. This outputs " { $snippet "t" } " when given a null set of any type." } ;
HELP: cardinality
{ $values { "set" set } { "n" "a non-negative integer" } }
{ $description "Returns the number of elements in the set. All sets support this operation." } ;
-HELP: combine
-{ $values { "sets" "a sequence of sets" } { "set/f" "a " { $link set } " or " { $link f } } }
+HELP: intersect-all
+{ $values { "sets" sequence } { "set/f" { $maybe set } } }
+{ $description "Outputs the intersection of all the sets of the sequence " { $snippet "sets" } ", or " { $link f } " if " { $snippet "sets" } " is empty." } ;
+
+HELP: union-all
+{ $values { "sets" { $sequence set } } { "set/f" { $maybe set } } }
{ $description "Outputs the union of a sequence of sets, or " { $link f } " if the sequence is empty." } ;
projects / factor.git / blobdiff