dicey 0.15.2 → 0.16.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c18dbf421c9c19d438194ec9f63a9a22bfd18abb50d1f3b491a6e8067e3a04ae
-  data.tar.gz: e01eabaa58523f5fb2e1610ec671fc41a31f4aee7a583b64aa52d5bb9f083462
+  metadata.gz: 86d934c5cf9455e15c42f84abe397c7c32ada670512969decd4e44c9eef1841f
+  data.tar.gz: bcba52a9d0e1bbb0308db1025ba2c723bf963aa02b323b631538bdbc722144e2
 SHA512:
-  metadata.gz: 48759bc7919e8dbf699777a92735c586a8365f517c2c12d48cb725f12ada1fcfd6904e2c08e54ec7159267ad79003e7a1725a1e6e97694d7d4cbfb32198b2566
-  data.tar.gz: fa0cd4f20b6262cf927eb98cb5c296db2473910a27e2500323f80aeb5d2ac3224de143f67e0990fe555890535ff395d8514996934759984316d9fe22c4fb0e17
+  metadata.gz: 46d142b6caed4432f4adede2d34214498e1bbfe02aadca4aaa58709c5fa9ce15d4c71e75ce37f599752c10f334da0acb616c7278ba5076d1ed4746b36fb7b35b
+  data.tar.gz: 14ad44e95941c5e7d94c71968a9f84105d1f6a64b50ab551c94ddea247dda77a80e5f83e2566bdea76ec912b799f1a05e3bbb160d0cc1b3af5211c795bc2b415

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:
@@ -336,20 +385,22 @@ die.roll
 ### Distribution calculators
 
 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::KroneckerSubstitution` is the recommended calculator, able to handle all `Dicey::RegularDie` and more. It is very fast, though sometimes slower than the next one.
+- `Dicey::SumFrequencyCalculators::MultinomialCoefficients` is specialized for repeated numeric dice, with performance on par with the previous one, depending on exact parameters. However, it is currently limited to dice with arithmetic sequences (this includes regular dice, however).
+- `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.
+
+When in doubt which calculator to use (and if a given one *can* be used), use `Dicey::SumFrequencyCalculators::AutoSelector`. Its `#call(dice)` method will return a valid calculator for the given dice or `nil` if none are acceptable.
 
 ### 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 +409,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 +433,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
 
@@ -405,10 +466,10 @@ For a further discussion of calculations, it is important to understand which cl
 > [!TIP]
 > 💡 If you only need to roll **regular** dice, this section will not contain anything important.
 
-- **Natural** die has sides with only positive integers or 0. For example, (1,2,3,4,5,6), (5,1,6,5), (1,10000), (1,1,1,1,1,1,1,0).
+- **Integer** die has sides with only integers. For example, (1,2,3,4,5,6), (-5,0,5), (1,10000), (1,1,1,1,1,1,1,0).
 - **Arithmetic** die's sides form an arithmetic sequence. For example, (1,2,3,4,5,6), (1,0,-1), (2.6,2.1,1.6,1.1).
 - **Numeric** die is limited by having sides confined to ℝ (or ℂ if you are feeling particularly adventurous).
-- **Abstract** die is not limited by anything other than not having partial sides (and how would that work anyway?).
+- **Abstract** die is unlimited!
 
 > [!NOTE]
 > 💡 If your die definition starts with a negative number, it can be bracketed, prefixed with "d", or put after "--" pseudo-argument to avoid processing as an option.
@@ -418,31 +479,40 @@ 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 is only an approximation.
 
 ### Kronecker substitution
 
 An algorithm based on fast polynomial multiplication. This is the default algorithm, used for most reasonable dice.
 
-- Limitations: only **natural** dice are allowed, including **regular** dice.
+- Limitations: only **integer** 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(n<sup>3</sup>⋅m<sup>2</sup>)**
+- Running time examples:
+  - 6d1000 — 0.5 seconds
+  - 1000d6 — 18 seconds
 
 ### Multinomial coefficients
 
