Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

292 lines (290 sloc) 9.376 kb
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<title>
NetLogo User Manual: Array &amp; Table Extensions
</title>
<link rel="stylesheet" href="netlogo.css" type="text/css">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<h1>
Array and Table Extensions
</h1>
<p>
These extensions add two new data structures to NetLogo, arrays and
hash tables.
<h2>
When to use
</h2>
<p>
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.
<p>
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.
<p>
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 &quot;keys&quot;. You can easily retrieve the value
for any key in the table, but not vice versa.
<p>
Unlike NetLogo's lists and strings, arrays and tables are
&quot;mutable&quot;. 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.
<h2>
Lists and arrays in NetLogo 5.0
</h2>
<p>
In NetLogo 4.1 and earlier, common list operations such as
<tt>last</tt>, <tt>lput</tt>, <tt>item</tt>, and
<tt>replace-item</tt> 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.
<h2>
How to use
</h2>
<p>
Both extensions come preinstalled.
<p>
To use the array extension in your model, add a line to the top of
your Code tab:
<pre>
extensions [array]
</pre>
<p>
To use the table extension in your model, add a line to the top of
your Code tab:
<pre>
extensions [table]
</pre>
<p>
You can use both extensions in the same model if you want, as
follows:
<pre>
extensions [array table]
</pre>
<p>
If your model already uses other extensions, then it already has an
<a href="dictionary.html#extensions"><tt>extensions</tt></a> line in
it, so just add <tt>array</tt> and/or <tt>table</tt> to the list.
<p>
For more information on using NetLogo extensions, see the <a href=
"extensions.html">Extensions Guide</a>.
<h3>
Limitation on table keys
</h3>
<p>
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.)
<h2>
Array example
</h2>
<pre>
let a array:from-list n-values 5 [0]
print a
=&gt; {{array: 0 0 0 0 0}}
print array:length a
=&gt; 5
foreach n-values 5 [?] [ array:set a ? ? * ? ]
print a
=&gt; {{array: 0 1 4 9 16}}
print array:item a 0
=&gt; 0
print array:item a 3
=&gt; 9
array:set a 3 50
print a
=&gt; {{array: 0 1 4 50 16}}
</pre>
<h2>
Table example
</h2>
<pre>
let dict table:make
table:put dict &quot;turtle&quot; &quot;cute&quot;
table:put dict &quot;bunny&quot; &quot;cutest&quot;
print dict
=&gt; {{table: &quot;turtle&quot; -&gt; &quot;cute&quot;, &quot;bunny&quot; -&gt; &quot;cutest&quot; }}
print table:length dict
=&gt; 2
print table:get dict &quot;turtle&quot;
=&gt; &quot;cute&quot;
print table:get dict &quot;leopard&quot;
=&gt; (error)
print table:keys dict
=&gt; [&quot;turtle&quot; &quot;bunny&quot;]
</pre>
<blockquote>
<p>
<b>Code Example:</b> Table Example
</blockquote>
<h2>
Array primitives
</h2>
<p>
<a href="#array:from-list">array:from-list</a> <a href=
"#array:item">array:item</a> <a href="#array:set">array:set</a>
<a href="#array:length">array:length</a> <a href=
"#array:to-list">array:to-list</a>
<h3>
<a name="array:from-list" id="array:from-list">array:from-list</a>
</h3>
<h4>
array:from-list <i>list</i>
</h4>
<p>
Reports a new array containing the same items in the same order as
the input list.
<h3>
<a name="array:item" id="array:item">array:item</a>
</h3>
<h4>
array:item <i>array</i> <i>index</i>
</h4>
<p>
Reports the item in the given array with the given index (ranging
from zero to the length of the array minus one).
<h3>
<a name="array:set" id="array:set">array:set</a>
</h3>
<h4>
array:set <i>array</i> <i>index</i> <i>value</i>
</h4>
<p>
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.
<p>
Note that unlike the <a href=
"dictionary.html#replace-item"><tt>replace-item</tt></a> primitive
for lists, a new array is not created. The given array is actually
modified.
<h3>
<a name="array:length" id="array:length">array:length</a>
</h3>
<h4>
array:length <i>array</i>
</h4>
<p>
Reports the length of the given array, that is, the number of items
in the array.
<h3>
<a name="array:to-list" id="array:to-list">array:to-list</a>
</h3>
<h4>
array:to-list <i>array</i>
</h4>
<p>
Reports a new list containing the same items in the same order as the
given array.
<h2>
Table Primitives
</h2>
<p>
<a href="#table:clear">table:clear</a> <a href=
"#table:from-list">table:from-list</a> <a href=
"#table:get">table:get</a> <a href=
"#table:has-key">table:has-key?</a> <a href=
"#table:keys">table:keys</a> <a href="#table:length">table:length</a>
<a href="#table:make">table:make</a> <a href=
"#table:put">table:put</a> <a href="#table:remove">table:remove</a>
<a href="#table:to-list">table:to-list</a>
<h3>
<a name="table:clear" id="table:clear">table:clear</a>
</h3>
<h4>
table:clear <i>table</i>
</h4>
<p>
Removes all key-value pairs from <i>table</i>.
<h3>
<a name="table:from-list" id="table:from-list">table:from-list</a>
</h3>
<h4>
table:from-list <i>list</i>
</h4>
<p>
Reports a new table with the contents of <i>list</i>. <i>list</i>
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.
<h3>
<a name="table:get" id="table:get">table:get</a>
</h3>
<h4>
table:get <i>table</i> <i>key</i>
</h4>
<p>
Reports the value that <i>key</i> is mapped to in the table. Causes
an error if there is no entry for the key.
<h3>
<a name="table:has-key" id="table:has-key">table:has-key?</a>
</h3>
<h4>
table:has-key? <i>table</i> <i>key</i>
</h4>
<p>
Reports true if <i>key</i> has an entry in <i>table</i>.
<h3>
<a name="table:keys" id="table:keys">table:keys</a>
</h3>
<h4>
table:keys <i>table</i>
</h4>
<p>
Reports a list of all the keys in <i>table</i>, in the same order the
keys were inserted.
<h3>
<a name="table:length" id="table:length">table:length</a>
</h3>
<h4>
table:length <i>table</i>
</h4>
<p>
Reports the number of entries in <i>table</i>.
<h3>
<a name="table:make" id="table:make">table:make</a>
</h3>
<h4>
table:make
</h4>
<p>
Reports a new, empty table.
<h3>
<a name="table:put" id="table:put">table:put</a>
</h3>
<h4>
table:put <i>table</i> <i>key</i> <i>value</i>
</h4>
<p>
Maps <i>key</i> to <i>value</i> in <i>table</i>. If an entry already
exists in the table for the given key, it is replaced.
<h3>
<a name="table:remove" id="table:remove">table:remove</a>
</h3>
<h4>
table:remove <i>table</i> <i>key</i>
</h4>
<p>
Removes the mapping in <i>table</i> for <i>key</i>.
<h3>
<a name="table:to-list" id="table:to-list">table:to-list</a>
</h3>
<h4>
table:to-list <i>table</i>
</h4>
<p>
Reports a list with the content of <i>table</i>. 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.
Jump to Line
Something went wrong with that request. Please try again.