loaded_die 1.0.1 → 2.0.0

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2018 Aaron Beckerman
+Copyright (c) 2024 Aaron Beckerman
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

data/README.txt

@@ -0,0 +1,47 @@
+Loaded Die
+
+Loaded Die is a Ruby library that makes it easy to randomly choose from a set
+of options where some options are more likely than others.
+
+
+Usage
+
+This is the basic pattern: First, you load the library. Then you create an
+instance of LoadedDie::Sampler and send the sample message to it as many
+times as you like.
+
+Let's say you want to choose randomly from three strings: "A", "B", and "C".
+You want "A" and "B" to be equally likely, and "C" to be twice as likely as one
+of them. That means "A" should be 25% likely, B should be 25% likely, and C
+should be 50% likely.
+
+You can create your sampler like this:
+
+  require "loaded_die"
+  sampler = LoadedDie::Sampler.new({ "A" => 0.25, "B" => 0.25, "C" => 0.5 })
+
+And then sample from it like this:
+
+  sampler.sample
+
+But you don't need to be fussy about how you represent probabilities. That is,
+you don't need to represent them as numbers between zero and one such that they
+sum to one. Their relative values are what matter. Furthermore, they don't need
+to be floats, just objects that convert to floats. So you could also create
+your sampler like this:
+
+  sampler = LoadedDie::Sampler.new({ "A" => 1, "B" => 1, "C" => 2 })
+
+You can specify the random number generator that sample uses. To do this,
+supply as the argument a hash with your random number generator under the
+:random key. (This is based on the behavior of Ruby's Array#sample.) Your
+random number generator will be sent a rand message with one argument, the sum
+of the weights you specified when creating the sampler. The returned object
+must be a float greater than or equal to zero and less than the sum of the
+weights.
+
+  rng = Object.new
+  def rng.rand(n)
+    0.0
+  end
+  sampler.sample({ :random => rng })

data/lib/loaded_die.rb

@@ -1,52 +1,98 @@
+##
+# This module allows you to choose randomly from a set of options where some
+# options are more likely than others.
+
 module LoadedDie
-  VERSION = '1.0.1'
+
+  ##
+  # Instances of this class can choose randomly from a set of options (called
+  # individuals here). The options can have different probabilities of being
+  # chosen.
 
   class Sampler
+
+    ##
+    # The default random number generator. It samples from a uniform
+    # distribution.
+
     DEFAULT_RNG = ::Object.new
-    def DEFAULT_RNG.rand(n)
+    def DEFAULT_RNG.rand n
       ::Kernel.rand * n
     end
 
-    Segment = ::Struct.new(:maximum, :individual)
+    ##
+    # Creates a sampler from a population. The argument should return an
+    # enumerable (conventionally an instance of Enumerator) of arrays when sent
+    # a to_enum message with no arguments. (A normal instance of Hash
+    # qualifies.) Each array must have at least two elements: the first element
+    # is an individual that can be chosen and the second element is its weight
+    # -- that is, the likelihood relative to the other weights that the
+    # individual will be chosen. Weights must convert to finite floats that are
+    # zero or positive.
 
-    def initialize(population)
-      @compiled = population.inject [] do |accum, (individual, weight)|
-        if weight <= 0
-          raise ::ArgumentError, "non-positive weight #{weight}"
+    def initialize population
+      @compiled = population.to_enum.inject [] do |accum, elem|
+        individual = elem.fetch 0
+        weight = elem.fetch 1
+        weight_f = ::Kernel.Float weight
+        unless 0.0 <= weight_f && weight_f.finite?
+          ::Kernel.raise ::ArgumentError, "invalid weight #{weight_f}"
+          break
         end
         prev_max =
           if last = accum.last
-            last.maximum
+            last.fetch :maximum
           else
-            0
+            0.0
           end
-        accum << Segment.new(prev_max + weight, individual)
+        accum << { :maximum => prev_max + weight_f, :individual => individual }
       end
       nil
     end
 
+    ##
+    # Returns the sum of weights.
+
     def length
       if last = @compiled.last
-        last.maximum
+        last.fetch :maximum
       else
-        0
+        0.0
       end
     end
 
-    def [](point)
-      if point < 0
+    ##
+    # Returns the individual associated with the given point on a line. The
+    # point should convert to a float. If it is greater than or equal to zero
+    # and less than the sum of weights, this returns the corresponding
+    # individual. If it is outside those bounds, this returns nil.
+
+    def [] point
+      point_f = ::Kernel.Float point
+      if 0.0 > point_f
         nil
-      elsif choice = @compiled.detect { |segment| point < segment.maximum }
-        choice.individual
+      elsif choice = @compiled.detect { |segment|
+        segment.fetch(:maximum) > point_f }
+        choice.fetch :individual
       else
         nil
       end
     end
 
-    def sample(options = {})
-      rng = options.fetch(:random) { DEFAULT_RNG }
-      point = rng.rand(length)
+    ##
+    # Returns a randomly-chosen individual. The argument is a hash, empty by
+    # default. If it contains a value for the +:random+ key, that value will be
+    # used as the random number generator instead of the default. This RNG will
+    # be sent a rand message with one argument, the sum of weights, and should
+    # return a number (convertible to a float) greater than or equal to zero
+    # and less than the sum of weights.
+
+    def sample options = {}
+      rng = options.fetch(:random) { ::LoadedDie::Sampler::DEFAULT_RNG }
+      point = rng.rand length
       self[point]
     end
+
   end
+
 end

data/loaded_die.gemspec

@@ -1,19 +1,12 @@
-# -*- encoding: utf-8 -*-
-lib = File.expand_path("../lib", __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "loaded_die"
-
 Gem::Specification.new do |s|
   s.name = "loaded_die"
-  s.version = LoadedDie::VERSION
-  s.author = "Aaron Beckerman"
-  s.summary = %q{A library for choosing randomly when some options are more likely than others.}
-  s.description = %q{Loaded Die makes it easy to choose randomly when some options are more likely than others.}
-  s.license = "MIT"
-  s.platform = Gem::Platform::RUBY
+  s.version = "2.0.0"
+  s.authors = ["Aaron Beckerman"]
+  s.summary = "A library for choosing randomly where some options are more" \
+    " likely than others."
+  s.licenses = ["MIT"]
   s.required_ruby_version = ">= 1.8.7"
-  s.files = ["LICENSE.txt", "README.rdoc", "loaded_die.gemspec", "lib/loaded_die.rb", "test/loaded_die_test.rb"]
+  s.files = ["LICENSE.txt", "README.txt", "loaded_die.gemspec",
+    "lib/loaded_die.rb", "test/loaded_die_test.rb"]
   s.test_files = ["test/loaded_die_test.rb"]
-  s.executables = []
-  s.require_paths = ["lib"]
 end

data/test/loaded_die_test.rb

@@ -1,71 +1,195 @@
-require 'loaded_die'
+# Sections that create local variables are in class definitions so that later
+# sections cannot accidentally reference those local variables.
 
-String == LoadedDie::VERSION.class or fail
+require "loaded_die"
 
-Module == LoadedDie.class or fail
+# LoadedDie should be an instance of Module.
+fail "" unless Module.equal? LoadedDie.class
 
-Class == LoadedDie::Sampler.class or fail
+# LoadedDie::Sampler should be a class.
+fail "" unless Class.equal? LoadedDie::Sampler.class
 
+# LoadedDie::Sampler::DEFAULT_RNG.rand should return a float in the expected
+# range.
+class ::Object
+  n = LoadedDie::Sampler::DEFAULT_RNG.rand 0.5
+  fail "" unless Float.equal? n.class
+  fail "" unless 0.0 <= n && 0.5 > n
+end
+
+# LoadedDie::Sampler.new with an empty population should return an object of
+# class LoadedDie::Sampler.
+fail "" unless LoadedDie::Sampler.equal? LoadedDie::Sampler.new({}).class
+
+# LoadedDie::Sampler.new with only zero or positive finite weights should
+# return an instance of LoadedDie::Sampler.
+fail "" unless LoadedDie::Sampler.equal?(
+  LoadedDie::Sampler.new({ :a => 0.0, :b => 1.0 }).class)
+
+# LoadedDie::Sampler.new with a negative weight should raise an exception.
+begin
+  LoadedDie::Sampler.new({ :a => -1.0 })
+rescue ArgumentError
+  fail "" unless /\Ainvalid weight / =~ $!.message
+else
+  fail ""
+end
+
+# LoadedDie::Sampler.new with a NaN weight should raise an exception.
+begin
+  LoadedDie::Sampler.new({ :a => 0.0 / 0.0 })
+rescue ArgumentError
+  fail "" unless /\Ainvalid weight / =~ $!.message
+else
+  fail ""
+end
+
+# LoadedDie::Sampler.new with an infinite weight should raise an exception.
 begin
-  LoadedDie::Sampler.new(:a => 0)
+  LoadedDie::Sampler.new({ :a => 1.0 / 0.0 })
 rescue ArgumentError
+  fail "" unless /\Ainvalid weight / =~ $!.message
+else
+  fail ""
+end
+
+# LoadedDie::Sampler.new with a weight that does not convert to a float should
+# raise an exception.
+begin
+  LoadedDie::Sampler.new({ :a => nil })
+rescue TypeError
+else
+  fail ""
+end
+
+# LoadedDie::Sampler.new with a population that doesn't conform to the
+# interface should raise an exception.
+begin
+  LoadedDie::Sampler.new nil
+rescue NoMethodError
+else
+  fail ""
+end
+begin
+  LoadedDie::Sampler.new [[]]
+rescue IndexError
+else
+  fail ""
+end
+begin
+  LoadedDie::Sampler.new [[1.0]]
+rescue IndexError
 else
-  fail
+  fail ""
 end
 
+# Sending new with superfluous non-block arguments to LoadedDie::Sampler should
+# raise an exception.
 begin
-  LoadedDie::Sampler.new(:a => -1)
+  LoadedDie::Sampler.new({}, nil)
 rescue ArgumentError
 else
-  fail
+  fail ""
 end
 
-lambda do
+# A sampler should say it responds to the expected messages.
+class ::Object
   sampler = LoadedDie::Sampler.new({})
-  sampler.respond_to?(:length) or fail
-  sampler.respond_to?(:[]) or fail
-  sampler.respond_to?(:sample) or fail
-end.call
-
-lambda do
-  0 == LoadedDie::Sampler.new({}).length or fail
-  2 == LoadedDie::Sampler.new({ :a => 2 }).length or fail
-  (2 + 3.1) == LoadedDie::Sampler.new({ :a => 2, :b => 3.1 }).length or fail
-end.call
-
-lambda do
+  fail "" unless sampler.respond_to? :length
+  fail "" unless sampler.respond_to? :[]
+  fail "" unless sampler.respond_to? :sample
+end
+
+# Sampler length should be the sum of weights converted to floats.
+fail "" unless 0.0 == LoadedDie::Sampler.new([]).length
+fail "" unless 2.0 == LoadedDie::Sampler.new([[:a, 2.0]]).length
+fail "" unless (Float(2) + 0.0 + 3.1) ==
+  LoadedDie::Sampler.new([[:a, 2], [:b, 0.0], [:c, 3.1]]).length
+
+# Sending length with superfluous non-block arguments to a sampler should raise
+# an exception.
+begin
+  LoadedDie::Sampler.new({}).length nil
+rescue ArgumentError
+else
+  fail ""
+end
+
+# An empty sampler should always find nil when queried.
+class ::Object
   sampler = LoadedDie::Sampler.new({})
-  nil == sampler[0.42] or fail
-end.call
-
-lambda do
-  sampler = LoadedDie::Sampler.new([[:a, 3], [:b, 2.0], [:c, 5]])
-  nil == sampler[-1.0] or fail
-  :a == sampler[0.0] or fail
-  :a == sampler[2.99] or fail
-  :b == sampler[3] or fail
-  :b == sampler[3.0] or fail
-  :b == sampler[4.99] or fail
-  :c == sampler[5.0] or fail
-  :c == sampler[9.99] or fail
-  nil == sampler[10.0] or fail
-  nil == sampler[11.0] or fail
-end.call
-
-lambda do
+  fail "" unless nil.equal? sampler[0.42]
+end
+
+# A sampler should find the expected segment or nil when queried.
+class ::Object
+  sampler = LoadedDie::Sampler.new [[:a, 3], ["!", 0.0], [:b, 2.0], [:c, 5]]
+  fail "" unless nil.equal? sampler[-1.0]
+  fail "" unless :a.equal? sampler[0.0]
+  fail "" unless :a.equal? sampler[2.9]
+  fail "" unless :b.equal? sampler[3.0]
+  fail "" unless :b.equal? sampler[4.9]
+  fail "" unless :c.equal? sampler[5.0]
+  fail "" unless :c.equal? sampler[9.9]
+  fail "" unless nil.equal? sampler[10.0]
+  fail "" unless nil.equal? sampler[11.0]
+  fail "" unless nil.equal? sampler[0.0 / 0.0] # NaN
+  fail "" unless nil.equal? sampler[1.0 / 0.0] # infinity
+
+  # This non-float should be converted to a float.
+  fail "" unless :b.equal? sampler[4]
+
+  # An exception should be raised when the argument cannot be converted to a
+  # float.
+  begin
+    sampler[nil]
+  rescue TypeError
+  else
+    fail ""
+  end
+end
+
+# Sending [] with superfluous non-block arguments to a sampler should raise an
+# exception.
+begin
+  LoadedDie::Sampler.new({})[0.0, nil]
+rescue ArgumentError
+else
+  fail ""
+end
+
+# An empty sampler should return nil when sampled with the default
+# random number generator.
+class ::Object
   sampler = LoadedDie::Sampler.new({})
-  nil == sampler.sample or fail
-end.call
+  fail "" unless nil.equal? sampler.sample
+end
 
-lambda do
-  sampler = LoadedDie::Sampler.new([[:a, 3], [:b, 2.0], [:c, 9001]])
+# A sampler should return the expected individual when the random number
+# generator is faked and it should return something reasonable when sampled
+# with the default random number generator.
+class ::Object
+  sampler = LoadedDie::Sampler.new [[:a, 3], [:b, 2.0], ["!", 0.0], [:c, 9001]]
   rng = Object.new
-  def rng.rand(n)
-    (3 + 2.0 + 9001) == n or fail
-    4.99
+  def rng.rand n
+    fail "" unless ((Float(3) + 2.0) + Float(9001)) == n
+    4.9
   end
-  :b == sampler.sample(:random => rng) or fail
-  [:a, :b, :c].include?(sampler.sample) or fail
-end.call
+  fail "" unless :b.equal? sampler.sample({ :random => rng })
+  fail "" unless [:a, :b, :c].include? sampler.sample
+  # Unknown options should be ignored.
+  fail "" unless :b.equal? sampler.sample({ :random => rng, "?" => "?" })
+  fail "" unless [:a, :b, :c].include? sampler.sample({ "?" => "?" })
+end
+
+# Sending sample with superfluous non-block arguments to a sampler should raise
+# an exception.
+begin
+  LoadedDie::Sampler.new({}).sample({}, nil)
+rescue ArgumentError
+else
+  fail ""
+end
 
-puts 'Test finished.'
+# If this message doesn't get written, there was a problem.
+puts "Test finished: #{__FILE__}"

metadata

@@ -1,50 +1,73 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: loaded_die
-version: !ruby/object:Gem::Version
-  version: 1.0.1
+version: !ruby/object:Gem::Version 
+  hash: 15
+  prerelease: 
+  segments: 
+  - 2
+  - 0
+  - 0
+  version: 2.0.0
 platform: ruby
-authors:
+authors: 
 - Aaron Beckerman
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-31 00:00:00.000000000 Z
+
+date: 2024-03-12 00:00:00 -07:00
+default_executable: 
 dependencies: []
-description: Loaded Die makes it easy to choose randomly when some options are more
-  likely than others.
+
+description: 
 email: 
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - LICENSE.txt
-- README.rdoc
-- lib/loaded_die.rb
+- README.txt
 - loaded_die.gemspec
+- lib/loaded_die.rb
 - test/loaded_die_test.rb
+has_rdoc: true
 homepage: 
-licenses:
+licenses: 
 - MIT
-metadata: {}
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
-  requirements:
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
   - - ">="
-    - !ruby/object:Gem::Version
+    - !ruby/object:Gem::Version 
+      hash: 57
+      segments: 
+      - 1
+      - 8
+      - 7
       version: 1.8.7
-required_rubygems_version: !ruby/object:Gem::Requirement
-  requirements:
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
   - - ">="
-    - !ruby/object:Gem::Version
-      version: '0'
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 requirements: []
+
 rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 1.6.2
 signing_key: 
-specification_version: 4
-summary: A library for choosing randomly when some options are more likely than others.
-test_files:
+specification_version: 3
+summary: A library for choosing randomly where some options are more likely than others.
+test_files: 
 - test/loaded_die_test.rb

checksums.yaml

@@ -1,7 +0,0 @@
----
-SHA256:
-  metadata.gz: 362b5a5dc03dcbf3580aeb5501c964cb273a183ce9ab3763bc9840288f4e4b95
-  data.tar.gz: e5e901d9a0611c2579d33595569658d112736f89714655db4b161349c5f00d24
-SHA512:
-  metadata.gz: 5510423a7c21354514d3a035f77b7c518d2ed563ac315dc1d1ebba6f10459201416a5ed427cadb9c78c957a94a591a9766c75dabe8b15ca96911e8aed413350b
-  data.tar.gz: 5d8ccf6c0f9713cf6e1d3bf1b45ba63d7c026d7e41523e0c61211163815173cdeff20341b5c4518350674ecc0f67565de16f29dd1f063a7dc2d347e9084c01f7

data/README.rdoc

@@ -1,57 +0,0 @@
-= Loaded Die
-
-Loaded Die is a Ruby library that makes it easy to randomly choose from a set
-of options when some options are more likely than others.
-
-
-== Usage
-
-This is the basic pattern: First, you load the library. Then you create an
-instance of LoadedDie::Sampler and send the "sample" message to it as many
-times as you like.
-
-Let's say you want to choose randomly from three strings: "A", "B", and "C".
-You want "A" and "B" to be equally likely, and "C" to be twice as likely as one
-of them. That means "A" should be 25% likely, B should be 25% likely, and C
-should be 50% likely.
-
-You can create your sampler like this:
-
-  require 'loaded_die'
-  sampler = LoadedDie::Sampler.new('A' => 0.25, 'B' => 0.25, 'C' => 0.5)
-
-And then sample from it like this:
-
-  sampler.sample
-
-But you don't have to be fussy about how you represent probabilities. That is,
-you don't need to represent them as numbers between 0 and 1 such that they sum
-up to 1. Their relative values are what matter. So you could also create your
-sampler like this:
-
-  sampler = LoadedDie::Sampler.new('A' => 1, 'B' => 1, 'C' => 2)
-
-You can specify the random number generator that sample uses. To do this,
-supply as the argument a hash with your random number generator under the
-:random key. (This is based on the behavior of Ruby's Array#sample.) Your
-random number generator will be sent the "rand" message with one argument, the
-sum of the weights you specified when creating the sampler. The return value
-must be a number greater than or equal to zero and less than the sum of the
-weights.
-
-  rng = Object.new
-  def rng.rand(n)
-    0
-  end
-  sampler.sample(:random => rng)
-
-
-== Author
-
-This was written by Aaron Beckerman.
-
-
-== Copyright
-
-This code is distributed under the MIT License (also known as the Expat
-License). See the LICENSE.txt file for details.