-This algorithm is based on raising a univariate polynomial to a power and using the coefficients of the result, though certain restrictions are lifted as they don't actually matter for the calculation.
+This algorithm is based on raising a univariate polynomial to a power and using the coefficients of the result, though certain restrictions are lifted as they don't actually matter for the calculation. It is usually faster than Kronecker substitution for many dice with few sides.
 
 - 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(n<sup>2</sup>⋅m<sup>2</sup>)**
+- Running time examples:
+  - 6d1000 — 1.65 seconds
+  - 1000d6 — 10.5 seconds
 
 ### 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.
+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 (and memory usage), it has the largest input space, allowing to work with completely nonsensical dice, including complex numbers and altogether non-numeric values.
 
-- Limitations: objects on dice sides must be numbers.
-- Example: `dicey 5 1,0.1,2 1,-1,1,-1,0`
-- Complexity: `O(mⁿ)`
+- Limitations: without **vector_number** all values must be numbers, otherwise almost any values are viable.
+- Example: `dicey 5 1,0.1,2 A,B,C`
+- Complexity: **O(m<sup>n</sup>)**
+- Running time examples:
+  - 6d10 — 0.25 seconds
+  - 10d6 — 9.5 seconds
 
 ## 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/cli/blender.rb

@@ -10,13 +10,6 @@ module Dicey
     # Slice and dice everything in the Dicey module to produce a useful result.
     # This is the entry point for the CLI.
     class Blender
-      # List of calculators to use, ordered by efficiency.
-      ROLL_FREQUENCY_CALCULATORS = [
-        SumFrequencyCalculators::KroneckerSubstitution.new,
-        SumFrequencyCalculators::MultinomialCoefficients.new,
-        SumFrequencyCalculators::BruteForce.new,
-      ].freeze
-
       # How to transform option values from command-line arguments
       # to internally significant objects.
       OPTION_TRANSFORMATIONS = {
@@ -27,6 +20,7 @@ module Dicey
           "gnuplot" => OutputFormatters::GnuplotFormatter.new,
           "yaml" => OutputFormatters::YAMLFormatter.new,
           "json" => OutputFormatters::JSONFormatter.new,
+          "null" => OutputFormatters::NullFormatter.new,
         }.freeze,
       }.freeze
 
@@ -47,7 +41,6 @@ module Dicey
       def call(argv = ARGV)
         options, arguments = get_options_and_arguments(argv)
         require_optional_libraries(options)
-        options[:roll_calculators] = ROLL_FREQUENCY_CALCULATORS
         return_value = RUNNERS[options.delete(:mode)].call(arguments, **options)
         print return_value if return_value.is_a?(String)
         !!return_value

data/lib/dicey/cli/options.rb

@@ -11,7 +11,7 @@ module Dicey
       # Allowed result types (--result).
       RESULT_TYPES = %w[frequencies probabilities].freeze
       # Allowed output formats (--format).
-      FORMATS = %w[list gnuplot json yaml].freeze
+      FORMATS = %w[list gnuplot json yaml null].freeze
 
       # Default values for initial values of the options.
       DEFAULT_OPTIONS = { mode: "frequencies", format: "list", result: "frequencies" }.freeze

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.
+      #
+      # @param 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,30 @@
+# frozen_string_literal: true
+
+module Dicey
+  # @api private
+  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/output_formatters/null_formatter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Dicey
+  module OutputFormatters
+    # Formatter that doesn't format anything and always returns an empty string.
+    class NullFormatter
+      # @param hash [Hash{Object => Object}]
+      # @param description [String] text to add as a comment.
+      # @return [String] always an empty string
+      def call(hash, description = nil) # rubocop:disable Lint/UnusedMethodArgument
+        ""
+      end
+    end
+  end
+end

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

@@ -2,12 +2,16 @@
 
 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 +21,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 +37,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/auto_selector.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "brute_force"
