# ==================================================================
# Ring Data Structure  (a ring of beads)
#
# User objects are held in a ring that has no begining or end. There
# is a "pointer" that "points" to one of the objects. The "pointer"
# can be move around the ring.
#
# Notes:
# 1. I have no idea what this data structure could be use for.
#    I did it because it was fun.
#
# ==================================================================
#
# In this code the class Bead is external to the class Ring.
# Bead could be an internal class of the Ring class. Making
# the class Bead internal  means the user only deals with
# their objects and the Ring class. This could make things
# simpler for the user? 
#
# ==================================================================
# To create a PyDoc html file:
#
#    pydoc -w ring
#
# To run a web server (port 2001) for the documentation
# for the modules in the current directory:
#
#    python3 -m pydoc -p 2001
#
# ==================================================================

Classes
		builtins.object Bead Ring   class Bead(builtins.object)     Ring bead class definition   Bead is a helper class for the ring class. It is generally not used by the users.   Beads hold the objects the user inserts into the ring. The ring can contain a mixture of objects because the ring does not have knowledge of object internals. Objects are the responsibility of the user.   Attributes:   obj               user defined object   forward           next bead in the forward direction   backward          next bead in the backward direction   Bead methods:   __init__            create a bead     Methods defined here: __init__(self, obj) Create a bead. Data descriptors defined here: __dict__ dictionary for instance variables (if defined) __weakref__ list of weak references to the object (if defined)   class Ring(builtins.object)     Ring class definition   Beads hold the objects the user inserts into the ring. The ring can contain a mixture of objects because the ring does not have knowledge of object internals. Objects are the responsibility of the user.   A ring always has a "pointer" pointing to one of the ring beads or "None" if there are no ring beads. This bead is called the ring's current bead.   The ring's beads are not maintained in any particular order. They are in the order the user inserts them.   Why have beads?   Beads allow the ring to know nothing about the objects it contains and therefore imposes no requirements on the objects in the ring.   Attributes:   bead              ring's current bead       count             number of beads in the ring   Ring methods:   __init__            create a ring insert              insert a bead into the ring forward             move forward one bead backward            move backward one bead fetch               return the object in the ring's current bead locate              locate a specific object in the ring                     if found, make it the ring's current bead delete              delete the ring's current bead display_ring        display (print) the ring     Methods defined here: __init__(self) Create a ring.   Attributes:   bead = none   count = 0 backward(self) Move backward one bead.   Return False if there is no current bead, else return True. delete(self) Delete the ring's current bead.   If there is no current bead return False, else return True. display_ring(self, f) Print all of the beads in the ring.   Because the ring knows nothing about the objects it contains, the user must pass in a function to return an object's information as a string. (The size of the display string should be limited. See the code.)   Parameters:     f    user defined function that returns a        user defined data value for a object. fetch(self) Return the object contained in the ring's current bead. If there is no currernt bead return None. forward(self) Move forward one bead.   Return False if there is no current bead, else return True. insert(self, obj, before=True) Insert a new bead into the ring.   If the 'before' flag is True, the new bead is inserted before (forward) the ring's current bead. If the 'before' flag is False, the new bead is inserted behind (backward) the ring's current bead. locate(self, val, f) Locate a specific object in the ring.   If found, make the found bead the ring's current bead and return True, else return False.   Because the ring knows nothing about the objects stored in it, the user must pass in a function to do the matching test.   Parameters:   val      value to be locate   f        function (user supplied) to compare a user            object with the val passed to this method. Data descriptors defined here: __dict__ dictionary for instance variables (if defined) __weakref__ list of weak references to the object (if defined)