money 7.0.2 → 7.1.0

data/sig/lib/money/money/allocation.rbs

@@ -0,0 +1,24 @@
+class Money
+  class Allocation
+    # Allocates a specified amount into parts based on their proportions or distributes
+    # it evenly when the number of parts is specified numerically.
+    #
+    # The total of the allocated amounts will always equal the original amount.
+    #
+    # The parts can be specified as:
+    #   Numeric — performs the split between a given number of parties evenly
+    #   Array<Numeric> — allocates the amounts proportionally to the given array
+    #
+    # @param amount [Numeric] The total amount to be allocated.
+    # @param parts [Numeric, Array<Numeric>] Number of parts to split into or an array (proportions for allocation).
+    # @param decimal_cutoff [bool | Integer] Controls per-split precision:
+    #   - When true, splits are truncated to whole amounts.
+    #   - When an Integer N, splits are rounded to N decimal places.
+    #   - When false or nil, no rounding/truncation is applied.
+    #   Defaults to true (whole amounts).
+    #
+    # @return [Array[Numeric]] An array containing the allocated amounts.
+    # @raise [ArgumentError] If parts is empty or not provided.
+    def self.generate: (Numeric amount, (Numeric | Array[Numeric]) parts, ?(bool | Integer) decimal_cutoff) -> Array[Numeric]
+  end
+end

data/sig/lib/money/money/arithmetic.rbs

