Crate common_traits
source ·Expand description
§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
asAtomicF64
f32
asAtomicF32
half::f16
asAtomicF16
half::bf16
asAtomicBF16
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
, andSequenceGrowable
to abstract over slices and other sequence like types.
Traits for conversion between types are also provided:
UpcastableInto
andUpcastableFrom
to cast primitive values which are known to don’t lose precision.
DowncastableInto
andDowncastableFrom
to cast primitive values which are known to lose precision.
CastableInto
andCastableFrom
to cast primitive values which may or may not lose precision. This is the union ofDowncastableInto
andUpcastableInto
.To
, to cast primitve values usingas
.
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 enableportable_simd
and be able to do generic simd codeatomic_from_mut
: to add theget_mut_slice
andfrom_mut_slice
methodsstd
: to disable forno_std
half
: to enable support forhalf::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§
- Atomic
half::bf16
based onAtomicU16
BooleanSelector
version offalse
, this is an empty struct used only for type system boundsBooleanSelector
version oftrue
, this is an empty struct used only for type system bounds
Traits§
- A trait for types that have a fixed-length representation as a sequence of bytes. This includes all standard numerical scalar types.
- Values that can be atomically read and written
- An atomic finite number type.
- An atomic integer type.
- An atomic number type.
- An atomic signed integer type.
- An atomic unsigned integer type.
- Binary selection trait that make it possible to implement traits differently on disjoint types.
- Trait for primitive integers, this is the combination of
DowncastableFrom
andUpcastableFrom
. Prefer using the other two traits, as casting without knowing which value will be bigger might result in hard to find bugs. CastableInto : CastableFrom = Into : From
, It’s easier to use to specify bounds on generic variables- A trait to access a type with double the number of bits of Self.
- Trait for primitive integers, the expected behaviour is to truncate the bits in the UnsignedInt to the possibly smaller UnsignedInt size.
DowncastableInto : DowncastableFrom = Into : From
, It’s easier to use to specify bounds on generic variables- Fast division, modulo reduction, and an alternative operation that maps a number between 0 and
n
. - A number that has a Max and a Min.
- Common operations on floats
- Traits for types that can be created safely from an array of bytes.
- A trait to access a type with half the number of bits of Self.
- The analog of
core::hash::Hash
but that usesHash
- An generalization of
core::hash::Hasher
that doesn’t force the output to beu64
- A trait for operations that are shared by signed and unsigned integers.
- A trait for types that have an equivalent atomic type.
- 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 theatomic_data
example. - A generic trait with an associated boolean, which can be used to do specialization. See the example
atomic_data
for more information. - 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 theatomic_data
example. - Non zero variants of primitives types for enum optimizations
- A trait for operations that are shared by integers and floats.
- A generic Random number generator
- Implementation of a specific type generation for a Rng
- An hasher that has extra parameters in initalization
- Select the i-th 1-bit or 0-bit in a word of memory.
- A trait for types that can be viewed as a sequence of copiable elements, such as
&[T]
. - A trait for types that can be viewed as a growable sequence of copiable elements, such as
Vec<T>
. - A trait for types that can be viewed as a mutable sequence of copiable elements, such as
&mut [T]
. - Signed UnsignedInt common operations
- Take a smaller value and broadcast to all the values
- Primitive cast between types using
as
- Traits for types that can be cast to an array of bytes.
- Unsigned UnsignedInt common operations
- 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 : UpcastableFrom = Into : From
, It’s easier to use to specify bounds on generic variables