money2 7.0.0.rc1

data/lib/money/allocate.rb

@@ -0,0 +1,86 @@
+class Money
+  module Allocate
+    # Allocates money between different parties without losing pennies.
+    # After the mathematical split has been performed, leftover pennies will
+    # be distributed round-robin amongst the parties. This means that parties
+    # listed first will likely receive more pennies than ones that are listed later
+    #
+    # @param [Array<Numeric>] splits [0.50, 0.25, 0.25] to give 50% of the cash to party1, 25% to party2, and 25% to party3.
+    #
+    # @return [Array<Money>]
+    #
+    # @example
+    #   Money.new(5,   "USD").allocate([0.3, 0.7])         #=> [Money.new(2), Money.new(3)]
+    #   Money.new(100, "USD").allocate([0.33, 0.33, 0.33]) #=> [Money.new(34), Money.new(33), Money.new(33)]
+    #
+    def allocate(splits)
+      allocations = splits.inject(0.to_d) { |sum, n| sum + n }
+
+      if (allocations - 1) > Float::EPSILON
+        raise ArgumentError, "splits add to more then 100%"
+      end
+
+      amounts, left_over = amounts_from_splits(allocations, splits)
+
+      unless self.class.infinite_precision
+        delta = left_over > 0 ? 1 : -1
+        # Distribute left over pennies amongst allocations
+        left_over.to_i.abs.times { |i| amounts[i % amounts.length] += delta }
+      end
+
+      subunit_to_unit = currency.subunit_to_unit
+      amounts.collect { |x| build_new(x.to_d / subunit_to_unit, currency) }
+    end
+
+    # Split money amongst parties evenly without losing pennies.
+    #
+    # @param [Numeric] num number of parties.
+    #
+    # @return [Array<Money>]
+    #
+    # @example
+    #   Money.new(100, "USD").split(3) #=> [Money.new(34), Money.new(33), Money.new(33)]
+    def split(num)
+      raise ArgumentError, "need at least one party" if num < 1
+
+      if self.class.infinite_precision
+        split_infinite(num)
+      else
+        split_flat(num)
+      end
+    end
+
+    private
+
+    def amounts_from_splits(allocations, splits)
+      fractional = self.fractional
+      left_over = fractional
+
+      amounts = splits.map do |ratio|
+        if self.class.infinite_precision
+          fractional * ratio
+        else
+          (fractional * ratio / allocations).truncate.tap do |frac|
+            left_over -= frac
+          end
+        end
+      end
+
+      [amounts, left_over]
+    end
+
+    def split_infinite(num)
+      part = div(num)
+      Array.new(num) { part }
+    end
+
+    def split_flat(num)
+      subunit_to_unit = currency.subunit_to_unit
+      fractional = self.fractional
+      low = build_new((fractional / num).to_d / subunit_to_unit, currency)
+      high = build_new(low.to_d + 1.to_d / subunit_to_unit, currency)
+      remainder = fractional % num
+      Array.new(num) { |index| index < remainder ? high : low }
+    end
+  end
+end

data/lib/money/arithmetic.rb

