= rand.rb -- library for picking random elements and shuffling

== Overview

rand.rb adds new methods to Enumerable, Array, and Hash to:

* return a random element (+pick+, +pick_index+, +pick_key+,
+pick_value+ and their destructive versions suffixed with
<tt>!</tt>).

* arrange elements in new, random order (+shuffle+,
+shuffle_hash_pairs+, +shuffle_hash+).

* use above methods in convenient ways (+each_random+, +map_random+).


It also provides these new facilities to String:

* +shuffle_chars+, to arrange the characters of the string in new order.

* +pick_byte+, +pick_char+ and +pick_index+, to return random bytes,
characters or elements.


== Limitations

* Enumerable#pick does not work for infinite Enumerables. (Doesn't
make sense, anyway.)

* Enumerable#pick has O(n) memory usage in worst case. There is an
alternative solution at [ruby-talk:94451], but not yet integrated
into rand.rb.

* Enumerable#shuffle is sightly biased due the limited number of
Floats between 0 and 1. This will possibly be addressed in a later
release.


== Authors

Ilmari Heikkinen <mailto:[email protected]>:: Code and unit tests
Christian Neukirchen <mailto:[email protected]>:: Documentation and
housekeeping.

Please mail bugs, feature requests or patches to the mail addresses
above or use IRC[irc://freenode.net/#ruby-lang] to contact the
developers.


== History

November 26, 2004:: Initial version done as IRC collaboration project
between <tt>kig</tt> and <tt>chris2</tt>.

November 29, 2004:: First public release 0.9.


== Copyright

Copyright (C) 2004 Ilmari Heikkinen
Parts Copyright (C) 2004 Christian Neukirchen
This work is licensed under the same terms as Ruby itself.