Files
harbour-core/harbour/doc/en/math.txt
Viktor Szakats 0f365f1a5d 2012-07-03 13:14 UTC+0200 Viktor Szakats (harbour syenar.net)
* doc/en/command.txt
  * doc/en/datetime.txt
  * doc/en/dbdelim.txt
  * doc/en/dbsdf.txt
  * doc/en/dbstrux.txt
  * doc/en/dir.txt
  * doc/en/diskspac.txt
  * doc/en/eval.txt
  * doc/en/garbage.txt
  * doc/en/gtslang.txt
  * doc/en/hashes.txt
  * doc/en/hb_api.txt
  * doc/en/hb_apier.txt
  * doc/en/hb_apigt.txt
  * doc/en/hb_apiit.txt
  * doc/en/hb_apiln.txt
  * doc/en/hb_apird.txt
  * doc/en/hb_compa.txt
  * doc/en/hb_date.txt
  * doc/en/hb_macro.txt
  * doc/en/hb_set.txt
  * doc/en/hb_vm.txt
  * doc/en/idle.txt
  * doc/en/input.txt
  * doc/en/lang.txt
  * doc/en/macro.txt
  * doc/en/math.txt
  * doc/en/memo.txt
  * doc/en/memvar2.txt
  * doc/en/misc.txt
  * doc/en/string.txt
  * doc/en/var.txt
    * fixes

  * doc/en/*.txt
    * set mime-type to UTF-8
2012-07-03 11:20:27 +00:00

744 lines
16 KiB
Plaintext

/*
* $Id$
*/
/*
* The following parts are Copyright of the individual authors.
* www - http://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 API
* $SUBCATEGORY$
* Math functions
* See COPYING 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 rtl
* $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 rtl
* $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 DECIMAL TO 5
* ? INT( 632512.62541 )
* ? INT( 845414111.91440 )
* $STATUS$
* R
* $COMPLIANCE$
* C
* $PLATFORMS$
* All
* $FILES$
* Library is rtl
* $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 rtl
* $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( STOD( "20001111" ), STOD( "20140621" ) )
* $STATUS$
* R
* $COMPLIANCE$
* C
* $PLATFORMS$
* All
* $FILES$
* Library is rtl
* $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( STOD( "20001111" ), STOD( "20140621" ) )
* $STATUS$
* R
* $COMPLIANCE$
* C
* $PLATFORMS$
* All
* $FILES$
* Library is rtl
* $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 rtl
* $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 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$
* C
* $PLATFORMS$
* All
* $FILES$
* Library is rtl
* $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 rtl
* $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 rtl
* $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 rtl
* $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 rtl
* $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 rtl
* $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 rtl
* $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 rtl
* $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 rtl
* $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 rtl
* $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 rtl
* $SEEALSO$
*
* $END$
*/