+require_relative "kronecker_substitution"
+require_relative "multinomial_coefficients"
+
+module Dicey
+  module SumFrequencyCalculators
+    # Tool to automatically select a calculator for a given set of dice.
+    #
+    # Calculator is guaranteed to be compatible, with a strong chance of being the most performant.
+    #
+    # @see BaseCalculator#heuristic_complexity
+    class AutoSelector
+      # Calculators to consider when selecting a match.
+      AVAILABLE_CALCULATORS = [
+        KroneckerSubstitution.new,
+        MultinomialCoefficients.new,
+        BruteForce.new,
+      ].freeze
+
+      # @param calculators [Array<BaseCalculator>]
+      #   calculators which this instance will consider
+      def initialize(calculators = AVAILABLE_CALCULATORS)
+        @calculators = calculators
+      end
+
+      # Determine best (or adequate) calculator for a given set of dice
+      # based on heuristics from the list of available calculators.
+      #
+      # @param dice [Enumerable<NumericDie>]
+      # @return [BaseCalculator, nil] +nil+ if no calculator is compatible
+      def call(dice)
+        compatible = @calculators.select { _1.valid_for?(dice) }
+        return if compatible.empty?
+
+        compatible.min_by { _1.heuristic_complexity(dice) }
+      end
+    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
@@ -54,6 +55,16 @@ module Dicey
         dice.is_a?(Enumerable) && dice.all?(AbstractDie) && validate(dice)
       end
 
+      # Heuristic complexity of the calculator, used to determine best calculator.
+      #
+      # @see AutoSelector
+      #
+      # @param dice [Enumerable<AbstractDie>]
+      # @return [Integer]
+      def heuristic_complexity(dice)
+        calculate_heuristic(dice.length, dice.map(&:sides_num).max).to_i
+      end
+
       private
 
       # Do additional validation on the dice list.
@@ -62,12 +73,19 @@ module Dicey
         true
       end
 
+      # Calculate heuristic complexity of the calculator.
+      #
+      # @param dice_count [Integer]
+      # @param sides_count [Integer] maximum number of sides
+      # @return [Numeric]
+      def calculate_heuristic(dice_count, sides_count)
+        raise NotImplementedError
+      end
+
       # Peform frequencies calculation.
       # (see #call)
       def calculate(dice, **nil)
-        # :nocov:
         raise NotImplementedError
-        # :nocov:
       end
 
       # Check that resulting frequencies actually add up to what they are supposed to be.

data/lib/dicey/sum_frequency_calculators/brute_force.rb

@@ -2,55 +2,40 @@
 
 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
+      def calculate_heuristic(dice_count, sides_count)
+        1000 * (sides_count**dice_count)
       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))
-        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))
-        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>>]
-        def product(enums, &block)
-          return to_enum(__method__, enums) unless block_given?
-
-          enums
-            .reverse
-            .reduce(block) { |inner, enum|
-              ->(values) { enum.each_entry { inner.call([*values, _1]) } }
-            }
-            .call([])
-        end
+      def calculate(dice, **nil)
+        dice = vectorize_dice(dice) if defined?(VectorNumber)
+        dice.map(&:sides_list).reduce { |result, die|
+          result.flat_map { |roll| die.map { |side| roll + side } }
+        }.tally
       end
-      # :nocov:
     end
   end
 end

data/lib/dicey/sum_frequency_calculators/empirical.rb

@@ -2,9 +2,11 @@
 
 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 +14,36 @@ 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_heuristic(dice_count, sides_count)
+        N * dice_count * Math.log2(sides_count)
       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/kronecker_substitution.rb

@@ -4,9 +4,9 @@ require_relative "base_calculator"
 
 module Dicey
   module SumFrequencyCalculators
-    # Calculator for lists of dice with non-negative integer sides (fast).
+    # Calculator for lists of dice with integer sides (fast).
     #
-    # Example dice: (1,2,3,4), (0,1,5,6), (5,4,5,4,5).
+    # Example dice: (1,2,3,4), (0,1,-5,6), (5,4,5,4,5).
     #
     # Based on Kronecker substitution method for polynomial multiplication.
     # @see https://en.wikipedia.org/wiki/Kronecker_substitution
