Class: GamesDice::Die

Inherits:
Object
  • Object
show all
Defined in:
lib/games_dice/die.rb

Overview

This class models the simplest, most-familiar kind of die.

An object of the class represents a basic die that rolls 1..#sides, with equal weighting for each value.

Examples:

Create a 6-sided die, and roll it

d = GamesDice::Die.new( 6 )
d.roll # => Integer in range 1..6
d.result # => same Integer value as just returned by d.roll

Create a 10-sided die, that rolls using a monkey-patch to SecureRandom

module SecureRandom
  def self.rand n
    random_number( n )
  end
end
d = GamesDice::Die.new( 10, SecureRandom )
d.roll # => (secure) Integer in range 1..10
d.result # => same Integer value as just returned by d.roll

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(sides, prng = nil) ⇒ GamesDice::Die

Creates new instance of GamesDice::Die

Parameters:

  • sides (Integer) —

    the number of sides

  • prng (#rand) (defaults to: nil) —

    random number generator, GamesDice::Die will use Ruby's built-in #rand() by default

Raises:

  • (ArgumentError) 


28
29
30
31
32
33
34
35
 
# File 'lib/games_dice/die.rb', line 28

def initialize(sides, prng = nil)
  @sides = Integer(sides)
  raise ArgumentError, "sides value #{sides} is too low, it must be 1 or greater" if @sides < 1
  raise ArgumentError, 'prng does not support the rand() method' if prng && !prng.respond_to?(:rand)

  @prng = prng
  @result = nil
end

Instance Attribute Details

#maps ⇒ nil (readonly)

Rules for when to map return value of this die.

Returns:

  • (nil) —

    always nil, available for interface equivalence with GamesDice::ComplexDie



97
98
99
 
# File 'lib/games_dice/die.rb', line 97

def maps
  nil
end

#max ⇒ Integer (readonly)

Returns maximum possible result from a call to #roll.

Returns:

  • (Integer) —

    maximum possible result from a call to #roll



54
55
56
 
# File 'lib/games_dice/die.rb', line 54

def max
  @sides
end

#min ⇒ Integer (readonly)

Returns minimum possible result from a call to #roll.

Returns:

  • (Integer) —

    minimum possible result from a call to #roll



48
49
50
 
# File 'lib/games_dice/die.rb', line 48

def min
  1
end

#prng ⇒ Object (readonly)

Returns random number generator as supplied to constructor, may be nil.

Returns:

  • (Object) —

    random number generator as supplied to constructor, may be nil



44
45
46
 
# File 'lib/games_dice/die.rb', line 44

def prng
  @prng
end

#rerolls ⇒ nil (readonly)

Rules for when to re-roll this die.

Returns:

  • (nil) —

    always nil, available for interface equivalence with GamesDice::ComplexDie



90
91
92
 
# File 'lib/games_dice/die.rb', line 90

def rerolls
  nil
end

#result ⇒ Integer (readonly)

Returns result of last call to #roll, nil if no call made yet.

Returns:

  • (Integer) —

    result of last call to #roll, nil if no call made yet



41
42
43
 
# File 'lib/games_dice/die.rb', line 41

def result
  @result
end

#sides ⇒ Integer (readonly)

Returns number of sides on simulated die.

Returns:

  • (Integer) —

    number of sides on simulated die



38
39
40
 
# File 'lib/games_dice/die.rb', line 38

def sides
  @sides
end

Instance Method Details

#all_values ⇒ Array<Integer>

Returns All potential results from the die.

Returns:

  • (Array<Integer>) —

    All potential results from the die



83
84
85
 
# File 'lib/games_dice/die.rb', line 83

def all_values
  (1..@sides).to_a
end

#each_value {|result| ... } ⇒ GamesDice::Die

Iterates through all possible results on die.

Yield Parameters:

  • result (Integer) —

    A potential result from the die

Returns:



77
78
79
80
 
# File 'lib/games_dice/die.rb', line 77

def each_value(&)
  (1..@sides).each(&)
  self
end

#probabilities ⇒ GamesDice::Probabilities

Calculates probability distribution for this die.

Returns:



60
61
62
 
# File 'lib/games_dice/die.rb', line 60

def probabilities
  @probabilities ||= GamesDice::Probabilities.for_fair_die(@sides)
end

#roll ⇒ Integer

Simulates rolling the die

Returns:

  • (Integer) —

    selected value between 1 and #sides inclusive



66
67
68
69
70
71
72
 
# File 'lib/games_dice/die.rb', line 66

def roll
  @result = if @prng
              @prng.rand(@sides) + 1
            else
              rand(@sides) + 1
            end
end