dicey 0.18.0 → 0.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c11673348152c65cc6b6bb0b50a3bdf6b515479b6df9e1885c26d1e89e826dd4
-  data.tar.gz: 722bcec16c95bd5fbd9774aa382b3d074c2c2898fbef1308ecce9f988f2e2f55
+  metadata.gz: 6c3e35746de9367cc5f314d235013036e23347addba832d108612e96a5d0b556
+  data.tar.gz: 7c269e9c93c22370780a7dec18e8439a433c07c6f67dad5d2574453196f3b82e
 SHA512:
-  metadata.gz: 536a1274842408a7daeb543382ffd799fbf500020a9bde67f050ce2c3ce0e95e3dd9b0b94034f115af78f0c4d95ad7eef88910271b0db131b6433ad8303b2500
-  data.tar.gz: 5a67e9950f0fb8b82b156dcd001623a9029a1fd666e08f6570095648ef4e57e582699ca1ffcb85d1ec9e746adb8dd1f27ad1b36630f5682629a2d5ff57272ac4
+  metadata.gz: 1ac83738ab8b68e73ce66003c524d38020e1cd6157d833de26567c9c0fb89e84ae036833cdce81747e4ef672432a36c62c12802b27f6646f1f860d3565d28ead
+  data.tar.gz: 6131b2bd5b4d1fadb7a9a9fbb458cbea0c7e63839ac6a0819c0ff29c58449a873626c2acc3d54e04ddd9ae48fd6084d461ac4f0518c723cc5288ded82aa416c1

data/README.md

@@ -70,7 +70,7 @@ gem install dicey
 
 Or, if using Bundler, add it to your `Gemfile`:
 ```rb
-gem "dicey", "~> 0.17"
+gem "dicey", "~> 0.19"
 ```
 
 > [!TIP]
@@ -87,7 +87,7 @@ gem "dicey", "~> 0.17"
 
 ## Usage: CLI (command line)
 
-Following examples assume that `dicey` (or `dicey-to-gnuplot`) is executable and is in `$PATH`.
+Following examples assume that `dicey` (or `dicey-to-gnuplot`) is executable and is in `$PATH`. This should be the case if installed through RubyGems or Bundler.
 
 > [!NOTE]
 > 💡 Run `dicey --help` to get a list of all possible options.
@@ -259,19 +259,28 @@ Wind, wood and lightning in equal proportion it is! Your enemies will tremble!
 
 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).
+- *"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,3/2)", 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.
   - There is no difference between equal decimal and fractional representations of numbers.
