no-std fixed-point-math

Fixed point math support

2 unstable releases

0.1.0 Dec 11, 2023
0.0.2 Jan 18, 2023
0.0.1 Jan 16, 2023

MIT license

19KB
354 lines

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 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:

[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:

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:

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.

No runtime deps