mirror of
https://github.com/wren-lang/wren.git
synced 2026-01-11 14:18:42 +01:00
162 lines
12 KiB
HTML
162 lines
12 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>
|
||
<ul>
|
||
<li><a href="getting-started.html">Getting Started</a></li>
|
||
</ul>
|
||
<section>
|
||
<h2>language</h2>
|
||
<ul>
|
||
<li><a href="syntax.html">Syntax</a></li>
|
||
<li><a href="expressions.html">Expressions</a></li>
|
||
<li><a href="variables.html">Variables</a></li>
|
||
<li><a href="control-flow.html">Control Flow</a></li>
|
||
<li><a href="error-handling.html">Error Handling</a></li>
|
||
<li><a href="modules.html">Modules</a></li>
|
||
</ul>
|
||
</section>
|
||
<section>
|
||
<h2>types</h2>
|
||
<ul>
|
||
<li><a href="values.html">Values</a></li>
|
||
<li><a href="classes.html">Classes</a></li>
|
||
<li><a href="fibers.html">Fibers</a></li>
|
||
<li><a href="functions.html">Functions</a></li>
|
||
<li><a href="lists.html">Lists</a></li>
|
||
<li><a href="maps.html">Maps</a></li>
|
||
</ul>
|
||
</section>
|
||
<section>
|
||
<h2>reference</h2>
|
||
<ul>
|
||
<li><a href="core">Core Library</a></li>
|
||
<li><a href="embedding-api.html">Embedding API</a></li>
|
||
<li><a href="performance.html">Performance</a></li>
|
||
<li><a href="contributing.html">Contributing</a></li>
|
||
<li><a href="qa.html">Q & A</a></li>
|
||
</ul>
|
||
</section>
|
||
</nav>
|
||
<main>
|
||
<h1>Maps</h1>
|
||
<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="s2">"George"</span><span class="o">:</span> <span class="s2">"Harrison"</span><span class="p">,</span>
|
||
<span class="s2">"John"</span><span class="o">:</span> <span class="s2">"Lennon"</span><span class="p">,</span>
|
||
<span class="s2">"Paul"</span><span class="o">:</span> <span class="s2">"McCartney"</span><span class="p">,</span>
|
||
<span class="s2">"Ringo"</span><span class="o">:</span> <span class="s2">"Starr"</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
|
||
|
||
<p>This creates a map that maps the first names of the Beatles to their last
|
||
names. 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 by using the <a href="expressions.html#subscript-operators">subscript operator</a>:</p>
|
||
<div class="codehilite"><pre><span class="kd">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="s2">"Georgia"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"Atlanta"</span>
|
||
<span class="n">capitals</span><span class="p">[</span><span class="s2">"Idaho"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"Boise"</span>
|
||
<span class="n">capitals</span><span class="p">[</span><span class="s2">"Maine"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"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="n">IO</span><span class="p">.</span><span class="n">print</span><span class="p">(</span><span class="n">capitals</span><span class="p">[</span><span class="s2">"Idaho"</span><span class="p">])</span> <span class="c1">// "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="kd">var</span> <span class="n">belief</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"nihilism"</span><span class="o">:</span> <span class="kc">null</span><span class="p">}</span>
|
||
|
||
<span class="n">IO</span><span class="p">.</span><span class="n">print</span><span class="p">(</span><span class="n">belief</span><span class="p">[</span><span class="s2">"nihilism"</span><span class="p">])</span> <span class="c1">// "null" though key exists.</span>
|
||
<span class="n">IO</span><span class="p">.</span><span class="n">print</span><span class="p">(</span><span class="n">belief</span><span class="p">[</span><span class="s2">"solipsism"</span><span class="p">])</span> <span class="c1">// Also "null".</span>
|
||
<span class="n">IO</span><span class="p">.</span><span class="n">print</span><span class="p">(</span><span class="n">belief</span><span class="p">.</span><span class="n">containsKey</span><span class="p">(</span><span class="s2">"nihilism"</span><span class="p">))</span> <span class="c1">// "true".</span>
|
||
<span class="n">IO</span><span class="p">.</span><span class="n">print</span><span class="p">(</span><span class="n">belief</span><span class="p">.</span><span class="n">containsKey</span><span class="p">(</span><span class="s2">"solipsism"</span><span class="p">))</span> <span class="c1">// "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="n">IO</span><span class="p">.</span><span class="n">print</span><span class="p">(</span><span class="n">capitals</span><span class="p">.</span><span class="n">count</span><span class="p">)</span> <span class="c1">// "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="p">.</span><span class="n">remove</span><span class="p">(</span><span class="s2">"Maine"</span><span class="p">)</span>
|
||
<span class="n">IO</span><span class="p">.</span><span class="n">print</span><span class="p">(</span><span class="n">capitals</span><span class="p">.</span><span class="n">containsKey</span><span class="p">(</span><span class="s2">"Maine"</span><span class="p">))</span> <span class="c1">// "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="n">IO</span><span class="p">.</span><span class="n">print</span><span class="p">(</span><span class="n">capitals</span><span class="p">.</span><span class="n">remove</span><span class="p">(</span><span class="s2">"Georgia"</span><span class="p">))</span> <span class="c1">// "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, just like with <a href="lists.html">lists</a>, you
|
||
can just call <code>clear()</code>:</p>
|
||
<div class="codehilite"><pre><span class="n">capitals</span><span class="p">.</span><span class="n">clear</span><span class="p">()</span>
|
||
<span class="n">IO</span><span class="p">.</span><span class="n">print</span><span class="p">(</span><span class="n">capitals</span><span class="p">.</span><span class="n">count</span><span class="p">)</span> <span class="c1">// "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="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="kd">var</span> <span class="n">stateBirds</span> <span class="o">=</span> <span class="p">{</span>
|
||
<span class="s2">"Arizona"</span><span class="o">:</span> <span class="s2">"Cactus wren"</span><span class="p">,</span>
|
||
<span class="s2">"Hawaii"</span><span class="o">:</span> <span class="s2">"Nēnē"</span><span class="p">,</span>
|
||
<span class="s2">"Ohio"</span><span class="o">:</span> <span class="s2">"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">stateBirds</span><span class="p">.</span><span class="n">keys</span><span class="p">)</span> <span class="p">{</span>
|
||
<span class="n">IO</span><span class="p">.</span><span class="n">print</span><span class="p">(</span><span class="s2">"The state bird of "</span><span class="p">,</span> <span class="n">state</span><span class="p">,</span> <span class="s2">" is "</span><span class="p">,</span> <span class="n">stateBirds</span><span class="p">[</span><span class="n">state</span><span class="p">])</span>
|
||
<span class="p">}</span>
|
||
</pre></div>
|
||
|
||
|
||
<p>This program will print 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 will be iterated in when you use these methods. All it promises is that every entry will appear exactly once.</p>
|
||
</main>
|
||
</div>
|
||
<footer>
|
||
<div class="page">
|
||
<div class="main-column">
|
||
<p>Wren lives <a href="https://github.com/munificent/wren">on GitHub</a> — Made with ❤ by <a href="http://journal.stuffwithstuff.com/">Bob Nystrom</a> and <a href="https://github.com/munificent/wren/blob/master/AUTHORS">friends</a>.</p>
|
||
<div class="main-column">
|
||
</div>
|
||
</footer>
|
||
</body>
|
||
</html> |