<commit_before>/************************************************************************/
/*                                                                      */
/*               Copyright 1998-2002 by <NAME>                  */
/*                                                                      */
/*    This file is part of the VIGRA computer vision library.           */
/*    The VIGRA Website is                                              */
/*        http://hci.iwr.uni-heidelberg.de/vigra/                       */
/*    Please direct questions, bug reports, and contributions to        */
/*        <EMAIL>    or                    */
/*        <EMAIL>                               */
/*                                                                      */
/*    Permission is hereby granted, free of charge, to any person       */
/*    obtaining a copy of this software and associated documentation    */
/*    files (the "Software"), to deal in the Software without           */
/*    restriction, including without limitation the rights to use,      */
/*    copy, modify, merge, publish, distribute, sublicense, and/or      */
/*    sell copies of the Software, and to permit persons to whom the    */
/*    Software is furnished to do so, subject to the following          */
/*    conditions:                                                       */
/*                                                                      */
/*    The above copyright notice and this permission notice shall be    */
/*    included in all copies or substantial portions of the             */
/*    Software.                                                         */
/*                                                                      */
/*    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND    */
/*    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES   */
/*    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND          */
/*    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT       */
/*    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,      */
/*    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING      */
/*    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR     */
/*    OTHER DEALINGS IN THE SOFTWARE.                                   */                
/*                                                                      */
/************************************************************************/
 
 
#ifndef VIGRA_NUMERICTRAITS_HXX
#define VIGRA_NUMERICTRAITS_HXX

#include <climits>
#include <limits>
#include <cfloat>
#include <complex>
#include "metaprogramming.hxx"
#include "sized_int.hxx"

/********************************************************/
/*                                                      */
/*                      NumericTraits                   */
/*                                                      */
/********************************************************/


/** \page NumericPromotionTraits Numeric and Promotion Traits

    Meta-information about arithmetic types.
    
    <UL style="list-style-image:url(documents/bullet.gif)">
    <LI> \ref NumericTraits
         <BR>&nbsp;&nbsp;&nbsp;<em>Unary traits for promotion, conversion, creation of arithmetic objects</em>
    <LI> \ref PromoteTraits
         <BR>&nbsp;&nbsp;&nbsp;<em>Binary traits for promotion of arithmetic objects</em>
    <LI> \ref SquareRootTraits
         <BR>&nbsp;&nbsp;&nbsp;<em>Unary traits for the calculation of the square root of arithmetic objects</em>
    <LI> \ref NormTraits
         <BR>&nbsp;&nbsp;&nbsp;<em>Unary traits for the calculation of the norm and squared norm of arithmetic objects</em>
    </UL>
    
    These traits classes contain information that is used by generic
    algorithms and data structures to determine intermediate and result
    types of numerical calculations, to convert between different 
    representations of arithmetic types, and to create certain important
    constants of each type. Thus, algorithms and data structures
    operating that need arithmetic operations can be made more
    independent from the actual data representation.
    
    NumericTraits are implemented as template specializations of one
    arithmetic type, while PromoteTraits are specialized for a pair of
    arithmetic types that shall be combined in one operation.    
*/

