Working with amounts of money has never been a simple matter: rounding, currency exchanges... mismanagement can result in losses for our company or in overcharging our clients, with the consequent reputational damage.

The pattern Money

Martin Fowler published in 2002 his famous book Patterns of Enterprise Application Architecture, where one of the patterns included was the so called pattern Money. With this pattern, Fowler aims to simplify the management of monetary amounts and reduce the possible risks mentioned above.

The pattern Money is based on another pattern known as Value Object, and consists of modeling a small object that represents a monetary amount. Two attributes are used for this purpose: the quantity (amount), and the currency (currency), and a series of logical and mathematical operations:

Attributes

• amount: is the amount, always represented in the minimum unit of the associated currency. This representation is perfect for comparisons between amounts of the same currency, since comparisons between floating point numbers remain an unresolved issue in any language.
  
  It is important to know that not all currencies are like the dollar or the euro, since not in all of them the minimum unit is the cent. There are currencies where the coin itself is the minimum unit, and others where they not only have cents, but also have units smaller than a penny.
  
  Examples of these cases are the Bahraini dinar, with thousandths of a dinar, or the Chilean peso, where there are no units less than a peso. A list of all currencies is available this link.

• currency: is the code ISO-4217 of the currency we are working with. It is a 3-letter code that represents the currency internationally, for example EUR for Euros.

Methods / Operations

• +, -, *, / : basic mathematical operations, such as addition, subtraction, multiplication, division...
• allocate: a special operation intended to divide an amount of money between two or more recipients. We will go into more detail later.
• , ≤, ≥, = basic logical operations, such as less than, greater than, less than, greater than, same...

Examples

We want to represent the amount 528.75€, whose minimum unit is the euro cent:

• amount: 52875
• currency: EUR

We want to represent the amount 528.75.د (Bahrain dinars), whose minimum unit is one thousandth of a dinar.

• amount: 528750
• currency: BHD

To visually represent the quantity, we only need to apply the simple formula: amount / (10 x minimum unit).

Implementation

It is easy to make a basic implementation of this pattern, what is really tedious is to have always updated the list of currencies, with their minimum units or their conversion ratios.

Let's see a simple implementation in PHP:+

This basic implementation would be missing all the methods of logical and mathematical operations. I wanted to leave this implementation aside in order to comment that we can do it in two different versions:

• Object-oriented: adding the following methods add, substract, multiply, divide... This would be the classic object-oriented style. It would allow us to take two approaches: mutable (modifies the current instance) or immutable (does not modify the instance, returns a new one). This way we can execute things like:

• Operator overload: many object-oriented languages, such as Java, PHP, Python or Ruby, allow for what we call operator overload, which is nothing more than allowing to change the behavior of arithmetic and logical operators when they are applied to objects of a certain class, and not to primitive types as it is usually done.
  This would allow us to overload the operators in such a way that we could execute something like:

The basic implementation of this pattern is really very simple, but if we want to get the most out of it we have implementations in almost all languages, which also cover other aspects such as the visual representation of the amount (placing the currency symbol to the right or to the left), or the conversion between currencies.

Some known implementations:

• PHP: https://github.com/moneyphp/money
• Ruby: https://github.com/RubyMoney/money
• Python: https://github.com/poswald/python-money

Method allocate

This method, as mentioned before, is a special method used to properly distribute an amount between two or more recipients when it cannot be done in an exact way (no leftovers). For example when we do it based on percentages or ratios.

Let's look at a specific case:

We want to split 5cts euro between two accounts at 30%-70%. This implies a split of 1.5 cents and 3.5 cents. The problem is that the cent is the minimum unit of the euro currency, and we cannot split a cent in two, therefore the exact split cannot be done.

The most common solution is to distribute 1 cent to each recipient as long as they have not reached the right amount. Once you have exceeded that amount, you stop receiving money.