Array

Uniform list of items.

THP Arrays contain an ordered list of values of a unique datatype, that is to say, you cannot store values of different datatypes inside an Array.

If you need to store values of different types, see Tuples.

THP arrays are 0-indexed.

Signature

type Array[T] = Map[Int, T]

Where T is the datatype that the Array stores. For example:

Array[Int]              // An array of integers
Array[Float]            // An array of floats
Array[Array[String]]    // A 2-dimensional array of strings

PHP array internals

Since THP compiles down to PHP, it's important to understand how PHP represents arrays internally. PHP doesn't have arrays. Instead, PHP has ordered maps and syntax sugar to make them look like arrays.

When declaring an array like:

var letters = ["a", "b", "c"]

in reality what goes into memory is a map with numbers as keys:

array(
    0 => "a",
    1 => "b",
    2 => "c",
);

As long as this map contains valid keys, it can be treated as an array. We can loop over it, read and write.

However, once we assign to an invalid index, it cannot be treated as an array anymore.

Invalid indexes are:

Problems with iterations

PHP maps preserve insertion order. This means that when iterating over a PHP map, values are processed in FIFO.

var letters = ["a", "b", "c"]
letters[-10] = "?"    // Assignment to a negative index

// Now the array will be:
// array(
//     0 => "a",
//     1 => "b",
//     2 => "c",
//   -10 => "?",
// )

letters[7] = "!" // Out of bounds assignment

// Now the array will be:
// array(
//   0 => "a",
//   1 => "b",
//   2 => "c",
// -10 => "?",
//   7 => "!",
// )

// In this loop, values will be printed based on when
// they were inserted, not by order of the index.
for #(_, value) in letters {
    print("{value} ")
    // outputs: a b c ? !
}

letters[-4] = "???"
// array(
//   0 => "a",
//   1 => "b",
//   2 => "c",
// -10 => "?",
//   7 => "!",
//  -4 => "???",
// )

// When pushing, the value will be assigned to the highest key + 1
letters.push("/") // This will be at position 8

// array(
//   0 => "a",
//   1 => "b",
//   2 => "c",
// -10 => "?",
//   7 => "!",
//  -4 => "???",
//   8 => "/",
// )

This is one of many fundamental flaws with PHP. The only way to solve it would be to check every insertion at runtime, and this would have a performance penalty.

From now on, the documentation will continue to work with the Array abstraction, as if all indexes were valid.

Usage

Empty array

To create an empty array use square brackets. If you create an empty array, you must specify the datatype.

Array[Int] empty = []

Array with items

To create an array with items use square brackets notation:

val numbers = [0, 1, 2, 3, 4, 5]

When the array is not empty, you don't need to specify a datatype.

Assignment to elements

Use square brackets notation to insert into an array or modify it:

To modify an array it must be mutable, that is, assigned to a var instead of a val.

// This array cannot be modified, as it's declared with \`val\`
val immutable = [1, 2, 3]
// This is a compile time error
immutable[0] = 322

// This array can be modified, as it's declared with \`var\`
var mutable = [1, 2, 3]
// Ok
mutable[0] = 322

To append an element to an array, use the method push():

mutable.push(4)

Do not insert into an invalid index. See PHP array internals to learn why.

Iteration

Use a for loop to iterate over the elements of an array. You'll receive a index and the element:

val my_colors = ["red", "green", "blue"]

for #(idx, color) in my_colors {
    print("{color} ")
}

red green blue

A for loop automatically declares new immutable variables. It is a compile error to attempt to modify those, as in the following snippet:

val my_colors = ["red", "green", "blue"]

for #(_, c) in my_colors {
    c = "orange" // Compile error: Can't assign to an immutable variable
    print("{c} ")
}

You can also declare an index along with the value:

val my_colors = ["red", "green", "blue"]

for #(index, color) in my_colors {
    println("item {index}: {c}")
}

item 0: red
item 1: green
item 2: blue

Access

To access a value of the array use square brackets notation:

print(colors[0])

Destructuring

THP arrays don't have destructuring, since the values can all be null. If you know that the number of elements is fixed and valid, use Tuples instead.

Operators

While PHP allows using certain operators with arrays, THP disallows that. Methods that perform comparisons should be used instead.

Assignment

// TODO: Detail that assignment of arrays is copy on write

Methods

In the parameters, self is the array to operate on.