Added bag docs

docs/api/srfi/113.md

@@ -8,8 +8,6 @@ Bags are like sets, but can contain the same object more than once. However, if
 
 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.
 
-TODO: above is not good enough, should at the very least add function signatures for the bag functions, and either copy the corresponding set description or link to this section and/or the corresponding set function.
-
 See the [SRFI document](http://srfi.schemers.org/srfi-113/srfi-113.html) for more information.
 
 - Constructors:
@@ -161,8 +159,16 @@ Create a newly allocated set as if by set using `comparator`. If the result of a
 
 # bag 
 
+    (bag comparator element ...)
+
+Returns a newly allocated empty bag. The comparator argument is a SRFI 114 comparator, which is used to control and distinguish the elements of the bag. The elements are used to initialize the bag.
+
 # bag-unfold
 
+    (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.
+
 # set? 
 
     (set? obj)
@@ -188,10 +194,29 @@ Returns `#t` if `set` has no elements and `#f` otherwise.
 Returns `#t` if `set1` and `set2` have no elements in common and `#f` otherwise.
 
 # bag? 
+
+    (bag? obj)
+
+Returns `#t` if `obj` is a bag, and `#f` otherwise.
+
 # bag-contains? 
+
+    (bag-contains? bag element)
+
+Returns `#t` if `element` is a member of `bag` and `#f` otherwise.
+
 # bag-empty? 
+
+    (bag-empty? bag)
+
+Returns `#t` if `bag` has no elements and `#f` otherwise.
+
 # bag-disjoint?
 
+    (bag-disjoint? bag1 bag2)
+
+Returns `#t` if `bag1` and `bag2` have no elements in common and `#f` otherwise.
+
 # set-member 
 
     (set-member set element default)
@@ -205,8 +230,17 @@ Returns the element of `set` that is equal, in the sense of `set's` equality pre
 Returns the comparator used to compare the elements of `set`.
 
 # bag-member 
+
+    (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.
+
 # bag-element-comparator
 
+    (bag-element-comparator bag)
+
+Returns the comparator used to compare the elements of `bag`.
+
 #set-adjoin 
 
     (set-adjoin set element ...)
@@ -273,15 +307,71 @@ The effects of the continuations are as follows (where obj is any Scheme object)
 
 In all cases, two values are returned: the possibly updated set and obj.
 
-#bag-adjoin
+# bag-adjoin
-#bag-adjoin!
+
-#bag-replace
+    (bag-adjoin bag element ...)
-#bag-replace!
+
-#bag-delete
+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 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 bag that does not return #t when passed to the type test procedure of the comparator.
-#bag-delete!
+
-#bag-delete-all
+# bag-adjoin! 
-#bag-delete-all!
+
-#bag-search!
+    (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.
+
+# bag-replace 
+
+    (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 except as follows: If element is equal (in the sense of bag's comparator) to an existing member of bag, then that member is omitted and replaced by element. If there is no such element in bag, then bag is returned unchanged.
+
+# bag-replace!
+
+    (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.
+
+# bag-delete 
+
+    (bag-delete bag element ...)
+
+The bag-delete procedure returns a newly allocated bag containing all the values of bag except for any that are equal (in the sense of bag's comparator) to one or more of the elements. Any element that is not equal to some member of the bag is ignored.
+
+# bag-delete! 
+
+    (bag-delete! bag element ...)
+
+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.
+
+# bag-delete-all 
+
+    (bag-delete-all bag element-list)
+
+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.
+
+# bag-delete-all! 
+
+    (bag-delete-all! bag element-list)
+
+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.
+
+# bag-search!
+
+    (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.
 
 # set-size
 
@@ -314,11 +404,33 @@ Returns #t if any element of set satisfies predicate, or #f otherwise. Note that
 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.
 
 # bag-size
+
+    (bag-size bag)
+
+Returns the number of elements in bag as an exact integer.
+
 # bag-find
+
+    (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.
+
 # bag-count
+
+    (bag-count predicate bag)
+
+Returns the number of elements of bag that satisfy predicate as an exact integer.
+
 # bag-any?
+
+    (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.
+
 # bag-every?
 
+    (bag-every? predicate bag)
+
 # set-map
 
     (set-map comparator proc set)
@@ -384,16 +496,72 @@ Returns two values: a newly allocated set with the same comparator as set that c
     (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.
-#bag-map
 
-#bag-for-each
+# bag-map
-#bag-fold
+
-#bag-filter
+    (bag-map comparator proc bag)
-#bag-remove
+
-#bag-partition
+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-filter!
+
-#bag-remove!
+    (bag-map string-ci-comparator symbol->string (bag eq? 'foo 'bar 'baz))
-#bag-partition!
+        => (bag 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 bag constructor. For example:
+
+    (bag-map (lambda (x) (quotient x 2))
+             integer-comparator
+             (bag integer-comparator 1 2 3 4 5))
+        => (bag 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.
+
+# bag-for-each
+
+    (bag-for-each proc bag)
+
+Applies proc to bag in arbitrary order, discarding the returned values. Returns an unspecified result.
+
+# bag-fold
+
+    (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.
+
+# bag-filter
+
+    (bag-filter predicate bag)
+
+Returns a newly allocated bag with the same comparator as bag, containing just the elements of bag that satisfy predicate.
+
+# bag-filter!
+
+    (bag-filter! predicate bag)
+
+A linear update procedure that returns a bag containing just the elements of bag that satisfy predicate.
+
+# bag-remove
+
+    (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.
+
+# bag-remove!
+
+    (bag-remove! predicate bag)
+
+A linear update procedure that returns a bag containing just the elements of bag that do not satisfy predicate.
+
+# bag-partition
+
+    (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.
+
+# bag-partition!
+
+    (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.
 
 # set-copy
 
@@ -419,12 +587,31 @@ Returns a newly allocated set, created as if by set using comparator, that conta
 
 Returns a set that contains the elements of both set and list. Duplicate elements (in the sense of the equality predicate) are omitted.
 
-#bag-copy
+# bag-copy
-#bag->list
-#list->bag
-#list->bag!
 
-#set=?
+    (bag-copy bag)
+
+Returns a newly allocated bag containing the elements of bag, and using the same comparator.
+
+# bag->list
+
+    (bag->list bag)
+
+Returns a newly allocated list containing the members of bag in unspecified order.
+
+# list->bag
+
+    (list->bag comparator list)
+
+Returns a newly allocated bag, created as if by bag using comparator, that contains the elements of list. Duplicate elements (in the sense of the equality predicate) are omitted.
+
+# list->bag!
+
+    (list->bag! bag list)
+
+Returns a bag that contains the elements of both bag and list. Duplicate elements (in the sense of the equality predicate) are omitted.
+
+# set=?
 
     (set=? set1 set2 ...)
 
@@ -432,35 +619,59 @@ Returns #t if each set contains the same elements.
 
 Note: The following subset predicates do not obey the trichotomy law and therefore do not constitute a total order on sets.
 
-#set<?
+# set<?
 
     (set<? set1 set2 ...)
 
 Returns #t if each set other than the last is a proper subset of the following set, and #f otherwise.
 
-#set>?
+# set>?
 
     (set>? set1 set2 ...)
 
 Returns #t if each set other than the last is a proper superset of the following set, and #f otherwise.
 
-#set<=?
+# set<=?
 
     (set<=? set1 set2 ...)
 
 Returns #t if each set other than the last is a subset of the following set, and #f otherwise.
 
-#set>=?
+# set>=?
 
     (set>=? set1 set2 ...)
 
 Returns #t if each set other than the last is a superset of the following set, and #f otherwise.
 
-#bag=?
+# bag=?
-#bag<?
+
-#bag>?
+    (bag=? bag1 bag2 ...)
-#bag<=?
+
-#bag>=?
+Returns #t if each bag contains the same elements.
+
+# bag<?
+
+    (bag<? bag1 bag2 ...)
+
+Returns #t if each bag other than the last is a proper subset of the following bag, and #f otherwise.
+
+# bag>?
+
+    (bag>? bag1 bag2 ...)
+
+Returns #t if each bag other than the last is a proper superset of the following bag, and #f otherwise.
+
+# bag<=?
+
+    (bag<=? bag1 bag2 ...)
+
+Returns #t if each bag other than the last is a subset of the following bag, and #f otherwise.
+
+# bag>=?
+
+    (bag>=? bag1 bag2 ...)
+
+Returns #t if each bag other than the last is a superset of the following bag, and #f otherwise.
 
 # set-union
 
@@ -518,24 +729,74 @@ Symmetric difference is not extended beyond two sets. Elements in the result set
 
 # bag-union
 
-TODO: need to integrate content below with the 4 (8?) applicable bag procedures
+    (bag-union bag1 bag2 ...)
-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.
+Return a newly allocated bag that is the union of the 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.
+The number of equal elements in the result is the largest 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).
+# bag-intersection
 
-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.
+    (bag-intersection bag1 bag2 ...)
 
-#bag-intersection
+Return a newly allocated bag that is the intersection of the bags. 
-#bag-difference
+
-#bag-xor
+The number of equal elements in the result is the smallest number of equal elements in any of the original bags.
-#bag-union!
+
-#bag-intersection!
+# bag-difference
-#bag-difference!
+
-#bag-xor!
+    (bag-difference bag1 bag2 ...)
+
+Return a newly allocated bag that is the asymmetric 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. 
+
+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).
+
+# bag-xor
+
+    (bag-xor bag1 bag2)
+
+Return a newly allocated bag that is the symmetric difference of the bags. 
+
+Symmetric difference is not extended beyond two bags. Elements in the result bag are drawn from the first bag in which they appear.
+
+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.
+
+# bag-union!
+    (bag-union! bag1 bag2 ...)
+
+Linear update procedures returning a bag that is the union of the bags. 
+
+The number of equal elements in the result is the largest number of equal elements in any of the original bags.
+
+# bag-intersection!
+
+    (bag-intersection! bag1 bag2 ...)
+
+Linear update procedures returning a bag that is the intersection of the bags. 
+
+The number of equal elements in the result is the smallest number of equal elements in any of the original bags.
+
+# bag-difference!
+
+    (bag-difference! bag1 bag2 ...)
+
+Linear update procedures returning a bag that is the asymmetric 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. 
+
+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).
+
+# bag-xor!
+
+    (bag-xor! bag1 bag2)
+
+Linear update procedures returning a bag that is the symmetric difference of the bags. 
+
+Symmetric difference is not extended beyond two bags. Elements in the result bag are drawn from the first bag in which they appear.
+
+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.
 
 # bag-sum