= 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:kig@misfiring.net>:: Code and unit tests
Christian Neukirchen <mailto:chneukirchen@gmail.com>:: 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.