lucre 0.8.0

An ergonomic library for handling money.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# lucre

[![status-badge](https://ci.cosmicrose.dev/api/badges/43/status.svg)](https://ci.cosmicrose.dev/repos/43)
[![Crates.io Version](https://img.shields.io/crates/v/lucre)](https://crates.io/crates/lucre)
[![docs.rs](https://img.shields.io/docsrs/lucre)](https://docs.rs/lucre)

An ergonomic Rust library for handling money.

Represent money in your applications without fussing over generics or
lifetimes, while still being safe and fast. [ISO 4217] currency definitions are
built in.

[ISO 4217]: https://en.wikipedia.org/wiki/ISO_4217

## Install

Add `lucre` to your `Cargo.toml`.

```toml
[dependencies]
lucre = "0.8.0"
```

## Usage

The `Money` struct is the primary interface, with the `Currency` struct supporting it.
`Currency` contains constants for all current ISO 4217 currencies.

```rust
use lucre::{Money, Currency, Format, MoneyError};

fn main() -> Result<(), MoneyError> {
    // Create money from major or minor units
    let subtotal = Money::from_major(100, &Currency::USD);
    let tax = Money::from_minor(475, &Currency::USD);

    // Arithmetic is available as either checked or panicking operations
    let _unchecked = subtotal + tax;
    let total = subtotal.checked_add(&tax)?;

    // The display format has sensible defaults...
    assert_eq!(total.to_string(), "104.75 USD");

    // ...which can be overridden
    let format = Format::default().symbol();
    assert_eq!(total.format_with(&format).to_string(), "$104.75");

    Ok(())
}
```

### Several currencies at once

`Money` refuses to mix currencies — `+` panics and comparisons answer `None`.
When amounts in different currencies have to travel together, put them in a
`MoneyBag`, which keeps each currency on its own books.

```rust
use lucre::{Currency, Money, MoneyBag};

let mut wallet = MoneyBag::new();
wallet += Money::from_major(25, &Currency::USD);
wallet += Money::from_major(10, &Currency::EUR);

assert_eq!(
    wallet.balance(&Currency::USD),
    Money::from_major(25, &Currency::USD)
);

// A currency the wallet has never held answers zero, not nothing
assert_eq!(
    wallet.balance(&Currency::JPY),
    Money::from_major(0, &Currency::JPY)
);

// Both sums are available over the same iterator, so the type asked for is
// the decision: `Option<Money>` insists the currencies match, a bag keeps
// them apart
let refunds = [
    Money::from_minor(1999, &Currency::USD),
    Money::from_minor(1250, &Currency::USD),
];

assert_eq!(
    refunds.iter().sum::<Option<Money>>(),
    Some(Money::from_minor(3249, &Currency::USD))
);
assert_eq!(refunds.iter().sum::<MoneyBag>().to_string(), "32.49 USD");

// Once the currencies disagree, only the bag still answers
let mixed = [
    Money::from_minor(1999, &Currency::USD),
    Money::from_minor(1250, &Currency::EUR),
];

assert_eq!(
    mixed.iter().sum::<MoneyBag>().to_string(),
    "12.50 EUR, 19.99 USD"
);
```

Converting between currencies needs exchange rates, which are live data rather
than a standard, so they are out of scope here. Iterating a bag yields each
currency's balance in ISO alphabetic order, which is enough to apply rates of
your own.

## Maintainer

This project is maintained by [Rosa Richter](https://cosmicrose.dev).
For ways to contact her, see her [contact page](https://cosmicrose.dev/contact/).

## Contributing

Questions and contributions are absolutely welcome!
Please [create an issue](https://code.cosmicrose.dev/rosa/lucre/issues/new)
for bugs, feature requests, or questions.

## License

[BSD-2-Clause-Patent](https://spdx.org/licenses/BSD-2-Clause-Patent.html) © Rosa Richter