fixed-point-math 0.1.0

Fixed point math support
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

# DEPRECATED

This package has been deprecated in favor of https://crates.io/crates/soroban-fixed-point-math and is no longer being maintained. The last supported version was `0.0.2`.

If you would like to use this crate name, please email me (listed in `Cargo.toml`)

## Old README

## fixed-point-math
A light fixed-point math library for Rust. Written specifically to be used in [Soroban](https://soroban.stellar.org/) and other WASM based blockchain environments.

## Safety
This is **experimental software** and is provided on an "as is" and "as available" basis.

We do **not give any warranties** and **will not be liable for any loss** incurred through any use of this codebase.

## Usage
Add this to your `Cargo.toml`:

```toml
[dependencies]
fixed-point-math = "<desired version>"
```

### Examples
Fixed-point math support is currently added to both `i128` and `u64` types. For any supported number, you can perform fixed-point operations like this:

```rust
use fixed_point_math::{STROOP, FixedPoint};

let x: u64 = 1_5000000;
let y: u64 = 2_0000000;
assert_eq!(x.fixed_mul_floor(y, STROOP).unwrap(), 3_0000000);
```

## Overflow
Overflowing results are handled in the same manner as Rust's built-in "checked" math, by returning `None`.

Fixed-point math also deals with phantom overflows, where an intermediary computation overflows but the expected result would be within bounds. This library manages this differently for each supported type:
* i128
    * No extra handling is done. `i128` is large enough to support most computation with 7/9 decimal values. However, its likely 18-decimal math will encounter overflows.
* u64
    * The intermediary computation gets scaled to `u128`, and it is attempted again.

## Acknowledgements
This library was inspired by or directly modified from many sources, primary:
- [Solmate](https://github.com/transmissions11/solmate)
- [OpenZeppelin](https://github.com/OpenZeppelin/openzeppelin-contracts)

## WASM
The WASM target `wasm32-unknown-unknown` is supported.

## Contributions
Contributions are welcome. Please check out the contribution guide (TODO)!

## License
This library is released under the [MIT License](../LICENSE).