easydollar 1.0.2
A simple, light-weight data type for handling cash (in USD)

### What's new in v1.0.2

* Improved parsing of easydollar.usd() to allow commas (eg '$1,000.00')
* Changed the output of USD.__repr__ to improve readability
* Fixed a major logical error in USD.distribute(). It should now function as intended.

#### Example
```python
cash = usd('$5,000.67')
print(repr(cash)) # Output: USD(dollars=5000, cents=67)
```


# easydollar | py
###### written by Sean Franklin (sean.patrick516@gmail.com)

```
pip install easydollar
```

Floating-Point values should **not** be used in money calculations.
Python's **Decimal** or *BigDecimal* in Java are a bit clunky to use for quick
prototyping.

This module is useful for **str**-parsed US-Dollar amounts (from user input, or a .*txt*/.*csv*/.*xls*)


This is the **wrong** module for cent calcuations that need three or more decimal-point places (like gas prices or some APR calculations)



**Note**
"Instantiating a **USD** with a **float**" is a feature intentionally left out. Input like 50.20 actually becomes *50.2* which then becomes *$50.02*
..which is obviously incorrect.



## How to use the USD type

**Note**
You can see the output of all the below examples by writing
```python
import easydollar.examples
```

#### How to import
It is recommended you use the **lower-case** *usd()*
to instantiate USD instances.

*usd()* casts a **str** to a **USD** instance.

```python
from easydollar.USD import usd
```

#### Add cash amounts

*Example 1*
```python
husband_income = usd('55000.00')

# if it's a whole dollar amount, the decimal-point is optional.
wife_income = usd('62000')

household_income = husband_income + wife_income

print(f'Total household income: {household_income}\n')
```

*Example 2*
```python
# USD instances will implicitly roll over cents into dollars when cast to a string.
money1 = usd('1.50')
money2 = usd('0.50')
total = money1 + money2
print (f'Dollar addition: {money1} + {money2} = {total}')

print (f"Output of usd('0.5255') = {usd('0.5255')}") # Outputs "$52.55"
print(f"Output of usd('1000575.100') = {usd('1000575.100')}") # Outputs "$1,000,576.00"
```


#### Making change from a transaction

```python
price = usd('56.60')

paid = usd('60.00')

change = paid - price

print(f'Price: {price}')
print(f'Paid: {paid}')
print (f'Change due: {change}')
```


## IMPORTANT!
The multiply operator on the USD object is a "scale" operation (only accepts a whole number)
*You can't multiply two USD's together.*

```python
payrate = usd('15.00')
hours_worked = 40

paycheck = payrate * hours_worked

print(f'This weeks earnings: {paycheck}')
```


#### Division, and Interest Multiplication 

The divide operator in **USD** is a *distribution* function.

Similar to the *multiply* operator, a USD instance can only be "divided" by a whole number.

## IMPORTANT!
The division operator is not a *true division* (this would involve using floating-point values in some cases.) Instead, it invokes USD's 'distribute' method.

*USD.distribute(n)* distributes the *USD*-instance's value among *n* and returns a **list** of **USD**

If you were to sum the elements of the list, you would have
the pre-*distribute()* value **exactly**

The divide "/" operator is **only** a shorthand for *my_usd.distribute(n)[0]*

## IMPORTANT!
If you add the result of the "/" operator *n* times, you **might not**
get the original value.

```python
loan_amount = usd('10653.26')

interest = 21   # 21 percent (21%)

total_loan_interest = loan_amount.interest(interest)

term = 60

monthly_principle = loan_amount / term
monthly_interest = total_loan_interest / term

first_payment = monthly_interest + monthly_principle

print('~~ Loan Issued. ~~')
print(f'Loan Amount: {loan_amount}')
print(f'Interest: {interest}%')
print(f'Term: {term} months')
print(f'Total interest to be paid over term: {total_loan_interest}\n')

print(f'Principle monthly: {monthly_principle}')
print(f'Interest monthly: {monthly_interest}\n')
print(f'First payment due: {first_payment}')
```

Using the division operator here is okay, because this is a calculation of the first payment.
It is equivilent to 
```python
monthly_principle = loan_amount.distribute(term)[0]
```

To find the current payment, you could do:
```python
current_payment = my_usd.distribute(total_term)[payments_already_made]
```
or
```python
current_payment = my_usd.distribute(remaining_term)[0]
```

*A feature to streamline this is being worked on.*


## Other features of note:


#### with_interest(percent)
```python
appreciated_value = my_usd.with_interest(50) # 50% appreciation
```

#### apply_interest(percent)
```python
my_usd.apply_interest(0.6) # Applies 0.6% interest to my_usd
```