-- *"1,1.5,Two", "(💚,🧡,💙,💜)" or "('1','(bracket)')"*: a list of strings and numbers separated by commas, possibly in round brackets, makes an arbitrary die.
+- *"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 include other quotes and round brackets in the string. Otherwise, they are prohibited. Commas are always prohibited.
+  - Single (') or double (") quotes can be used to include other quotes, round brackets and ambigious characters in a string. Otherwise, they are prohibited. Commas are always prohibited.
   - Quotes can also be used to treat numbers as strings.
+- *"+5", "+WIZ", or "-2.5"*: a single value prefixed with a sign makes a die with exactly that value.
+  - Accepted signs: "+", "-", "−" (minus).
+  - Single (') or double (") quotes can be used to include other quotes, round brackets and ambigious characters in a string. Otherwise, they are prohibited. Commas are always prohibited.
+  - Non-numeric values are only accepted with a "+".
 
-*"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 "-".
+*"D6", "d(-1,3)", "d2..4", "d+5", 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", "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.
+*"2D6", "5d-1,3", "277D(2..4)", "3d+5", 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.
+
+*"5+3", "2d6+4", "2D3—5-1", or "d(💚,🧡)+♥️"*: any definitions can be suffixed with a single signed value (see above), except for a single signed value itself. This adds the constant factor to result once.
+
+> [!NOTE]
+> 💡 If your die definition starts with a negative number, it can be bracketed, prefixed with "d", or put after "--" pseudo-argument to avoid being processed as an option.
 
 ## Usage: API
 
@@ -281,10 +290,11 @@ There are four *main* ways to define dice:
 
 ### Dice
 
-There are 3 classes of dice currently:
+There are 4 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.
 - `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*).
+- `Dicey::StaticDie` is a specialized subclass of `Dicey::AbstractDie`. It accepts any single value and always produces that value.
 
 All dice classes have constructor methods aside from `.new`:
 - `.from_list` takes a list of definitions and calls `.new` with each one;
@@ -293,7 +303,7 @@ All dice classes have constructor methods aside from `.new`:
 See [Diving deeper](#diving-deeper) for more theoretical information.
 
 > [!NOTE]
-> 💡 Using `Float` values is liable to cause precision issues. Due to in-built result verification, this **will** raise errors. Use `Rational` or `BigDecimal` instead. 
+> 💡 Using `Float` values is liable to cause precision issues. Due to built-in result verification, this **will** raise errors. Use `Rational` or `BigDecimal` instead. 
 
 #### DieFoundry
 
@@ -373,6 +383,9 @@ die.roll
 > [!NOTE]
 > 💡 Randomness source is *global*, shared between all dice and probably not thread-safe.
 
+> [!NOTE]
+> 💡 `Dicey::StaticDie` has no impact on roll randomness, unlike other single-sided dice.
+
 ### Distribution calculators
 
 Distribution calculators live in `Dicey::DistributionCalculators` module. There are three main calculators currently.
@@ -467,9 +480,6 @@ For a further discussion of calculations, it is important to understand which cl
 - **Numeric** die is limited by having sides confined to ℝ (or ℂ if you are feeling particularly adventurous).
 - **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.
-
 Currently, three algorithms for calculating distributions are implemented, with different possibilities and trade-offs.
 
 > [!NOTE]

data/lib/dicey/abstract_die.rb

@@ -16,6 +16,10 @@ module Dicey
   # {.srand} can be used to (re)set the internal randomizer's state for all dice,
   # allowing to reproduce the same sequence of rolls (if it was done with a known state).
   class AbstractDie
+    # Matcher to check whether string needs quoting.
+    # @see DieFoundry::SPECIAL
+    STRING_TO_QUOTE = /["',()+−-]/
+
     # Yes, class variable is actually useful here.
     # TODO: Allow supplying a custom Random.
     # rubocop:disable Style/ClassVars
@@ -49,7 +53,12 @@ module Dicey
     def self.describe(dice)
       return dice.to_s if AbstractDie === dice
 
-      dice.to_a.join("+")
+      dice.map(&:to_s).reduce { |string, die|
+        die_string = die.to_s
+        string << "+" unless die_string.match?(/\A[+-]/)
+        string << die_string
+        string
+      }.to_s
     end
 
     # Create a bunch of different dice at once from a list of definitions.
@@ -85,7 +94,7 @@ module Dicey
     # @raise [DiceyError] if +sides_list+ is empty
     def initialize(sides_list)
       @sides_list = sides_list.to_a
-      @sides_list = @sides_list.dup if @sides_list.equal?(sides_list)
+      @sides_list = @sides_list.dup if @sides_list.equal?(sides_list) && !@sides_list.frozen?
       raise DiceyError, "dice must have at least one side!" if @sides_list.empty?
 
       @sides_list.freeze
@@ -121,10 +130,12 @@ module Dicey
     # Return a string representing the die.
     #
     # Default representation is a list of sides in round brackets.
+    # Strings are quoted.
     #
     # @return [String]
     def to_s
-      (@sides_list.size > 1) ? "(#{@sides_list.join(",")})" : "(#{@sides_list.first},)"
+      sides = @sides_list.map { |side| side_to_s(side) }
+      (@sides_list.size > 1) ? "(#{sides.join(",")})" : "(#{sides.first},)"
     end
 
     # Determine if this die and the other one have the same list of sides.
@@ -159,8 +170,35 @@ module Dicey
       [self.class, @sides_list].hash
     end
 
+    # Whether all sides of this die are +Numeric+.
+    #
+    # @return [Boolean]
+    def numeric?
+      return @numeric if defined?(@numeric)
+
+      @numeric = @sides_list.all?(Numeric)
+    end
+
+    # Freezes +self+ (if not already frozen); returns +self+.
+    #
+    # Performs computations that memoize results before freezing.
+    def freeze
+      numeric? unless frozen?
+      super
+    end
+
     private
 
+    # @param side [#to_s]
+    # @return [String]
+    def side_to_s(side)
+      if String === side && side.match?(STRING_TO_QUOTE)
+        side.include?('"') ? "'#{side}'" : "\"#{side}\""
+      else
+        side.to_s
+      end
+    end
+
     # @param other [AbstractDie]
     # @return [Boolean]
     def same_sides?(other)

data/lib/dicey/cli/calculator_test_runner.rb

@@ -24,7 +24,10 @@ module Dicey
         [[2, 2, 2, 2], { 4 => 1, 5 => 4, 6 => 6, 7 => 4, 8 => 1 }],
         [[1, 2, 3], { 3 => 1, 4 => 2, 5 => 2, 6 => 1 }],
         [[3, 2, 1], { 3 => 1, 4 => 2, 5 => 2, 6 => 1 }],
+        [["+5"], { 5 => 1 }],
+        [["+5", "-12.2"], { -7.2r => 1 }],
         [[[0], 1], { 1 => 1 }],
+        [[[2, 3, 4], "-3"], { -1 => 1, 0 => 1, 1 => 1 }],
         [[4, 6], { 2 => 1, 3 => 2, 4 => 3, 5 => 4, 6 => 4, 7 => 4, 8 => 3, 9 => 2, 10 => 1 }],
         [[[3, 17, 21]], { 3 => 1, 17 => 1, 21 => 1 }],
         [[[3, 3, 3, 3, 3, 5, 5, 5]], { 3 => 5, 5 => 3 }],
@@ -42,10 +45,9 @@ 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 }],
+        [[2, 2, "+2"], { 4 => 1, 5 => 2, 6 => 1 }],
         *(
-          # :nocov:
-          if defined?(VectorNumber)
-            # :nocov:
+          if defined?(VectorNumber) # simplecov:disable
             [
               [[["s", "a", "d", 33]],
                { VectorNumber["s"] => 1, VectorNumber["a"] => 1, VectorNumber["d"] => 1, 33 => 1 }],
@@ -58,6 +60,10 @@ module Dicey
                  VectorNumber["s"] * 2 => 1, VectorNumber["a"] * 2 => 1, 8 => 1,
                  VectorNumber["s", "a"] => 2, VectorNumber["s", 4] => 2, VectorNumber["a", 4] => 2,
                }],
+              [[[1, 3], "+d"], { VectorNumber[1, "d"] => 1, VectorNumber[3, "d"] => 1 }],
+              [[%w[A B], %w[A B], "+A"],
+               { VectorNumber["A"] * 3 => 1, VectorNumber["A", "B", "A"] => 2,
+                 VectorNumber["B", "B", "A"] => 1 }],
             ]
           end
         ),
@@ -93,8 +99,8 @@ module Dicey
       def run_test(test)
         dice = build_dice(test.first)
         test_result =
-          AVAILABLE_CALCULATORS.each_with_object({}) do |calculator, hash|
-            hash[calculator] = run_test_on_calculator(calculator, dice, test.last)
+          AVAILABLE_CALCULATORS.to_h do |calculator|
+            [calculator, run_test_on_calculator(calculator, dice, test.last)]
           end
         [dice, test_result]
       end
@@ -104,9 +110,11 @@ module Dicey
       # @param definition [Array<Integer, Array<Integer>>]
       # @return [Array<AbstractDie>]
       def build_dice(definition)
-        definition.map do |die_def|
+        definition.flat_map do |die_def|
           if die_def.is_a?(Integer)
             RegularDie.new(die_def)
+          elsif die_def.is_a?(String)
+            DieFoundry.new.cast(die_def)
           elsif die_def.all?(Numeric)
             NumericDie.new(die_def)
           else

data/lib/dicey/die_foundry.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "abstract_die"
 require_relative "numeric_die"
 require_relative "regular_die"
+require_relative "static_die"
 
 require_relative "mixins/rational_to_integer"
 
@@ -11,60 +13,81 @@ module Dicey
   class DieFoundry
     include Mixins::RationalToInteger
 
-    # Regexp for matching a possible count.
-    PREFIX = /(?:(?<count>[1-9]\d*+)?+d)?+/i
-    # Regexp for an integer number.
-    INTEGER = /(?:-?\d++)/
-    # Regexp for a (possibly) fractional number.
-    FRACTION = %r{(?:-?\d++(?:/\d++|\.\d++)?)}
-    # Regexp for an "arbitrary" string.
-    STRING = /(?:(?<side>[^"',()]++)|"(?<side>[^",]++)"|'(?<side>[^',]++)')/
+    # Special characters disallowed in unquoted strings.
+    # @see AbstractDie::STRING_TO_QUOTE
+    SPECIAL = %{"',()+−-}
+
+    # Pattern for an integer number.
+    INTEGER = "(?:-?\\d++)"
+    # Pattern for a possibly fractional number.
+    NUMBER = "(?:-?\\d++(?:/\\d++|\\.\\d++)?)"
+    # Pattern for an "arbitrary" string or number.
+    STRING = %{(?:(?<string>[^#{SPECIAL}]++)|"(?<string>[^",]++)"|'(?<string>[^',]++)')}.freeze
+    # Pattern for a number or string (allowing negative numbers).
+    VALUE = "(?:#{NUMBER}(?=[,)+−-]|\\z)|#{STRING})".freeze
+
+    # Pattern for matching a possible count.
+    COUNT = "(?:(?<count>[1-9]\\d*+)?+[Dd])?+"
+    # Pattern for matching an optional constant factor.
+    CONSTANT = "(?<constant>(?<sign>[+−-])(?<constant_value>#{NUMBER})|" \
+               "(?<sign>\\+)(?<constant_value>#{STRING}))".freeze
+
+    molder = ->(pattern) { /\A#{COUNT}(?:#{pattern}|\(#{pattern}\))#{CONSTANT}?\z/ }
 
     # 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,
+      [/\A#{COUNT}(?<sides>[1-9]\d*+)#{CONSTANT}?\z/, :regular_mold],
       # Integer range goes into the NumericDie mold.
-      [/\A#{PREFIX}\(?(?<begin>#{INTEGER})(?:[-–—…]|\.{2,3})(?<end>#{INTEGER})\)?\z/,
-       :range_mold].freeze,
+      [molder.("(?<begin>#{INTEGER})(?:[–—…]|\\.{2,3})(?<end>#{INTEGER})"), :range_mold],
       # List of numbers goes into the NumericDie mold.
-      [/\A#{PREFIX}\(?(?<sides>#{INTEGER}(?:(?:,#{INTEGER})++,?+|,))\)?\z/,
-       :weirdly_shaped_mold].freeze,
+      [molder.("(?<sides>#{INTEGER}(?:(?:,#{INTEGER})++,?+|,))"), :weirdly_shaped_mold],
       # Non-integers require special handling for precision.
-      [/\A#{PREFIX}\(?(?<sides>#{FRACTION}(?:(?:,#{FRACTION})++,?+|,))\)?\z/,
-       :weirdly_precise_mold].freeze,
+      [molder.("(?<sides>#{NUMBER}(?:(?:,#{NUMBER})++,?+|,))"), :weirdly_precise_mold],
       # Lists of stuff are broken into AbstractDie.
-      [/\A#{PREFIX}\(?(?<sides>#{STRING}(?:(?:,#{STRING})++,?+|,))\)?\z/, :cursed_mold].freeze,
+      [molder.("(?<sides>#{VALUE}(?:(?:,#{VALUE})++,?+|,))"), :cursed_mold],
+      # Sign-prefixed value goes into the StaticDie mold.
+      [/\A#{COUNT}(?:#{CONSTANT}|\(#{CONSTANT}\))\z/, :static_mold],
       # Anything else is spilled on the floor.
-    ].freeze
+    ].each(&:freeze).freeze
 
     # Cast a die definition into a mold to make a die.
     #
     # Following definitions are recognized:
     # - positive integer (like "6" or "20"), which produces a {RegularDie};
-    # - integer range (like "3-6" or "(-5..5)"), which produces a {NumericDie};
+    # - 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;
     # - list of strings, possibly mixed with numbers (like "0.5,asdf" or "(👑,♠️,♥️,♣️,♦️,⚓️)"),
     #   which produces an {AbstractDie} with numbers treated the same as in previous cases,
     #   and other or quoted values treated as Strings.
+    # - signed value (like "+3", "-3.6" or "(+ABC)"), which produces a {StaticDie},
+    #   non-numeric values are only allowed as positive values;
     #
     # 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.
+    # A plain "d"/"D" without an explicit count is ignored instead, creating a single die.
+    #
+    # All die definitions (aside from plain signed value) can be suffixed with a signed value
+    # to add or subtract from the result, like "2D6+3" or "5dA,B,C+C".
+    # Only numbers can be subtracted.
     #
     # @param definition [String] die shape
     # @return [AbstractDie, Array<AbstractDie>]
     # @raise [DiceyError] if no mold fits the definition
     def call(definition)
       matched, name =
-        MOLDS.reduce(nil) do |_, (shape, mold)|
+        MOLDS.find do |(shape, mold)|
           match = shape.match(definition)
           break [match, mold] if match
         end
       raise DiceyError, "can not cast die from `#{definition}`!" unless name
 
-      __send__(name, matched)
+      if matched[:constant] && name != :static_mold
+        [__send__(name, matched), static_mold(matched, ignore_count: true)].flatten
+      else
+        __send__(name, matched)
+      end
     end
 
     alias cast call
@@ -93,19 +116,28 @@ module Dicey
 
     def cursed_mold(definition)
       sides = definition[:sides].split(",")
-      sides.map! do |side|
-        case side
-        when /\A#{INTEGER}\z/o
-          side.to_i
-        when /\A#{FRACTION}\z/o
-          rational_to_integer(Rational(side))
-        else
-          side.match(STRING)[:side]
-        end
-      end
+      sides.map! { |side| parse_value(side) }
       build_dice(AbstractDie, definition[:count], sides)
     end
 
+    def static_mold(definition, ignore_count: false)
+      value = parse_value(definition[:constant_value])
+      value = -value if definition[:sign] != "+"
+
+      build_dice(StaticDie, ignore_count ? nil : definition[:count], value)
+    end
+
+    def parse_value(side)
+      case side
+      when /\A#{INTEGER}\z/o
+        side.to_i
+      when /\A#{NUMBER}\z/o
+        rational_to_integer(Rational(side))
+      else
+        side.match(STRING)[:string]
+      end
+    end
+
     def build_dice(die_class, count, sides)
       if count
         die_class.from_count(count.to_i, sides)

data/lib/dicey/distribution_calculators/base_calculator.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../mixins/vectorize_dice"
+
 module Dicey
   module DistributionCalculators
     # Base class for implementing distribution calculators.
@@ -26,6 +28,8 @@ module Dicey
     #
     # @abstract
     class BaseCalculator
+      include Mixins::VectorizeDice
+
       # Possible values for +result_type+ argument in {#call}.
       RESULT_TYPES = %i[weights probabilities].freeze
 
@@ -33,6 +37,10 @@ module Dicey
       #
       # Returns empty hash for an empty list of dice.
       #
+      # @note Calculation is supposed to return exact results.
+      #   Using dice with +Float+ values can break this promise and raise errors.
+      #   Please use +Integer+, +Rational+ or +BigDecimal+ instead.
+      #
       # @param dice [Enumerable<AbstractDie>]
       # @param result_type [Symbol] one of {RESULT_TYPES}
       # @param options [Hash{Symbol => Any}] calculator-specific options,
@@ -47,23 +55,31 @@ module Dicey
         unless RESULT_TYPES.include?(result_type)
           raise DiceyError, "#{result_type} is not a valid result type!"
         end
-        raise DiceyError, "#{self.class} can not handle these dice!" unless valid_for?(dice)
-
+        raise DiceyError, "dice must be an Enumerable!" unless Enumerable === dice
         # Short-circuit for a degenerate case.
         return {} if dice.empty?
 
-        distribution = calculate(dice, **options)
+        static_dice, normal_dice = dice.partition { StaticDie === _1 }
+        raise DiceyError, "#{self.class} can not handle these dice!" unless valid_for?(normal_dice)
+
+        distribution = prepare_distribution(normal_dice, static_dice, options)
         verify_result(distribution, dice)
-        distribution = sort_result(distribution)
         transform_result(distribution, result_type)
       end
 
       # Whether this calculator can be used for the list of dice.
       #
+      # {StaticDie} instances are always ignored.
+      #
       # @param dice [Enumerable<AbstractDie>]
       # @return [Boolean]
       def valid_for?(dice)
-        dice.is_a?(Enumerable) && (dice.empty? || (dice.all?(AbstractDie) && validate(dice)))
+        return false if !(Enumerable === dice) || !dice.all?(AbstractDie)
+
+        normal_dice = dice.grep_v(StaticDie)
+        return true if normal_dice.none?
+
+        validate(normal_dice)
       end
 
       # Heuristic complexity of the calculator, used to determine best calculator.
@@ -77,7 +93,7 @@ module Dicey
       def heuristic_complexity(dice)
         return 0 if dice.empty?
 
-        calculate_heuristic(dice.length, dice.map(&:sides_num).max).to_i
+        calculate_heuristic(dice.grep_v(StaticDie).length, dice.map(&:sides_num).max).to_i
       end
 
       private
@@ -103,9 +119,35 @@ module Dicey
         raise NotImplementedError
       end
 
+      # Prepare distribution by calculating it for normal dice and adding static dice to it.
+      #
+      # @param normal_dice [Enumerable<AbstractDie>]
+      # @param static_dice [Enumerable<StaticDie>]
+      # @param options [Hash]
+      # @return [Hash{Any => Integer}]
+      def prepare_distribution(normal_dice, static_dice, options)
+        if normal_dice.any?
+          distribution = calculate(normal_dice, **options)
+          distribution = sort_result(distribution)
+        else
+          # We can't get to this point if there are no dice at all,
+          # so prepare a "nothing" distribution to add static dice to it.
+          distribution = { 0 => 1 }
+        end
+
+        if static_dice.any?
+          c = vectorize_dice(static_dice).sum(&:value)
+          # This is done via `+=` because different `k + c` can produce the same key.
+          distribution = distribution.each_with_object(Hash.new(0)) { |(k, v), h| h[k + c] += v }
+          distribution.default = nil
+        end
+
+        distribution
+      end
+
       # Check that resulting weights actually add up to what they are supposed to be.
       #
-      # @param distribution [Hash{Numeric => Integer}]
+      # @param distribution [Hash{Any => Integer}]
       # @param dice [Enumerable<AbstractDie>]
       # @return [void]
       # @raise [DiceyError] if result is wrong
@@ -125,9 +167,9 @@ module Dicey
 
       # Transform calculated weights to requested result type, if needed.
       #
-      # @param distribution [Hash{Numeric => Integer}]
+      # @param distribution [Hash{Any => Integer}]
       # @param result_type [Symbol] one of {RESULT_TYPES}
-      # @return [Hash{Numeric => Numeric}]
+      # @return [Hash{Any => Numeric}]
       def transform_result(distribution, result_type)
         if result_type == :weights
           distribution

data/lib/dicey/distribution_calculators/binomial.rb

@@ -3,7 +3,6 @@
 require_relative "base_calculator"
 
 require_relative "../mixins/missing_math"
-require_relative "../mixins/vectorize_dice"
 
 module Dicey
   module DistributionCalculators
@@ -13,12 +12,12 @@ module Dicey
     # If dice include non-numeric sides, gem +vector_number+ has to be installed.
     class Binomial < BaseCalculator
       include Mixins::MissingMath
-      include Mixins::VectorizeDice
 
       private
 
       def validate(dice)
-        dice.first.sides_num == 2 && dice.all? { _1 == dice.first }
+        die = dice.first
+        die.sides_num == 2 && dice.all? { _1 == die }
       end
 
       def calculate_heuristic(dice_count, _sides_count)

data/lib/dicey/distribution_calculators/empirical.rb

@@ -2,8 +2,6 @@
 
 require_relative "base_calculator"
 
-require_relative "../mixins/vectorize_dice"
-
 module Dicey
   module DistributionCalculators
     # "Calculator" for a collection of {AbstractDie} using empirically-obtained statistics.
@@ -19,15 +17,13 @@ module Dicey
     # *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)
-        !!defined?(VectorNumber) || dice.all?(NumericDie)
+        !!defined?(VectorNumber) || dice.all?(&:numeric?)
       end
 
       def calculate_heuristic(dice_count, sides_count)

data/lib/dicey/distribution_calculators/iterative.rb

@@ -2,8 +2,6 @@
 
 require_relative "base_calculator"
 
-require_relative "../mixins/vectorize_dice"
-
 module Dicey
   module DistributionCalculators
     # Calculator for a collection of {AbstractDie} which goes through
@@ -11,12 +9,10 @@ module Dicey
     #
     # If dice include non-numeric sides, gem +vector_number+ has to be available.
     class Iterative < BaseCalculator
-      include Mixins::VectorizeDice
-
       private
 
       def validate(dice)
-        !!defined?(VectorNumber) || dice.all?(NumericDie)
+        !!defined?(VectorNumber) || dice.all?(&:numeric?)
       end
 
       def calculate_heuristic(dice_count, sides_count)
@@ -24,7 +20,7 @@ module Dicey
       end
 
       def calculate(dice, **nil)
-        dice = vectorize_dice(dice)
+        dice = vectorize_dice(dice).sort_by! { _1.numeric? ? 0 : _1.sides_num }
 
         dice[1..].reduce(dice.first.sides_list.tally) do |previous_distribution, die|
           convolve_with_die(previous_distribution, die.sides_list.tally)

data/lib/dicey/distribution_calculators/multinomial_coefficients.rb

@@ -28,7 +28,7 @@ module Dicey
 
       def validate(dice)
         first_die = dice.first
-        return false unless first_die.is_a?(NumericDie)
+        return false unless first_die.numeric?
         return false unless dice.all? { _1 == first_die }
         return true if first_die.sides_num == 1
 
@@ -36,7 +36,7 @@ module Dicey
       end
 
       # @param sides_list [Array<Numeric>]
-      # @return [false, Array<Numeric>]
+      # @return [Boolean]
       def arithmetic_sequence?(sides_list)
         increment = sides_list[1] - sides_list[0]
         return false if increment.zero?

data/lib/dicey/distribution_calculators/trivial.rb

@@ -47,9 +47,7 @@ module Dicey
       # Simplest multinomial distribution: two regular dice.
       def bimultinomial(die)
         middle = die.sides_num
-        (1...(die.sides_num * 2)).each_with_object({}) do |i, hash|
-          hash[i + 1] = middle - (middle - i).abs
-        end
+        (1...(die.sides_num * 2)).to_h { |i| [i + 1, middle - (middle - i).abs] }
       end
     end
   end

data/lib/dicey/distribution_properties_calculator.rb

@@ -5,6 +5,11 @@ require_relative "mixins/rational_to_integer"
 module Dicey
   # @note This class is considered experimental. It may be changed at any point.
   #
+  # @note Almost all distribution properties only really make sense
+  #   for ordered values in a single dimension.
+  #   This calculator assumes that only distributions of real numbers
+  #   satisfy these conditions.
+  #
   # Calculates distribution properties,
   # also known as descriptive statistics when applied to a population sample.
   #
@@ -36,7 +41,7 @@ module Dicey
     def call(distribution)
       return {} if distribution.empty?
 
-      calculate_properties(distribution)
+      calculate_properties(distribution).transform_values! { rational_to_integer(_1) }
     end
 
     private
@@ -50,7 +55,7 @@ module Dicey
         modes: modes(distribution),
         **range_characteristics(outcomes),
         **median(outcomes),
-        **means(outcomes, weights),
+        **means(outcomes),
         **moments(distribution),
       }
     end
@@ -89,16 +94,16 @@ module Dicey
         min: min,
         max: max,
         range_length: max - min,
-        mid_range: rational_to_integer(Rational(min + max, 2)),
+        mid_range: Rational(min + max, 2),
       }
     rescue ArgumentError, TypeError, NoMethodError
       # Outcomes are not comparable with each other, so a range can not be determined.
       {}
     end
 
