Sanitize sizes to avoid integer overflow. More...

Classes
class	OverflowError
	Error from an integer overflow. More...

Functions
template<typename Size_ , typename Left_ , typename Right_ >
Size_	sum (Left_ left, Right_ right)

template<typename Size_ , typename Left_ , typename Right_ >
Size_	sum_unsafe (Left_ left, Right_ right)

template<typename Size_ , typename Left_ , typename Right_ >
Size_	product (Left_ left, Right_ right)

template<typename Size_ , typename Left_ , typename Right_ >
Size_	product_unsafe (Left_ left, Right_ right)

template<typename Size_ , typename Input_ >
constexpr Size_	cap (Input_ x)

template<typename Size_ , typename Input_ >
Size_	cast (Input_ x)

template<typename Size_ , typename Input_ >
Input_	can_cast (Input_ x)

template<class Container_ , typename Input_ , typename ... Args_>
Container_	create (Input_ x, Args_ &&... args)

template<typename Left_ , typename Right_ >
constexpr bool	is_equal (Left_ l, Right_ r)

template<typename Left_ , typename Right_ >
constexpr bool	is_less_than (Left_ l, Right_ r)

template<typename Left_ , typename Right_ >
constexpr bool	is_greater_than_or_equal (Left_ l, Right_ r)

template<typename Left_ , typename Right_ >
constexpr bool	is_greater_than (Left_ l, Right_ r)

template<typename Left_ , typename Right_ >
constexpr bool	is_less_than_or_equal (Left_ l, Right_ r)

template<typename Size_ , typename First_ , typename Second_ , typename... Remaining_>
Size_	nd_offset (First_ x1, First_ extent1, Second_ x2, Remaining_... remaining)

Detailed Description

Sanitize sizes to avoid integer overflow.

Function Documentation

◆ can_cast()

template<typename Size_ , typename Input_ >

Input_ sanisizer::can_cast ( Input_ x )

Check that x can be cast to the type of the size of a C-style array or STL container. This is useful for chaining together checks without actually doing the cast itself.

Template Parameters

Size_	Integer type to cast to, typically representing some concept of size for an array/container.
Input_	Integer type of the input size.

Parameters

x	Non-negative value to be casted, typically representing the size of an array/container.

Returns: x as its input type. If overflow would occur, an OverflowError is raised.

◆ cap()

template<typename Size_ , typename Input_ >

Size_ sanisizer::cap ( Input_ x )

constexpr

Cap an integer at the largest value of a size type. This is primarily intended for setting appropriate default values of function arguments and class variables.

Template Parameters

Size_	Integer type to return, typically representing some concept of size for an array/container.
Input_	Integer type of the input size.

Parameters

x	Non-negative value to be capped.

Returns: x if it can be represented in Size_, otherwise the maximum value of Size_.

◆ cast()

template<typename Size_ , typename Input_ >

Size_ sanisizer::cast ( Input_ x )

Cast x to the type of the size of a C-style array or STL container. This avoids accidental overflow from an implicit cast when x is used in new or the container's constructor.

Template Parameters

Size_	Integer type to cast to, typically representing some concept of size for an array/container.
Input_	Integer type of the input size.

Parameters

x	Non-negative value to be casted, typically representing the size of an array/container.

Returns: x as a Size_. If overflow would occur, an OverflowError is raised.

◆ create()

template<class Container_ , typename Input_ , typename ... Args_>

Container_ sanisizer::create	(	Input_	x,
		Args_ &&...	args )

Create a new container of a specified size. This protects against overflow when casting the integer size to the container's size type.

Template Parameters

Container_	Container class that accepts the size in the first argument of its constructor.
Input_	Integer type of the input size.
Args_	Further arguments to pass to the container's constructor.

Parameters

x	Non-negative value representing the desired container size.
args	Additional arguments to pass to the `Container_` constructor after the size.

Returns: An instance of the container, constructed to be of size x. If overflow would occur, an OverflowError is raised.

◆ is_equal()

template<typename Left_ , typename Right_ >

bool sanisizer::is_equal	(	Left_	l,
		Right_	r )

constexpr

Template Parameters

Left_	Integer type on the left hand side of the comparison.
Right_	Integer type on the right hand side of the comparison.

Parameters

l	Non-negative value on the left hand side of the comparison.
r	Non-negative value on the right hand side of the comparison.

Returns: Whether l is equal to r.

◆ is_greater_than()

template<typename Left_ , typename Right_ >

bool sanisizer::is_greater_than	(	Left_	l,
		Right_	r )

constexpr

Template Parameters

Left_	Integer type on the left hand side of the comparison.
Right_	Integer type on the right hand side of the comparison.

Parameters

l	Non-negative value on the left hand side of the comparison.
r	Non-negative value on the right hand side of the comparison.

Returns: Whether l is greater than r.

◆ is_greater_than_or_equal()

template<typename Left_ , typename Right_ >

bool sanisizer::is_greater_than_or_equal	(	Left_	l,
		Right_	r )

constexpr

Template Parameters

Left_	Integer type on the left hand side of the comparison.
Right_	Integer type on the right hand side of the comparison.

Parameters

l	Non-negative value on the left hand side of the comparison.
r	Non-negative value on the right hand side of the comparison.

Returns: Whether l is greater than or equal to r.

◆ is_less_than()

template<typename Left_ , typename Right_ >

