CeylanMathsBasic.h

Go to the documentation of this file.

/* 
 * Copyright (C) 2003-2009 Olivier Boudeville
 *
 * This file is part of the Ceylan library.
 *
 * The Ceylan library is free software: you can redistribute it and/or modify
 * it under the terms of either the GNU Lesser General Public License or
 * the GNU General Public License, as they are published by the Free Software
 * Foundation, either version 3 of these Licenses, or (at your option) 
 * any later version.
 *
 * The Ceylan library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License and the GNU General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License and the GNU General Public License along with the Ceylan library.
 * If not, see <http://www.gnu.org/licenses/>.
 *
 * Author: Olivier Boudeville (olivier.boudeville@esperide.com)
 *
 */


#ifndef CEYLAN_MATHS_BASIC_H_
#define CEYLAN_MATHS_BASIC_H_



#include "CeylanException.h"        // for Exception
#include "CeylanTypes.h"            // for Float32, etc.
#include "CeylanFunctor.h"          // for functor, etc.


#include <string>



namespace Ceylan
{


    namespace Maths
    {
    
    
    
        /*
         * Numerical constants commonly used for mathematic computations.
         *
         * Instead of standard variables (ex: M_E), their GNU counterparts
         * (ex: M_El) are used, since their accuracy (precision) is better:
         * they are adequate for computation using `Ceylan::LongFloat'.
         * 
         * Since depending on a GNU set of constants would not be portable
         * enough, their values are explicitly set here, one time for all.
         *
         * @note Curiously, the overall accuracy is not that great, for 
         * example with E: 
         *  - original: 2.7182818284590452353602874713526625
         *  - displayed: 2.7182818284590450908
         * even with a precision set to 40 digits.
         *
         * From that comparison, we defined epsilon.
         *
         * @note For floating point numbers, tests for equality should be
         * performed thanks to the AreEqual method, since limited precision
         * generates tiny numerical errors.
         *
         * @see GNU extension of math.h 
         *
         * @todo Maybe add signal handler or similar device to catch 
         * floating point exceptions.
         *
         */


        typedef Ceylan::Sint32 IntegerData ;
        
        
        
        typedef Ceylan::Float32 Real ;
        
        
        
        typedef Ceylan::Float32 AngleInDegrees ;
        


        typedef Ceylan::Float32 AngleInRadians ;
        
        
        
        typedef Ceylan::Uint8 Percentage ;
    
        
        
        typedef Ceylan::Uint32 Hertz ;


        
        typedef Ceylan::Float32 Ratio ;
        
        
        
        
        class CEYLAN_DLL MathsException : public Ceylan::Exception
        {
        
            public:
            
                explicit MathsException( const std::string & message ) ;
                
                virtual ~MathsException() throw() ;
        
        } ;
        
        
        
        
        /*
         * Section related to most useful constants.
         *
         * @note The LongFloat type is used to decrease numerical errors.
         *
         */
        
        
        extern CEYLAN_DLL const Ceylan::LongFloat E ;



        extern CEYLAN_DLL const Ceylan::LongFloat Log2E ;
    
    
    
        extern CEYLAN_DLL const Ceylan::LongFloat Log10E ;
    
    
    
        extern CEYLAN_DLL const Ceylan::LongFloat LogE2 ;
    
    
    
        extern CEYLAN_DLL const Ceylan::LongFloat LogE10 ;




        // Section related to the Pi constant.
        
    
        extern CEYLAN_DLL const Ceylan::LongFloat Pi ;
    
    
    
        extern CEYLAN_DLL const Ceylan::LongFloat Pi_div_2 ;
    
    
    
        extern CEYLAN_DLL const Ceylan::LongFloat Pi_div_4 ;
    
    
    
        extern CEYLAN_DLL const Ceylan::LongFloat One_div_Pi ;
    
    
    
        extern CEYLAN_DLL const Ceylan::LongFloat Two_div_Pi ;
    
    
    
        extern CEYLAN_DLL const Ceylan::LongFloat Two_div_sqrt_Pi ;
    
    
    
    
    
        // Section related to the sqrt(2) constant.
        
    
        extern CEYLAN_DLL const Ceylan::LongFloat Sqrt_2 ;
    
    
    
        extern CEYLAN_DLL const Ceylan::LongFloat One_div_sqrt_2 ;
    
    
    