-    def means(outcomes, _weights)
+    def means(outcomes)
       {
-        arithmetic_mean: rational_to_integer(Rational(outcomes.sum, outcomes.size)),
+        arithmetic_mean: Rational(outcomes.sum, outcomes.size),
       }
     rescue ArgumentError, TypeError
       # Outcomes are not summable with each other, means are meaningless.
@@ -121,12 +126,10 @@ module Dicey
 
     def moments(distribution)
       total_weight = distribution.values.sum
-      expected_value = rational_to_integer(moment(distribution, total_weight, 1))
-      variance = rational_to_integer(moment(distribution, total_weight, 2) - (expected_value**2))
-      skewness =
-        rational_to_integer(moment(distribution, total_weight, 3, expected_value, variance))
-      kurtosis =
-        rational_to_integer(moment(distribution, total_weight, 4, expected_value, variance))
+      expected_value = moment(distribution, total_weight, 1)
+      variance = moment(distribution, total_weight, 2) - (expected_value**2)
+      skewness = moment(distribution, total_weight, 3, expected_value, variance)
+      kurtosis = moment(distribution, total_weight, 4, expected_value, variance)
 
       {
         expected_value: expected_value,
@@ -137,7 +140,7 @@ module Dicey
         excess_kurtosis: kurtosis ? kurtosis - 3 : nil,
       }
     rescue ArgumentError, TypeError, NoMethodError
