AMCAF provides a vast number of useful functions to assist with integer math and string manipulation.

- =Binexp
- =Binlog
- =Lsl
- =Lsr
- =Wordswap
- =Qarc
- =Qsin
- =Qcos
- =Qrnd
- =Qsqr
- =Asc.w
- =Asc.l
- =Vclip
- =Vin
- =Vmod
- =Even
- =Odd
- =Pattern Match
- =Chr.w$
- =Chr.l$
- =Lzstr$
- =Lsstr$
- =Insstr$
- =Cutstr$
- =Replacestr$
- =Itemstr$

**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"