62 releases (31 stable)
2.0.0alpha.25.1  Feb 6, 2024 

2.0.0alpha.12 

2.0.0alpha.11 

2.0.0alpha.8 

0.1.4  Nov 29, 2018 
#1381 in Math
58,445 downloads per month
Used in 203 crates
(79 directly)
1.5MB
28K
SLoC
Fixedpoint numbers
Alpha: This is an alpha release of the new major version 2.0.0 that makes
use of const generics instead of the typenum
crate. This version requires the nightly
compiler with the generic_const_exprs
feature enabled. The stable version
2.0.0 itself will not be released before the generic_const_exprs
feature is
stabilized. See the documentation for porting from version 1 to version 2.
The fixed crate provides fixedpoint numbers.
FixedI8
andFixedU8
are eightbit fixedpoint numbers.FixedI16
andFixedU16
are 16bit fixedpoint numbers.FixedI32
andFixedU32
are 32bit fixedpoint numbers.FixedI64
andFixedU64
are 64bit fixedpoint numbers.FixedI128
andFixedU128
are 128bit fixedpoint numbers.
An nbit fixedpoint number has f = FRAC
fractional
bits, and n − f integer bits. For example,
FixedI32<24>
is a 32bit signed fixedpoint number with
n = 32 total bits, f = 24 fractional bits, and
n − f = 8 integer bits.
FixedI32<0>
behaves like i32
, and
FixedU32<0>
behaves like u32
.
The difference between any two successive representable numbers is constant
throughout the possible range for a fixedpoint number:
Δ = 1/2^{f}. When f = 0, like
in FixedI32<0>
, Δ = 1 because representable
numbers are integers, and the difference between two successive integers is 1.
When f = n, Δ = 1/2^{n}
and the value lies in the range −0.5 ≤ x < 0.5
for signed numbers like FixedI32<32>
, and in the range
0 ≤ x < 1 for unsigned numbers like
FixedU32<32>
.
The main features are
 Representation of binary fixedpoint numbers up to 128 bits wide.
 Conversions between fixedpoint numbers and numeric primitives.
 Comparisons between fixedpoint 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 decimal fixedpoint numbers. For example 0.001 cannot be represented exactly, as it is 1/10^{3}. It is binary fractions like 1/2^{4} (0.0625) that can be represented exactly, provided there are enough fractional bits.
This crate does not provide general analytic functions.
 No algebraic functions are provided, for example no
sqrt
orpow
.  No trigonometric functions are provided, for example no
sin
orcos
.  No other transcendental functions are provided, for example no
log
orexp
.
These functions are not provided because different implementations can have different tradeoffs, for example trading some correctness for speed. Implementations can be provided in other crates.
 The fixedsqrt crate provides the square root operation.
 The cordic crate provides various functions implemented using the CORDIC algorithm.
The conversions supported cover the following cases.
 Infallible lossless conversions between fixedpoint numbers and numeric
primitives are provided using
From
andInto
. These never fail (infallible) and do not lose any bits (lossless).  Infallible lossy conversions between fixedpoint numbers and numeric
primitives are provided using the
LossyFrom
andLossyInto
traits. The source can have more fractional bits than the destination.  Checked lossless conversions between fixedpoint numbers and numeric
primitives are provided using the
LosslessTryFrom
andLosslessTryInto
traits. The source cannot have more fractional bits than the destination.  Checked conversions between fixedpoint numbers and numeric primitives are
provided using the
FromFixed
andToFixed
traits, or using thefrom_num
andto_num
methods and their checked versions.  Additionally,
az
casts are implemented for conversion between fixedpoint numbers and numeric primitives.  Fixedpoint numbers can be parsed from decimal strings using
FromStr
, and from binary, octal and hexadecimal strings using thefrom_str_binary
,from_str_octal
andfrom_str_hex
methods. The result is rounded to the nearest, with ties rounded to even.  Fixedpoint numbers can be converted to strings using
Display
,Binary
,Octal
,LowerHex
,UpperHex
,LowerExp
andUpperExp
. The output is rounded to the nearest, with ties rounded to even.  All fixedpoint numbers are plain old data, so
bytemuck
bit casting conversions can be used.
What’s new
Version 2.0.0alpha.25.1 news (20240205)
 The crate now requires the nightly compiler with the
generic_const_exprs
feature enabled.  The crate now uses generic constant expressions to specify the number of fractional bits.
 The
Fixed
trait constraints have been relaxed, and the methods which needed the strict constraints have been moved to the subtraitFixedStrict
.  The
INT_NBITS
andFRAC_NBITS
associated constants were replaced withINT_BITS
andFRAC_BITS
which can be negative.  The
Unwrapped
methodsfrom_str_binary
,from_str_octal
andfrom_str_hex
return the value directly instead of aResult
.  The deprecated
F128Bits
struct has been removed. It was replaced byF128
in version 1.18.0.  The deprecated
const_fixed_from_int
macro has been removed. It was replaced by theconst_from_int
method in version 1.20.0.  The deprecated optional features
az
andf16
were removed. These features had no effect, as the functionality they enabled is now always enabled.  The new generic associated type
Fixed
was added to theFixedBits
trait.  The following methods of the
Fixed
trait and of theSaturating
,Wrapping
andUnwrapped
wrappers now have some parameters and return types that can be generic:  The following methods of the
Fixed
trait now have some parameters and return types that can be generic:
Version 1.25.1 news (20240206)
 Bug fix: formatting numbers with
