In the TRACE_REFS version of the code, call _Py_NewReference() instead
of INCREF to bump the refcount from zero to one.

When exiting the function, don't DECREF the object back to zero
refcount, as that will reinvoke the object's deallocation function.
XXX Why did this ever work?

and Zope3 branch versions of this function.  No semantic change.

to figure out to fix the off-by-1 bug in BTreeItems_slice().

"next" functions, these can return a PER_USE() error *after* decrefing
the keys and values left over from the last call.  But they don't mark
the iteration as terminated, so finiSetIteration() will also try to
decref the leftovers.  The fix is to mark the iteration as terminated
when these functions fail.

"BTreeItems slice contains 1 too many elements"
This also fixes many related glitches, such as that giving an
out-of-bound slice index raised IndexError instead of clipping.

BTreeItems_slice():  Emulate Python slicing semantics in all cases.

testBTrees.py:  new testSlicing() tests in MappingBase and NormalSetTests
to ensure that slicing of .keys()/.items()/.values() works exactly the
same way as slicing of Python lists, in all one-sided, two-sided and
whole-structure ([:]) cases, with both negative and positive slice indices,
and mixtures of + and -, and whether in bounds or out of bounds.

+ Documented the arguments.
+ Used BUCKET_SEARCH.
+ Vastly reduced nesting.
+ Changed the "*changed" argument to get set true whenever PER_CHANGED
  is called, i.e. whenever the bucket mutates.  The purpose of *changed
  wasn't documented, and its only use was in the BTree set routine, which
  is known to have at least one bug.  So it wasn't clear what the purpose
  of *changed was.  What it did do is get set true if and only if the
  key was found in the bucket and its value was replaced, and I couldn't
  imagine a plausible reason for why the BTree set routine could care
  about that alone (all other calls to _bucket_set pass NULL, so there
  were no other clues).
+ Fixed all places where error returns didn't finish the persistence
  dance.

micro-optimized BUCKET_SEARCH macro.  Change _bucket_get() to use
it (more later).

way out of date (prints stuff and asserts instead of raising unittest
failures).

does.

iteration protocol a destructor (finiSetIteration()), to plug assorted
leaks of keys, values and even BTree nodes.

modifications were needed in Zope (only two files). A lot of unused
(or rarely) features were removed from the Interface package. Slightly
deeper imports are needed.

initSetIteration(), because it specifically doesn't want to bother
getting values out of mappings.

Elsewhere, repaired all other known cases where uses of the
TEST_KEY_OR_SET macro did early exits without finishing persistence
dances (Jeremy confirmed that's a Bad Thing -- creates unghostifiable
cache hogs).

a persistence dance on the buckets/sets it handles directly by itself.
If so, a similar but different change is also needed on the Zope3 branch.

SetIteration structs.

Added lots of comments as a result.  Redid parts of multiunion() because
it was clearly leaking references tucked away inside its SetIteration
struct.  Added XXX comments in another place I'm pretty sure is leaking
similar references in error cases (but am too tired to fix that now, if
so).

this now copies the keys into the work area in one gulp via memcpy,
instead of iterating over them one at a time.  Yields a nice speedup when
it applies (and it usually should apply!).

from a sequence of ints in reverse-sorted order (a quadratic-time
proposition).  That doesn't test anything interesting in context, though.
So fiddled it to do a larger input, but it runs much faster now.

to squash delicate code duplication and for speed.

+ This is optimized in several subtle ways over the current method.  This
  is documented in Maintainer.txt, along with a correctness proof.

+ I'll replace all the BTree searches with this soon.  For now I just
  changed _BTree_get().  I *suspect* this also fixes a subtle bug
  introduced by the recent "don't ignore comparison error" patch:  if a
  comparison did trigger an exception, the function just returned without
  doing the PER_ALLOW_DEACTIVATION + PER_ACCESSED dance.  _BTree_get()
  does that dance again now.

follows from that.

neglected to change the name in new comments barely an hour old.

"value" to "child".  All the rest is mechanical name-changing.  Next
step is to change the decl of child from PyObject* to Sized*.

the common initial fields (pyobject hair, persistence hair, 'size',
and 'len').  I think Jim wants the data decls split into a separate
file, but I'm unclear on why so am not doing that now.

Renamed stuff for consistency.

Added some comments.  More BTree comments will end up in Maintainer.txt.