safemath.hpp

/******************************************************************************
* Copyright (c) ATTX LLC 2024. All Rights Reserved.
*
* This software and associated documentation (the "Software") are the 
* proprietary and confidential information of ATTX, LLC. The Software is 
* furnished under a license agreement between ATTX and the user organization 
* and may be used or copied only in accordance with the terms of the agreement.
* Refer to 'license/attx_license.adoc' for standard license terms.
*
* EXPORT CONTROL NOTICE: THIS SOFTWARE MAY INCLUDE CONTENT CONTROLLED UNDER THE
* INTERNATIONAL TRAFFIC IN ARMS REGULATIONS (ITAR) OR THE EXPORT ADMINISTRATION 
* REGULATIONS (EAR99). No part of the Software may be used, reproduced, or 
* transmitted in any form or by any means, for any purpose, without the express 
* written permission of ATTX, LLC.
******************************************************************************/
/*
Safe math header file
---------------------
This file defines basic functions for safe mathematical operations.
Rather than raising an error on fail cases (i.e. divide by zero),
the following libraries are designed to check for errors and return
corresponding codes.
 
Author: Alex Reynolds
*/
 
#ifndef SAFEMATH_HPP
#define SAFEMATH_HPP
 
#define SAFE_MATH_ZERO_TOLERANCE 1e-15
 
namespace clockwerk {
 
    /// @brief   Overloaded functions to perform safe division
    /// @param   a   Dividend
    /// @param   b   Divisor
    /// @param   result  PBR value to receive result of division
    /// @return  Error code corresponding to errors in clockwerkerrors.h
    int safeDivide(const float &a, const float &b, float &result);
    int safeDivide(const double &a, const double &b, double &result);
    int safeDivide(const int &a, const int &b, int &result);
    int safeDivide(const unsigned long long &a, const unsigned long long &b, unsigned long long &result);
 
    /// @brief   Overloaded functions to perform safe square root
    /// @param   input   The value to take the square root of
    /// @param   result  PBR value to receive result of square
    /// @return  Error code corresponding to errors in clockwerkerrors.h
    int safeSqrt(const float &input, float &result);
    int safeSqrt(const double &input, double &result);
 
    /// @brief   Overloaded functions to perform safe n root
    /// @param   input   The value to take the n root of
    /// @param   rt    The degree of root to take
    /// @param   result  PBR value to receive result of n-root
    /// @return  Error code corresponding to errors in clockwerkerrors.h
    int safeNroot(const float &input, const int &rt, float &result);
    int safeNroot(const double &input, const int &rt, double &result);
 
    /// @brief Overloaded functions to perform save cosine inverse
    /// @param input The input value to take cosine of
    /// @param result The result of the cos
    /// @return Error code corresponding to success/failure
    int safeAcos(const float &input, float &result);
    int safeAcos(const double &input, double &result);
 
    /// @brief Overloaded functions to perform save sine inverse
    /// @param input The input value to take sine of
    /// @param result The result of the sin
    /// @return Error code corresponding to success/failure
    int safeAsin(const float &input, float &result);
    int safeAsin(const double &input, double &result);
 
    /// @brief Overloaded functions to perform safe tangent
    /// @param input The input value to take tangent of
    /// @param result The result of the tangent
    /// @return Error code corresponding to success/failure
    int safeTan(const float &input, float &result);
    int safeTan(const double &input, double &result);
}
 
#endif