Numeric Functions
Updated: July 28, 2012
Return numeric result r based on applicable numeric or string arguments.
Arguments are described as "string", "number" (any type), "integer"
(INTEGER, LONG, DWORD) and "immediate" number like "0" or "1".
Please refer to the FPU object for other numerical methods.
Function Arguments, Comments, Examples
~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@, VARPTR Returns DWORD address of argument
Addr = @MySUB: Addr = @MySTRING: Addr = @MyMEMORY
Addr = VARPTR(MySUB): Addr = VARPTR(MySTRING): Addr = VARPTR(MyMEMORY)
Used for certain arguments in API calls or in MEMCPY, MEMCMP, etc.
For Arrays, omit subscripts and note: A.Pointer = @A
If you need the address of an element in the array, several methods work,
Addr = @A + offset 'you compute your offset, or try
x=A(i,j,k): Addr = @A + A.Position - SIZEOF(A)
For UDT's, you can use @MyType.MemberItem syntax
ABS Absolute value, r = ABS(number)
ACOS Arc cosine, r = ACOS(number)
ARRAYREF +
Reads numeric array value based on a pointer to the array object
and the element subscripts.
r = ARRAYREF(lpArrayObject, subscripts)
where lpArrayObject is obtained with the OBJPTR() Numeric Function and
subscripts is a comma-delimited list of numeric values as might be used in
reading a conventional array value.
DIM A(99,99) As LONG
DEFINT Aptr = OBJPTR(A)
DEFINT i, j
'code to get value for i and j
r = ARRAYREF(Aptr,i,j) 'same as r = A(i,j)
Notice you can pass an OBJPTR() value as an argument to a procedure which
may read/write array values based on a pointer, not the dimensioned name of
the array.
Please see the ARRAYREF() statement in Advanced Techniques.
ASC ASCII value of first character, r = ASC(string)
ASIN Arc sine, r = ASIN(number)
ATAN, ATN Arc tangent, r = ATAN(number) 'or ATN(number)
ATN Same as ATAN
BOOLEAN, BOOL +
Boolean value (1,0) of expression
r = BOOLEAN(x1 = x2)
r = BOOLEAN(a$ >= b$)
BYREF + Gets value at address. r = BYREF(address)
Please see the related BYREF statement in Advanced Techniques.
BYTESWAP Reverses byte order in 32-bit, non-floating values i.
r = BYTESWAP(i) 'i is variable or expression
Please see the BYTESWAP statement for more details.
CALLBACK, CODEPTR
Returns DWORD address of SUB or LABEL (please see GOSUB)
CEIL Round up to positive infinity; r = CEIL(number)
[Change Sign]
FPU.load r: FPU.chs: r = FPU.pop; please see NEG().
CINT, CLNG, ROUND
Convert to integer by round method; r = ROUND(number)
CLNG Same as CINT
CODEPTR Same as CALLBACK
COMMANDCOUNT
Number of command line arguments; r = COMMANDCOUNT
COS Cosine of number in radians; r = COS(number)
CPUCOUNT Number of processors on machine; r = CPUCOUNT
CPUCOUNT is part of HotBasic's Multi-Threading (MT), Multi-CPU support.
CREATEOBJ Creates new FORM object and returns its handle; r = CREATEOBJ(EDIT)
CREATEOBJ() should be used after DIM/CREATE of the first FORM (main form of
a GUI application). Any FORM object may be created (e.g., EDIT above) and its
.Parent is the last FORM dimensioned (or the main form if the application
has only one FORM object). At present, if the CREATEOBJ function is used,
HotBasic allocates RAM for up to 100 objects. A future release may remove
this limit.
CREATETHREAD(lpFunc, lpParam)
Syntax: ThreadID = CREATETHREAD(lpFunc, lpParam)
where lpFunc is CODEPTR(Proc_Name) and lpParam is the address of a
variable or UDT with the procedure's parameters.
For more detail, please see the "Threads" topic.
CSRLIN Current cursor line; r = CSRLIN: LOCATE CSRLIN,21
DIREXISTS TRUE if DIREXISTS(string)
IF NOT DIREXISTS(string) THEN MKDIR string
EAX Same as RETFUNC
EXP Exponential function; e raised to the power of number;
r = EXP(number)
FALSE Same as ZERO
FILEEXISTS TRUE if FILEEXISTS(string)
DIM F As FILE
IF FILEEXISTS(string) THEN F.OPEN(string,2) ELSE F.OPEN(string,65535)
FIX, INT Largest integer less than or equal to number; r = INT(number)
FLOOR Round down to negative infinity; r = FLOOR(number)
FRAC Fractional part of number; r = FRAC(number)
GETGTK Gets integer value for property of FORM object by handle
r = GETGTK(handle, string property)
Linux GTK-mode only; example: r = GETGTK(myEdit,"editable")
GETLASTERROR
W32 API GetLastError; r = GETLASTERROR
HCOS Hyperbolic cosine of number in radians; r =HCOS(number)
HEX2DW Convert hex string; r = HEX2DW("3CFF") or HEX2DW(string)
HIWORD High word of 32-bit value; r = HIWORD(number)
HSIN Hyperbolic sine of number in radians; r =HSIN(number)
HTAN Hyperbolic tangent of number in radians; r =HTAN(number)
IADD Integer addition; r = IADD(int1, int2) where int1 is a variable.
IAND Integer AND logic; r = IAND(int1, int2) where int1 is a variable.
IDIV Integer division; r = IDIV(int1, int2) where int1 is a variable.
IIF + Evaluates expression and returns either number1 (true) or
number2 (false). r = IFF(expression, number1, number2)
r = IIF(2 > 1, TRUE, FALSE) 'returns TRUE (1)
r = IIF(a$ > b$, 1, 0)
Note: There is an IIF$ string function (please see String Functions).
IMOD Integer divide remainder; r = IMOD(int1, int2) where int1 is a
variable.
IMUL Integer multiplication; r = IMUL(int1, int2) where int1 is a variable.
INP Byte read from I/O port number 0 to 65535; r = INP(integer)
INPW Word read from I/O port number 0 to 65535; r = INPW(integer)
INSTR Position of string2 in string1 starting at optional 1-based integer
position;
r = INSTR([integer,] string1, string2)
IF INSTR(name$,letter$) THEN PRINT letter$; " was found in "; name$
Above, INSTR(name$,letter$) is the same as INSTR(1,name$,letter$).
Note: string values may be dimensioned As STRING, As LIST or As MEMORY
INT Same as FIX
IOR Integer OR logic; r = IOR(int1, int2) where int1 is a variable.
ISHL Integer multiplication by a power of 2; r = ISHL(int1, immediate)
where immedite is an integer literal (1 to 31).
ISHR Integer division by a power of 2; r = ISHR(int1, immediate)
where immedite is an integer literal (1 to 31).
Note: immediate values above are 1 to 31. Your code, where prudent,
should check for overflow (incorrect result) with IMUL and ISHL.
For the "I" Integer functions, HotBasic error checks that the int1 argument
is a dimensioned INTEGER (alias LONG) variable.
ISUB Integer subtraction; r = ISUB(int1, int2) where int1 is a variable.
IXOR Integer XOR logic; r = IXOR(int1, int2) where int1 is a variable.
LBOUND Lower bound of ARRAY subscript index; r = LBOUND(ARRAY, integer)
DIM A(10, 20, 10) As LONG: r = LBOUND(A, 2) 'r = 0 for second subscript
LEN Length of non-unicode text; r = LEN(string)
IF string.Length <> LEN(string) THEN PRINT "String is binary or unicode?"
LEN() is needed only for strings returned by third-party software, such as
APIs. Strings dimensioned and assigned in HotBasic code are objects where
the .Length property always stores the STRING/MEMORY/LIST length.
LN Natural logarithm; r = LN(number)
LNTWO Natural log of 2; r = LNTWO
LOG Logarithm base 10; r = LOG(number)
LOG2E Logarithm base 2 of e; r = LOG2E
LOG2TEN Logarithm base 2 of 10; r = LOG2TEN
LOGTWO Logarithm base 10 of 2; r = LOGTWO
LOWORD Low word of 32-bit value; r = LOWORD(number)
MEMCMP Compares nbytes at addr1 and addr2
r = MEMCMP(addr1, addr2, nbytes) where nbytes, addr1 and addr2 are integers.
r = 0 if equal, r = 1 if addr1 data > addr2 data and r = -1 if addr1 < addr2
HotBasic uses MEMCMP in evaluating string comparisons like
IF j$ >= k$ THEN ... However, behind the scenes, the compiler provides
a fourth parameter so MEMCMP has two pointers and two lengths, so "ABCDEF"
is said to be greater than "ABC" and "AACDEF" is less than "ABC".
Therefore, if your strings are of different length, use IF ... THEN instead.
Don't worry, the strings don't have to be text-only data.
r = MEMCMP(@string1, @string2, string1.Length) 'or string2.Length if lesser.
r = MEMCMP(@var1, @var2, 8) 'compares 8 bytes of data.
Note:
RapidQ Basic returns 0 for *not* equal;
HotBasic returns 1 or -1 for *not* equal.
IF MEMCMP(@var1, @var2, 8) THEN PRINT "var1 is not equal to var2"
MESSAGEBOX Returns user response to message box.
r = MESSAGEBOX string1, string2, integer
where string1 is message, string2 is title and integer is messagebox
style bit mask (0 is just "OK"). A partial listing of mask bits:
$DEFINE MB_OK 0
$DEFINE MB_OKCANCEL 1
$DEFINE MB_ABORTRETRYIGNORE 2
$DEFINE MB_YESNOCANCEL 3
$DEFINE MB_YESNO 4
$DEFINE MB_RETRYCANCEL 5
$DEFINE MB_ICONHAND &H10
$DEFINE MB_ICONQUESTION &H20
$DEFINE MB_ICONEXCLAMATION &H30
$DEFINE MB_ICONASTERISK &H40
$DEFINE MB_USERICON &H80
User response (function success) is coded as a non-zero r:
1 OK
2 Cancel
3 Abort
4 Retry
5 Ignore
6 Yes
7 No
8 Close
9 Help
[NAPIER] Napier value e from FPU; FPU.napier: r = FPU.pop
NEG, - Negates value; r = NEG(x) 'same as -(x)
NOT Boolean NOT; r = not(j) 'r = 0 if j <> 0; r = 1 if j = 0
Note: useful to toggle flag variables "on" and "off"; iFLAG = not(iFLAG)
OBJPTR + Pointer of array object; r = OBJPTR(a) 'a is dimensioned array
Please see the ARRAYREF family of keywords for usage example.
ONE, TRUE One, faster than "1"; r = ONE: r = ONE/x
TRUE is merely an alias for ONE. Logical True is not zero and therefore
is not necessarily = 1. Therefore, write:
IF MyValue THEN 'rather than IF MyValue = TRUE THEN
PI Pi as stored by the FPU; r = PI: r = 2*PI*r^2: r = ONE/PI
POS, POS() Cursor column position; r = POS: LOCATE line,POS
POSTMESSAGE hWnd, uMsg, wParam, lParam; where all arguments are integers.
Used to send message to hWnd object. Please see SENDMESSAGE below.
Sends message and does not wait for the message to be processed.
RESOURCE Used as argument in EXTRACTRESOURCE; RESOURCE(immediate)
RESOURCECOUNT
Number of resources in executable; r = RESOURCECOUNT
RETFUNC, EAX
MyVar = RETFUNC; assigns value of CPU eax register to MyVar.
Using alias, MyVar = EAX
Used to get result of a function in an external .obj or .dll module or the OS.
Normally, one declares the function with LIB and writes:
MyVar=DeclaredFunction(args,...)
That is, it works just like the function was in your program.
An alternative is:
Call[Func] SomeProcedure[Addr]
MyVar = RETFUNC 'now we have the result of SomeProcedure
Also, advanced programmers may want to call a callback procedure they wrote.
RGB Convert red, green, blue values to RGB value;
r = RGB(red_integer, green_integer, blue_integer)
r = RGB(255, 0, 0) 'red with r = &H0000FF
r = RGB(0, 0, 255) 'blue and r = &HFF0000
RND Random integer between 0 and integer; r = RND(integer)
Without argument, random floating value 0 to 1; r = RND
ROUND Same as CINT
SCREEN ASCII value of character; r = SCREEN(row_integer, col_integer)
SGN Sign; r = SGN(number) '1 positive, 0 zero, -1 negative
SENDMESSAGE hWnd, uMsg, wParam, lParam; where all arguments are integers.
Used to send message to hWnd object. Uses SendMessageA w32 function.
Sends message and waits for the message to be processed.
r = SendMessage(MyForm, MyMessage, MyParam1, MyParam2)
Each GUI object has many valid messages which set or get values or
properties. This is a "work-horse" function in GUI programming.
Please see HBguidef.inc in HotInclude and Objects > FORM Objects.
SHELL r = SHELL cmd$; where r is exit code of cmd$
If pipe symbols are used in cmd$, then "command.com /c" or "cmd.exe /c" may
have to be added as a prefix to cmd$.
SIN Sine of number in radians; r = SIN(number)
SIZEOF Length in bytes of object
r = SIZEOF(MyUDT): r = SIZEOF(variable)
For ARRAYs, returns element size. MyArray.Length gives total length.
For strings, MyString.Length gives length even for binary data.
SQR Square root; r = SQR(number)
TALLY Count of number of string2 in string1;
r = TALLY(string1, string2)
r = TALLY(s$,CRLF) 'r now has line count and if s$ is LIST, r = item count!
IF TALLY(s$,CHR$(0)) THEN
PRINT "Hey, what are null chars doing in my string?"
PRINT "Reply: hmmm, did you get that from a socket?"
END IF
TAN Tangent; r = TAN(number) where number is an X/Y value.
TIME Nano-seconds in epoch since Jan 1, 1970; r = TIME / 10000000 gives
seconds in epoch. For r = TIME, r should be an INT64 variable,
which is equivalent to a Windows FILETIME value. That is, @r (the
address of r) is the same as a pointer to a FILETIME value.
TIMER Returns floating number of seconds since computer booted;
r = TIMER
Microsoft states: "the time will wrap around to zero if Windows is run
continuously for 49.7 days." A common technique is to time intervals:
DEFDBL SavedTimer
'code
IF TIMER - SavedTimer > 8.0 THEN 'True if 8 sec have elapsed
'code for task to do
END IF
However, after TIMER "wrap around to zero", TIMER _will not_ be greater
than SavedTimer. Thus, for programs that time events with this simple
method, each SavedTimer value must be checked for "wrap around" first:
IF SavedTimer > TIMER THEN SavedTimer = TIMER 'reset after wrap around
For programs that run for a long time or "for ever", this wrap around
test prevents hang up or failure to execute the timed task.
TRUE Same as ONE; use only as alias for ONE, not as logical true.
UBOUND Upper bound of ARRAY subscript index; r = UBOUND(ARRAY, integer)
DIM A(10, 20, 10) As LONG: r = UBOUND(A, 2) 'r = 20 for second subscript
VAL Value of string representation of number; r = VAL(string)
Note: An invalid string should return a zero result which may be ambiguous.
Conclusion: User code should check the validity of string data arguments.
The Val() function may be used to enter scientific notation:
DEFREAL10 alpha = VAL("7.2973525698E-3") 'coupling constant
VARIANTREF
Accesses VARIANT data by pointer; r = VARIANTREF(integer)
where integer is a pointer to a VARIANT.
VariantRef() reads VARIANT data by reference, useful when functions in other
modules may provide a result as a pointer to VARIANT.
VARPTR Same as @
VARTYPE Type of dimensioned variable; r = VARTYPE(MyVar) where
r = 0 (non-float number), 1 (floating number), 2 (string), 3 (variant)
WAITTHREAD
Gets thread completion status; r = WAITTHREAD(ThreadID)
where ThreadID is the result of the CREATETHREAD function.
The boolean result r is true if the thread is still running.
WINDOW + Gets FORM object numeric property by object handle.
r = WINDOW(handle).Left 'get property
Syntax: WINDOW(handle[,qualified_type]).property
The optional qualified_type argument is needed in special cases where the
compiler needs this information to generate special code in your application.
If handle alone does not work, add the qualified type.
ZERO
Zero, faster than "0"; r = ZERO; IF r = ZERO THEN
+ Penthouse (registered) version
Copyright 2003-2007 James J Keene PhD
Original Publication: Oct 8, 2003