Class: Craigslist::API::Money

Inherits:
Object
  • Object
show all
Defined in:
lib/craigslist/api/money.rb

Overview

A monetary amount as the Bulkpost API reports it: an integer in minor units plus the exponent needed to scale it.

{amount: 100000, currency: "USD", exponent: 2} is $1,000.00.

Conversion goes through Rational rather than Float so the scaling is exact, and deliberately avoids BigDecimal, which stopped being a default gem in Ruby 3.4 and would add a dependency.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(amount:, currency: "USD", exponent: 2) ⇒ Money

Returns a new instance of Money.



23
24
25
26
27
28
 
# File 'lib/craigslist/api/money.rb', line 23

def initialize(amount:, currency: "USD", exponent: 2)
  @amount = amount.to_i
  @currency = currency.to_s
  @exponent = exponent.to_i
  freeze
end

Instance Attribute Details

#amount ⇒ Integer (readonly)

Returns value in minor units.

Returns:

  • (Integer) —

    value in minor units



15
16
17
 
# File 'lib/craigslist/api/money.rb', line 15

def amount
  @amount
end

#currency ⇒ String (readonly)

Returns ISO 4217 currency code.

Returns:

  • (String) —

    ISO 4217 currency code



18
19
20
 
# File 'lib/craigslist/api/money.rb', line 18

def currency
  @currency
end

#exponent ⇒ Integer (readonly)

Returns power of ten separating minor units from major.

Returns:

  • (Integer) —

    power of ten separating minor units from major



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

def exponent
  @exponent
end

Class Method Details

.from(hash) ⇒ Money?

Parameters:

  • hash (Hash, nil) —

    raw {"amount", "currency", "exponent"} payload

Returns:



32
33
34
35
36
37
38
39
40
 
# File 'lib/craigslist/api/money.rb', line 32

def self.from(hash)
  return nil if hash.nil?

  new(
    amount: hash["amount"],
    currency: hash.fetch("currency", "USD"),
    exponent: hash.fetch("exponent", 2)
  )
end

Instance Method Details

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

Returns true when amount, currency and exponent all match.

Parameters:

  • other (Object)

Returns:

  • (Boolean) —

    true when amount, currency and exponent all match



59
60
61
62
63
64
 
# File 'lib/craigslist/api/money.rb', line 59

def ==(other)
  other.is_a?(Money) &&
    amount == other.amount &&
    currency == other.currency &&
    exponent == other.exponent
end

#hash ⇒ Integer

Returns value-based hash, so Money can key a Hash.

Returns:

  • (Integer) —

    value-based hash, so Money can key a Hash



68
69
70
 
# File 'lib/craigslist/api/money.rb', line 68

def hash
  [amount, currency, exponent].hash
end

#inspect ⇒ Object 



72
73
74
 
# File 'lib/craigslist/api/money.rb', line 72

def inspect
  "#<#{self.class.name} #{self}>"
end

#to_f ⇒ Float

Returns value in major units, with the usual float caveats.

Returns:

  • (Float) —

    value in major units, with the usual float caveats



48
49
50
 
# File 'lib/craigslist/api/money.rb', line 48

def to_f
  to_r.to_f
end

#to_r ⇒ Rational

Returns exact value in major units.

Returns:

  • (Rational) —

    exact value in major units



43
44
45
 
# File 'lib/craigslist/api/money.rb', line 43

def to_r
  Rational(amount, 10**exponent)
end

#to_s ⇒ String

Returns e.g. "1000.00 USD".

Returns:

  • (String) —

    e.g. "1000.00 USD"



53
54
55
 
# File 'lib/craigslist/api/money.rb', line 53

def to_s
  "#{format("%.#{exponent}f", to_r)} #{currency}"
end