-      # Outcomes are not compatible with each other, moments are fleeing.
+      # Outcomes are not compatible with each other, moments are fleeting.
       {}
     end
 

data/lib/dicey/mixins/missing_math.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module Dicey
+  # @api private
+  # Various mixins with shared methods.
   module Mixins
     # @api private
     # Some math functions missing from Math, though without argument range checks.

data/lib/dicey/mixins/rational_to_integer.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 module Dicey
-  # @api private
-  # Various mixins with shared methods.
   module Mixins
     # @api private
     # Mix-in for converting rationals with denominator of 1 to integers.
@@ -13,7 +11,7 @@ module Dicey
       # Otherwise, return +value+ as-is.
       #
       # @param value [Numeric, Any]
-      # @return [Numeric, Integer, Any]
+      # @return [Rational, Integer, Any]
       def rational_to_integer(value)
         (Rational === value && value.denominator == 1) ? value.numerator : value
       end

data/lib/dicey/mixins/vectorize_dice.rb

@@ -22,13 +22,18 @@ module Dicey
       end
 
       def vectorize_die_sides(die)
-        return die if NumericDie === die
+        case die
+        when NumericDie
+          die
+        when StaticDie
+          die.class.new(vectorize_one_die_side(die.value))
+        else
+          die.class.new(die.sides_list.map { vectorize_one_die_side(_1) })
+        end
+      end
 
