harbour-core/harbour/doc/en/math.txt

/*
 * $Id$
 */

/*
 * 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-Cl*pper 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-Cl*pper 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-Cl*pper 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-Cl*pper 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-Cl*pper 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-Cl*pper 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-Cl*pper 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-Cl*pper 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-Cl*pper 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 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$
 *
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Compliance is not applicable to API calls.
 *  $FILES$
 *      Header file is hbmath.h
 *      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$
 *      Header file is hbmath.h
 *      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$
 *      Header file is hbmath.h
 *      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$
 *      Header file is hbmath.h
 *      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$
 *      Header file is hbmath.h
 *      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 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$
 *      Compliance is not applicable to API calls.
 *  $FILES$
 *      Header file is hbmath.h
 *      Library is rtl
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      hb_mathGetErrMode()
 *  $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$
 *      Header file is hbmath.h
 *      Library is rtl
 *  $PLATFORMS$
 *      All
 *  $SEEALSO$
 *      hb_mathSetErrMode()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      HB_MATHERMODE()
 *  $CATEGORY$
 *      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 rtl
 *  $SEEALSO$
 *
 *  $END$
 */

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