@@ -0,0 +1,233 @@
+class Money
+  module Arithmetic
+    # Returns a money object with changed polarity.
+    #
+    # @return [Money]
+    #
+    # @example
+    #    - Money.new(100) #=> #<Money @fractional=-100>
+    def -@
+      build_new(-to_d, currency)
+    end
+
+    # Checks whether two Money objects have the same currency and the same
+    # amount. If Money objects have a different currency it will only be true
+    # if the amounts are both zero. Checks against objects that are not Money or
+    # a subclass will always return false.
+    #
+    # @param [Money] other Value to compare with.
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   Money.new(100).eql?(Money.new(101))                #=> false
+    #   Money.new(100).eql?(Money.new(100))                #=> true
+    #   Money.new(100, "USD").eql?(Money.new(100, "GBP"))  #=> false
+    #   Money.new(0, "USD").eql?(Money.new(0, "EUR"))      #=> true
+    #   Money.new(100).eql?("1.00")                        #=> false
+    def eql?(other)
+      other.is_a?(Money) && (to_d == other.to_d) &&
+        (currency == other.currency || to_d == 0)
+    end
+
+    # Compares two Money objects. If money objects have a different currency it
+    # will attempt to convert the currency.
+    #
+    # @param [Money] other Value to compare with.
+    #
+    # @return [Fixnum]
+    #
+    # @raise [TypeError] when other object is not Money
+    #
+    def <=>(other)
+      return unless other.is_a?(Money)
+      other = other.exchange_to(currency)
+      to_d <=> other.to_d
+    rescue Money::Bank::UnknownRate
+    end
+
+    # Test if the amount is positive. Returns +true+ if the money amount is
+    # greater than 0, +false+ otherwise.
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   Money.new(1).positive?  #=> true
+    #   Money.new(0).positive?  #=> false
+    #   Money.new(-1).positive? #=> false
+    def positive?
+      to_d > 0
+    end
+
+    # Test if the amount is negative. Returns +true+ if the money amount is
+    # less than 0, +false+ otherwise.
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   Money.new(-1).negative? #=> true
+    #   Money.new(0).negative?  #=> false
+    #   Money.new(1).negative?  #=> false
+    def negative?
+      to_d < 0
+    end
+
+    # Returns a new Money object containing the sum of the two operands' monetary
+    # values. If +other+ has a different currency then its monetary value
+    # is automatically exchanged to this object's currency using +exchange_to+.
+    #
+    # @param [Money] other Other +Money+ object to add.
+    #
+    # @return [Money]
+    #
+    # @example
+    #   Money.new(100) + Money.new(100) #=> #<Money @amount=200>
+    def +(other)
+      raise TypeError unless other.is_a?(Money)
+      other = other.exchange_to(currency)
+      build_new(to_d + other.to_d, currency)
+    end
+
+    # Returns a new Money object containing the difference between the two
+    # operands' monetary values. If +other+ has a different currency then
+    # its monetary value is automatically exchanged to this object's currency
+    # using +exchange_to+.
+    #
+    # @param [Money] other Other +Money+ object to subtract.
+    #
+    # @return [Money]
+    #
+    # @example
+    #   Money.new(100) - Money.new(99) #=> #<Money @amount=1>
+    def -(other)
+      raise TypeError unless other.is_a?(Money)
+      other = other.exchange_to(currency)
+      build_new(to_d - other.to_d, currency)
+    end
+
+    # Multiplies the monetary value with the given number and returns a new
+    # +Money+ object with this monetary value and the same currency.
+    #
+    # Note that you can't multiply a Money object by an other +Money+ object.
+    #
+    # @param [Numeric] other Number to multiply by.
+    #
+    # @return [Money] The resulting money.
+    #
+    # @raise [TypeError] If +other+ is NOT a number.
+    #
+    # @example
+    #   Money.new(100) * 2 #=> #<Money @amount=200>
+    #
+    def *(other)
+      raise TypeError unless other.is_a?(Numeric)
+      build_new(to_d * other, currency)
+    end
+
+    # Divides the monetary value with the given number and returns a new +Money+
+    # object with this monetary value and the same currency.
+    # Can also divide by another +Money+ object to get a ratio.
+    #
+    # +Money/Numeric+ returns +Money+. +Money/Money+ returns +Float+.
+    #
+    # @param [Money, Numeric] other Number to divide by.
+    #
+    # @return [Money] The resulting money if you divide Money by a number.
+    # @return [Float] The resulting number if you divide Money by a Money.
+    #
+    # @example
+    #   Money.new(100) / 10            #=> #<Money @amount=10>
+    #   Money.new(100) / Money.new(10) #=> 10.0
+    #
+    def /(other)
+      if other.is_a?(Money)
+        to_d / other.exchange_to(currency).to_d
+      else
+        build_new(to_d / other.to_d, currency)
+      end
+    end
+    alias_method :div, :/
+
+    # Divide money by money or fixnum and return array containing quotient and
+    # modulus.
+    #
+    # @param [Money, Fixnum] other Number to divmod by.
+    #
+    # @return [Array<Money,Money>,Array<Fixnum,Money>]
+    #
+    # @example
+    #   Money.new(100).divmod(9)            #=> [#<Money @amount=11>, #<Money @amount=1>]
+    #   Money.new(100).divmod(Money.new(9)) #=> [11, #<Money @amount=1>]
+    def divmod(other)
+      if other.is_a?(Money)
+        delimiter = other.exchange_to(currency).to_d
+        quotient, remainder = to_d.divmod(delimiter)
+        [quotient, build_new(remainder, currency)]
+      else
+        subunit_to_unit = currency.subunit_to_unit
+        fractional.divmod(other).map { |x| build_new(x.to_d / subunit_to_unit, currency) }
+      end
+    end
+
+    # Equivalent to +divmod(other)[1]+
+    #
+    # @param [Money, Fixnum] other Number take modulo with.
+    #
+    # @return [Money]
+    #
+    # @example
+    #   Money.new(100).modulo(9)            #=> #<Money @amount=1>
+    #   Money.new(100).modulo(Money.new(9)) #=> #<Money @amount=1>
+    def %(other)
+      other = other.exchange_to(currency).to_d if other.is_a?(Money)
+      build_new(to_d.modulo(other), currency)
+    end
+    alias_method :modulo, :%
+
+    # If different signs +modulo(other) - other+ otherwise +modulo(other)+
+    #
+    # @param [Money, Fixnum] other Number to rake remainder with.
+    #
+    # @return [Money]
+    #
+    # @example
+    #   Money.new(100).remainder(9) #=> #<Money @amount=1>
+    def remainder(other)
+      other = other.exchange_to(currency).to_d if other.is_a?(Money)
+      build_new(to_d.remainder(other), currency)
+    end
+
+    # Return absolute value of self as a new Money object.
+    #
+    # @return [Money]
+    #
+    # @example
+    #   Money.new(-100).abs #=> #<Money @amount=100>
+    def abs
+      to_d >= 0 ? self : build_new(to_d.abs, currency)
+    end
+
+    # Test if the money amount is zero.
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   Money.new(100).zero? #=> false
+    #   Money.new(0).zero?   #=> true
+    def zero?
+      to_d == 0
+    end
+
+    # Test if the money amount is non-zero. Returns this money object if it is
+    # non-zero, or nil otherwise, like +Numeric#nonzero?+.
+    #
+    # @return [Money, nil]
+    #
+    # @example
+    #   Money.new(100).nonzero? #=> #<Money @amount=100>
+    #   Money.new(0).nonzero?   #=> nil
+    def nonzero?
+      to_d != 0 ? self : nil
+    end
+  end
+end