/** \page NumericTraits template<> struct NumericTraits<ArithmeticType>

    Unary traits for promotion, conversion, creation of arithmetic objects.

    <b>\#include</b> \<vigra/numerictraits.hxx\>

    This traits class is used derive important properties of
    an arithmetic type. Consider the following algorithm:
    
    \code
    // calculate the sum of a sequence of bytes
    int sumBytes(unsigned char * begin, unsigned char * end)
    {
        int result = 0;
        for(; begin != end; ++begin)  result += *begin;
        return result;
    }
    \endcode 
    
    The return type of this function can not be 'unsigned char' because
    the summation would very likely overflow. Since we know the source
    type, we can easily choose 'int' as an appropriate return type.
    Likewise, we would have chosen 'float' if we had to sum a 
    sequence of floats. If we want to make this 
    algorithm generic, we would like to derive the appropriate return 
    type automatically. This can be done with NumericTraits. 
    The code would look like this (we use \ref DataAccessors to 
    read the data from the sequence):
    
    \code
    // calculate the sum of any sequence
    template <class Iterator, class Accessor>
    typename vigra::NumericTraits<typename Accessor::value_type>::Promote
    sumSequence(Iterator begin, Iterator end, Accessor a)
    {
        // an abbreviation
        typedef vigra::NumericTraits<typename Accessor::value_type>  SrcTraits;
        
        // find out result type
        typedef typename SrcTraits::Promote ResultType;
      
        // init result to zero
        ResultType result = vigra::NumericTraits<ResultType>::zero();
    
        for(; begin != end; ++begin)
        {  
            // cast current item to ResultType and add
            result += SrcTraits::toPromote(a(begin));
        }
        
        return result;
    }
    \endcode
    
    In this example NumericTraits is not only used to deduce the 
    ReturnType of the operation, but also to initialize it with the
    constant 'zero'. This is necessary since we do not know in general,
    which expression must be used to obtain a zero of some arbitrary
    type - '<TT>ResultType result = 0;</TT>' would only work if the 
    ResultType had an constructor taking an '<TT>int</TT>' argument, and we 
    would not even have any guarantee as to what the semantics of this
    constructor are. In addition, the traits are used to cast the 
    source type into the promote type.
    
    Similarly, an algorithm that needs multiplication would use the 
    return type <TT>RealPromote</TT> and the functions <TT>one()</TT> and
    <TT>toRealPromote()</TT>. The following members are defined in 
    <b> <TT>NumericTraits<ArithmeticType></TT></b>:
    
    <table>
    <tr><td>
    <b> <TT>typedef ... Type;</TT></b>
    </td><td>
    
            the type itself 
        
    </td></tr>
    <tr><td>
    <b> <TT>typedef ... Promote;</TT></b>
    </td><td>
    
            promote type for addition and subtraction 
        
    </td></tr>
    <tr><td>
    <b> <TT>typedef ... RealPromote;</TT></b>
    </td><td>
            promote type for multiplication and division with a real number
    
    (only defined if <TT>ArithmeticType</TT> supports these operations) 
    
    </td></tr>
    <tr><td>
    <b> <TT>typedef ... ComplexPromote;</TT></b>
    </td><td>
    
            promote type for complex arithmetic 
        
    </td></tr>
    <tr><td>
    <b> <TT>typedef ... ValueType;</TT></b>
    </td><td>
    
            for scalar types: the type itself<br>
            otherwise: typename Type::value_type (if defined)<commit_msg>DOC: fix table markup of NumericTraits<commit_after>/************************************************************************/
/*                                                                      */
/*               Copyright 1998-2002 by <NAME>                  */
/*                                                                      */
/*    This file is part of the VIGRA computer vision library.           */
/*    The VIGRA Website is                                              */
/*        http://hci.iwr.uni-heidelberg.de/vigra/                       */
/*    Please direct questions, bug reports, and contributions to        */
/*        <EMAIL>    or                    */
/*        <EMAIL>                               */
/*                                                                      */
/*    Permission is hereby granted, free of charge, to any person       */
/*    obtaining a copy of this software and associated documentation    */
/*    files (the "Software"), to deal in the Software without           */
/*    restriction, including without limitation the rights to use,      */
/*    copy, modify, merge, publish, distribute, sublicense, and/or      */
/*    sell copies of the Software, and to permit persons to whom the    */
/*    Software is furnished to do so, subject to the following          */
/*    conditions:                                                       */
/*                                                                      */
/*    The above copyright notice and this permission notice shall be    */
/*    included in all copies or substantial portions of the             */
/*    Software.                                                         */
/*                                                                      */
/*    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND    */
/*    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES   */
/*    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND          */
/*    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT       */
/*    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,      */
/*    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING      */
/*    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR     */
/*    OTHER DEALINGS IN THE SOFTWARE.                                   */                
/*                                                                      */
/************************************************************************/
 
 
#ifndef VIGRA_NUMERICTRAITS_HXX
#define VIGRA_NUMERICTRAITS_HXX

#include <climits>
#include <limits>
#include <cfloat>
#include <complex>
#include "metaprogramming.hxx"
#include "sized_int.hxx"

/********************************************************/
/*                                                      */
/*                      NumericTraits                   */
/*                                                      */
/********************************************************/


