loaded_die 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 362b5a5dc03dcbf3580aeb5501c964cb273a183ce9ab3763bc9840288f4e4b95
-  data.tar.gz: e5e901d9a0611c2579d33595569658d112736f89714655db4b161349c5f00d24
+  metadata.gz: b04718fe3728aa1a6f354e81eed37708842a79fb62b6151f6d9a2823bccd603e
+  data.tar.gz: a6993994255411fdcd889aab140e8c8a1cb8453fad9ad44fb972076330409534
 SHA512:
-  metadata.gz: 5510423a7c21354514d3a035f77b7c518d2ed563ac315dc1d1ebba6f10459201416a5ed427cadb9c78c957a94a591a9766c75dabe8b15ca96911e8aed413350b
-  data.tar.gz: 5d8ccf6c0f9713cf6e1d3bf1b45ba63d7c026d7e41523e0c61211163815173cdeff20341b5c4518350674ecc0f67565de16f29dd1f063a7dc2d347e9084c01f7
+  metadata.gz: 52d5caf5851d300a185600d5a6e00203bebf672913a78ab42ca4430a369b5d690033fd679ccbef1df8abac7bbdd6c63e77d8f04067f4445142caf4b052e0850c
+  data.tar.gz: 2d896e03013c765bfe6beec383ffa456e9e4c199573d8b77900d3a7badef92f70d0a90a49e467317b98308b6779246c34e52401aec1d602b7e59e844071ab94b

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2018 Aaron Beckerman
+Copyright (c) 2022 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.rdoc

@@ -1,7 +1,7 @@
 = 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.
+of options where some options are more likely than others.
 
 
 == Usage
@@ -33,8 +33,8 @@ sampler like this:
 
 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
++: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 return value
 must be a number greater than or equal to zero and less than the sum of the
 weights.

data/lib/loaded_die.rb

@@ -1,14 +1,42 @@
+##
+# This module provides a class for randomly choosing from a set of options
+# where some options are more likely than others.
+#
 module LoadedDie
-  VERSION = '1.0.1'
 
+  ##
+  # The version string.
+  #
+  VERSION = '1.0.2'
+
+  ##
+  # Objects 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.
+    #
     DEFAULT_RNG = ::Object.new
     def DEFAULT_RNG.rand(n)
       ::Kernel.rand * n
     end
 
+    ##
+    # A class representing a segment of the number line with an associated
+    # individual.
+    #
     Segment = ::Struct.new(:maximum, :individual)
 
+    ##
+    # Creates a sampler from a population. The argument should be an enumerable
+    # of two-element arrays (a hash qualifies). The first element of each array
+    # is an individual that can be chosen; the second element is its weight --
+    # that is, the likelihood (relative to the other weights) that the
+    # individual will be chosen. Weights must be positive numbers.
+    #
     def initialize(population)
       @compiled = population.inject [] do |accum, (individual, weight)|
         if weight <= 0
@@ -25,6 +53,9 @@ module LoadedDie
       nil
     end
 
+    ##
+    # Returns the sum of weights.
+    #
     def length
       if last = @compiled.last
         last.maximum
@@ -33,6 +64,12 @@ module LoadedDie
       end
     end
 
+    ##
+    # Returns the individual for the given point. The point should be a number.
+    # 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)
       if point < 0
         nil
@@ -43,6 +80,14 @@ module LoadedDie
       end
     end
 
+    ##
+    # 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 greater than or equal to zero and less than the
+    # sum of weights.
+    #
     def sample(options = {})
       rng = options.fetch(:random) { DEFAULT_RNG }
       point = rng.rand(length)

data/loaded_die.gemspec

@@ -7,8 +7,8 @@ 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.summary = %q{A library for choosing randomly where some options are more likely than others.}
+  s.description = %q{Loaded Die is a library that makes it easy to choose randomly from a set of options where some options are more likely than others.}
   s.license = "MIT"
   s.platform = Gem::Platform::RUBY
   s.required_ruby_version = ">= 1.8.7"

data/test/loaded_die_test.rb

@@ -27,11 +27,9 @@ lambda do
   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
+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
 
 lambda do
   sampler = LoadedDie::Sampler.new({})

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: loaded_die
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Aaron Beckerman
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-31 00:00:00.000000000 Z
+date: 2022-12-01 00:00:00.000000000 Z
 dependencies: []
-description: Loaded Die makes it easy to choose randomly when some options are more
-  likely than others.
+description: Loaded Die is a library that makes it easy to choose randomly from a
+  set of options where some options are more likely than others.
 email: 
 executables: []
 extensions: []
@@ -41,10 +41,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
-summary: A library for choosing randomly when some options are more likely than others.
+summary: A library for choosing randomly where some options are more likely than others.
 test_files:
 - test/loaded_die_test.rb