Class: BigMoney

Inherits:
Object
  • Object
show all
Extended by:
Parser
Includes:
Exchangeable, Comparable
Defined in:
lib/big_money.rb,
lib/big_money/parser.rb,
lib/big_money/currency.rb,
lib/big_money/exchange.rb,
lib/big_money/exchange/yahoo.rb,
lib/big_money/currency/iso4217.rb

Overview

Synopsis

bm = BigMoney.new('3.99', :aud)
bm.amount           #=> BigDecimal.new('3.99')
bm.currency         #=> BigMoney::Currency::AUD
bm.to_s             #=> '3.99'
bm.to_s('$.2f')     #=> '$3.99'
bm.to_s('$%.2f %s') #=> '$3.99 AUD'

Amount

Amounts can be anything Numeric or Strings that are BigDecimal friendly. Keep in mind BigDecimal will silently return 0.0 for unrecognised strings. See BigMoney::Amount.

BigMoney.new(BigDecimal.new('12.50')) # BigDecimal
BigMoney.new(12)                      # Fixnum
BigMoney.new(12.50)                   # Float
BigMoney.new('12.50')                 # String

Currency

Any currency defined by the current ISO4217 table on Wikipedia is already available. Naturally you may define your own currencies. See BigMoney::Currency.

Default

A default currency risks exchanging an amount 1:1 between currencies if the default is unintentionally used. BigMoney expects an explicit currency in the constructor and will raise an ArugmentError unless one is given or a default currency set.

BigMoney::Currency.default = BigMoney::Currency::AUD # Module
BigMoney::Currency.default = 'AUD'                   # String, ISO4217 3 letter currency code.
BigMoney::Currency.default = :aud                    # Symbol, ISO4217 3 letter currency code.

Defined Under Namespace

Modules: Exchangeable, Parser Classes: Currency, Exchange

Constant Summary

Constants included from Parser

Parser::REGEXP

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Parser

parse

Methods included from Exchangeable

#exchange

Constructor Details

#initialize(amount, currency = nil) ⇒ BigMoney

Create a BigMoney instance.

Parameters

amount<BigDecimal, Numeric, String>

Numeric or BigDecimal friendly String.

currency<BigMoney::Currency, Symbol, String>

Optional ISO-4217 3 letter currency code. Default BigMoney.currency.default

Returns

BigMoney

Raises:

  • (ArgumentError) 


66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/big_money.rb', line 66

def initialize(amount, currency = nil)
  @amount = case amount
    when BigDecimal then amount
    when String     then BigDecimal.new(amount)
    when Numeric    then BigDecimal.new(amount.to_s)
    else raise TypeError.new("Can't convert +amount+ #{amount.class} into BigDecimal.")
  end

  raise ArgumentError.new("Nil +currency+ without default.") if currency.nil? && !Currency.default?
  unless currency && @currency = Currency.find(currency)
    raise ArgumentError.new("Unknown +currency+ '#{currency.inspect}'.") unless Currency.default?
    @currency = Currency.default
  end
end

Instance Attribute Details

#amount ⇒ Object (readonly)

Returns the value of attribute amount.



41
42
43
 
# File 'lib/big_money.rb', line 41

def amount
  @amount
end

#currency ⇒ Object (readonly)

Returns the value of attribute currency.



41
42
43
 
# File 'lib/big_money.rb', line 41

def currency
  @currency
end

Class Method Details

.currency(currency) ⇒ Object

Short form BigMoney::Currency.find(code) to save some typing.

Examples

BigMoney.currency(:usd) #=> BigMoney::Currency.find(:usd)

Parameters

code<#to_s>

An upper or lowercase string or symbol of the ISO-4217 currency code.

Returns

BigMoney::Currency



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

def self.currency(currency)
  Currency.find(currency)
end

Instance Method Details

#-@ ⇒ Object 



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

def -@
  self.class.new(-amount, currency)
end

#<=>(money) ⇒ Object 



97
98
99
 
# File 'lib/big_money.rb', line 97

def <=>(money)
  money.kind_of?(self.class) ? (currency <=> money.currency).nonzero? || (amount <=> money.amount).nonzero? || 0 : nil
end

#eql?(money) ⇒ Boolean Also known as: ==

Returns:

  • (Boolean) 


101
102
103
104
105
 
# File 'lib/big_money.rb', line 101

def eql?(money)
  money.kind_of?(self.class) &&
  amount == money.amount &&
  currency == money.currency
end

#negative? ⇒ Boolean

Returns:

  • (Boolean) 


93
94
95
 
# File 'lib/big_money.rb', line 93

def negative?
  self < self.class.new(0, self.currency)
end

#nonzero? ⇒ Boolean

Returns:

  • (Boolean) 


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

def nonzero?
  amount.nonzero? && self
end

#positive? ⇒ Boolean

Returns:

  • (Boolean) 


89
90
91
 
# File 'lib/big_money.rb', line 89

def positive?
  self > self.class.new(0, self.currency)
end

#to_f ⇒ Object 



137
138
139
 
# File 'lib/big_money.rb', line 137

def to_f
  amount.to_f
end

#to_i ⇒ Object 



133
134
135
 
# File 'lib/big_money.rb', line 133

def to_i
  amount.to_i
end

#to_s(format = nil) ⇒ Object 



128
129
130
131
 
# File 'lib/big_money.rb', line 128

def to_s(format = nil)
  format ||= "%.#{currency.offset}f"
  format.sub(/%s/, currency.code) % amount
end

#zero? ⇒ Boolean

Returns:

  • (Boolean) 


81
82
83
 
# File 'lib/big_money.rb', line 81

def zero?
  amount.zero?
end