NUMERIC

Function ABS()

 ABS(<nExp>) --> nPositive

ABS() is a numeric function that determines the magnitude of a numeric value independent of its sign. It lets you, for example, obtain the difference between two numbers as a positive value without knowing in advance which of the two is larger.

As a formalism, ABS(x) is defined in terms of its argument, x, as follows: if x >= 0, ABS(x) returns x; otherwise, ABS(x) returns the negation of x.

  These examples show typical results from ABS():
 
 nNum1 := 100
 nNum2 := 150
 ? nNum1 - nNum2                  // Result: -50
 ? ABS(nNum1 - nNum2)             // Result: 50
 ? ABS(nNum2 - nNum1)             // Result: 50
 ? ABS(-12)                       // Result: 12
 ? ABS(0)                         // Result: 0
 
 

Function BIN2I()

 BIN2I(<cSignedInt>) --> nNumber

BIN2I() is a low-level file function that is used with FREAD() to convert a two-byte character string formatted as a signed integer to a xClipper numeric data type. This is most useful when you are reading foreign file types and want to read numeric data in its native format.

  This example opens a database file using low-level file
 functions and reads the date of last update (bytes 1-3).  The result
 is the same as with LUPDATE():
 
 #include "Fileio.ch"
 //
 nHandle := FOPEN("Sales.dbf", FO_READ)
 //
 // Point to byte 1 in the file
 FSEEK(nHandle, 1, FS_SET)
 //
 // Read date of last update
 nYear := BIN2I(FREADSTR(nHandle, 1) + CHR(0))
 nMonth := BIN2I(FREADSTR(nHandle, 1) + CHR(0))
 nDay := BIN2I(FREADSTR(nHandle, 1) + CHR(0))
 //
 ? LTRIM(STR(nMonth)), LTRIM(STR(nDay)), LTRIM(STR(nYear))
 FCLOSE(nHandle)

Function BIN2L()

 BIN2L(<cSignedInt>) --> nNumber

BIN2L() is a low-level file function that is used with FREAD() to convert a four-byte character string formatted as a signed integer to a xClipper numeric data type. This is most useful when you are reading foreign file types and want to read numeric data in its native format.

 This example opens a database file using low-level file
 functions and reads the number of records (bytes 4-7).  The result is
 the same as with LASTREC():
 
 #include "Fileio.ch"
 //
 nHandle := FOPEN("Sales.dbf", FO_READ)
 // Note:  Sales.dbf contains 84 records
 //
 // Point to byte 4
 FSEEK(nHandle, 4, FS_SET)
 //
 // Read the number of records
 cRecords := SPACE(4)
 FREAD(nHandle, @cRecords, 4)
 //
 ? LTRIM(STR(BIN2L(cRecords)))         // Result: 84
 FCLOSE(nHandle)

Function BIN2W()

 BIN2W(<cUnsignedInt>) --> nNumber

BIN2W() is a low-level file function that is used with FREAD() to convert a two-byte character string formatted as an unsigned integer to a xClipper numeric data type. This is most useful when you are reading from a binary file and want to read data in its native format.

 This example opens a database file using low-level file
 functions and reads the number of bytes per record (bytes 10-11).
 The result is the same as with RECSIZE():
 
 #include "Fileio.ch"
 //
 nHandle := FOPEN("Sales.dbf", FO_READ)
 // Note:  The length of a record in Sales.dbf is 124
 //
 // Point to byte 10, the first record size byte
 FSEEK(nHandle, 10, FS_SET)
 //
 // Read record size
 cRecSize := SPACE(2)
 FREAD(nHandle, @cRecSize, 2)
 //
 ? LTRIM(STR(BIN2W(cRecSize)))            // Result: 124
 FCLOSE(nHandle)

Function EXP()

 EXP(<nExponent>) --> nAntilogarithm

EXP() is a mathematical function that calculates the value, y, (the antilogarithm) of the following equation,

e**x = y

where e is the base of natural logarithms (2.71828...) and x is <nExponent>. The maximum value of <nExponent> is 45 before a numeric overflow occurs. EXP() and LOG() are inverse functions.

The number of decimal places displayed is determined solely by SET DECIMALS regardless of the current SET FIXED value.

 This example demonstrates several invocations of EXP():
 
 ? EXP(1)                       // Result: 2.72
 SET DECIMALS TO 10
 ? EXP(1)                       // Result: 2.7182818285
 ? LOG(EXP(1))                  // Result: 1.0000000000

Function FT_GCD()

 FT_GCD( <nNumber1>, <nNumber2> ) --> nGCD

