Blitz:Numerical Functions

Blitz Basic / AmiBlitz provides many numerical functions to evaluate certain properties or carry out certain mathematical operations. Most of these will be very familiar to anyone who has programmed before. Note that in the examples given, numbers are used as the inputs for clarity, however a variable or expression can always be used instead.

Basic Arithmetic

The simplest numerical operations are the basic mathematical functions such as add and subtract. These are used in an expression using + for add, - for subtract, * for multiply and / for divide:

a = 2 + 5  ; a is 7

b = 3 - 5  ; b is -2

c = 2 * 8  ; c is 16

d = 10 / 2 ; d is 5

Blitz follows the standard conventional order used in the real world for carrying out the calculation:

• Brackets
• Powers
• Multiplication & Division
• Addition and Subtraction

Calculations are evaluated going from left to right with operators of equal priority as normal. Placing brackets around any expression allows you to change the normal priority:

a = 3 + 2 * 5   ; a is 13

b = (3 + 2) * 5 ; b is 25

It is also possible to nest bracketed expressions, with the innermost brackets getting the highest priority:

a = (3 + 2) * ((5 - 3) * 2) ; a is 20

Powers are represented by the ^ symbol:

a = 2 ^ 3 ; a is 8

Fractions / Floats

Fractions are called floating point numbers in computer terms. Only certain variable types can store floating point numbers. More details on variable types are available at the linked page, but for now just remember that if a float is stored in a variable that can only store integers, it will not cause an error. Instead, the fractional part is simply lost. This can be a source of much confusion as it can cause bugs that only occur in certain circumstances and are very hard to track down!

a.f = 5 / 2 ; a is a floating point variable and holds the value 2.5

b.w = 5 / 2 ; b is a word (integer) variable and holds the value 2

Basically, if you need the fractional part of a calculation, ensure the relevant variables are of a suitable type.

Trigonometry

Blitz includes a number of functions for carrying out trigonometric calculations. These are useful for certain curve and3D calculations, but can be slow to execute.

The basic functions are Sin(), Cos() and Tan(), which return the sin cos and tan of the given value. All parameters are floats, and all values returned are floats too - naturally enough if you don't use a float for the returned value, all you'll get is either 0 or 1:

a.f = Sin(27) ; a is 0.45399......

b.w = Cos(45) ; b is 0 (would be 0.7071.... but an integer type was used for the result)

The functions ASin(), ACos() and ATan() are the ArcSin, ArcCos and ArcTan equivalents of the Sin(), Cos() and Tan() functions. HSin(), HCos() and HTan() are the hyperbolic Sin, Cos and Tan equivalents.

More Arithmetic

Square roots are calculated using the Sqr() function:

a.f = Sqr(27) ; a is 9

The Exp() function returns the e value raised to the power of the given argument:

a.f = Exp(5) ; a is 148.413....

The inverse of this is the Log() function, which returns the natural log (base e) of the given value:

a.f = Log(20) ; a is 2.9957.....

The base 10 equivalent is the Log10() function.

Other Functions

To get the absolute value of a number, use the Abs() function. This simply removes any negative sign from the number:

a = Abs(10)  ; a is 10

b = Abs(-10) ; b is also 10

Int() and Frac() return the integer and fractional sections of a float:

a.f = Int(3.14)  ; a is 3

b.f = Frac(3.14) ; b is 0.14

Alternative "quick" versions of the Abs() and Frac() functions are available. These are faster to execute than the standard commands on non-FPU systems, but are limited to using the quick variable type. They may also be slower than the floating equivalents on an FPU-equipped machine. These functions are QAbs() and QFrac().

Random numbers can be generated using the Rnd() function. With no arguments, this returns a fractional number between 0 and 1. With an argument, this returns a value between 0 and the number given:

 a.f = rnd() ; a is somewhere between 0 and 1

b.f = rnd(6) ; b is a float between 0 and 6, e.g. 2.264

c.b = rnd(6) ; c is a random integer between 0 and 5 inclusive, since the fractional part is dropped for an integer type

Wrapping and limiting numbers based on a given range can be done using the QWrap and QLimit functions. These can only be used on quick types:

a = QWrap(22, 10, 20)

This wraps the first number based on the second and third parameters as the low and high limits. If the first value is between the two limits, just that value is returned. If it's above or below the limits it will be wrapped around to the other end of the limit. So, in the example above a will contain 12, since 22 is above 20 by 2 so 2 is added onto the lower limit. QLimit works the same way except the value returned will be the relevant limit if it's exceeded:

a = QLimit(22, 10, 20)

In this case, a is 20.

The Sgn() function can be used to easily determine the sign of a value. It returns 0 if the value given is 0, -1 if the value is negative and +1 if the value is positive:

a = Sgn(-17) ; a is -1

b = Sgn(0)   ; b is 0

c = Sgn(21)  ; c is 1

Numbers Stored as Strings

Numbers can be stored as strings if required for certain functions that require strings for their arguments, but internally, strings cannot be used as values for calculations. Functions are available to convert values to strings and vice versa as required.

To convert a numerical value to a string, use the Str$() function:

a$ = Str$(42)

In this case, the string variable a$ contains "42" as a string, not as a value. This means it can be used for commands requiring a string, such as opening a file called "42" etc. the string variable a$ can't be used as a numerical value though, so something like a$ + 2 won't work - to the computer it's the same as trying to calculate "Hello" + 2, which is obviously not possible!

To convert a string to a numerical value, the Val() function is used:

a = Val("42")

This will put the value 42 in the variable a so it can be used in normal numerical functions again. If the string contains a non-numerical value, the result will be 0.

Important Note: Val() works fine in Blitz Basic 2.1, however in the latest AmiBlitz it requires an FPU to be fitted and will crash if used on a computer without an FPU. Be very careful of this! The Vallong() function in AmiBlitz can be used instead, but can only convert integer values.

a.l = Vallong("42")