Safe integer (e.g. i32
) and floating point
(e.g. f32
) numerics, and numeric concepts.
This namespace contains safe integer types and floating point types.
Safe numeric types:
 Signed integers:
i8
,i16
,i32
,i64
,isize
.  Unsigned integers:
u8
,u16
,u32
,u64
,usize
,uptr
.  Floating point:
f32
,f64
.  Portability helper: [
CInt
]
Additionally, there are Concepts that match against safe numerics, C++ primitive types, and operations with numeric types.
The Subspace library numeric types can interoperate with primitive C++ types, but are safer than primitive C++ types and eliminate many classes of bugs that often lead to security vulnerabilities:
 Integer overflow is not allowed by default (see Overflow behaviour), and will
panic
to terminate the program. Intentional overflow can be achieved through methods likewrapping_add
orsaturating_mul
. TheOverflowInteger
type can be used for a series of potentiallyoverflowing operations and unwraps to an integer value ifandonlyif no overflow has occured.  Integers and floats convert implicitly into each other or into primitive
types only when no data can be lost, otherwise conversions do not
compile. To convert fallibly and observe data loss, use the
TryFrom
concept methods, such asu32::try_from(3_i32)
. To do casting conversions with truncation, useCast
.  No integer promotion. Math on 8bit and 16bit integers will not change their type, unlike primitive types which convert to (signed) int on any math operation.
 No Undefined Behaviour in conversions. Conversions between all numeric types, and between them and primitive types is welldefined for all possible values, unlike conversions between primitive integer and floating point types which can result in Undefined Behaviour.
The numeric types also come with builtin methods to perform common
operations, such as abs
,
pow
, log10
, or
leading_ones
.
Overflow behaviour
The default build configuration will panic on integer overflow in arithmetic
operations (+
, 
, *
, /
, etc). These checks can be disabled by
defining SUS_CHECK_INTEGER_OVERFLOW
to false during compilation. Both
signed and unsigned integers will then overflow by performing wrapping
operations. There is no Undefined Behaviour with signed or unsigned integers
unless going through the unchecked operations explicitly, such as
unchecked_add
.
Division by zero, or overflow in integer division will panic regardless of whether overflow checks are enabled.
Conversions
To explicitly invoke a lossless conversion, use
From
. Use Into
to
constrain inputs in generic code, and sus::into()
to typededuce for conversions. Some lossless conversions are also allowed
to happen implicitly, though explicit conversion is better.
To convert and handle the case where data is lost, use
TryFrom
, or
TryInto
in generic code. Using
T::try_from(U).unwrap()
is a quick way to convert and find out if the
value was out of range, or to terminate on malicious inputs. Or
T::try_from(U).unwrap_or_default()
to convert to the input value or else
to zero.
To convert with truncation/loss of data, like static_cast
, use
sus::cast<T>()
. It can convert between
integers, floats, and enums, for both safe numerics and primitives. See
Casting numeric types for the rules of
conversion through cast
.
Classes

An integer type that handles overflow instead of panicing.

The error type returned when a checked integral type conversion fails.

A 32bit floating point type.

A 64bit floating point type.

A 16bit signed integer.

A 32bit signed integer.

A 64bit signed integer.

An 8bit signed integer.

An addresssized signed integer.

A 16bit unsigned integer.

A 32bit unsigned integer.

A 64bit unsigned integer.

An 8bit unsigned integer.

A pointersized unsigned integer.

An addresssized unsigned integer.
Operators


Satisfies the
Rem
concept for floating point values. 
Computes the remainder of
l
divided byr
, also known as the modulo operation. 
Computes the remainder of
l
divided byr
, also known as the modulo operation. 
Performs the bitwise operation
l
ANDr
. 
Performs the bitwise operation
l
ANDr
. 

Satisfies the
Mul
concept for floating point values. 
Computes
l
multiplied byr
. 
Computes
l
multiplied byr
. 

Satisfies the
Add
concept for floating point values. 
Computes
l
summed withr
. 
Computes
l
summed withr
. 

Satisfies the
Sub
concept for floating point values. 
Computes
l
subtracted byr
. 
Computes
l
subtracted byr
. 

Satisfies the
Div
concept for floating point values. 
Computes
l
divided byr
. 
Computes
l
divided byr
. 
Satisfies the
Shl
concept for signed integers. 
Satisfies the
Shl
concept for unsigned integers. 
Satisfies the
PartialOrd
concept for floating point numbers. 

Returns the ordering of
l
andr
for signed integers. 
Returns the ordering of
l
andr
for unsigned integers. 
Satisfies the
Eq
concept for floating point numbers. 

Returns whether
l
andr
are equal for signed integers. 
Returns whether
l
andr
are equal for unsigned integers. 
Satisfies the
Shr
concept for signed integers. 
Satisfies the
Shr
concept for unsigned integers. 
Performs the bitwise operation
l
XORr
. 
Performs the bitwise operation
l
XORr
. 
Performs the bitwise operation
l
ORr
. 
Performs the bitwise operation
l
ORr
.
Concepts













All Subspace numeric integer types. This includes all safe integer types except
uptr
which represents pointers. SeeUnsignedNumeric
andUnsignedPointer
. 
All Subspace pointer integer types. This includes safe integer types that represent pointer values, which is just
uptr
. SeeUnsignedNumeric
andUnsignedPointer
. 



Enum types that are backed by a signed or unsigned value, excluding
enum class
types. 
Enum class (scoped enumeration) types that are backed by a signed or unsigned value.


Signed or unsigned primitive integer types (
char
,int
,unsigned int
,unsigned long
, etc). 






Enum types that are backed by a signed value, excluding
enum class
types. 
Enum class (scoped enumeration) types that are backed by a signed value.

Signed primitive integer types (
signed char
,int
,long
, etc). 


Unsigned Subspace pointer integer types. This is the rest of
Unsigned
that is not included inUnsignedNumeric
, which is justuptr
. 
Enum types that are backed by an unsigned value, excluding
enum class
types. 
Enum class (scoped enumeration) types that are backed by an unsigned value.

Unsigned primitive integer types (
unsigned char
,unsigned int
, etc).