mirror of
https://github.com/wren-lang/wren.git
synced 2026-01-11 22:28:45 +01:00
228 lines
14 KiB
HTML
228 lines
14 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-type" content="text/html;charset=UTF-8" />
|
|
<title>Maps – Wren</title>
|
|
<link rel="stylesheet" type="text/css" href="style.css" />
|
|
<link href='//fonts.googleapis.com/css?family=Source+Sans+Pro:400,700,400italic,700italic|Source+Code+Pro:400|Lato:400|Sanchez:400italic,400' rel='stylesheet' type='text/css'>
|
|
<!-- Tell mobile browsers we're optimized for them and they don't need to crop
|
|
the viewport. -->
|
|
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1"/>
|
|
</head>
|
|
<body id="top">
|
|
<header>
|
|
<div class="page">
|
|
<div class="main-column">
|
|
<h1><a href="./">wren</a></h1>
|
|
<h2>a classy little scripting language</h2>
|
|
</div>
|
|
</div>
|
|
</header>
|
|
<div class="page">
|
|
<nav class="big">
|
|
<a href="./"><img src="./wren.svg" class="logo"></a>
|
|
<ul>
|
|
<li><a href="getting-started.html">Getting Started</a></li>
|
|
<li><a href="contributing.html">Contributing</a></li>
|
|
<li><a href="blog">Blog</a></li>
|
|
</ul>
|
|
<section>
|
|
<h2>guides</h2>
|
|
<ul>
|
|
<li><a href="syntax.html">Syntax</a></li>
|
|
<li><a href="values.html">Values</a></li>
|
|
<li><a href="lists.html">Lists</a></li>
|
|
<li><a href="maps.html">Maps</a></li>
|
|
<li><a href="method-calls.html">Method Calls</a></li>
|
|
<li><a href="control-flow.html">Control Flow</a></li>
|
|
<li><a href="variables.html">Variables</a></li>
|
|
<li><a href="functions.html">Functions</a></li>
|
|
<li><a href="classes.html">Classes</a></li>
|
|
<li><a href="concurrency.html">Concurrency</a></li>
|
|
<li><a href="error-handling.html">Error Handling</a></li>
|
|
<li><a href="modularity.html">Modularity</a></li>
|
|
</ul>
|
|
</section>
|
|
<section>
|
|
<h2>reference</h2>
|
|
<ul>
|
|
<li><a href="modules">Modules</a></li>
|
|
<li><a href="embedding">Embedding</a></li>
|
|
<li><a href="performance.html">Performance</a></li>
|
|
<li><a href="qa.html">Q & A</a></li>
|
|
</ul>
|
|
</section>
|
|
</nav>
|
|
<nav class="small">
|
|
<table>
|
|
<tr>
|
|
<div><a href="getting-started.html">Getting Started</a></div>
|
|
<div><a href="contributing.html">Contributing</a></div>
|
|
<div><a href="blog">Blog</a></div>
|
|
</tr>
|
|
<tr>
|
|
<td colspan="2"><h2>guides</h2></td>
|
|
<td><h2>reference</h2></td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
<ul>
|
|
<li><a href="syntax.html">Syntax</a></li>
|
|
<li><a href="values.html">Values</a></li>
|
|
<li><a href="lists.html">Lists</a></li>
|
|
<li><a href="maps.html">Maps</a></li>
|
|
<li><a href="method-calls.html">Method Calls</a></li>
|
|
<li><a href="control-flow.html">Control Flow</a></li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
<ul>
|
|
<li><a href="variables.html">Variables</a></li>
|
|
<li><a href="functions.html">Functions</a></li>
|
|
<li><a href="classes.html">Classes</a></li>
|
|
<li><a href="concurrency.html">Concurrency</a></li>
|
|
<li><a href="error-handling.html">Error Handling</a></li>
|
|
<li><a href="modularity.html">Modularity</a></li>
|
|
</ul>
|
|
</td>
|
|
<td>
|
|
<ul>
|
|
<li><a href="modules">Modules</a></li>
|
|
<li><a href="embedding">Embedding</a></li>
|
|
<li><a href="performance.html">Performance</a></li>
|
|
<li><a href="qa.html">Q & A</a></li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</nav>
|
|
<main>
|
|
<h2>Maps</h2>
|
|
<p>A map is an <em>associative</em> collection. It holds a set of entries, each of which
|
|
maps a <em>key</em> to a <em>value</em>. The same data structure has a variety of names in
|
|
other languages: hash table, dictionary, association, table, etc. </p>
|
|
<p>You can create a map by placing a series of comma-separated entries inside
|
|
curly braces. Each entry is a key and a value separated by a colon: </p>
|
|
<div class="codehilite"><pre><span class="p">{</span>
|
|
<span class="s">"George"</span><span class="o">:</span> <span class="s">"Harrison"</span><span class="p">,</span>
|
|
<span class="s">"John"</span><span class="o">:</span> <span class="s">"Lennon"</span><span class="p">,</span>
|
|
<span class="s">"Paul"</span><span class="o">:</span> <span class="s">"McCartney"</span><span class="p">,</span>
|
|
<span class="s">"Ringo"</span><span class="o">:</span> <span class="s">"Starr"</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
|
|
|
|
<p>This creates a map that associates the first name of each Beatle with his last
|
|
name. Syntactically, in a map literal, keys can be any literal, a variable
|
|
name, or a parenthesized expression. Values can be any expression. Here, we’re
|
|
using string literals for both keys and values. </p>
|
|
<p><em>Semantically</em>, values can be any object, and multiple keys may map to the same
|
|
value. Keys have a few limitations. They must be one of the immutable built-in
|
|
<a href="values.html">value types</a> in Wren. That means a number, string, range, bool, or <code>null</code>.
|
|
You can also use a <a href="classes.html">class object</a> as a key. </p>
|
|
<p>The reason for this limitation—and the reason maps are called “<em>hash</em>
|
|
tables” in other languages—is that each key is used to generate a numeric
|
|
<em>hash code</em>. This lets a map locate the value associated with a key in constant
|
|
time, even in very large maps. Since Wren only knows how to hash certain
|
|
built-in types, only those can be used as keys. </p>
|
|
<h2>Adding entries <a href="#adding-entries" name="adding-entries" class="header-anchor">#</a></h2>
|
|
<p>You add new key-value pairs to the map using the <a href="method-calls.html#subscripts">subscript operator</a>: </p>
|
|
<div class="codehilite"><pre><span class="k">var</span> <span class="n">capitals</span> <span class="o">=</span> <span class="p">{}</span>
|
|
<span class="n">capitals</span><span class="p">[</span><span class="s">"Georgia"</span><span class="p">]</span> <span class="o">=</span> <span class="s">"Atlanta"</span>
|
|
<span class="n">capitals</span><span class="p">[</span><span class="s">"Idaho"</span><span class="p">]</span> <span class="o">=</span> <span class="s">"Boise"</span>
|
|
<span class="n">capitals</span><span class="p">[</span><span class="s">"Maine"</span><span class="p">]</span> <span class="o">=</span> <span class="s">"Augusta"</span>
|
|
</pre></div>
|
|
|
|
|
|
<p>If the key isn’t already present, this adds it and associates it with the given
|
|
value. If the key is already there, this just replaces its value. </p>
|
|
<h2>Looking up values <a href="#looking-up-values" name="looking-up-values" class="header-anchor">#</a></h2>
|
|
<p>To find the value associated with some key, again you use your friend the
|
|
subscript operator: </p>
|
|
<div class="codehilite"><pre><span class="vg">System</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="n">capitals</span><span class="p">[</span><span class="s">"Idaho"</span><span class="p">])</span> <span class="output">Boise</span>
|
|
</pre></div>
|
|
|
|
|
|
<p>If the key is present, this returns its value. Otherwise, it returns <code>null</code>. Of
|
|
course, <code>null</code> itself can also be used as a value, so seeing <code>null</code> here
|
|
doesn’t necessarily mean the key wasn’t found. </p>
|
|
<p>To tell definitively if a key exists, you can call <code>containsKey()</code>: </p>
|
|
<div class="codehilite"><pre><span class="k">var</span> <span class="n">belief</span> <span class="o">=</span> <span class="p">{</span><span class="s">"nihilism"</span><span class="o">:</span> <span class="kc">null</span><span class="p">}</span>
|
|
|
|
<span class="vg">System</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="n">belief</span><span class="p">[</span><span class="s">"nihilism"</span><span class="p">])</span> <span class="output">null (though key exists)</span>
|
|
<span class="vg">System</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="n">belief</span><span class="p">[</span><span class="s">"solipsism"</span><span class="p">])</span> <span class="output">null</span>
|
|
<span class="vg">System</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="n">belief</span><span class="o">.</span><span class="n">containsKey</span><span class="p">(</span><span class="s">"nihilism"</span><span class="p">))</span> <span class="output">true</span>
|
|
<span class="vg">System</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="n">belief</span><span class="o">.</span><span class="n">containsKey</span><span class="p">(</span><span class="s">"solipsism"</span><span class="p">))</span> <span class="output">false</span>
|
|
</pre></div>
|
|
|
|
|
|
<p>You can see how many entries a map contains using <code>count</code>: </p>
|
|
<div class="codehilite"><pre><span class="vg">System</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="n">capitals</span><span class="o">.</span><span class="n">count</span><span class="p">)</span> <span class="output">3</span>
|
|
</pre></div>
|
|
|
|
|
|
<h2>Removing entries <a href="#removing-entries" name="removing-entries" class="header-anchor">#</a></h2>
|
|
<p>To remove an entry from a map, call <code>remove()</code> and pass in the key for the
|
|
entry you want to delete: </p>
|
|
<div class="codehilite"><pre><span class="n">capitals</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="s">"Maine"</span><span class="p">)</span>
|
|
<span class="vg">System</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="n">capitals</span><span class="o">.</span><span class="n">containsKey</span><span class="p">(</span><span class="s">"Maine"</span><span class="p">))</span> <span class="output">false</span>
|
|
</pre></div>
|
|
|
|
|
|
<p>If the key was found, this returns the value that was associated with it: </p>
|
|
<div class="codehilite"><pre><span class="vg">System</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="n">capitals</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="s">"Georgia"</span><span class="p">))</span> <span class="output">Atlanta</span>
|
|
</pre></div>
|
|
|
|
|
|
<p>If the key wasn’t in the map to begin with, <code>remove()</code> just returns <code>null</code>. </p>
|
|
<p>If you want to remove <em>everything</em> from the map, like with <a href="lists.html">lists</a>, you call
|
|
<code>clear()</code>: </p>
|
|
<div class="codehilite"><pre><span class="n">capitals</span><span class="o">.</span><span class="n">clear</span><span class="p">()</span>
|
|
<span class="vg">System</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="n">capitals</span><span class="o">.</span><span class="n">count</span><span class="p">)</span> <span class="output">0</span>
|
|
</pre></div>
|
|
|
|
|
|
<h2>Iterating over the contents <a href="#iterating-over-the-contents" name="iterating-over-the-contents" class="header-anchor">#</a></h2>
|
|
<p>The subscript operator works well for finding values when you know the key
|
|
you’re looking for, but sometimes you want to see everything that’s in the map.
|
|
For that, map exposes two methods: <code>keys</code> and <code>values</code>. </p>
|
|
<p>The first returns a <a href="modules/core/sequence.html">Sequence</a> that <a href="control-flow.html#the-iterator-protocol">iterates</a> over all of the keys in the
|
|
map, and the second returns one that iterates over the values. </p>
|
|
<p>If you want to see all of the key-value pairs in a map, the easiest way is to
|
|
iterate over the keys and use each to look up its value: </p>
|
|
<div class="codehilite"><pre><span class="k">var</span> <span class="n">birds</span> <span class="o">=</span> <span class="p">{</span>
|
|
<span class="s">"Arizona"</span><span class="o">:</span> <span class="s">"Cactus wren"</span><span class="p">,</span>
|
|
<span class="s">"Hawaii"</span><span class="o">:</span> <span class="s">"Nēnē"</span><span class="p">,</span>
|
|
<span class="s">"Ohio"</span><span class="o">:</span> <span class="s">"Northern Cardinal"</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="k">for</span> <span class="p">(</span><span class="n">state</span> <span class="k">in</span> <span class="n">birds</span><span class="o">.</span><span class="n">keys</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="vg">System</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="s">"The state bird of "</span> <span class="o">+</span> <span class="n">state</span> <span class="o">+</span> <span class="s">" is "</span> <span class="o">+</span> <span class="n">birds</span><span class="p">[</span><span class="n">state</span><span class="p">])</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
|
|
|
|
<p>This program prints the three states and their birds. However, the <em>order</em>
|
|
that they are printed isn’t defined. Wren makes no promises about what order
|
|
keys and values are iterated in when you use these methods. All it promises is
|
|
that every entry will appear exactly once. </p>
|
|
<p><br><hr>
|
|
<a class="right" href="method-calls.html">Method Calls →</a>
|
|
<a href="lists.html">← Lists</a> </p>
|
|
</main>
|
|
</div>
|
|
<footer>
|
|
<div class="page">
|
|
<div class="main-column">
|
|
<p>Wren lives
|
|
<a href="https://github.com/wren-lang/wren">on GitHub</a>
|
|
— Made with ❤ by
|
|
<a href="http://journal.stuffwithstuff.com/">Bob Nystrom</a> and
|
|
<a href="https://github.com/wren-lang/wren/blob/master/AUTHORS">friends</a>.
|
|
</p>
|
|
<div class="main-column">
|
|
</div>
|
|
</footer>
|
|
</body>
|
|
</html>
|