# 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`

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§

- Atomic
`half::bf16`

based on`AtomicU16`

`BooleanSelector`

version of`false`

, this is an empty struct used only for type system bounds`BooleanSelector`

version of`true`

, 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`

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 : 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 uses`Hash`

- An generalization of
`core::hash::Hasher`

that doesn’t force the output to be`u64`

- 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 the`atomic_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 the`atomic_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