data/lib/money/bank/base.rb

@@ -0,0 +1,137 @@
+class Money
+  # Provides classes that aid in the ability of exchange one currency with
+  # another.
+  module Bank
+
+    # The lowest Money::Bank error class.
+    # All Money::Bank errors should inherit from it.
+    class Error < StandardError
+    end
+
+    # Raised when the bank doesn't know about the conversion rate
+    # for specified currencies.
+    class UnknownRate < Error
+    end
+
+
+    # Money::Bank::Base is the basic interface for creating a money exchange
+    # object, also called Bank.
+    #
+    # A Bank is responsible for storing exchange rates, take a Money object as
+    # input and returns the corresponding Money object converted into an other
+    # currency.
+    #
+    # This class exists for aiding in the creating of other classes to exchange
+    # money between different currencies. When creating a subclass you will
+    # need to implement the following methods to exchange money between
+    # currencies:
+    #
+    # - #exchange_with(Money) #=> Money
+    #
+    # See Money::Bank::VariableExchange for a real example.
+    #
+    # Also, you can extend +Money::Bank::VariableExchange+ instead of
+    # +Money::Bank::Base+ if your bank implementation needs to store rates
+    # internally.
+    #
+    # @abstract Subclass and override +#exchange_with+ to implement a custom
+    #  +Money::Bank+ class. You can also override +#setup+ instead of
+    #  +#initialize+ to setup initial variables, etc.
+    class Base
+
+      # Returns the singleton instance of the Base bank.
+      #
+      # @return [Money::Bank::Base]
+      def self.instance
+        @singleton ||= new
+      end
+
+      # The rounding method to use when exchanging rates.
+      attr_accessor :rounding_method
+
+      # Initializes a new +Money::Bank::Base+ object. An optional block can be
+      # passed to dictate the rounding method that +#exchange_with+ can use.
+      #
+      # @yield [n] Optional block to use when rounding after exchanging one
+      #  currency for another.
+      # @yieldparam [Float] n The resulting float after exchanging one currency
+      #  for another.
+      # @yieldreturn [Integer]
+      #
+      # @return [Money::Bank::Base]
+      #
+      # @example
+      #   Money::Bank::Base.new #=> #<Money::Bank::Base @rounding_method=nil>
+      #   Money::Bank::Base.new {|n|
+      #     n.floor
+      #   } #=> #<Money::Bank::Base @round_method=#<Proc>>
+      def initialize(&block)
+        @rounding_method = block
+        setup
+      end
+
+      # Called after initialize. Subclasses can use this method to setup
+      # variables, etc that they normally would in +#initialize+.
+      #
+      # @abstract Subclass and override +#setup+ to implement a custom
+      #  +Money::Bank+ class.
+      #
+      # @return [self]
+      def setup
+      end
+
+      # Exchanges the given +Money+ object to a new +Money+ object in
+      # +to_currency+.
+      #
+      # @abstract Subclass and override +#exchange_with+ to implement a custom
+      #  +Money::Bank+ class.
+      #
+      # @raise NotImplementedError
+      #
+      # @param [Money] from The +Money+ object to exchange from.
+      # @param [Money::Currency, String, Symbol] to_currency The currency
+      #  string or object to exchange to.
+      # @yield [n] Optional block to use to round the result after making
+      #  the exchange.
+      # @yieldparam [Float] n The result after exchanging from one currency to
+      #  the other.
+      # @yieldreturn [Integer]
+      #
+      # @return [Money]
+      def exchange_with(from, to_currency, &block)
+        raise NotImplementedError, "#exchange_with must be implemented"
+      end
+
+      # Given two currency strings or object, checks whether they're both the
+      # same currency. Return +true+ if the currencies are the same, +false+
+      # otherwise.
+      #
+      # @param [Money::Currency, String, Symbol] currency1 The first currency
+      #  to compare.
+      # @param [Money::Currency, String, Symbol] currency2 The second currency
+      #  to compare.
+      #
+      # @return [Boolean]
+      #
+      # @example
+      #   same_currency?("usd", "USD")                #=> true
+      #   same_currency?("usd", "EUR")                #=> false
+      #   same_currency?("usd", Currency.new("USD"))   #=> true
+      #   same_currency?("usd", "USD")                #=> true
+      def same_currency?(currency1, currency2)
+        Currency.wrap(currency1) == Currency.wrap(currency2)
+      end
+
+      # Rounds value with a given block or rounding_method.
+      def round(value, currency, mode = nil, &block)
+        method = block || mode || rounding_method
+        return value unless method
+        if method.is_a?(Symbol)
+          value.round(currency.decimal_places, method)
+        else
+          method.call(value, currency)
+        end
+      end
+    end
+  end
+end