latinum 0.5.6 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b5a04f37290c238dda1763d8a9df4a0a858def89
-  data.tar.gz: 3afb2e8848f66d1ac4807808ab7981fea0ae4ac0
+  metadata.gz: c4a1959c3b1c833751fdc2536ce1db9c040e48be
+  data.tar.gz: a870124602130bfcfc036ba61abdbcc529af9645
 SHA512:
-  metadata.gz: 7fb26870f5d89b03ebb5f06870fda36f8db2d05d76e9ff9f9ca535ba661d0f11824b3797bf60e3c0102e7fe1e0ef8ed5363c08e76761dbbeaf159aed54e9dadf
-  data.tar.gz: 0af553ebbef75f2fe4faa3efc70a7e68ebf9a7916548e3cc6ce7f3c5cfae2da23db96323a5f7d84c3a6942b73d59919083afc09b7fbab43fd65d08c60494d5da
+  metadata.gz: 85efa5c7e88b2a0e5b41f039054daae59f55848060d24f9d6d0d8a88e406391a77309febdf727c10db505e4bd2de76e656de1e6e996eed485c3f396fdcc72027
+  data.tar.gz: c620f6a689945b472cee3290a01f89c4fef33d192c6600fbe5f14346b0071b92c46cb0c5d865b38ffce630d2f4b38825edbca8c9a098692f565c6d50c3a3f496

data/README.md

@@ -9,15 +9,15 @@ Latinum is a library for resource and currency calculations. It provides immutab
 
 Add this line to your application's Gemfile:
 
-    gem 'latinum'
+	gem 'latinum'
 
 And then execute:
 
-    $ bundle
+	$ bundle
 
 Or install it yourself as:
 
-    $ gem install latinum
+	$ gem install latinum
 
 ## Usage
 
@@ -58,6 +58,64 @@ To add multiple currencies together, use a collection:
 	> currencies.collect {|currency| collection[currency]}
 	=> [10.0 NZD, 20.0 AUD]
 
+#### Calculating Totals
+
+The `Latinum::Collection` is the correct way to sum up a list of transactions or other items with an
+associated `Latinum::Resource`. Here is an example:
+
+	<table class="listing transactions" data-model="Transaction">
+		<thead>
+			<tr>
+				<th class="name">Name</th>
+				<th class="date">Date</th>
+				<th class="price">Price</th>
+				<th class="quantity">Quantity</th>
+				<th class="subtotal">Sub-total</th>
+				<th class="tax_rate">Tax</th>
+				<th class="total">Total</th>
+			</tr>
+		</thead>
+		<tbody>
+			<?r 
+				currencies = Set.new
+				
+				summary = {
+					:subtotal => Latinum::Collection.new(currencies),
+					:tax => Latinum::Collection.new(currencies),
+					:total => Latinum::Collection.new(currencies)
+				}
+				
+				invoice.transactions.each do |transaction|
+					subtotal = transaction.subtotal
+					summary[:subtotal] << subtotal
+					summary[:tax] << subtotal * transaction.tax_rate.to_d
+					summary[:total] << transaction.total
+				
+			?>
+			<tr data-id="#{transaction.id}" data-rev="#{transaction.rev}">
+				<th class="name">#{f.text transaction.name}</th>
+				<td class="date">#{f.text transaction.date}</td>
+				<td class="price">#{f.text transaction.price}</td>
+				<td class="quantity">#{f.quantity transaction}</td>
+				<td class="subtotal">#{f.text subtotal}</td>
+				<td class="tax_rate">#{f.tax transaction}</td>
+				<td class="total">#{f.text transaction.total}</td>
+			</tr>
+			<?r end ?>
+		</tbody>
+		<tfoot>
+			<?r currencies.each do |currency| ?>
+			<tr>
+				<td colspan="5">#{currency} Summary:</td>
+				<td class="subtotal">#{f.text summary[:subtotal][currency]}</td>
+				<td class="tax_rate">#{f.text summary[:tax][currency]}</td>
+				<td class="total">#{f.text summary[:total][currency]}</td>
+				<td></td>
+			</tr>
+			<?r end ?>
+		</tfoot>
+	</table>
+
 ### Banks and Exchange Rates
 
 The bank is responsible for formatting and exchange rates:
