6. Strings, Arrays and Mappings

6.1 Strings

LPC has real strings, not arrays of characters. Strings are shared, i.e. when a string is created it is stored in a table and replaced with a reference. This saves memory.

The index operator can be used on strings. The returned value of str[i] is the character (i.e., an integer) at position i in the string 'str'. For example, '"abcd"[-1]' gives 100, the character value of 'd'. Note that this is not the string "d".

The index operator can be used to set single elements in the string:

  string str;

  str = "abcdef";
  str[1] = 'C'; // str is now "aCcdef"

but not to set a sub-string of length 1, i.e.

  string str;

  str = "abcdef";
  str[1] = "C";

does not work; it will in fact trigger a load-time error. Note the difference between the character 'C' and the string "C".

Giving the index operator a range will yield a string:

  string str1, str2, str3;

  str1 = "abcdef";
  str2 = str1[1..3]; // str2 is now "bcd".
  str3 = str1[2..2]; // str3 is now "c".

In this way, the index operator can be used to set parts of a string:

  string s;

  s = "abcdef";
  s[1..2] = "BC";   // s is now "aBCdef".
  s[1..2] = "B--C"; // s is now "aB--Cdef".

6.2 Arrays

LPC allows you to declare arrays of any type. This is usually done by prepending a '*' before the variable name, as in 'int *many' (which declares an array of integers named 'many'). If you use the #pragma strict_types, you must declare them that way. Before you can use the array, you have to initialise it to a valid array. Remember that LPC initialises all variables to zero (0), which is not a valid array.

You can create an array by using the allocate efun:

  int *arr;
  arr = allocate(12);

which declares an array of ints 'arr' and initialises it to consist of 12 integers, numbered 0 to 11, that are zero. The use of 'allocate' is not needed, the above can as well be written

  int *arr;
  arr = ({ 0,0,0,0,0,0,0,0,0,0,0,0 });

Arrays change size dynamically. For example, adding two arrays with three elements gives a single array with 6 elements. The allocation of the needed memory and the copying of data is handled by the driver.

You can, naturally, have multi-dimensional arrays. Those are handled as arrays of arrays, and thus there is no real type for them. You then have to resort to using the type 'mixed'.

The index operator can be used on arrays to get a single element, a range of elements, to set a single element, and to set a range of elements. For example:

  mixed a, b;
  
  a = ({ 0,1,2,3,4 });
  b = a[2];   // b is now 2.
  b = a[2..3] // b is now ({ 2,3 }).
  
  a[5] = 9;                // a is now ({ 0,1,2,3,4,9 }).
  a[0..0] = ({ "a","b" }); // a is now ({ "a","b",1,2,3,4,9 }).
  a[0..1] = ({ "c","d" }); // a is now ({ "c","d",1,2,3,4,9 }).
  a[0..3] = ({ 99 });      // a is now ({ 99,3,4,9 }).
  a[0] = ({ 0,1 });        // a is now ({ ({ 0,1 }), 3,4,5 }).

  a = ({});
  a[0..0] = ({ 1 }); // a is now ({ 1 });
  
  a = ({});
  a[0] = 0; // This gives an 'index out of bounds' error.

6.3 Mappings

A mapping is LPC's associative array. You can think of it as an array that accepts any type of value as an index, or as a list of index-data pairs. Using an index for which there is no data, returns a zero. New entries are simply added by

  map[index]=value;

or by

  map += ([ index:value ]);

The former over-writes any previous entry on that index, the latter does not. Using the latter, you can force several entries with the same index but different values. If so, what exact value is returned by 'map[index]' cannot be predicted¹³. Also of interest is that the former construction just extends the mapping, while the latter creates a new copy of the mapping.

The index operator does not accept ranges when operating on mappings.

Mappings are always sorted (on the indices, but the sort order is not one humans can interpret, with one glorious exception: when the index are integers, the mapping is sorted in ascending order.

6.4 Strings, Arrays and Mappings as Function Arguments

For all practical purposes, strings,arrays and mappings as function arguments are passed by value. In reality, they are passed by reference, and the copying is delayed until a change is done to the string/array/mapping.

Footnotes

... predicted¹³

It will not change while the driver runs, but differ between different runs. Shutting down the driver and restarting it is known as a 'reboot'.