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