Add Money#to_nearest_cash_value to return a rounded Money instance to the smallest denomination

This new method allows you to get a new Money instance rounded to the smallest denomination.

Closes RubyMoney#1131

Author: sunny

AUTHORS

@@ -1,8 +1,8 @@
 Abhay Kumar
 Adrian Longley
+Alex Speller
 Alexander Donkin
 Alexander Ross
-Alex Speller
 Andreas Loupasakis
 Andrei
 Andrew White
@@ -49,8 +49,8 @@ Greg Byrne
 Hakan Ensari
 Hongli Lai
 Ilia Lobsanov
-Ivan Shamatov
 Ingo Wichmann
+Ivan Shamatov
 Jack Spiva
 Jacob Atzen
 James Cotterill
@@ -83,8 +83,8 @@ Marco Otte-Witte
 Mateus Gomes
 Mateusz Wolsza
 Matias Korhonen
-Matthew McEachen
 Matt Jankowski
+Matthew McEachen
 Max Melentiev
 Michael Irwin
 Michael J. Cohen
@@ -96,14 +96,15 @@ Mike Połétyn
 Musannif Zahir
 Neil Middleton
 Nick Lozon
+Nicolay Hvidsten
 Nihad Abbasov
 Olek Janiszewski
 Orien Madgwick
-Paweł Madejski
 Paul McMahon
 Paulo Diniz
 Pavan Sudarshan
 Pavel Gabriel
+Paweł Madejski
 pconnor
 Pedro Nascimento
 Pelle Braendgaard
@@ -119,9 +120,11 @@ sankaranarayanan
 Scott Pierce
 Semyon Perepelitsa
 Shane Emmons
+Simon Neutert
 Simone Carletti
 Spencer Rinehart
 Steve Morris
+Sunny Ripert
 Thomas E Enebo
 Thomas Weymuth
 Ticean Bennett
@@ -142,5 +145,3 @@ Yuri Sidorov
 Yuusuke Takizawa
 Zubin Henner
 Бродяной Александр
-Nicolay Hvidsten
-Simon Neutert

CHANGELOG.md

@@ -13,7 +13,8 @@
 - Add Zimbabwe Gold (ZWG) currency
 - Update thousands_separator for CHF
 - Add Caribbean Guilder (XCG) as replacement for Netherlands Antillean Gulden (ANG)
-- Add `Currency#cents_based?` to check if currency is cents-based
+- Add `Money#to_nearest_cash_value` to return a rounded Money instance to the smallest denomination
+- Add `Money::Currency#cents_based?` to check if currency is cents-based
 - Add ability to nest `Money.with_rounding_mode` blocks
 - Allow `nil` to be used as a default_currency
 

CONTRIBUTING.md

@@ -7,8 +7,8 @@
 3. Make sure everything is working: `bundle exec rake spec`
 4. Make your changes
 5. Test your changes
-5. Create a Pull Request
-6. Celebrate!!!!!
+6. Create a Pull Request
+7. Celebrate! 🎉
 
 ## Notes
 

README.md

@@ -472,7 +472,7 @@ Money.from_amount(2.34567).format #=> "$2.34567"
 
 To round to the nearest cent (or anything more precise), you can use the `round` method. However, note that the `round` method on a `Money` object does not work the same way as a normal Ruby `Float` object. Money's `round` method accepts different arguments. The first argument to the round method is the rounding mode, while the second argument is the level of precision relative to the cent.
 
-```
+```ruby
 # Float
 2.34567.round     #=> 2
 2.34567.round(2)  #=> 2.35
