Public Member Functions | Protected Member Functions | Protected Attributes | Friends

mozilla::CheckedInt< T > Class Template Reference

Integer wrapper class checking for integer overflow and other errors. More...

#include <CheckedInt.h>

Collaboration diagram for mozilla::CheckedInt< T >:

List of all members.

Public Member Functions

template<typename U >
 CheckedInt (U value)
 Constructs a checked integer with given value.
 CheckedInt ()
 Constructs a valid checked integer with initial value 0.
value () const
PRBool valid () const
template<typename U >
CheckedIntoperator+= (U rhs)
 Adds.
template<typename U >
CheckedIntoperator-= (U rhs)
 Substracts.
template<typename U >
CheckedIntoperator*= (U rhs)
 Multiplies.
template<typename U >
CheckedIntoperator/= (U rhs)
 Divides.
CheckedInt operator- () const
PRBool operator== (const CheckedInt &other) const
CheckedIntoperator++ ()
 prefix ++
CheckedInt operator++ (int)
 postfix ++
CheckedIntoperator-- ()
 prefix --
CheckedInt operator-- (int)
 postfix --

Protected Member Functions

template<typename U >
 CheckedInt (U value, T isValid)

Protected Attributes

mValue
mIsValid

Friends

template<typename U >
CheckedInt< U > operator+ (const CheckedInt< U > &lhs, const CheckedInt< U > &rhs)
template<typename U >
CheckedInt< U > operator- (const CheckedInt< U > &lhs, const CheckedInt< U > &rhs)
template<typename U >
CheckedInt< U > operator* (const CheckedInt< U > &lhs, const CheckedInt< U > &rhs)
template<typename U >
CheckedInt< U > operator/ (const CheckedInt< U > &lhs, const CheckedInt< U > &rhs)

Detailed Description

template<typename T>
class mozilla::CheckedInt< T >

Integer wrapper class checking for integer overflow and other errors.

Parameters:
T the integer type to wrap. Can be any of PRInt8, PRUint8, PRInt16, PRUint16, PRInt32, PRUint32, PRInt64, PRUint64.

This class implements guarded integer arithmetic. Do a computation, check that valid() returns true, you then have a guarantee that no problem, such as integer overflow, happened during this computation.

The arithmetic operators in this class are guaranteed not to crash your app in case of a division by zero.

For example, suppose that you want to implement a function that computes (x+y)/z, that doesn't crash if z==0, and that reports on error (divide by zero or integer overflow). You could code it as follows:

    PRBool compute_x_plus_y_over_z(PRInt32 x, PRInt32 y, PRInt32 z, PRInt32 *result)
    {
        CheckedInt<PRInt32> checked_result = (CheckedInt<PRInt32>(x) + y) / z;
        *result = checked_result.value();
        return checked_result.valid();
    }

Implicit conversion from plain integers to checked integers is allowed. The plain integer is checked to be in range before being casted to the destination type. This means that the following lines all compile, and the resulting CheckedInts are correctly detected as valid or invalid:

    CheckedInt<PRUint8> x(1);   // 1 is of type int, is found to be in range for PRUint8, x is valid
    CheckedInt<PRUint8> x(-1);  // -1 is of type int, is found not to be in range for PRUint8, x is invalid
    CheckedInt<PRInt8> x(-1);   // -1 is of type int, is found to be in range for PRInt8, x is valid
    CheckedInt<PRInt8> x(PRInt16(1000)); // 1000 is of type PRInt16, is found not to be in range for PRInt8, x is invalid
    CheckedInt<PRInt32> x(PRUint32(3123456789)); // 3123456789 is of type PRUint32, is found not to be in range
                                             // for PRInt32, x is invalid

Implicit conversion from checked integers to plain integers is not allowed. As shown in the above example, to get the value of a checked integer as a normal integer, call value().

Arithmetic operations between checked and plain integers is allowed; the result type is the type of the checked integer.

Checked integers of different types cannot be used in the same arithmetic expression.

