Man arrays

From LSWiki

Description

There is support for arrays. The arrays can't be declared, but should be allocated dynamically with the function 'allocate()' (see efun/allocate).

Arrays are stored by reference, so all assignments of whole arrays will just copy the address. The array will be deallocated when no variable points to it any longer.

When a variable points to an array, items can be accessed with indexing: 'arr[3]' as an example. The name of the array being indexed can be any expression, even a function call: 'func()[2]'. It can also be another array, if this array has pointers to arrays:

       arr = allocate(2);
       arr[0] = allocate(3);
       arr[1] = allocate(3);

Now 'arr[1][2]' is a valid value.

The 'sizeof()' function (in true C a compiler-directive, not a function) will give the number of elements in an array (see efun/sizeof).

• NOTE - Nowadays it is most of the time preferable to use an array

constructor, a list surrounded by '({' and '})', e.g. ({ 1, "xx", 2 }) will construct a new array with size 3, initialized with 1, "xx" and 2 respectively.

Operations

• Indexing

There are several very useful operations defined on array. The most used is the indexing:

               a=({ 0,1,2,3 });
               return a[2];      // this will return 2

You also can count from the end of the array. Use <1 to specify the last element in the array:

               a=({ 0,1,2,3 });
               return a[<3];     // this will return 1

With indexing you can also create sub-arrays:

               a=({ 0,1,2,3,4,5,6,7 });
               return a[3..5];   // this will return ({ 3,4,5 })
               return a[2..<2];  // this will return ({ 2,3,4,5,6 })
               return a[<5..<3]; // this will return ({ 3,4,5 })
               return a[<6..5];  // this will return ({ 2,3,4,5 })
               return a[3..3];   // this will return ({ 3 })
               return a[3..2];   // this will return ({ })
               return a[3..0];   // this will return ({ })
               return a[5..100]; // this will return ({ 5,6,7 })
               [x..] is interpreted as [x..<1]

• Adding -

You can add two arrays. The result is one array with the elements of both the former arrays:

               a=({ 0,1 });
               b=({ "a","b" });
               return a+b;       // this will return ({ 0,1,"a","b" })
               return b+a;       // this will return ({ "a","b",0,1 })

• Subtracting -

You can erase all elements of one array that occur in another array:

               a=({ 0,1,2,3,4,5,6,7 });
               b=({ 7,2,5,8,1,9 });
               return a-b;       // this will return ({ 0,3,4,6 })
               return b-a;       // this will return ({ 8,9 })

• Interjunction -

Use the &-operator to create the interjunction of two arrays:

               a=({ 5,2,8,1,9,4 })
               b=({ 1,6,7,3,4,5 })
               return a&b;       // this will return ({ 1,4,5 })

• Assigning -

Assigning can also be done to sub-arrays and is thus very powerful:

               a=({ 0,1,2,3,4,5,6,7 });
               a[<4..<3]=({ 8,9 });
               return a;         // this will return ({ 0,1,2,3,8,9,6,7 })

               a=({ 0,1,2,3,4,5,6,7 });
               a[2..5]=({ });
               return a;         // this will return ({ 0,1,6,7 })

               a=({ 0,1,2,3,4 });
               a[3..2]=({ 8,9 });
               return a;         // this will return ({ 0,1,2,8,9,3,4 })

               a=({ 0,1,2,3,4 });
               a[3..0]=({ 8,9 });
               return a;         // this will return ({ 0,1,2,8,9,1,2,3,4 })
                                 // this is quite funny but true ;-)
                                 // WARNING: If done unintentionally and
                                 // within a loop, you can quickly cause
                                 // the game to run out of memory!

• General -

Of course for any of the operators explained above you can use the combined form of assigning and operating; that means the operators +=, -= and &= work.

Tips

If you want to make sure that no element is more than once in an array you can use the following:

              a = m_indices(mkmapping(a));
       

This creates a mapping out of the array and recreates the array at once. The elements in the array can be shuffled by this procedure.