harbour-core/doc/en/math.txt

/*
 * Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
 *    Documentation for: Abs(), Exp(), Log(), Int(), Max()
 *    Min(), Sqrt(), Round()
 * Copyright 2001 IntTec GmbH, Neunlindenstr 32, 79106 Freiburg, Germany
 *           Author: Martin Vogel <vogel@inttec.de>
 *    Documentation for API
 *  $SUBCATEGORY$
 *      Math functions
 * See COPYING.txt for licensing terms.
 *
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      Abs()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Math
   $ONELINER$
      Return the absolute value of a number.
   $SYNTAX$
      Abs( <nNumber> ) --> <nAbsNumber>
   $ARGUMENTS$
      <nNumber> Any number.
   $RETURNS$
      <nAbsNumber> The absolute numeric value.
   $DESCRIPTION$
      This function yields the absolute value of the numeric value or
      expression <nNumber>.
   $EXAMPLES$
      PROCEDURE Main()
         LOCAL nNumber := 50
         LOCAL nNumber1 := 27
         CLS

         ? nNumber - nNumber1
         ? nNumber1 - nNumber
         ? Abs( nNumber - nNumber1 )
         ? Abs( nNumber1 - nNumber )
         ? Abs( -1 * 345 )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$

   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      Exp()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Math
   $ONELINER$
      Calculates the value of e raised to the passed power.
   $SYNTAX$
      Exp( <nNumber> ) --> <nValue>
   $ARGUMENTS$
      <nNumber> Any  real number.
   $RETURNS$
      <nValue>  The anti-logarithm of <nNumber>
   $DESCRIPTION$
      This function returns the value of e raised to the power of
      <nNumber>.  It is the inverse of Log().
   $EXAMPLES$
      ? Exp( 45 )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Log()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      Int()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Math
   $ONELINER$
      Return the integer port of a numeric value.
   $SYNTAX$
      Int( <nNumber> ) --> <nIntNumber>
   $ARGUMENTS$
      <nNumber> Any  numeric value.
   $RETURNS$
      <nIntNumber> The integer portion of the numeric value.
   $DESCRIPTION$
      This function converts a numeric expression to an integer. All
      decimal digits are truncated. This function does not round a value
      upward or downward; it merely truncates a number at the decimal
      point.
   $EXAMPLES$
      Set( _SET_DECIMALS, 5 )
      ? Int( 632512.62541 )
      ? Int( 845414111.91440 )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Round(), StrZero()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      Log()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Math
   $ONELINER$
      Returns the natural logarithm of a number.
   $SYNTAX$
      Log( <nNumber> ) --> <nLog>
   $ARGUMENTS$
      <nNumber> Any numeric expression.
   $RETURNS$
      <nExponent> The natural logarithm of <nNumber>.
   $DESCRIPTION$
      This function returns the natural logarithm of the number <nNumber>.
      If <nNumber> is 0 or less than 0, a numeric overflow occurs,
      which is depicted on the display device as a series of asterisks.
      This function is the inverse of Exp().
   $EXAMPLES$
      ? Log( 632512 )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Exp()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      Max()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Math
   $ONELINER$
      Returns the maximum of two numbers or dates.
   $SYNTAX$
      Max( <xValue>, <xValue1> ) --> <xMax>
   $ARGUMENTS$
      <xValue>  Any date or numeric value.

      <xValue1> Any date or numeric value (same type as <xValue>).
   $RETURNS$
      <xMax> The larger numeric (or later date) value.
   $DESCRIPTION$
      This function returns the larger of the two passed espressions. If
      <xValue> and <xValue1> are numeric data types, the value returned by
      this function will be a numeric data type as well and will be the
      larger of the two numbers passed to it. If <xValue> and <xValue1>
      are date data types, the return value will be a date data type as
      well. It will be the later of the two dates passed to it.
   $EXAMPLES$
      ? Max( 214514214, 6251242142 )
      ? Max( hb_SToD( "20001111" ), hb_SToD( "20140621" ) )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Min()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      Min()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Math
   $ONELINER$
      Determines the minumum of two numbers or dates.
   $SYNTAX$
      Min( <xValue>, <xValue1> ) --> <xMin>
   $ARGUMENTS$
      <xValue>  Any date or numeric value.

      <xValue1> Any date or numeric value.
   $RETURNS$
      <xMin>  The smaller numeric (or earlier date) value.
   $DESCRIPTION$
      This function returns the smaller of the two passed espressions.
      <xValue> and <xValue1> must be the same data type. If numeric, the
      smaller number is returned. If dates, the earlier date is returned.
   $EXAMPLES$
      ? Min( 214514214, 6251242142 )
      ? Min( hb_SToD( "20001111" ), hb_SToD( "20140621" ) )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Max()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      Mod()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Math
   $ONELINER$
      Return the modulus of two numbers.
   $SYNTAX$
      Mod( <nNumber>, <nNumber1> ) -->  <nRemainder>
   $ARGUMENTS$
      <nNumber>  Numerator in a divisional expression.

      <nNumber1> Denominator in a divisional expression.
   $RETURNS$
      <nRemainder>  The remainder after the division operation.
   $DESCRIPTION$
      This functuion returns the remainder of one number divided by
      another.
   $EXAMPLES$
      ? Mod( 12, 8.521 )
      ? Mod( 12, 0 )
      ? Mod( 62412.5142, 4522114.12014 )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      %
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      Sqrt()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Math
   $ONELINER$
      Calculates the square root of a number.
   $SYNTAX$
      Sqrt( <nNumber> ) --> <nSqrt>
   $ARGUMENTS$
      <nNumber> Any  numeric value.
   $RETURNS$
      <nSqrt>   The square root of <number>.
   $DESCRIPTION$
      This function returns the square root of <nNumber>. The precision
      of this evaluation is based solely on the setting of _SET_DECIMALS.
      Any negative number passed as <nNumber> will always return a 0.
   $EXAMPLES$
      Set( _SET_DECIMALS, 5 )
      ? Sqrt( 632512.62541 )
      ? Sqrt( 845414111.91440 )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Round()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      Round()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Math
   $ONELINER$
      Rounds off a numeric expression.
   $SYNTAX$
      Round( <nNumber>, <nPlace> ) --> <nResult>
   $ARGUMENTS$
      <nNumber> Any numeric value.

      <nPlace>  The number of places to round to.
   $RETURNS$
      <nResult> The rounded number.
   $DESCRIPTION$
      This function rounds off the value of <nNumber> to the number of
      decimal places specified by <nPlace>. If the value of <nPlace> is
      a negative number, the function will attempt to round <nNumber> in
      whole numbers. Numbers from 5 through 9 will be rounded up, all
      others will be rounded down.
   $EXAMPLES$
      ? Round( 632512.62541, 5 )
      ? Round( 845414111.91440, 3 )
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$
      Int(), Str(), Val(), SET FIXED
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_mathGetLastError()
   $CATEGORY$
      C level API
   $SUBCATEGORY$
      Math
   $ONELINER$
      get the last math lib error
   $SYNTAX$
      C Prototype

      #include "hbmath.h"
      hb_mathGetLastError( HB_MATH_EXCEPTION * phb_exc )
                          --> int iMathErrorType
   $ARGUMENTS$
      phb_exc     pointer to HB_MATH_EXCEPTION structure, if not NULL,
                  the structure will be filled with information about the
                  last math error:

           typedef struct _HB_MATH_EXCEPTION {
             int type;        // Math error type, is one of the constants
                              // HB_MATH_ERR_xxx defined in hbmath.ch
             char *funcname;  // Pointer to name of the math C RTL routine
                              // that caused the error.
             char *error;     // Pointer to error description.
             double arg1;     // First and
             double arg2;     // Second double argument to the math routine.
             double retval;   // Corrected return value for the math routine.
             int retvalwidth; // Width and
             int retvaldec;   // Decimals of the corrected return value,
                              // both default to -1
             int handled;     // 1, if the math error is already corrected,
                              // 0 otherwise.
          } HB_MATH_EXCEPTION;
   $RETURNS$
      <iMathErrorType>
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      NA
   $FILES$
      Header file is hbmath.h
      Library is core
   $PLATFORMS$
      All
   $SEEALSO$

   $END$
 */