@@ -0,0 +1,225 @@
+class Money
+  module Arithmetic
+    # Wrapper for coerced numeric values to distinguish
+    # when numeric was on the 1st place in operation.
+    CoercedNumeric: untyped
+
+    # Returns a money object with changed polarity.
+    #
+    # @return [Money]
+    #
+    # @example
+    #    - Money.new(100) #=> #<Money @fractional=-100>
+    def -@: () -> Money
+
+    # Checks whether two Money objects have the same currency and the same
+    # amount. Checks against objects that are not Money or a subclass will
+    # always return false.
+    #
+    # @param [Money] other_money Value to compare with.
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   Money.new(1_00).eql?(Money.new(1_00))               #=> true
+    #   Money.new(1_00).eql?(Money.new(1_01))               #=> false
+    #   Money.new(1_00, "USD").eql?(Money.new(1_00, "GBP")) #=> false
+    #   Money.new(0, "USD").eql?(Money.new(0, "EUR"))       #=> false
+    #   Money.new(1_00).eql?("1.00")                        #=> false
+    #
+    # @see Money.strict_eql_compare
+    def eql?: (Money other_money) -> bool
+
+    # 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 [Integer]
+    #
+    # @raise [TypeError] when other object is not Money
+    #
+    def <=>: (Money other) -> Integer
+
+    # Uses Comparable's implementation but raises ArgumentError if non-zero
+    # numeric value is given.
+    def ==: ((Money | Numeric) other) -> bool
+
+    # 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?: () -> bool
+
+    # 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?: () -> bool
+
+    # Returns a new Money object containing the sum of the two operands' monetary
+    # values. If +other_money+ 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]
+    #
+    # @raise [TypeError] If +other+ is a non-zero Numeric.
+    #
+    # @example
+    #   Money.new(100) + Money.new(100) #=> #<Money @fractional=200>
+    def +: ((Money | Numeric) other) -> Money
+
+    # Returns a new Money object containing the difference between the two
+    # operands' monetary values. If +other_money+ 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]
+    #
+    # @raise [TypeError] If +other+ is a non-zero Numeric.
+    #
+    # @example
+    #   Money.new(100) - Money.new(99) #=> #<Money @fractional=1>
+    def -: ((Money | Numeric) other) -> Money
+
+    # 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] value Number to multiply by.
+    #
+    # @return [Money] The resulting money.
+    #
+    # @raise [TypeError] If +value+ is NOT a number.
+    #
+    # @example
+    #   Money.new(100) * 2 #=> #<Money @fractional=200>
+    #
+    def *: (Numeric value) -> Money
+
+    # 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] value 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 @fractional=10>
+    #   Money.new(100) / Money.new(10) #=> 10.0
+    #
+    def /: ((Money | Numeric) value) -> (Money | Float)
+
+    # Synonym for +#/+.
+    #
+    # @param [Money, Numeric] value 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.
+    #
+    # @see #/
+    #
+    def div: ((Money | Numeric) value) -> (Money | Float)
+
+    # Divide money by money or fixnum and return array containing quotient and
+    # modulus.
+    #
+    # @param [Money, Integer] val Number to divmod by.
+    #
+    # @return [Array<Money,Money>,Array<Integer,Money>]
+    #
+    # @example
+    #   Money.new(100).divmod(9)            #=> [#<Money @fractional=11>, #<Money @fractional=1>]
+    #   Money.new(100).divmod(Money.new(9)) #=> [11, #<Money @fractional=1>]
+    def divmod: ((Money | Integer) val) -> Array[Money | Integer]
+
+    private
+
+    def divmod_money: (untyped val) -> ::Array[untyped]
+
+    def divmod_other: (untyped val) -> ::Array[untyped]
+
+    public
+
+    # Equivalent to +self.divmod(val)[1]+
+    #
+    # @param [Money, Integer] val Number take modulo with.
+    #
+    # @return [Money]
+    #
+    # @example
+    #   Money.new(100).modulo(9)            #=> #<Money @fractional=1>
+    #   Money.new(100).modulo(Money.new(9)) #=> #<Money @fractional=1>
+    def modulo: ((Money | Integer) val) -> Money
+
+    # Synonym for +#modulo+.
+    #
+    # @param [Money, Integer] val Number take modulo with.
+    #
+    # @return [Money]
+    #
+    # @see #modulo
+    def %: ((Money | Integer) val) -> Money
+
+    # If different signs +self.modulo(val) - val+ otherwise +self.modulo(val)+
+    #
+    # @param [Money, Integer] val Number to rake remainder with.
+    #
+    # @return [Money]
+    #
+    # @example
+    #   Money.new(100).remainder(9) #=> #<Money @fractional=1>
+    def remainder: ((Money | Integer) val) -> Money
+
+    # Return absolute value of self as a new Money object.
+    #
+    # @return [Money]
+    #
+    # @example
+    #   Money.new(-100).abs #=> #<Money @fractional=100>
+    def abs: () -> Money
+
+    # Test if the money amount is zero.
+    #
+    # @return [Boolean]
+    #
+    # @example
+    #   Money.new(100).zero? #=> false
+    #   Money.new(0).zero?   #=> true
+    def zero?: () -> bool
+
+    # 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 @fractional=100>
+    #   Money.new(0).nonzero?   #=> nil
+    def nonzero?: () -> Arithmetic?
+
+    # Used to make Money instance handle the operations when arguments order is reversed
+    # @return [Array]
+    #
+    # @example
+    #   2 * Money.new(10) #=> #<Money @fractional=20>
+    def coerce: (untyped other) -> ::Array[self | untyped]
+  end
+end

data/sig/lib/money/money/constructors.rbs

@@ -0,0 +1,73 @@
+class Money
+  module Constructors
+    # Create a new money object with value 0.
+    #
+    # @param [Currency, String, Symbol] currency The currency to use.
+    #
+    # @return [Money]
+    #
+    # @example
+    #   Money.empty #=> #<Money @fractional=0>
+    def empty: (?(Money::Currency | string | Symbol) currency) -> Money
+
+    alias zero empty
+
+    # Creates a new Money object of the given value, using the Canadian
+    # dollar currency.
+    #
+    # @param [Integer] cents The cents value.
+    #
+    # @return [Money]
+    #
+    # @example
+    #   n = Money.ca_dollar(100)
+    #   n.cents    #=> 100
+    #   n.currency #=> #<Money::Currency id: cad>
+    def ca_dollar: (int cents) -> Money
+
+    alias cad ca_dollar
+
+    # Creates a new Money object of the given value, using the American dollar
+    # currency.
+    #
+    # @param [Integer] cents The cents value.
+    #
+    # @return [Money]
+    #
+    # @example
+    #   n = Money.us_dollar(100)
+    #   n.cents    #=> 100
+    #   n.currency #=> #<Money::Currency id: usd>
+    def us_dollar: (int cents) -> Money
+
+    alias usd us_dollar
+
+    # Creates a new Money object of the given value, using the Euro currency.
+    #
+    # @param [Integer] cents The cents value.
+    #
+    # @return [Money]
+    #
+    # @example
+    #   n = Money.euro(100)
+    #   n.cents    #=> 100
+    #   n.currency #=> #<Money::Currency id: eur>
+    def euro: (int cents) -> Money
+
+    alias eur euro
+
+    # Creates a new Money object of the given value, in British pounds.
+    #
+    # @param [Integer] pence The pence value.
+    #
+    # @return [Money]
+    #
+    # @example
+    #   n = Money.pound_sterling(100)
+    #   n.fractional    #=> 100
+    #   n.currency #=> #<Money::Currency id: gbp>
+    def pound_sterling: (int pence) -> Money
+
+    alias gbp pound_sterling
+  end
+end

