## SRFI-113: Sets and Bags

Sets and bags (also known as multisets) are unordered collections that can contain any Scheme object. Sets enforce the constraint that no two elements can be the same in the sense of the set's associated equality predicate; bags do not.

## Installation

$ chicken-install srfi-113

or

$ chicken-install srfi-113 -test

if you want to run the tests for the egg in addition.

## SRFI Description

For a full description of this SRFI, see the full SRFI document. This documentation covers the API only.

Although this version of SRFI-113 is based on the reference implementation, there is one notable difference. As SRFI-114 comparators have been deprecated in favour of SRFI-128 comparators, this egg uses SRFI-128 comparators whenever a comparator is needed. Thus, this egg depends on SRFI-128.

## Set Procedures

### Constructors

*[procedure]*

`(set comparator element ...)`

Returns a newly allocated empty set. The comparator argument is a SRFI-128 comparator, which is used to control and distinguish the elements of the set. The elements are used to initialize the set.

*[procedure]*

`(set-unfold comparator stop? mapper successor seed)`

Create a newly allocated set as if by set using `comparator`. If the result of applying the predicate `stop?` to `seed` is true, return the set. Otherwise, apply the procedure `mapper` to `seed`. The value that `mapper` returns is added to the set. Then get a new seed by applying the procedure successor to `seed`, and repeat this algorithm.

### Predicates

*[procedure]*

`(set? obj)`

Returns `#t` if `obj` is a set, and `#f` otherwise.

*[procedure]*

`(set-contains? set element)`

Returns `#t` if `element` is a member of `set` and `#f` otherwise.

*[procedure]*

`(set-empty? set)`

Returns `#t` if `set` has no elements and `#f` otherwise.

*[procedure]*

`(set-disjoint? set1 set2)`

Returns `#t` if `set1` and `set2` have no elements in common and `#f` otherwise.

### Accessors

*[procedure]*

`(set-member set element default)`

Returns the element of `set` that is equal, in the sense of set's equality predicate, to `element`. If `element` is not a member of set, `default` is returned.

*[procedure]*

`(set-element-comparator set)`

Returns the comparator used to compare the elements of `set`.

### Updaters

*[procedure]*

`(set-adjoin set element ...)`

The `set-adjoin` procedure returns a newly allocated set that uses the same comparator as `set` and contains all the values of `set`, and in addition each `element` unless it is already equal (in the sense of the comparator) to one of the existing or newly added members. It is an error to add an element to `set` that does not return `#t` when passed to the type test procedure of the comparator.

*[procedure]*

`(set-adjoin! set element ...)`

The `set-adjoin!` procedure is the same as `set-adjoin`, except that it is permitted to mutate and return the `set` argument rather than allocating a new set.

*[procedure]*

`(set-replace set element)`

