Next: , Previous: , Up: Top   [Contents][Index]

3 Hash-sets

For change ringing applications it is often useful to manipulate sets of rows. That is, unordered collections of rows without duplicates. To support this and similar uses Roan supplies hash-sets, which use equalp as the comparison for whether or not two candidate elements are “the same”. In addition, equalp can be used to compare two hash-sets themselves for equality: they are equalp if they contain the same number of elements, and each of the elements of one is equalp to an element of the other.

 (equalp (hash-set !12345678 !13572468 !12753468 !13572468)
         (hash-set-union (hash-set !12753468 !12345678)
                         (hash-set !13572468 !12753468 !13572468)))
     ⇒ t
Type: hash-set

A set data structure, with element equality determined by equalp. That is, no two elements of such a set will ever be equalp, only one of those added remaining present in the set. Set membership testing, adding new elements to the set, and deletion of elements from the set is, on average, constant time. Two hash-sets can be compared with equalp: they are considered equalp if and only if they contain the same number of elements, and each of the elements of one is equalp to an element of the other.

Function: make-hash-set &key size rehash-size rehash-threshold initial-elements

Returns a new hash-set. If initial-elements is supplied and non-nil, it must be a list of elements that the return value will contain; otherwise an empty set is returned. If any of size, rehash-size or rehash-threshold are supplied they have meanings analagous to the eponymous arguments to make-hash-table.

Function: hash-set &rest initial-elements

Returns a new hash-set containing the elements of initial-elements. If no initial-elements are supplied, the returned hash-set is empty.

 (hash-set 1 :foo 2 :foo 1) ⇒ #<HASH-SET 3>
 (hash-set-elements (hash-set 1 :foo 2 :foo 1))
     ⇒ (1 2 :foo)
 (hash-set-elements (hash-set)) ⇒ nil
Function: hash-set-copy set &key size rehash-size rehash-threshold

Returns a new hash-set containing the same elements as the hash-set set. If any of size, rehash-size or rehash-threshold are supplied they have the same meanings as the eponymous arguments to copy-hash-table. A type-error is signaled if set is not a hash-set.


Next: , Up: Hash-sets   [Contents][Index]

3.1 Properties of hash-sets

Function: hash-set-count set

Returns a non-negative integer, the number of elements the hash-set set contains. Signals a type-error if set is not a hash-set.

 (hash-set-count (hash-set !1234 !1342 !1234)) ⇒ 2
 (hash-set-count (hash-set)) ⇒ 0
Function: hash-set-empty-p set

True if and only if the hash-set set contains no elements. Signals a type-error if set is not a hash-set.

Function: hash-set-elements set

Returns a list of all the elements of the hash-set set. The order of the elements in the list is undefined, and may vary between two invocations of hash-set-elements. Signals a type-error if set is not a hash-set.

 (hash-set-elements (hash-set 1 2 1 3 1)) ⇒ (3 2 1)
Function: hash-set-member item set

True if and only if item is an element of the hash-set set. Signals a type-error if set is not a hash-set.

 (hash-set-member !1342 (hash-set !1243 !1342)) ⇒ t
 (hash-set-member !1342 (hash-set !12435 !12425)) ⇒ nil
Function: hash-set-subset-p subset superset
Function: hash-set-proper-subset-p subset superset

