unary_factorial 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c511fb978628b0b06d10374f54d920c5883fd8e5d8d7d32e9f569af38c0b8b66
+  data.tar.gz: e865e43dfc2535d9d8298cb02aee1edfea323580f0e3041bf54af801bbfc7d22
+SHA512:
+  metadata.gz: 004453a45bee3aa899cde947fbfd1fb6ee82d8aa53b6dc9803399d31978cdb64805b488c9036781880400d77388bbb48c89907269daa86e687aeca67d04c3d06
+  data.tar.gz: ac5eb373a42bc84f3ed00a02cab8f6b479e575e94427494a769d865dbbfc53753d81091a3d21276f439576fde30c7515b9398988fd5b0d8fc269d6b7aaa8447e

data/bench/cached_bench.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative '../lib/unary_factorial'
+require 'benchmark/ips'
+
+using UnaryFactorial.new
+
+def bench(target)
+  puts "Factorial of #{target}:"
+  Benchmark.ips do
+    it.report("Normal uncached #{target}") { (2..target).reduce(1, :*) }
+    it.report("Unary cached #{target}") { !target }
+
+    it.compare!
+  end
+end
+
+bench(2_600)

data/bench/uncached_bench.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative '../lib/unary_factorial'
+require 'benchmark/ips'
+
+using UnaryFactorial.new(cache: nil)
+
+def bench(target)
+  puts "Factorial of #{target}:"
+  Benchmark.ips do
+    it.report("Normal uncached #{target}") { (2..target).reduce(1, :*) }
+    it.report("Unary uncached #{target}") { !target }
+
+    it.compare!
+  end
+end
+
+bench(120)
+bench(2_600)

data/gems.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'minitest', '~> 5'
+gem 'rake', '~> 10'

data/lib/unary_factorial.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+##
+# This refinement uses the Schönhage–Strassen algorithm for efficient
+# computation of factorials with results cached by default.
+#
+# Caching dramatically improves performance when portions of the
+# factorial calculation are repeated.
+class UnaryFactorial < Module
+  class NegativeError < StandardError
+    def initialize(message = 'Factorials cannot be negative') = super
+  end
+
+  attr_accessor :cache
+
+  ##
+  # If the `cache` keyword argument doesn't provide a custom cache,
+  # a `Hash` will be used as the default cache. Set `cache` to `nil`
+  # to disable caching.
+  #
+  # A custom `cache` must respond to `[]` and `[]=` and should also
+  # respond to `size`, `clear` and `delete` as an accessor interface.
+  def initialize(cache: {})
+    @cache = cache
+
+    module_eval do
+      refine Integer do
+        def !@
+          raise NegativeError if negative?
+
+          factorial(1..self)
+        end
+
+        private
+
+        define_method :factorial do |range|
+          if cache
+            value = cache[range]
+            return value if value
+          end
+
+          from = range.begin
+          to = range.end
+          diff = to - from
+
+          value = case diff
+          when 0
+            from
+          when ..3
+            range.reduce(1, :*)
+          else
+            mid = (to + from) / 2
+            factorial(from..mid) * factorial(mid.succ..to)
+          end
+
+          cache[range] = value if cache
+
+          value
+        end
+      end
+    end
+  end
+end

data/license.txt

@@ -0,0 +1,22 @@
+Copyright (c) Shannon Skipper
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/rakefile.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+task default: %w[test]
+
+task :test do
+  Rake::FileList['test/*_test.rb'].each do |file|
+    ruby file
+  end
+end
+
+task :bench do
+  Rake::FileList['bench/*_bench.rb'].each do |file|
+    ruby file
+  end
+end

data/readme.md

@@ -0,0 +1,56 @@
+# UnaryFactorial
+
+This gem refines `Integer` to provide a unary-style interface.
+
+```ruby
+!42
+#=> 1405006117752879898543142606244511569936384000000000
+```
+
+The Schönhage–Strassen algorithm is used for efficient factorial calculation.
+
+Optional caching is enabled by default for much faster repeated calculations.
+
+## Usage
+
+```ruby
+require 'unary_factorial'
+
+Factorial = UnaryFactorial.new
+using Factorial
+
+!5
+#=> 120
+
+Factorial.cache
+#=> {1..3 => 6, 4..5 => 20, 1..5 => 120}
+```
+
+## Optionally disable caching
+
+To disable caching, provide a falsey `cache` keyword argument:
+
+```ruby
+require 'unary_factorial'
+
+Factorial = UnaryFactorial.new(cache: nil)
+
+!5
+#=> 120
+
+Factorial.cache
+#=> nil
+```
+
+## Installation
+
+Install the gem directly:
+```sh
+gem install unary_factorial
+```
+
+Or add the gem to your app's bundle:
+```
+bundle add unary_factorial
+bundle
+```

data/test/cache_test.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative '../lib/unary_factorial'
+require 'minitest/autorun'
+require 'minitest/pride'
+
+class UnaryFactorialTest < Minitest::Test
+  Factorial = UnaryFactorial.new
+  using Factorial
+
+  def test_cache_basics
+    assert_respond_to Factorial, :cache
+    assert_kind_of Hash, Factorial.cache
+  end
+
+  def test_cache_contents
+    !120
+
+    assert_equal Factorial.cache.size, 63
+    assert_equal Factorial.cache.fetch(69..72), 24_690_960
+  end
+end

data/test/unary_factorial_test.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative '../lib/unary_factorial'
+require 'minitest/autorun'
+require 'minitest/pride'
+
+class UnaryFactorialTest < Minitest::Test
+  using UnaryFactorial.new
+
+  def test_small_factorials
+    assert_equal 1, !0
+    assert_equal 1, !1
+    assert_equal 2, !2
+    assert_equal 6, !3
+    assert_equal 24, !4
+    assert_equal 120, !5
+    assert_equal 3_628_800, !10
+    assert_equal 2_432_902_008_176_640_000, !20
+  end
+
+  def test_larger_factorials
+    assert_equal 30_414_093_201_713_378_043_612_608_166_064_768_844_377_641_568_960_512_000_000_000_000, !50
+    assert_equal 8_320_987_112_741_390_144_276_341_183_223_364_380_754_172_606_361_245_952_449_277_696_409_600_000_000_000_000,
+                 !60
+  end
+
+  def test_negatives_error
+    assert_raises(UnaryFactorial::NegativeError) { !-1 }
+    assert_raises(UnaryFactorial::NegativeError) { !-42 }
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: unary_factorial
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Shannon Skipper
+bindir: bin
+cert_chain: []
+date: 2025-03-04 00:00:00.000000000 Z
+dependencies: []
+description: An Integer refinement gem for efficient Schönhage–Strassen factorial
+  calculation with optional caching with a unary method interface.
+email:
+- shannonskipper@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- bench/cached_bench.rb
+- bench/uncached_bench.rb
+- gems.rb
+- lib/unary_factorial.rb
+- license.txt
+- rakefile.rb
+- readme.md
+- test/cache_test.rb
+- test/unary_factorial_test.rb
+homepage: https://github.com/havenwood/unary_factorial
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.0.dev
+specification_version: 4
+summary: A refinement for efficient Schönhage–Strassen factorial calculation with
+  caching.
+test_files: []