@@ -17,15 +17,19 @@ module Dicey
       private
 
       def validate(dice)
-        dice.all? { |die| die.sides_list.all? { _1.is_a?(Integer) && _1 >= 0 } }
+        dice.all? { |die| die.sides_list.all?(Integer) }
+      end
+
+      def calculate_heuristic(dice_count, sides_count)
+        (dice_count**3.2) * 100 * (sides_count**1.9)
       end
 
       def calculate(dice, **nil)
-        polynomials = build_polynomials(dice)
+        polynomials, offset = build_polynomials(dice)
         evaluation_point = find_evaluation_point(polynomials)
         values = evaluate_polynomials(polynomials, evaluation_point)
         product = values.reduce(:*)
-        extract_coefficients(product, evaluation_point)
+        extract_coefficients(product, evaluation_point, offset, polynomials.count)
       end
 
       # Turn dice into hashes where keys are side values and values are numbers of those sides,
@@ -35,7 +39,8 @@ module Dicey
       # @param dice [Enumerable<NumericDie>]
       # @return [Array<Hash{Integer => Integer}>]
       def build_polynomials(dice)
-        dice.map { _1.sides_list.tally }
+        minimum = dice.map { |die| die.sides_list.min }.min
+        [dice.map { |die| die.sides_list.map { _1 - minimum }.tally }, minimum]
       end
 
       # Find a power of 2 which is larger in magnitude than any resulting polynomial coefficients,
@@ -67,13 +72,15 @@ module Dicey
       #
       # @param product [Integer]
       # @param evaluation_point [Integer]
+      # @param offset [Integer]
+      # @param number_of_dice [Integer]
       # @return [Hash{Integer => Integer}]
-      def extract_coefficients(product, evaluation_point)
+      def extract_coefficients(product, evaluation_point, offset, number_of_dice)
         window = evaluation_point - 1
         window_shift = window.bit_length
         (0..).each_with_object({}) do |power, result|
           coefficient = product & window
-          result[power] = coefficient unless coefficient.zero?
+          result[power + (offset * number_of_dice)] = coefficient unless coefficient.zero?
           product >>= window_shift
           break result if product.zero?
         end

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
 
@@ -33,6 +34,12 @@ module Dicey
         true
       end
 
+      def calculate_heuristic(dice_count, sides_count)
+        # Fitting shows both coefficients to be around 500,
+        # but empirical runtime doesn't agree, so 150 it is.
+        150 * (dice_count**2.2) * 500 * (sides_count**1.9)
+      end
+
       def calculate(dice, **nil)
         first_die = dice.first
         number_of_sides = first_die.sides_num
@@ -71,7 +78,7 @@ module Dicey
       # @return [Array<Integer>]
       def next_row_of_coefficients(row_index, window_size, previous_row)
         length = (row_index * window_size) + 1
-        (0..length).map do |col_index|
+        (0...length).map do |col_index|
           # Have to clamp to 0 to prevent accessing array from the end.
           # BUG: TruffleRuby can't handle endless range in #clamp (see https://github.com/oracle/truffleruby/issues/3945)
           window_range = ((col_index - window_size).clamp(0..col_index)..col_index)

data/lib/dicey/sum_frequency_calculators/runner.rb

@@ -13,17 +13,18 @@ module Dicey
       # Transform die definitions to roll frequencies.
       #
       # @param arguments [Array<String>] die definitions
-      # @param roll_calculators [Array<BaseCalculator>] list of calculators to use
       # @param format [#call] formatter for output
       # @param result [Symbol] result type selector
       # @return [nil]
       # @raise [DiceyError]
-      def call(arguments, roll_calculators:, format:, result:, **)
+      def call(arguments, format:, result:, **)
         raise DiceyError, "no dice!" if arguments.empty?
 
         dice = arguments.flat_map { |definition| die_foundry.cast(definition) }
