[ZODB-Dev] Updated BTree docs

[Tim Peters]

[Casey Duncan]
> Sorry, I forgot to mention that it takes a single argument, which
> is a minimum value. It filters out any values less then this.

That's another piece of the truth <wink>.  The rest is that if

1) the minimum value is larger than 0;

and,

2) it's an IIBTree or OIBTree (but not an IOBTree or OOBTree),

then each value is also divided by the minimum (truncating toward 0), and
these fiddled values are what you see in the returned list.  Put that all
together, and the examples I posted before make some kind of sense.

> I don't know what the use case is for this feature, ZCatalog does not
> use it.  If I were to guess I would probably say it is some sort of
> score threshold for eliminating results below a certain score.

Yes, plus some notion of score normalization (the macro doing the division
(or not doing division, depending on tree type) is NORMALIZE_VALUE).

> ...
> We could have a keysForBestValues(N) method that did this, I dunno.

Me neither.  We should talk about the characteristics of the use cases; an
N-best queue can be much faster and more memory-efficient than a full-blown
sort, but it may not help either, depending on what the whole problem looks
like.

> ...
> Yup, I agree byValue should be deprecated in this case. Its a
> pretty weird method.

Good!  I'll stop feeling guilty about never getting around to writing a test
case for it then.