adds the following API calls: PySet_Clear(), _PySet_Next(), and
_PySet_Update(). The latter two are considered non-public. Tests and
documentation (for the public API) are included.
* set_merge() cannot assume that the table doesn't resize during iteration.
* convert some unnecessary tests to asserts -- they were necessary in
dictobject.c because PyDict_Next() is a public function. The same is
not true for set_next().
* re-arrange the order of functions to more closely match the order
in dictobject.c. This makes it must easier to compare the two
and ought to simplify any issues of maintaining both.
a frozenset conversion when the initial search attempt fails with a
TypeError and the key is some type of set. Add a testcase.
* Eliminate a duplicate if-stmt.
s|=s, s&=s, s-=s, or s^=s). Add related tests.
* Improve names for several variables and functions.
* Provide alternate table access functions (next, contains, add, and discard)
that work with an entry argument instead of just a key. This improves
set-vs-set operations because we already have a hash value for each key
and can avoid unnecessary calls to PyObject_Hash(). Provides a 5% to 20%
speed-up for quick hashing elements like strings and integers. Provides
much more substantial improvements for slow hashing elements like tuples
or objects defining a custom __hash__() function.
* Have difference operations resize() when 1/5 of the elements are dummies.
Formerly, it was 1/6. The new ratio triggers less frequently and only
in cases that it can resize quicker and with greater benefit. The right
answer is probably either 1/4, 1/5, or 1/6. Picked the middle value for
an even trade-off between resize time and the space/time costs of dummy
entries.