        extern CEYLAN_DLL const Ceylan::LongFloat EpsilonFloat32 ;



        extern CEYLAN_DLL const Ceylan::LongFloat EpsilonFloat64 ;



        extern CEYLAN_DLL const Ceylan::LongFloat EpsilonLongFloat ;



        extern CEYLAN_DLL const Ceylan::LongFloat Epsilon ;

        
        
        
        
        // Templates could have been more widely used.



        // IsNull section.
        

        CEYLAN_DLL bool IsNull( Ceylan::Float32 x ) ;

        
        CEYLAN_DLL bool IsNull( Ceylan::Float32 x, Ceylan::Float32 epsilon ) ;
        
        
        
        CEYLAN_DLL bool IsNull( Ceylan::Float64 x ) ;
        
        
        
        CEYLAN_DLL bool IsNull( Ceylan::Float64 x, Ceylan::Float64 epsilon ) ;
        
        
        
        CEYLAN_DLL bool IsNull( Ceylan::LongFloat x ) ;
        
        
        
        CEYLAN_DLL bool IsNull( Ceylan::LongFloat x, 
            Ceylan::LongFloat epsilon ) ;
        
        
        
        
        // AreEqual section.
        
        
        
        CEYLAN_DLL bool AreEqual( Ceylan::Float32 x, Ceylan::Float32 y ) ;
        
        
        
        CEYLAN_DLL bool AreEqual( Ceylan::Float32 x, Ceylan::Float32 y, 
            Ceylan::Float32 epsilon ) ;
        
        
        
        CEYLAN_DLL bool AreEqual( Ceylan::Float64 x, Ceylan::Float64 y ) ;
        
        
        
        CEYLAN_DLL bool AreEqual( Ceylan::Float64 x, Ceylan::Float64 y, 
            Ceylan::Float64 epsilon ) ;
        


        CEYLAN_DLL bool AreExactlyEqual( Ceylan::Float64 x, 
            Ceylan::Float64 y ) ;
        
        
        CEYLAN_DLL bool AreEqual( Ceylan::LongFloat x, Ceylan::LongFloat y ) ;

        
        
        CEYLAN_DLL bool AreEqual( Ceylan::LongFloat x, Ceylan::LongFloat y, 
            Ceylan::LongFloat epsilon ) ;
        
    
    
        template <typename T>
        bool AreRelativelyEqual( T x, T y ) 
        {
        
        
            /*
             * One goal, avoid division by zero on final formula:
             * x + y == 0 iff x == -y, in this case:  
             *   - if x == 0 then y == 0 and they are deemed equal
             *   - otherwise x != 0 implies x != y (since x == -y),
             * hence they are not deemed equal.
             *
             * EpsilonFloat32 not used, otherwise the IsNull calls are
             * deemed ambiguous.
             * 
             */
            if ( IsNull( x + y ) )
                return IsNull( x ) ;
                
                
            /*
             * Here x + y != 0.
             * 
             * Relative comparison: compare their difference (|x-y|) 
             * to their mean value ((x+y)/2), here using 
             * EpsilonFloat32 as equality criterion.
             *
             * @note The second Abs, in the denominator, is necessary if 
             * x + y is negative, for example if x and y are negative.
             * The cast to a T value is then necessary to avoid an integer
             * division. 
             *
             */
            return ( 2 * Abs( x - y ) / static_cast<T>( Abs( x + y ) ) 
                < static_cast<T>( EpsilonFloat32 ) ) ;
            
        }
        
        
        
        
        template <typename T>
        bool AreRelativelyEqual( T x, T y, Ceylan::LongFloat epsilon ) 
        {
                
            T castedEpsilon = static_cast<T>( epsilon ) ;
            
            /*
             * One goal, avoid division by zero on final formula:
             * x + y == 0 iff x == -y, in this case:  
             *   - if x == 0 then y == 0 and they are deemed equal
             *   - otherwise x != 0 implies x != y (since x == -y),
             * hence they are not deemed equal.
             *
             */
            if ( IsNull( x + y, castedEpsilon ) )
                return IsNull( x, castedEpsilon ) ;
                
                
            /*
             * Here x + y != 0.
             * 
             * Relative comparison: compare their difference (|x-y|) 
             * to their mean value ((x+y)/2), here using epsilon as 
             * equality criterion.
             *
             * @note The second Abs, in the denominator, is necessary if 
             * x + y is negative, for example if x and y are negative.
             * The cast to a T value is then necessary to avoid an integer
             * division. 
             *
             */
            return ( 2 * Abs( x - y ) / static_cast<T>( Abs( x + y ) ) 
                < castedEpsilon ) ;
            
        }
        
        
        
        
        /*
         * Floor, Ceil and Round section.
         *
         * These functions are designed to help computations.
         *
         * In order to display floating-point values with a limited number
         * of digits, one should prefer toString methods, whose second
         * parameter allows to select the precision.
         *
         * @see Ceylan::toString
         *
         */
        
        
        CEYLAN_DLL Ceylan::Float32 Floor( Ceylan::Float32 x ) ;


        
        CEYLAN_DLL Ceylan::Float64 Floor( Ceylan::Float64 x ) ;
        
        
        