@@ -108,6 +166,73 @@ For storage in traditional databases, you may prefer to use integers. Based on t
 
 As BitCoin has 8 decimal places, it requires an integer representation with at least 10^8.
 
+### ActiveRecord Serialization
+
+Latinum can be easily used in a [ActiveRecord](https://github.com/rails/rails/tree/master/activerecord) model simply by declaring a serialized data-type for a string or text column, e.g.
+
+	class Transaction < ActiveRecord::Base
+		serialize :total, Latinum::Resource
+	end
+
+It can be used like so:
+
+	> transaction = Transaction.new(:total => "10 NZD")
+	> transaction.total * 2
+	=> "20.0 NZD"
+
+To format the output, use a `Latinum::Bank`, e.g. assuming the bank is set up correctly:
+
+	> bank.format(transaction.total)
+	=> "$20.00 NZD"
+	
+	> bank.format(transaction.total, name: nil)
+	=> "$20.00"
+	
+	> bank.format(transaction.total, symbol: nil)
+	=> "20.00 NZD"
+
+### Relaxo Serialization
+
+Latinum is natively supported by [Relaxo](https://github.com/ioquatix/relaxo) (CouchDB) and as such can be used in [Relaxo models](https://github.com/ioquatix/relaxo-model) easily.
+
+	require 'latinum'
+	require 'relaxo/model'
+	require 'relaxo/model/properties/latinum'
+	
+	class Transaction
+		include Relaxo::Model
+
+		property :name
+		property :price, Attribute[Latinum::Resource]
+	end
+	
+	db = Relaxo.connect('test')
+	db.create!
+	
+	t = Transaction.create(db, price: Latinum::Resource.load("50 NZD"))
+	
+	t.price
+	# => <Latinum::Resource "50.0 NZD">
+	
+	# Save and reload from database server:
+	t.save
+	t = Transaction.fetch(db, t.id)
+	
+	t.price
+	# => <Latinum::Resource "50.0 NZD">
+
+It gets stored in the database like so:
+
+	{
+		"_id": "740f4728fc9a571d826688db2f004771",
+		"_rev": "1-45a29c63311cfa0d5a765707184b2b3b",
+		"type": "transaction",
+		"price": [
+			"50.0",
+			"NZD"
+		]
+	}
+
 ## Contributing
 
 1. Fork it

data/lib/latinum/bank.rb

@@ -115,6 +115,13 @@ module Latinum
 			end
 		end
 		
+		def round(resource)
+			formatter = @formatters[resource.name]
+			raise ArgumentError.new("No formatter found for #{resource.name}") unless formatter
+			
+			Latinum::Resource.new(formatter.round(resource.amount), resource.name)
+		end
+		
 		# Format a resource as a string according to the loaded currencies.
 		def format(resource, *args)
 			formatter = @formatters[resource.name]

data/lib/latinum/formatters.rb

@@ -53,6 +53,10 @@ module Latinum
 				@name = options[:name]
 			end
 
+			def round(amount)
+				return amount.round(@places)
+			end
+
 			def format(amount, options = DEFAULT_OPTIONS)
 				# Round to the desired number of places. Truncation used to be the default.
 				amount = amount.round(@places)

data/lib/latinum/version.rb

@@ -19,5 +19,5 @@
 # THE SOFTWARE.
 
 module Latinum
-	VERSION = "0.5.6"
+	VERSION = "0.6.0"
 end

data/spec/latinum/bank_spec.rb

@@ -48,6 +48,18 @@ module Latinum::BankSpec
 			expect(@bank.format(resource)).to be == "B⃦1.12345678 BTC"
 		end
 		
+		it "should round up using correct precision" do
+			resource = Latinum::Resource.new("19.9989", "NZD")
+			
+			expect(@bank.round(resource)).to be == Latinum::Resource.new(20, "NZD")
+		end
+		
+		it "should round down using correct precision" do
+			resource = Latinum::Resource.new("19.991", "NZD")
+			
+			expect(@bank.round(resource)).to be == Latinum::Resource.new("19.99", "NZD")
+		end
+		
 		it "should round values when formatting" do
 			resource = Latinum::Resource.new("19.9989", "NZD")
 			

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: latinum
 version: !ruby/object:Gem::Version
-  version: 0.5.6
+  version: 0.6.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-08-19 00:00:00.000000000 Z
+date: 2015-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler