micro-lite-lib 0.0.1

data/money-7.0.2/lib/money/money.rb

@@ -0,0 +1,664 @@
+# frozen_string_literal: true
+
+require "money/bank/variable_exchange"
+require "money/bank/single_currency"
+require "money/money/arithmetic"
+require "money/money/constructors"
+require "money/money/formatter"
+require "money/money/allocation"
+require "money/money/locale_backend"
+
+# "Money is any object or record that is generally accepted as payment for
+# goods and services and repayment of debts in a given socio-economic context
+# or country." -Wikipedia
+#
+# An instance of Money represents an amount of a specific currency.
+#
+# Money is a value object and should be treated as immutable.
+#
+# @see https://en.wikipedia.org/wiki/Money
+class Money
+  include Comparable
+  include Money::Arithmetic
+  extend Constructors
+
+  # Raised when smallest denomination of a currency is not defined
+  class UndefinedSmallestDenomination < StandardError; end
+
+  # Convenience method for fractional part of the amount. Synonym of #fractional
+  #
+  # @return [Integer] when infinite_precision is false
+  # @return [BigDecimal] when infinite_precision is true
+  #
+  # @see infinite_precision
+  def cents
+    fractional
+  end
+
+  # The value of the monetary amount represented in the fractional or subunit
+  # of the currency.
+  #
+  # For example, in the US dollar currency the fractional unit is cents, and
+  # there are 100 cents in one US dollar. So given the Money representation of
+  # one US dollar, the fractional interpretation is 100.
+  #
+  # Another example is that of the Kuwaiti dinar. In this case the fractional
+  # unit is the fils and there 1000 fils to one Kuwaiti dinar. So given the
+  # Money representation of one Kuwaiti dinar, the fractional interpretation is
+  # 1000.
+  #
+  # @return [Integer] when infinite_precision is false
+  # @return [BigDecimal] when infinite_precision is true
+  #
+  # @see infinite_precision
+  def fractional
+    # Ensure we have a BigDecimal. If the Money object is created
+    # from YAML, @fractional can end up being set to a Float.
+    fractional = as_d(@fractional)
+
+    return_value(fractional)
+  end
+
+  # Round a given amount of money to the nearest possible amount in cash value. For
+  # example, in Swiss franc (CHF), the smallest possible amount of cash value is
+  # CHF 0.05. Therefore, this method rounds CHF 0.07 to CHF 0.05, and CHF 0.08 to
+  # CHF 0.10.
+  #
+  # @return [Integer] when infinite_precision is false
+  # @return [BigDecimal] when infinite_precision is true
+  #
+  # @see infinite_precision
+  def round_to_nearest_cash_value
+    warn "[DEPRECATION] `round_to_nearest_cash_value` is deprecated - use " \
+         "`to_nearest_cash_value.fractional` instead"
+
+    to_nearest_cash_value.fractional
+  end
+
+  # Round a given amount of money to the nearest possible money in cash value.
+  # For example, in Swiss franc (CHF), the smallest possible amount of cash
+  # value is CHF 0.05. Therefore, this method rounds CHF 0.07 to CHF 0.05, and
+  # CHF 0.08 to CHF 0.10.
+  #
+  # @return [Money]
+  def to_nearest_cash_value
+    unless self.currency.smallest_denomination
+      raise UndefinedSmallestDenomination,
+            "Smallest denomination of this currency is not defined"
+    end
+
+    fractional = as_d(@fractional)
+    smallest_denomination = as_d(self.currency.smallest_denomination)
+    rounded_value =
+      (fractional / smallest_denomination)
+        .round(0, self.class.rounding_mode) * smallest_denomination
+
+    dup_with(fractional: return_value(rounded_value))
+  end
+
+  # @!attribute [r] currency
+  #   @return [Currency] The money's currency.
+  # @!attribute [r] bank
+  #   @return [Money::Bank::Base] The +Money::Bank+-based object which currency
+  #     exchanges are performed with.
+
+  attr_reader :currency, :bank
+
+  # Class Methods
+  class << self
+
+    # @!attribute [rw] default_bank
+    #   Used to set a default bank for currency exchange.
+    #
+    #   Each Money object is associated with a bank
+    #   object, which is responsible for currency exchange. This property
+    #   allows you to specify the default bank object. The default value for
+    #   this property is an instance of +Bank::VariableExchange.+ It allows
+    #   one to specify custom exchange rates.
+    #
+    #   @return [Money::Bank::Base]
+    #
+    # @!attribute default_formatting_rules
+    #   Used to define a default hash of rules for every time
+    #   +Money#format+ is called.  Rules provided on method call will be
+    #   merged with the default ones.  To overwrite a rule, just provide the
+    #   intended value while calling +format+.
+    #
+    #   @see Money::Formatter#initialize Money::Formatter for more details
+    #
+    #   @example
+    #     Money.default_formatting_rules = { display_free: true }
+    #     Money.new(0, "USD").format                          # => "free"
+    #     Money.new(0, "USD").format(display_free: false)  # => "$0.00"
+    #
+    #   @return [Hash]
+    #
+    # @!attribute [rw] default_infinite_precision
+    #   @return [Boolean] Use this to enable infinite precision cents as the
+    #     global default
+    #
+    # @!attribute [rw] conversion_precision
+    #   Used to specify precision for converting Rational to BigDecimal
+    #
+    #   @return [Integer]
+    #
+    # @!attribute [rw] strict_eql_compare
+    #    Use this to specify how +Money#eql?+ behaves. Opt-in to the new
+    #    behavior by setting this to +true+ and disable warnings when comparing
+    #    zero amounts with different currencies.
+    #
+    #    @example
+    #      Money.strict_eql_compare = false # (default)
+    #      Money.new(0, "USD").eql?(Money.new(0, "EUR")) # => true
+    #      # => [DEPRECATION] warning
+    #
+    #      Money.strict_eql_compare = true
+    #      Money.new(0, "USD").eql?(Money.new(0, "EUR")) # => false
+    #
+    #    @return [Boolean]
+    #
+    #    @see Money#eql
+    attr_accessor :default_formatting_rules,
+                  :default_infinite_precision,
+                  :conversion_precision,
+                  :strict_eql_compare
+    attr_reader :locale_backend
+    attr_writer :default_bank
+  end
+
+  # @!attribute default_currency
+  #   @return [Money::Currency] The default currency, which is used when
+  #     +Money.new+ is called without an explicit currency argument.
+  def self.default_currency
+    if @default_currency.nil?
+      nil
+    elsif @default_currency.respond_to?(:call)
+      Money::Currency.new(@default_currency.call)
+    else
+      Money::Currency.new(@default_currency)
+    end
+  end
+
+  def self.default_currency=(currency)
+    @default_currency = currency
+  end
+
+  # Modified to support thread-local bank override
+  def self.default_bank
+    # Check for thread-local bank first, then fall back to global default
+    return Thread.current[:money_bank] if Thread.current[:money_bank]
+
+    if @default_bank.respond_to?(:call)
+      @default_bank.call
+    else
+      @default_bank
+    end
+  end
+
+  # Thread-safe bank switching method
+  # Temporarily changes the default bank in the current thread only
+  #
+  # @param [Money::Bank::Base] bank The bank to use within the block
+  # @yield The block within which the bank will be changed
+  # @return [Object] block results
+  #
+  # @example
+  #   Money.with_bank(european_bank) do
+  #     Money.new(100, "USD").exchange_to("EUR")
+  #   end
+  def self.with_bank(bank)
+    original_bank = Thread.current[:money_bank]
+    Thread.current[:money_bank] = bank
+    yield
+  ensure
+    Thread.current[:money_bank] = original_bank
+  end
+
+  def self.locale_backend=(value)
+    @locale_backend = value ? LocaleBackend.find(value) : nil
+  end
+
+  # @attr_writer rounding_mode Use this to specify the rounding mode
+  def self.rounding_mode=(new_rounding_mode)
+    @rounding_mode = new_rounding_mode
+  end
+
+  def self.setup_defaults
+    # Set the default bank for creating new +Money+ objects.
+    self.default_bank = Bank::VariableExchange.instance
+
+    # Default to using currency backend
+    self.locale_backend = :currency
+
+    # Default to not using infinite precision cents
+    self.default_infinite_precision = false
+
+    # Default rounding mode toward the nearest neighbor; if the neighbors are equidistant, round away from zero
+    self.rounding_mode = BigDecimal::ROUND_HALF_UP
+
+    # Default the conversion of Rationals precision to 16
+    self.conversion_precision = 16
+
+    # Defaults to the deprecated behavior where
+    # `Money.new(0, "USD").eql?(Money.new(0, "EUR"))` is true.
+    self.strict_eql_compare = false
+  end
+
+  def self.inherited(base)
+    base.setup_defaults
+  end
+
+  setup_defaults
+
+  # Use this to return the rounding mode.
+  #
+  # @return [BigDecimal::ROUND_MODE] rounding mode
+  def self.rounding_mode
+    return Thread.current[:money_rounding_mode] if Thread.current[:money_rounding_mode]
+
+    @rounding_mode
+  end
+
+  # Temporarily changes the rounding mode in a given block.
+  #
+  # @param [BigDecimal::ROUND_MODE] mode
+  #
+  # @yield The block within which rounding mode will be changed. Its return
+  #   value will also be the return value of the whole method.
+  #
+  # @return [Object] block results
+  #
+  # @example
+  #   fee = Money.with_rounding_mode(BigDecimal::ROUND_HALF_DOWN) do
+  #     Money.new(1200) * BigDecimal('0.029')
+  #   end
+  def self.with_rounding_mode(mode)
+    original_mode = Thread.current[:money_rounding_mode]
+    Thread.current[:money_rounding_mode] = mode
+    yield
+  ensure
+    Thread.current[:money_rounding_mode] = original_mode
+  end
+
+  # Adds a new exchange rate to the default bank and return the rate.
+  #
+  # @param [Currency, String, Symbol] from_currency Currency to exchange from.
+  # @param [Currency, String, Symbol] to_currency Currency to exchange to.
+  # @param [Numeric] rate Rate to exchange with.
+  #
+  # @return [Numeric]
+  #
+  # @example
+  #   Money.add_rate("USD", "CAD", 1.25) #=> 1.25
+  def self.add_rate(from_currency, to_currency, rate)
+    Money.default_bank.add_rate(from_currency, to_currency, rate)
+  end
+
+  # Sets the default bank to be a SingleCurrency bank that raises on
+  # currency exchange. Useful when apps operate in a single currency at a time.
+  def self.disallow_currency_conversion!
+    self.default_bank = Bank::SingleCurrency.instance
+  end
+
+  # Creates a new Money object of value given in the +unit+ of the given
+  # +currency+.
+  #
+  # @param [Numeric] amount The numerical value of the money.
+  # @param [Currency, String, Symbol] currency The currency format.
+  # @param [Hash] options Optional settings for the new Money instance
+  # @option [Money::Bank::*] :bank The exchange bank to use.
+  #
+  # @example
+  #   Money.from_amount(23.45, "USD") # => #<Money fractional:2345 currency:USD>
+  #   Money.from_amount(23.45, "JPY") # => #<Money fractional:23 currency:JPY>
+  #
+  # @return [Money]
+  #
+  # @see #initialize
+  def self.from_amount(amount, currency = default_currency, options = {})
+    raise ArgumentError, "'amount' must be numeric" unless Numeric === amount
+
+    currency = Currency.wrap(currency) || Money.default_currency
+    raise Currency::NoCurrency, 'must provide a currency' if currency.nil?
+
+    value = amount.to_d * currency.subunit_to_unit
+    new(value, currency, options)
+  end
+
+  # DEPRECATED.
+  #
+  # @see Money.from_amount
+  def self.from_dollars(amount, currency = default_currency, options = {})
+    warn "[DEPRECATION] `Money.from_dollars` is deprecated in favor of " \
+         "`Money.from_amount`."
+
+    from_amount(amount, currency, options)
+  end
+
+  class << self
+    alias_method :from_cents, :new
+  end
+
+  # Creates a new Money object of value given in the
+  # +fractional unit+ of the given +currency+.
+  #
+  # Alternatively you can use the convenience
+  # methods like {Money.ca_dollar} and {Money.us_dollar}.
+  #
+  # @param [Object] obj Either the fractional value of the money,
+  #   a Money object, or a currency. (If passed a currency as the first
+  #   argument, a Money will be created in that currency with fractional value
+  #   = 0.
+  # @param [Currency, String, Symbol] currency The currency format.
+  # @param [Hash] options Optional settings for the new Money instance
+  # @option [Money::Bank::*] :bank The exchange bank to use.
+  #
+  # @return [Money]
+  #
+  # @example
+  #   Money.new(100)        #=> #<Money @fractional=100 @currency="USD">
+  #   Money.new(100, "USD") #=> #<Money @fractional=100 @currency="USD">
+  #   Money.new(100, "EUR") #=> #<Money @fractional=100 @currency="EUR">
+  #
+  def initialize(obj, currency = nil, options = {})
+    # For backwards compatibility, if options is not a Hash, treat it as a bank parameter
+    unless options.is_a?(Hash)
+      options = { bank: options }
+    end
+
+    @fractional = as_d(obj.respond_to?(:fractional) ? obj.fractional : obj)
+    @currency   = obj.respond_to?(:currency) ? obj.currency : Currency.wrap(currency)
+    @currency ||= Money.default_currency
+    @bank       = obj.respond_to?(:bank) ? obj.bank : options[:bank]
+    @bank     ||= Money.default_bank
+
+    # BigDecimal can be Infinity and NaN, money of that amount does not make sense
+    raise ArgumentError, 'must be initialized with a finite value' unless @fractional.finite?
+    raise Currency::NoCurrency, 'must provide a currency' if @currency.nil?
+  end
+
+  # DEPRECATED.
+  #
+  # @see #amount
+  def dollars
+    warn "[DEPRECATION] `Money#dollars` is deprecated in favor of " \
+         "`Money#amount`."
+
+    amount
+  end
+
+  # Returns the numerical value of the money.
+  #
+  # @return [BigDecimal]
+  #
+  # @example
+  #   Money.new(1_00, "USD").amount # => BigDecimal("1.00")
+  #
+  # @see #to_d
+  # @see #fractional
+  def amount
+    to_d
+  end
+
+  # Returns a Integer hash value based on the +fractional+ and +currency+ attributes
+  # in order to use functions like & (intersection), group_by, etc.
+  #
+  # @return [Integer]
+  #
+  # @example
+  #   Money.new(100).hash #=> 908351
+  def hash
+    [fractional.hash, currency.hash].hash
+  end
+
+  # Uses +Currency#symbol+. If +nil+ is returned, defaults to "¤".
+  #
+  # @return [String]
+  #
+  # @example
+  #   Money.new(100, "USD").symbol #=> "$"
+  def symbol
+    currency.symbol || "¤"
+  end
+
+  # Common inspect function
+  #
+  # @return [String]
+  def inspect
+    "#<#{self.class.name} fractional:#{fractional} currency:#{currency}>"
+  end
+
+  # Returns the amount of money as a string.
+  #
+  # @return [String]
+  #
+  # @example
+  #   Money.ca_dollar(100).to_s #=> "1.00"
+  def to_s
+    format thousands_separator: '',
+           no_cents_if_whole: currency.decimal_places == 0,
+           symbol: false,
+           ignore_defaults: true
+  end
+
+  # Return the amount of money as a BigDecimal.
+  #
+  # @return [BigDecimal]
+  #
+  # @example
+  #   Money.us_dollar(1_00).to_d #=> BigDecimal("1.00")
+  def to_d
+    as_d(fractional) / as_d(currency.subunit_to_unit)
+  end
+
+  # Return the amount of money as a Integer.
+  #
+  # @return [Integer]
+  #
+  # @example
+  #   Money.us_dollar(1_00).to_i #=> 1
+  def to_i
+    to_d.to_i
+  end
+
+  # Return the amount of money as a float. Floating points cannot guarantee
+  # precision. Therefore, this function should only be used when you no longer
+  # need to represent currency or working with another system that requires
+  # floats.
+  #
+  # @return [Float]
+  #
+  # @example
+  #   Money.us_dollar(100).to_f #=> 1.0
+  def to_f
+    to_d.to_f
+  end
+
+  # Returns a new Money instance in a given currency leaving the amount intact
+  # and not performing currency conversion.
+  #
+  # @param [Currency, String, Symbol] new_currency Currency of the new object.
+  #
+  # @return [self]
+  def with_currency(new_currency)
+    new_currency = Currency.wrap(new_currency)
+    if !new_currency || currency == new_currency
+      self
+    else
+      dup_with(currency: new_currency)
+    end
+  end
+
+  # Conversion to +self+.
+  #
+  # @return [self]
+  def to_money(given_currency = nil)
+    given_currency = Currency.wrap(given_currency)
+    if given_currency.nil? || self.currency == given_currency
+      self
+    else
+      exchange_to(given_currency)
+    end
+  end
+
+  # Receive the amount of this money object in another Currency.
+  #
+  # @param [Currency, String, Symbol] other_currency Currency to exchange to.
+  #
+  # @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]
+  #
+  # @example
+  #   Money.new(2000, "USD").exchange_to("EUR")
+  #   Money.new(2000, "USD").exchange_to("EUR") {|x| x.round}
+  #   Money.new(2000, "USD").exchange_to(Currency.new("EUR"))
+  def exchange_to(other_currency, &rounding_method)
+    other_currency = Currency.wrap(other_currency)
+    if self.currency == other_currency
+      self
+    else
+      @bank.exchange_with(self, other_currency, &rounding_method)
+    end
+  end
+
+  # Receive a money object with the same amount as the current Money object
+  # in United States dollar.
+  #
+  # @return [Money]
+  #
+  # @example
+  #   n = Money.new(100, "CAD").as_us_dollar
+  #   n.currency #=> #<Money::Currency id: usd>
+  def as_us_dollar
+    exchange_to("USD")
+  end
+
+  # Receive a money object with the same amount as the current Money object
+  # in Canadian dollar.
+  #
+  # @return [Money]
+  #
+  # @example
+  #   n = Money.new(100, "USD").as_ca_dollar
+  #   n.currency #=> #<Money::Currency id: cad>
+  def as_ca_dollar
+    exchange_to("CAD")
+  end
+
+  # Receive a money object with the same amount as the current Money object
+  # in euro.
+  #
+  # @return [Money]
+  #
+  # @example
+  #   n = Money.new(100, "USD").as_euro
+  #   n.currency #=> #<Money::Currency id: eur>
+  def as_euro
+    exchange_to("EUR")
+  end
+
+  # Splits a given amount in parts without losing pennies. The left-over pennies will be
+  # distributed round-robin amongst the parties. This means that parts listed first will likely
+  # receive more pennies than ones listed later.
+  #
+  # Pass [2, 1, 1] as input to give twice as much to part1 as part2 or
+  # part3 which results in 50% of the cash to party1, 25% to part2, and 25% to part3. Passing a
+  # number instead of an array will split the amount evenly (without losing pennies when rounding).
+  #
+  # @param [Array<Numeric>, Numeric] parts how amount should be distributed to parts
+  #
+  # @return [Array<Money>]
+  #
+  # @example
+  #   Money.new(5,   "USD").allocate([3, 7]) #=> [Money.new(2), Money.new(3)]
+  #   Money.new(100, "USD").allocate([1, 1, 1]) #=> [Money.new(34), Money.new(33), Money.new(33)]
+  #   Money.new(100, "USD").allocate(2) #=> [Money.new(50), Money.new(50)]
+  #   Money.new(100, "USD").allocate(3) #=> [Money.new(34), Money.new(33), Money.new(33)]
+  #
+  def allocate(parts)
+    amounts = Money::Allocation.generate(fractional, parts, !Money.default_infinite_precision)
+    amounts.map { |amount| dup_with(fractional: amount) }
+  end
+  alias_method :split, :allocate
+
+  # Round the monetary amount to smallest unit of coinage.
+  #
+  # @note
+  #   This method is only useful when operating with infinite_precision turned
+  #   on. Without infinite_precision values are rounded to the smallest unit of
+  #   coinage automatically.
+  #
+  # @return [Money]
+  #
+  # @example
+  #   Money.new(10.1, 'USD').round #=> Money.new(10, 'USD')
+  #
+  # @see Money.default_infinite_precision
+  def round(rounding_mode = self.class.rounding_mode, rounding_precision = 0)
+    rounded_amount = as_d(@fractional).round(rounding_precision, rounding_mode)
+    dup_with(fractional: rounded_amount)
+  end
+
+  # Creates a formatted price string according to several rules.
+  #
+  # @param [Hash] rules See {Money::Formatter Money::Formatter} for the list of formatting options
+  #
+  # @return [String]
+  #
+  def format(*rules)
+    Money::Formatter.new(self, *rules).to_s
+  end
+
+  # Returns a thousands separator according to the locale
+  #
+  # @return [String]
+  #
+  def thousands_separator
+    (locale_backend && locale_backend.lookup(:thousands_separator, currency)) ||
+      Money::Formatter::DEFAULTS[:thousands_separator]
+  end
+
+  # Returns a decimal mark according to the locale
+  #
+  # @return [String]
+  #
+  def decimal_mark
+    (locale_backend && locale_backend.lookup(:decimal_mark, currency)) ||
+      Money::Formatter::DEFAULTS[:decimal_mark]
+  end
+
+  def dup_with(options = {})
+    self.class.new(
+      options[:fractional] || fractional,
+      options[:currency] || currency,
+      bank: options[:bank] || bank
+    )
+  end
+
+  private
+
+  def as_d(num)
+    if num.respond_to?(:to_d)
+      num.is_a?(Rational) ? num.to_d(self.class.conversion_precision) : num.to_d
+    else
+      BigDecimal(num.to_s.empty? ? 0 : num.to_s)
+    end
+  end
+
+  def return_value(value)
+    if self.class.default_infinite_precision
+      value
+    else
+      value.round(0, self.class.rounding_mode).to_i
+    end
+  end
+
+  def locale_backend
+    self.class.locale_backend
+  end
+end