[Python-checkins] python/dist/src/Modules collectionsmodule.c, 1.24, 1.25

Fri Oct 1 03:32:56 CEST 2004

Update of /cvsroot/python/python/dist/src/Modules
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv14968/Modules
Modified Files:
	collectionsmodule.c 
Log Message:
Document some reverse-engineered invariants and pragmatic hints.
Index: collectionsmodule.c
===================================================================
RCS file: /cvsroot/python/python/dist/src/Modules/collectionsmodule.c,v
retrieving revision 1.24
retrieving revision 1.25
diff -u -d -r1.24 -r1.25

--- collectionsmodule.c	1 Oct 2004 01:04:50 -0000	1.24
+++ collectionsmodule.c	1 Oct 2004 01:32:53 -0000	1.25
@@ -9,6 +9,21 @@
 
 #define BLOCKLEN 46
 
+/* A `dequeobject` is composed of a doubly-linked list of `block` nodes.
+ * This list is not circular (the leftmost block has leftlink==NULL,
+ * and the rightmost block has rightlink==NULL). A deque d's first
+ * element is at d.leftblock[leftindex] and its last element is at
+ * d.rightblock[rightindex]; note that, unlike as for Python slice
+ * indices, this indices are inclusive on both ends.
+ * The list of blocks is never empty. An empty deque d has
+ * d.leftblock == d.rightblock != NULL; d.len == 0; and
+ * d.leftindex > d.rightindex; checking for d.len == 0 is the intended
+ * way to see whether d is empty.
+ * Note that since d.leftindex and d.rightindex may be indices into
+ * distinct blocks (and certainly are, for and d with len(d) > BLOCKLEN),
+ * it's not generally true that d.leftindex <= d.rightindex.
+ */
+
 typedef struct BLOCK {
 	struct BLOCK *leftlink;
 	struct BLOCK *rightlink;
@@ -31,8 +46,8 @@
 	PyObject_HEAD
 	block *leftblock;
 	block *rightblock;
-	int leftindex;
-	int rightindex;
+	int leftindex;	/* in range(BLOCKLEN) */
+	int rightindex;	/* in range(BLOCKLEN) */
 	int len;
 	PyObject *weakreflist; /* List of weak references */
 } dequeobject;
