Jamie Balfour

Welcome to my personal website.

Find out more about me, my personal projects, reviews, courses and much more here.

Official ZPE/YASS documentationList data type

Official ZPE/YASS documentationList 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
$b = ["Hello world"] * 3

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]

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.

When the INDEX_SAFETY setting is set to on negative indices cannot be used.

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]

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.
  $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.
$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.
$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]]
Feedback 👍
Comments are sent via email to me.