games_dice 0.4.0 → 0.5.0

data/ext/games_dice/probabilities.c

@@ -21,7 +21,7 @@ VALUE Probabilities = Qnil;
 //  General utils
 //
 
-inline int max( int *a, int n ) {
+static int max( int *a, int n ) {
   int m = -1000000000;
   int i;
   for ( i=0; i < n; i++ ) {
@@ -30,7 +30,7 @@ inline int max( int *a, int n ) {
   return m;
 }
 
-inline int min( int *a, int n ) {
+static int min( int *a, int n ) {
   int m = 1000000000;
   int i;
   for ( i=0; i < n; i++ ) {
@@ -110,7 +110,7 @@ double num_arrangements( int *args, int nargs ) {
 //  Probability List basics - create, delete, copy
 //
 
-ProbabilityList *create_probability_list() {
+ProbabilityList *create_probability_list(void) {
   ProbabilityList *pl;
   pl = malloc (sizeof(ProbabilityList));
   if ( pl == NULL ) {
@@ -183,7 +183,7 @@ ProbabilityList *copy_probability_list( ProbabilityList *orig ) {
   return pl;
 }
 
-inline ProbabilityList *new_basic_pl( int nslots, double iv, int o ) {
+static ProbabilityList *new_basic_pl( int nslots, double iv, int o ) {
   ProbabilityList *pl = create_probability_list();
   alloc_probs_iv( pl, nslots, iv );
   pl->offset = o;
@@ -195,11 +195,13 @@ inline ProbabilityList *new_basic_pl( int nslots, double iv, int o ) {
 //  Probability List core "native" methods
 //
 
-inline int pl_min( ProbabilityList *pl ) {
+static double pl_p_le( ProbabilityList *pl, int target );
+
+static int pl_min( ProbabilityList *pl ) {
   return pl->offset;
 }
 
-inline int pl_max( ProbabilityList *pl ) {
+static int pl_max( ProbabilityList *pl ) {
   return pl->offset + pl->slots - 1;
 }
 
@@ -243,7 +245,7 @@ ProbabilityList *pl_add_distributions_mult( int mul_a, ProbabilityList *pl_a, in
   return pl;
 }
 
-inline double pl_p_eql( ProbabilityList *pl, int target ) {
+static double pl_p_eql( ProbabilityList *pl, int target ) {
   int idx = target - pl->offset;
   if ( idx < 0 || idx >= pl->slots ) {
     return 0.0;
@@ -251,15 +253,15 @@ inline double pl_p_eql( ProbabilityList *pl, int target ) {
   return (pl->probs)[idx];
 }
 
-inline double pl_p_gt( ProbabilityList *pl, int target ) {
+static double pl_p_gt( ProbabilityList *pl, int target ) {
   return 1.0 - pl_p_le( pl, target );
 }
 
-inline double pl_p_lt( ProbabilityList *pl, int target ) {
+static double pl_p_lt( ProbabilityList *pl, int target ) {
   return pl_p_le( pl, target - 1 );
 }
 
-inline double pl_p_le( ProbabilityList *pl, int target ) {
+static double pl_p_le( ProbabilityList *pl, int target ) {
   int idx = target - pl->offset;
   if ( idx < 0 ) {
     return 0.0;
@@ -270,11 +272,11 @@ inline double pl_p_le( ProbabilityList *pl, int target ) {
   return (pl->cumulative)[idx];
 }
 
-inline double pl_p_ge( ProbabilityList *pl, int target ) {
+static double pl_p_ge( ProbabilityList *pl, int target ) {
   return 1.0 - pl_p_le( pl, target - 1 );
 }
 
-inline double pl_expected( ProbabilityList *pl ) {
+static double pl_expected( ProbabilityList *pl ) {
   double t = 0.0;
   int o = pl->offset;
   int s = pl->slots;
@@ -426,7 +428,7 @@ void calc_keep_distributions( ProbabilityList *pl, int k, int q, int kbest, Prob
   return;
 }
 
-inline void clear_pl_array( int k, ProbabilityList **pl_array  ) {
+static void clear_pl_array( int k, ProbabilityList **pl_array  ) {
   int n;
   for ( n=0; n<k; n++) {
     if ( pl_array[n] != NULL ) {
@@ -515,23 +517,50 @@ ProbabilityList *pl_repeat_n_sum_k( ProbabilityList *pl, int n, int k, int kbest
 //  Ruby integration
 //
 
-inline VALUE pl_as_ruby_class( ProbabilityList *pl, VALUE klass ) {
-  return Data_Wrap_Struct( klass, 0, destroy_probability_list, pl );
+static void free_probability_list( void *ptr ) {
+  destroy_probability_list( ptr );
+}
+
+static size_t probability_list_memsize( const void *ptr ) {
+  const ProbabilityList *pl = ptr;
+  size_t size = sizeof(ProbabilityList);
+
+  if ( pl == NULL ) return 0;
+  if ( pl->probs != NULL ) size += pl->slots * sizeof(double);
+  if ( pl->cumulative != NULL ) size += pl->slots * sizeof(double);
+  return size;
+}
+
+static const rb_data_type_t probability_list_type = {
+  .wrap_struct_name = "GamesDice::Probabilities",
+  .function = {
+    .dmark = NULL,
+    .dfree = free_probability_list,
+    .dsize = probability_list_memsize,
+    .dcompact = NULL,
+    .reserved = { NULL }
+  },
+  .parent = NULL,
+  .data = NULL,
+  .flags = 0
+};
+
+static inline VALUE pl_as_ruby_class( ProbabilityList *pl, VALUE klass ) {
+  return TypedData_Wrap_Struct( klass, &probability_list_type, pl );
 }
 
 VALUE pl_alloc(VALUE klass) {
   return pl_as_ruby_class( create_probability_list(), klass );
 }
 
-inline ProbabilityList *get_probability_list( VALUE obj ) {
+static inline ProbabilityList *get_probability_list( VALUE obj ) {
   ProbabilityList *pl;
-  Data_Get_Struct( obj, ProbabilityList, pl );
+  TypedData_Get_Struct( obj, ProbabilityList, &probability_list_type, pl );
   return pl;
 }
 
 void assert_value_wraps_pl( VALUE obj ) {
-  if ( TYPE(obj) != T_DATA ||
-      RDATA(obj)->dfree != (RUBY_DATA_FUNC)destroy_probability_list) {
+  if ( ! rb_typeddata_is_kind_of( obj, &probability_list_type ) ) {
     rb_raise( rb_eTypeError, "Expected a Probabilities object, but got something else" );
   }
 }
@@ -574,6 +603,13 @@ int copy_key_value( VALUE key, VALUE val, VALUE obj ) {
 //  Ruby class and instance methods for Probabilities
 //
 
+/*
+ * @overload initialize(probs, offset)
+ *   Creates new instance of GamesDice::Probabilities.
+ *   @param [Array<Float>] probs Each entry in the array is the probability of getting a result
+ *   @param [Integer] offset The result associated with index of 0 in the array
+ *   @return [GamesDice::Probabilities]
+ */
 VALUE probabilities_initialize( VALUE self, VALUE arr, VALUE offset ) {
   int i, o, s;
   double error, p_item;
@@ -604,7 +640,11 @@ VALUE probabilities_initialize( VALUE self, VALUE arr, VALUE offset ) {
   return self;
 }
 
-
+/*
+ * @overload clone
+ *   Cloning an object of this class creates a deep copy of the probabilities hash.
+ *   @return [GamesDice::Probabilities]
+ */
 VALUE probabilities_initialize_copy( VALUE copy, VALUE orig ) {
   ProbabilityList *pl_copy;
   ProbabilityList *pl_orig;
@@ -622,6 +662,12 @@ VALUE probabilities_initialize_copy( VALUE copy, VALUE orig ) {
   return copy;
 }
 
+/*
+ * A hash representation of the distribution. Each key is an integer result,
+ * and the matching value is probability of getting that result. A new hash is generated on each
+ * call to this method.
+ * @return [Hash]
+ */
 VALUE probabilities_to_h( VALUE self ) {
   ProbabilityList *pl = get_probability_list( self );
   VALUE h = rb_hash_new();
@@ -637,56 +683,126 @@ VALUE probabilities_to_h( VALUE self ) {
   return h;
 }
 
+/*
+ * @overload min
+ *   @!attribute [r] min
+ *   Minimum result in the distribution
+ *   @return [Integer]
+ */
 VALUE probabilities_min( VALUE self ) {
   return INT2NUM( pl_min(  get_probability_list( self ) ) );
 }
 
+/*
+ * @overload max
+ *   @!attribute [r] max
+ *   Maximum result in the distribution
+ *   @return [Integer]
+ */
 VALUE probabilities_max( VALUE self ) {
   return INT2NUM( pl_max( get_probability_list( self ) ) );
 }
 
+/*
+ * Probability of result equalling specific target
+ * @param [Integer] target
+ * @return [Float] in range (0.0..1.0)
+ */
 VALUE probabilites_p_eql( VALUE self, VALUE target ) {
   return DBL2NUM( pl_p_eql( get_probability_list( self ), NUM2INT(target) ) );
 }
 
+/*
+ * Probability of result being greater than specific target
+ * @param [Integer] target
+ * @return [Float] in range (0.0..1.0)
+ */
 VALUE probabilites_p_gt( VALUE self, VALUE target ) {
   return DBL2NUM( pl_p_gt( get_probability_list( self ), NUM2INT(target) ) );
 }
 
+/*
+ * Probability of result being equal to or greater than specific target
+ * @param [Integer] target
+ * @return [Float] in range (0.0..1.0)
+ */
 VALUE probabilites_p_ge( VALUE self, VALUE target ) {
   return DBL2NUM( pl_p_ge( get_probability_list( self ), NUM2INT(target) ) );
 }
 
+/*
+ * Probability of result being equal to or less than specific target
+ * @param [Integer] target
+ * @return [Float] in range (0.0..1.0)
+ */
 VALUE probabilites_p_le( VALUE self, VALUE target ) {
   return DBL2NUM( pl_p_le( get_probability_list( self ), NUM2INT(target) ) );
 }
 
+/*
+ * Probability of result being less than specific target
+ * @param [Integer] target
+ * @return [Float] in range (0.0..1.0)
+ */
 VALUE probabilites_p_lt( VALUE self, VALUE target ) {
   return DBL2NUM( pl_p_lt( get_probability_list( self ), NUM2INT(target) ) );
 }
 
+/*
+ * @overload expected
+ *   @!attribute [r] expected
+ *   Expected value of distribution.
+ *   @return [Float]
+ */
 VALUE probabilites_expected( VALUE self ) {
   return DBL2NUM( pl_expected( get_probability_list( self ) ) );
 }
 
+/*
+ * Probability distribution derived from this one, where we know (or are only interested in
+ * situations where) the result is greater than or equal to target.
+ * @param [Integer] target
+ * @return [GamesDice::Probabilities] new distribution.
+ */
 VALUE probabilities_given_ge( VALUE self, VALUE target ) {
   int t = NUM2INT(target);
   ProbabilityList *pl = get_probability_list( self );
   return pl_as_ruby_class( pl_given_ge( pl, t ), Probabilities );
 }
 
+/*
+ * Probability distribution derived from this one, where we know (or are only interested in
+ * situations where) the result is less than or equal to target.
+ * @param [Integer] target
+ * @return [GamesDice::Probabilities] new distribution.
+ */
 VALUE probabilities_given_le( VALUE self, VALUE target ) {
   int t = NUM2INT(target);
   ProbabilityList *pl = get_probability_list( self );
   return pl_as_ruby_class( pl_given_le( pl, t ), Probabilities );
 }
 
+/*
+ * @overload repeat_sum(n)
+ *   Adds a distribution to itself repeatedly, to simulate a number of dice
+ *   results being summed.
+ *   @param [Integer] n Number of repetitions, must be at least 1
+ *   @return [GamesDice::Probabilities] new distribution
+ */
 VALUE probabilities_repeat_sum( VALUE self, VALUE nsum ) {
   int n = NUM2INT(nsum);
   ProbabilityList *pl = get_probability_list( self );
   return pl_as_ruby_class( pl_repeat_sum( pl, n ), Probabilities );
 }
 
+/* 
+ * @overload repeat_n_sum_k(n, k, kmode = :keep_best)
+ *   Calculates distribution generated by summing best k results of n iterations
+ *   of the distribution.
+ *   @param [Integer] n Number of repetitions, must be at least 1
+ *   @param [Integer] k Number of best results to keep and sum
+ *   @return [GamesDice::Probabilities] new distribution
+ */
 VALUE probabilities_repeat_n_sum_k( int argc, VALUE* argv, VALUE self ) {
   VALUE nsum, nkeepers, kmode;
   int keep_best, n, k;
@@ -709,6 +825,12 @@ VALUE probabilities_repeat_n_sum_k( int argc, VALUE* argv, VALUE self ) {
   return pl_as_ruby_class( pl_repeat_n_sum_k( pl, n, k, keep_best ), Probabilities );
 }
 
+/*  
+ * Iterates through value, probability pairs
+ * @yieldparam [Integer] result A result that may be possible in the dice scheme
+ * @yieldparam [Float] probability Probability of result, in range 0.0..1.0
+ * @return [GamesDice::Probabilities] this object
+ */
 VALUE probabilities_each( VALUE self ) {
   ProbabilityList *pl = get_probability_list( self );
   int i;
@@ -725,6 +847,11 @@ VALUE probabilities_each( VALUE self ) {
   return self;
 }
 
+/*
+ * Distribution for a die with equal chance of rolling 1..N
+ * @param [Integer] sides Number of sides on die
+ * @return [GamesDice::Probabilities]
+ */
 VALUE probabilities_for_fair_die( VALUE self, VALUE sides ) {
   int s = NUM2INT( sides );
   VALUE obj;
@@ -743,6 +870,13 @@ VALUE probabilities_for_fair_die( VALUE self, VALUE sides ) {
   return obj;
 }
 
+/* 
+ * @overload from_h(prob_hash)
+ *   Creates new instance of GamesDice::Probabilities.
+ *   @param [Hash] prob_hash A hash representation of the distribution, each key is an integer result,
+ *     and the matching value is probability of getting that result
+ *   @return [GamesDice::Probabilities]
+ */
 VALUE probabilities_from_h( VALUE self, VALUE hash ) {
   VALUE obj;
   ProbabilityList *pl;
@@ -773,9 +907,18 @@ VALUE probabilities_from_h( VALUE self, VALUE hash ) {
   return obj;
 }
 
+/*
+ * @overload add_distributions(pd_a, pd_b)
+ *   Combines two distributions to create a third, that represents the distribution created when adding
+ *   results together.
+ *   @param [GamesDice::Probabilities] pd_a First distribution
+ *   @param [GamesDice::Probabilities] pd_b Second distribution
+ *   @return [GamesDice::Probabilities]
+ */
 VALUE probabilities_add_distributions( VALUE self, VALUE gdpa, VALUE gdpb ) {
-  ProbabilityList *pl_a = get_probability_list( gdpa );
-  ProbabilityList *pl_b = get_probability_list( gdpb );
+  ProbabilityList *pl_a;
+  ProbabilityList *pl_b;
+
   assert_value_wraps_pl( gdpa );
   assert_value_wraps_pl( gdpb );
   pl_a = get_probability_list( gdpa );
@@ -783,6 +926,16 @@ VALUE probabilities_add_distributions( VALUE self, VALUE gdpa, VALUE gdpb ) {
   return pl_as_ruby_class( pl_add_distributions( pl_a, pl_b ), Probabilities );
 }
 
+/*
+ * @overload add_distributions_mult(m_a, pd_a, m_b, pd_b)
+ *   Combines two distributions with multipliers to create a third, that represents the distribution
+ *   created when adding weighted results together.
+ *   @param [Integer] m_a Weighting for first distribution
+ *   @param [GamesDice::Probabilities] pd_a First distribution
+ *   @param [Integer] m_b Weighting for second distribution
+ *   @param [GamesDice::Probabilities] pd_b Second distribution
+ *   @return [GamesDice::Probabilities]
+ */
 VALUE probabilities_add_distributions_mult( VALUE self, VALUE m_a, VALUE gdpa, VALUE m_b, VALUE gdpb ) {
   int mul_a, mul_b;
   ProbabilityList *pl_a;
@@ -797,17 +950,14 @@ VALUE probabilities_add_distributions_mult( VALUE self, VALUE m_a, VALUE gdpa, V
   return pl_as_ruby_class( pl_add_distributions_mult( mul_a, pl_a, mul_b, pl_b ), Probabilities );
 }
 
-VALUE probabilities_implemented_in( VALUE self ) {
-  return ID2SYM( rb_intern("c") );
-}
-
 ///////////////////////////////////////////////////////////////////////////////////////////////////
 //
 //  Setup Probabilities class for Ruby interpretter
 //
 
-void init_probabilities_class( VALUE ParentModule ) {
-  Probabilities = rb_define_class_under( ParentModule, "Probabilities", rb_cObject );
+void init_probabilities_class(void) {
+  VALUE GamesDice = rb_define_module("GamesDice");
+  Probabilities = rb_define_class_under( GamesDice, "Probabilities", rb_cObject );
   rb_define_alloc_func( Probabilities, pl_alloc );
   rb_define_method( Probabilities, "initialize", probabilities_initialize, 2 );
   rb_define_method( Probabilities, "initialize_copy", probabilities_initialize_copy, 1 );
@@ -828,7 +978,6 @@ void init_probabilities_class( VALUE ParentModule ) {
   rb_define_singleton_method( Probabilities, "for_fair_die", probabilities_for_fair_die, 1 );
   rb_define_singleton_method( Probabilities, "add_distributions", probabilities_add_distributions, 2 );
   rb_define_singleton_method( Probabilities, "add_distributions_mult", probabilities_add_distributions_mult, 4 );
-  rb_define_singleton_method( Probabilities, "implemented_in", probabilities_implemented_in, 0 );
   rb_define_singleton_method( Probabilities, "from_h", probabilities_from_h, 1 );
   return;
 }

data/ext/games_dice/probabilities.h

@@ -7,7 +7,7 @@
 
 #include <ruby.h>
 
-void init_probabilities_class( VALUE ParentModule );
+void init_probabilities_class(void);
 
 typedef struct _pd {
     int offset;
@@ -16,26 +16,10 @@ typedef struct _pd {
     double *cumulative;
   } ProbabilityList;
 
-inline int pl_min( ProbabilityList *pl );
-
-inline int pl_max( ProbabilityList *pl );
-
 ProbabilityList *pl_add_distributions( ProbabilityList *pl_a, ProbabilityList *pl_b );
 
 ProbabilityList *pl_add_distributions_mult( int mul_a, ProbabilityList *pl_a, int mul_b, ProbabilityList *pl_b );
 
-inline double pl_p_eql( ProbabilityList *pl, int target );
-
-inline double pl_p_gt( ProbabilityList *pl, int target );
-
-inline double pl_p_lt( ProbabilityList *pl, int target );
-
-inline double pl_p_le( ProbabilityList *pl, int target );
-
-inline double pl_p_ge( ProbabilityList *pl, int target );
-
-inline double pl_expected( ProbabilityList *pl );
-
 ProbabilityList *pl_given_ge( ProbabilityList *pl, int target );
 
 ProbabilityList *pl_given_le( ProbabilityList *pl, int target );

data/games_dice.gemspec

@@ -10,31 +10,23 @@ Gem::Specification.new do |gem|
   gem.version       = GamesDice::VERSION
   gem.authors       = ['Neil Slater']
   gem.email         = ['slobo777@gmail.com']
-  gem.description   = 'A library for simulating dice. Use it to construct dice-rolling systems used in role-playing and board games.'
-  gem.summary       = 'Simulates and explains dice rolls from simple "1d6" to complex "roll 7 ten-sided dice, take best 3,
-                        results of 10 roll again and add on".'
+  gem.description   = <<~GEMDESC
+    A library for simulating dice. Use it to construct dice-rolling systems used in role-playing and board games.
+  GEMDESC
+  gem.summary = <<~GEMSUMM
+    Simulates and explains dice rolls from simple "1d6" to complex "roll 7 ten-sided dice, take best 3,
+    results of 10 roll again and add on".
+  GEMSUMM
   gem.homepage      = 'https://github.com/neilslater/games_dice'
   gem.license       = 'MIT'
 
-  gem.required_ruby_version = '>= 2.6.0'
-  gem.add_development_dependency 'coveralls', '>= 0.6.7'
-  gem.add_development_dependency 'json', '>= 1.7.7'
-  gem.add_development_dependency 'rake', '>= 1.9.1'
-  gem.add_development_dependency 'rake-compiler', '>= 0.8.3'
-  gem.add_development_dependency 'rspec', '>= 2.13.0'
-  gem.add_development_dependency 'rubocop', '>= 1.2.1'
-  gem.add_development_dependency 'yard', '>= 0.8.6'
+  gem.required_ruby_version = '>= 3.3.0'
 
-  # Red Carpet renders README.md, and is optional even when developing the gem.
-  # However, it has a C extension, which will not work in JRuby. This only affects the gem build process, so
-  # is only really used in environments like Travis, and is safe to wrap like this in the gemspec.
-  gem.add_development_dependency 'redcarpet', '>=3.5.1' if RUBY_DESCRIPTION !~ /jruby/
+  gem.add_dependency 'parslet', '~> 2.0'
 
-  gem.add_dependency 'parslet', '>= 1.5.0'
-
-  gem.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  gem.files         = `git ls-files -z`.split("\0").select { |file| File.file?(file) }
   gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
   gem.extensions    = gem.files.grep(%r{/extconf\.rb$})
-  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ['lib']
+  gem.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/games_dice/bunch.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'games_dice/bunch_helpers'
+
 module GamesDice
   # This class models a number of identical dice, which may be either GamesDice::Die or
   # GamesDice::ComplexDie objects.
@@ -21,6 +23,9 @@ module GamesDice
   #  d.explain_result # => "4, 9, 2, 9, 1. Keep: 9 + 9 = 18"
   #
   class Bunch
+    include KeepHelpers
+    include ExplainHelpers
+
     # The constructor accepts parameters that are suitable for either GamesDice::Die or GamesDice::ComplexDie
     # and decides which of those classes to instantiate.
     # @param [Hash] options
@@ -28,8 +33,10 @@ module GamesDice
     # @option options [Integer] :sides Number of sides on a single die in the bunch, *mandatory*
     # @option options [String] :name Optional name for the bunch
     # @option options [Array<GamesDice::RerollRule,Array>] :rerolls Optional rules that cause the die to roll again
-    # @option options [Array<GamesDice::MapRule,Array>] :maps Optional rules to convert a value into a final result for the die
-    # @option options [#rand] :prng Optional alternative source of randomness to Ruby's built-in #rand, passed to GamesDice::Die's constructor
+    # @option options [Array<GamesDice::MapRule,Array>] :maps Optional rules to convert a value into a final result
+    #   for the die
+    # @option options [#rand] :prng Optional alternative source of randomness to Ruby's built-in #rand, passed to
+    #   GamesDice::Die's constructor
     # @option options [Symbol] :keep_mode Optional, either *:keep_best* or *:keep_worst*
     # @option options [Integer] :keep_number Optional number of dice to keep when :keep_mode is not nil
     # @return [GamesDice::Bunch]
@@ -138,26 +145,15 @@ module GamesDice
     # Simulates rolling the bunch of identical dice
     # @return [Integer] Sum of all rolled dice, or sum of all keepers
     def roll
-      @result = 0
-      @raw_result_details = []
+      generate_raw_results
+      return @result if !@keep_mode || @keep_number.to_i >= @ndice
 
-      @ndice.times do
-        @result += @single_die.roll
-        @raw_result_details << @single_die.result
-      end
-
-      return @result unless @keep_mode
-
-      use_dice = if @keep_mode && @keep_number < @ndice
-                   case @keep_mode
-                   when :keep_best then @raw_result_details.sort[-@keep_number..]
-                   when :keep_worst then @raw_result_details.sort[0..(@keep_number - 1)]
-                   end
-                 else
-                   @raw_result_details
+      use_dice = case @keep_mode
+                 when :keep_best then @raw_result_details.sort[-@keep_number..]
+                 when :keep_worst then @raw_result_details.sort[0..(@keep_number - 1)]
                  end
 
-      @result = use_dice.inject(0) { |so_far, die_result| so_far + die_result }
+      @result = use_dice.sum
     end
 
     # @!attribute [r] explain_result
@@ -166,44 +162,25 @@ module GamesDice
     def explain_result
       return nil unless @result
 
-      explanation = ''
-
       # With #keep_mode, we may need to show unused and used dice separately
       used_dice = result_details
-      unused_dice = []
-
-      # Pick highest numbers and their associated details
-      if @keep_mode && @keep_number < @ndice
-        full_dice = result_details.sort_by(&:total)
-        case @keep_mode
-        when :keep_best
-          used_dice = full_dice[-@keep_number..]
-          unused_dice = full_dice[0..full_dice.length - 1 - @keep_number]
-        when :keep_worst
-          used_dice = full_dice[0..(@keep_number - 1)]
-          unused_dice = full_dice[@keep_number..(full_dice.length - 1)]
-        end
-      end
-
-      # Show unused dice (if any)
-      if @keep_mode || @single_die.maps
-        explanation += result_details.map(&:explain_value).join(', ')
-        if @keep_mode
-          separator = @single_die.maps ? ', ' : ' + '
-          explanation += ". Keep: #{used_dice.map(&:explain_total).join(separator)}"
-        end
-        explanation += ". Successes: #{@result}" if @single_die.maps
-        explanation += " = #{@result}" if @keep_mode && !@single_die.maps && @keep_number > 1
-      else
-        explanation += used_dice.map(&:explain_value).join(' + ')
-        explanation += " = #{@result}" if @ndice > 1
-      end
+      used_dice, = find_used_dice_due_to_keep_mode(result_details) if @keep_mode && @keep_number < @ndice
 
-      explanation
+      build_explanation(used_dice)
     end
 
     private
 
+    def generate_raw_results
+      @result = 0
+      @raw_result_details = []
+
+      @ndice.times do
+        @result += @single_die.roll
+        @raw_result_details << @single_die.result
+      end
+    end
+
     def name_number_sides_from_hash(options)
       @name = options[:name].to_s
       @ndice = Integer(options[:ndice])
@@ -213,21 +190,6 @@ module GamesDice
       raise ArgumentError, ":sides must be 1 or more, but got #{@sides}" unless @sides.positive?
     end
 
-    def keep_mode_from_hash(options)
-      case options[:keep_mode]
-      when nil
-        @keep_mode = nil
-      when :keep_best
-        @keep_mode = :keep_best
-        @keep_number = Integer(options[:keep_number] || 1)
-      when :keep_worst
-        @keep_mode = :keep_worst
-        @keep_number = Integer(options[:keep_number] || 1)
-      else
-        raise ArgumentError, ":keep_mode can be nil, :keep_best or :keep_worst. Got #{options[:keep_mode].inspect}"
-      end
-    end
-
     def complex_die_params_from_hash(options)
       cd_hash = {}
       %i[maps rerolls].each do |k|