[Zope-Checkins] CVS: Zope3/lib/python/Persistence/BTrees - BTreeTemplate.c:1.9

[Tim Peters]

Update of /cvs-repository/Zope3/lib/python/Persistence/BTrees
In directory cvs.zope.org:/tmp/cvs-serv9128

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


=== Zope3/lib/python/Persistence/BTrees/BTreeTemplate.c 1.8 => 1.9 ===
 }
 
+/*
+ * 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)
 {
@@ -634,7 +661,7 @@
 	    && BUCKET(self->data->child)->po_oid == NULL
 #endif
 	    ) {
-	    /* We have just one bucket. Save it's data directly. */
+	    /* We have just one bucket. Save its data directly. */
 	    o = bucket_getstate((Bucket *)self->data->child);
 	    if (o == NULL)
 		goto err;