The `set-replace` procedure returns a newly allocated set that uses the same comparator as `set` and contains all the values of `set` except as follows: If `element` is equal (in the sense of `set`'s comparator) to an existing member of `set`, then that member is omitted and replaced by `element`. If there is no such element in `set`, then `set` is returned unchanged.

*[procedure]*

`(set-replace! set element)`

The `set-replace!` procedure is the same as `set-replace`, except that it is permitted to mutate and return the `set` argument rather than allocating a new set.

*[procedure]*

`(set-delete set element ...)`

*[procedure]*

`(set-delete! set element ...)`

*[procedure]*

`(set-delete-all set element-list)`

*[procedure]*

`(set-delete-all! set element-list)`

The `set-delete` procedure returns a newly allocated set containing all the values of `set` except for any that are equal (in the sense of `set`'s comparator) to one or more of the elements. Any `element` that is not equal to some member of the set is ignored.

The `set-delete!` procedure is the same as `set-delete`, except that it is permitted to mutate and return the `set` argument rather than allocating a new set.

The `set-delete-all` and `set-delete-all!` procedures are the same as `set-delete` and `set-delete!`, except that they accept a single argument which is a list of elements to be deleted.

*[procedure]*

`(set-search! set element failure success)`

The `set` is searched for element. If it is not found, then the `failure` procedure is tail-called with two continuation arguments, `insert` and `ignore`, and is expected to tail-call one of them. If `element` is found, then the `success` procedure is tail-called with the matching element of `set` and two continuations, `update` and `remove`, and is expected to tail-call one of them.

The effects of the continuations are as follows (where obj is any Scheme object):

- Invoking
`(insert obj)`causes`element`to be inserted into`set`. - Invoking
`(ignore obj)`causes`set`to remain unchanged. - Invoking
`(update new-element obj)`causes`new-element`to be inserted into`set`in place of`element`. - Invoking
`(remove obj)`causes the matching element of`set`to be removed from it.

In all cases, two values are returned: the possibly updated `set` and `obj`.

### The Whole Set

*[procedure]*

`(set-size set)`

Returns the number of elements in `set` as an exact integer.

*[procedure]*

`(set-find predicate set failure)`

Returns an arbitrarily chosen element of `set` that satisfies `predicate`, or the result of invoking `failure` with no arguments if there is none.

*[procedure]*

`(set-count predicate set)`

Returns the number of elements of `set` that satisfy `predicate` as an exact integer.

*[procedure]*

`(set-any? predicate set)`

Returns `#t` if any element of `set` satisfies `predicate`, or `#f` otherwise. Note that this differs from the SRFI 1 analogue because it does not return an element of the set.

*[procedure]*

`(set-every? predicate set)`

Returns `#t` if every element of `set` satisfies `predicate`, or `#f` otherwise. Note that this differs from the SRFI 1 analogue because it does not return an element of the set.

### Mapping and Folding

*[procedure]*

`(set-map comparator proc set)`

Applies `proc` to each element of set in arbitrary order and returns a newly allocated set, created as if by (set comparator), which contains the results of the applications. For example:

(set-map string-ci-comparator symbol->string (set eq? 'foo 'bar 'baz)) => (set string-ci-comparator "foo" "bar" "baz")

Note that, when `proc` defines a mapping that is not 1:1, some of the mapped objects may be equivalent in the sense of `comparator`'s equality predicate, and in this case duplicate elements are omitted as in the `set` constructor. For example:

(set-map (lambda(x) (quotient x 2)) integer-comparator (set integer-comparator 1 2 3 4 5)) => (set integer-comparator 0 1 2)

If the elements are the same in the sense of `eqv?`, it is unpredictable which one will be preserved in the result.

*[procedure]*

`(set-for-each proc set)`

Applies `proc` to `set` in arbitrary order, discarding the returned values. Returns an unspecified result.

*[procedure]*

`(set-fold proc nil set)`

Invokes `proc` on each member of `set` in arbitrary order, passing the result of the previous invocation as a second argument. For the first invocation, `nil` is used as the second argument. Returns the result of the last invocation, or `nil` if there was no invocation.

*[procedure]*

`(set-filter predicate set)`

Returns a newly allocated set with the same comparator as `set`, containing just the elements of `set` that satisfy `predicate`.

*[procedure]*

`(set-filter! predicate set)`

A linear update procedure that returns a set containing just the elements of `set` that satisfy `predicate`.

*[procedure]*

`(set-remove predicate set)`

Returns a newly allocated set with the same comparator as `set`, containing just the elements of `set` that do not satisfy `predicate`.

*[procedure]*

`(set-remove! predicate set)`

A linear update procedure that returns a set containing just the elements of `set` that do not satisfy `predicate`.

*[procedure]*

`(set-partition predicate set)`

Returns two values: a newly allocated set with the same comparator as `set` that contains just the elements of `set` that satisfy `predicate`, and another newly allocated set, also with the same comparator, that contains just the elements of `set` that do not satisfy `predicate`.

*[procedure]*

`(set-partition! predicate set)`

A linear update procedure that returns two sets containing the elements of set that do and do not, respectively, not satisfy predicate.

### Copying and Conversion

*[procedure]*

`(set-copy set)`

Returns a newly allocated set containing the elements of `set`, and using the same comparator.

*[procedure]*

`(set->list set)`

Returns a newly allocated list containing the members of `set` in unspecified order.

*[procedure]*

`(list->set comparator list)`

Returns a newly allocated set, created as if by `set` using `comparator`, that contains the elements of `list`. Duplicate elements (in the sense of the equality predicate) are omitted.

*[procedure]*

`(list->set! set list)`

Returns a set that contains the elements of both `set` and `list`. Duplicate elements (in the sense of the equality predicate) are omitted.

### Subsets

**Note:** The following three predicates do not obey the trichotomy law and therefore do not constitute a total order on sets.

*[procedure]*

`(set=? set1 set2 ...)`

Returns `#t` if each set contains the same elements.

*[procedure]*

`(set<? set1 set2 ...)`

Returns `#t` if each set other than the last is a proper subset of the following set, and `#f` otherwise.

*[procedure]*

`(set>? set1 set2 ...)`

Returns `#t` if each set other than the last is a proper superset of the following set, and `#f` otherwise.

*[procedure]*

`(set<=? set1 set2 ...)`

Returns `#t` if each set other than the last is a subset of the following set, and `#f` otherwise.

*[procedure]*

`(set>=? set1 set2 ...)`

Returns `#t` if each set other than the last is a superset of the following set, and `#f` otherwise.

### Set-theory Operations

*[procedure]*

`(set-union set1 set2 ...)`

*[procedure]*

`(set-intersection set1 set2 ...)`

*[procedure]*

`(set-difference set1 set2 ...)`

*[procedure]*

`(set-xor set1 set2)`

Return a newly allocated set that is the union, intersection, asymmetric difference, or symmetric difference of the `sets`. Asymmetric difference is extended to more than two sets by taking the difference between the first set and the union of the others. Symmetric difference is not extended beyond two sets. Elements in the result set are drawn from the first set in which they appear.

*[procedure]*

`(set-union! set1 set2 ...)`

*[procedure]*

`(set-intersection! set1 set2 ...)`

*[procedure]*

`(set-difference! set1 set2 ...)`

*[procedure]*

`(set-xor! set1 set2)`

Linear update procedures returning a set that is the union, intersection, asymmetric difference, or symmetric difference of the `sets`. Asymmetric difference is extended to more than two sets by taking the difference between the first set and the union of the others. Symmetric difference is not extended beyond two sets. Elements in the result set are drawn from the first set in which they appear.

## Bag Procedures

Bags are like sets, but can contain the same object more than once. However, if two elements that are the same in the sense of the equality predicate, but not in the sense of `eqv?`, are both included, it is not guaranteed that they will remain distinct when retrieved from the bag. It is an error for a single procedure to be invoked on bags with different comparators.

The procedures for creating and manipulating bags are the same as those for sets, except that `set` is replaced by `bag` in their names, and that adjoining an element to a bag is effective even if the bag already contains the element. If two elements in a bag are the same in the sense of the bag's comparator, the implementation may in fact store just one of them.

The `bag-union`, `bag-intersection`, `bag-difference`, and `bag-xor` procedures (and their linear update analogues) behave as follows when both bags contain elements that are equal in the sense of the bags' comparator:

- For
`bag-union`, the number of equal elements in the result is the largest number of equal elements in any of the original bags. - For
`bag-intersection`, the number of equal elements in the result is the smallest number of equal elements in any of the original bags. - For
`bag-difference`, the number of equal elements in the result is the number of equal elements in the first bag, minus the number of elements in the other bags (but not less than zero). - For
`bag-xor`, the number of equal elements in the result is the absolute value of the difference between the number of equal elements in the first and second bags.

### Constructors

*[procedure]*

`(bag comparator element ...)`

Returns a newly allocated empty bag. The comparator argument is a SRFI-128 comparator, which is used to control and distinguish the elements of the bag. The elements are used to initialize the bag.

*[procedure]*

`(bag-unfold comparator stop? mapper successor seed)`

Create a newly allocated bag as if by bag using `comparator`. If the result of applying the predicate `stop?` to `seed` is true, return the bag. Otherwise, apply the procedure `mapper` to `seed`. The value that `mapper` returns is added to the bag. Then get a new seed by applying the procedure successor to `seed`, and repeat this algorithm.

### Predicates

*[procedure]*

`(bag? obj)`

Returns `#t` if `obj` is a bag, and `#f` otherwise.

*[procedure]*

`(bag-contains? bag element)`

Returns `#t` if `element` is a member of `bag` and `#f` otherwise.

*[procedure]*

`(bag-empty? bag)`

Returns `#t` if `bag` has no elements and `#f` otherwise.

*[procedure]*

`(bag-disjoint? bag1 bag2)`

Returns `#t` if `bag1` and `bag2` have no elements in common and `#f` otherwise.

### Accessors

*[procedure]*

`(bag-member bag element default)`

Returns the element of `bag` that is equal, in the sense of bag's equality predicate, to `element`. If `element` is not a member of bag, `default` is returned.

*[procedure]*

`(bag-element-comparator bag)`

Returns the comparator used to compare the elements of `bag`.

### Updaters

*[procedure]*

`(bag-adjoin bag element ...)`

The `bag-adjoin` procedure returns a newly allocated bag that uses the same comparator as `bag` and contains all the values of `bag`, and in addition each `element`. It is an error to add an element to `bag` that does not return `#t` when passed to the type test procedure of the comparator.

*[procedure]*

`(bag-adjoin! bag element ...)`

The `bag-adjoin!` procedure is the same as `bag-adjoin`, except that it is permitted to mutate and return the `bag` argument rather than allocating a new bag.

*[procedure]*

`(bag-replace bag element)`

The `bag-replace` procedure returns a newly allocated bag that uses the same comparator as `bag` and contains all the values of `bag`. If there is no such element in `bag`, then `bag` is returned unchanged.

*[procedure]*

`(bag-replace! bag element)`

The `bag-replace!` procedure is the same as `bag-replace`, except that it is permitted to mutate and return the `bag` argument rather than allocating a new bag.

*[procedure]*

`(bag-delete bag element ...)`

*[procedure]*

`(bag-delete! bag element ...)`

*[procedure]*

`(bag-delete-all bag element-list)`

*[procedure]*

`(bag-delete-all! bag element-list)`

The `bag-delete` procedure returns a newly allocated bag containing all the values of `bag` Any `element` that is not equal to some member of the bag is ignored.

The `bag-delete!` procedure is the same as `bag-delete`, except that it is permitted to mutate and return the `bag` argument rather than allocating a new bag.

The `bag-delete-all` and `bag-delete-all!} procedures are the same as {{bag-delete` and `bag-delete!`, except that they accept a single argument which is a list of elements to be deleted.

*[procedure]*

`(bag-search! bag element failure success)`

The `bag` is searched for element. If it is not found, then the `failure` procedure is tail-called with two continuation arguments, `insert` and `ignore`, and is expected to tail-call one of them. If `element` is found, then the `success` procedure is tail-called with the matching element of `bag` and two continuations, `update` and `remove`, and is expected to tail-call one of them.

The effects of the continuations are as follows (where obj is any Scheme object):

- Invoking
`(insert obj)`causes`element`to be inserted into`bag`. - Invoking
`(ignore obj)`causes`bag`to remain unchanged. - Invoking
`(update new-element obj)`causes`new-element`to be inserted into`bag`in place of`element`. - Invoking
`(remove obj)`causes the matching element of`bag`to be removed from it.

In all cases, two values are returned: the possibly updated `bag` and `obj`.

### The Whole bag

*[procedure]*

`(bag-size bag)`

Returns the number of elements in `bag` as an exact integer.

*[procedure]*

`(bag-find predicate bag failure)`

Returns an arbitrarily chosen element of `bag` that satisfies `predicate`, or the result of invoking `failure` with no arguments if there is none.

*[procedure]*

`(bag-count predicate bag)`

Returns the number of elements of `bag` that satisfy `predicate` as an exact integer.

*[procedure]*

`(bag-any? predicate bag)`

Returns `#t` if any element of `bag` satisfies `predicate`, or `#f` otherwise. Note that this differs from the SRFI 1 analogue because it does not return an element of the bag.

*[procedure]*

`(bag-every? predicate bag)`

Returns `#t` if every element of `bag` satisfies `predicate`, or `#f` otherwise. Note that this differs from the SRFI 1 analogue because it does not return an element of the bag.

### Mapping and Folding

*[procedure]*

`(bag-map comparator proc bag)`

Applies `proc` to each element of bag in arbitrary order and returns a newly allocated bag, created as if by (bag comparator), which contains the results of the applications. For example:

(bag-map string-ci-comparator symbol->string (bag eq? 'foo 'bar 'baz)) => (bag string-ci-comparator "foo" "bar" "baz")

*[procedure]*

`(bag-for-each proc bag)`

Applies `proc` to `bag` in arbitrary order, discarding the returned values. Returns an unspecified result.

*[procedure]*

`(bag-fold proc nil bag)`

Invokes `proc` on each member of `bag` in arbitrary order, passing the result of the previous invocation as a second argument. For the first invocation, `nil` is used as the second argument. Returns the result of the last invocation, or `nil` if there was no invocation.

*[procedure]*

`(bag-filter predicate bag)`

Returns a newly allocated bag with the same comparator as `bag`, containing just the elements of `bag` that satisfy `predicate`.

*[procedure]*

`(bag-filter! predicate bag)`

A linear update procedure that returns a bag containing just the elements of `bag` that satisfy `predicate`.

*[procedure]*

`(bag-remove predicate bag)`

Returns a newly allocated bag with the same comparator as `bag`, containing just the elements of `bag` that do not satisfy `predicate`.

*[procedure]*

`(bag-remove! predicate bag)`

A linear update procedure that returns a bag containing just the elements of `bag` that do not satisfy `predicate`.

*[procedure]*

`(bag-partition predicate bag)`

Returns two values: a newly allocated bag with the same comparator as `bag` that contains just the elements of `bag` that satisfy `predicate`, and another newly allocated bag, also with the same comparator, that contains just the elements of `bag` that do not satisfy `predicate`.

*[procedure]*

`(bag-partition! predicate bag)`

A linear update procedure that returns two bags containing the elements of bag that do and do not, respectively, not satisfy predicate.

### Copying and Conversion

*[procedure]*

`(bag-copy bag)`

Returns a newly allocated bag containing the elements of `bag`, and using the same comparator.

*[procedure]*

`(bag->list bag)`

Returns a newly allocated list containing the members of `bag` in unspecified order.

*[procedure]*

`(list->bag comparator list)`

Returns a newly allocated bag, created as if by `bag` using `comparator`, that contains the elements of `list`.

*[procedure]*

`(list->bag! bag list)`

Returns a bag that contains the elements of both `bag` and `list`.

### Subbags

*[procedure]*

`(bag=? bag1 bag2 ...)`

Returns `#t` if each bag contains the same elements.

*[procedure]*

`(bag<? bag1 bag2 ...)`

Returns `#t` if each bag other than the last is a proper subbag of the following bag, and `#f` otherwise.

*[procedure]*

`(bag>? bag1 bag2 ...)`

Returns `#t` if each bag other than the last is a proper superbag of the following bag, and `#f` otherwise.

*[procedure]*

`(bag<=? bag1 bag2 ...)`

Returns `#t` if each bag other than the last is a subbag of the following bag, and `#f` otherwise.

*[procedure]*

`(bag>=? bag1 bag2 ...)`

Returns `#t` if each bag other than the last is a superbag of the following bag, and `#f` otherwise.

### Bag-theory Operations

*[procedure]*

`(bag-union bag1 bag2 ...)`

*[procedure]*

`(bag-intersection bag1 bag2 ...)`

*[procedure]*

`(bag-difference bag1 bag2 ...)`

*[procedure]*

`(bag-xor bag1 bag2)`

Return a newly allocated bag that is the union, intersection, asymmetric difference, or symmetric difference of the `bags`. Asymmetric difference is extended to more than two bags by taking the difference between the first bag and the union of the others. Symmetric difference is not extended beyond two bags.

*[procedure]*

`(bag-union! bag1 bag2 ...)`

*[procedure]*

`(bag-intersection! bag1 bag2 ...)`

*[procedure]*

`(bag-difference! bag1 bag2 ...)`

*[procedure]*

`(bag-xor! bag1 bag2)`

Linear update procedures returning a bag that is the union, intersection, asymmetric difference, or symmetric difference of the `bags`. Asymmetric difference is extended to more than two bags by taking the difference between the first bag and the union of the others. Symmetric difference is not extended beyond two bags.

### Additional bag procedures

*[procedure]*

`(bag-sum bag1 bag2 ...)`

*[procedure]*

`(bag-sum! bag1 bag2)`

The `bag-sum` procedure returns a newly allocated bag containing all the unique elements in all the bags, such that the count of each unique element in the result is equal to the sum of the counts of that element in the arguments. It differs from bag-union by treating identical elements as potentially distinct rather than attempting to match them up.

The `bag-sum!` procedure is equivalent except that it is linear-update.

*[procedure]*

`(bag-product n bag)`

*[procedure]*

`(bag-product! n bag)`

The `bag-product` procedure returns a newly allocated bag containing all the unique elements in `bag`, where the count of each unique element in the bag is equal to the count of that element in `bag` multiplied by `n`.

The `bag-product!` procedure is equivalent except that it is linear-update.

*[procedure]*

`(bag-unique-size bag)`

Returns the number of unique elements of {{bag}}.

*[procedure]*

`(bag-element-count bag element)`

Returns an exact integer representing the number of times that `element` appears in `bag`.

*[procedure]*

`bag-for-each-unique proc bag)`

Applies `proc` to each unique element of `bag` in arbitrary order, passing the element and the number of times it occurs in `bag`, and discarding the returned values. Returns an unspecified result.

*[procedure]*

`(bag-fold-unique proc nil bag)`

Invokes `proc` on each unique element of `bag` in arbitrary order, passing the number of occurrences as a second argument and the result of the previous invocation as a third argument. For the first invocation, `nil` is used as the third argument. Returns the result of the last invocation.

*[procedure]*

`(bag-increment! bag element count)`

*[procedure]*

`(bag-decrement! bag element count)`

Linear update procedures that return a bag with the same elements as `bag`, but with the element count of element in `bag` increased or decreased by the exact integer `count` (but not less than zero).

*[procedure]*

`(bag->set bag)`

*[procedure]*

`(set->bag set)`

*[procedure]*

`(set->bag! bag set)`

The `bag->set` procedure returns a newly allocated set containing the unique elements (in the sense of the equality predicate) of `bag`. The `set->bag` procedure returns a newly allocated bag containing the elements of `set`. The `set->bag!` procedure returns a bag containing the elements of both `bag` and `set`. In all cases, the comparator of the result is the same as the comparator of the argument or arguments.

*[procedure]*

`(bag->alist bag)`

*[procedure]*

`(alist->bag comparator alist)`

The `bag->alist` procedure returns a newly allocated alist whose keys are the unique elements of `bag` and whose values are the number of occurrences of each element. The `alist->bag` returning a newly allocated bag based on comparator, where the keys of alist specify the elements and the corresponding values of alist specify how many times they occur.

## Comparators

The following comparators are used to compare sets or bags, and allow sets of

sets, bags of sets, etc.

*[constant]*

`set-comparator`

*[constant]*

`bag-comparator`

**Note:** that these comparators do not provide comparison procedures, as there is no ordering between sets or bags. It is an error to compare sets or bags with different element comparators.

## Repository

## Version History

- 0.7
- Adds fix to (set/bag) sob-map argument order
- 0.6
- Fix for single argument case of
`set-union` - 0.5
- Removes hardcoded .so in setup
- 0.4
- Adds standard README.org to SRFIs
- 0.3
- Packages egg without extraneous files
- 0.2
- Fixes setup file on Windows
- 0.1
- Initial release.

## License

Copyright (C) John Cowan (2015). All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.