XMREngine.arrays

From Dreamnation
Jump to: navigation, search

ASSOCIATIVE ARRAYS

Arrays are associative in that the index can be any immutable type, and any given array can have a mix of index types and a mix of value types. In particular, the index of an array can be a list to provide multiple-dimension array functionality.

(Note: For fixed-dimension arrays, see XMREngine.objects).

The index can be type float, key, list, integer, rotation, string, vector.

Unlike other LSL script types, arrays are mutable. So, unlike lists, arrays can be passed to a function, the function can modify the array, and the caller will see the changes made by the function, all without any array copying.

Enabled by: xmroption arrays;

Keywords:

   array       declare variable to be an array, and make it initially empty
   foreach     iterate through all elements in an array
   in          keyword part of foreach statement
   is          test array element to be a particular type
   object      declare variable that can hold any type
   undef       test object or array element to hold undefined element

Declare an array:

   'array' name ';'
   Example:
       array ar;

Insert or replace element:

   name '[' index ']' '=' value ';'
       name  : was declared with 'array' statement
       index : lsl value of type float, key, list, integer, rotation, string, vector
       value : lsl value of any type
   Examples:
       ar[3] = "abcdef";
       ar["five"] = [ "one", "two", "three" ];
       ar[5.0,"six"] = 7;

Delete element:

   name '[' index ']' '=' undef ';'
       it is not an error to delete an element that does not exist
   Example:
       ar["five"] = undef;

Retrieve element:

   name '[' index ']'
       if element not defined, return value is 'undef'
   Example:
       llOwnerSay((string)ar[3]);

Test type of object:

   <object> is <type>  =>  integer 0 or 1
   <object> is undef   =>  integer 0 or 1
   object o;
   if (o is integer) ...
   if (o is string) ... etc

Methods and Properties:

   ar.clear()  // empty array, returns type void
   ar.count    // get number of elements in array, returns type integer
   ar.index(i) // get index of i'th (zero based) element, returns type object
   ar.value(i) // get value of i'th (zero based) element, returns type object

Iterate through all elements:

   array ar;
   object k;
   object v;
   foreach (k,v in ar) {
       k holds the index
       v holds the value
       llOwnerSay("ar[" + (string)k + "]=" + (string)v);
   }
   // alternatively:
   object k;
   object v;
   integer n = ar.count;
   for (integer i = 0; i < n; i ++) {
       k = ar.index(i);
       v = ar.value(i);
       llOwnerSay((string)i + ": ar[" + (string)k + "]=" + (string)v);
   }