Crates.io | fixed |
lib.rs | fixed |
version | 2.0.0-alpha.27.0 |
source | src |
created_at | 2018-08-09 18:02:57.977963 |
updated_at | 2024-03-27 15:47:53.820724 |
description | Fixed-point numbers. |
homepage | |
repository | https://gitlab.com/tspiteri/fixed |
max_upload_size | |
id | 78561 |
size | 1,752,736 |
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 fixed-point numbers.
FixedI8
and FixedU8
are eight-bit fixed-point numbers.FixedI16
and FixedU16
are 16-bit fixed-point numbers.FixedI32
and FixedU32
are 32-bit fixed-point numbers.FixedI64
and FixedU64
are 64-bit fixed-point numbers.FixedI128
and FixedU128
are 128-bit fixed-point numbers.An n-bit fixed-point number has f = FRAC
fractional
bits, and n − f integer bits. For example,
FixedI32<24>
is a 32-bit signed fixed-point 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 fixed-point number:
Δ = 1/2f. 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/2n
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
This crate does not provide decimal fixed-point numbers. For example 0.001 cannot be represented exactly, as it is 1/103. It is binary fractions like 1/24 (0.0625) that can be represented exactly, provided there are enough fractional bits.
This crate does not provide general analytic functions.
pow
.sin
or cos
.log
or
exp
.These functions are not provided because different implementations can have different trade-offs, for example trading some correctness for speed. Implementations can be provided in other crates.
The conversions supported cover the following cases.
From
and Into
. These never fail
(infallible) and do not lose any bits (lossless).LossyFrom
and LossyInto
traits.
The source can have more fractional bits than the destination.LosslessTryFrom
and
LosslessTryInto
traits. The source cannot have more fractional bits than
the destination.FromFixed
and ToFixed
traits, or using the
from_num
and to_num
methods and their checked
versions.az
casts are implemented for conversion between
fixed-point numbers and numeric primitives.FromStr
,
and from binary, octal and hexadecimal strings using the
from_str_binary
, from_str_octal
and from_str_hex
methods. The
result is rounded to the nearest, with ties rounded to even.Display
,
Binary
, Octal
, LowerHex
, UpperHex
, LowerExp
and
UpperExp
. The output is rounded to the nearest, with ties rounded to
even.bytemuck
bit casting
conversions can be used.generic_const_exprs
feature enabled.Fixed
trait constraints have been relaxed. Methods that
required the number of fractional bits to be bounded have been moved to the
new subtrait FixedBoundFrac
.INT_NBITS
and FRAC_NBITS
associated constants were replaced with
INT_BITS
and FRAC_BITS
which can be negative.Unwrapped
methods from_str_binary
,
from_str_octal
and from_str_hex
return the
value directly instead of a Result
.F128Bits
struct has been removed. It was replaced by
F128
in version 1.18.0.const_fixed_from_int
macro has been removed. It was
replaced by the const_from_int
method in version 1.20.0.az
and f16
were removed. These features
had no effect, as the functionality they enabled is now always enabled.Fixed
was added to the
FixedBits
trait.Fixed
trait and of the
Saturating
, Wrapping
and Unwrapped
wrappers now have some parameters and return types that can be generic:
Fixed
trait now have some
parameters and return types that can be generic:
hypot
method was added to all fixed-point numbers, to the
Fixed
trait, and to the Saturating
,
Wrapping
and Unwrapped
wrappers.Fixed
trait:
sqrt
method was added to all fixed-point numbers, to the
Fixed
trait, and to the Saturating
,
Wrapping
and Unwrapped
wrappers.checked_sqrt
method was added to all fixed-point numbers
and to the Fixed
trait.Details on other releases can be found in RELEASES.md.
#![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 32-bit fixed-point 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.
The lit
method, which is available as a const
function, can be used to
parse literals. It supports
0b
”, “0o
” and “0x
” for binary, octal and hexadecimal
numbers;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);
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.0-alpha.27.0"
This alpha version of the fixed crate requires the nightly compiler with the
generic_const_exprs
feature enabled.
The fixed crate has these optional feature:
arbitrary
, disabled by default. This provides the generation of arbitrary
fixed-point 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
fixed-point types. This feature requires the serde crate.std
, disabled by default. This is for features that are not possible under
no_std
: currently the implementation of the Error
trait for
ParseFixedError
.serde-str
, disabled by default. Fixed-point numbers are serialized as
strings showing the value when using human-readable formats. This feature
requires the serde
and the std
optional features. With this feature,
serialization is only supported for fixed-point 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.0-alpha.27.0"
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.
num-traits
, disabled by default. This implements some traits from the
num-traits crate. (The plan is to promote this to an optional feature
once the num-traits crate reaches version 1.0.0.)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 the generic_const_exprs
feature using
#![feature(generic_const_exprs)]
Use integer literals instead of typenum integer constants, for example
FixedI32<8>
instead of
FixedI32<U8>
.
The Fixed
trait constraints have been relaxed. Methods that required the
number of fractional bits to be bounded have been moved to the new subtrait
FixedBoundFrac
. For code that uses these trait methods, Fixed
should
be replaced by FixedBoundFrac
.
The FRAC_NBITS
and INT_NBITS
associated constants of type u32
were replaced by FRAC_BITS
and INT_BITS
of type i32
.
For the Unwrapped
wrapper, the methods from_str_binary
,
from_str_octal
and from_str_hex
return the value
directly instead of a Result
.
The deprecated F128Bits
struct has been removed. It was replaced by
F128
in version 1.18.0
The deprecated const_fixed_from_int
macro has been removed. It was
replaced by the const_from_int
method in version 1.20.0.
The deprecated optional features az
and f16
were removed. These features
had no effect, as their functionality has been unconditionally enabled since
version 1.7.0.
This crate is free software: you can redistribute it and/or modify it under the terms of either
at your option.
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.