CoinPurse

A lightweight .NET library for managing currency containers in games, simulations, or any application that needs flexible coin and currency tracking. CoinPurse supports multiple currency types, coin and weight capacity enforcement, and currency conversion.

---

Installation

Install via NuGet Package Manager:

Install-Package CoinPurse

Or via the .NET CLI:

dotnet add package CoinPurse

---

Requirements

.NET Standard 2.0 compatible runtime or higher, including .NET Framework 4.6.1+, .NET Core 2.0+, and .NET 5–10.

---

Quick Start

Defining Currencies

Create Currency objects to represent each denomination in your system. The BaseValue represents how many of the smallest unit make up one of this coin — for example, 100 copper to 1 silver.

var copper = new Currency(baseValue: 1, coinName: "Copper", weight: 0.09); var silver = new Currency(baseValue: 10, coinName: "Silver", weight: 0.09); var gold = new Currency(baseValue: 100, coinName: "Gold", weight: 0.09);

Creating a Container

A Container is a coin purse or pouch that holds your currencies. You can set a maximum coin count and weight capacity.

// Default container: 50 coin capacity, 50oz weight capacity, named "Coin Purse" var purse = new Container(); // Custom capacity and name var pouch = new Container(coinCapacity: 100, weightCapacity: 20.0, containerName: "Belt Pouch"); // Pre-load with currency types (no coins yet) var purse = new Container( currencies: new List { copper, silver, gold }, coinCapacity: 100, containerName: "Adventurer's Purse" ); // Pre-load with currencies and starting coins var purse = new Container( coins: new Dictionary { { copper, 50 }, { silver, 10 } }, coinCapacity: 100, containerName: "Starting Purse" );

---

Usage

Adding and Removing Coins

purse.AddToCoinPurse(copper, 25); purse.RemoveFromCoinPurse(copper, 10);

Counting Coins

int totalCoins = purse.CountAllCoins(); int copperCount = purse.CountCoins(copper);

Checking Weight

double totalWeight = purse.GetWeight(); double goldWeight = purse.GetWeight(gold);

Adjusting Capacity

purse.IncreaseCapacity(capacityIncrease: 50, weightCapacity: 10.0); purse.DecreaseCapacity(coinCapacityDecrease: 10, weightCapacityDecrease: 5.0);

Currency Conversion

Preview a conversion without modifying the container:

int goldPieces = purse.ConvertCoins(silver, gold); // How many gold can I get for my silver?

Convert and apply the result to the container:

purse.ConvertAndAddToContainer(silver, gold);

Conversions use integer division and round down to the nearest whole coin. Any remainder stays in the original denomination.

---

Exceptions

Exception	Thrown When
ContainerNameInvalidException	A null or empty name is provided to a container
CoinPurseTooFullException	Adding coins would exceed the coin capacity
CoinPurseTooHeavyException	Adding coins would exceed the weight capacity
CoinPurseTooEmptyException	Decreasing capacity would drop below the current coin count
CoinPurseTooLightException	Decreasing weight capacity would drop below the current weight
NotEnoughCoinsException	Removing more coins than are present in the container
ConversionFailedException	A conversion results in zero coins, or a currency is not found in the container

---

Notes

• Currency objects are tracked by reference. The same Currency instance must be used consistently when adding, removing, and converting coins within a container.
• Capacities cannot go below zero. Passing a negative value to a capacity setter will clamp it to zero.
• BaseValue cannot be less than 1. Passing zero or a negative value will default to 1.

---

Changelog

1.0.1.1 — Bug Fixes

• Fixed UpdateContainerName always assigning to itself instead of the new value, making the method a no-op
• Fixed ConvertAndAddToContainer and ConvertCoins throwing an unhandled KeyNotFoundException when either currency was not present in the container — now throws ConversionFailedException with a descriptive message
• Fixed ConvertAndAddToContainer silently doing nothing when there were not enough coins to complete the conversion — now throws ConversionFailedException
• Fixed ArgumentNullException in constructors passing the message string as the parameter name
• Fixed DecreaseCapacity incorrectly blocking valid decreases with a redundant <= 0 check on the weight capacity
• Fixed typo in ContainerNameInvaldException — renamed to ContainerNameInvalidException
• Removed unused variable in AddCurrency catch block
• Migrated target framework from .NET 4.6.1 to .NET Standard 2.0 for broader platform compatibility

1.0.1 — Container Overhaul (Breaking Changes)

• Breaking: Renamed primary class from CoinPurse to Container
• Breaking: SetCapacity is now private — use IncreaseCapacity or DecreaseCapacity instead
• Breaking: CountCoins() (no arguments) renamed to CountAllCoins()
• Breaking: ConvertAndAddToCoinPurse renamed to ConvertAndAddToContainer
• Breaking: CoinPurseFullException removed — replaced by CoinPurseTooFullException
• Added weight capacity system — containers now track both coin count and total weight
• Added container naming — containers can be named and renamed via UpdateContainerName
• Added ConvertCoins method for previewing a conversion without modifying the container
• Added AddCurrency overload that accepts a KeyValuePair<Currency, int>
• Added GetWeight(Currency, int) overload for weighing a hypothetical number of coins
• Added exceptions: ContainerNameInvalidException, CoinPurseTooHeavyException, CoinPurseTooLightException, CoinPurseTooEmptyException, ConversionFailedException
• AddCurrency now upserts — adding a currency that already exists increments its count rather than throwing

1.0.0 — Initial Release

• CoinPurse class with coin capacity enforcement
• Currency class with BaseValue, CoinName, and Weight
• Add, remove, and count coins by currency type
• Basic currency conversion via ConvertAndAddToCoinPurse
• Exceptions: NotEnoughCoinsException, CoinPurseFullException, CoinPurseTooFullException, CurrencyExistsException