data/sig/lib/money/money/formatter.rbs

@@ -0,0 +1,214 @@
+class Money
+  class Formatter
+    DEFAULTS: Hash[Symbol, string]
+
+    # Creates a formatted price string according to several rules.
+    #
+    # @param [Hash] rules The options used to format the string.
+    #
+    # @return [String]
+    #
+    # @option rules [Boolean, String] :display_free (false) Whether a zero
+    #  amount of money should be formatted of "free" or as the supplied string.
+    #
+    # @example
+    #   Money.us_dollar(0).format(display_free: true)     #=> "free"
+    #   Money.us_dollar(0).format(display_free: "gratis") #=> "gratis"
+    #   Money.us_dollar(0).format                            #=> "$0.00"
+    #
+    # @option rules [Boolean] :with_currency (false) Whether the currency name
+    #  should be appended to the result string.
+    #
+    # @example
+    #   Money.ca_dollar(100).format #=> "$1.00"
+    #   Money.ca_dollar(100).format(with_currency: true) #=> "$1.00 CAD"
+    #   Money.us_dollar(85).format(with_currency: true)  #=> "$0.85 USD"
+    #
+    # @option rules [Boolean] :rounded_infinite_precision (false) Whether the
+    #  amount of money should be rounded when using {infinite_precision}
+    #
+    # @example
+    #   Money.us_dollar(100.1).format #=> "$1.001"
+    #   Money.us_dollar(100.1).format(rounded_infinite_precision: true) #=> "$1"
+    #   Money.us_dollar(100.9).format(rounded_infinite_precision: true) #=> "$1.01"
+    #
+    # @option rules [Boolean] :no_cents (false) Whether cents should be omitted.
+    #
+    # @example
+    #   Money.ca_dollar(100).format(no_cents: true) #=> "$1"
+    #   Money.ca_dollar(599).format(no_cents: true) #=> "$5"
+    #
+    # @option rules [Boolean] :no_cents_if_whole (false) Whether cents should be
+    #  omitted if the cent value is zero
+    #
+    # @example
+    #   Money.ca_dollar(10000).format(no_cents_if_whole: true) #=> "$100"
+    #   Money.ca_dollar(10034).format(no_cents_if_whole: true) #=> "$100.34"
+    #
+    # @option rules [Boolean, String, nil] :symbol (true) Whether a money symbol
+    #  should be prepended to the result string. The default is true. This method
+    #  attempts to pick a symbol that's suitable for the given currency.
+    #
+    # @example
+    #   Money.new(100, "USD") #=> "$1.00"
+    #   Money.new(100, "GBP") #=> "£1.00"
+    #   Money.new(100, "EUR") #=> "€1.00"
+    #
+    #   # Same thing.
+    #   Money.new(100, "USD").format(symbol: true) #=> "$1.00"
+    #   Money.new(100, "GBP").format(symbol: true) #=> "£1.00"
+    #   Money.new(100, "EUR").format(symbol: true) #=> "€1.00"
+    #
+    #   # You can specify a false expression or an empty string to disable
+    #   # prepending a money symbol.§
+    #   Money.new(100, "USD").format(symbol: false) #=> "1.00"
+    #   Money.new(100, "GBP").format(symbol: nil)   #=> "1.00"
+    #   Money.new(100, "EUR").format(symbol: "")    #=> "1.00"
+    #
+    #   # If the symbol for the given currency isn't known, then it will default
+    #   # to "¤" as symbol.
+    #   Money.new(100, "AWG").format(symbol: true) #=> "¤1.00"
+    #
+    #   # You can specify a string as value to enforce using a particular symbol.
+    #   Money.new(100, "AWG").format(symbol: "ƒ") #=> "ƒ1.00"
+    #
+    #   # You can specify a indian currency format
+    #   Money.new(10000000, "INR").format(south_asian_number_formatting: true) #=> "1,00,000.00"
+    #   Money.new(10000000).format(south_asian_number_formatting: true) #=> "$1,00,000.00"
+    #
+    # @option rules [Boolean, String, nil] :decimal_mark (true) Whether the
+    #  currency should be separated by the specified character or '.'
+    #
+    # @example
+    #   # If a string is specified, it's value is used.
+    #   Money.new(100, "USD").format(decimal_mark: ",") #=> "$1,00"
+    #
+    #   # If the decimal_mark for a given currency isn't known, then it will default
+    #   # to "." as decimal_mark.
+    #   Money.new(100, "FOO").format #=> "$1.00"
+    #
+    # @option rules [Boolean, String, nil] :thousands_separator (true) Whether
+    #  the currency should be delimited by the specified character or ','
+    #
+    # @example
+    #   # If a falsey value is specified, no thousands_separator is used.
+    #   Money.new(100000, "USD").format(thousands_separator: false) #=> "1000.00"
+    #   Money.new(100000, "USD").format(thousands_separator: nil)   #=> "1000.00"
+    #   Money.new(100000, "USD").format(thousands_separator: "")    #=> "1000.00"
+    #
+    #   # If true is specified, the locale or default thousands_separator is used.
+    #   Money.new(100000, "USD").format(thousands_separator: true) #=> "1,000.00"
+    #
+    #   # If a string is specified, it's value is used.
+    #   Money.new(100000, "USD").format(thousands_separator: ".") #=> "$1.000.00"
+    #
+    #   # If the thousands_separator for a given currency isn't known, then it will
+    #   # default to "," as thousands_separator.
+    #   Money.new(100000, "FOO").format #=> "$1,000.00"
+    #
+    # @option rules [Boolean] :html_wrap (false) Whether all currency parts should be HTML-formatted.
+    #
+    # @example
+    #   Money.ca_dollar(570).format(html_wrap: true, with_currency: true)
+    #   #=> "<span class=\"money-currency-symbol\">$</span><span class=\"money-whole\">5</span><span class=\"money-decimal-mark\">.</span><span class=\"money-decimal\">70</span> <span class=\"money-currency\">CAD</span>"
+    #
+    # @option rules [Boolean] :sign_positive (false) Whether positive numbers should be
+    #  signed, too.
+    #
+    # @example
+    #   # You can specify to display the sign with positive numbers
+    #   Money.new(100, "GBP").format(sign_positive: true,  sign_before_symbol: true)  #=> "+£1.00"
+    #   Money.new(100, "GBP").format(sign_positive: true,  sign_before_symbol: false) #=> "£+1.00"
+    #   Money.new(100, "GBP").format(sign_positive: false, sign_before_symbol: true)  #=> "£1.00"
+    #   Money.new(100, "GBP").format(sign_positive: false, sign_before_symbol: false) #=> "£1.00"
+    #   Money.new(100, "GBP").format                               #=> "£+1.00"
+    #
+    # @option rules [Boolean] :disambiguate (false) Prevents the result from being ambiguous
+    #  due to equal symbols for different currencies. Uses the `disambiguate_symbol`.
+    #
+    # @example
+    #   Money.new(10000, "USD").format(disambiguate: false)   #=> "$100.00"
+    #   Money.new(10000, "CAD").format(disambiguate: false)   #=> "$100.00"
+    #   Money.new(10000, "USD").format(disambiguate: true)    #=> "US$100.00"
+    #   Money.new(10000, "CAD").format(disambiguate: true)    #=> "C$100.00"
+    #
+    # @option rules [Boolean] :translate (true) `true` Checks for custom
+    #   symbol definitions using I18n.
+    #
+    # @example
+    #   # With the following entry in the translation files:
+    #   # en:
+    #   #   number:
+    #   #     currency:
+    #   #       symbol:
+    #   #         CAD: "CAD$"
+    #   Money.new(10000, "CAD").format(translate: true) #=> "CAD$100.00"
+    #
+    # @option rules [Boolean] :drop_trailing_zeros (false) Ignore trailing zeros after
+    #   the decimal mark
+    #
+    # @example
+    #   Money.new(89000, :btc).format(drop_trailing_zeros: true) #=> B⃦0.00089
+    #   Money.new(110, :usd).format(drop_trailing_zeros: true)   #=> $1.1
+    #
+    # @option rules [Boolean] :delimiter_pattern (/(\d)(?=(?:\d{3})+(?:[^\d]{1}|$))/) Regular expression to set the placement
+    #   for the thousands delimiter
+    #
+    # @example
+    #   Money.new(89000, :btc).format(delimiter_pattern: /(\d)(?=\d)/) #=> B⃦8,9,0.00
+    #
+    # @option rules [String] :format (nil) Provide a template for formatting. `%u` will be replaced
+    # with the symbol (if present) and `%n` will be replaced with the number.
+    #
+    # @example
+    #   Money.new(10000, "USD").format(format: '%u %n') #=> "$ 100.00"
+    #   Money.new(10000, "USD").format(format: '<span>%u%n</span>')  #=> "<span>$100.00</span>"
+    #
+    # Note that the default rules can be defined through {Money.default_formatting_rules} hash.
+    #
+    # @see Money.default_formatting_rules Money.default_formatting_rules for more information.
+    def initialize: (untyped money, *untyped rules) -> void
+
+    def to_s: () -> string
+
+    def thousands_separator: () -> string
+
+    def decimal_mark: () -> string
+
+    alias delimiter thousands_separator
+
+    alias separator decimal_mark
+
+    private
+
+    attr_reader money: Money
+
+    attr_reader currency: Currency
+
+    attr_reader rules: FormattingRules
+
+    def format_number: () -> string
+
+    def append_sign: (untyped formatted_number) -> string
+
+    def append_currency_symbol: (untyped formatted_number) -> string
+
+    def show_free_text?: () -> untyped
+
+    def html_wrap: (string string, string class_name) -> ::String
+
+    def free_text: () -> (untyped | "free")
+
+    def format_whole_part: (untyped value) -> untyped
+
+    def extract_whole_and_decimal_parts: () -> Array[string]
+
+    def format_decimal_part: (untyped value) -> (nil | string)
+
+    def lookup: (Symbol key) -> untyped
+
+    def lookup_default: (Symbol key) -> untyped
+
+    def symbol_value_from: (Hash[Symbol, untyped] rules) -> (untyped | untyped | "" | untyped)
+  end
+end