/** \page NumericPromotionTraits Numeric and Promotion Traits

    Meta-information about arithmetic types.
    
    <UL style="list-style-image:url(documents/bullet.gif)">
    <LI> \ref NumericTraits
         <BR>&nbsp;&nbsp;&nbsp;<em>Unary traits for promotion, conversion, creation of arithmetic objects</em>
    <LI> \ref PromoteTraits
         <BR>&nbsp;&nbsp;&nbsp;<em>Binary traits for promotion of arithmetic objects</em>
    <LI> \ref SquareRootTraits
         <BR>&nbsp;&nbsp;&nbsp;<em>Unary traits for the calculation of the square root of arithmetic objects</em>
    <LI> \ref NormTraits
         <BR>&nbsp;&nbsp;&nbsp;<em>Unary traits for the calculation of the norm and squared norm of arithmetic objects</em>
    </UL>
    
    These traits classes contain information that is used by generic
    algorithms and data structures to determine intermediate and result
    types of numerical calculations, to convert between different 
    representations of arithmetic types, and to create certain important
    constants of each type. Thus, algorithms and data structures
    operating that need arithmetic operations can be made more
    independent from the actual data representation.
    
    NumericTraits are implemented as template specializations of one
    arithmetic type, while PromoteTraits are specialized for a pair of
    arithmetic types that shall be combined in one operation.    
*/

/** \page NumericTraits template<> struct NumericTraits<ArithmeticType>

    Unary traits for promotion, conversion, creation of arithmetic objects.

    <b>\#include</b> \<vigra/numerictraits.hxx\>

    This traits class is used derive important properties of
    an arithmetic type. Consider the following algorithm:
    
    \code
    // calculate the sum of a sequence of bytes
    int sumBytes(unsigned char * begin, unsigned char * end)
    {
        int result = 0;
        for(; begin != end; ++begin)  result += *begin;
        return result;
    }
    \endcode 
    
    The return type of this function can not be 'unsigned char' because
    the summation would very likely overflow. Since we know the source
    type, we can easily choose 'int' as an appropriate return type.
    Likewise, we would have chosen 'float' if we had to sum a 
    sequence of floats. If we want to make this 
    algorithm generic, we would like to derive the appropriate return 
    type automatically. This can be done with NumericTraits. 
    The code would look like this (we use \ref DataAccessors to 
    read the data from the sequence):
    
    \code
    // calculate the sum of any sequence
    template <class Iterator, class Accessor>
    typename vigra::NumericTraits<typename Accessor::value_type>::Promote
    sumSequence(Iterator begin, Iterator end, Accessor a)
    {
        // an abbreviation
        typedef vigra::NumericTraits<typename Accessor::value_type>  SrcTraits;
        
        // find out result type
        typedef typename SrcTraits::Promote ResultType;
      
        // init result to zero
        ResultType result = vigra::NumericTraits<ResultType>::zero();
    
        for(; begin != end; ++begin)
        {  
            // cast current item to ResultType and add
            result += SrcTraits::toPromote(a(begin));
        }
        
        return result;
    }
    \endcode
    
    In this example NumericTraits is not only used to deduce the 
    ReturnType of the operation, but also to initialize it with the
    constant 'zero'. This is necessary since we do not know in general,
    which expression must be used to obtain a zero of some arbitrary
    type - '<TT>ResultType result = 0;</TT>' would only work if the 
    ResultType had an constructor taking an '<TT>int</TT>' argument, and we 
    would not even have any guarantee as to what the semantics of this
    constructor are. In addition, the traits are used to cast the 
    source type into the promote type.
    
    Similarly, an algorithm that needs multiplication would use the 
    return type <TT>RealPromote</TT> and the functions <TT>one()</TT> and
    <TT>toRealPromote()</TT>. The following members are defined in 
    <b> <TT>NumericTraits<ArithmeticType></TT></b>:
    
    <table>
    <tr><td>
    <b> <TT>typedef ... Type;</TT></b>
    </td><td>
            the type itself 
        
    </td></tr>
    <tr><td>
    <b> <TT>typedef ... Promote;</TT></b>
    </td><td>
            promote type for addition and subtraction 
        
    </td></tr>
    <tr><td>
    <b> <TT>typedef ... RealPromote;</TT></b>
    </td><td>
            promote type for multiplication and division with a real number
    
    (only defined if <TT>ArithmeticType</TT> supports these operations) 
    
    </td></tr>
    <tr><td>
    <b> <TT>typedef ... ComplexPromote;</TT></b>
    </td><td>
            promote type for complex arithmetic 
        
    </td></tr>
    <tr><td>
    <b> <TT>typedef ... ValueType;</TT></b>
    </td><td>
            for scalar types: the type itself<br>
            otherwise: typename Type::value_type (if defined)
{'fraction_non_alphanumeric': 0.11482280431432974, 'fraction_numerical': 0.0012326656394453005, 'mean_word_length': 1.8576963719619584, 'pattern_counts': {'":': 0, '<': 205, '<?xml version=': 0, '>': 205, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 60, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3286810', 'n_tokens_mistral': 4024, 'n_tokens_neox': 3786, 'n_words': 1534}