This function calculates the greatest common divisor between 2 numbers, i.e., the largest number that will divide into both numbers evenly. It will return zero (0) if either number is zero.

 ? FT_GCD(10,15)                  // Result: 5
 ? FT_GCD(108,54)                 // Result: 54
 ? FT_GCD(102,54)                 // Result: 6
 ? FT_GCD(111,17)                 // Result: 1

Function FT_NETPV()

 FT_NETPV( <nInitialInvestment>, <nInterestRate>, <aCashFlow> ;
 [, <nNoOfCashFlows> ] ) --> nNetPV

This function calculates the net present value, the difference between the cost of an initial investment and the present value of the expected cash flow(s) from the investment. The present value of the expected cashflow(s) is calculated at the specified interest rate, which is often referred to as the "cost of capital".

This function can be used to evaluate alternative investments. The larger the NPV, the more profitable the investment. See also the FutureValue and PresentValue for further explanations. The formula to calculate the net present value is:

NetPresentValue = SUM(CashFlow[i] / ((1 + InterestRate) ** i)) FOR i = 1 TO NoOfCashFlows

 nNetPresentValue := FT_NETPV(10000, 10, { 10000,15000,16000,17000 } )

Function FT_RAND1()

 FT_RAND1( <nMax> ) --> nRand

Generates a non-integer random number based on the Linear Congruential Method.

If you need a random number between 1 and <nMax> inclusive, INT() the result and add 1.

If you need a random number between 0 and <nMax> inclusive, then you should ROUND() the result.

 nResult := INT( FT_RAND1(100) ) + 1    // 1 <= nResult <= 100
 nResult := ROUND( FT_RAND1(100), 0 )   // 0 <= nResult <= 100
 nResult := FT_RAND1( 1 )               // 0 <= nResult < 1

Function FT_ROUND()

 FT_ROUND( <nNumber> [, <nRoundToAmount>           ;
 [, <cRoundType>  [, <cRoundDirection>   ;
 [, <nAcceptableError> ] ] ] ] )           --> nNumber

