GuardedInt.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "CoreTypes.h"
#include "Concepts/Integral.h"
#include "HAL/PlatformMath.h"
#include "Misc/AssertionMacros.h"
#include "Templates/Requires.h"
#include <limits>
#include <type_traits>
 
template<UE::CIntegral IntType>
class TGuardedInt
{
private:
    static_assert(std::is_integral_v<IntType>, "Only defined for integer types");
    typedef typename std::make_unsigned_t<IntType> UnsignedType;
 
    static constexpr IntType MinValue = std::numeric_limits<IntType>::min();
    static constexpr IntType MaxValue = std::numeric_limits<IntType>::max();
    static constexpr IntType NumBits = IntType((sizeof(IntType) / sizeof(char)) * 8); // Using sizeof to guess the bit count, ugh.
 
    IntType Value = 0;
    bool bIsValid = false;
 
public:
    [[nodiscard]] TGuardedInt() = default;
 
    template<UE::CIntegral ValueType>
    [[nodiscard]] explicit TGuardedInt(ValueType InValue)
        : Value((IntType)InValue), bIsValid(false)
    {
        if constexpr (std::is_signed_v<ValueType>)
        {
            bIsValid = (InValue >= MinValue && InValue <= MaxValue);
        }
        else
        {
            bIsValid = InValue <= UnsignedType(MaxValue);
        }
    }
 
    [[nodiscard]] TGuardedInt(const TGuardedInt& Other) = default;
 
    TGuardedInt& operator=(const TGuardedInt& Other) = default;
 
    [[nodiscard]] bool IsValid() const
    {
        return bIsValid;
    }
 
    [[nodiscard]] IntType Get(const IntType DefaultValue) const
    {
        return IsValid() ? Value : DefaultValue;
    }
 
    [[nodiscard]] IntType GetChecked(const IntType DefaultValue = 0) const
    {
        checkf(IsValid(), TEXT("Invalid value in TGuardedInt::GetChecked."));
        return Get(DefaultValue);
    }
 
    [[nodiscard]] bool operator ==(const TGuardedInt Other) const
    {
        if (bIsValid != Other.bIsValid)
        {
            return false;
        }
 
        return !bIsValid || Value == Other.Value;
    }
 
    [[nodiscard]] bool operator !=(const TGuardedInt Other) const
    {
        if (bIsValid != Other.bIsValid)
        {
            return true;
        }
 
        return bIsValid && Value != Other.Value;
    }
 
    // There are intentionally no overloads for the ordered comparison operators, because we have
    // to decide what to do about validity as well. Instead, do this.
 
    [[nodiscard]] bool ComparisonValid(const TGuardedInt Other) const 
    {
        return bIsValid && Other.bIsValid;
    }
 
    template<typename ValueType>
    [[nodiscard]] bool ValidAndLessThan(const ValueType Other) const
    {
        TGuardedInt CheckedOther{ Other };
        return ComparisonValid(CheckedOther) && Value < CheckedOther.Value;
    }
 
    template<typename ValueType>
    [[nodiscard]] bool ValidAndLessOrEqual(const ValueType Other) const
    {
        TGuardedInt CheckedOther{ Other };
        return ComparisonValid(CheckedOther) && Value <= CheckedOther.Value;
    }
 
    template<typename ValueType>
    [[nodiscard]] bool ValidAndGreaterThan(const ValueType Other) const
    {
        TGuardedInt CheckedOther{ Other };
        return ComparisonValid(CheckedOther) && Value > CheckedOther.Value;
    }
 
    template<typename ValueType>
    [[nodiscard]] bool ValidAndGreaterOrEqual(const ValueType Other) const
    {
        TGuardedInt CheckedOther{ Other };
        return ComparisonValid(CheckedOther) && Value >= CheckedOther.Value;
    }
 
    template<typename ValueType>
    [[nodiscard]] bool InvalidOrLessThan(const ValueType Other) const
    {
        TGuardedInt CheckedOther{ Other };
        return !ComparisonValid(CheckedOther) || Value < CheckedOther.Value;
    }
 