        CEYLAN_DLL Ceylan::LongFloat Floor( Ceylan::LongFloat x ) ;
        
        
        
        
        CEYLAN_DLL Ceylan::Float32 Ceil( Ceylan::Float32 x ) ;
        
        
        
        CEYLAN_DLL Ceylan::Float64 Ceil( Ceylan::Float64 x ) ;


        
        CEYLAN_DLL Ceylan::LongFloat Ceil( Ceylan::LongFloat x ) ;
        
        
        
        
        // Round section.
        
        
        CEYLAN_DLL Ceylan::Float32 Round( Ceylan::Float32 x ) ;



        CEYLAN_DLL Ceylan::Float32 Round( Ceylan::Float32 x, 
            Ceylan::Uint8 precision ) ;

        
        
        CEYLAN_DLL Ceylan::Float64 Round( Ceylan::Float64 x ) ;



        CEYLAN_DLL Ceylan::Float64 Round( Ceylan::Float64 x, 
            Ceylan::Uint8 precision ) ;
                
                
                
        
        CEYLAN_DLL Ceylan::LongFloat Round( Ceylan::LongFloat x ) ;



        CEYLAN_DLL Ceylan::LongFloat Round( Ceylan::LongFloat x, 
            Ceylan::Uint8 precision ) ;
    
        
            
                
        
        
        // Integer signed types:

        CEYLAN_DLL Ceylan::Sint8 Abs( Ceylan::Sint8 x ) ;       
        
        
        CEYLAN_DLL Ceylan::Sint16 Abs( Ceylan::Sint16 x ) ;
                
                
        CEYLAN_DLL Ceylan::Sint32 Abs( Ceylan::Sint32 x ) ;
                
                
        CEYLAN_DLL Ceylan::SignedLongInteger Abs( 
            Ceylan::SignedLongInteger x ) ;
        
        
        
        //long long int Abs( long long int x ) ;
        
        
        
        // Floating point types:
         
         
        CEYLAN_DLL Ceylan::Float32 Abs( Ceylan::Float32 x ) ;
        
        
        CEYLAN_DLL Ceylan::Float64 Abs( Ceylan::Float64 x ) ;
        
        
        CEYLAN_DLL Ceylan::LongFloat Abs( Ceylan::LongFloat x ) ;
        
        
        
        

        template<typename T>
        T Min( T x, T y ) 
        {
            return ( ( x < y ) ? x : y ) ;
                
        }



        template<typename T>
        T Min( T x, T y, T z ) 
        {
        
            if ( x < y ) 
                return Min( x, z ) ;
            else
                return Min( y, z ) ;
                                
        }


        
        // Integer signed and unsigned types:


        CEYLAN_DLL Ceylan::Sint8 Min( Ceylan::Sint8 x, Ceylan::Sint8 y ) ;      

        
        
        CEYLAN_DLL Ceylan::Uint8 Min( Ceylan::Uint8 x, Ceylan::Uint8 y ) ;      
        
        
        
        CEYLAN_DLL Ceylan::Sint16 Min( Ceylan::Sint16 x, Ceylan::Sint16 y ) ;
            
        
            
        CEYLAN_DLL Ceylan::Uint16 Min( Ceylan::Uint16 x, Ceylan::Uint16 y ) ;
    
                
                
        CEYLAN_DLL Ceylan::Sint32 Min( Ceylan::Sint32 x, Ceylan::Sint32 y ) ;
    
    
        
