/*
 * $Id: math.txt,v 1.9 2002/07/07 20:45:38 mbirdyg Exp $
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://www.harbour-project.org
 *
 * 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 Math API functions
 * See doc/license.txt for licensing terms.
 *
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ABS()
 *  $CATEGORY$
 *      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$
 *      Proc Main()
 *
 *      Local nNumber:=50
 *      Local nNumber1:=27
 *      cls
 *
 *      qout(nNumber-nNumber1)
 *      qout(nNumber1-nNumber)
 *      qout(ABS(nNumber-nNumber1))
 *      qout(ABSnNumber1-nNumber))
 *      qout(ABS( -1 * 345))
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compliant.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      EXP()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      EXP()
 *  $CATEGORY$
 *      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)
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compliant.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      LOG()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      INT()
 *  $CATEGORY$
 *      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 Decimal to 5
 *      ? INT(632512.62541)
 *      ? INT(845414111.91440)
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compliant.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ROUND(),STRZERO()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      LOG()
 *  $CATEGORY$
 *      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)
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compliant.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      EXP()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      MAX()
 *  $CATEGORY$
 *      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(CTOD('11/11/2000'),CTOD('21/06/2014')
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is Ca-Clipper compliant.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      Min()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      MIN()
 *  $CATEGORY$
 *      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(CTOD('11/11/2000'),CTOD('21/06/2014')
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is Ca-Clipper compliant.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      MAX()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      MOD()
 *  $CATEGORY$
 *      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)
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This Function is Ca-Clipper compliant.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      %
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      SQRT()
 *  $CATEGORY$
 *      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 settings of the SET DECIMAL TO
 *      command. Any negative number passed as <nNumber> will always return a 0.
 *  $EXAMPLES$
 *      SET Decimal to 5
 *      ? SQRT(632512.62541)
 *      ? SQRT(845414111.91440)
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compliant.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ROUND()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ROUND()
 *  $CATEGORY$
 *      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$
 *      This function is CA-Clipper compliant.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      INT(),STR(),VAL(),SET FIXED
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_mathGetLastError()
 *  $CATEGORY$
 *      Math API
 *  $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 math.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$
 *      
 *  $DESCRIPTION$
 *      
 *  $EXAMPLES$
 *      
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Compliance is not applicable to API calls.
 *  $FILES$
 *      Library is rtl
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_mathResetError()
 *  $CATEGORY$
 *      Math API
 *  $ONELINER$
 *      reset the internal math error information structure
 *  $SYNTAX$
 *      C Prototype
 *      
 *      #include <hbmath.h>
 *      hb_mathResetError (void) --> void
 *  $ARGUMENTS$
 *      
 *  $RETURNS$
 *      
 *  $DESCRIPTION$
 *      
 *  $EXAMPLES$
 *      
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Compliance is not applicable to API calls.
 *  $FILES$
 *      Library is rtl
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_mathIsMathErr()
 *  $CATEGORY$
 *      Math API
 *  $ONELINER$
 *      check if harbour math error handling is available
 *  $SYNTAX$
 *      C Prototype
 *      
 *      #include <hbmath.h>
 *      hb_mathIsMathErr (void) --> int iIsMathHandler
 *  $ARGUMENTS$
 *      
 *  $RETURNS$
 *      
 *  $DESCRIPTION$
 *      
 *  $EXAMPLES$
 *      
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Compliance is not applicable to API calls.
 *  $FILES$
 *      Library is rtl
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_mathSetHandler()
 *  $CATEGORY$
 *      Math API
 *  $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$
 *      Compliance is not applicable to API calls.
 *  $FILES$
 *      Library is rtl
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_mathGetHandler()
 *  $CATEGORY$
 *      Math API
 *  $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$
 * 
 *  $DESCRIPTION$
 *      
 *  $EXAMPLES$
 *      
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Compliance is not applicable to API calls.
 *  $FILES$
 *      Library is rtl
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_mathSetErrMode()
 *  $CATEGORY$
 *      Math API
 *  $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 math.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$
 *      Compliance is not applicable to API calls.
 *  $FILES$
 *      Library is rtl
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      hb_mathGetErrMode()
 *  $CATEGORY$
 *      Math API
 *  $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$
 *      Compliance is not applicable to API calls.
 *  $FILES$
 *      Library is rtl
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      MATHERRMODE()
 *  $CATEGORY$
 *      Math
 *  $ONELINER$
 *      Set/Get math error handling mode
 *  $SYNTAX$
 *      MATHERRMODE ([<nNewMode>]) -> <nOldMode> 
 *  $ARGUMENTS$
 *      [<nNumber>]   new math error handling mode, one of the following constants, defined in math.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$
 *      Library is rtl
 *  $SEEALSO$
 *      
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      MATHERRORBLOCK()
 *  $CATEGORY$
 *      Math
 *  $ONELINER$
 *      Set/Get math error handling codeblock
 *  $SYNTAX$
 *      MATHERRORBLOCK ([<bNewBlock>]) -> <bOldBlock> 
 *  $ARGUMENTS$
 *  $RETURNS$
 *  $DESCRIPTION$
 *  $EXAMPLES$
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      
 *  $END$
 */



