TGuardedInt

Navigation

API > API/Runtime > API/Runtime/Core > API/Runtime/Core/Math

References

Syntax

template<typename IntType>  
class TGuardedInt  
Copy full snippet

template<typename IntType> class TGuardedInt

Remarks

Overflow- and error-checked integer. For integer arithmetic on data from untrusted sources (like imported files), especially when doing size computations. Also checks for division by zero and invalid shift amounts.

You're not meant to use this directly. Use FGuardedInt32 or FGuardedInt64 (defined below). A typical use case would be:

FGuardedInt64 NumBytes = FGuardedInt32(Width) * Height * BytesPerPixel; if (NumBytes.InvalidOrGreaterThan(SizeLimit)) { // Report error. } int64 NumBytesValidated = NumBytes.GetValue();

This is a template meant to be instantiated on top of regular basic integer types. The code is written so the logic is integer-size agnostic and uses just regular C++ arithmetic operations. It is assumed to run on a two's complement integer platform (which is all we support, and as of C++20 is contractual). You should generally use the specializations FGuardedInt32 and FGuardedInt64 below.

Checked integers keep both the integer value and a "valid" flag. Default-constructed guarded ints are invalid, and guarded integers constructed from an integer value are valid and hold that value. Guarded integers are somewhat analogous to a TOptional in semantics, and borrow some of the function names.

The main feature of guarded integers is that all arithmetic on them is overflow-checked. Any arithmetic involving guarded integers results in a guarded integer, and any arithmetic involving invalid values, or arithmetic resulting in overflows or other errors (such as division by zero) likewise results in an invalid value. The idea is that integer arithmetic using guarded integers should be possible to write very straightforwardly and without having to consider any of these special cases; if any error occurred along the way, the result will be invalid. These invalid values can then be checked for and handled right when the result is converted back to a regular integer.

Some compilers provide built-ins for overflow-checked integer arithmetic for some types. We could eventually use this (it's especially interesting for multiplications, since our current overflow-checking algorithm is fairly expensive), but a big benefit of the current approach is that it uses nothing but regular arithmetic and is type-agnostic. In particular, this makes it possible to check this implementation exhaustively against a known-good reference for small integer types such as int8. It is much trickier and more subtle to do good testing for larger integer types where that brute-force approach is not practical. As-is, the current approach is not the fastest, but it's not presently intended to be used in contexts where speed of arithmetic operations is a major concern.

Constructors

Functions

Operators

Typedefs

Constants