dicey 0.15.2 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c18dbf421c9c19d438194ec9f63a9a22bfd18abb50d1f3b491a6e8067e3a04ae
-  data.tar.gz: e01eabaa58523f5fb2e1610ec671fc41a31f4aee7a583b64aa52d5bb9f083462
+  metadata.gz: 1b590b1e43f4e265f3a8fab12a949de1cdd20cc39b1f4334d997520cdbc9efc4
+  data.tar.gz: 2c0e3c4577a3f22483296b3a6c238c54937c8b5a360b21c53ca2d0b9aa432fcb
 SHA512:
-  metadata.gz: 48759bc7919e8dbf699777a92735c586a8365f517c2c12d48cb725f12ada1fcfd6904e2c08e54ec7159267ad79003e7a1725a1e6e97694d7d4cbfb32198b2566
-  data.tar.gz: fa0cd4f20b6262cf927eb98cb5c296db2473910a27e2500323f80aeb5d2ac3224de143f67e0990fe555890535ff395d8514996934759984316d9fe22c4fb0e17
+  metadata.gz: bed55910f504316de9f078f938f2a9a56e8dfbe65c3552eee330bc58f7559f699a0906837f4bda30fe098feed58469e8c7039e78864e79f4d263918729222ebb
+  data.tar.gz: 392b0c5c3b5e547d497092358769260b7b8e1c99bd98f1eb8759c389757386452720a173e619aea5bd2cebe996348c99f314bfc3b1e54fa068583fc083525cd9

data/README.md