bool sanisizer::is_less_than	(	Left_	l,
		Right_	r )

constexpr

Template Parameters

Left_	Integer type on the left hand side of the comparison.
Right_	Integer type on the right hand side of the comparison.

Parameters

l	Non-negative value on the left hand side of the comparison.
r	Non-negative value on the right hand side of the comparison.

Returns: Whether l is less than r.

◆ is_less_than_or_equal()

template<typename Left_ , typename Right_ >

bool sanisizer::is_less_than_or_equal	(	Left_	l,
		Right_	r )

constexpr

Template Parameters

Left_	Integer type on the left hand side of the comparison.
Right_	Integer type on the right hand side of the comparison.

Parameters

l	Non-negative value on the left hand side of the comparison.
r	Non-negative value on the right hand side of the comparison.

Returns: Whether l is less than or equal to r.

◆ nd_offset()

template<typename Size_ , typename First_ , typename Second_ , typename... Remaining_>

Size_ sanisizer::nd_offset	(	First_	x1,
		First_	extent1,
		Second_	x2,
		Remaining_...	remaining )

Compute offsets for accessing elements in a flattened N-dimensional array (for N > 1). The first dimension is assumed to be the fastest-changing, followed by the second dimension, and so on.

Template Parameters

Size_	Integer type to represent the size of the flattened array.
First_	Integer type to represent the index on or extent of the first dimension. It is assumed that this can be safely cast to `Size_`, as overflow checks should have been performed during array allocation, e.g., via `product()`.
Second_	Integer type to represent the index on or extent of the second dimension. It is assumed that this can be safely cast to `Size_`, as overflow checks should have been performed during array allocation, e.g., via `product()`.
Remaining_	Additional arguments for further dimensions. It is assumed that all types can be safely cast to `Size_`, as overflow checks should have been performed during array allocation, e.g., `product()`.

Parameters

x1	Position on the first dimension.
extent1	Extent of the first dimension.
x2	Position on the second dimension.
remaining	Additional arguments for further dimensions. These should be `(extentP, xQ)` pairs where `extentP` is the extent of the `P`-th dimension and `xQ` is the position on the `Q = P + 1`-th dimension. For example, for a 3-dimensional array, we would expect an `extent2` and `x3` argument.

Returns: Offset into the array for element (x1, x2, ...).

◆ product()

template<typename Size_ , typename Left_ , typename Right_ >

Size_ sanisizer::product	(	Left_	left,
		Right_	right )

Multiply two values, checking for overflow in the output type. This is typically used to compute the size of a flattened N-dimensional array as the product of its dimension extents.

For consistency, this function will also check that each of left and right can be cast to Size_. This ensures that per-dimension indices/extents can be safely represented as Size_ in later steps (e.g., nd_offset()). These checls are necessary as the product may fit in Size_ but not each of left and right if either is equal to zero.

Template Parameters

Size_	Integer type representing some concept of size for an array/container.
Left_	Integer type of the left hand side value.
Right_	Integer type of the right hand side value.

Parameters

left	Non-negative value to multiply.
right	Non-negative value to multiply.

Returns: Product of left and right as a Size_. If overflow would occur, an OverflowError is raised.

◆ product_unsafe()

template<typename Size_ , typename Left_ , typename Right_ >

Size_ sanisizer::product_unsafe	(	Left_	left,
		Right_	right )

Unsafe version of product() that casts its arguments to Size_ but does not check for overflow. This is more efficent if it is known that the product will not overflow, e.g., from previous calls to product() with larger values.

Template Parameters

Size_	Integer type representing some concept of size for an array/container.
Left_	Integer type of the left hand side value.
Right_	Integer type of the right hand side value.

Parameters

left	Non-negative value to multiply.
right	Non-negative value to multiply.

Returns: Product of left and right as a Size_.

◆ sum()

template<typename Size_ , typename Left_ , typename Right_ >

Size_ sanisizer::sum	(	Left_	left,
		Right_	right )

Add two values, checking for overflow in the output type. This is typically used to compute the size of an array that is a concatenation of smaller arrays.

Template Parameters

Size_	Integer type representing some concept of size for an array/container.
Left_	Integer type of the left hand side value.
Right_	Integer type of the right hand side value.

Parameters

left	Non-negative value to add.
right	Non-negative value to add.

Returns: Sum of left and right as a Size_. If overflow would occur, an OverflowError is raised.

◆ sum_unsafe()

template<typename Size_ , typename Left_ , typename Right_ >

Size_ sanisizer::sum_unsafe	(	Left_	left,
		Right_	right )

Unsafe version of sum() that casts its arguments to Size_ but does not check for overflow. This is more efficent if it is known that the sum will not overflow, e.g., from previous calls to sum() with larger values.

Template Parameters

Size_	Integer type representing some concept of size for an array/container.
Left_	Integer type of the left hand side value.
Right_	Integer type of the right hand side value.

Parameters

left	Non-negative value to add.
right	Non-negative value to add.

Returns: Sum of left and right as a Size_.

Classes

Functions

Detailed Description

Function Documentation

◆ can_cast()

◆ cap()

◆ cast()

◆ create()

◆ is_equal()

◆ is_greater_than()

◆ is_greater_than_or_equal()

◆ is_less_than()

◆ is_less_than_or_equal()

◆ nd_offset()

◆ product()

◆ product_unsafe()

◆ sum()

◆ sum_unsafe()