data/sig/lib/money/money/formatting_rules.rbs

@@ -0,0 +1,32 @@
+class Money
+  class FormattingRules
+    @rules: Hash[Symbol, untyped]
+
+    def initialize: (untyped currency, *untyped raw_rules) -> void
+
+    def []: (untyped key) -> untyped
+
+    def has_key?: (untyped key) -> untyped
+
+    private
+
+    attr_reader currency: untyped
+
+    # Cleans up formatting rules.
+    #
+    # @param [Hash] rules
+    #
+    # @return [Hash]
+    def normalize_formatting_rules: (Hash[Symbol, untyped] rules) -> Hash[Symbol, untyped]
+
+    def default_formatting_rules: () -> Hash[Symbol, untyped]
+
+    def translate_formatting_rules: (Hash[Symbol, untyped] rules) -> Hash[Symbol, untyped]
+
+    def determine_format: () -> String
+
+    def default_format: () -> String
+
+    def delimiter_pattern_rule: (Hash[Symbol, untyped] rules) -> ::Regexp
+  end
+end

data/sig/lib/money/money/locale_backend.rbs

@@ -0,0 +1,7 @@
+class Money
+  module LocaleBackend
+    BACKENDS: { i18n: untyped, currency: untyped }
+
+    def self.find: (untyped name) -> untyped
+  end
+end