lare_round 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 34df43a119476abc7ae5444a36b0f0780037132e
+  data.tar.gz: 4080b4c67caaf8defc3f6cac1166cb79e899ed3a
+SHA512:
+  metadata.gz: ad2b381a02883609ffd9bed1a70c398a4e9a80c680c7e7e0def0b8ad752c8c2620bc602753dc38b84db4a0ee450091346d2b36843c8cdc84a9953a9b82c8121e
+  data.tar.gz: 99372d477e87a7ee1150fe1358752bf853215ca77101ac8dfe83d3be60129e396fdd4d4f04997cc919135615e7a2056f4533222aebc4d9cd601c9f781b37f5ad

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,9 @@
+rvm:
+
+  - "1.9.3"
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-19mode
+branches:
+  only:
+    - master
+

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in lare_round.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,24 @@
+Copyright (c) 2013 Carsten Wirth
+
+
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,122 @@
+# LareRound
+
+A collection of BigDecimal items e.g. invoice items can be rounded for displaying them in views. Rounding may apply a rounding error to the items such as the summed up rounded items will show deviation towards an invoice total with summed unrounded items. Which might cause confusion for customers and finance departments alike. Application of the largest remainder method can help to preserve the total sum for rounded parts thus eliminating this confusion.
+
+## Build status
+[![Build Status](https://secure.travis-ci.org/jethroo/lare_round.png)](http://travis-ci.org/jethroo/lare_round)
+
+
+## Used in production
+
+since 4th of september 2013 (still needs to be released as gem)
+
+## Example
+
+say we have an array of 3 invoice items which are stored in the database and your invoice calculations are precise to the 4th position after the decimal point:
+
+```ruby
+Array.new(3){BigDecimal.new('0.3334')}
+#  => [#<BigDecimal:c75a38,'0.3334E0',9(18)>, #<BigDecimal:c759c0,'0.3334E0',9(18)>, #<BigDecimal:c75920,'0.3334E0',9(18)>]
+```
+say you have an invoice which is rendered as pdf which only needs to display the total you are fine, because you only
+have to round once for displaying a customer friendly price:
+
+```ruby
+Array.new(3){BigDecimal.new('0.3334')}.reduce(:+).round(2).to_f
+# => 1.0
+```
+
+But what if you need to dispay each item separately? Each item of the invoice has to be displayed in a customer friendly way.
+
+Item | Price
+ --- | ---
+ item 1 | 0.3334
+ item 2 | 0.3334
+ item 3 | 0.3334
+ **Total** | **1.0002**
+
+
+So the most likely aproach is to simply round each item by itself, so the customer isn't bothered with 34/10000 €-Cents. Simple at it is its not quite what you want:
+
+```ruby
+Array.new(3){BigDecimal.new('0.3334')}.map{|i| i.round(2)}.reduce(:+).to_f
+# => 0.99
+```
+
+Item | Price
+ --- | ---
+ item 1 | 0.33
+ item 2 | 0.33
+ item 3 | 0.33
+ **Total** | **1.00**
+
+Now you have the customer bothering about why there is a difference between the invoice total and the invoice items sum. Which may lead in mistrust ("Hey! These guys can't even do math. I'll keep my money.") or all kinds of related confusions.
+
+This gem helps to distribute the rounding error amongst the items to preserve the total:
+```ruby
+a =  Array.new(3){BigDecimal.new('0.3334')}
+# => [#<BigDecimal:887b6c8,'0.3334E0',9(18)>, #<BigDecimal:887b600,'0.3334E0',9(18)>, #<BigDecimal:887b4c0,'0.3334E0',9(18)>]
+a = LareRound.round(a,2)
+# => [#<BigDecimal:8867330,'0.34E0',9(36)>, #<BigDecimal:8867290,'0.33E0',9(36)>, #<BigDecimal:88671f0,'0.33E0',9(36)>]
+a.reduce(:+).to_f
+# => 1.0
+```
+
+This is accomplish by utilizing the largest remainder method. Which checks for the items with the largest rounding error and increasing them iteratively as long as the sums do not match. Regarding the before mentioned expample each item
+is rounded down to 0.33 and then the algorithm adds 0.01 to one item thus making the sums equal.
+
+Item | Price
+ --- | ---
+ item 1 | 0.34
+ item 2 | 0.33
+ item 3 | 0.33
+ **Total** | **1.00**
+
+LareRound supports *Array* and *Hash* as collection types. As usage of array was shown above here comes the hash example:
+
+```ruby
+hash = Hash[(1..3).map.with_index{|x,i|[x,BigDecimal.new('0.3334')]}]
+# => {1=>#<BigDecimal:26ac7d0,'0.3334E0',9(18)>, 2=>#<BigDecimal:26ac730,'0.3334E0',9(18)>, 3=>#<BigDecimal:26ac690,'0.3334E0',9(18)>}
+LareRound.round(hash,2)
+# => {1=>#<BigDecimal:26b9318,'0.34E0',9(36)>, 2=>#<BigDecimal:26b9250,'0.33E0',9(36)>, 3=>#<BigDecimal:26b91b0,'0.33E0',9(36)>}
+LareRound.round(hash,2).values.reduce(:+).to_f
+#=> 1.0
+```
+
+## Open Issues / Features
+
+  * support specific type of rounding behavior for single items such as always rounding up in the case of taxes
+
+Item (unrounded)| Price (unrounded) | LareRound | Financial
+ --- | --- | --- | ---
+ item | 10.000 | 10.00 | 10.00
+ tax ( 8.23%) | 0.823 | 0.82 | 0.83
+ **Total** | **10.823** | **10.82** | **10.83**
+
+  * release as gem
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'lare_round', :git => "git://github.com/jethroo/lare_round.git"
+
+And then execute:
+
+    $ bundle
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+Hereby released under MIT license.
+
+## Authors/Contributors
+
+- [BlackLane GmbH](http://www.blacklane.com "Blacklane")
+- [Carsten Wirth](http://github.com/jethroo)

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/lare_round.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'lare_round/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "lare_round"
+  spec.version       = LareRound::VERSION
+  spec.authors       = ["Carsten Wirth\n\n"]
+  spec.email         = ["carsten.wirth@blacklane.com\n"]
+  spec.description   = %q{A collection of BigDecimal items e.g. invoice items can be rounded for displaying them in views. Rounding may apply a rounding error to the items such as the summed up rounded items will show deviation towards an invoice total with summed unrounded items. Which might cause confusion for customers and finance departments alike. Application of the largest remainder method can help to preserve the total sum for fractionated parts thus eliminating this confusion.
+  }
+  spec.summary       = %q{gem for rounding BigDecimal items by preserving its sum}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+end

data/lib/lare_round.rb

@@ -0,0 +1,54 @@
+require 'bigdecimal'
+
+module LareRound
+
+  def self.round(values,precision)
+    raise LareRoundError.new("precision must not be nil")                   if precision.nil?
+    raise LareRoundError.new("precision must be a number")                  unless precision.is_a? Numeric
+    raise LareRoundError.new("precision must be greater or equal to 0")     if precision < 0
+    raise LareRoundError.new("values must not be nil")                      if values.nil?
+    raise LareRoundError.new("values must not be empty")                    if values.empty?
+    if values.kind_of?(Array)
+      round_array_of_values(values,precision)
+    elsif values.kind_of?(Hash)
+      rounded_values = round_array_of_values(values.values,precision)
+      values.keys.each_with_index do |key,index|
+        values[key] = rounded_values[index]
+      end
+      return values
+    end
+  end
+
+  # StandardError for dealing with application level errors
+  class LareRoundError < StandardError
+
+  end
+
+  private
+  def self.round_array_of_values(array_of_values,precision)
+    raise LareRoundError.new("array_of_values must be an array")            unless array_of_values.is_a? Array
+    number_of_invalid_values = array_of_values.map{|i| i.is_a? Numeric}.reject{|i| i == true}.size
+    raise LareRoundError.new("values contains not numeric values (#{number_of_invalid_values})") if number_of_invalid_values > 0
+    warn "values contains non decimal values, you might loose precision or even get wrong rounding results" if array_of_values.map{|i| i.is_a? BigDecimal}.reject{|i| i == true}.size > 0
+
+    #prevention of can't omit precision for a Rational
+    decimal_shift = BigDecimal.new (10 ** precision.to_i)
+    rounded_total = array_of_values.reduce(:+).round(precision) * decimal_shift
+    array_of_values = array_of_values.map{|v| ((v.is_a? BigDecimal) ? v : BigDecimal.new(v.to_s))}
+    unrounded_values = array_of_values.map{|v| v * decimal_shift }
+
+    # items needed to be rounded down if positiv:
+    # 0.7 + 0.7 + 0.7 = ( 2.1 ).round(0) = 2
+    # (0.7).round(0) + (0.7).round(0) + (0.7).round(0) = 1 + 1 + 1 = 3
+    # elsewise if negative
+    rounded_values = array_of_values.map{|v| v < 0 ? v.round(precision, BigDecimal::ROUND_UP) * decimal_shift : v.round(precision, BigDecimal::ROUND_DOWN) * decimal_shift }
+
+    while not rounded_values.reduce(:+) >= rounded_total
+      fractions = unrounded_values.zip(rounded_values).map { |x, y| x - y }
+      rounded_values[fractions.index(fractions.max)] += 1
+    end
+
+    return rounded_values.map{|v| v / decimal_shift }
+  end
+
+end

data/lib/lare_round/version.rb

@@ -0,0 +1,3 @@
+module LareRound
+  VERSION = "0.0.1"
+end

data/test/lare_round_test.rb

@@ -0,0 +1,116 @@
+require_relative 'test_helper'
+require 'bigdecimal'
+require 'securerandom'
+
+class LareRoundTest < MiniTest::Unit::TestCase
+
+  def test_lareRound_has_static_method_round
+    assert_equal(true,LareRound.respond_to?(:round))
+  end
+
+  (1..9).each do |digit|
+    (1..23).each do |items|
+      (0..10).each do |precision|
+
+        method_name = "test #{items} rounded items with last digit of #{digit} should sum up to rounded total of BigDecimal items with precision of #{precision} if passed as array".gsub(' ','_')
+        define_method method_name do
+          decimal = BigDecimal.new("0."+"3"*precision+"#{digit}")
+          arr = Array.new(items){decimal}
+          rounded_total = arr.reduce(:+).round(precision)
+          assert_equal(rounded_total,LareRound.round(arr,precision).reduce(:+).round(precision))
+        end
+
+        method_name = "test #{items} rounded items with last digit of #{digit} should sum up to rounded total of BigDecimal items with precision of #{precision} if passed as hash".gsub(' ','_')
+        define_method method_name do
+          decimal = BigDecimal.new("0."+"3"*precision+"#{digit}")
+          hash = Hash[(1..items).map.with_index{|x,i|[x,decimal]}]
+          rounded_total = hash.values.reduce(:+).round(precision)
+          assert_equal(rounded_total,LareRound.round(hash,precision).values.reduce(:+).round(precision))
+        end
+
+        method_name = "test #{items} rounded items with last digit of #{digit} and precision of #{precision} if passed as hash should not change order".gsub(' ','_')
+        define_method method_name do
+          decimal = BigDecimal.new("0."+"3"*precision+"#{digit}")
+          hash = Hash[(1..items).map.with_index{|x,i|[x,decimal+BigDecimal.new(i)]}]
+          rounded_hash = LareRound.round(hash.clone,precision)
+          hash.keys.each do |key|
+            assert( (((hash[key] - rounded_hash[key])*10**precision).abs < 1) )
+          end
+        end
+
+        method_name = "test #{items} rounded negative items with last digit of #{digit} should sum up to rounded total of BigDecimal items with precision of #{precision} if passed as array".gsub(' ','_')
+        define_method method_name do
+          decimal = BigDecimal.new("-0."+"3"*precision+"#{digit}")
+          arr = Array.new(items){decimal}
+          rounded_total = arr.reduce(:+).round(precision)
+          assert_equal(rounded_total,LareRound.round(arr,precision).reduce(:+).round(precision))
+        end
+
+        method_name = "test #{items} rounded mixed (+/-) items with last digit of #{digit} should sum up to rounded total of BigDecimal items with precision of #{precision} if passed as array".gsub(' ','_')
+        define_method method_name do
+          decimal = BigDecimal.new( (SecureRandom.random_number(100) % 2 == 0) ? "" : "-" + "0."+"3"*precision+"#{digit}")
+          arr = Array.new(items){decimal}
+          rounded_total = arr.reduce(:+).round(precision)
+          assert_equal(rounded_total,LareRound.round(arr,precision).reduce(:+).round(precision))
+        end
+
+      end
+    end
+  end
+
+  def test_should_raise_if_precision_is_nil
+    decimal = BigDecimal.new("0.1234")
+    arr = Array.new(3){decimal}
+    exception = assert_raises(LareRound::LareRoundError){
+      LareRound.round(arr,nil)
+    }
+    assert_equal("precision must not be nil", exception.message)
+  end
+
+  def test_should_raise_if_precision_is_less_than_zero
+    decimal = BigDecimal.new("0.1234")
+    arr = Array.new(3){decimal}
+    exception = assert_raises(LareRound::LareRoundError){
+      LareRound.round(arr,-1)
+    }
+    assert_equal("precision must be greater or equal to 0", exception.message)
+  end
+
+  def test_should_raise_if_precision_is_not_a_number
+    decimal = BigDecimal.new("0.1234")
+    arr = Array.new(3){decimal}
+    exception = assert_raises(LareRound::LareRoundError){
+      LareRound.round(arr,"not_a_number")
+    }
+    assert_equal("precision must be a number", exception.message)
+  end
+
+  def test_should_raise_if_values_is_nil
+    exception = assert_raises(LareRound::LareRoundError){
+      LareRound.round(nil,2)
+    }
+    assert_equal("values must not be nil", exception.message)
+  end
+
+  def test_should_raise_if_values_is_empty
+    exception = assert_raises(LareRound::LareRoundError){
+      LareRound.round([],2)
+    }
+    assert_equal("values must not be empty", exception.message)
+  end
+
+  def test_should_raise_if_values_contains_invalid_values
+    exception = assert_raises(LareRound::LareRoundError){
+      LareRound.round([3.2, 1, "not_a_number", Exception.new, nil],2)
+    }
+    assert_equal("values contains not numeric values (3)", exception.message)
+  end
+
+  def test_should_warn_if_numbers_not_big_decimals
+    out, err = capture_io do
+      LareRound.round([1.2132, 12.21212, 323.23],2)
+    end
+    assert_match(/values contains non decimal values, you might loose precision or even get wrong rounding results/, err)
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,8 @@
+base_dir = File.expand_path(File.join(File.dirname(__FILE__), ".."))
+lib_dir  = File.join(base_dir, "lib")
+test_dir = File.join(base_dir, "test")
+
+$LOAD_PATH.unshift(lib_dir)
+
+require 'test/unit'
+require 'lare_round'

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: lare_round
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- |+
+  Carsten Wirth
+
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-10-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: "A collection of BigDecimal items e.g. invoice items can be rounded for
+  displaying them in views. Rounding may apply a rounding error to the items such
+  as the summed up rounded items will show deviation towards an invoice total with
+  summed unrounded items. Which might cause confusion for customers and finance departments
+  alike. Application of the largest remainder method can help to preserve the total
+  sum for fractionated parts thus eliminating this confusion.\n  "
+email:
+- |
+  carsten.wirth@blacklane.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lare_round.gemspec
+- lib/lare_round.rb
+- lib/lare_round/version.rb
+- test/lare_round_test.rb
+- test/test_helper.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: gem for rounding BigDecimal items by preserving its sum
+test_files:
+- test/lare_round_test.rb
+- test/test_helper.rb