This function will allow you to round a number. The following can be specified: a. Direction (up, down or normal - normal is 4/5 convention) b. Type (whole, decimal, fraction) c. Amount (100's, 5 decimals, 16th, etc.)

 // round normal to 2 decimal places
 nDollars := FT_ROUND(nDollars)
 
 // round normal to 6 decimal places
 nIntRate := FT_ROUND(nIntRate, 6)
 
 // round to nearest thousands
 nPrice   := FT_ROUND(nPrice, 3, NEAREST_WHOLE_NUMBER)
 
 // round Up to nearest third
 nAmount  := FT_ROUND(nAmount, 3, NEAREST_FRACTION, ROUND_UP)
 
 // round down to 3 decimals Within .005
 nAvg     := FT_ROUND(nAvg, 3, , ROUND_DOWN, .005)

Function I2BIN()

 I2BIN(<nInteger>) --> cBinaryInteger

I2BIN() is a low-level file function that converts an integer numeric value to a character string formatted as a binary integer--least significant byte first. I2BIN() is used with FWRITE() to convert a xClipper numeric to a standard binary form. The inverse of I2BIN() is BIN2I().

 This example opens a database file using low-level file
 functions and writes a new date of the last update to bytes 1-3:
 
 #include "Fileio.ch"
 //
 nHandle = FOPEN("Sales.dbf", FO_READWRITE)
 //
 // Convert date of last update to int
 nYear = I2BIN(90)
 nMonth = I2BIN(12)
 nDay = I2BIN(15)
 //
 // Point to the date of last update
 FSEEK(nHandle, 1, FS_SET)
 //
 // Write the new update date using only the first byte
 FWRITE(nHandle, nYear, 1)
 FWRITE(nHandle, nMonth, 1)
 FWRITE(nHandle, nDay, 1)
 FCLOSE(nHandle)

Function INT()

 INT(<nExp>) --> nInteger

INT() is a numeric function that converts a numeric value to an integer by truncating--not rounding--all digits to the right of the decimal point. INT() is useful in operations where the decimal portion of a number is not needed.

  These examples demonstrate the results of various invocations
 of the INT() function:
 
 ? INT(100.00)               // Result: 100
 ? INT(.5)                     // Result: 0
 ? INT(-100.75)               // Result: -100
 
 

Function L2BIN()

 L2BIN(<nExp>) --> cBinaryInteger

L2BIN() is a low-level file function used with FWRITE() to write xClipper numeric values to a binary file. This function is like I2BIN() which formats a xClipper numeric to a 16-bit binary value.

L2BIN() is the inverse function of BIN2L().

 This example creates a new binary file, and then writes a
 series of numbers to the files using L2BIN() to convert the numeric
 value to 32-bit binary form:
 
 #include "Fileio.ch"
 //
 LOCAL nNumber, nHandle
 nHandle := FCREATE("MyFile", FC_NORMAL)
 FOR nNumber := 1 TO 100
 FWRITE(nHandle, L2BIN(nNumber) + CHR(0))
 NEXT
 FCLOSE(nHandle)

Function LOG()

 LOG(<nExp>) --> nNaturalLog

LOG() is a numeric function that calculates the natural logarithm of a number and is the inverse of EXP(). The natural logarithm has a base of e which is approximately 2.7183. The LOG() function returns x in the following equation,

e**x = y

where y is the numeric expression used as the LOG() argument (i.e., LOG(y) = x). Due to mathematical rounding, the values returned by LOG() and EXP() may not agree exactly (i.e., EXP(LOG(x)) may not always equal x).

 These examples demonstrate various results of LOG():
 
 ? LOG(10)                  // Result: 2.30
 ? LOG(10 * 2)            // Result: 3.00
 ? EXP(LOG(1))            // Result: 1.00
 ? LOG(2.71)               // Result: 1.00
 
 This example is a user-defined function that returns the base
 10 logarithm:
 
 FUNCTION Log10( nNumber )
 IF nNumber > 0
 RETURN LOG(nNumber)/LOG(10)
 ELSE
 RETURN NIL
 ENDIF

Function MAX()

 MAX(<nExp1>, <nExp2>) --> nLarger
 MAX(<dExp1>, <dExp2>) --> dLarger

MAX() is a numeric and date function that ensures the value of an expression is larger than a specified minimum. The inverse of MAX() is MIN(), which returns the lesser of two numeric or date values.

 In these examples MAX() returns the greater of two numeric
 values:
 
 ? MAX(1, 2)                     // Result: 2
 ? MAX(2, 1)                     // Result: 2
 
 In these examples MAX() compares date values:
 
 ? DATE()                           // Result: 09/01/90
 ? MAX(DATE(), DATE() + 30)         // Result: 10/01/90
 ? MAX(DATE(), CTOD(""))            // Result: 09/01/90

Function MIN()

 MIN(<nExp1>, <nExp2>) --> nSmaller
 MIN(<dExp1>, <dExp2>) --> dSmaller

MIN() is a numeric and date function that ensures the value of an expression is smaller than a specified minimum. The inverse of MIN() is MAX() which returns the greater of two numeric or date values.

 In these examples MIN() returns the smaller of two numeric
 values:
 
 ? MIN(99, 100)                  // Result: 99
 ? MIN(100, 99)                  // Result: 99
 
 In these examples MIN() compares date values:
 
 ? DATE()                        // Result: 09/01/90
 ? MIN(DATE(), DATE() + 30)      // Result: 09/01/90

Function MOD()

 MOD(<nDividend>, <nDivisor>) --> nRemainder

MOD() is a numeric function that emulates the dBASE III PLUS MOD() function.

MOD() is supplied as a compatibility function and therefore not recommended. It is superseded entirely by the modulus operator (%).

Function ROUND()

 ROUND(<nNumber>, <nDecimals>) --> nRounded

ROUND() is a numeric function that rounds <nNumber> to the number of places specified by <nDecimals>. Specifying a zero or negative value for <nDecimals> allows rounding of whole numbers. A negative <nDecimals> indicates the number of digits to the left of the decimal point to round. Digits between five to nine (inclusive) are rounded up. Digits below five are rounded down.

The display of the return value does not obey the DECIMALS setting unless SET FIXED is ON. With SET FIXED OFF, the display of the return value contains as many decimal digits as you specify for <nDecimals>, or zero, if <nDecimals> is less than one.

  These examples round values with decimal digits:
 
 SET DECIMALS TO 2
 SET FIXED ON
 //
 ? ROUND(10.4, 0)                     // Result: 10.00
 ? ROUND(10.5, 0)                     // Result: 11.00
 ? ROUND(10.51, 0)                    // Result: 11.00
 ? ROUND(10.49999999999999, 2)        // Result: 10.50
 
 These examples use a negative <nDecimals> argument to round
 numeric values to whole number values:
 
 ? ROUND(101.99, -1)                  // Result: 100.00
 ? ROUND(109.99, -1)                  // Result: 110.00
 ? ROUND(109.99, -2)                  // Result: 100.00
 
 

Function SQRT()

 SQRT(<nNumber>) --> nRoot

SQRT() is a numeric function used anywhere in a numeric calculation to compute a square root (e.g., in an expression that calculates standard deviation).

 These examples show various results of SQRT():
 
 SET DECIMALS TO 5
 //
 ? SQRT(2)                 // Result: 1.41421
 ? SQRT(4)                 // Result: 2.00000
 ? SQRT(4) ** 2            // Result: 4.00000
 ? SQRT(2) ** 2            // Result: 2.00000