Class: Money

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Comparable
Defined in:
lib/money/money.rb,
lib/money/errors.rb,
lib/money/helpers.rb,
lib/money/version.rb,
lib/money/currency.rb,
lib/money/allocator.rb,
lib/money/null_currency.rb,
lib/money/currency/loader.rb

Defined Under Namespace

Modules: Helpers Classes: Allocator, Currency, Error, IncompatibleCurrencyError, NullCurrency, ReverseOperationProxy

Constant Summary collapse

NULL_CURRENCY = 
NullCurrency.new.freeze
VERSION = 
"0.13.0"

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(value, currency) ⇒ Money

Returns a new instance of Money.

Raises:

  • (ArgumentError) 


83
84
85
86
87
88
 
# File 'lib/money/money.rb', line 83

def initialize(value, currency)
  raise ArgumentError if value.nan?
  @currency = Helpers.value_to_currency(currency)
  @value = value.round(@currency.minor_units)
  freeze
end

Class Attribute Details

.default_currency ⇒ Object

Returns the value of attribute default_currency.



13
14
15
 
# File 'lib/money/money.rb', line 13

def default_currency
  @default_currency
end

.parser ⇒ Object

Returns the value of attribute parser.



13
14
15
 
# File 'lib/money/money.rb', line 13

def parser
  @parser
end

Instance Attribute Details

#currency ⇒ Object (readonly)

Returns the value of attribute currency.



9
10
11
 
# File 'lib/money/money.rb', line 9

def currency
  @currency
end

#value ⇒ Object (readonly)

Returns the value of attribute value.



9
10
11
 
# File 'lib/money/money.rb', line 9

def value
  @value
end

Class Method Details

.current_currency ⇒ Object 



54
55
56
 
# File 'lib/money/money.rb', line 54

def current_currency
  Thread.current[:money_currency]
end

.current_currency=(currency) ⇒ Object 



58
59
60
 
# File 'lib/money/money.rb', line 58

def current_currency=(currency)
  Thread.current[:money_currency] = currency
end

.default_settings ⇒ Object 



76
77
78
79
 
# File 'lib/money/money.rb', line 76

def default_settings
  self.parser = MoneyParser
  self.default_currency = Money::NULL_CURRENCY
end

.from_cents(cents, currency = nil) ⇒ Object 



37
38
39
 
# File 'lib/money/money.rb', line 37

def from_cents(cents, currency = nil)
  new(cents.round.to_f / 100, currency)
end

.from_subunits(subunits, currency_iso) ⇒ Object 



41
42
43
44
45
 
# File 'lib/money/money.rb', line 41

def from_subunits(subunits, currency_iso)
  currency = Helpers.value_to_currency(currency_iso)
  value = Helpers.value_to_decimal(subunits) / currency.subunit_to_unit
  new(value, currency)
end

.new(value = 0, currency = nil) ⇒ Object Also known as: from_amount 



15
16
17
18
19
20
21
22
23
24
25
 
# File 'lib/money/money.rb', line 15

def new(value = 0, currency = nil)
  value = Helpers.value_to_decimal(value)
  currency = Helpers.value_to_currency(currency)

  if value.zero?
    @@zero_money ||= {}
    @@zero_money[currency.iso_code] ||= super(Helpers::DECIMAL_ZERO, currency)
  else
    super(value, currency)
  end
end

.parse(*args) ⇒ Object 



33
34
35
 
# File 'lib/money/money.rb', line 33

def parse(*args)
  parser.parse(*args)
end

.rational(money1, money2) ⇒ Object 



47
48
49
50
51
52
 
# File 'lib/money/money.rb', line 47

def rational(money1, money2)
  money1.send(:arithmetic, money2) do
    factor = money1.currency.subunit_to_unit * money2.currency.subunit_to_unit
    Rational((money1.value * factor).to_i, (money2.value * factor).to_i)
  end
end

.with_currency(new_currency) ⇒ Object

Set Money.default_currency inside the supplied block, resets it to the previous value when done to prevent leaking state. Similar to I18n.with_locale and ActiveSupport’s Time.use_zone. This won’t affect instances being created with explicitly set currency.



66
67
68
69
70
71
72
73
74
 
# File 'lib/money/money.rb', line 66

def with_currency(new_currency)
  begin
    old_currency = Money.current_currency
    Money.current_currency = new_currency
    yield
  ensure
    Money.current_currency = old_currency
  end
