fixed 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0e87ed315b7c15cb15aa8663e00e8090b29d352babf0d30191da6d16ccca1640
+  data.tar.gz: fb6001610413384c17bdd211bcbccd471c8e5c506e4c07bdabef3814903e11b3
+SHA512:
+  metadata.gz: 333bb7867bddec4a1939e205d35e5c05e0443dce411f766d263f3d27c573a54c93a8d021204fbc4edf0d4b0c255a99b6323332464dfbe7afc14a2fbe1a6cf6e9
+  data.tar.gz: edcda27654f5edce4d586d463d4f682e0f552a525eef203e68655efa751fbc2235437d34215332530e7cba0179420e366efa5146ef315deff24c6e53b687ee27

data/README.md

@@ -0,0 +1,108 @@
+# Fixed
+
+Fixed is a Ruby gem that provides a fixed-point implementation of numbers with 18-digit precision. It is designed to avoid issues with floating-point rounding errors and ensures that arithmetic operations are performed with full precision. This gem is useful in situations where it is necessary to represent rational numbers with a high degree of precision, such as in scientific or financial applications.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'fixed'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install fixed
+
+## Usage
+
+Here's an example of how to use the Fixed gem:
+
+```ruby
+require 'fixed'
+
+# Create Fixed instances
+a = Fixed(1)
+b = Fixed(6)
+
+# Perform arithmetic operations
+sum = a + b
+difference = a - b
+product = a * b
+ratio = a / b
+
+# Output the results
+puts "Sum: #{sum}"                  # => Sum: 7.00000000
+puts "Difference: #{difference}"    # => Difference: -5.00000000
+puts "Product: #{product}"          # => Product: 6.00000000
+puts "Ratio: #{ratio.format(18)}"   # => Ratio: 0.166666666666666667
+```
+
+In the above example, the Fixed gem allows you to perform arithmetic operations with high precision, avoiding rounding errors that can occur with floating-point numbers.
+
+## API
+
+### Fixed Class
+
+The `Fixed` class represents a fixed-point number with 18-digit precision.
+
+#### Constructors
+
+- `Fixed.parse(str)`: Creates a new `Fixed` instance by parsing a string representation of a fixed-point number.
+- `Fixed.from_number(number)`: Creates a new `Fixed` instance from a numeric value.
+- `Fixed.from_fractions(fractions)`: Creates a new `Fixed` instance from the raw number of fractions.
+- `Fixed.smallest`: Returns a `Fixed` instance representing the smallest possible value (1e-18).
+- `Fixed.zero`: Returns a `Fixed` instance representing zero (0).
+
+#### Arithmetic Operations
+
+The `Fixed` class supports the following arithmetic operations:
+
+- `+`, `-`, `*`, `/`: Addition, subtraction, multiplication, and division operations.
+- `-@`: Unary negation (returns a new `Fixed` instance with the opposite sign).
+- `abs`: Returns the absolute value of the `Fixed` instance.
+
+#### Comparisons
+
+The `Fixed` class includes the `Comparable` module, allowing you to compare instances of `Fixed` using comparison operators such as `<`, `>`, `<=`, `>=`, `==`, and `<=>`.
+
+#### String Formatting
+
+- `to_s(precision = 8)`: Returns a string representation of the `Fixed` instance with the specified precision.
+- `format(precision = 8)`: Returns a formatted string representation of the `Fixed` instance with the specified precision.
+- `pretty_format(precision = 8)`: Returns a formatted string representation of the `Fixed` instance with the specified precision, including thousands separators.
+
+### Kernel Method
+
+The `Fixed` gem also adds a `Fixed` method to the `Kernel` module, allowing you to create `Fixed` instances using a convenient syntax. For example:
+
+```ruby
+a = Fixed(1)
+```
+
+This is equivalent to:
+
+```ruby
+a = Fixed.from_number(1)
+```
+
+### Numeric Extension
+
+The `Fixed` gem extends the `Numeric` class with a `to_fixed` method, allowing you to convert numeric values to `Fixed` instances. For example:
+
+```ruby
+number = 1.23
+fixed = number.to_fixed
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/akuhn/fixed](https://github.com/akuhn/fixed). This project encourages collaboration and appreciates contributions. Feel free to contribute to the project by reporting bugs or submitting pull requests.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/fixed/version.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class Fixed
+  VERSION = "1.0.0"
+end
+
+
+__END__
+
+# Major version bump when breaking changes or new features
+# Minor version bump when backward-compatible changes or enhancements
+# Patch version bump when backward-compatible bug fixes, security updates etc
+
+1.0.0
+
+  - Added Fixed-number with 18-digit precision
+  - Introduced convenient constructors for creating fixed numbers
+  - Implemented basic arithmetic operations support
+  - Added functionality for comparing fixed numbers
+  - Included number formatting capabilities

data/lib/fixed.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require 'fixed/version'
+
+
+# A number with 18-digit precision.
+#
+# Fixed-point implementation of numbers with 18-digit precision, which
+# avoids issues with floating-point rounding errors and ensures that
+# arithmetic operations are performed with full precision. This class is
+# useful in situations where it's necessary to represent rational
+# numbers with a high degree of precision, such as in scientific or
+# financial applications.
+#
+# Example usage
+#
+#   a = Fixed(1)
+#   b = Fixed(6)
+#   ratio = a / b
+#   puts ratio.format(18) # => prints 1.666666666666666667
+#
+#
+
+
+class Fixed
+
+  include Comparable
+
+
+  #------- constructors ---------------------------------------------
+
+  private_class_method :new
+
+  def initialize(fractions)
+    raise unless Integer === fractions
+    @fractions = fractions
+    freeze
+  end
+
+  def self.parse(str)
+    new string_as_fractions(str)
+  end
+
+  def self.from_number(number)
+    new number_as_fractions(number)
+  end
+
+  def self.from_fractions(fractions)
+    new fractions
+  end
+
+  def self.smallest
+    new 1
+  end
+
+  def self.zero
+    new 0
+  end
+
+  #------- arithmetics ----------------------------------------------
+
+  def +(number)
+    make(self.fractions + number.fractions)
+  end
+
+  def -(number)
+    make(self.fractions - number.fractions)
+  end
+
+  def *(number)
+    make(division_with_rounding(
+      self.fractions * number.fractions,
+      1000000000000000000,
+    ))
+  end
+
+  def /(number)
+    make(division_with_rounding(
+      1000000000000000000 * self.fractions,
+      number.fractions,
+    ))
+  end
+
+  def -@
+    make(-self.fractions)
+  end
+
+  def abs
+    make(self.fractions.abs)
+  end
+
+  # ------- comparing -----------------------------------------------
+
+  def <=>(number)
+    return nil unless Fixed === number
+    self.fractions <=> number.fractions
+  end
+
+  def ==(number)
+    Fixed === number && self.fractions == number.fractions
+  end
+
+  def negative?
+    self.fractions.negative?
+  end
+
+  def positive?
+    self.fractions.positive?
+  end
+
+  def zero?
+    self.fractions.zero?
+  end
+
+
+  # ------- printing ------------------------------------------------
+
+  def inspect
+    if @fractions >= 0
+      @fractions.to_s.rjust(19, ?0).insert(-19, ?.)
+    else
+      "-#{@fractions.abs.to_s.rjust(19, ?0).insert(-19, ?.)}"
+    end
+  end
+
+  def to_s(precision = 8)
+    format(precision)
+  end
+
+  def format(precision = 8)
+    raise "expected 1..18, got #{precision.inspect}" unless (0..18) === precision
+
+    # Note: although Ruby's documentation indicates otherwise, Rational values
+    # are actually formatted with full precision rather than as floats.
+
+    str = "%.0#{precision}f" % Rational(@fractions, 1000000000000000000)
+    (str =~ /^-?0(\.0+)?$/ && @fractions != 0) ? str << ?* : str
+  end
+
+  # ------- serialization -------------------------------------------
+
+  def to_json(state)
+    inspect.to_json(state)
+  end
+
+  def self.from_snapshot(arg, options)
+    String === arg ? self.parse(arg) : arg
+  end
+
+
+  # ------- helpers -------------------------------------------------
+
+  attr_reader :fractions
+
+  def to_fixed
+    self
+  end
+
+  protected
+
+  def make(new_fractions)
+    Fixed.from_fractions new_fractions
+  end
+
+  def self.string_as_fractions(str)
+
+    # NOTE: this code has been optimized to balance execution time versus
+    # creation of unnecessary objects and string copies. We found calling
+    # String#match to be slower than calling Regexp#=~ and using special
+    # variables, and we found caching the special variables to be faster
+    # (apparently new substrings are created upon each access), and also
+    # we found string concatenation and converting integer only once to
+    # be faster than two conversions and arithmetic concatenation that
+    # correctly handles the sign for all negative numbers...
+
+    str =~ /\A(-?\d+)(?:\.(\d{1,18}))?\Z/
+    whole, decimals = $1, $2
+    raise "expected number with up to 18 decimal places, got #{str.inspect}" unless whole
+    if decimals and decimals.length == 18
+      "#{whole}#{decimals}".to_i
+    elsif decimals
+      "#{whole}#{decimals}".to_i * (10 ** (18 - decimals.length))
+    else
+      whole.to_i * 1000000000000000000
+    end
+  end
+
+  def self.number_as_fractions(number)
+    case number
+    when Float
+      # This approach ensures consistency with the visible representation
+      # of floats by avoiding rounding errors that may occur if we simply
+      # multiply by 18 digits, considering that floats have only about
+      # 15 digits of precision (see unit tests for examples).
+
+      Integer Rational(number.to_s) * 1000000000000000000
+    else
+      Integer number * 1000000000000000000
+    end
+  end
+
+  private
+
+  def division_with_rounding(numerator, denominator)
+    (numerator + (denominator / 2)) / denominator
+  end
+end
+
+module Kernel
+  def Fixed(arg)
+    case arg
+    when String
+      Fixed.parse arg
+    when Numeric
+      Fixed.from_number arg
+    else
+      raise ArgumentError
+    end
+  end
+end
+
+class Numeric
+  def to_fixed
+    Fixed.from_number self
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: fixed
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Adrian Kuhn
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-05-28 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- akuhn@iam.unibe.ch
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/fixed.rb
+- lib/fixed/version.rb
+homepage: https://github.com/akuhn/fixed
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/akuhn/fixed
+  source_code_uri: https://github.com/akuhn/fixed
+  changelog_uri: https://github.com/akuhn/fixed/blob/master/lib/fixed/version.rb
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Fixed-point numbers with 18-digit precision.
+test_files: []