Class: Money

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/money/money.rb,
lib/money/currency.rb,
lib/money/bank/base.rb,
lib/money/bank/variable_exchange.rb

Overview

Represents an amount of money in a given currency.

Defined Under Namespace

Modules: Bank Classes: Currency

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(cents, currency = Money.default_currency, bank = Money.default_bank) ⇒ Money

Creates a new Money object of cents value in cents, with given currency.

Alternatively you can use the convenience methods like ca_dollar and us_dollar.

Examples:

Money.new(100)
#=> #<Money @cents=100 @currency="USD">
Money.new(100, "USD")
#=> #<Money @cents=100 @currency="USD">
Money.new(100, "EUR")
#=> #<Money @cents=100 @currency="EUR">

Parameters:

  • cents (Integer) —

    The money amount, in cents.

  • currency (Currency, String, Symbol) (defaults to: Money.default_currency) —

    The currency format.

  • bank (Money::Bank::*) (defaults to: Money.default_bank) —

    The exchange bank to use.

See Also:



388
389
390
391
392
 
# File 'lib/money/money.rb', line 388

def initialize(cents, currency = Money.default_currency, bank = Money.default_bank)
  @cents = cents.round
  @currency = Currency.wrap(currency)
  @bank = bank
end

Class Attribute Details

.default_bank ⇒ Money::Bank::*

Each Money object is associated to 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 if Bank::VariableExchange. It allows one to specify custom exchange rates.

Returns:



31
32
33
 
# File 'lib/money/money.rb', line 31

def default_bank
  @default_bank
end

.default_currency ⇒ Money::Currency

The default currency, which is used when Money.new is called without an explicit currency argument. The default value is Currency.new(“USD”). The value must be a valid Money::Currency instance.

Returns:



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

def default_currency
  @default_currency
end

Instance Attribute Details

#bank ⇒ Money::Bank::* (readonly)

The Money::Bank based object used to perform currency exchanges with.

Returns:



21
22
23
 
# File 'lib/money/money.rb', line 21

def bank
  @bank
end

#cents ⇒ Integer (readonly)

The value of the money in cents.

Returns:

  • (Integer) 


11
12
13
 
# File 'lib/money/money.rb', line 11

def cents
  @cents
end

#currency ⇒ Currency (readonly)

The currency the money is in.

Returns:



16
17
18
 
# File 'lib/money/money.rb', line 16

def currency
  @currency
end

Class Method Details

.add_rate(from_currency, to_currency, rate) ⇒ Numeric

Adds a new exchange rate to the default bank and return the rate.

Examples:

Money.add_rate("USD", "CAD", 1.25) #=> 1.25

Parameters:

  • from_currency (Currency, String, Symbol) —

    Currency to exchange from.

  • to_currency (Currency, String, Symbol) —

    Currency to exchange to.

  • rate (Numeric) —

    Rate to exchange with.

Returns:



361
362
363
 
# File 'lib/money/money.rb', line 361

def self.add_rate(from_currency, to_currency, rate)
  Money.default_bank.add_rate(from_currency, to_currency, rate)
end

.ca_dollar(cents) ⇒ Money

Creates a new Money object of the given value, using the Canadian dollar currency.

Examples:

n = Money.ca_dollar(100)
n.cents    #=> 100
n.currency #=> #<Money::Currency id: cad>

Parameters:

  • cents (Integer) —

    The cents value.

Returns:



70
71
72
 
# File 'lib/money/money.rb', line 70

def self.ca_dollar(cents)
  Money.new(cents, "CAD")
end

.empty(currency = default_currency) ⇒ Money

Create a new money object with value 0.

Examples:

Money.empty #=> #<Money @cents=0>

Parameters:

  • currency (Currency, String, Symbol) (defaults to: default_currency) —

    The currency to use.

Returns:



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

def self.empty(currency = default_currency)
  Money.new(0, currency)
end

.euro(cents) ⇒ Money

Creates a new Money object of the given value, using the Euro currency.

Examples:

n = Money.euro(100)
n.cents    #=> 100
n.currency #=> #<Money::Currency id: eur>

Parameters:

  • cents (Integer) —

    The cents value.

Returns:



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

