Money Type for the CLR

Updated Wiki: Home

codekaizen — Mon, 18 Mar 2013 17:32:55 GMT

A convenient money structure for the CLR which carefully handles rounding and currency types.

NOTE: source now at: https://bitbucket.org/rplaire/money-type-for-the-clr

Background

The CLR doesn't include a native money type. This could be seen as a shortcoming, or a reasonable design decision, given that it is an object-oriented framework, and adding your own type to encapsulate the data and behavior you need is pretty much its reason of being.

Money, however, is a type which is so primitive, and so pervasive, that it's absence is notable. Other primitive types are built in, after all. Martin Fowler considers this in Patterns of Enterprise Application Architecture [PEAA]:

A large proportion of the computers in this world manipulate money, so it's always puzzled me that money isn't actually a first class data type in any mainstream programming language. The lack of a type causes problems, the most obvious surrounding currencies. ...

The good thing about object-oriented programming is that you can fix these problems by creating a Money class that handles them. Of course, it's still surprising that none of the mainstream base class libraries actually do this. (p. 488)

Approach

Money
In [PEAA], Martin Fowler and Matt Foemmel's example shows Money as an object with value semantics. In .Net, a value type is a first-class entity, and so it makes sense to combine these two and make Money a value type. This should also help deal with the issue of performance the authors bring up, since value types are not reference counted on the heap, meaning less pressure on the GC and therefore higher performance.

Also in [PEAA], the underlying type used to store the value was an Int64 (long). The authors then scale the value by some power of 10 (0 - 3) to represent fractional units. In this type, I opted to represent the fraction as a completely separate Int32, which is scaled by 10^9 (the largest power of 10 which fits into an Int32). This allows storing much smaller fractions, which is useful for intermediate computations. Due to this, the type a fixed-decimal point numeric representation. This is how relational databases often store money, so it makes a natural fit. Another alternative was to represent the money value with a System.Decimal, as is done here: http://www.noticeablydifferent.com/CodeSamples/Money.aspx. The problem with this approach is that System.Decimal is a binary floating-point type, and binary floating-point types give us all sorts of headaches when computing with them and not treating the round-off with extreme care. These issues can be avoided by working with whole numbers and scaling to represent fractions.

I opted to separate the responsibility to allocate money in a defined distribution into another class: MoneyDistributor. The reasons for this are that I think it helps readability and conscientious use, and having both a divide operation and an allocate operation on the money class seemed to be a bit of a conflict of interest. By separating out the responsibility for not losing (or gaining!) fractions of money into a separate class, I force Money to admit that it can't really do a good job at dividing itself up, and rather entrusts this to another class. Further, this then allows subclassing of MoneyDistributor for custom behavior, which can no longer be done with Money, since it is a value type.

Currency
With regard to the Currency aspect of the type, .Net doesn't have this, but Java does. Java follows ISO 4217, and so it is pretty safe to add something like this to .Net - just follow the spec. My first inclination was to just make a Currency class with static fields: one for each currency. However, Jason Hunt's implementation used a CultureInfo instance to represent the currency, and it got me to think about how this is already somewhat present in the BCL. Since the CultureInfo classes are built around an Int32 identifier known as the LCID, it seems reasonable to use this as the currency identifier as well. However, after some observation, this appears not to be a sound approach: not only are the culture-to-currency relationships not 1-to-1, but they are also not N-to-1, since some cultures use more than one currency. In the end, I used the ISO spec to generate some lookup tables, and keep everything related based on the ISO numeric code for any given currency. This code is an Int32, and this serves as the only field in a Currency instance, allowing me to represent the Currency as a value type as well, making serialization of Money quite simple: there are no reference fields in it! One last functionality of currency to point out: IFormatProvider is implemented on it, so that when ToString() is called on Money, the associated Currency instance is passed with it and it gets formatted as expected.

Updated Wiki: Home

codekaizen — Mon, 18 Mar 2013 17:25:34 GMT

A convenient money structure for the CLR which carefully handles rounding and currency types.

Background

Approach

Commented Issue: Multiply and divide ignore the Currency [3437]

Marchy — Mon, 22 Oct 2012 02:27:50 GMT

operator * and operator / both ignore the Currency of the amount being modified and return a Money for the current culture. Code should be
 
 public static Money operator *(Money left, Decimal right)
 {
 return new Money(((Decimal)left * right), left._currency);
 }
 
 public static Money operator /(Money left, Decimal right)
 {
 return new Money(((Decimal)left / right), left._currency);
 }
 
thanks for prividing this project
Paul
Comments: ** Comment from web user: Marchy **

Agreed, had made the same fix

Source code checked in, #80132

Project Collection Service Accounts — Mon, 01 Oct 2012 21:49:39 GMT

Upgrade: New Version of LabDefaultTemplate.xaml. To upgrade your build definitions, please visit the following link: http://go.microsoft.com/fwlink/?LinkId=254563

Source code checked in, #80131

Project Collection Service Accounts — Mon, 01 Oct 2012 21:43:10 GMT

Checked in by server upgrade

Source code checked in, #55373

_TFSSERVICE — Mon, 02 Aug 2010 22:49:34 GMT

Checked in by server upgrade

Created Issue: Money(decimal, Currency) ignores second argument

esteewhy — Fri, 08 May 2009 15:10:59 GMT

