# Fixed-point numbers

The fixed crate provides fixed-point numbers.

These types can have `Frac` fractional bits, where 0 ≤ `Frac` ≤ n and n is the total number of bits. When `Frac` = 0, the fixed-point number behaves like an n-bit integer. When `Frac` = n, the value x lies in the range −0.5 ≤ x < 0.5 for signed numbers, and in the range 0 ≤ x < 1 for unsigned numbers.

Currently the typenum crate is used for the fractional bit count `Frac`; it is planned to move to const generics when they are supported by the Rust compiler.

The main features are

• Representation of fixed-point numbers up to 128 bits wide.
• Conversions between fixed-point numbers and numeric primitives.
• Comparisons between fixed-point numbers and numeric primitives.
• Parsing from strings in decimal, binary, octal and hexadecimal.
• Display as decimal, binary, octal and hexadecimal.
• Arithmetic and logic operations.

This crate does not provide general analytic functions.

• No algebraic functions are provided, for example no `sqrt` or `pow`.
• No trigonometric functions are provided, for example no `sin` or `cos`.
• No other transcendental functions are provided, for example no `log` or `exp`.

The conversions supported cover the following cases.

## Quick examples

```use fixed::types::I20F12;

// 19/3 = 6 1/3
let six_and_third = I20F12::from_num(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_num::<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<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.

```use fixed::types::{I4F4, I4F12};

// −8 ≤ I4F4 < 8 with steps of 1/16 (~0.06)
let a = I4F4::from_num(1);
// multiplication and division by integers are possible
let ans1 = a / 5 * 17;
// 1 / 5 × 17 = 3 2/5 (3.4), but we get 3 3/16 (~3.2)
assert_eq!(ans1, I4F4::from_bits((3 << 4) + 3));
assert_eq!(ans1.to_string(), "3.2");

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

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.2). 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.4).

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_num` 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.5.0"
``````

The fixed crate requires rustc version 1.39.0 or later.

## Optional features

The fixed crate has three optional feature:

1. `az`, disabled by default. This implements the cast traits provided by the az crate.
2. `f16`, disabled by default. This provides conversion to/from `f16` and `bf16`. This features requires the half crate.
3. `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.5.0"
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 number with `Frac` fractional bits. FixedI16 A 16-bit fixed-point signed number with `Frac` fractional bits. FixedI32 A 32-bit fixed-point signed number with `Frac` fractional bits. FixedI64 A 64-bit fixed-point signed number with `Frac` fractional bits. FixedI128 A 128-bit fixed-point signed number with `Frac` fractional bits. FixedU8 An eight-bit fixed-point unsigned number with `Frac` fractional bits. FixedU16 A 16-bit fixed-point unsigned number with `Frac` fractional bits. FixedU32 A 32-bit fixed-point unsigned number with `Frac` fractional bits. FixedU64 A 64-bit fixed-point unsigned number with `Frac` fractional bits. FixedU128 A 128-bit fixed-point unsigned number with `Frac` fractional bits. ParseFixedError An error which can be returned when parsing a fixed-point number. Wrapping Provides intentionally wrapped arithmetic on fixed-point numbers.