# Array and Table Extensions

These extensions add two new data structures to NetLogo, arrays and hash tables.

## When to use

In general, anything you can do with an array or table, you could also just use a list for. But you may want to consider using an array or table instead for speed reasons. All three data structures (list, array, and table) have different performance characteristics, so you may be able to make your model run faster by selecting the appropriate data structure.

Arrays are useful when you need a collection of values whose size is fixed. You can quickly access or alter any item in an array if you know its position.

Tables are useful when you need to do associate values with other values. For example, you might make a table of words and their definitions. Then you can look up the definition of any word. Here, the words are the "keys". You can easily retrieve the value for any key in the table, but not vice versa.

Unlike NetLogo's lists and strings, arrays and tables are "mutable". That means that you can actually modify them directly, rather than constructing an altered copy as with lists. If the array or table is used in more than one place in your code, any changes you make will show up everywhere. It's tricky to write code involving mutable structures and it's easy to make subtle errors or get surprising results, so we suggest sticking with lists and strings unless you're certain you want and need mutability.

## Lists and arrays in NetLogo 5.0

In NetLogo 4.1 and earlier, common list operations such as `last`, `lput`, `item`, and `replace-item` took linear time (proportional to the size of the list). As a result, some users chose to use arrays instead of lists in order to get good performance. But in the current NetLogo, these operations now run in nearly constant time. So arrays are now less often needed.

## How to use

Both extensions come preinstalled.

To use the array extension in your model, add a line to the top of your Code tab:

    extensions [array]

To use the table extension in your model, add a line to the top of your Code tab:

    extensions [table]

You can use both extensions in the same model if you want, as follows:

    extensions [array table]

If your model already uses other extensions, then it already has an `extensions` line in it, so just add `array` and/or `table` to the list.

For more information on using NetLogo extensions, see the Extensions Guide.

### Limitation on table keys

Table keys may only be strings, numbers, booleans, or lists. (Lists may be arbitrarily nested lists as long as all the items inside are strings, numbers, or booleans.)

## Array example

    let a array:from-list n-values 5 [0]
    print a
    => {{array: 0 0 0 0 0}}
    print array:length a
    => 5
    foreach n-values 5 [?] [ array:set a ? ? * ? ]
    print a
    => {{array: 0 1 4 9 16}}
    print array:item a 0
    => 0
    print array:item a 3
    => 9
    array:set a 3 50
    print a
    => {{array: 0 1 4 50 16}}

## Table example

    let dict table:make
    table:put dict "turtle" "cute"
    table:put dict "bunny" "cutest"
    print dict
    => {{table: "turtle" -> "cute", "bunny" -> "cutest" }}
    print table:length dict
    => 2
    print table:get dict "turtle"
    => "cute"
    print table:get dict "leopard"
    => (error)
    print table:keys dict
    => ["turtle" "bunny"]

> Code Example: Table Example

## Array primitives

array:from-list array:item array:set array:length array:to-list

### array:from-list

#### array:from-list list

Reports a new array containing the same items in the same order as the input list.

### array:item

#### array:item array index

Reports the item in the given array with the given index (ranging from zero to the length of the array minus one).

### array:set

#### array:set array index value

Sets the item in the given array with the given index (ranging from zero to the length of the array minus one) to the given value.

Note that unlike the `replace-item` primitive for lists, a new array is not created. The given array is actually modified.

### array:length

#### array:length array

Reports the length of the given array, that is, the number of items in the array.

### array:to-list

#### array:to-list array

Reports a new list containing the same items in the same order as the given array.

## Table Primitives

table:clear table:from-list table:get table:has-key? table:keys table:length table:make table:put table:remove table:to-list

### table:clear

#### table:clear table

Removes all key-value pairs from table.

### table:from-list

#### table:from-list list

Reports a new table with the contents of list. list must be a list of two element lists, or pairs. The first element in the pair is the key and the second element is the value.

### table:get

#### table:get table key

Reports the value that key is mapped to in the table. Causes an error if there is no entry for the key.

### table:has-key?

#### table:has-key? table key

Reports true if key has an entry in table.

### table:keys

#### table:keys table

Reports a list of all the keys in table, in the same order the keys were inserted.

### table:length

#### table:length table

Reports the number of entries in table.

### table:make

Reports a new, empty table.

### table:put

#### table:put table key value

Maps key to value in table. If an entry already exists in the table for the given key, it is replaced.

### table:remove

#### table:remove table key

Removes the mapping in table for key.

### table:to-list

#### table:to-list table

Reports a list with the content of table. The list will be a list of two element lists, or pairs. The first element in the pair is the key and the second element is the value. The keys appear in the same order they were inserted.