/* $DOC$
   $TEMPLATE$
      Procedure
   $NAME$
      hb_mathResetError()
   $CATEGORY$
      C level API
   $SUBCATEGORY$
      Math
   $ONELINER$
      Reset the internal math error information structure
   $SYNTAX$
      C Prototype

      #include "hbmath.h"
      hb_mathResetError( void )
   $ARGUMENTS$

   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      NA
   $FILES$
      Header file is hbmath.h
      Library is core
   $PLATFORMS$
      All
   $SEEALSO$

   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_mathIsMathErr()
   $CATEGORY$
      C level API
   $SUBCATEGORY$
      Math
   $ONELINER$
      Check if Harbour math error handling is available
   $SYNTAX$
      C Prototype

      #include "hbmath.h"
      hb_mathIsMathErr( void ) --> int iIsMathHandler
   $ARGUMENTS$

   $RETURNS$
      <iIsMathHandler>
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      NA
   $FILES$
      Header file is hbmath.h
      Library is core
   $PLATFORMS$
      All
   $SEEALSO$

   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_mathSetHandler()
   $CATEGORY$
      C level API
   $SUBCATEGORY$
      Math
   $ONELINER$
      set the Harbour math handler
   $SYNTAX$
      C Prototype

      #include "hbmath.h"
      hb_mathSetHandler( HB_MATH_HANDLERPROC handlerproc )
                        --> HB_MATH_HANDLERPROC previous_handerproc
   $ARGUMENTS$
      handlerproc             custom math handler
              typedef int (* HB_MATH_HANDLERPROC)(HB_MATH_EXCEPTION * err)
   $RETURNS$
      previous_handlerproc    previous math handler
              typedef int (* HB_MATH_HANDLERPROC)(HB_MATH_EXCEPTION * err)
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      NA
   $FILES$
      Header file is hbmath.h
      Library is core
   $PLATFORMS$
      All
   $SEEALSO$

   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_mathGetHandler()
   $CATEGORY$
      C level API
   $SUBCATEGORY$
      Math
   $ONELINER$
      get current Harbour math error handler
   $SYNTAX$
      C Prototype

      #include "hbmath.h"
      hb_mathGetHandler( void ) --> HB_MATH_HANDLERPROC handlerproc
   $ARGUMENTS$
      handlerproc             custom math handler
              typedef int (* HB_MATH_HANDLERPROC)(HB_MATH_EXCEPTION * err)
   $RETURNS$
      <handerproc>
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      NA
   $FILES$
      Header file is hbmath.h
      Library is core
   $PLATFORMS$
      All
   $SEEALSO$

   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_mathSetErrMode()
   $CATEGORY$
      C level API
   $SUBCATEGORY$
      Math
   $ONELINER$
      set math error handling mode
   $SYNTAX$
      C Prototype

      #include "hbmath.h"
      hb_mathSetErrMode( int imode ) --> int ioldmode
   $ARGUMENTS$
      imode        math error handling mode, one of the following
                   constants, defined in hbmath.ch:
                     HB_MATH_ERRMODE_DEFAULT
                     HB_MATH_ERRMODE_CDEFAULT
                     HB_MATH_ERRMODE_USER
                     HB_MATH_ERRMODE_USERDEFAULT
                     HB_MATH_ERRMODE_USERCDEFAULT
   $RETURNS$
      ioldmode     old math error handling mode
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      NA
   $FILES$
      Header file is hbmath.h
      Library is core
   $PLATFORMS$
      All
   $SEEALSO$
      hb_mathGetErrMode()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_mathGetErrMode()
   $CATEGORY$
      C level API
   $SUBCATEGORY$
      Math
   $ONELINER$
      get math error handling mode
   $SYNTAX$
      C Prototype

      #include "hbmath.h"
      hb_mathGetErrMode( void ) --> imode
   $ARGUMENTS$

   $RETURNS$
      imode       math error handling mode
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      NA
   $FILES$
      Header file is hbmath.h
      Library is core
   $PLATFORMS$
      All
   $SEEALSO$
      hb_mathSetErrMode()
   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_matherMode()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Math
   $ONELINER$
      Set/Get math error handling mode
   $SYNTAX$
      hb_matherMode( [<nNewMode>] ) --> <nOldMode>
   $ARGUMENTS$
      [<nNumber>]   new math error handling mode, one of the following
                    constants, defined in hbmath.ch:
                     HB_MATH_ERRMODE_DEFAULT
                     HB_MATH_ERRMODE_CDEFAULT
                     HB_MATH_ERRMODE_USER
                     HB_MATH_ERRMODE_USERDEFAULT
                     HB_MATH_ERRMODE_USERCDEFAULT
   $RETURNS$
      <nOldMode>    old math error handling mode
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$
      All
   $FILES$
      Header file is hbmath.ch
      Library is core
   $SEEALSO$

   $END$
 */

/* $DOC$
   $TEMPLATE$
      Function
   $NAME$
      hb_matherBlock()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Math
   $ONELINER$
      Set/Get math error handling codeblock
   $SYNTAX$
      hb_matherBlock( [<bNewBlock>] ) --> <bOldBlock>
   $ARGUMENTS$
      <bNewBlock>
   $RETURNS$
      <bOldBlock> is the current error handler codeblock
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$

   $PLATFORMS$
      All
   $FILES$
      Library is core
   $SEEALSO$

   $END$
 */