[Zope-Checkins] CVS: Zope/lib/python/BTrees - BTreeTemplate.c:1.46

[Tim Peters]

Update of /cvs-repository/Zope/lib/python/BTrees
In directory cvs.zope.org:/tmp/cvs-serv9607

Modified Files:
	BTreeTemplate.c 
Log Message:
BTree_getstate():  Documented what it returns.


=== Zope/lib/python/BTrees/BTreeTemplate.c 1.45 => 1.46 ===
 }
 
+/*
+ * Return:
+ *
+ * For an empty BTree (self->len == 0), None.
+ *
+ * For a BTree with one child (self->len == 1), and that child is a bucket,
+ * and that bucket has a NULL oid, a one-tuple containing a one-tuple
+ * containing the bucket's state:
+ *
+ *     (
+ *         (
+ *              child[0].__getstate__(),
+ *         ),
+ *     )
+ *
+ * Else a two-tuple.  The first element is a tuple interleaving the BTree's
+ * keys and direct children, of size 2*self->len - 1 (key[0] is unused and
+ * is not saved).  The second element is the firstbucket:
+ *
+ *     (
+ *          (child[0], key[1], child[1], key[2], child[2], ...,
+ *                                       key[len-1], child[len-1]),
+ *          self->firstbucket
+ *     )
+ *
+ * In the above, key[i] means self->data[i].key, and similarly for child[i].
+ */
 static PyObject *
 BTree_getstate(BTree *self, PyObject *args)
 {
@@ -611,7 +638,7 @@
 #endif
           )
         {
-          /* We have just one bucket. Save it's data directly. */
+          /* We have just one bucket. Save its data directly. */
           UNLESS(o=bucket_getstate(BUCKET(self->data->child), NULL)) goto err;
           PyTuple_SET_ITEM(r,0,o);
           ASSIGN(r, Py_BuildValue("(O)", r));