rand 0.9.1

data/History.txt

@@ -0,0 +1,25 @@
+== 0.9.1 / 2007-05-27
+
+* (setup.rb) Added setup 3.4.1, for non-gem users.
+
+* (Rakefile) Now we just require 'hoe' from seattle.rb and override
+  a few tasks which aren't generated to our liking.  (Keegan Quinn, 2007-05-29)
+
+* Rearranged files to match the usual Ruby project layout.
+  (Keegan Quinn, 2007-05-29)
+
+* (install.rb) Removed old installation script.  (Keegan Quinn, 2007-05-29)
+
+* lib/rand.rb: New shuffle. (Ilmari Heikkinen, 2005-01-04)
+
+* test/test_rand.rb: Bias tests. (Ilmari Heikkinen, 2005-01-04)
+
+* lib/rand.rb: Document _with_index methods. (Christian Neukirchen, 2004-12-03)
+
+* lib/rand.rb: Add pick_with_index. (Christian Neukirchen, 2004-12-02)
+
+
+== 0.9.0 / 2004-11-29
+
+* Initial release.
+

data/Manifest.txt

@@ -0,0 +1,7 @@
+History.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/rand.rb
+setup.rb
+test/test_rand.rb

data/README.txt

@@ -0,0 +1,62 @@
+= 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.

data/Rakefile

@@ -0,0 +1,52 @@
+# $Id: Rakefile 24 2007-07-14 13:24:11Z keegan $
+# Copyright 2007 Keegan Quinn
+#
+# Rakefile for rand, a library to shuffle and pick elements at random.
+#
+# This script can be redistributed and/or modified under the terms of the
+# Ruby license.  It comes without any warranty, to the extent permitted by
+# applicable law.
+
+
+SHORTNAME = 'rand'
+PKG_FILES = [ '[A-Z]*', 'setup.rb', 'lib/**/*.rb', 'test/**/*.rb' ]
+PKG_VERSION = '0.9.1'
+RDOC_OPTIONS = [
+  '--title', 'rand -- Random elements and shuffling', '--main', 'README.txt',
+  '--line-numbers', '--inline-source', '--all'
+]
+
+
+# Generate tasks with hoe
+require 'hoe'
+
+h = Hoe.new(SHORTNAME, PKG_VERSION) do |p|
+  p.rubyforge_name = SHORTNAME
+  p.summary = 'A library for picking random elements and shuffling.'
+  p.description = p.summary
+
+  p.changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+
+  p.url = 'http://rand.rubyforge.org'
+  p.email = 'keegan@rubyforge.org'
+  p.author = [ 'Ilmari Heikkinen', 'Christian Neukirchen', 'Keegan Quinn' ]
+
+  p.need_zip = true
+  p.remote_rdoc_dir = 'rdoc'
+
+  p.spec_extras = { 'rdoc_options' => RDOC_OPTIONS }
+end
+
+Rake::RDocTask.new(:docs) do |rd|
+  rd.main = "README.txt"
+  rd.options << '-d' if RUBY_PLATFORM !~ /win32/ and `which dot` =~ /\/dot/
+  rd.rdoc_dir = 'doc'
+
+  files = h.spec.files.grep(/^(lib|bin)|txt$/)
+  files -= ['Manifest.txt']
+  rd.rdoc_files.push(*files)
+
+  title = "#{h.name}-#{h.version} Documentation"
+
+  rd.options << "-t #{title}"
+end

data/lib/rand.rb

