Struct Transform 

pub struct Transform { /* private fields */ }

A small helper struct which represents a 1 dimensional affine transformation from a signed 64 bit space A, to a signed 64 bit space B. Conceptually, this is the function…

f(a) = b = (a * scale) + offset

Internally, however, the exact function used is

f(a) = b = (((a - A_offset) * B_scale) / A_scale) + B_offset

Where the offsets involved are 64 bit signed integers, and the scale factors are 32 bit unsigned integers.

Overflow/Underflow saturation behavior is as follows. The transformation operation is divided into three stages.

1. Offset by A_offset
2. Scale by (B_scale / A_scale)
3. Offset by B_offset

Each stage is saturated independently. That is to say, if the result of stage #1 is clamped at int64::min, this is the input value which will be fed into stage #2. The calculations are not done with infinite precision and then clamped at the end.

TODO(johngro): Reconsider this. Clamping at intermediate stages can make it more difficult to understand that saturation happened at all, and might be important to a client. It may be better to either signal explicitly that this happened, or to extend the precision of the operation in the rare slow path so that saturation behavior occurs only at the end of the op, and produces a correct result if the transform would have saturated at an intermediate step, but got brought back into range by a subsequent operation.

Saturation is enabled by default, but may be disabled by choosing the Saturate::No form of Apply/ApplyInverse. When saturation behavior is disabled, the results of a transformation where over/underflow occurs at any stage is undefined.

Implementations

impl Transform

pub const fn const_default() -> Self

Returns the identity Transform (f(a) = a).

pub const fn new(a_offset: i64, b_offset: i64, ratio: Ratio) -> Self

Constructs a new Transform.

pub const fn new_linear(ratio: Ratio) -> Self

pub const fn invertible(&self) -> bool

pub const fn a_offset(&self) -> i64

pub const fn b_offset(&self) -> i64

pub const fn ratio(&self) -> Ratio

pub const fn numerator(&self) -> u32

pub const fn denominator(&self) -> u32

pub const fn inverse(&self) -> Self

pub fn apply_static<const SATURATE: bool>( a_offset: i64, b_offset: i64, ratio: Ratio, val: i64, ) -> i64

pub fn apply_inverse_static<const SATURATE: bool>( a_offset: i64, b_offset: i64, ratio: Ratio, val: i64, ) -> i64

pub fn apply<const SATURATE: bool>(&self, val: i64) -> i64

pub fn apply_inverse<const SATURATE: bool>(&self, val: i64) -> i64

pub fn compose(bc: &Transform, ab: &Transform, exact: Exact) -> Transform

Trait Implementations

impl Clone for Transform

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Transform

impl Debug for Transform

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Transform

fn default() -> Self

Returns the “default value” for a type.

impl Eq for Transform

impl FromBytes for Transform

where i64: FromBytes, Ratio: FromBytes,

fn read_from_bytes(source: &[u8]) -> Result<Self, SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the given source.

fn read_from_prefix( source: &[u8], ) -> Result<(Self, &[u8]), SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the prefix of the given source.

fn read_from_suffix( source: &[u8], ) -> Result<(&[u8], Self), SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the suffix of the given source.

impl FromZeros for Transform

where i64: FromZeros, Ratio: FromZeros,

fn zero(&mut self)

Overwrites self with zeros.

fn new_zeroed() -> Self

where Self: Sized,

Creates an instance of Self from zeroed bytes.

impl Immutable for Transform

where i64: Immutable, Ratio: Immutable,

impl IntoBytes for Transform

where i64: IntoBytes, Ratio: IntoBytes, (): PaddingFree<Self, { _ }>,

fn as_bytes(&self) -> &[u8]

where Self: Immutable,

Gets the bytes of this value.

fn as_mut_bytes(&mut self) -> &mut [u8]

where Self: FromBytes,

Gets the bytes of this value mutably.

fn write_to(&self, dst: &mut [u8]) -> Result<(), SizeError<&Self, &mut [u8]>>

where Self: Immutable,

Writes a copy of self to dst.

fn write_to_prefix( &self, dst: &mut [u8], ) -> Result<(), SizeError<&Self, &mut [u8]>>

where Self: Immutable,

Writes a copy of self to the prefix of dst.

fn write_to_suffix( &self, dst: &mut [u8], ) -> Result<(), SizeError<&Self, &mut [u8]>>

where Self: Immutable,

Writes a copy of self to the suffix of dst.

impl Mul for Transform

Composes two timeline functions B->C and A->B producing A->C.

Panics on loss of precision.

type Output = Transform

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self::Output

Performs the * operation.

impl PartialEq for Transform

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Transform

impl TryFromBytes for Transform

where i64: TryFromBytes, Ratio: TryFromBytes,

fn try_read_from_bytes( source: &[u8], ) -> Result<Self, ConvertError<!, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: Sized,

Attempts to read the given source as a Self.

fn try_read_from_prefix( source: &[u8], ) -> Result<(Self, &[u8]), ConvertError<!, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: Sized,

Attempts to read a Self from the prefix of the given source.

fn try_read_from_suffix( source: &[u8], ) -> Result<(&[u8], Self), ConvertError<!, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: Sized,

Attempts to read a Self from the suffix of the given source.