def self.euro(cents)
  Money.new(cents, "EUR")
end

.from_bigdecimal(value, currency = Money.default_currency) ⇒ Money

 Converts a BigDecimal into a Money object treating the value as dollars and converting them to the corresponding cents value, according to currency subunit property, before instantiating the Money object.

Examples:

Money.from_bigdecimal(BigDecimal.new("100")
#=> #<Money @cents=10000 @currency="USD">
Money.from_bigdecimal(BigDecimal.new("100", "USD")
#=> #<Money @cents=10000 @currency="USD">
Money.from_bigdecimal(BigDecimal.new("100", "EUR")
#=> #<Money @cents=10000 @currency="EUR">
Money.from_bigdecimal(BigDecimal.new("100", "BHD")
#=> #<Money @cents=100 @currency="BHD">

Parameters:

  • value (BigDecimal) —

    The money amount, in dollars.

  • currency (Currency, String, Symbol) (defaults to: Money.default_currency) —

    The currency format.

Returns:

See Also:



300
301
302
303
304
 
# File 'lib/money/money.rb', line 300

def self.from_bigdecimal(value, currency = Money.default_currency)
  currency = Money::Currency.wrap(currency)
  amount   = value * currency.subunit_to_unit
  Money.new(amount.fix, currency)
end

.from_fixnum(value, currency = Money.default_currency) ⇒ Money

 Converts a Fixnum into a Money object treating the value as dollars and converting them to the corresponding cents value, according to currency subunit property, before instantiating the Money object.

Examples:

Money.from_fixnum(100)
#=> #<Money @cents=10000 @currency="USD">
Money.from_fixnum(100, "USD")
#=> #<Money @cents=10000 @currency="USD">
Money.from_fixnum(100, "EUR")
#=> #<Money @cents=10000 @currency="EUR">
Money.from_fixnum(100, "BHD")
#=> #<Money @cents=100 @currency="BHD">

Parameters:

  • value (Fixnum) —

    The money amount, in dollars.

  • currency (Currency, String, Symbol) (defaults to: Money.default_currency) —

    The currency format.

Returns:

See Also:



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

def self.from_fixnum(value, currency = Money.default_currency)
  currency = Money::Currency.wrap(currency)
  amount   = value * currency.subunit_to_unit
  Money.new(amount, currency)
end

.from_float(value, currency = Money.default_currency) ⇒ Money

 Converts a Float into a Money object treating the value as dollars and converting them to the corresponding cents value, according to currency subunit property, before instantiating the Money object.

Behind the scenes, this method relies on Money.from_bigdecimal to avoid problems with floating point precision.

Examples:

Money.from_float(100.0)
#=> #<Money @cents=10000 @currency="USD">
Money.from_float(100.0, "USD")
#=> #<Money @cents=10000 @currency="USD">
Money.from_float(100.0, "EUR")
#=> #<Money @cents=10000 @currency="EUR">
Money.from_float(100.0, "BHD")
#=> #<Money @cents=100 @currency="BHD">

Parameters:

  • value (Float) —

    The money amount, in dollars.

  • currency (Currency, String, Symbol) (defaults to: Money.default_currency) —

    The currency format.

Returns:

See Also:



273
274
275
 
# File 'lib/money/money.rb', line 273

def self.from_float(value, currency = Money.default_currency)
  from_bigdecimal(BigDecimal.new(value.to_s), currency)
end

.from_numeric(value, currency = Money.default_currency) ⇒ Money

 Converts a Numeric value into a Money object treating the value as dollars and converting them to the corresponding cents value, according to currency subunit property, before instantiating the Money object.

This method relies on various Money.from_* methods and tries to forwards the call to the most appropriate method in order to reduce computation effort. For instance, if value is an Integer, this method calls from_fixnum instead of using the default from_bigdecimal which adds the overload to converts the value into a slower BigDecimal instance.

Examples:

Money.from_numeric(100)
#=> #<Money @cents=10000 @currency="USD">
Money.from_numeric(100.00)
#=> #<Money @cents=10000 @currency="USD">
Money.from_numeric("100")
#=> ArgumentError

Parameters:

  • value (Numeric) —

    The money amount, in dollars.

  • currency (Currency, String, Symbol) (defaults to: Money.default_currency) —

    The currency format.

Returns:

Raises:

  • ArgumentError Unless value is a supported type.

See Also:



339
340
341
342
343
344
345
346
347
348
 
# File 'lib/money/money.rb', line 339

def self.from_numeric(value, currency = Money.default_currency)
  case value
    when Fixnum
      from_fixnum(value, currency)
    when Numeric
      from_bigdecimal(BigDecimal.new(value.to_s), currency)
    else
      raise ArgumentError, "`value' should be a Numeric object"
  end
end

.from_string(value, currency = Money.default_currency) ⇒ Money

 Converts a String into a Money object treating the value as dollars and converting them to the corresponding cents value, according to currency subunit property, before instantiating the Money object.

Behind the scenes, this method relies on from_bigdecimal to avoid problems with string-to-numeric conversion.

Examples:

Money.from_string("100")
#=> #<Money @cents=10000 @currency="USD">
Money.from_string("100", "USD")
#=> #<Money @cents=10000 @currency="USD">
Money.from_string("100", "EUR")
#=> #<Money @cents=10000 @currency="EUR">
Money.from_string("100", "BHD")
#=> #<Money @cents=100 @currency="BHD">

Parameters:

  • value (String, #to_s) —

    The money amount, in dollars.

  • currency (Currency, String, Symbol) (defaults to: Money.default_currency) —

    The currency to set the resulting Money object to.

Returns:

See Also:



214
215
216
 
# File 'lib/money/money.rb', line 214

def self.from_string(value, currency = Money.default_currency)
  from_bigdecimal(BigDecimal.new(value.to_s), currency)
end

.new_with_dollars(amount, currency = Money.default_currency, bank = Money.default_bank) ⇒ Money

Creates a new Money object of amount value in dollars, with given currency.

The amount value is expressed in dollars where the dollar is the main monetary unit, opposite to the subunit-based representation used internally by this library called cents.

Examples:

Money.new_with_dollars(100)
#=> #<Money @cents=10000 @currency="USD">
Money.new_with_dollars(100, "USD")
#=> #<Money @cents=10000 @currency="USD">
Money.new_with_dollars(100, "EUR")
#=> #<Money @cents=10000 @currency="EUR">

Parameters:

  • amount (Numeric) —

    The money amount, in dollars.

  • currency (Currency, String, Symbol) (defaults to: Money.default_currency) —

    The currency format.

  • bank (Money::Bank::*) (defaults to: Money.default_bank) —

    The exchange bank to use.

Returns:

See Also:

  • new


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

def self.new_with_dollars(amount, currency = Money.default_currency, bank = Money.default_bank)
  money = from_numeric(amount, currency)
  # Hack! You can't change a bank
  money.instance_variable_set("@bank", bank)
  money
end

.parse(input, currency = nil) ⇒ Money

Parses the current string and converts it to a Money object. Excess characters will be discarded.

Examples:

'100'.to_money                #=> #<Money @cents=10000>
'100.37'.to_money             #=> #<Money @cents=10037>
'100 USD'.to_money            #=> #<Money @cents=10000, @currency=#<Money::Currency id: usd>>
'USD 100'.to_money            #=> #<Money @cents=10000, @currency=#<Money::Currency id: usd>>
'$100 USD'.to_money           #=> #<Money @cents=10000, @currency=#<Money::Currency id: usd>>
'hello 2000 world'.to_money   #=> #<Money @cents=200000 @currency=#<Money::Currency id: usd>>

Mismatching currencies

'USD 2000'.to_money("EUR")    #=> ArgumentError

Parameters:

  • input (String, #to_s) —

    The input to parse.

  • currency (Currency, String, Symbol) (defaults to: nil) —

    The currency format. The currency to set the resulting Money object to.

Returns:

Raises:

  • (ArgumentError) —

    If any currency is supplied and given value doesn’t match the one extracted from the input string.

See Also:



162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/money/money.rb', line 162

def self.parse(input, currency = nil)
  i = input.to_s

  # Get the currency.
  m = i.scan /([A-Z]{2,3})/
  c = m[0] ? m[0][0] : nil

  # check that currency passed and embedded currency are the same,
  # and negotiate the final currency
  if currency.nil? and c.nil?
    currency = Money.default_currency
  elsif currency.nil?
    currency = c
  elsif c.nil?
    currency = currency
  elsif currency != c
    # TODO: ParseError
    raise ArgumentError, "Mismatching Currencies"
  end
  currency = Money::Currency.wrap(currency)

  cents = extract_cents(i, currency)
  Money.new(cents, currency)
end

.us_dollar(cents) ⇒ Money

Creates a new Money object of the given value, using the American dollar currency.

Examples:

n = Money.us_dollar(100)
n.cents    #=> 100
n.currency #=> #<Money::Currency id: usd>

Parameters:

  • cents (Integer) —

    The cents value.

Returns:



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

def self.us_dollar(cents)
  Money.new(cents, "USD")
end

Instance Method Details

#%(val) ⇒ Money

Synonym for #modulo.

Parameters:

  • val (Money, Fixnum) —

    Number take modulo with.

Returns:

See Also:



648
649
650
 
# File 'lib/money/money.rb', line 648

def %(val)
  self.modulo(val)
end

#*(value) ⇒ 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.

Examples:

Money.new(100) * 2 #=> #<Money @cents=200>

Parameters:

  • value (Numeric) —

    Number to multiply by.

Returns:

  • (Money) —

    The resulting money.

Raises:

  • (ArgumentError) —

    If value is a Money instance.



559
560
561
562
563
564
565
 
# File 'lib/money/money.rb', line 559

def *(value)
  if value.is_a?(Money)
    raise ArgumentError, "Can't multiply a Money by a Money"
  else
    Money.new(cents * value, currency)
  end
end

#+(other_money) ⇒ Money

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.

Examples:

Money.new(100) + Money.new(100) #=> #<Money @cents=200>

Parameters:

  • other_money (Money) —

    Other Money object to add.

Returns:



518
519
520
521
522
523
524
 
# File 'lib/money/money.rb', line 518

def +(other_money)
  if currency == other_money.currency
    Money.new(cents + other_money.cents, other_money.currency)
  else
    Money.new(cents + other_money.exchange_to(currency).cents, currency)
  end
end

#-(other_money) ⇒ 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.

Examples:

Money.new(100) - Money.new(99) #=> #<Money @cents=1>

Parameters:

  • other_money (Money) —

    Other Money object to subtract.

Returns:



537
538
539
540
541
542
543
 
# File 'lib/money/money.rb', line 537

def -(other_money)
  if currency == other_money.currency
    Money.new(cents - other_money.cents, other_money.currency)
  else
    Money.new(cents - other_money.exchange_to(currency).cents, currency)
  end
end

#/(value) ⇒ Money, Float

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.

Examples:

Money.new(100) / 10            #=> #<Money @cents=10>
Money.new(100) / Money.new(10) #=> 10.0

Parameters:

Returns:

  • (Money) —

    The resulting money if you divide Money by a number.

  • (Float) —

    The resulting number if you divide Money by a Money.



582
583
584
585
586
587
588
589
590
591
592
 
# File 'lib/money/money.rb', line 582

def /(value)
  if value.is_a?(Money)
    if currency == value.currency
      (cents / BigDecimal.new(value.cents.to_s)).to_f
    else
      (cents / BigDecimal(value.exchange_to(currency).cents.to_s)).to_f
    end
  else
    Money.new(cents / value, currency)
  end
end

#<=>(other_money) ⇒ -1, ...

Compares this money object against another object. other_money must respond to #to_money. Returns -1 when less than, 0 when equal and 1 when greater than.

If other_money is a different currency, then other_money will first be converted into this money object’s currency by calling #exchange on other_money.

Comparisons against objects that do not respond to #to_money will cause an ArgumentError to be raised.

Examples:

Money.new(100) <=> 99             #=>  1
Money.new(100) <=> Money.new(100) #=>  0
Money.new(100) <=> "$101.00"      #=> -1

Parameters:

Returns:

  • (-1, 0, 1)

Raises:

  • (ArgumentError) 


495
496
497
498
499
500
501
502
503
504
505
506
 
# File 'lib/money/money.rb', line 495

def <=>(other_money)
  if other_money.respond_to?(:to_money)
    other_money = other_money.to_money
    if self.currency == other_money.currency
      cents <=> other_money.cents
    else
      cents <=> other_money.exchange_to(currency).cents
    end
  else
    raise ArgumentError, "Comparison of #{self.class} with #{other_money.inspect} failed"
  end
end

#==(other_money) ⇒ Boolean

Checks whether two money objects have the same currency and the same amount. Checks against money objects with a different currency and checks against objects that do not respond to #to_money will always return false.

Examples:

Money.new(100) == Money.new(101) #=> false
Money.new(100) == Money.new(100) #=> true

Parameters:

  • other_money (Money) —

    Value to compare with.

Returns:

  • (Boolean) 


443
444
445
446
447
448
449
450
 
# File 'lib/money/money.rb', line 443

def ==(other_money)
  if other_money.respond_to?(:to_money)
    other_money = other_money.to_money
    cents == other_money.cents && self.currency == other_money.currency
  else
    false
  end
end

#abs ⇒ Money

Return absolute value of self as a new Money object.

Examples:

Money.new(-100).abs #=> #<Money @cents=100>

Returns:



678
679
680
 
# File 'lib/money/money.rb', line 678

def abs
  Money.new(self.cents.abs, self.currency)
end

#as_ca_dollar ⇒ Money

Receive a money object with the same amount as the current Money object in canadian dollar.

Examples:

n = Money.new(100, "USD").as_ca_dollar
n.currency #=> #<Money::Currency id: cad>

Returns:



957
958
959
 
# File 'lib/money/money.rb', line 957

def as_ca_dollar
  exchange_to("CAD")
end

#as_euro ⇒ Money

Receive a money object with the same amount as the current Money object in euro.

Examples:

n = Money.new(100, "USD").as_euro
n.currency #=> #<Money::Currency id: eur>

Returns:



969
970
971
 
# File 'lib/money/money.rb', line 969

def as_euro
  exchange_to("EUR")
end

#as_us_dollar ⇒ Money

Receive a money object with the same amount as the current Money object in american dollars.

Examples:

n = Money.new(100, "CAD").as_us_dollar
n.currency #=> #<Money::Currency id: usd>

Returns:



945
946
947
 
# File 'lib/money/money.rb', line 945

def as_us_dollar
  exchange_to("USD")
end

#currency_as_string ⇒ String

Return string representation of currency object

Examples:

Money.new(100, :USD).currency_as_string #=> "USD"

Returns:



416
417
418
 
# File 'lib/money/money.rb', line 416

def currency_as_string
  self.currency.to_s
end

#currency_as_string=(val) ⇒ Money::Currency

Set currency object using a string

Examples:

Money.new(100).currency_as_string("CAD") #=> #<Money::Currency id: cad>

Parameters:

  • val (String) —

    The currency string.

Returns:



428
429
430
 
# File 'lib/money/money.rb', line 428

def currency_as_string=(val)
  @currency = Currency.wrap(val)
end

#delimiter ⇒ Object 



724
725
726
 
# File 'lib/money/money.rb', line 724

def delimiter
  I18n.t(:"number.format.delimiter", :default => currency.delimiter || ",")
end

#div(value) ⇒ Money, Float

Synonym for #/.

Parameters:

Returns:

  • (Money) —

    The resulting money if you divide Money by a number.

  • (Float) —

    The resulting number if you divide Money by a Money.

See Also:



603
604
605
 
# File 'lib/money/money.rb', line 603

def div(value)
  self / value
end

#divmod(val) ⇒ Array<Money,Money>, Array<Fixnum,Money>

Divide money by money or fixnum and return array containing quotient and modulus.

Examples:

Money.new(100).divmod(9)            #=> [#<Money @cents=11>, #<Money @cents=1>]
Money.new(100).divmod(Money.new(9)) #=> [11, #<Money @cents=1>]

Parameters:

  • val (Money, Fixnum) —

    Number to divmod by.

Returns:



617
618
619
620
621
622
623
624
625
626
 
# File 'lib/money/money.rb', line 617

def divmod(val)
  if val.is_a?(Money)
    a = self.cents
    b = self.currency == val.currency ? val.cents : val.exchange_to(self.currency).cents
    q, m = a.divmod(b)
    return [q, Money.new(m, self.currency)]
  else
    return [self.div(val), Money.new(self.cents.modulo(val), self.currency)]
  end
end

#dollars ⇒ Float

Returns the value of the money in dollars, instead of in cents.

Examples:

Money.new(100).dollars           # => 1.0
Money.new_with_dollars(1).dollar # => 1.0

Returns:

  • (Float)

See Also:



406
407
408
 
# File 'lib/money/money.rb', line 406

def dollars
  to_f
end

#eql?(other_money) ⇒ Money

Synonymous with #==.

Parameters:

  • other_money (Money) —

    Value to compare with.

Returns:

See Also:



459
460
461
 
# File 'lib/money/money.rb', line 459

def eql?(other_money)
  self == other_money
end

#exchange_to(other_currency) ⇒ Money

Receive the amount of this money object in another Currency.

Examples:

Money.new(2000, "USD").exchange_to("EUR")
Money.new(2000, "USD").exchange_to(Currency.new("EUR"))

Parameters:

  • other_currency (Currency, String, Symbol) —

    Currency to exchange to.

Returns:



932
933
934
935
 
# File 'lib/money/money.rb', line 932

def exchange_to(other_currency)
  other_currency = Currency.wrap(other_currency)
  @bank.exchange_with(self, other_currency)
end

#format(*rules) ⇒ String

Creates a formatted price string according to several rules.

Examples:

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"
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"
Money.ca_dollar(100).format(:no_cents => true) #=> "$1"
Money.ca_dollar(599).format(:no_cents => true) #=> "$5"
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"
# If a string is specified, it's value is used.
Money.new(100, "USD").format(:separator => ",") #=> "$1,00"

# If the separator for a given currency isn't known, then it will default
# to "." as separator.
Money.new(100, "FOO").format #=> "$1.00"
# If false is specified, no delimiter is used.
Money.new(100000, "USD").format(:delimiter => false) #=> "1000.00"
Money.new(100000, "USD").format(:delimiter => nil)   #=> "1000.00"
Money.new(100000, "USD").format(:delimiter => "")    #=> "1000.00"

# If a string is specified, it's value is used.
Money.new(100000, "USD").format(:delimiter => ".") #=> "$1.000.00"

# If the delimiter for a given currency isn't known, then it will default
# to "," as delimiter.
Money.new(100000, "FOO").format #=> "$1,000.00"
s = Money.ca_dollar(570).format(:html => true, :with_currency => true)
s #=>  "$5.70 <span class=\"currency\">CAD</span>"

Parameters:

  • *rules (Hash) —

    The options used to format the string.

Returns:



839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
 
# File 'lib/money/money.rb', line 839

def format(*rules)
  # support for old format parameters
  rules = normalize_formatting_rules(rules)

  if cents == 0
    if rules[:display_free].respond_to?(:to_str)
      return rules[:display_free]
    elsif rules[:display_free]
      return "free"
    end
  end

  if rules.has_key?(:symbol)
    if rules[:symbol] === true
      symbol_value = symbol
    elsif rules[:symbol]
      symbol_value = rules[:symbol]
    else
      symbol_value = ""
    end
  else
    symbol_value = symbol
  end

  formatted = case rules[:no_cents]
              when true
                "#{symbol_value}#{self.to_s.to_i}"
              else
                "#{symbol_value}#{self.to_s}"
              end
  if rules.has_key?(:separator) and rules[:separator] and
    rules[:separator] != separator
    formatted.sub!(separator, rules[:separator])
  end

  delimiter_value = delimiter
  # Determine delimiter
  if rules.has_key?(:delimiter)
    if rules[:delimiter] === false or rules[:delimiter].nil?
      delimiter_value = ""
    elsif rules[:delimiter]
      delimiter_value = rules[:delimiter]
    end
  end

  # Apply delimiter
  formatted.gsub!(/(\d)(?=(?:\d{3})+(?:\.|,|$))(\d{3}\..*)?/, "\\1#{delimiter_value}\\2")

  if rules[:with_currency]
    formatted << " "
    formatted << '<span class="currency">' if rules[:html]
    formatted << currency.to_s
    formatted << '</span>' if rules[:html]
  end
  formatted
end

#hash ⇒ Fixnum

Returns a Fixnum hash value based on the cents and currency attributes in order to use functions like & (intersection), group_by, etc.

Examples:

Money.new(100).hash #=> 908351

Returns:

  • (Fixnum) 


470
471
472
 
# File 'lib/money/money.rb', line 470

def hash
  [cents.hash, currency.hash].hash
end

#modulo(val) ⇒ Money

Equivalent to self.divmod(val)

Examples:

Money.new(100).modulo(9)            #=> #<Money @cents=1>
Money.new(100).modulo(Money.new(9)) #=> #<Money @cents=1>

Parameters:

  • val (Money, Fixnum) —

    Number take modulo with.

Returns:



637
638
639
 
# File 'lib/money/money.rb', line 637

def modulo(val)
  self.divmod(val)[1]
end

#nonzero? ⇒ Money?

Test if the money amount is non-zero. Returns this money object if it is non-zero, or nil otherwise, like Numeric#nonzero?.

Examples:

Money.new(100).nonzero? #=> #<Money @cents=100>
Money.new(0).nonzero?   #=> nil

Returns:



701
702
703
 
# File 'lib/money/money.rb', line 701

def nonzero?
  cents != 0 ? self : nil
end

#remainder(val) ⇒ Money

If different signs self.modulo(val) - val otherwise self.modulo(val)

Examples:

Money.new(100).remainder(9) #=> #<Money @cents=1>

Parameters:

  • val (Money, Fixnum) —

    Number to rake remainder with.

Returns:



660
661
662
663
664
665
666
667
668
669
670
 
# File 'lib/money/money.rb', line 660

def remainder(val)
  a, b = self, val
  b = b.exchange_to(a.currency) if b.is_a?(Money) and a.currency != b.currency

  a_sign, b_sign = :pos, :pos
  a_sign = :neg if a.cents < 0
  b_sign = :neg if (b.is_a?(Money) and b.cents < 0) or (b < 0)

  return a.modulo(b) if a_sign == b_sign
  a.modulo(b) - (b.is_a?(Money) ? b : Money.new(b, a.currency))
end

#separator ⇒ Object 



742
743
744
 
# File 'lib/money/money.rb', line 742

def separator
  I18n.t(:"number.format.separator", :default => currency.separator || ".")
end

#symbol ⇒ String

Uses Currency#symbol. If nil is returned, defaults to “¤”.

Examples:

Money.new(100, "USD").symbol #=> "$"

Returns:



711
712
713
 
# File 'lib/money/money.rb', line 711

def symbol
  currency.symbol || "¤"
end

#to_f ⇒ Float

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 decimals.

Examples:

Money.us_dollar(100).to_f => 1.0

Returns:

  • (Float) 


919
920
921
 
# File 'lib/money/money.rb', line 919

def to_f
  (BigDecimal.new(cents.to_s) / currency.subunit_to_unit).to_f
end

#to_money ⇒ self

Conversation to self.

Returns:

  • (self) 


976
977
978
 
# File 'lib/money/money.rb', line 976

def to_money
  self
end

#to_s ⇒ String

Returns the amount of money as a string.

Examples:

Money.ca_dollar(100).to_s #=> "1.00"

Returns:



902
903
904
905
906
907
908
 
# File 'lib/money/money.rb', line 902

def to_s
  decimal_places = Math.log10(currency.subunit_to_unit).ceil
  unit, subunit  = cents.divmod(currency.subunit_to_unit).map{|o| o.to_s}
  return unit if decimal_places == 0
  subunit = (subunit + ("0" * decimal_places))[0, decimal_places]
  "#{unit}#{separator}#{subunit}"
end

#zero? ⇒ Boolean

Test if the money amount is zero.

Examples:

Money.new(100).zero? #=> false
Money.new(0).zero?   #=> true

Returns:

  • (Boolean) 


689
690
691
 
# File 'lib/money/money.rb', line 689

def zero?
  cents == 0
end