
  Arrays tutor
        written by Ironman

=========================================================================

The purpose of this Tutorial is explain the definition and use of arrays.
An array is one of 2 variables that allow information to be indexed easily
within the programs. In other words, storing information without resorting
to the use of a database file like some other programming languages force
us to do (not that databases are not present in the LPC language). The 
other type is called a mapping and will be discussed in it's own tutorial.

DEFINING the array

You may define an array of any datatype. The way this is done is with a *
in the definition line as follows;

string *names;
string* names, dates, places;

The first line defines names as an array of strings. the second line defines
names, dates and places each as string arrrays.

INITIATING the arrays

All arrays start out as a NULL value, meaning they contain NOTHING at all.
The system needs to be told that the variable is going to hold array type
information or ({}). This is done as follows;

string *names;
names=({});

or you can condense the code and do this

string *names=({});

READING an array of information

Reading or affecting the information can be done in two manners.

 int counter=sizeof(names);
 int x=0;

 for( x ; x<counter ; x++) {
      message("info",names[x],this_player());
                                               }

The above code will step through your array and send the message to
the player. Sizeof() is a function that reads how many items are
contained inside of your array. The [x] is something called an index.
An array assigns a value to each item it contains starting at 0 and
increasing to sizeof-1. In other words, if an array contains 5 items,
those items will be indexed as array[0], array[1], array[2], array[3]
array[4].  Array[5] would not exist until an sixth item is added to
the array. If you try to index a value larger then the array contains
, you will get an index out-of-bounds error.

ADDING and REMOVING items from an array

It is fairly easy to add and remove items from an array. You first need
to test to see if your value is already part of the array or not. This
is done with a func() called member_array(). Please see the man entry
for details on it.

string *names=({});
names=({"larry","moe","curley"});

    if(member_array("larry",names)) names -=({ "larry" });

    if(!member_array("shecky",names)) names +=({ "shecky" }) ;

I defined the array's initial values with the second name= after
I defined the array's initial values with the name= after I initiated
it in the definition. The first if() statement checks to see if "larry"
is contained in the array and then deletes it if it is. The second
if() checks if "shecky" is NOT part of the array and adds him if he is
NOT part of the array.

COMBINING and SORTING arrays

Arrays can be added together or subtracted from eachother.

In actuality, you have already seen this done without knowing it.
My example of how to add and remove a member from an array was
turning the strings "larry" and "shecky" into a single member array
and then adding or removing them from the array.

Whole arrays may also be added and subtracted. Be careful however
if you subract arrays. If one of the members on the second array is
NOT a member of the first array you will get an index out-of-bounds
error. The final array may also have duplicates in it if an item is
contained in both arrays.

EXAMPLE --

array_1=({"larry","moe","curley"});
array_2=({"manny","moe","jack","shecky"});
rejects=({"shecky"});

 membership= array_1 + array_2;

 membership= membership - rejects;

I have assumed that the three arrays were properly initiated and
defined as string arrays as I demonstrated above. Membership is the sum
of array_1 and array_2. It would have the following value;

membership=({"manny","moe","jack","larry","moe","curley","shecky"})

Please notice that "moe" is there twice as it was in both of the original
arrays. The second line subtractss the array ({ "shecky" }) from membership

You may solve the problem of having multiple entries with the same values
by using unique_array(). You may also sort your arrays with sort_array()
ot alphabatize them. You can even filter out unwanted members with
filter_array() and map_array(). Please see the man entries on these
functions.

Magelord Ironman