    template<typename ValueType>
    [[nodiscard]] bool InvalidOrLessOrEqual(const ValueType Other) const
    {
        TGuardedInt CheckedOther{ Other };
        return !ComparisonValid(CheckedOther) || Value <= CheckedOther.Value;
    }
 
    template<typename ValueType>
    [[nodiscard]] bool InvalidOrGreaterThan(const ValueType Other) const
    {
        TGuardedInt CheckedOther{ Other };
        return !ComparisonValid(CheckedOther) || Value > CheckedOther.Value;
    }
 
    template<typename ValueType>
    [[nodiscard]] bool InvalidOrGreaterOrEqual(const ValueType Other) const
    {
        TGuardedInt CheckedOther{ Other };
        return !ComparisonValid(CheckedOther) || Value >= CheckedOther.Value;
    }
 
    // Arithmetic operations
 
    [[nodiscard]] TGuardedInt operator-() const
    {
        if constexpr (std::is_signed_v<IntType>)
        {
            // Unary negation (for two's complement) overflows iff the operand is MinValue.
            return (bIsValid && Value > MinValue) ? TGuardedInt(-Value) : TGuardedInt();
        }
        else
        {
            // Negating anything but zero overflows unsigned integers.
            return (bIsValid && Value == 0) ? TGuardedInt(-Value) : TGuardedInt();
        }
    }
 
    [[nodiscard]] TGuardedInt operator +(const TGuardedInt Other) const
    {
        // Any sum involving an invalid value is invalid.
        if (!bIsValid || !Other.bIsValid)
        {
            return TGuardedInt();
        }
 
        IntType Result;
        return FPlatformMath::AddAndCheckForOverflow<IntType>(Value, Other.Value, Result)
            ? TGuardedInt(Result)
            : TGuardedInt();
    }
 
    [[nodiscard]] TGuardedInt operator -(const TGuardedInt Other) const
    {
        // Any difference involving an invalid value is invalid.
        if (!bIsValid || !Other.bIsValid)
        {
            return TGuardedInt();
        }
        
        IntType Result;
        return FPlatformMath::SubtractAndCheckForOverflow<IntType>(Value, Other.Value, Result)
            ? TGuardedInt(Result)
            : TGuardedInt();
    }
 
    [[nodiscard]] TGuardedInt operator *(const TGuardedInt Other) const
    {
        // Any product involving invalid values is invalid.
        if (!bIsValid || !Other.bIsValid)
        {
            return TGuardedInt();
        }
 
        IntType Result;
        return FPlatformMath::MultiplyAndCheckForOverflow<IntType>(Value, Other.Value, Result)
            ? TGuardedInt(Result)
            : TGuardedInt();
    }
 
    [[nodiscard]] TGuardedInt operator /(const TGuardedInt Other) const
    {
        // Any quotient involving invalid values is invalid.
        if (!bIsValid || !Other.bIsValid)
        {
            return TGuardedInt();
        }
 
        // Luckily for us, division generally makes things smaller, so there's only two things to watch
        // out for: division by zero is not allowed, and division of MinValue by -1 would give -MinValue
        // which overflows. All other combinations are fine.
        if (Other.Value == 0 || (std::is_signed_v<IntType> && Value == MinValue && Other.Value == -1))
        {
            return TGuardedInt();
        }
 
        return TGuardedInt(Value / Other.Value);
    }
 
    [[nodiscard]] TGuardedInt operator %(const TGuardedInt Other) const
    {
        // Any quotient involving invalid values is invalid.
        if (!bIsValid || !Other.bIsValid)
        {
            return TGuardedInt();
        }
 
        // Same error cases as for division.
        if (Other.Value == 0 || (std::is_signed_v<IntType> && Value == MinValue && Other.Value == -1))
        {
            return TGuardedInt();
        }
 
        return TGuardedInt(Value % Other.Value);
    }
 