        CEYLAN_DLL Ceylan::Uint32 Min( Ceylan::Uint32 x, Ceylan::Uint32 y ) ;
        
        
                
        CEYLAN_DLL Ceylan::SignedLongInteger Min( Ceylan::SignedLongInteger x,
            Ceylan::SignedLongInteger y ) ;


                
        CEYLAN_DLL Ceylan::UnsignedLongInteger Min( 
            Ceylan::UnsignedLongInteger x,
            Ceylan::UnsignedLongInteger y ) ;
    
    
        
        //long long int Min( long long int x, long long int y ) ;
        
        
        
        
        // Floating point types:

         
        CEYLAN_DLL Ceylan::Float32 Min( Ceylan::Float32 x, Ceylan::Float32 y ) ;


        
        CEYLAN_DLL Ceylan::Float64 Min( Ceylan::Float64 x, Ceylan::Float64 y ) ;

        
        
        CEYLAN_DLL Ceylan::LongFloat Min( Ceylan::LongFloat x, 
            Ceylan::LongFloat y ) ;
        
        
        
        
    

        
        template<typename T>
        T Max( T x, T y ) 
        {
            return ( ( x > y ) ? x: y ) ;
                
        }

        
        
        // Integer signed and unsigned types:

        
        CEYLAN_DLL Ceylan::Sint8 Max( Ceylan::Sint8 x, Ceylan::Sint8 y ) ;      

        
        
        CEYLAN_DLL Ceylan::Uint8 Max( Ceylan::Uint8 x, Ceylan::Uint8 y ) ;      
        
        
        
        CEYLAN_DLL Ceylan::Sint16 Max( Ceylan::Sint16 x, Ceylan::Sint16 y ) ;
        
            
            
        CEYLAN_DLL Ceylan::Uint16 Max( Ceylan::Uint16 x, Ceylan::Uint16 y ) ;
        
                
                
        CEYLAN_DLL Ceylan::Sint32 Max( Ceylan::Sint32 x, Ceylan::Sint32 y ) ;
    
    
        
        CEYLAN_DLL Ceylan::Uint32 Max( Ceylan::Uint32 x, Ceylan::Uint32 y ) ;
        
                
                
        CEYLAN_DLL Ceylan::SignedLongInteger Max( Ceylan::SignedLongInteger x,
            Ceylan::SignedLongInteger y ) ;


                
        CEYLAN_DLL Ceylan::UnsignedLongInteger Max( 
            Ceylan::UnsignedLongInteger x,
            Ceylan::UnsignedLongInteger y ) ;
    
    
        
        //long long int Max( long long int x, long long int y ) ;
        
        
        
        
        // Floating point types:

         
        CEYLAN_DLL Ceylan::Float32 Max( Ceylan::Float32 x, Ceylan::Float32 y ) ;

        
        
        CEYLAN_DLL Ceylan::Float64 Max( Ceylan::Float64 x, Ceylan::Float64 y ) ;

    
        
        CEYLAN_DLL Ceylan::LongFloat Max( Ceylan::LongFloat x, 
            Ceylan::LongFloat y ) ;
        
            

    
                
        // Exponentials:
        
        
        CEYLAN_DLL Ceylan::Float32 Exp( Ceylan::Float32 x ) ;
        
    
        
        CEYLAN_DLL Ceylan::Float64 Exp( Ceylan::Float64 x ) ;
        
    
        
        CEYLAN_DLL Ceylan::LongFloat Exp( Ceylan::LongFloat x ) ;
        
        
    
        
        // Power:
        
        CEYLAN_DLL Ceylan::Float32 Pow( Ceylan::Float32 x, Ceylan::Float32 y ) ;
    
        
        CEYLAN_DLL Ceylan::Float64 Pow( Ceylan::Float64 x, Ceylan::Float64 y ) ;
        
        
        CEYLAN_DLL Ceylan::LongFloat Pow( Ceylan::LongFloat x, 
            Ceylan::LongFloat y ) ;
    
        
        
        
        // Power of two:
    
        
        CEYLAN_DLL Ceylan::Float32 Pow2( Ceylan::Float32 x ) ;
    
        
        CEYLAN_DLL Ceylan::Float64 Pow2( Ceylan::Float64 x ) ;
    
        
        CEYLAN_DLL Ceylan::LongFloat Pow2( Ceylan::LongFloat x ) ;
        
    
            
            
        // Logarithm:
        
        
        CEYLAN_DLL Ceylan::Float32 Log( Ceylan::Float32 x ) ;
        
    
        
