NMoneys 7.3.0
dotnet add package NMoneys --version 7.3.0
NuGet\Install-Package NMoneys -Version 7.3.0
<PackageReference Include="NMoneys" Version="7.3.0" />
paket add NMoneys --version 7.3.0
#r "nuget: NMoneys, 7.3.0"
// Install NMoneys as a Cake Addin #addin nuget:?package=NMoneys&version=7.3.0 // Install NMoneys as a Cake Tool #tool nuget:?package=NMoneys&version=7.3.0
Implementation of the Money Value Object to support representing moneys in the currencies defined in the ISO 4217 standard
What
NMoneys (plural) is a simple .Net library to represent monetary quantities.
What does NMoneys provide?
- types for representing currencies that conform to the ISO 4217 standard and quantities of money in a given currency.
- simple but extensible operations with monetary quantities of the same currency, including allocations of several sorts.
- ways of formatting the representation of monetary quantities
- a simple way of contributing to improve the completeness and correctness of the library
What not
NMoneys does not provide any support for exchanging monetary quantities in different currencies. That means that you could not "convert", for example, 10 Euro into the equivalent quantity in dollars using an internal exchange rate in the library. Instead, you could, for example, perform the conversion with numeric types and then display the resultant quantity in a meaningful way by using types provided by NMoneys.
If you need to convert monetary quantities into other currencies you can use the (from now an on) archived library NMoneys.Exchange alongside your trusted currency rates feed.
NMoneys does not provide, as of now, complex monetary or financial operations
What might
The aim of NMoneys is being simple and to-the-point: represent monetary quantities.
But, one of the reasons of making it Open-Source is that people with knowledge in the areas related with the subject of the library, that is money, can contribute with correct and useful ways to operate with the concepts in the library without cluttering its original purpose.
Quickstart
Install Nuget package.
dotnet add package NMoneys
Instantiate monetary quantities:
var threeDollars = new Money(3m, Currency.Usd);
var twoandAHalfPounds = new Money(2.5m, CurrencyIsoCode.GBP);
var tenEuro = new Money(10m, "EUR");
Obtain currencies or symbols:
Currency cad = Currency.Get(CurrencyIsoCode.CAD);
Currency australianDollar = Currency.Get("AUD");
Currency euro = Currency.Get(CultureInfo.GetCultureInfo("es-ES"));
string isoSymbol;
bool wasFound = Currency.TryGet(isoSymbol, out Currency? itMightNotBe);
Currency.Code.TryCast(36, out CurrencyIsoCode? maybeAud);
Currency.Code.TryParse("036", out CurrencyIsoCode? possiblyAud);
Operate with monetary quantities:
int isPositive = new Money(3m, Currency.Nok).CompareTo(new Money(2m, CurrencyIsoCode.NOK));
var three = new Money(3m);
var two = new Money(2m);
Money five = three.Plus(two);
Money oneOwed = two - three;
Money one = oneOwed.Abs();
10m.Eur().ToString(); // default formatting "10,00 €"
new Money(1500, Currency.Eur).Format("{1} {0:#,#.00}"); // rich formatting "€ 1.500,00"
Allocation fair = 40m.Eur().Allocate(4);
// fair.IsComplete --> true
// fair.Remainder --> 0€
// fair --> < 10€, 10€, 10€ >
Money moneyBack = 1m.Usd().Minus(.37m.Usd()); // ¢63
Denomination[] usCoins =
{
new Denomination(.25m), // quarters
new Denomination(.10m), // dimes
new Denomination(.05m), // nickels
new Denomination(.01m) // pennies
};
ChangeSolution change = moneyBack.MakeChange(usCoins);
// --> six coins (optimal): 2 quarters, 1 dime, 3 pennies
A more complete quick-start can be found here.
Why
The .NET Framework
.Net does not provide a good way of representing and operating with monetary quantities. Nonetheless, it does support numeric types that can be used to represent monetary quantities and it also provides support for formatting those numeric values in different cultures. But it is surprisingly easy to mix the concept of "10 represented euros when was saved" with "now, 10 represents something else because of the current culture of the thread".
The .Net Framework mixes numbers, currencies, cultures and formats in a way that it becomes confusing, difficult and/or impossible to represent something as simple as "one Euro" or "ten-and-the-half Zambian kwacha".
On top of that mixture of concepts, it does not support a complete implementation for the ISO standard and for the subset implemented, the information may be outdated or even wrong. Fixes might be issued for wrong/outdated data, but they may take too long to be rolled-out and to add further confusion currency formatting information can be modified by the user.
Other libraries
There might be others libraries or simple code snippets that might cover a necessity. But they did not cover mine for one or another reason: different goals, lack of activity/outdated, not suitable API,...
Open source
I have been using different incarnations of this library in commercial projects for some time now. It started with a limited set of well-known currencies. Then it grew to include some others until I decided to support all ISO currencies. At that point I realised that there was no way I could support correctly all scenarios for multiple reasons:
- lack of cultural knowledge (e.g. how does one represent decimals in Swaziland?)
- lack of technical knowledge (e.g how does one distribute an amount of money amongst a number of parties?)
With the realisation came the proposal to my employer to Open-Source the library and modify it so that is easy enough for people to help out, even if they are not .Net programmers.
And here we are.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net6.0
- No dependencies.
NuGet packages (10)
Showing the top 5 NuGet packages that depend on NMoneys:
Package | Downloads |
---|---|
NMoneys.Exchange
Extensions to the implementation of the Money Value Object to support exchange operations between moneys in different currencies. |
|
NMoneys.Serialization.Json_NET
Custom serialization when NMoneys objects are to be serialized/deserialized using Json.NET. |
|
NMoneys.Serialization.Raven_DB
Custom serialization when NMoneys objects are to be serialized/deserialized using RavenDB. |
|
SquareAccess
SquareAccess webservices API wrapper |
|
NMoneys.Serialization.Mongo_DB.mongocsharpdriver
Custom serialization when NMoneys objects are to be serialized/deserialized using MongDB's legacy driver. |
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
7.3.0 | 14,876 | 7/3/2024 |
7.2.0 | 12,733 | 3/19/2024 |
7.1.0 | 14,575 | 1/28/2024 |
7.0.0 | 3,344 | 12/30/2023 |
6.1.2 | 352,538 | 12/3/2021 |
6.1.1 | 980 | 12/1/2021 |
6.1.0 | 337,377 | 8/19/2018 |
6.0.0 | 24,363 | 12/31/2017 |
5.1.4.1 | 24,295 | 8/22/2017 |
5.1.4 | 1,713 | 8/16/2017 |
5.1.3 | 3,261 | 7/21/2017 |
5.1.2 | 1,238 | 7/19/2017 |
5.1.1 | 1,219 | 7/18/2017 |
5.1.0 | 2,369 | 6/14/2017 |
5.0.0 | 7,713 | 4/21/2017 |
4.5.0 | 42,102 | 7/20/2016 |
4.4.1 | 1,388 | 7/18/2016 |
4.4.0 | 1,527 | 7/11/2016 |
4.3.0 | 15,150 | 6/22/2016 |
4.2.0 | 4,083 | 3/16/2016 |
4.1.0 | 7,600 | 7/15/2015 |
4.0.0 | 5,782 | 4/21/2015 |
3.6.0 | 10,341 | 1/8/2015 |
3.5.1 | 3,847 | 6/19/2014 |
3.5.0 | 2,793 | 4/15/2014 |
3.4.1 | 1,985 | 3/14/2014 |
3.4.0 | 1,748 | 1/21/2014 |
3.3.0 | 1,517 | 1/6/2014 |
3.2.0 | 14,577 | 4/7/2013 |
3.1.0 | 4,678 | 1/1/2013 |
3.0.1 | 1,959 | 9/1/2012 |
3.0.0 | 2,490 | 8/2/2012 |
2.5.0 | 1,730 | 6/25/2012 |
2.2.0 | 1,891 | 2/13/2012 |
2.1.0 | 1,975 | 9/1/2011 |
2.0.0 | 2,110 | 6/30/2011 |
1.6.0 | 1,953 | 6/2/2011 |
1.5.1 | 1,909 | 5/20/2011 |
1.5.0 | 1,878 | 5/3/2011 |
1.4.0 | 2,062 | 3/17/2011 |
1.3.1 | 2,204 | 2/24/2011 |
1.3.0 | 2,411 | 2/12/2011 |