AMCAF provides a vast number of useful functions to assist with integer math and string manipulation.
BINEXP
function: return the result of two to the power n
v=Binexp(a)
This function calculates the result of the exponential function 2^a, but is much faster than the normal AMOS expression.
The parameter a must lie between 0 and 31.
Examples: Binexp(1)=2, Binexp(3)=8, Binexp(16)=65536, Binexp(24)=16777216
BINLOG
function: return logarithmic function on a basis of two
a=Binlog(v)
Binlog is the reverse function to Binexp. It returns the logarithm to the
value 'v' with basis 2.
'v' therefore must be a power of 2, otherwise you will get an error.
Binlog is handy to get the number of bitplanes out from the amount of colours of a screen (exception: HAM).
Examples: Binlog(2)=1, Binlog(8)=3, Binlog(65536)=16, Binlog(16777216)=24
LSL
function: return a value as a quick multiplication by a power of two
nv=Lsl(v,n)
Rotates the number 'v' to the left by 'n' bits. I.e that a number 'v', which is shifted one bit to the left contains the value v*2, with two bits v*4, with 3 bits v*8 etc.
This function is very quick and should be used instead of multiplications wherever possible.
LSR
function: return a value as a quick division by a power of two
nv=Lsr(v,n)
LSR shifts a number 'v' to the right by 'n' bits. This function does the same as a division by 2^n, but is much quicker.
WORDSWAP
function: return the swap of the upper and lower 16 bits of a value
newval=Wordswap(value)
This command swaps the upper and the lower Word of a value.
QARC
function: return an angle from the coordinates
angle=Qarc(deltax,deltay)
This function will return the angle to a point at the relative coordinates
deltax,deltay.
Angle is in the same format used with Qsin and Qcos, so an angle of 360 degree is equivalent to 1024.
This function is very fast and rather accurate.
It's normally used for all kinds of 'aiming-at' routines, e.g to get the angle from one player to another to shoot a missile at ;-)
QSIN
function: return a sine of an angle
value=Qsin(angle,radius)
This is a function to replace the original sine function of AMOS.
It is faster and even allows you to multiple the value with the a parameter.
No math libraries are required.
The angle of the sine 'angle' is not a value in radians or degrees, but with Qsin, an angle of
360 degrees equals a value of 1024.
QCOS
function: return the cosine of an angle
value=Qcos(angle,radius)
This is a function to replace the original cosine function of AMOS.
It is faster and even allows you to multiple the value with the a parameter.
No math libraries are required.
The angle of the sine 'angle' is not value in radians or degrees, but with Qcos, an angle of
360 degrees equals a value of 1024.
QRND
function: return a random number
value=Qrnd(maximum number)
Qrnd is totally identical to the Rnd function, with the only difference, that this one is much faster.
QSQR
function: return the square root of a value
root=Qsqr(value)
This function calculates the square root from the value 'value'.
However, it only works with integer and is faster than the AMOS square root function =Sqr.
ASC.W
function: convert a word string into a number
word=Asc.w(word$)
Asc.w is used to convert a word string to a number value. Therefore the result will be between 0 and 65535.
If the length of 'word$' is less than two, the function is aborted and an error message is returned.
ASC.L
function: convert a long string into a number
long=Asc.l(long$)
The Asc.l-function converts a 4 bytes long string back into a number.
This value can range between -2147483648 and +2147483647.
If 'long$' contains less than four characters, you will get an error message immediately.
VCLIP
function: restrict a value to a given range
newval=Vclip(val,lower To upper)
The Vclip function works like a Min(Max(val,lower),upper) expression, it restricts a value val into its lower and upper boundaries.
VIN
function: return a flag to test if a value is within a range
flag=Vin(val,lower To upper)
This function will check if a value lies between lower and upper. If this is the case, flag will return True (-1), otherwise False (0).
VMOD
function: return a value from a modulo operation on a value
newval=Vmod(val,upper)
newval=Vmod(val,lower To upper)
Vmod restricts a value val into the lower and upper boundaries. However,
it does it in another way compared to Vclip.
If val exceeds upper by 1, it will be set to lower, if it exceeds upper by 2, it will be set to
lower+1.
If it goes deeper than lower by 1, it will be set to upper and so on.
So this function is not the same as Add val,delta,lower To upper If lower is omitted, zero is taken as lower boundary. Example: Print Vmod(100,50 To 150) would return 100 (should be clear). Print Vmod(151,50 To 150) would return 50. Print Vmod(152,50 To 150) would return 51. Print Vmod(49,50 To 150) would return 150. Print Vmod(0,50 To 150) would return 101.
EVEN
function: return a flag if a number is even
flag=Even(value)
This function returns True (-1), if a number is even or False (0), if a number is odd.
ODD
function: return a flag if a number is odd
flag=Odd(value)
This function returns True (-1), if a number is odd or False (0), if a number is even.
PATTERN MATCH
function: match a string with a certain pattern
flag=Pattern Match(sourcestring$,pattern$)
Pattern Match checks, if the string 'sourcestring$' matches the pattern 'pattern$'.
If this is the case, then True (-1) will be returned otherwise False (0).
The pattern may contain any regular DOS jokers a asterisk (*) will be converted into '#?' automatically.
This command only works on OS2.0 and higher.
CHR.W$
function: return a two byte string from a number
word$=Chr.w$(word)
This function converts a number into a 2 bytes string.
The upper 16 bits of the value are ignored and therefore you should only use values from 0 to 65535.
CHR.L$
function: return a four byte string from a number
long$=Chr.l$(long)
The Chr.l$ function converts a number into a 4 bytes string. 'long' can be any number you like.
Using this technique, you can save numbers as normal strings.
LZSTR$
function: return a right adjusted number with leading zeros
s$=Lzstr$(v,n)
This function is nearly identical to Lsstr$ with the difference that
leading zeros are not replaced by space characters.
The parameter 'n' sets the number of digits the string should contain and can range from 1 to 10.
LSSTR$
function: return a right adjusted number
s$=Lsstr$(v,n)
Similar to the AMOS function Str$, Lsstr$ creates a string out of a number.
However, with Lsstr$ the number will be created right justified with 'n' digits, leading zeros are replaced by spaces.
The sign of the number will not be printed. 'n' must lie within 1 to 10.
INSSTR$
function: insert the second string into the first string
newstr$=Insstr$(a$,b$,pos)
This function inserts the string b$ at the position pos into string a$.
Example:
Print Insstr$("Hello Ben!","dear ",6) creates 'Hello dear Ben!'.
CUTSTR$
function: cut out a piece of a string
newstr$=Cutstr$(s$,pos1 To pos2)
This function cuts out part of the string s$ from letter position pos1 to pos2.
Example:
Print Cutstr$("Hello dear Ben!",7 To 11) would generate 'Hello Ben!'.
REPLACESTR$
function: replace a string with another one
newstr$=Replacestr$(s$,search$ To replace$)
This function searches in the string s$ for occurrences of search$ and replaces them with the string replace$.
ITEMSTR$
function: returns an item contained in a string
item$=Itemstr$(s$,itemnum)
item$=Itemstr$(s$,itemnum,sep$)
This is a very handy function that helps you to avoid little string arrays
where actually no are required.
s$ contains a number of so called items, which are numbered increasingly from zero onwards.
Normally, the items are separated with a '|' character, but you can give your own single character for separation in the optional string sep$.
Empty strings for s$ are not allowed and will create an error message,
however, empty items can be used without hesitation.
Trying to access an item, that does not exist, will create an error as well.
Example:
Print Itemstr$("Ben|Semprini|Petri|Andy",1) would return 'Semprini'.
Print Itemstr$("The quick brown fox",2," ") would return 'brown'.
Print Itemstr$("zero|one|two||four|five,5) would return 'five'.
Print "The weather is "+Itemstr$("great|fine|nice|not bad|rainy|awful|apocalyptic",WEATHER)
would have a similar effect to:
Dim W$(6)
For A=0 To 6
Read W$(A)
Next
Print "The weather is "+W$(WEATHER)
[...]
Data "great","fine","nice","not bad","rainy","awful","apocalyptic"