History for HelperFunctions

??changed:
-
The following helper functions operate on sets, buckets and trees.
Methods apply only to objects of the same module (e.g. !IISet with !IIBTree).

  - difference(c1, c2)--  Return the keys or items in c1 for
    which there is no key in c2. If c1 is None, then None is 
    returned.  If c2 is none, then c1 is returned.

  - union(c1, c2) --Compute the Union of c1 and c2.  If c1 is None, 
    then c2 is returned, otherwise, if c2 is None,  then c1 is returned.
    The output is a Set containing keys from the input collections.
 
  - intersection(c1, c2): Compute the intersection of c1 and c2. If c1 is None, 
    then c2 is returned, otherwise, if c2 is None, then c1 is returned.
    The output is a Set containing matching keys from the input collections.

  - multiunion( seq ): Compute the union of a sequence of sets seq=(c1,c2,...).
    (*only available in Zope 2.6*)

  Example::

    from BTrees.IIBTree import IISet,IIBTree, intersection, union, difference

    set1 = IISet( range(0,10) )
    set2 = IISet( range(5,20) )
    tree = IIBTree( { 2:4, 4:16, 5:25 } )

    >>> set1
    IISet([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
    >>> set2
    IISet([5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19])
    >>> tree
    <IIBTree object at 0x816ec70>
    >>> union(set1,set2)
    IISet([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19])
     >>> intersection(set1,set2)
    IISet([5, 6, 7, 8, 9])
    >>> difference(set1,set2)
    IISet([0, 1, 2, 3, 4])
    >>> difference(set2,set1)
    IISet([10, 11, 12, 13, 14, 15, 16, 17, 18, 19])
    >>> union(set1,tree)
    IISet([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
    >>> difference (set1,tree)
    IISet([0, 1, 3, 6, 7, 8, 9])
    >>> intersection (set1,tree)
    IISet([2, 4, 5])
    >>> intersection (tree,set1)
    IISet([2, 4, 5])
    >>> difference (set1,tree)
    IISet([0, 1, 3, 6, 7, 8, 9])
    >>> difference (tree,set2)
    IIBucket([(2, 4), (4, 16)])
      
The following helper functions operate only on objects with integer keys:

  - weightedUnion(c1, c2, weight1=1, weight2=1 --
    Compute the weighted Union of c1 and c2.
    
    -  If c1 and c2 are None, the output is (0, None)

    -  if c1 is None and c2 is not None, the output is (weight2, c2)

    -  if c1 is not None and c2 not None and _both are sets_, 
       the output is (weight1, c1)

    -  If c1 and c2 are not None and _not both sets_, the output 
       is 1 and a Bucket such that the output values are::

        v1*weight1 + v2*weight2

        where:

          v1 is 0 if the key was not in c1. Otherwise, v1 is 1, if
          c1 is a set, or the value from c1.

          v2 is 0 if the key was not in c2. Otherwise, v2 is 2, if
          c2 is a set, or the value from c2.

    - Note that c1 and c2 must be collections. 

  - weightedIntersection(c1, c2, weight1=1, weight2=1) --
    Compute the weighted intersection of c1 and c2.

    - If c1 and c2 are None, the output is (None, None).

    - if c1 is None and c2 is not None, the output is (weight2, c2)

    - if c1 is not None and c2 not None, the output is (weight1, c1)

    - If c1 and c2 are _both sets_, the output is the  tuple (sum of the weights
      and the (unweighted) intersection of the sets).

    - If c1 and c2 are not None and _not both sets_, the output is 1
      and a Bucket such that the output values are::

        v1*weight1 + v2*weight2

        where:

          v1 is 0 if the key was not in c1. Otherwise, v1 is 1, if
          c1 is a set, or the value from c1.

          v2 is 0 if the key was not in c2. Otherwise, v2 is 2, if
          c2 is a set, or the value from c2.

   - Note that c1 and c2 must be collections.