_{Official ZPE/YASS documentation}List data type

The list data type is one of the most powerful data types in ZPE. The list works similar to an array in other languages but unlike a standard array can be either fixed length or countably infinite.

Defining a list is easy:

$empty_list = []
$some_list = [1, 2, 3, 4]

//Using TYPO (version 1.9.7+)
declare myList as list = []
  

There are many operations that can be performed on the list but perhaps the most common is simply obtaining an element from the list:

$some_list = [1, 2, 3, 4]
//This will obtain the third element from the list
$some_element = $some_list[2]
  

$a = [44, 32, 99]
print([4, 9, 3])
  

Fixed-length arrays

Version 1.6.7 added fixed size lists (arrays). Defining a fixed-length array is also very easy by just defining in the brackets the default value of the array and then telling the compiler how many elements are needed:

$a = [0] * 4
print($a)
$b = ["Hello world"] * 3
print($b)
  

The previous example will add the number 0 four times to the first list and then add "Hello world" three times to the second list.

The difference between a list and an array (added in version 1.6.7) is that arrays have a fixed size whereas lists can be increased (or decreased) in size very easily. Arrays have the advantage of index existence, that is, one can be assured that such an index does exist.

Other languages use arrays and do not offer a list type and as a result, from an educational perspective, arrays are better suited as a teaching tool.

Negative indices and ranges

ZPE 1.8.6 (Younis) added support for negative indices. These will work backward from 0, e.g. -1 will be the last element within the list and -2 will be the penultimate element.

$l = [0, 1, 2, 3]
print($l[-1])
  

For the sake of preventing accidental accessing a negative index that does not exist, for example applying -53 here, ZPE sanitises any negtaive index access automatically.

ZPE 1.8.6 also added ranges of indices. This allows you to obtain a list of items from the list very quickly.

$l = [0, 1, 2, 3]
print($l[1:3])
  

Note that the range is inclusive and includes both the first index and the second index when using this range, so the above example would return [1, 2, 3].

Reference functions

The list data type provides several reference functions that allow for ease of use:

to_string () ⇒ string

Converts (casts) the list to a string

put (mixed value) ⇒ list

Puts an element at the end of the list.

push (mixed value) ⇒ list

Adds an element to the start of the list.

get_circular (number index) ⇒ mixed

Gets an element using a circular index, meaning that it will always be index safe. This was formerly called getc in versions prior to ZPE 1.9.10.

sublist (number from, number to) ⇒ list

Gets a sublist of the list.

remove (number index) ⇒ list

Removes an element from a list at a specified index.

length () ⇒ number

Returns the length or size of the list.

map (function f) ⇒ list

Returns a new list based on an existing list. The function, f, can modify the data being added to the new list.

YASS

  $x = [11, 22, 33]
  $y = $x.map(function($a){
    return $a * 3
  })
  print($y) //Should print [33, 66, 99]
  

filter (function f) ⇒ list

Returns a new list based on an existing list. The function, f, must return a boolean value to determine whether or not to put the value into the new list.

YASS

$x = [11, 22, 33]
$y = $x.filter(function($a){
  return $a > 15
})
print($y) //Should print [22, 33]

reduce (function f, mixed initialValue) ⇒ mixed

Reduces a list down to a single value. The initialValue is needed as it will set the first parameter in the function.

YASS

$x = [11, 22, 33]
$y = $x.reduce(function($result, $item){
  return $result + $item
}, 0)
print($y) //Should print 66

Interesting examples

Using the reduce reference function to create a list of lists:

$x = [11, 22, 33]
$y = $x.reduce(function($a, $b){
  return list_add_element($a, [$b])
}, [])
print($y) //Should print [[11], [22], [33]]