end

.zero(currency = NULL_CURRENCY) ⇒ Object Also known as: empty 



28
29
30
 
# File 'lib/money/money.rb', line 28

def zero(currency = NULL_CURRENCY)
  new(0, currency)
end

Instance Method Details

#*(numeric) ⇒ Object 



135
136
137
138
139
140
 
# File 'lib/money/money.rb', line 135

def *(numeric)
  unless numeric.is_a?(Numeric)
    Money.deprecate("Multiplying Money with #{numeric.class.name} is deprecated and will be removed in the next major release.")
  end
  Money.new(value.to_r * numeric, currency)
end

#+(other) ⇒ Object 



123
124
125
126
127
 
# File 'lib/money/money.rb', line 123

def +(other)
  arithmetic(other) do |money|
    Money.new(value + money.value, calculated_currency(money.currency))
  end
end

#-(other) ⇒ Object 



129
130
131
132
133
 
# File 'lib/money/money.rb', line 129

def -(other)
  arithmetic(other) do |money|
    Money.new(value - money.value, calculated_currency(money.currency))
  end
end

#-@ ⇒ Object 



112
113
114
 
# File 'lib/money/money.rb', line 112

def -@
  Money.new(-value, currency)
end

#/(numeric) ⇒ Object 



142
143
144
 
# File 'lib/money/money.rb', line 142

def /(numeric)
  raise "[Money] Dividing money objects can lose pennies. Use #split instead"
end

#<=>(other) ⇒ Object 



116
117
118
119
120
121
 
# File 'lib/money/money.rb', line 116

def <=>(other)
  return unless other.respond_to?(:to_money)
  arithmetic(other) do |money|
    value <=> money.value
  end
end

#==(other) ⇒ Object 



150
151
152
 
# File 'lib/money/money.rb', line 150

def ==(other)
  eql?(other)
end

#abs ⇒ Object 



229
230
231
 
# File 'lib/money/money.rb', line 229

def abs
  Money.new(value.abs, currency)
end

#allocate(splits, strategy = :roundrobin) ⇒ Object

See Also:



249
250
251
 
# File 'lib/money/money.rb', line 249

def allocate(splits, strategy = :roundrobin)
  Money::Allocator.new(self).allocate(splits, strategy)
end

#allocate_max_amounts(maximums) ⇒ Object

See Also:



254
255
256
 
# File 'lib/money/money.rb', line 254

def allocate_max_amounts(maximums)
  Money::Allocator.new(self).allocate_max_amounts(maximums)
end

#as_json(*args) ⇒ Object 



225
226
227
 
# File 'lib/money/money.rb', line 225

def as_json(*args)
  to_s
end

#calculate_splits(num) ⇒ Hash<Money, Integer>

Calculate the splits evenly without losing pennies. Returns the number of high and low splits and the value of the high and low splits. Where high represents the Money value with the extra penny and low a Money without the extra penny.

Examples:

Money.new(100, "USD").calculate_splits(3) #=> {Money.new(34) => 1, Money.new(33) => 2}

Parameters:

  • number (2) —

    of parties.

Returns:

Raises:

  • (ArgumentError) 


281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/money/money.rb', line 281

def calculate_splits(num)
  raise ArgumentError, "need at least one party" if num < 1
  subunits = self.subunits
  low = Money.from_subunits(subunits / num, currency)
  high = Money.from_subunits(low.subunits + 1, currency)

  num_high = subunits % num

  {}.tap do |result|
    result[high] = num_high if num_high > 0
    result[low] = num - num_high
  end
end

#cents ⇒ Object 



99
100
101
102
 
# File 'lib/money/money.rb', line 99

def cents
  # Money.deprecate('`money.cents` is deprecated and will be removed in the next major release. Please use `money.subunits` instead. Keep in mind, subunits are currency aware.')
  (value * 100).to_i
end

#clamp(min, max) ⇒ Object

Clamps the value to be within the specified minimum and maximum. Returns self if the value is within bounds, otherwise a new Money object with the closest min or max value.

Examples:

Money.new(50, "CAD").clamp(1, 100) #=> Money.new(50, "CAD")

Money.new(120, "CAD").clamp(0, 100) #=> Money.new(100, "CAD")

Raises:

  • (ArgumentError) 


