Understanding Arrays in ZScript
v0.1
Author: ZoriaRPG
Part I: Basic Usage
In the simplest context, arrays are a series of variables, stored in memory as one large variable table.
Instead of each individual value occupying memory space, the entire aray (of any given size) uses
the same amount of space as one normal variable.
For example, here we have twelve variables that we would normally store as:
int x = 0;
int y = 1;
int z = 2;
int dir = 3;
bool flying = false;
bool swiming = false;
bool usingRing = true;
int screen = 30;
int dmap = 7;
float spaceFree = 10.30;
int hp = 64;
int keys = 8;
Each of these uses one 'slot' available to us, for a variable.
Instead of using twelve unique variables, we can condense this into one array. Because we have variables of
each of the three main datatypes (bool, int, float), and because of the way ZScript handles both variable types,
and typecasting, we can use one float array for all of them:
float Vars[12]={0,1,2,3,0,0,1,30,7,10.3000,64,8};
In this example, the first index (position Vars[0], holding a value of '0') would take the place of int x; above.
The second, taking the place of int y; is Vars[1], holding a value of '1'.
The third, taking the place of int z; is Vars[2], holding a value of '2'.
The fourth, taking the place of int dir; is Vars[3], holding a value of '4'.
The fifth, was originally a boolean, bool flying;. We have that in Vars[4], the fifth position, with a value of '0'.
Because you can typecase from float/int to boolean, ZC will interpret a '0' here as 'false', and any other value as 'true'.
The sixth, Vars[5], takes the place of bool swimming; Again, the value here is '0' (false).
The seventh, Vars[6], takes the place of usingRing. Here, we've initialised it with a value of '1' (true).
The eigHth, Vars[7] replaces int screen. We've initialised this with a value of '30'.
The ninth, Vars[8], replaces int dmap, and is initialised with a value of '7'.
For the tenth position, Vars[9], is replacing float freeSpace; and holds a value of '10.3000'.
In this case, we're genuinely using a float. Because ZC uses ints and floats interchangably, it's best to use float arrays
so that you may use all three datatypes in the same place.
The eleventh position, Vars[10], replaces int hp;, and is initialised with a value of '64'.
The twelvth, and final position, Vars[11], replaces int keys;, and holds a value of '8'.
Indices:
Positions in an array, are defined as 'indices' (singular: 'index'), a.k.a. 'elements' (singular: 'element').
The first position, is index '0', represented as Vars[0].
The number between the braces is the index number, starting with '0':
An array with 512 indices ( e.g. arr[512] ) will have indices arr[0] through arr[511].
Unfortunately, we don't want to remember all of that on a regular basis. Instead, we want to asign some
constants to these INDEX values:
//Constant Index
const int POS_X = 0;
const int POS_Y = 1;
const int POS_Z = 2;
const int DIR = 3;
const int FLYING = 4;
const int SWIMMING = 5;
const int USINGRING = 6;
const int SCREEN = 7;
const int DMAP = 8;
const int FREESPACE = 9;
const int HP = 10;
const int KEYS = 11;
The constant (on the left), matches the index number, on the right.
Thus, Vars[DIR] == Vars[3]. The number between the braces [ x ] is the index, whereas the corresponding value
between the curly braces, is the value OF that index, so:
float Vars[12]={0,1,2,5,0,0,1,30,7,10.3000,64,8};
Vars[DIR] is INDEX 3, which is the FOURTH position here, holding a value of '5'.
The value of INDEX 9 (Vars[9]), is the tenth position here, and is '10.3000'.
Assigning constants allows us to access information in the array, using that constant, to represent the index
number, so that we never again need to remember it.
Thus, Vars[KEYS] is the same as Vars[11].
Thus, we can wasily make a call using the information int he array, as we would a normal variable:
if ( Vars[SWIMMING] )
would be used, instead of if ( swimming )
...
Of course, sometimes the name of an array can be long, and we don;t always want to type all of that out in detail,
so we instead, use a special function, designed to read into the array, as a shortcut:
float Is(int pos){
return Vars[pos];
}
This function returns the value of Vars[ pos ]. It accepts one argument ('pos') and passes that argument to the return
instruction, so that we may call:
if ( Is(SWIMMING) )
This is identical to calling ( if Vars[SWIMMING] ) because we're passing the constant 'SWIMMING' to the
function as an argument, and it is using that constant when returning the value held in that array index.
Now, that usage is as a boolean, but we can also do:
if ( Is(DMAP) > 20 )
That's a fully valid expression, and because Vars[DMAP] will return a value of '30', the expression is evaluated
as 'true'.
We can also invert this, with a not ( ! , bang ) :
if ( !Is(DMAP) > 20 )
The value held in Vars[DMAP] is still 30, so this would evaluate as 'false'.
Those are some basic models, for using arrays.
Likewise, we can also create a function to store, or change a value in an array:
void UpdateSwimming(float set){
Vars[SWIMMING] = set;
}
Using this:
UpdateSwimming(1);
This changes the value of Vars[SWIMMING] from '0' to '1'.
void AddKey(){
Vars[KEYS]++;
}
//Adds +1 to Vars[KEYS].