@@ -0,0 +1,319 @@
+# $Id: rand.rb 23 2007-07-14 13:13:48Z keegan $
+# Copyright 2007 Keegan Quinn
+# Copyright 2004 Christian Neukirchen
+# Copyright 2004 Ilmari Heikkinen
+#
+# rand.rb -- library for picking random elements and shuffling
+
+
+module Enumerable
+  # Choose and return a random element of the Enumerable.
+  #   [1, 2, 3, 4].pick  #=> 2 (or 1, 3, 4)
+  def pick
+    entries.pick
+  end
+
+  # Return an array of the elements in random order.
+  #   [1, 2, 3, 4].shuffle  #=> [3, 4, 1, 2]
+  def shuffle
+    entries.shuffle
+  end
+
+  # Calls _block_ once for each element in _self_ in random order,
+  # passing that element as a parameter.
+  def each_random(&block)
+    shuffle.each(&block)
+  end
+
+  # Invokes _block_ once for each element of _self_ in random order.
+  # Creates a new array containing the values returned by the block.
+  def map_random(&block)
+    shuffle.map(&block)
+  end
+end
+
+
+class Array
+  # Choose and return a random element of _self_.
+  #   [1, 2, 3, 4].pick  #=> 2 (or 1, 3, 4)
+  def pick
+    self[pick_index]
+  end
+
+  # Deletes a random element of _self_, returning that element.
+  #   a = [1, 2, 3, 4]
+  #   a.pick  #=> 2
+  #   a       #=> [1, 3, 4]
+  def pick!
+    i = pick_index
+    rv = self[i]
+    delete_at(i)
+    rv
+  end
+
+  # Return the index of an random element of _self_.
+  #   ["foo", "bar", "baz"].pick_index  #=> 1 (or 0, or 2)
+  def pick_index
+    rand(size)
+  end
+
+  # Destructive pick_index.  Delete a random element of _self_ and
+  # return its index.
+  #   a = [11, 22, 33, 44]
+  #   a.pick_index!  #=> 2
+  #   a              #=> [11, 22, 44]
+  def pick_index!
+    i = pick_index
+    delete_at i
+    i
+  end
+
+  # Return a random element of _self_ with its index.
+  #   a = ["a", "b", "c", "d"]
+  #   a.pick_with_index #=> ["b", 1]
+  #   a #=> ["a", "b", "c", "d"]
+  def pick_with_index
+    i = pick_index
+    [self[i], i]
+  end
+
+  # Delete and return a random element of _self_ with its index.
+  #   a = ["a", "b", "c", "d"]
+  #   a.pick_with_index! #=> ["b", 1]
+  #   a #=> ["a", "c", "d"]
+  def pick_with_index!
+    rv = pick_with_index
+    delete_at rv[1]
+    rv
+  end
+
+  # Return an array of the elements in random order.
+  #   [11, 22, 33, 44].shuffle  #=> [33, 11, 44, 22]
+  def shuffle
+    dup.shuffle!
+  end
+
+  # Destructive shuffle.  Arrange the elements of _self_ in new order.
+  # Using Fisher-Yates shuffle.
+  #   a = [11, 22, 33, 44]
+  #   a.shuffle!
+  #   a                      #=> [33, 11, 44, 22]
+  def shuffle!
+    (size-1).downto(1) {|index|
+      other_index = rand(index+1)
+      next if index == other_index
+      tmp = self[index]
+      self[index] = self[other_index]
+      self[other_index] = tmp
+    }
+    self
+  end
+end
+
+
+class Hash
+  # Choose and return a random key-value pair of _self_.
+  #   {:one => 1, :two => 2, :three => 3}.pick  #=> [:one, 1]
+  def pick
+    k = keys.pick
+    [k, self[k]]
+  end
+
+  # Deletes a random key-value pair of _self_, returning that pair.
+  #   a = {:one => 1, :two => 2, :three => 3}
+  #   a.pick  #=> [:two, 2]
+  #   a       #=> {:one => 1, :three => 3}
+  def pick!
+    rv = pick
+    delete rv.first
+    rv
+  end
+
+  # Return a random key of _self_.
+  #   {:one => 1, :two => 2, :three => 3}.pick_key  #=> :three
+  def pick_key
+    keys.pick
+  end
+
+  # Return a random value of _self_.
+  #   {:one => 1, :two => 2, :three => 3}.pick_value  #=> 3
+  def pick_value
+    values.pick
+  end
+
+  # Delete a random key-value pair of _self_ and return the key.
+  #   a = {:one => 1, :two => 2, :three => 3}
+  #   a.pick_key!  #=> :two
+  #   a       #=> {:one => 1, :three => 3}
+  def pick_key!
+    pick!.first
+  end
+
+  # Delete a random key-value pair of _self_ and return the value.
+  #   a = {:one => 1, :two => 2, :three => 3}
+  #   a.pick_value!  #=> 2
+  #   a       #=> {:one => 1, :three => 3}
+  def pick_value!
+    pick!.last
+  end
+
+  # Return the key-value pairs of _self_ with _keys_ and _values_
+  # shuffled independedly.
+  #   {:one => 1, :two => 2, :three => 3}.shuffle_hash_pairs
+  #      #=> [[:one, 3], [:two, 1], [:three, 2]]
+  def shuffle_hash_pairs
+    keys.shuffle.zip(values.shuffle)
+  end
+
+  # Return a copy of _self_ with _values_ arranged in random order.
+  #   {:one => 1, :two => 2, :three => 3}.shuffle_hash
+  #      #=> {:two=>2, :three=>1, :one=>3}
+  def shuffle_hash
+    shuffled = {}
+    shuffle_hash_pairs.each{|k, v|
+      shuffled[k] = v
+    }
+    shuffled
+  end
+
+  # Destructive shuffle_hash.  Arrange the values of _self_ in
+  # new, random order.
+  #   h = {:one => 1, :two => 2, :three => 3}
+  #   h.shuffle_hash!
+  #   h  #=> {:two=>2, :three=>1, :one=>3}
+  def shuffle_hash!
+    shuffle_hash_pairs.each{|k, v|
+      self[k] = v
+    }
+    self
+  end
+end
+
+
+class String
+  # Return the string with characters arranged in random order.
+  #   "Ruby rules".shuffle_chars  #=> "e lybRsuur"
+  def shuffle_chars
+    dup.shuffle_chars!
+  end
+
+  # Destructive shuffle_chars.  Arrange the characters of the string
+  # in new, random order.
+  #   s = "Ruby rules".shuffle_chars
+  #   s.shuffle_chars!
+  #   s    #=> "e lybRsuur"
+  def shuffle_chars!
+    (0...size).each {|j| 
+      i = rand(size-j)
+      self[j], self[j+i] = self[j+i], self[j]
+    }
+    self
+  end
+
+  # Return a random byte of _self_.
+  #   "Ruby rules".pick_byte  #=> 121
+  def pick_byte
+    self[pick_index]
+  end
+
+  # Return a single-character string of a random character in _self_.
+  #   "Ruby rules".pick_char  #=> "y"
+  def pick_char
+    pick_byte.chr
+  end
+
+  # Destructive pick_char.  Delete a random character of the string
+  # and return it as a single-character string.
+  #   s = "Ruby rules"
+  #   s.pick_char!  #=> "y"
+  #   s             #=> "Rub rules"
+  def pick_char!
+    i = pick_index
+    rv = self[i,1]
+    self[i,1] = ""
+    rv
+  end
+
+  # Destructive pick_byte.  Delete a random byte of _self_ and return it.
+  #   s = "Ruby rules"
+  #   s.pick_byte!  #=> 121
+  #   s             #=> "Rub rules"
+  def pick_byte!
+    pick_char![0]
+  end
+
+  # Return a random byte index of _self_.
+  #   "Ruby rules".pick_index  #=> 3
+  def pick_index
+    rand(size)
+  end
+
+  # Destructive pick_index.  Delete a random byte of _self_ and
+  # return it's index.
+  #   s = "Ruby rules"
+  #   s.pick_index  #=> 3
+  #   s             #=> "Rub rules"
+  def pick_index!
+    i = pick_index
+    self[i,1] = ""
+    i
+  end
+
+  # Return a two element array consisting of an random byte of _self_
+  # and it's index.
+  #   "Ruby rules".pick_byte_with_index  #=> [121, 3]
+  def pick_byte_with_index
+    i = pick_index
+    [self[i], i]
+  end
+
+  # Destructive pick_byte_with_index.  Delete a random byte of _self_
+  # and return it and it's index.
+  #   s = "Ruby rules"
+  #   s.pick_byte_with index!  #=> [121, 3]
+  #   s                        #=> "Rub rules"
+  def pick_byte_with_index!
+    rv = pick_byte_with_index
+    delete_at(rv[0])
+    rv
+  end
+
+  # Return a single-character string of a random character in _self_
+  # and it's index.
+  #   "Ruby rules".pick_char_with_index  #=> ["y", 3]
+  def pick_char_with_index
+    byte, index = pick_byte_with_index
+    [byte.chr, index]
+  end
+
+  # Destructive pick_char_with_index.  Delete a random character of
+  # the string and return it as a single-character string together
+  # with it's index.
+  #   s = "Ruby rules"
+  #   s.pick_char_with_index!  #=> ["y", 3]
+  #   s                        #=> "Rub rules"
+  def pick_char_with_index!
+    byte, index = pick_byte_with_index!
+    [byte.chr, index]
+  end
+
+  def pick
+    to_a.pick
+  end
+
+  def pick!
+    pick_with_index![0]
+  end
+
+  def pick_with_index
+    to_a.pick_with_index
+  end
+
+  def pick_with_index!
+    tokens = to_a
+    s, index = tokens.pick_with_index
+    start = tokens[0, index].join
+    self[start.size, s.size] = ""
+    [s, index]
+  end
+end