diff --git a/CHANGELOG.md b/CHANGELOG.md index 498903b..e4db240 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm ### Added - Reference to Martin Fowler's Money Pattern in documentation - ReadTheDocs integration for comprehensive documentation +- Documentation on working with cents and smallest currency units ### Changed - Updated documentation URLs to point to ReadTheDocs diff --git a/README.md b/README.md index 93c825e..8571a9a 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,37 @@ print(f"Tax: {tax.format()}") # $1.40 print(f"Total: {total.format()}") # $21.39 ``` +### Working with Cents + +Some applications store and calculate money in the smallest currency unit (cents, pence, etc.). Here's how to work with cents in moneyx: + +```python +from decimal import Decimal +from moneyx import Money + +# Convert from cents to dollars when creating Money objects +cents_amount = 1299 # $12.99 in cents +price = Money(cents_amount / 100, "USD") +print(price.format()) # $12.99 + +# For more precision, use Decimal +cents_amount = 1299 +price = Money(Decimal(cents_amount) / Decimal("100"), "USD") +print(price.format()) # $12.99 + +# Converting a Money object to cents +dollars = Money("45.67", "USD") +cents = int(dollars.amount * 100) # 4567 +print(f"Amount in cents: {cents}") + +# Working with cents directly for JPY (which has 0 decimal places) +yen_amount = 1000 # ¥1000 (JPY has 0 decimal places) +jpy = Money(yen_amount, "JPY") +print(jpy.format()) # ¥1,000 +``` + +Note that moneyx handles the smallest currency unit internally, so you generally don't need to worry about cents-to-dollars conversion unless your application specifically stores amounts in cents. + ### Different Currencies ```python diff --git a/docs/source/conf.py b/docs/source/conf.py index ea765cc..7919cf5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -11,7 +11,7 @@ author = "devAbreu" # The full version, including alpha/beta/rc tags -release = "0.1.0" +release = "0.1.1" # Extensions extensions = [ diff --git a/docs/source/usage.rst b/docs/source/usage.rst index 79b312d..4fe91ac 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -91,6 +91,38 @@ Multiply a Money object by a number: discount = price.multiply(0.20) # $4.00 (20% of price) discounted = price.subtract(discount) # $15.99 +Working with Cents +----------------- + +Many financial applications store monetary values in the smallest currency unit (cents, pence, etc.). Here's how to work with cents in moneyx: + +.. code-block:: python + + from decimal import Decimal + from moneyx import Money + + # Converting from cents to dollars + cents_amount = 1299 # $12.99 in cents + price = Money(cents_amount / 100, "USD") + print(price.format()) # $12.99 + + # For more precision, use Decimal + cents_amount = 1299 + price = Money(Decimal(cents_amount) / Decimal("100"), "USD") + print(price.format()) # $12.99 + + # Converting a Money object to cents + dollars = Money("45.67", "USD") + cents = int(dollars.amount * 100) # 4567 + print(f"Amount in cents: {cents}") + + # Working with currencies that have 0 decimal places + yen_amount = 1000 # ¥1000 (JPY has 0 decimal places) + jpy = Money(yen_amount, "JPY") + print(jpy.format()) # ¥1,000 + +Note that moneyx handles the smallest currency unit internally, but converting to/from cents may be necessary when interfacing with other systems or databases that store monetary values as integers. + Rounding Strategies ------------------