-        die.class.new(
-          die.sides_list.map do |side|
-            (Numeric === side || VectorNumber === side) ? side : VectorNumber.new([side])
-          end
-        )
+      def vectorize_one_die_side(side)
+        (Numeric === side || VectorNumber === side) ? side : VectorNumber.new([side])
       end
     end
   end

data/lib/dicey/numeric_die.rb

@@ -16,6 +16,8 @@ module Dicey
         unless Integer === sides_list.begin && Integer === sides_list.end
           raise DiceyError, "`#{sides_list.inspect}` is not a valid range!"
         end
+
+        @range = sides_list
       else
         sides_list.each do |value|
           raise DiceyError, "`#{value.inspect}` is not a number!" unless Numeric === value
@@ -24,5 +26,24 @@ module Dicey
 
       super
     end
+
+    # Whether all sides of this die are +Numeric+.
+    #
+    # @return [true]
+    def numeric?
+      true
+    end
+
+    # Return a string representing the die.
+    #
+    # Default representation is a list of sides in round brackets.
+    # If the die was initialized with a +Range+, string will be in the form of +begin..end+.
+    #
+    # @return [String]
+    def to_s
+      return "#{@range.begin}..#{@range.end}" if @range
+
+      super
+    end
   end
 end

data/lib/dicey/static_die.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "abstract_die"
+
+module Dicey
+  # Static die has only one side and always returns the same value.
+  # Useful to model constants in dice expressions.
+  #
+  # @note Unlike other dice, rolling a static die does not advance
+  #   shared randomness generator, thus it does not have any impact on
+  #   rolling other dice.
+  class StaticDie < AbstractDie
+    # Die's only value.
+    #
+    # @return [Any]
+    attr_reader :value
+
+    # @param value [Any]
+    def initialize(value)
+      @value = value
+      super([@value].freeze)
+    end
+
+    alias current value
+    alias next value
+    alias roll value
+
+    # Return a string representing the die.
+    #
+    # Static dice are represented with a "+" or "-" followed by the absolute value
+    # (0 is represented as +0). Strings are quoted.
+    #
+    # @return [String]
+    def to_s
+      if @value.respond_to?(:negative?) && @value.negative?
+        side_to_s(@value)
+      else
+        "+#{side_to_s(@value)}"
+      end
+    end
+  end
+end