        CEYLAN_DLL Ceylan::Float64 Log( Ceylan::Float64 x ) ;
    
        
        
        CEYLAN_DLL Ceylan::LongFloat Log( Ceylan::LongFloat x ) ;
        
    
        
                
        // Square root:
        
        
        CEYLAN_DLL Ceylan::Float32 Sqrt( Ceylan::Float32 x ) ;
        
        
        
        CEYLAN_DLL Ceylan::Float64 Sqrt( Ceylan::Float64 x ) ;
        
        
        
        CEYLAN_DLL Ceylan::LongFloat Sqrt( Ceylan::LongFloat x ) ;
            
            
            
            
        
        // Some trigonometry.
            
                
                
        // Cosine:

        
        CEYLAN_DLL Ceylan::Float32 Cos( Ceylan::Float32 angle ) ;
        
        
        
        CEYLAN_DLL Ceylan::Float64 Cos( Ceylan::Float64 angle ) ;
        
        
        
        CEYLAN_DLL Ceylan::LongFloat Cos( Ceylan::LongFloat angle ) ;
        



        
        // Sine:
        
        
        CEYLAN_DLL Ceylan::Float32 Sin( Ceylan::Float32 angle ) ;
        
        
        
        CEYLAN_DLL Ceylan::Float64 Sin( Ceylan::Float64 angle ) ;
        
        
        
        CEYLAN_DLL Ceylan::LongFloat Sin( Ceylan::LongFloat angle ) ;
        
        
        
    
    
        // Tangent:
        
        
        CEYLAN_DLL Ceylan::Float32 Tan( Ceylan::Float32 angle ) ;
        
        
        
        CEYLAN_DLL Ceylan::Float64 Tan( Ceylan::Float64 angle ) ;
        
        
        
        CEYLAN_DLL Ceylan::LongFloat Tan( Ceylan::LongFloat angle ) ;
        
    
        
        
#if defined(CEYLAN_ARCH_NINTENDO_DS) && CEYLAN_ARCH_NINTENDO_DS == 1


        // Fixed-point counterparts.    

        
        CEYLAN_DLL Ceylan::Uint32 SqrtFixed( Ceylan::Uint32 x ) ;
        

        
#ifdef CEYLAN_RUNS_ON_ARM9

        CEYLAN_DLL Ceylan::Sint32 CosFixed( Ceylan::Sint32 angle ) ;


        CEYLAN_DLL Ceylan::Sint32 SinFixed( Ceylan::Sint32 angle ) ;
    

        CEYLAN_DLL Ceylan::Sint32 TanFixed( Ceylan::Sint32 angle ) ;
    
        
#endif // CEYLAN_RUNS_ON_ARM9


#endif // defined(CEYLAN_ARCH_NINTENDO_DS) && CEYLAN_ARCH_NINTENDO_DS == 1



        
        CEYLAN_DLL AngleInRadians DegreeToRadian( 
            AngleInDegrees angleInDegrees ) ;
        
        
        
        CEYLAN_DLL Uint16 NextPowerOfTwo( Uint16 value ) ;
    
        
        
        CEYLAN_DLL bool IsAPowerOfTwo( Uint16 value ) ; 



        
        CEYLAN_DLL Uint16 NextMultipleOf( Uint16 multiple, Uint16 value ) ;
        
            
        

        
        class CEYLAN_DLL IntToIntFunctor: public Ceylan::Functor
        {
        
        
            public:
            
            
            
                explicit IntToIntFunctor( 
                    Ceylan::Sint32 creationParameter ) ;
                
                
                virtual ~IntToIntFunctor() throw() ;
                
                
                virtual Ceylan::Sint32 operator() ( 
                    Ceylan::Sint32 callParameter ) = 0 ;
    
        
        
                virtual const std::string toString( 
                    Ceylan::VerbosityLevels level = Ceylan::high ) const ;
        
        
        
            protected:
            
            
                Ceylan::Sint32 _creationParameter ;
                
            
        } ;
                
    }

}



#endif // CEYLAN_MATHS_BASIC_H_

---