`DrawSet`: A set with an efficient random draw

class epydemic.DrawSet(including=None, excluding=None)

A set re-implementation.

This class provides a re-implementation of sets that also provides an efficient (\(O(\log N)\)) method for drawing an element at random.

We implement only those parts of the set API that we need: perhaps ought to add the rest, for future-proofing.

Parameters:

including (Optional[Iterator[Union[Any, Tuple[Any, Any]]]]) – (optional) iterator of elements to add
excluding (Optional[Iterator[Union[Any, Tuple[Any, Any]]]]) – (optional) elements to exclude from the initialisation

The set interface

DrawSet.add(e)

Add an element to the set. This is a no-op if the element is already in the set.

DrawSet.__contains__(e)

Check whether the given element is a member of the set.

DrawSet.empty()

Test if the set is empty.

DrawSet.__len__()

Return the size of the set.

DrawSet.__iter__()

Return an iterator that returns elements in order.

DrawSet.discard(e)

Discard the given element from the locus. If the element isn’t in the set, this is a no-op: use remove() to detect removal of non-elements.

DrawSet.remove(e)

Remove the given element from the set, raising an exception if it wasn’t present: use discard() to allow the removal of non-elements.

The point of this class is to provide a way of drawing a random element efficiently, which isn’t possible using the standard Python set interface.

DrawSet.draw()

Draw an element from the set at random.