short first draft readme
read COPYING, the license for this code is GPL

If you end up using this for any purpose, please drop me a mail.
The code was written for my own uses, but I spent a day getting it prepped
for release so I'd love to know if it was worth it.
(I'll remove that paragraph if I get a few emails)

INSTALL:
python setup.py install

This will put it in your python site-packages/ directory,  wherever that is

This source is currently only easilly used as a Python module
I intend to library-ize the C in the future, but it isn't there yet
I intend to write perl bindings " "    "      "  "   "     "     "

Here is a short sample Python program

import probstat

mylist = [1,2,3]
p = probstat.Permutation(mylist)
for (item) in p:
  print item

generates the output
[3, 2, 1]
[2, 3, 1]
[3, 1, 2]
[1, 3, 2]
[2, 1, 3]
[1, 2, 3]

which is all the permutations of 1,2,3

you can do random access
l = p[17] # might throw an IndexError though

and slices
l = p[1:7] # possible IndexError

and of course length

print len(p)

DEPRECATED, the 'next()' method is deprecated, use for (blah) in foo:

_PATCHES WELCOME!_

The C code should be very readable, hack away.
All the code passes ElectricFence's memory checks, but if you find an
error please mail me, or prefereably submit a patch

As for performance, it is 10x + faster than the pure-python version
(which I might post if people want it)
Memory consuption is more than it needs to be by a factor of about two
this is because I wrote the C version to know nothing about the python bindings
Since the python bindings know everything about the C code, I could eliminate
this.  I'll get around to it someday.

Unlike some of the perl modules that do a similar thing, we don't calculate
all the premutations/combos/etc at the beginning and then iterate over the
[possibly] huge list.  When you iterate it figures out what the next
item is.  The memory consumed is about the size of the list passed in times 
three times the size of a pointer (we don't copy the list, just pointers to 
the items in the list).

If the list is straight scalars (int, string, etc) you can change the orignal
list and not worry about the results of the Permutation changing.  I only
keep a shallow copy of the data, so if you are permuting a list of lists and
you change the second-tier lists I make no garuntees that the data out is
what you want.

email jackdied@users.sourceforge.net with ideas, patches, comments
(if that bounces try jack_diederich@email.com)