data/lib/dicey/version.rb

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

data/lib/dicey.rb

@@ -12,7 +12,8 @@ end
 # Includes several classes of dice:
 # - {AbstractDie}, the base and most generic class;
 # - {NumericDie}, a subclass for strictly numeric dice;
-# - {RegularDie}, for the most common dice.
+# - {RegularDie}, for the most common dice;
+# - {StaticDie}, a constant offset pseudo-die.
 #
 # See {AbstractDie} for API and more information.
 #
@@ -30,6 +31,7 @@ module Dicey
   require_relative "dicey/abstract_die"
   require_relative "dicey/numeric_die"
   require_relative "dicey/regular_die"
+  require_relative "dicey/static_die"
 
   require_relative "dicey/die_foundry"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dicey
 version: !ruby/object:Gem::Version
-  version: 0.18.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Alexander Bulancov
@@ -79,6 +79,7 @@ files:
 - lib/dicey/mixins/vectorize_dice.rb
 - lib/dicey/numeric_die.rb
 - lib/dicey/regular_die.rb
+- lib/dicey/static_die.rb
 - lib/dicey/version.rb
 homepage: https://github.com/trinistr/dicey
 licenses:
@@ -86,9 +87,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.18.0
-  source_code_uri: https://github.com/trinistr/dicey/tree/v0.18.0
-  changelog_uri: https://github.com/trinistr/dicey/blob/v0.18.0/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/dicey/0.19.0
+  source_code_uri: https://github.com/trinistr/dicey/tree/v0.19.0
+  changelog_uri: https://github.com/trinistr/dicey/blob/v0.19.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options:
 - "--main"