    [[nodiscard]] TGuardedInt operator <<(const TGuardedInt Other) const
    {
        // Any shift involving invalid values is invalid.
        if (!bIsValid || !Other.bIsValid)
        {
            return TGuardedInt();
        }
 
        // Left-shifts by negative values or >= the width of the type are always invalid.
        if (Other.Value < 0 || Other.Value >= NumBits)
        {
            return TGuardedInt();
        }
 
        if constexpr (std::is_signed_v<IntType>)
        {
            const int ShiftAmount = Other.Value;
 
            // Once again, taking our overflow-prone expression and using algebra to find
            // a form that doesn't overflow:
            //
            // MinValue <= a * 2^b <= MaxValue
            // <=> MinValue * 2^(-b) <= a <= MaxValue * 2^(-b)
            //
            // The LHS is exact because MinValue is -2^(NumBits - 1) for two's complement,
            // and we just ensured that 0 <= b < NumBits (with b integer).
            //
            // The RHS has a fractional part whereas a is integer; therefore, we can
            // substitute floor(MaxValue * 2^(-b)) for the RHS without changing the result.
            //
            // And that gives us our test!
            return ((MinValue >> ShiftAmount) <= Value && Value <= (MaxValue >> ShiftAmount)) ? TGuardedInt(Value << ShiftAmount) : TGuardedInt();
        }
        else
        {
            return (static_cast<IntType>(Value << Other.Value) >> Other.Value) == Value
                ? TGuardedInt(static_cast<IntType>(Value << Other.Value))
                : TGuardedInt();
        }
    }
 
    [[nodiscard]] TGuardedInt operator >>(const TGuardedInt Other) const
    {
        // Any shift involving invalid values is invalid.
        if (!bIsValid || !Other.bIsValid)
        {
            return TGuardedInt();
        }
 
        // Right-shifts by negative values or >= the width of the type are always invalid.
        if (Other.Value < 0 || Other.Value >= NumBits)
        {
            return TGuardedInt();
        }
 
        // Right-shifts don't have any overflow conditions, so we're good!
        return TGuardedInt(Value >> Other.Value);
    }
 
    [[nodiscard]] TGuardedInt Abs() const
    {
        if (!bIsValid)
        {
            return TGuardedInt();
        }
 
        if constexpr (std::is_signed_v<IntType>)
        {
            // Note the absolute value of MinValue overflows, so this is not completely trivial.
            // Can't just use TGuardedInt(abs(Value)) here!
            return (Value < 0) ? -*this : *this;
        }
        else
        {
            // Abs on unsigned integers is the identity function, and can't overflow.
            return TGuardedInt(Value);
        }
    }
 
    // Mixed-type operators and assignment operators reduce to the base operators systematically
#define UE_GUARDED_SIGNED_INT_IMPL_BINARY_OPERATOR(OP) \
    /* Mixed-type expressions that coerce both operands to guarded ints */ \
    TGuardedInt operator OP(IntType InB) const { return *this OP TGuardedInt(InB); } \
    friend TGuardedInt operator OP(IntType InA, TGuardedInt InB) { return TGuardedInt(InA) OP InB; } \
    /* Assignment operators, direct and mixed */ \
    TGuardedInt& operator OP##=(TGuardedInt InB) { return *this = *this OP InB; } \
    TGuardedInt& operator OP##=(IntType InB) { return *this = *this OP TGuardedInt(InB); } \
    /* end */
 
    UE_GUARDED_SIGNED_INT_IMPL_BINARY_OPERATOR(+)
    UE_GUARDED_SIGNED_INT_IMPL_BINARY_OPERATOR(-)
    UE_GUARDED_SIGNED_INT_IMPL_BINARY_OPERATOR(*)
    UE_GUARDED_SIGNED_INT_IMPL_BINARY_OPERATOR(/)
    UE_GUARDED_SIGNED_INT_IMPL_BINARY_OPERATOR(%)
    UE_GUARDED_SIGNED_INT_IMPL_BINARY_OPERATOR(<<)
    UE_GUARDED_SIGNED_INT_IMPL_BINARY_OPERATOR(>>)
 
#undef UE_GUARDED_SIGNED_INT_IMPL_BINARY_OPERATOR
};
 
template<typename SignedType>
using TGuardedSignedInt = TGuardedInt<SignedType>;
 
using FGuardedInt32 = TGuardedInt<int32>;
 
using FGuardedInt64 = TGuardedInt<int64>;