There are convenience typedefs for all PR integer types, of the following form (these are just 2 examples):

    typedef CheckedInt<PRInt32> CheckedInt32;
    typedef CheckedInt<PRUint16> CheckedUint16;

Constructor & Destructor Documentation

template<typename T >
template<typename U >
mozilla::CheckedInt< T >::CheckedInt ( value,
isValid 
) [inline, protected]
template<typename T >
template<typename U >
mozilla::CheckedInt< T >::CheckedInt ( value  )  [inline]

Constructs a checked integer with given value.

The checked integer is initialized as valid or invalid depending on whether the value is in range.

This constructor is not explicit. Instead, the type of its argument is a separate template parameter, ensuring that no conversion is performed before this constructor is actually called. As explained in the above documentation for class CheckedInt, this constructor checks that its argument is valid.

template<typename T >
mozilla::CheckedInt< T >::CheckedInt (  )  [inline]

Constructs a valid checked integer with initial value 0.


Member Function Documentation

template<typename T >
template<typename U >
CheckedInt< T > & mozilla::CheckedInt< T >::operator*= ( rhs  ) 

Multiplies.

Checks for overflow.

Returns:
self reference
template<typename T >
CheckedInt& mozilla::CheckedInt< T >::operator++ (  )  [inline]

prefix ++

template<typename T >
CheckedInt mozilla::CheckedInt< T >::operator++ ( int   )  [inline]

postfix ++

template<typename T >
template<typename U >
CheckedInt< T > & mozilla::CheckedInt< T >::operator+= ( rhs  ) 

Adds.

Checks for overflow.

Returns:
self reference
template<typename T >
CheckedInt mozilla::CheckedInt< T >::operator- (  )  const [inline]
Returns:
the opposite value. Checks for overflow.
template<typename T >
CheckedInt& mozilla::CheckedInt< T >::operator-- (  )  [inline]

prefix --

template<typename T >
CheckedInt mozilla::CheckedInt< T >::operator-- ( int   )  [inline]

postfix --

template<typename T >
template<typename U >
CheckedInt< T > & mozilla::CheckedInt< T >::operator-= ( rhs  ) 

Substracts.

Checks for overflow.

Returns:
self reference
template<typename T >
template<typename U >
CheckedInt< T > & mozilla::CheckedInt< T >::operator/= ( rhs  ) 

Divides.

Checks for overflow and for divide-by-zero.

Returns:
self reference
template<typename T >
PRBool mozilla::CheckedInt< T >::operator== ( const CheckedInt< T > &  other  )  const [inline]
Returns:
true if the left and right hand sides are valid and have the same value.
template<typename T >
PRBool mozilla::CheckedInt< T >::valid (  )  const [inline]
Returns:
PR_TRUE if the checked integer is valid, i.e. is not the result of an invalid operation or of an operation involving an invalid checked integer
template<typename T >
T mozilla::CheckedInt< T >::value (  )  const [inline]
Returns:
the actual value

Friends And Related Function Documentation

template<typename T >
template<typename U >
CheckedInt<U> operator* ( const CheckedInt< U > &  lhs,
const CheckedInt< U > &  rhs 
) [friend]
Returns:
the product. Checks for overflow.
template<typename T >
template<typename U >
CheckedInt<U> operator+ ( const CheckedInt< U > &  lhs,
const CheckedInt< U > &  rhs 
) [friend]
Returns:
the sum. Checks for overflow.
template<typename T >
template<typename U >
CheckedInt<U> operator- ( const CheckedInt< U > &  lhs,
const CheckedInt< U > &  rhs 
) [friend]
Returns:
the difference. Checks for overflow.
template<typename T >
template<typename U >
CheckedInt<U> operator/ ( const CheckedInt< U > &  lhs,
const CheckedInt< U > &  rhs 
) [friend]
Returns:
the quotient. Checks for overflow and for divide-by-zero.

Member Data Documentation

template<typename T >
T mozilla::CheckedInt< T >::mIsValid [protected]
template<typename T >
T mozilla::CheckedInt< T >::mValue [protected]

The documentation for this class was generated from the following file: