fast_posit/posit/convert/
mod.rs

1use super::*;
2
3// TODO add examples to docs after the impls (for ints, etc) are done
4
5/// Used to do value-to-value conversions that consume the input and **round according to the posit
6/// standard**. It is the reciprocal of [`RoundInto`].
7///
8/// The interface is identical to the standard [`From`], but the conversion is not necessarily
9/// lossless, and may round if necessary. "Rounding" in this crate stands for the [definition in
10/// the posit standard]; in short:
11///
12///   - If the value is greater in absolute value than the biggest posit, round to it.
13///   - If the value is smaller in absolute value than the smallest positive posit, round to it.
14///   - Otherwise, round to the nearest bit pattern, or in case of a tie, to the even bit pattern.
15///
16/// For the exact rules, consult the documentation for specific implementations of [`RoundFrom`].
17///
18/// For more information, refer to the documentation of [`From`]. The same guidelines apply: prefer
19/// implementing [`RoundFrom`] over [`RoundInto`] because implementing [`RoundFrom`] automatically
20/// provides one with an implementation of[`RoundInto`], and prefer using [`RoundInto`] over
21/// [`RoundFrom`] in when specifying trait bounds on a generic function. There's also a blanket
22/// implementation of `RoundFrom<T> for T`.
23///
24/// [definition in the posit standard]: https://posithub.org/docs/posit_standard-2.pdf#section.4
25pub trait RoundFrom<T> {
26  /// Converts to this type from the input type, [rounding according to the posit standard] if
27  /// necessary (round to nearest, ties to even, never over- or under-flow).
28  ///
29  /// This is a rounding conversion that is specified in the posit standard; if you're looking for
30  /// the usual Rust-y conversions ([`Into`] if exact, [`TryInto`] if fallible), use those
31  /// traits instead.
32  ///
33  /// [rounding according to the posit standard]: https://posithub.org/docs/posit_standard-2.pdf#section.4
34  #[must_use]
35  fn round_from(value: T) -> Self;
36}
37
38/// Used to do value-to-value conversions that consume the input and **round according to the posit
39/// standard**. It is the reciprocal of [`RoundFrom`].
40///
41/// The interface is identical to the standard [`Into`], but the conversion is not necessarily
42/// lossless, and may round if necessary. "Rounding" in this crate stands for the [definition in
43/// the posit standard]:
44///
45///   - If the value is greater in absolute value than the biggest posit, round to it.
46///   - If the value is smaller in absolute value than the smallest positive posit, round to it.
47///   - Otherwise, round to the nearest bit pattern, or in case of a tie, to the even bit pattern.
48///
49/// For more information, refer to the documentation of [`Into`]. The same guidelines apply: prefer
50/// implementing [`RoundFrom`] over [`RoundInto`] because implementing [`RoundFrom`] automatically
51/// provides one with an implementation of[`RoundInto`], and prefer using [`RoundInto`] over
52/// [`RoundFrom`] in when specifying trait bounds on a generic function. There's also a blanket
53/// implementation of `RoundInto<T> for T`.
54///
55/// [definition in the posit standard]: https://posithub.org/docs/posit_standard-2.pdf#section.4
56pub trait RoundInto<T> {
57  /// Converts this type into the (usually inferred) input type, [rounding according to the posit
58  /// standard] if necessary (round to nearest, ties to even, never over- or under-flow).
59  ///
60  /// This is a rounding conversion that is specified in the posit standard; if you're looking for
61  /// the usual Rust-y conversions ([`Into`] if exact, [`TryInto`] if fallible), use those
62  /// traits instead.
63  ///
64  /// [rounding according to the posit standard]: https://posithub.org/docs/posit_standard-2.pdf#section.4
65  #[must_use]
66  fn round_into(self) -> T;
67}
68
69impl<T> RoundFrom<T> for T {
70  fn round_from(value: T) -> Self {
71    value
72  }
73}
74
75impl<T, U> RoundInto<U> for T where U: RoundFrom<T> {
76  fn round_into(self) -> U {
77    U::round_from(self)
78  }
79}
80
81mod float;
82mod int;
fast_posit/posit/convert/mod.rs

fast_posit/posit/convert/
mod.rs
