#numeric

no-std common_traits

Traits to write generic functions on different numeric types, with atomic support, and other features

34 releases (10 breaking)

0.11.0 Jun 14, 2024
0.10.2 Feb 3, 2024
0.10.0 Oct 11, 2023
0.7.0 Jul 31, 2023
0.2.4 Feb 9, 2023

#39 in Math

Download history 201/week @ 2024-08-12 250/week @ 2024-08-19 290/week @ 2024-08-26 338/week @ 2024-09-02 279/week @ 2024-09-09 465/week @ 2024-09-16 395/week @ 2024-09-23 647/week @ 2024-09-30 386/week @ 2024-10-07 338/week @ 2024-10-14 439/week @ 2024-10-21 474/week @ 2024-10-28 753/week @ 2024-11-04 795/week @ 2024-11-11 475/week @ 2024-11-18 445/week @ 2024-11-25

2,508 downloads per month
Used in 11 crates (6 directly)

Apache-2.0

230KB
4.5K SLoC

common_traits

downloads dependents GitHub CI license Latest version Documentation

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, variants of existing library traits such as [Rng] and Hash, and macros like invariant.

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. :)

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>,
{
    // Ensure compatability of the vectors
    invariant_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);

Numerical traits at a glance

The numerical traits dependancy chains is the following. Black arcs represent the traits dependancies, the blu arcs represent the possibility to access an associated type implementing that trait.

Why?

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 (the blue arcs in the previous graph), which allows to write generic code (e.g., code mixing a type and its associated atomic type) more easily and with less trait bounds.

Summary

An highlight of common_traits most noteworthy features.

Macros

This crate adds the following macros, invariant, invariant_eq, invariant_ne which are similar to the std debug_assert macros, which get checked during debug runs and get replaced with an unreachable_unchecked on release builds.

Structs

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

Numerical Traits

This crate provides the following traits for numerical types:

  • Number Something that can be added, subtracted, multiplied, divided and has a Zero and a One.
  • FiniteRangeNumber a Number which has a Minimum and a Maximum.
  • Float float numbers.
  • Integer an integer number represented as a sequence of bits.
  • SignedInt a signed integer represented in 2-complement.
  • UnsignedInt an unsigned integer.

Atomic Numerical Traits

There are two main traits for working with atomic values:

  • Atomic for values that can be read and written atomically.
  • IntoAtomic for values that can be converted into atomic types.

Each numerical trait has an atomic equivalent:

Miscellaneous Traits

The crate also contains a couple of extra traits:

Conversion traits

Traits for conversion between types are also provided:

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 (Experimental)

Dependencies

~0.5–1MB
~23K SLoC