Another subtle glitch: when supplying Currency as a second argument to Money ctor, that arg gets overridden. I think it's the order of constructor calls that matters.

Commented Issue: Code (re)usability improvements

esteewhy — Fri, 08 May 2009 13:24:21 GMT

Hello, great work! Found you at CodeProject first, than saw the code here, started using it and found some issues worth mentioning:

-- I'd like to persist Money type as a string in a custom format, so it's desirable to know if a given currency code is valid in the system. For this case to work i've introduced a Currency.TryParse(..) method with a semantic similar to that of some standard CLR value types.

-- For UI purpose it'd be cool to have a list of all valid currencies, so i've exposed it via static Currency.Currencies property

-- Presently, there's no way to know if a given Currency instance represents a valid currency until you try to access any instance property and, possibly, get an InvalidOperationException -- ups, not nice! I've made these properties silently return default values if no matching currency was found. So at least the following snippet won't cause an earthquake: new Currency().IsoNumericCode, but just silently return "0". For the sake of consistency, i've also added Currency.Empty static instance.

-- Finally, just to simplify a bit working with a huge source file, i've moved a part of Currency.cs into partial class file.
Comments: ** Comment from web user: esteewhy **

Ups, also, forgot to tell you: I've also created some helper methods to de/serialise Money to/fro string. Just in case smb. w'd be interested...

Created Issue: Code (re)usability improvements

esteewhy — Fri, 08 May 2009 13:21:37 GMT

Created Issue: Multiply and divide ignore the Currency

PaulLinton — Tue, 24 Mar 2009 00:36:06 GMT

operator * and operator / both ignore the Currency of the amount being modified and return a Money for the current culture. Code should be

public static Money operator *(Money left, Decimal right)
{
return new Money(((Decimal)left * right), left._currency);
}

public static Money operator /(Money left, Decimal right)
{
return new Money(((Decimal)left / right), left._currency);
}

thanks for prividing this project
Paul

Created Issue: Formatting errors

dgon — Mon, 29 Sep 2008 19:42:36 GMT

Hi,
When reviewing your code I found that no matter what currency is set on the Money object, it gets ignored when calling ToString(), being always the currency corresponding the current Culture. If it happens to be a culture with $, then the corresponding test is passed.
I tried fixing it myself, passing the current _currency as the IFormatInfo argument, but then it complains heavily about the code used to create the corresponding cultureInfo as it expect a windows Lcid (not Iso number code).

Thanks a lot if you happen to look at it, great code, by the way

New Post: Quick code scan feedback

sumothecat — Wed, 20 Aug 2008 11:57:47 GMT

Hi there codekaizen - a couple of thoughts.

What you say about System.Decimal isn't really accurate - it's a good type for representing Money and has the advantage of easily mapping to a database. Take a look here for a full explanation. How does this money class map to the database?

Names for simple enums shouldn't be pluralised.

You really need the mainline usage code samples on the project home page. Few people have the time it takes to look at the source code to initially evaluate this (including me!).

Thanks! Pete.

Source code checked in, #13518

codekaizen — Fri, 01 Aug 2008 19:24:32 GMT

Fixing static initialization

Source code checked in, #12971

codekaizen — Mon, 28 Jul 2008 20:07:27 GMT

Adding ISO 4217 currencies list

New Post: Quick code scan feedback

plind — Mon, 28 Jul 2008 19:38:00 GMT

Hey codekaizen,

As you reported on my blog, we both published a .NET Money implementation on exactly the same day. I’m still amazed! ;)

I did a quick scan of your implementation this weekend. I really like the completeness of your code. The completeness of the type converters and the implementation of IFormattable. Also, your test suite looks nice and complete.

By your comment on my implementation, you also got me to think and do some extra research on the best way to store monetary values and the best way to do calculations with them. Reading more, I got to think that it might indeed be wise to follow your path and use a two integers two represent the value (one for the whole number and the other for that fraction). In essence, by using an int64 for the whole number and an int32 for the fraction, you’ve created a fixed point 96 bit decimal. I’m using the regular Decimal type, which is a floating point type. I’m still not sure, however, if it being a floating point type is such a bad thing. First of all, the decimal point can be fixed per object instance. Second, if you need the extra precision, you can have it with the same type. Literature (like this from IBM) suggest a theoretic need for 2191(!) decimal places, but settles for 25-30 decimal places being enough for almost all cases. With the Decimal type you can at least reach a precision of 28 decimal places, but with the two-integer solution you’re always stuck with a maximum precision of 9 decimal places.

Reading all this, it became clear to me that I got some arithmetic sorting out to do with my implementation, which mainly focuses on easy creation and storage of monetary values. I’m going to puzzle a little more on this for my version 2 implementation.

Anyway, one last thing: I’m not sure your approach of adding the currency to the monetary value is “inviting” enough. The way a user of your type needs to address a certain currency code seems a little verbose (mainly judging from your tests). Although, in all honesty, I have not gotten around to dive deeply into that yet.

Keep up the good work!

Pascal.

Source code checked in, #12516

codekaizen — Fri, 25 Jul 2008 02:05:05 GMT

Adding initial import

Source code checked in, #12515

codekaizen — Fri, 25 Jul 2008 02:02:31 GMT

Adding svn structure