@@ -485,10 +485,18 @@ Money.from_cents(2.34567).round(BigDecimal::ROUND_HALF_UP, 2).format #=> "$0.023
 ```
 
 You can set the default rounding mode by passing one of the `BigDecimal` mode enumerables like so:
+
 ```ruby
 Money.rounding_mode = BigDecimal::ROUND_HALF_EVEN
 ```
-See [BigDecimal::ROUND_MODE](https://ruby-doc.org/stdlib-2.5.1/libdoc/bigdecimal/rdoc/BigDecimal.html#ROUND_MODE) for more information
+
+See [BigDecimal::ROUND_MODE](https://ruby-doc.org/stdlib-2.5.1/libdoc/bigdecimal/rdoc/BigDecimal.html#ROUND_MODE) for more information.
+
+To round to the nearest cash value in currencies without small denominations:
+
+```ruby
+Money.from_cents(11_11, "CHF").to_nearest_cash_value.cents # => "CHF 11.10"
+```
 
 ## Ruby on Rails
 
@@ -528,7 +536,7 @@ This will work seamlessly with [rails-i18n](https://github.com/svenfuchs/rails-i
 
 If you wish to disable this feature and use defaults instead:
 
-``` ruby
+```ruby
 Money.locale_backend = nil
 ```
 

lib/money/money.rb

@@ -80,6 +80,13 @@ def round_to_nearest_cash_value
     return_value(rounded_value)
   end
 
+  # Round a given amount of money to the nearest possible money in cash value.
+  #
+  # @return [Money]
+  def to_nearest_cash_value
+    dup_with(fractional: round_to_nearest_cash_value)
+  end
+
   # @!attribute [r] currency
   #   @return [Currency] The money's currency.
   # @!attribute [r] bank

spec/money_spec.rb

@@ -527,6 +527,36 @@ def expectation.fractional
     end
   end
 
+  describe "#to_nearest_cash_value" do
+    it "rounds to the nearest possible cash value" do
+      expect(Money.new(23_50, "AED").to_nearest_cash_value).to eq(Money.new(23_50, "AED"))
+      expect(Money.new(-23_50, "AED").to_nearest_cash_value).to eq(Money.new(-23_50, "AED"))
+      expect(Money.new(22_13, "AED").to_nearest_cash_value).to eq(Money.new(22_25, "AED"))
+      expect(Money.new(-22_13, "AED").to_nearest_cash_value).to eq(Money.new(-22_25, "AED"))
+      expect(Money.new(22_12, "AED").to_nearest_cash_value).to eq(Money.new(22_00, "AED"))
+      expect(Money.new(-22_12, "AED").to_nearest_cash_value).to eq(Money.new(-22_00, "AED"))
+
+      expect(Money.new(1_78, "CHF").to_nearest_cash_value).to eq(Money.new(1_80, "CHF"))
+      expect(Money.new(-1_78, "CHF").to_nearest_cash_value).to eq(Money.new(-1_80, "CHF"))
+      expect(Money.new(1_77, "CHF").to_nearest_cash_value).to eq(Money.new(1_75, "CHF"))
+      expect(Money.new(-1_77, "CHF").to_nearest_cash_value).to eq(Money.new(-1_75, "CHF"))
+      expect(Money.new(1_75, "CHF").to_nearest_cash_value).to eq(Money.new(1_75, "CHF"))
+      expect(Money.new(-1_75, "CHF").to_nearest_cash_value).to eq(Money.new(-1_75, "CHF"))
+
+      expect(Money.new(2_99, "USD").to_nearest_cash_value).to eq(Money.new(2_99, "USD"))
+      expect(Money.new(-2_99, "USD").to_nearest_cash_value).to eq(Money.new(-2_99, "USD"))
+      expect(Money.new(3_00, "USD").to_nearest_cash_value).to eq(Money.new(3_00, "USD"))
+      expect(Money.new(-3_00, "USD").to_nearest_cash_value).to eq(Money.new(-3_00, "USD"))
+      expect(Money.new( 3_01, "USD").to_nearest_cash_value).to eq(Money.new(3_01, "USD"))
+      expect(Money.new(-3_01, "USD").to_nearest_cash_value).to eq(Money.new(-3_01, "USD"))
+    end
+
+    it "raises an error if smallest denomination is not defined" do
+      expect {Money.new(1_00, "XAG").to_nearest_cash_value}
+        .to raise_error(Money::UndefinedSmallestDenomination)
+    end
+  end
+
   describe "#amount" do
     it "returns the amount of cents as dollars" do
       expect(Money.new(1_00).amount).to eq 1