Fixed-point numbers

The fixed crate provides fixed-point numbers. Currently it uses the typenum crate for the fractional bit count; it is planned to move to const generics when they are implemented by the Rust compiler.

The crate provides the following types:

All fixed-point numbers can have `Frac` fractional bits, where `Frac` can have any value from 0 up to and including the size of the number in bits. When `Frac` is 0, the fixed-point number behaves like an integer. When `Frac` is equal to the number of bits, the value of the fixed-point number lies in the range −0.5 ≤ x < 0.5 for signed fixed-point numbers, and in the range 0 ≤ x < 1 for unsigned fixed-point numbers.

All lossless infallible conversions between fixed-point numbers and numeric primitives are implemented. That is, you can use `From` or `Into` for the conversions that always work without losing any bits.

Quick examples

```// 20 integer bits, 12 fractional bits
use fixed::types::I20F12;

// 19/3 = 6 1/3
let six_and_third = I20F12::from_int(19) / 3;
// four decimal digits for 12 binary digits
assert_eq!(six_and_third.to_string(), "6.3333");
// find the ceil and convert to i32
assert_eq!(six_and_third.ceil().to_int::<i32>(), 7);
// we can also compare directly to integers
assert_eq!(six_and_third.ceil(), 7);```

The type `I20F12` is a 32-bit fixed-point signed number with 20 integer bits and 12 fractional bits. It is an alias to `FixedI32<frac::U12>`. The unsigned counterpart would be `U20F12`. Aliases are provided for all combinations of integer and fractional bits adding up to a total of eight, 16, 32, 64 or 128 bits.

```// −8 ≤ I4F4 < 8 with steps of 1/16 (about 0.06)
use fixed::types::I4F4;
let a = I4F4::from_int(1);
// multiplication and division by integers is possible
let ans1 = a / 5 * 17;
// 1 / 5 × 17 = 3 2/5 (3.4), but we get 3 3/16 (3.19)
assert_eq!(ans1, I4F4::from_bits((3 << 4) + 3));
assert_eq!(ans1.to_string(), "3.19");

// −8 ≤ I4F12 < 8 with steps of 1/4096 (about 0.0002)
use fixed::types::I4F12;
let wider_a = I4F12::from(a);
let wider_ans = wider_a / 5 * 17;
let ans2 = I4F4::from_fixed(wider_ans);
// now the answer is the much closer 3 6/16 (3.38)
assert_eq!(ans2, I4F4::from_bits((3 << 4) + 6));
assert_eq!(ans2.to_string(), "3.38");```

The second example shows some precision and conversion issues. The low precision of `a` means that `a / 5` is 3⁄16 instead of 1⁄5, leading to an inaccurate result `ans1` = 3 3⁄16 (3.19). With a higher precision, we get `wider_a / 5` equal to 819⁄4096, leading to a more accurate intermediate result `wider_ans` = 3 1635⁄4096. When we convert back to four fractional bits, we get `ans2` = 3 6⁄16 (3.38).

Note that we can convert from `I4F4` to `I4F12` using `From`, as the target type has the same number of integer bits and a larger number of fractional bits. Converting from `I4F12` to `I4F4` cannot use `From` as we have less fractional bits, so we use `from_fixed` instead.

Using the fixed crate

The fixed crate is available on crates.io. To use it in your crate, add it as a dependency inside Cargo.toml:

``````[dependencies]
fixed = "0.3.2"
``````

If you are using the 2015 Rust edition, you also need to declare it by adding this to your crate root (usually lib.rs or main.rs):

`extern crate fixed;`

The fixed crate requires rustc version 1.28.0 or later.

Optional features

The fixed crate has two optional feature:

1. `f16`, disabled by default. This provides conversion to/from `f16`. This features requires the half crate.
2. `serde`, disabled by default. This provides serialization support for the fixed-point types. This feature requires the serde crate.

To enable features, you can add the dependency like this to Cargo.toml:

``````[dependencies.fixed]
version = "0.3.2"
features = ["f16", "serde"]
``````

This crate is free software: you can redistribute it and/or modify it under the terms of either

 FixedI8 An eight-bit fixed-point signed integer with `Frac` fractional bits. FixedI16 A 16-bit fixed-point signed integer with `Frac` fractional bits. FixedI32 A 32-bit fixed-point signed integer with `Frac` fractional bits. FixedI64 A 64-bit fixed-point signed integer with `Frac` fractional bits. FixedI128 A 128-bit fixed-point signed integer with `Frac` fractional bits. FixedU8 An eight-bit fixed-point unsigned integer with `Frac` fractional bits. FixedU16 A 16-bit fixed-point unsigned integer with `Frac` fractional bits. FixedU32 A 32-bit fixed-point unsigned integer with `Frac` fractional bits. FixedU64 A 64-bit fixed-point unsigned integer with `Frac` fractional bits. FixedU128 A 128-bit fixed-point unsigned integer with `Frac` fractional bits. Wrapping Provides intentionally wrapped arithmetic on fixed-point numbers.