303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/money/money.rb', line 303

def clamp(min, max)
  raise ArgumentError, 'min cannot be greater than max' if min > max

  clamped_value = min if self.value < min
  clamped_value = max if self.value > max

  if clamped_value.nil?
    self
  else
    Money.new(clamped_value, self.currency)
  end
end

#coerce(other) ⇒ Object

Raises:

  • (TypeError) 


185
186
187
188
 
# File 'lib/money/money.rb', line 185

def coerce(other)
  raise TypeError, "Money can't be coerced into #{other.class}" unless other.is_a?(Numeric)
  [ReverseOperationProxy.new(other), self]
end

#encode_with(coder) ⇒ Object 



94
95
96
97
 
# File 'lib/money/money.rb', line 94

def encode_with(coder)
  coder['value'] = @value.to_s('F')
  coder['currency'] = @currency.iso_code
end

#eql?(other) ⇒ Boolean

TODO: Remove once cross-currency mathematical operations are no longer allowed

Returns:

  • (Boolean) 


155
156
157
158
159
 
# File 'lib/money/money.rb', line 155

def eql?(other)
  return false unless other.is_a?(Money)
  return false unless currency.compatible?(other.currency)
  value == other.value
end

#floor ⇒ Object 



233
234
235
 
# File 'lib/money/money.rb', line 233

def floor
  Money.new(value.floor, currency)
end

#fraction(rate) ⇒ Object

Raises:

  • (ArgumentError) 


241
242
243
244
245
246
 
# File 'lib/money/money.rb', line 241

def fraction(rate)
  raise ArgumentError, "rate should be positive" if rate < 0

  result = value / (1 + rate)
  Money.new(result, currency)
end

#init_with(coder) ⇒ Object 



90
91
92
 
# File 'lib/money/money.rb', line 90

def init_with(coder)
  initialize(Helpers.value_to_decimal(coder['value']), coder['currency'])
end

#inspect ⇒ Object 



146
147
148
 
# File 'lib/money/money.rb', line 146

def inspect
  "#<#{self.class} value:#{self} currency:#{self.currency}>"
end

#no_currency? ⇒ Boolean

Returns:

  • (Boolean) 


108
109
110
 
# File 'lib/money/money.rb', line 108

def no_currency?
  currency.is_a?(NullCurrency)
end

#round(ndigits = 0) ⇒ Object 



237
238
239
 
# File 'lib/money/money.rb', line 237

def round(ndigits=0)
  Money.new(value.round(ndigits), currency)
end

#split(num) ⇒ Array<Money, Money, Money>

Split money amongst parties evenly without losing pennies.

Examples:

Money.new(100, "USD").split(3) #=> [Money.new(34), Money.new(33), Money.new(33)]

Parameters:

  • number (2) —

    of parties.

Returns:



266
267
268
 
# File 'lib/money/money.rb', line 266

def split(num)
  calculate_splits(num).sum([]) { |value, count| Array.new(count, value) }
end

#subunits ⇒ Object 



104
105
106
 
# File 'lib/money/money.rb', line 104

def subunits
  (@value * @currency.subunit_to_unit).to_i
end

#to_d ⇒ Object 



204
205
206
 
# File 'lib/money/money.rb', line 204

def to_d
  value
end

#to_json(options = {}) ⇒ Object 



221
222
223
 
# File 'lib/money/money.rb', line 221

def to_json(options = {})
  to_s
end

#to_liquid ⇒ Object 



217
218
219
 
# File 'lib/money/money.rb', line 217

def to_liquid
  cents
end

#to_money(curr = nil) ⇒ Object 



190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/money/money.rb', line 190

def to_money(curr = nil)
  if !curr.nil? && no_currency?
    return Money.new(value, curr)
  end

  curr = Helpers.value_to_currency(curr)
  unless currency.compatible?(curr)
    Money.deprecate("mathematical operation not permitted for Money objects with different currencies #{curr} and #{currency}. " \
      "A Money::IncompatibleCurrencyError will raise in the next major release")
  end

  self
end

#to_s(style = nil) ⇒ Object 



208
209
210
211
212
213
214
215
 
# File 'lib/money/money.rb', line 208

def to_s(style = nil)
  case style
  when :legacy_dollars
    sprintf("%.2f", value)
  when :amount, nil
    sprintf("%.#{currency.minor_units}f", value)
  end
end