@@ -24,6 +24,7 @@ In seriousness, this program is mainly useful for calculating total frequency (p
   - [Example 2: Complex distribution with different dice](#example-2-complex-distribution-with-different-dice)
   - [Example 3: Custom dice](#example-3-custom-dice)
   - [Example 4: Rolling even more custom dice](#example-4-rolling-even-more-custom-dice)
+  - [Example 5: Non-numeric dice](#example-5-non-numeric-dice)
   - [All ways to define dice](#all-ways-to-define-dice)
 - [Usage: API](#usage-api)
   - [Dice](#dice)
@@ -63,7 +64,17 @@ gem install dicey
 
 Or, if using Bundler, add it to your `Gemfile`:
 ```rb
-gem "dicey", "~> 0.14"
+gem "dicey", "~> 0.16"
+```
+
+(Optional) If intending to work with non-numeric dice, install **vector_number** too:
+```sh
+gem install vector_number
+```
+
+or add it to your `Gemfile`:
+```rb
+gem "vector_number"
 ```
 
 > [!TIP]
@@ -76,6 +87,7 @@ gem "dicey", "~> 0.14"
 
 **Dicey** is tested to work on CRuby 3.0+, latest JRuby and TruffleRuby. Compatible implementations should work too.
 - JSON and YAML formatting require `json` and `yaml`.
+- Non-numeric dice require gem `vector_number` to be installed.
 
 Otherwise, there are no direct dependencies.
 
@@ -238,18 +250,35 @@ roll => 7/2 # You probably will get a different value here.
 > [!NOTE]
 > 💡 Roll mode is compatible with `--format` option.
 
+### Example 5: Non-numeric dice
+
+You are a wizard and you have a spellbook with an elemental vortex spell that deals three instances of random elemental damage. Let's find out what you have for your enemies in store today:
+```sh
+$ dicey 3d❄️,🔥,⚡️,🌪,🌲 -m r
+# (❄️,🔥,⚡️,🌪,🌲)+(❄️,🔥,⚡️,🌪,🌲)+(❄️,🔥,⚡️,🌪,🌲)
+roll => 1⋅🌪 + 1⋅🌲 + 1⋅⚡️
+```
+
+Wind, wood and lightning in equal proportion it is! Your enemies will tremble!
+
+Regrettably, it is not possible to use elemental dice without installing **vector_number** gem first.
+
 ### All ways to define dice
 
-There are three *main* ways to define dice:
+There are four *main* ways to define dice:
 - *"5", "25", or "525"*: a single positive integer makes a regular die (like a D20).
 - *"3-6", "-5..5", "(0-1)"*: a pair of integers with a separator, possibly in round brackets, makes a numeric die with integers in the range.
   - Accepted separators: "-", "..", "...", "–" (en dash), "—" (em dash), "…" (ellipsis).
-- *"1,2,4", "(-1.5,0,1.5)", or "2,"*: a list of any numbers separated by commas, possibly in round brackets, makes an arbitrary numeric die.
+- *"1,2,4", "(-1.5,0,1.5)", or "2,"*: a list of any numbers separated by commas, possibly in round brackets, makes a custom numeric die.
   - Lists can end in a comma, allowing single-number lists.
+- *"1,1.5,Two", "(💚,🧡,💙,💜)" or "('1','(bracket)')"*: a list of strings and numbers separated by commas, possibly in round brackets, makes an arbitrary die.
+  - Lists can end in a comma, allowing single-string lists.
+  - Single (') or double (") quotes can be used to use other quotes and round brackets in the string. Otherwise, they are prohibited. Commas are always prohibited.
+  - Quotes can also be used to treat numbers as strings.
 
-*"D6", "d(-1,3)", or "d2..4"*: any definitions can be prefixed with "d" or "D". While this doesn't do anything on its own, it can be useful to not start a definition with "-".
+*"D6", "d(-1,3)", "d2..4", or "d💚,🧡"*: any definitions can be prefixed with "d" or "D". While this doesn't do anything on its own, it can be useful to not start a definition with "-".
 
-*"2D6", "5d-1,3", or "277D(2..4)"*: any definitions can be prefixed with "*N*d" or "*N*D", where *N* is a positive integer. This creates *N* copies of the die.
+*"2D6", "5d-1,3", "277D(2..4)", or "3d👑,♠️,♥️,♣️,♦️,⚓️"*: any definitions can be prefixed with "*N*d" or "*N*D", where *N* is a positive integer. This creates *N* copies of the die.
 
 ## Usage: API
 
@@ -260,7 +289,7 @@ There are three *main* ways to define dice:
 ### Dice
 
 There are 3 classes of dice currently:
-- `Dicey::AbstractDie` is the base class for other dice, but can be used on its own. It has no restrictions on values of sides. For now, it is *only* useful for rolling and can't be used for distribution calculations.
+- `Dicey::AbstractDie` is the base class for other dice, but can be used on its own. It has no restrictions on values of sides.
 - `Dicey::NumericDie` behaves much the same as `Dicey::AbstractDie` (being its subclass), except for checking that all values are instances of `Numeric`. It can be initialized with an Array or Range.
 - `Dicey::RegularDie` is a specialized subclass of `Dicey::NumericDie`. It is defined by a single integer *N* which is expanded to a range (1..*N*).
 
@@ -282,7 +311,7 @@ Dicey::DieFoundry.new.call("100")
 Dicey::DieFoundry.new.call("2d6")
   # same as Dicey::RegularDie.from_count(2, 6)
 Dicey::DieFoundry.new.call("1d1,2,4")
-  # same as Dicey::NumericDie.from_list([1,2,4])
+  # same as Dicey::NumericDie.from_count(1, [1,2,4])
 ```
 
 It only takes a single argument and may return both an array of dice and a single die. You will probably want to use `Enumerable#flat_map`:
@@ -292,6 +321,26 @@ foundry = Dicey::DieFoundry.new
   # same as [Dicey::RegularDie.new(8), *Dicey::RegularDie.from_count(2, 4)]
 ```
 
+#### Really custom dice
+
+It is easy enough to create numeric dice or dice with distinct symbols. However, what if a symbolic die is needed, but one which also has custom counts of symbols?
+
+For example, a game may have a die which can roll 1-3 💚 or a ♥️. You could just use completely different strings for the different numbers of hearts, but they would not be summable (what if you need to roll two such dice and add them together?). In this case, you can directly use `VectorNumber` to create summable strings:
+```rb
+# Using Symbols is not required, but they look nicer in output.
+# `DieFoundry` uses Symbols for this reason.
+heal = VectorNumber[:"💚"]
+regen = VectorNumber[:"♥️"]
+die = Dicey::AbstractDie.new([heal, heal * 2, heal * 3, regen])
+  # => #<Dicey::AbstractDie:0x00007f4a7c95efe8 @current_side_index=0, @sides_list=[(1⋅💚), (2⋅💚), (3⋅💚), (1⋅♥️)], @sides_num=4>
+```
+
+Now such dice can easily be rolled together and results summed:
+```rb
+die.roll + die.roll
+  # => (5⋅💚)
+```
+
 ### Rolling
 
 `Dicey::AbstractDie#roll` implements the rolling:
@@ -338,18 +387,18 @@ die.roll
 Distribution calculators live in `Dicey::SumFrequencyCalculators` module. There are four calculators currently:
 - `Dicey::SumFrequencyCalculators::KroneckerSubstitution` is the recommended calculator, able to handle all `Dicey::RegularDie`. It is very fast, calculating distribution for *100d6* in about 0.1 seconds on a laptop.
 - `Dicey::SumFrequencyCalculators::MultinomialCoefficients` is specialized for repeated numeric dice, with performance only slightly worse. However, it is currently limited to dice with arithmetic sequences.
-- `Dicey::SumFrequencyCalculators::BruteForce` is the most generic and slowest one, but can in principle work with any dice. Currently, it is also limited to `Dicey::NumericDie`, as it's unclear how to handle other values.
-- `Dicey::SumFrequencyCalculators::Empirical`. This is more of a tool than a calculator. It can be interesting to play around with and see how practical results compare to theoretical ones.
+- `Dicey::SumFrequencyCalculators::BruteForce` is the most generic and slowest one, but can work with *any* dice. It needs gem "**vector_number**" to be installed and available to work with non-numeric dice.
+- `Dicey::SumFrequencyCalculators::Empirical`... this is more of a tool than a calculator. It "calculates" probabilities by performing a large number of rolls and counting frequencies of outcomes. It can be interesting to play around with and see how practical results compare to theoretical ones. Due to its simplicity, it also works with *any* dice.
 
 Calculators inherit from `Dicey::SumFrequencyCalculators::BaseCalculator` and provide the following public interface:
 - `#call(dice, result_type: {:frequencies | :probabilities}, **options) : Hash`
 - `#valid_for?(dice) : Boolean`
 
-See [Diving deeper](#diving-deeper) for more details on limitations and complexity considerations.
+See [Diving deeper](#diving-deeper) for more details on limitations and complexity considerations of different algorithms.
 
 ### Distribution properties
 
-While distribution itself is already enough in most cases (we are talking just dice here, after all). it may be of interest to calculate properties of it: mode, mean, expected value, standard deviation, etc. `Dicey::DistributionPropertiesCalculator` already provides this functionality:
+While distribution itself is already enough in most cases (we are talking just dice here, after all). it may be of interest to calculate properties of it: mode, mean, expected value, standard deviation, etc. `Dicey::DistributionPropertiesCalculator` provides this functionality:
 ```rb
 Dicey::DistributionPropertiesCalculator.new.call(
   Dicey::SumFrequencyCalculators::KroneckerSubstitution.new.call(
@@ -358,18 +407,19 @@ Dicey::DistributionPropertiesCalculator.new.call(
 )
   # => 
   # {:mode=>[4],
-  # :min=>2,
-  # :max=>6,
-  # :total_range=>4,
-  # :mid_range=>4,
-  # :median=>4,
-  # :arithmetic_mean=>4,
-  # :expected_value=>4,
-  # :variance=>(4/3),
-  # :standard_deviation=>1.1547005383792515,
-  # :skewness=>0.0,
-  # :kurtosis=>(9/4),
-  # :excess_kurtosis=>(-3/4)}
+  #  :modes=>[[4]]
+  #  :min=>2,
+  #  :max=>6,
+  #  :total_range=>4,
+  #  :mid_range=>4,
+  #  :median=>4,
+  #  :arithmetic_mean=>4,
+  #  :expected_value=>4,
+  #  :variance=>(4/3),
+  #  :standard_deviation=>1.1547005383792515,
+  #  :skewness=>0.0,
+  #  :kurtosis=>(9/4),
+  #  :excess_kurtosis=>(-3/4)}
 ```
 
 Of course, for regular dice most properties are quite simple and predicatable due to symmetricity of distribution. It becomes more interesting with unfair, lopsided dice. Remember [Example 3](#example-3-custom-dice)?
@@ -381,21 +431,30 @@ Dicey::DistributionPropertiesCalculator.new.call(
 )
   # => 
   # {:mode=>[5],
-  # :min=>2,
-  # :max=>8,
-  # :total_range=>6,
-  # :mid_range=>5,
-  # :median=>5,
-  # :arithmetic_mean=>5,
-  # :expected_value=>(31/6),
-  # :variance=>(101/36),
-  # :standard_deviation=>1.674979270186815,
-  # :skewness=>-0.15762965389465178,
-  # :kurtosis=>(23145/10201),
-  # :excess_kurtosis=>(-7458/10201)}
+  #  :modes=>[[5]],
+  #  :min=>2,
+  #  :max=>8,
+  #  :total_range=>6,
+  #  :mid_range=>5,
+  #  :median=>5,
+  #  :arithmetic_mean=>5,
+  #  :expected_value=>(31/6),
+  #  :variance=>(101/36),
+  #  :standard_deviation=>1.674979270186815,
+  #  :skewness=>-0.15762965389465178,
+  #  :kurtosis=>(23145/10201),
+  #  :excess_kurtosis=>(-7458/10201)}
+```
+
+This disitrubution is obviosuly skewed (as can be immediately seen from non-zero skewness), with expected value no longer equal to mean. This is a mild example. It is easily possible to create a distribution with multiple local maxima or high skewness. For example, let's take two D2 and a weighted die to create a distribution with two peaks:
+```rb
+    [*Dicey::RegularDie.from_count(2, 2), Dicey::NumericDie.new([1,8,9])]
+  # => 
+  # {:mode=>[11, 12],
+  #  :modes=>[[4], [11, 12]],
 ```
 
-This disitrubution is obviosuly skewed (as can be immediately seen from non-zero skewness), with expected value no longer equal to mean. This is a mild example. It is easily possible to create a distribution with multiple local maxima and high skewness.
+You can see that 11 and 12 are the most likely outcomes, coming from a larger peak, but a smaller peak (with lower probability) is placed at 4.
 
 ## Diving deeper
 
@@ -418,7 +477,7 @@ Dicey is in principle able to handle any real numeric dice and some abstract dic
 Currently, three algorithms for calculating frequencies are implemented, with different possibilities and trade-offs.
 
 > [!NOTE]
-> 💡 Complexity is listed for `n` dice with at most `m` sides and has not been rigorously proven.
+> 💡 Complexity is listed for **n** dice with at most **m** sides and has not been rigorously proven.
 
 ### Kronecker substitution
 
@@ -426,7 +485,7 @@ An algorithm based on fast polynomial multiplication. This is the default algori
 
 - Limitations: only **natural** dice are allowed, including **regular** dice.
 - Example: `dicey 5 3,4,1 0,`
-- Complexity: `O(m⋅n)` where `m` is the highest value
+- Complexity: **O(m⋅n)** where **m** is the highest value
 
 ### Multinomial coefficients
 
@@ -434,15 +493,15 @@ This algorithm is based on raising a univariate polynomial to a power and using
 
 - Limitations: only *equal* **arithmetic** dice are allowed.
 - Example: `dicey 1.5,3,4.5,6 1.5,3,4.5,6 1.5,3,4.5,6`
-- Complexity: `O(m⋅n²)`
+- Complexity: **O(m⋅n²)**
 
 ### Brute force
 
 As a last resort, there is a brute force algorithm which goes through every possible dice roll and adds results together. While quickly growing terrible in performace, it has the largest input space, allowing to work with completely nonsensical dice, including aforementioned dice with complex numbers.
 
-- Limitations: objects on dice sides must be numbers.
+- Limitations: without **vector_number** all values must be numbers, otherwise almost any values are viable.
 - Example: `dicey 5 1,0.1,2 1,-1,1,-1,0`
-- Complexity: `O(mⁿ)`
+- Complexity: **O(mⁿ)**
 
 ## Development
 

data/lib/dicey/abstract_die.rb

@@ -2,7 +2,7 @@
 
 module Dicey
   # Asbtract die which may have an arbitrary list of sides,
-  # not even neccessarily numbers (but preferably so).
+  # not even neccessarily numbers, but strings or other objects.
   class AbstractDie
     # rubocop:disable Style/ClassVars
 
@@ -69,9 +69,11 @@ module Dicey
     # @param sides_list [Enumerable<Any>]
     # @raise [DiceyError] if +sides_list+ is empty
     def initialize(sides_list)
-      @sides_list = (Array === sides_list) ? sides_list.dup.freeze : sides_list.to_a.freeze
+      @sides_list = sides_list.to_a
+      @sides_list = @sides_list.dup if @sides_list.equal?(sides_list)
       raise DiceyError, "dice must have at least one side!" if @sides_list.empty?
 
+      @sides_list.freeze
       @sides_num = @sides_list.size
       @current_side_index = 0
     end
@@ -97,7 +99,7 @@ module Dicey
     #
     # @return [Any] rolled side
     def roll
-      @current_side_index = self.class.rand(0...@sides_num)
+      @current_side_index = self.class.rand(@sides_num)
       current
     end
 

data/lib/dicey/die_foundry.rb

@@ -3,27 +3,37 @@
 require_relative "numeric_die"
 require_relative "regular_die"
 
-require_relative "rational_to_integer"
+require_relative "mixins/rational_to_integer"
 
 module Dicey
   # Helper class to define die definitions and automatically select the best one.
   class DieFoundry
-    include RationalToInteger
+    include Mixins::RationalToInteger
 
     # Regexp for matching a possible count.
-    PREFIX = /(?>(?<count>[1-9]\d*+)?d)?+/i
+    PREFIX = /(?:(?<count>[1-9]\d*+)?+d)?+/i
+    # Regexp for an integer number.
+    INTEGER = /(?:-?\d++)/
+    # Regexp for a (possibly) fractional number.
+    DECIMAL = /(?:-?\d++(?:\.\d++)?)/
+    # Regexp for an "arbitrary" string.
+    STRING = /(?:(?<side>[^"',()]++)|"(?<side>[^",]++)"|'(?<side>[^',]++)')/
 
     # Possible molds for the dice. They are matched in the order as written.
     MOLDS = [
       # Positive integer goes into the RegularDie mold.
       [/\A#{PREFIX}(?<sides>[1-9]\d*+)\z/, :regular_mold].freeze,
       # Integer range goes into the NumericDie mold.
-      [/\A#{PREFIX}\(?(?<begin>-?\d++)(?>[-–—…]|\.{2,3})(?<end>-?\d++)\)?\z/, :range_mold].freeze,
+      [/\A#{PREFIX}\(?(?<begin>#{INTEGER})(?:[-–—…]|\.{2,3})(?<end>#{INTEGER})\)?\z/,
+       :range_mold].freeze,
       # List of numbers goes into the NumericDie mold.
-      [/\A#{PREFIX}\(?(?<sides>-?\d++(?>,(?>-?\d++)?)+|,)\)?\z/, :weirdly_shaped_mold].freeze,
+      [/\A#{PREFIX}\(?(?<sides>#{INTEGER}(?:(?:,#{INTEGER})++,?+|,))\)?\z/,
+       :weirdly_shaped_mold].freeze,
       # Non-integers require special handling for precision.
-      [/\A#{PREFIX}\(?(?<sides>-?\d++(?>\.\d++)?(?>,(?>-?\d++(?>\.\d++)?)?)+|,)\)?\z/,
+      [/\A#{PREFIX}\(?(?<sides>#{DECIMAL}(?:(?:,#{DECIMAL})++,?+|,))\)?\z/,
        :weirdly_precise_mold].freeze,
+      # Lists of stuff are broken into AbstractDie.
+      [/\A#{PREFIX}\(?(?<sides>#{STRING}(?:(?:,#{STRING})++,?+|,))\)?\z/, :cursed_mold].freeze,
       # Anything else is spilled on the floor.
     ].freeze
 
@@ -34,13 +44,16 @@ module Dicey
     # - integer range (like "3-6" or "(-5..5)"), which produces a {NumericDie};
     # - list of integers (like "3,4,5", "(-1,0,1)", or "2,"), which produces a {NumericDie};
     # - list of decimal numbers (like "0.5,0.2,0.8" or "(2.0,)"), which produces a {NumericDie},
-    #   but uses +Rational+ for values to maintain precise results.
+    #   but uses +Rational+ for values to maintain precise results;
+    # - list of strings, possibly mixed with numbers (like "0.5,asdf" or "(👑,♠️,♥️,♣️,♦️,⚓️)"),
+    #   which produces an {AbstractDie} with strings converted to Symbols
+    #   and numbers treated the same as in previous cases.
     #
     # Any die definition can be prefixed with a count, like "2D6" or "1d1,3,5" to create an array.
     # A plain "d" without an explicit count is ignored instead, creating a single die.
     #
     # @param definition [String] die shape
-    # @return [NumericDie, RegularDie, Array<NumericDie>, Array<RegularDie>]
+    # @return [AbstractDie, Array<AbstractDie>]
     # @raise [DiceyError] if no mold fits the definition
     def call(definition)
       matched, name =
@@ -77,6 +90,21 @@ module Dicey
       build_dice(NumericDie, definition[:count], sides)
     end
 
+    def cursed_mold(definition)
+      sides = definition[:sides].split(",")
+      sides.map! do |side|
+        case side
+        when /\A#{INTEGER}\z/o
+          side.to_i
+        when /\A#{DECIMAL}\z/o
+          rational_to_integer(Rational(side))
+        else
+          side.match(STRING)[:side].to_sym
+        end
+      end
+      build_dice(AbstractDie, definition[:count], sides)
+    end
+
     def build_dice(die_class, count, sides)
       if count
         die_class.from_count(count.to_i, sides)

data/lib/dicey/distribution_properties_calculator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "rational_to_integer"
+require_relative "mixins/rational_to_integer"
 
 module Dicey
   # Calculates distribution properties,
@@ -16,7 +16,7 @@ module Dicey
   # (median, mean, ...) are all equal.
   # Mode is often not unique, but includes this center.
   class DistributionPropertiesCalculator
-    include RationalToInteger
+    include Mixins::RationalToInteger
 
     # Calculate properties for a given distribution.
     #
@@ -27,7 +27,7 @@ module Dicey
     #
     # @param distribution [Hash{Numeric => Numeric}, Hash{Any => Numeric}]
     #   distribution with pre-sorted keys
-    # @return [Hash{Symbol => Numeric, Array<Numeric>, Array<Array<Numeric>>}]
+    # @return [Hash{Symbol => Any}]
     def call(distribution)
       return {} if distribution.empty?
 

data/lib/dicey/mixins/rational_to_integer.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Dicey
+  # @api private
+  # Various mixins with shared methods.
+  module Mixins
+    # Mix-in for converting rationals with denominator of 1 to integers.
+    module RationalToInteger
+      private
+
+      # Convert +value+ to +Integer+ if it's a +Rational+ with denominator of 1.
+      # Otherwise, return +value+ as-is.
+      #
+      # @value [Numeric, Any]
+      # @return [Numeric, Integer, Any]
+      def rational_to_integer(value)
+        (Rational === value && value.denominator == 1) ? value.numerator : value
+      end
+    end
+  end
+end

data/lib/dicey/mixins/vectorize_dice.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Dicey
+  module Mixins
+    # Mix-in for converting dice with non-numeric sides into dice with +VectorNumber+ sides.
+    module VectorizeDice
+      private
+
+      # Vectorize non-numeric sides for AbstractDie instances,
+      # leaving NumericDie instances unchanged.
+      #
+      # Check for VectorNumber availability *before* calling.
+      #
+      # @param dice [Array<AbstractDie>]
+      # @return [Array<AbstractDie>] a new array of dice
+      def vectorize_dice(dice)
+        dice.map do |die|
+          next die if NumericDie === die
+
+          sides =
+            die.sides_list.map do |side|
+              (Numeric === side || VectorNumber === side) ? side : VectorNumber.new([side])
+            end
+          die.class.new(sides)
+        end
+      end
+    end
+  end
+end

data/lib/dicey/numeric_die.rb

@@ -4,8 +4,12 @@ require_relative "abstract_die"
 
 module Dicey
   # A die which only has numeric sides, with no shenanigans.
+  #
+  # The only inherent difference in behavior compared to {AbstractDie} is
+  # that this class checks values for sides on initialization.
+  # However, other classes may reject {AbstractDie} even with all numeric sides.
   class NumericDie < AbstractDie
-    # @param sides_list [Enumerable<Numeric>]
+    # @param sides_list [Array<Numeric>, Range<Numeric>, Enumerable<Numeric>]
     # @raise [DiceyError] if +sides_list+ contains non-numerical values or is empty
     def initialize(sides_list)
       if Range === sides_list

data/lib/dicey/output_formatters/key_value_formatter.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../rational_to_integer"
+require_relative "../mixins/rational_to_integer"
 
 module Dicey
   module OutputFormatters
@@ -8,7 +8,7 @@ module Dicey
     # Can add an optional description into the result.
     # @abstract
     class KeyValueFormatter
-      include RationalToInteger
+      include Mixins::RationalToInteger
 
       # @param hash [Hash{Object => Object}]
       # @param description [String] text to add as a comment.

data/lib/dicey/regular_die.rb

@@ -4,6 +4,8 @@ require_relative "numeric_die"
 
 module Dicey
   # Regular die, which has N sides with numbers from 1 to N.
+  #
+  # As a subclass of {NumericDie}, enjoys its treatment.
   class RegularDie < NumericDie
     # @param max [Integer] maximum side / number of sides
     def initialize(max)

data/lib/dicey/roller.rb

@@ -1,13 +1,24 @@
 # frozen_string_literal: true
 
+# Try to load "vector_number" pre-emptively.
+begin
+  require "vector_number"
+rescue LoadError
+  # VectorNumber not available, sad
+end
+
 require_relative "die_foundry"
 
-require_relative "rational_to_integer"
+require_relative "mixins/rational_to_integer"
+require_relative "mixins/vectorize_dice"
 
 module Dicey
   # Let the dice roll!
+  #
+  # This is the implementation of roll mode for the CLI.
   class Roller
-    include RationalToInteger
+    include Mixins::RationalToInteger
+    include Mixins::VectorizeDice
 
     # @param arguments [Array<String>] die definitions
     # @param format [#call] formatter for output
@@ -17,9 +28,15 @@ module Dicey
       raise DiceyError, "no dice!" if arguments.empty?
 
       dice = arguments.flat_map { |definition| die_foundry.cast(definition) }
-      result = dice.sum(&:roll)
+      result = roll_dice(dice)
 
       format.call({ "roll" => rational_to_integer(result) }, AbstractDie.describe(dice))
+    rescue TypeError
+      warn <<~TEXT
+        Dice with non-numeric sides need gem "vector_number" to be present and available.
+        If this is intended, please install the gem.
+      TEXT
+      raise DiceyError, "can not roll dice with non-numeric sides!"
     end
 
     private
@@ -27,5 +44,10 @@ module Dicey
     def die_foundry
       @die_foundry ||= DieFoundry.new
     end
+
+    def roll_dice(dice)
+      dice = vectorize_dice(dice) if defined?(VectorNumber)
+      dice.sum(&:roll)
+    end
   end
 end

data/lib/dicey/sum_frequency_calculators/base_calculator.rb

@@ -27,7 +27,8 @@ module Dicey
 
       # @param dice [Enumerable<AbstractDie>]
       # @param result_type [Symbol] one of {RESULT_TYPES}
-      # @param options [Hash{Symbol => Any}] calculator-specific options
+      # @param options [Hash{Symbol => Any}] calculator-specific options,
+      #   refer to the calculator's documentation to see what it accepts
       # @return [Hash{Numeric => Numeric}] frequencies or probabilities for each outcome
       # @raise [DiceyError] if +result_type+ is invalid
       # @raise [DiceyError] if dice list is invalid for the calculator

data/lib/dicey/sum_frequency_calculators/brute_force.rb

@@ -1,44 +1,66 @@
 # frozen_string_literal: true
 
+# Try to load "vector_number" pre-emptively.
+begin
+  require "vector_number"
+rescue LoadError
+  # VectorNumber not available, sad
+end
+
 require_relative "base_calculator"
 
+require_relative "../mixins/vectorize_dice"
+
 module Dicey
   module SumFrequencyCalculators
-    # Calculator for a collection of {NumericDie} using exhaustive search (very slow).
+    # Calculator for a collection of {AbstractDie} using exhaustive search (very slow).
+    #
+    # If dice include non-numeric sides, gem +vector_number+ has to be installed.
     class BruteForce < BaseCalculator
+      include Mixins::VectorizeDice
+
       private
 
       def validate(dice)
-        dice.all?(NumericDie)
+        if defined?(VectorNumber) || dice.all?(NumericDie)
+          true
+        else
+          warn <<~TEXT
+            Dice with non-numeric sides need gem "vector_number" to be present and available.
+            If this is intended, please install the gem.
+          TEXT
+          false
+        end
       end
 
       def calculate(dice, **nil)
-        combine_dice_enumerators(dice).map(&:sum).tally
+        dice = vectorize_dice(dice) if defined?(VectorNumber)
+        combine_dice_enumerators(dice.map(&:sides_list)).map(&:sum).tally
       end
 
       if defined?(Enumerator::Product)
         # Get an enumerator which goes through all possible permutations of dice sides.
         #
-        # @param dice [Enumerable<NumericDie>]
-        # @return [Enumerator<Array<Numeric>>]
-        def combine_dice_enumerators(dice)
-          Enumerator::Product.new(*dice.map(&:sides_list))
+        # @param side_lists [Enumerable<Enumerable<Any>>]
+        # @return [Enumerator<Enumerable<Enumerable<Any>>>]
+        def combine_dice_enumerators(side_lists)
+          Enumerator::Product.new(*side_lists)
         end
       # :nocov:
       else
         # Get an enumerator which goes through all possible permutations of dice sides.
         #
-        # @param dice [Enumerable<NumericDie>]
-        # @return [Enumerator<Array<Numeric>>]
-        def combine_dice_enumerators(dice)
-          product(dice.map(&:sides_list))
+        # @param side_lists [Enumerable<Enumerable<Any>>]
+        # @return [Enumerator<Array<Array<Any>>>]
+        def combine_dice_enumerators(side_lists)
+          product(side_lists)
         end
 
         # Simplified implementation of {Enumerator::Product}.
         # Adapted from {https://bugs.ruby-lang.org/issues/18685#note-10}.
         #
-        # @param enums [Enumerable<Enumerable<Numeric>>]
-        # @return [Enumerator<Array<Numeric>>]
+        # @param enums [Enumerable<Enumerable<Any>>]
+        # @return [Enumerator<Array<Array<Any>>>]
         def product(enums, &block)
           return to_enum(__method__, enums) unless block_given?
 

data/lib/dicey/sum_frequency_calculators/empirical.rb

@@ -1,10 +1,19 @@
 # frozen_string_literal: true
 
+# Try to load "vector_number" pre-emptively.
+begin
+  require "vector_number"
+rescue LoadError
+  # VectorNumber not available, sad
+end
+
 require_relative "base_calculator"
 
+require_relative "../mixins/vectorize_dice"
+
 module Dicey
   module SumFrequencyCalculators
-    # "Calculator" for a collection of {NumericDie} using empirically-obtained statistics.
+    # "Calculator" for a collection of {AbstractDie} using empirically-obtained statistics.
     #
     # @note This calculator is mostly a joke. It can be useful for educational purposes,
     #   or to verify results of {BruteForce} when in doubt. It is not used by default.
@@ -12,19 +21,32 @@ module Dicey
     # Does a number of rolls and calculates approximate probabilities from that.
     # Even if frequencies are requested, results are non-integer.
     #
+    # If dice include non-numeric sides, gem +vector_number+ has to be installed.
+    #
     # *Options:*
     # - *rolls* (Integer) (_defaults_ _to:_ _N_) — number of rolls to perform
     class Empirical < BaseCalculator
+      include Mixins::VectorizeDice
+
       # Default number of rolls to perform.
       N = 10_000
 
       private
 
       def validate(dice)
-        dice.all?(NumericDie)
+        if defined?(VectorNumber) || dice.all?(NumericDie)
+          true
+        else
+          warn <<~TEXT
+            Dice with non-numeric sides need gem "vector_number" to be present and available.
+            If this is intended, please install the gem.
+          TEXT
+          false
+        end
       end
 
       def calculate(dice, rolls: N)
+        dice = vectorize_dice(dice) if defined?(VectorNumber)
         statistics = rolls.times.with_object(Hash.new(0)) { |_, hash| hash[dice.sum(&:roll)] += 1 }
         total_results = dice.map(&:sides_num).reduce(:*)
         statistics.transform_values { Rational(_1 * total_results, rolls) }

data/lib/dicey/sum_frequency_calculators/multinomial_coefficients.rb

@@ -11,6 +11,7 @@ module Dicey
     # Based on extension of Pascal's triangle for a higher number of coefficients.
     # @see https://en.wikipedia.org/wiki/Pascal's_triangle
     # @see https://en.wikipedia.org/wiki/Trinomial_triangle
+    # @see https://en.wikipedia.org/wiki/Multinomial_distribution
     class MultinomialCoefficients < BaseCalculator
       private
 

data/lib/dicey/sum_frequency_calculators/test_runner.rb

@@ -42,6 +42,25 @@ module Dicey
          { Complex(1, 1) => 1, Complex(2, 1) => 1, Complex(3, 1) => 1,
            Complex(1, 2) => 1, Complex(2, 2) => 1, Complex(3, 2) => 1,
            Complex(1, 3) => 1, Complex(2, 3) => 1, Complex(3, 3) => 1 }],
+        *(
+          # :nocov:
+          if defined?(VectorNumber)
+            # :nocov:
+            [
+              [[["s", "a", "d", 33]],
+               { VectorNumber["s"] => 1, VectorNumber["a"] => 1, VectorNumber["d"] => 1, 33 => 1 }],
+              [[%w[s a d], [0, 1, 2]],
+               { VectorNumber["s"] => 1, VectorNumber["s", 1] => 1, VectorNumber["s", 2] => 1,
+                 VectorNumber["a"] => 1, VectorNumber["a", 1] => 1, VectorNumber["a", 2] => 1,
+                 VectorNumber["d"] => 1, VectorNumber["d", 1] => 1, VectorNumber["d", 2] => 1 }],
+              [Array.new(2) { ["s", "a", 4] },
+               {
+                 VectorNumber["s"] * 2 => 1, VectorNumber["a"] * 2 => 1, 8 => 1,
+                 VectorNumber["s", "a"] => 2, VectorNumber["s", 4] => 2, VectorNumber["a", 4] => 2,
+               }],
+            ]
+          end
+        ),
       ].freeze
 
       # Strings for displaying test results.
@@ -84,7 +103,15 @@ module Dicey
       # @param definition [Array<Integer, Array<Integer>>]
       # @return [Array<NumericDie>]
       def build_dice(definition)
-        definition.map { _1.is_a?(Integer) ? RegularDie.new(_1) : NumericDie.new(_1) }
+        definition.map do |die_def|
+          if die_def.is_a?(Integer)
+            RegularDie.new(die_def)
+          elsif die_def.all?(Numeric)
+            NumericDie.new(die_def)
+          else
+            AbstractDie.new(die_def)
+          end
+        end
       end
 
       # Determine test result for the selected calculator.

data/lib/dicey/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dicey
-  VERSION = "0.15.2"
+  VERSION = "0.16.0"
 end

data/lib/dicey.rb

@@ -5,6 +5,7 @@ module Dicey
   # General error for Dicey.
   class DiceyError < StandardError; end
 
+  Dir["dicey/mixins/*.rb", base: __dir__].each { require_relative _1 }
   Dir["dicey/*.rb", base: __dir__].each { require_relative _1 }
   Dir["dicey/output_formatters/*.rb", base: __dir__].each { require_relative _1 }
   Dir["dicey/sum_frequency_calculators/*.rb", base: __dir__].each { require_relative _1 }

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: dicey
 version: !ruby/object:Gem::Version
-  version: 0.15.2
+  version: 0.16.0
 platform: ruby
 authors:
 - Alexandr Bulancov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-08 00:00:00.000000000 Z
-dependencies: []
+date: 2025-10-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: vector_number
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.3
 description: |
   Dicey provides a CLI executable and a Ruby API for fast calculation of
   frequency/probability distributions of dice rolls,
@@ -36,6 +50,8 @@ files:
 - lib/dicey/cli/options.rb
 - lib/dicey/die_foundry.rb
 - lib/dicey/distribution_properties_calculator.rb
+- lib/dicey/mixins/rational_to_integer.rb
+- lib/dicey/mixins/vectorize_dice.rb
 - lib/dicey/numeric_die.rb
 - lib/dicey/output_formatters/gnuplot_formatter.rb
 - lib/dicey/output_formatters/hash_formatter.rb
@@ -43,7 +59,6 @@ files:
 - lib/dicey/output_formatters/key_value_formatter.rb
 - lib/dicey/output_formatters/list_formatter.rb
 - lib/dicey/output_formatters/yaml_formatter.rb
-- lib/dicey/rational_to_integer.rb
 - lib/dicey/regular_die.rb
 - lib/dicey/roller.rb
 - lib/dicey/sum_frequency_calculators/base_calculator.rb
@@ -60,9 +75,9 @@ licenses:
 metadata:
   homepage_uri: https://github.com/trinistr/dicey
   bug_tracker_uri: https://github.com/trinistr/dicey/issues
-  documentation_uri: https://rubydoc.info/gems/dicey/0.15.2
-  source_code_uri: https://github.com/trinistr/dicey/tree/v0.15.2
-  changelog_uri: https://github.com/trinistr/dicey/blob/v0.15.2/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/dicey/0.16.0
+  source_code_uri: https://github.com/trinistr/dicey/tree/v0.16.0
+  changelog_uri: https://github.com/trinistr/dicey/blob/v0.16.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options:

data/lib/dicey/rational_to_integer.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Dicey
-  # @api private
-  # Mix-in for converting rationals with denominator of 1 to integers.
-  module RationalToInteger
-    private
-
-    # Convert +value+ to +Integer+ if it's a +Rational+ with denominator of 1.
-    # Otherwise, return +value+ as-is.
-    #
-    # @value [Numeric, Any]
-    # @return [Numeric, Integer, Any]
-    def rational_to_integer(value)
-      (Rational === value && value.denominator == 1) ? value.numerator : value
-    end
-  end
-end