The hash-set-subset-p predicate is true if and only if all elements of subset occur in superset. The hash-set-proper-subset-p predicate is true if and only that is the case and further that subset does not contain all the elements of superset. type-error is signaled if either argument is not a hash-set.

 (hash-set-subset-p (hash-set 1) (hash-set 2 1) ⇒ t
 (hash-set-proper-subset-p (hash-set 1) (hash-set 2 1) ⇒ t
 (hash-set-subset-p (hash-set 1 2) (hash-set 2 1) ⇒ t
 (hash-set-proper-subset-p (hash-set 1 2) (hash-set 2 1) ⇒ nil
 (hash-set-subset-p (hash-set 1 3) (hash-set 2 1) ⇒ nil
 (hash-set-proper-subset-p (hash-set 1 3) (hash-set 2 1) ⇒ nil

Next: , Previous: , Up: Hash-sets   [Contents][Index]

3.2 Modifying hash-sets

Function: hash-set-clear set

Removes all elements from set, and then returns the now empty hash-set. Signals a type-error if set is not a hash-set.

Function: hash-set-adjoin set &rest elements
Function: hash-set-adjoin-list-elements set list
Function: hash-set-nadjoin set &rest elements
Function: hash-set-nadjoin-list-elements set list

Returns a hash-set that contains all the elements of set to which have been added the elements, or the elements of the list. As usual duplicate elements are not added, though exactly which of any potential duplicates are retained is undefined. The hash-set-adjoin and hash-set-adjoin-list-elements functions do not modify set but might return it if no changes are needed; that is, the caller cannot depend upon it necessarily being a fresh copy. The hash-set-nadjoin and hash-set-nadjoin-list-elements functions modify set (if one or more of the elements is not already contained therein) and return it. Note that hash-set-[n]adjoin-list-elements differs from (apply #'hash-set-[n]adjoin ...) in that the latter can adjoin at most call-arguments-limit elements. Signals a type-error if set is not a hash-set.

 (hash-set-elements (hash-set-adjoin (hash-set 1 2 3) 4 3 2))
     ⇒ (3 4 1 2)
Function: hash-set-remove set &rest elements

Returns a new hash-set that contains all the elements of set that are not equalp to any of the elements. Signals a type-error if set is not a hash-set.

Function: hash-set-delete set &rest elements

Deletes from the hash-set set all elements equalp to elements of elements, and returns the modified set. Signals a type-error if set is not a hash-set.

Function: hash-set-pop set &optional error-p empty-value

Deletes an element from set and returns it. The particular element chosen to be removed and returned is undefined. If set is empty returns empty-value if the generalized Boolean error-p is false and otherwise signals an error. By default error-p is true and empty-value is nil. Signals a type-error if set is not a hash-set.

Function: hash-set-difference set &rest more-sets
Function: hash-set-ndifference set &rest more-sets

Returns a hash-set containing all the elements of set that are not contained in any of more-sets. The hash-set-difference version returns a fresh hash-set, and does not modify set or any of the more-sets. The hash-set-ndifference version modifies and returns set, but does not modify any of more-sets. Signals a type-error if set or any of more-sets are not hash-sets.

 (hash-set-elements
   (hash-set-difference
     (hash-set !12345 !23451 !34512 !45123)
     (hash-set !23451 !54321 !12345)))
     ⇒ (!34512 !45123)
Function: hash-set-union set &rest more-sets
Function: hash-set-nunion set &rest more-sets

Returns a hash-set containing all the elements that appear in set or in any of the more-sets. The hash-set-union function does not modify set or any of the more-sets, but may return any one of them unmodified if appropriate; the caller should not assume a fresh hash-set is returned. The hash-set-nunion function always returns set, modifying it if necessary; it does not modify any of the more-sets. Signals a type-error if set or any of the more-sets are not hash-sets.

 (coerce
   (hash-set-elements
     (hash-set-union
       (apply #'hash-set (coerce "abcdef" 'list))
       (apply #'hash-set (coerce "ACEG" 'list))))
   'string)
     ⇒ "FaeGbcd"
 (hash-set-empty-p (hash-set-union)) ⇒ t
Function: hash-set-intersection set &rest more-sets
Function: hash-set-nintersection set &rest more-sets

Returns a hash-set such at all of its elements are also elements of set and of all the more-sets. The hash-set-intersection function does not modify set or any of the more-sets, but may return any one of them unmodified if appropriate; the caller should not assume a fresh hash-set is returned. The hash-set-nintersection function always returns set, modifying it if necessary; it does not modify any of the more-sets. Signals a type-error if set or any of the more-sets are not hash-sets.

 (coerce
   (hash-set-elements
     (hash-set-intersection
       (apply #'hash-set (coerce "abcdef" 'list))
       (apply #'hash-set (coerce "ACEG" 'list))))
   'string)
     ⇒ "EaC"

Previous: , Up: Hash-sets   [Contents][Index]

3.3 Iterating over hash-sets

Function: map-hash-set function set

Calls function on each element of the hash-set set, and returns nil. The order in which the elements of set have function applied to them is undefined. With one exception, the behavior is undefined if function attempts to modify the contents of set: function may call hash-set-delete to delete the current element, but no other. A type-error is signaled if set is not a hash-set.

 (let ((r nil))
   (map-hash-set #'(lambda (e)
                     (push (list e (in-course-p e)) r))
                 (hash-set !135246 !123456 !531246))
   r)
     ⇒ ((!135246 nil) (!531246 nil) (!123456 t))
Macro: do-hash-set (var set &optional result-form) &body body

Evaluates the body, an implicit progn, repeatedly with the symbol var bound to the elements of the hash-set set. Returns the result of evaluating result-form, which defaults to nil, after the last iteration. A value may be returned by using return or return-from nil, in which case result-form is not evaluated. The order in which the elements of set are bound to var for evaluating body is undefined. With one exception the behavior is undefined if body attempts to modify the contents of set: function may call hash-set-delete to delete the current element, but no other. A type-error is signaled if set is not a hash-set.

 (let ((r nil))
   (do-hash-set (e (hash-set !135246 !123456 !531246) r)
     (push (list e (in-course-p e) r))))
     ⇒ ((!531246 nil) (!123456 t) (!135246 nil))

In addition, it is possible to iterate over a hash-set using the iterate macro, by using the for...:in-hash-set... construct.

(iter (for element :in-hash-set (hash-set !135246 !123456 !531246))
      (collect (list element (in-course-p element))))
    ⇒ ((!531246 nil) (!135246 nil) (!123456 t))

Previous: , Up: Hash-sets   [Contents][Index]