Crate common_traits

common_traits

A collection of traits and dependencies that can be used to write code that is generic over numerical types. It provides also atomic floats implemented using the integer atomic byte with the same number of bits, and support for half precision floats via the crate half.

Additionally, there are a few traits missing from the standard library, such as Sequence, and variants of existing library traits such as Rng and Hash.

Finally, we provide traits for casting between types, such as UpcastableInto, and fast implementation of a few primitives such FastRange and SelectInWord.

Everything is experimental and I’ll change them to my needs, respecting semantic versioning. :)

The point of making this crate public is to be able to discuss this as it covers many core missings from Rust.

The traits in this crate are similar to the ones from num-traits but they are more interconnected, which allows to write generic code (e.g., code mixing a type and its associated atomic type) more easily and with less trait bounds.

The numerical traits dependancy chains is this:

This crate adds emulated atomic floats through fetch_update for the following types:

• f64 as AtomicF64
• f32 as AtomicF32
• half::f16 as AtomicF16
• half::bf16 as AtomicBF16

The crate also contains a couple of extra traits:

• Rng for a generic random number generator.
• Splat to broadcast a smaller type on a larger type, mainly used for SWAR.
• SelectInWord to find the position of the i-th 1 or 0 in words of memory.
• FastRange for faster div, mod, and range operations.
• Sequence, SequenceMut, and SequenceGrowable to abstract over slices and other sequence like types.

Traits for conversion between types are also provided:

• UpcastableInto and UpcastableFrom to cast primitive values which are known to don’t lose precision.

• DowncastableInto and DowncastableFrom to cast primitive values which are known to lose precision.

• CastableInto and CastableFrom to cast primitive values which may or may not lose precision. This is the union of DowncastableInto and UpcastableInto.
• To, to cast primitve values using as.

The difference between Castable and To is that Castable does not allow casting from f32 to u32 for example, because Castable is implemented only between integers and between floats, while To is implemented for all primitive types.

Features

This crate has the following features:

• simd: To enable portable_simd and be able to do generic simd code
• atomic_from_mut: to add the get_mut_slice and from_mut_slice methods
• std: to disable for no_std
• half: to enable support for half::f16 (WORK IN PROGRESS)

Example

Mixed precision generic dot products!

use common_traits::*;

#[inline]
pub fn dot_product<MT: Number, RT: Number, A, B>(a: A, b: B) -> RT
where
    A: Sequence,
    B: Sequence,
    A::Item: To<MT>,
    B::Item: To<MT>,
    MT: To<RT>,
    RT: To<MT>,
{
    // Check compatability of the vectors
    assert_eq!(a.len(), b.len());

    // Compute the dot product
    let mut accum = RT::ZERO;
    for (a, b) in a.iter().zip(b.iter()) {
        accum = (a.to()).mul_add(b.to(), accum.to()).to();
    }

    accum
}

let x: Vec<f32> = vec![1.0, 2.0, 3.0];
let w: Vec<u8> = vec![3, 2, 1];
// compute the dot product between f32 and u8, casting to f64 and
// accumulating as u16
let res: u16 = dot_product::<f64, _, _, _>(&x, &w);
println!("{:?}", res);

Structs

• AtomicBF16
  Atomic half::bf16 based on AtomicU16
• AtomicF16
  Atomic half::f16 based on AtomicU16
• AtomicF32
  Atomic f32 based on AtomicU32
• AtomicF64
  Atomic f64 based on AtomicU64
• False
  BooleanSelector version of false, this is an empty struct used only for type system bounds
• True
  BooleanSelector version of true, this is an empty struct used only for type system bounds

Traits

• AsBytes
  A trait for types that have a fixed-length representation as a sequence of bytes. This includes all standard numerical scalar types.
• Atomic
  Values that can be atomically read and written
• AtomicFiniteRangeNumber
  An atomic finite number type.
• AtomicInteger
  An atomic integer type.
• AtomicNumber
  An atomic number type.
• AtomicSignedInt
  An atomic signed integer type.
• AtomicUnsignedInt
  An atomic unsigned integer type.
• BooleanSelector
  Binary selection trait that make it possible to implement traits differently on disjoint types.
• CastableFrom
  Trait for primitive integers, this is the combination of DowncastableFrom and UpcastableFrom. Prefer using the other two traits, as casting without knowing which value will be bigger might result in hard to find bugs.
• CastableInto
  CastableInto : CastableFrom = Into : From, It’s easier to use to specify bounds on generic variables
• DoubleType
  A trait to access a type with double the number of bits of Self.
• DowncastableFrom
  Trait for primitive integers, the expected behaviour is to truncate the bits in the UnsignedInt to the possibly smaller UnsignedInt size.
• DowncastableInto
  DowncastableInto : DowncastableFrom = Into : From, It’s easier to use to specify bounds on generic variables
• FastRange
  Fast division, modulo reduction, and an alternative operation that maps a number between 0 and n.
• FiniteRangeNumber
  A number that has a Max and a Min.
• Float
  Common operations on floats
• FromBytes
  Traits for types that can be created safely from an array of bytes.
• HalfType
  A trait to access a type with half the number of bits of Self.
• Hash
  The analog of core::hash::Hash but that uses Hash
• Hasher
  An generalization of core::hash::Hasher that doesn’t force the output to be u64
• Integer
  A trait for operations that are shared by signed and unsigned integers.
• IntoAtomic
  A trait for types that have an equivalent atomic type.
• IsAtomic
  A trait with an associated BooleanSelector type specifying whether the type is atomic. It can be used to implement traits differently for atomic and non-atomic types. See the atomic_data example.
• IsNonZero
  A generic trait with an associated boolean, which can be used to do specialization. See the example atomic_data for more information.
• IsSigned
  A trait with an associated BooleanSelector type specifying whether an integer type is signed. It can be used to implement traits differently for signed and unsigned types. See the atomic_data example.
• NonZero
  Non zero variants of primitives types for enum optimizations
• Number
  A trait for operations that are shared by integers and floats.
• Rng
  A generic Random number generator
• RngNext
  Implementation of a specific type generation for a Rng
• SeedableHasher
  An hasher that has extra parameters in initalization
• SelectInWord
  Select the i-th 1-bit or 0-bit in a word of memory.
• Sequence
  A trait for types that can be viewed as a sequence of copiable elements, such as &[T].
• SequenceGrowable
  A trait for types that can be viewed as a growable sequence of copiable elements, such as Vec<T>.
• SequenceMut
  A trait for types that can be viewed as a mutable sequence of copiable elements, such as &mut [T].
• SignedInt
  Signed UnsignedInt common operations
• Splat
  Take a smaller value and broadcast to all the values
• To
  Primitive cast between types using as
• ToBytes
  Traits for types that can be cast to an array of bytes.
• UnsignedInt
  Unsigned UnsignedInt common operations
• UpcastableFrom
  Trait for primitive integers, the expected behaviour for unsigned integers is to zero extend the value, while for signed integers it will sign-extend it to the possibly bigger UnsignedInt size.
• UpcastableInto
  UpcastableInto : UpcastableFrom = Into : From, It’s easier to use to specify bounds on generic variables