-        frequencies = roll_calculators.find { _1.valid_for?(dice) }&.call(dice, result_type: result)
-        raise DiceyError, "no calculator could handle these dice!" unless frequencies
+        calculator = calculator_selector.call(dice)
+        raise DiceyError, "no calculator could handle these dice!" unless calculator
+
+        frequencies = calculator.call(dice, result_type: result)
 
         format.call(frequencies, AbstractDie.describe(dice))
       end
@@ -33,6 +34,10 @@ module Dicey
       def die_foundry
         @die_foundry ||= DieFoundry.new
       end
+
+      def calculator_selector
+        @calculator_selector ||= AutoSelector.new
+      end
     end
   end
 end

data/lib/dicey/sum_frequency_calculators/test_runner.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "auto_selector"
 require_relative "brute_force"
 require_relative "kronecker_substitution"
 require_relative "multinomial_coefficients"
@@ -8,6 +9,8 @@ module Dicey
   module SumFrequencyCalculators
     # A simple testing facility for roll frequency calculators.
     class TestRunner
+      AVAILABLE_CALCULATORS = AutoSelector::AVAILABLE_CALCULATORS
+
       # These are manually calculated frequencies,
       # with test cases for pretty much all variations of what this program can handle.
       TEST_DATA = [
@@ -42,6 +45,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.
@@ -51,12 +73,11 @@ module Dicey
 
       # Check all tests defined in {TEST_DATA} with every passed calculator.
       #
-      # @param roll_calculators [Array<BaseCalculator>]
       # @param report_style [Symbol] one of: +:full+, +:quiet+;
       #   +:quiet+ style does not output any text
       # @return [Boolean] whether there are no failing tests
-      def call(*, roll_calculators:, report_style:, **)
-        results = TEST_DATA.to_h { |test| run_test(test, roll_calculators) }
+      def call(*, report_style:, **)
+        results = TEST_DATA.to_h { |test| run_test(test) }
         full_report(results) if report_style == :full
         results.values.none? do |test_result|
           test_result.values.any? { FAILURE_RESULTS.include?(_1) }
@@ -67,13 +88,12 @@ module Dicey
 
       # @param test [Array(Array<Integer, Array<Numeric>>, Hash{Numeric => Integer})]
       #   pair of a dice list definition and expected results
-      # @param calculators [Array<BaseCalculator>]
       # @return [Array(Array<NumericDie>, Hash{BaseCalculator => Symbol})]
       #   result of running the test in a format suitable for +#to_h+
-      def run_test(test, calculators)
+      def run_test(test)
         dice = build_dice(test.first)
         test_result =
-          calculators.each_with_object({}) do |calculator, hash|
+          AVAILABLE_CALCULATORS.each_with_object({}) do |calculator, hash|
             hash[calculator] = run_test_on_calculator(calculator, dice, test.last)
           end
         [dice, test_result]
@@ -84,7 +104,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.1"
 end

data/lib/dicey.rb

@@ -1,10 +1,18 @@
 # frozen_string_literal: true
 
+# Try to load "vector_number" pre-emptively.
+begin
+  require "vector_number"
+rescue LoadError
+  # VectorNumber not available, sad
+end
+
 # A library for rolling dice and calculating roll frequencies.
 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.1
 platform: ruby
 authors:
 - Alexandr Bulancov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-08 00:00:00.000000000 Z
-dependencies: []
+date: 2025-10-10 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,16 +50,19 @@ 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
 - lib/dicey/output_formatters/json_formatter.rb
 - lib/dicey/output_formatters/key_value_formatter.rb
 - lib/dicey/output_formatters/list_formatter.rb
+- lib/dicey/output_formatters/null_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/auto_selector.rb
 - lib/dicey/sum_frequency_calculators/base_calculator.rb
 - lib/dicey/sum_frequency_calculators/brute_force.rb
 - lib/dicey/sum_frequency_calculators/empirical.rb
@@ -60,9 +77,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.1
+  source_code_uri: https://github.com/trinistr/dicey/tree/v0.16.1
+  changelog_uri: https://github.com/trinistr/dicey/blob/v0.16.1/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