LowerExp
andUpperExp
was producing incorrect output when rounding incremented a zero in the middle of a string, for exampleformat!("{:.2e}", I16F16::lit("9.099"))
.
Version 1.25.0 news (20240205)
 Bug fix: formatting numbers with
LowerExp
andUpperExp
was producing incorrect output for very small numbers, for exampleformat!("{:e}", I16F16::DELTA)
.  Bug fix: formatting numbers with
LowerExp
andUpperExp
was panicking for some cases of positive exponents and small precision, for exampleformat!("{:.1e}", I16F16::from_num(1001))
.  Bug fix: formatting numbers with
LowerExp
andUpperExp
was producing incorrect output when rounding adds a more significant digit, for exampleformat!("{:.1e}", I16F16::lit("0.999"))
.  The experimental
borsh
feature was promoted to an optional feature, and the optional borsh crate dependency was updated to version 1.0.
Other releases
Details on other releases can be found in RELEASES.md.
Quick examples
#![feature(generic_const_exprs)]
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 32bit fixedpoint signed number with 20 integer bits
and 12 fractional bits. It is an alias to FixedI32<12>
. 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.
#![feature(generic_const_exprs)]
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.
Writing fixedpoint constants and values literally
The lit
method, which is available as a const
function, can be used to
parse literals. It supports
 underscores as separators;
 prefixes “
0b
”, “0o
” and “0x
” for binary, octal and hexadecimal numbers;  an optional decimal exponent with separator “
e
” or “E
” for decimal, binary and octal numbers, or with separator “@
” for all supported radices including hexadecimal.
#![feature(generic_const_exprs)]
use fixed::types::I16F16;
// 0.1275e2 is 12.75
const TWELVE_POINT_75: I16F16 = I16F16::lit("0.127_5e2");
// 1.8 hexadecimal is 1.5 decimal, and 18@1 is 1.8
const ONE_POINT_5: I16F16 = I16F16::lit("0x_18@1");
// 12.75 + 1.5 = 14.25
let sum = TWELVE_POINT_75 + ONE_POINT_5;
assert_eq!(sum, 14.25);
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 = "2.0.0alpha.25.1"
This alpha version of the fixed crate requires the nightly compiler with the
generic_const_exprs
feature enabled.
Optional features
The fixed crate has these optional feature:
arbitrary
, disabled by default. This provides the generation of arbitrary fixedpoint numbers from raw, unstructured data. This feature requires the arbitrary crate.borsh
, disabled by default. This implements serialization and deserialization using the borsh crate.serde
, disabled by default. This provides serialization support for the fixedpoint types. This feature requires the serde crate.std
, disabled by default. This is for features that are not possible underno_std
: currently the implementation of theError
trait forParseFixedError
.serdestr
, disabled by default. Fixedpoint numbers are serialized as strings showing the value when using humanreadable formats. This feature requires theserde
and thestd
optional features. With this feature, serialization is only supported for fixedpoint numbers where the number of fractional bits is from zero to the total number of bits. Warning: numbers serialized when this feature is enabled cannot be deserialized when this feature is disabled, and vice versa.
To enable features, you can add the dependency like this to Cargo.toml:
[dependencies.fixed]
features = ["serde"]
version = "2.0.0alpha.25.1"
Experimental optional features
It is not considered a breaking change if the following experimental features are removed. The removal of experimental features would however require a minor version bump. Similarly, on a minor version bump, optional dependencies can be updated to an incompatible newer version.
numtraits
, disabled by default. This implements some traits from the numtraits crate. (The plan is to promote this to an optional feature once the numtraits crate reaches version 1.0.0.)
Porting from version 1 to version 2
To port from version 1 to version 2, the following is required:

Temporary change required until the
generic_const_exprs
feature are stabilized: use the nightly compiler and enable thegeneric_const_exprs
feature using#![feature(generic_const_exprs)]

Use integer literals instead of typenum integer constants, for example
FixedI32<8>
instead ofFixedI32<U8>
. 
The
Fixed
trait constraints have been relaxed, and the methods which needed the strict constraints have been moved to the subtraitFixedStrict
. For code that uses these trait methods,Fixed
should be replaced byFixedStrict
. 
The
FRAC_NBITS
andINT_NBITS
associated constants of typeu32
were replaced byFRAC_BITS
andINT_BITS
of typei32
. 
For the
Unwrapped
wrapper, the methodsfrom_str_binary
,from_str_octal
andfrom_str_hex
return the value directly instead of aResult
. 
The deprecated
F128Bits
struct has been removed. It was replaced byF128
in version 1.18.0 
The deprecated
const_fixed_from_int
macro has been removed. It was replaced by theconst_from_int
method in version 1.20.0. 
The deprecated optional features
az
andf16
were removed. These features had no effect, as their functionality has been unconditionally enabled since version 1.7.0.
License
This crate is free software: you can redistribute it and/or modify it under the terms of either
 the Apache License, Version 2.0 or
 the MIT License
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache License, Version 2.0, shall be dual licensed as above, without any additional terms or conditions.
Dependencies
~0.5–0.8MB
~17K SLoC