Provides a 'hierarchical set' data structure. See hier-set for details.
Provides a 'hierarchical set' data structure. See `hier-set` for details.
(->edn coll)Serializes a HierSet's primary members to a versioned EDN string.
The containment predicate is intentionally not serialized; callers must
provide it to edn->hier-set. Only sets using natural ordering and string
or keyword members are supported. Sets with custom comparators are rejected
because a comparator function cannot be safely or faithfully encoded in EDN.
Metadata is not part of this primary-member serialization format.
Serializes a `HierSet`'s primary members to a versioned EDN string. The containment predicate is intentionally not serialized; callers must provide it to `edn->hier-set`. Only sets using natural ordering and string or keyword members are supported. Sets with custom comparators are rejected because a comparator function cannot be safely or faithfully encoded in EDN. Metadata is not part of this primary-member serialization format.
(children coll key)Returns the immediate children of key in sorted order.
Returns the immediate children of `key` in sorted order.
(datafy coll)Returns an inspectable map representation of a HierSet.
Returns an inspectable map representation of a `HierSet`.
(difference left right)Returns a HierSet containing primary members in left but not right.
Both sets must have equal comparators and containment predicates. Otherwise an ExceptionInfo is thrown rather than constructing a set with ambiguous hierarchy semantics.
Returns a HierSet containing primary members in `left` but not `right`. Both sets must have equal comparators and containment predicates. Otherwise an ExceptionInfo is thrown rather than constructing a set with ambiguous hierarchy semantics.
(edn->hier-set hcontains? edn)Deserializes edn using hcontains? and natural member ordering.
edn must be a version 1 payload produced by ->edn. The containment
predicate is not serialized and must be supplied by the caller.
Deserializes `edn` using `hcontains?` and natural member ordering. `edn` must be a version 1 payload produced by `->edn`. The containment predicate is not serialized and must be supplied by the caller.
(hier-set hcontains? & keys)Creates a hierarchical set with the containment predicate hcontains? and
primary members keys. The hcontains? predicate should be a function with
two arguments of the set element type. It should return true if the first
argument contains the second, and false otherwise.
A hierarchical set is a set of elements that can contain other elements
hierarchically. The element sort-order and the hcontains? predicate define
the hierarchical relationship. These constraints apply: (a) elements must sort
before any descendants; and (b) elements must contain all elements that sort
between themselves and any descendant. This means (hcontains? x x) must be
true. Elements are both ancestors and descendants of themselves.
Lookup in the set returns a seq of all primary members that are ancestors of the provided key. It returns nil if the provided key is not a descendant of a primary member.
conj and disj return new HierSets and never mutate the original. This is
persistent behavior, even though HierSet also implements java.util.Set;
that Java interface's mutator methods are unsupported. Unlike a standard
sorted set, contains is true for a descendant that is not a primary member,
and get returns the primary ancestors of its argument.
Creates a hierarchical set with the containment predicate `hcontains?` and primary members `keys`. The `hcontains?` predicate should be a function with two arguments of the set element type. It should return `true` if the first argument contains the second, and false otherwise. A hierarchical set is a set of elements that can contain other elements hierarchically. The element sort-order and the `hcontains?` predicate define the hierarchical relationship. These constraints apply: (a) elements must sort before any descendants; and (b) elements must contain all elements that sort between themselves and any descendant. This means `(hcontains? x x)` must be true. Elements are both ancestors and descendants of themselves. Lookup in the set returns a seq of all primary members that are ancestors of the provided key. It returns nil if the provided key is not a descendant of a primary member. `conj` and `disj` return new HierSets and never mutate the original. This is persistent behavior, even though HierSet also implements `java.util.Set`; that Java interface's mutator methods are unsupported. Unlike a standard sorted set, `contains` is true for a descendant that is not a primary member, and `get` returns the primary ancestors of its argument.
(hier-set-by hcontains? comparator & keys)Creates a HierSet using comparator for element comparison.
hcontains? must be a two-argument function accepting two values of the
element type and returning true when its first argument contains its second.
comparator must accept two element values and return the usual negative,
zero, or positive comparison result. The comparator is not merely a display
order: it defines the order used to find ancestors and descendants. It must
place every element before its descendants, and each ancestor must contain all
elements sorted between it and those descendants. Comparator equality (a zero
result) also makes two values the same set member, as with sorted-set-by.
keys are the initial primary members. conj and disj are persistent
operations: each returns a new HierSet and leaves its input unchanged. Unlike
a mutable Java Set, the Java mutator methods are unsupported. HierSet's
contains also recognizes descendants, while get and function invocation
return the lazy sequence of primary ancestors rather than the queried value.
Creates a HierSet using `comparator` for element comparison. `hcontains?` must be a two-argument function accepting two values of the element type and returning true when its first argument contains its second. `comparator` must accept two element values and return the usual negative, zero, or positive comparison result. The comparator is not merely a display order: it defines the order used to find ancestors and descendants. It must place every element before its descendants, and each ancestor must contain all elements sorted between it and those descendants. Comparator equality (a zero result) also makes two values the same set member, as with sorted-set-by. `keys` are the initial primary members. `conj` and `disj` are persistent operations: each returns a new HierSet and leaves its input unchanged. Unlike a mutable Java Set, the Java mutator methods are unsupported. HierSet's `contains` also recognizes descendants, while `get` and function invocation return the lazy sequence of primary ancestors rather than the queried value.
Defines operations on collections with hierarchical relationships.
Defines operations on collections with hierarchical relationships.
(ancestors coll key)(ancestors coll key strict?)Returns a lazy sequence of ancestors of key in a Hierarchical coll.
key must be a value comparable to the collection's elements. With the
two-argument arity, key itself is included when present; pass the boolean
strict? as true to omit it. The result is ordered from the nearest ancestor
to the farthest, and is empty when no primary member contains key.
Returns a lazy sequence of ancestors of `key` in a Hierarchical `coll`. `key` must be a value comparable to the collection's elements. With the two-argument arity, `key` itself is included when present; pass the boolean `strict?` as true to omit it. The result is ordered from the nearest ancestor to the farthest, and is empty when no primary member contains `key`.
(descendants coll key)(descendants coll key strict?)Returns a lazy sequence of primary members below key in a Hierarchical
coll. key must be a value comparable to the collection's elements. With
the two-argument arity, key itself is included when present; pass the
boolean strict? as true to omit it. The result is in the collection's sort
order and is empty when no primary member is a descendant of key.
Returns a lazy sequence of primary members below `key` in a Hierarchical `coll`. `key` must be a value comparable to the collection's elements. With the two-argument arity, `key` itself is included when present; pass the boolean `strict?` as true to omit it. The result is in the collection's sort order and is empty when no primary member is a descendant of `key`.
(intersection left right)Returns a HierSet containing primary members present in both sets.
Both sets must have equal comparators and containment predicates. Otherwise an ExceptionInfo is thrown rather than constructing a set with ambiguous hierarchy semantics.
Returns a HierSet containing primary members present in both sets. Both sets must have equal comparators and containment predicates. Otherwise an ExceptionInfo is thrown rather than constructing a set with ambiguous hierarchy semantics.
(leaves coll)Returns the members without children in sorted order.
Returns the members without children in sorted order.
(parent coll key)Returns the immediate parent of key, or nil when it has no parent.
Returns the immediate parent of `key`, or nil when it has no parent.
(roots coll)Returns the members without parents in sorted order.
Returns the members without parents in sorted order.
(union left right)Returns a HierSet containing the primary members of left and right.
Both sets must have equal comparators and containment predicates. Otherwise an ExceptionInfo is thrown rather than constructing a set with ambiguous hierarchy semantics.
Returns a HierSet containing the primary members of `left` and `right`. Both sets must have equal comparators and containment predicates. Otherwise an ExceptionInfo is thrown rather than constructing a set with ambiguous hierarchy semantics.
(valid-hierarchy? coll)Returns true when coll satisfies all HierSet invariants.
Returns true when `coll` satisfies all `HierSet` invariants.
(validate! coll)Validates the ordering, containment, and parent-index invariants of a
HierSet. Returns true when valid and throws ExceptionInfo describing the
first violated invariant otherwise.
Validates the ordering, containment, and parent-index invariants of a `HierSet`. Returns true when valid and throws `ExceptionInfo` describing the first violated invariant otherwise.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |