docs/versions/7.4.0/rules/lib/core/dict.mdx - bazel - Git at Google

 <html devsite>
 <head>
   <meta name="project_path" value="/_project.yaml">
   <meta name="book_path" value="/versions/7.4.0/_book.yaml">
 </head>
 <body>

 <h1 class="page-title" id="modules.dict">dict</h1>

 {% dynamic setvar source_file "src/main/java/net/starlark/java/eval/Dict.java" %}
 {% dynamic setvar version "7.4.0" %}
 {% dynamic setvar original_path "/rules/lib/core/dict" %}
 {% include "_buttons.html" %}
 <!-- {% raw %} -->

 dict is a built-in type representing an associative mapping or <i>dictionary</i>. A dictionary supports indexing using <code>d[k]</code> and key membership testing using <code>k in d</code>; both operations take constant time. Unfrozen dictionaries are mutable, and may be updated by assigning to <code>d[k]</code> or by calling certain methods. Dictionaries are iterable; iteration yields the sequence of keys in insertion order. Iteration order is unaffected by updating the value associated with an existing key, but is affected by removing then reinserting a key.
 <pre>d = {0: 0, 2: 2, 1: 1}
 [k for k in d]  # [0, 2, 1]
 d.pop(2)
 d[0], d[2] = "a", "b"
 0 in d, "a" in d  # (True, False)
 [(k, v) for k, v in d.items()]  # [(0, "a"), (1, 1), (2, "b")]
 </pre>
 <p>There are four ways to construct a dictionary:
 <ol>
 <li>A dictionary expression <code>{k: v, ...}</code> yields a new dictionary with the specified key/value entries, inserted in the order they appear in the expression. Evaluation fails if any two key expressions yield the same value.
 <li>A dictionary comprehension <code>{k: v for vars in seq}</code> yields a new dictionary into which each key/value pair is inserted in loop iteration order. Duplicates are permitted: the first insertion of a given key determines its position in the sequence, and the last determines its associated value.
 <pre class="language-python">
 {k: v for k, v in (("a", 0), ("b", 1), ("a", 2))}  # {"a": 2, "b": 1}
 {i: 2*i for i in range(3)}  # {0: 0, 1: 2, 2: 4}
 </pre>
 <li>A call to the built-in <a href="../globals/all.html#dict">dict</a> function returns a dictionary containing the specified entries, which are inserted in argument order, positional arguments before named. As with comprehensions, duplicate keys are permitted.
 <li>The union expression <code>x | y</code> yields a new dictionary by combining two existing dictionaries. If the two dictionaries have a key <code>k</code> in common, the right hand side dictionary's value of the key (in other words, <code>y[k]</code>) wins. The <code>|=</code> variant of the union operator modifies a dictionary in-place. Example:<br><pre class=language-python>d = {"foo": "FOO", "bar": "BAR"} | {"foo": "FOO2", "baz": "BAZ"}
 # d == {"foo": "FOO2", "bar": "BAR", "baz": "BAZ"}
 d = {"a": 1, "b": 2}
 d |= {"b": 3, "c": 4}
 # d == {"a": 1, "b": 3, "c": 4}</pre></ol>

 <h2>Members</h2>
 <ul>
     <li>
     <a href="#clear">clear</a>
   </li>
       <li>
     <a href="#get">get</a>
   </li>
       <li>
     <a href="#items">items</a>
   </li>
       <li>
     <a href="#keys">keys</a>
   </li>
       <li>
     <a href="#pop">pop</a>
   </li>
       <li>
     <a href="#popitem">popitem</a>
   </li>
       <li>
     <a href="#setdefault">setdefault</a>
   </li>
       <li>
     <a href="#update">update</a>
   </li>
       <li>
     <a href="#values">values</a>
   </li>
   </ul>

       <h2 id="clear">clear</h2>
         <p><pre class="rule-signature"><code>None</code> dict.clear()</pre></p>

     Remove all items from the dictionary.


         <h2 id="get">get</h2>
         <p><pre class="rule-signature">unknown dict.get(key, default=None)</pre></p>

     Returns the value for <code>key</code> if <code>key</code> is in the dictionary, else <code>default</code>. If <code>default</code> is not given, it defaults to <code>None</code>, so that this method never throws an error.

           <!-- hide-from-toc is a class used by DevSite for the public Bazel site
       (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
       <h3 class="hide-from-toc">Parameters</h3>
       <table class="table table-bordered table-condensed table-params">
         <colgroup>
           <col class="col-param">
           <col class="param-description">
         </colgroup>
         <thead>
           <tr>
             <th>Parameter</th>
             <th>Description</th>
           </tr>
         </thead>
         <tbody>
                   <tr>
             <td id="get.key">
               <code>key</code>
             </td>
             <td>
                                      required<br/>
                           The key to look for.
             </td>
           </tr>
                   <tr>
             <td id="get.default">
               <code>default</code>
             </td>
             <td>
                                      default is <code>None</code><br/>
                           The default value to use (instead of None) if the key is not found.
             </td>
           </tr>
                 </tbody>
       </table>

         <h2 id="items">items</h2>
         <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dict.items()</pre></p>

     Returns the list of key-value tuples:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.items() == [(2, "a"), (4, "b"), (1, "c")]</pre>


         <h2 id="keys">keys</h2>
         <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dict.keys()</pre></p>

     Returns the list of keys:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.keys() == [2, 4, 1]</pre>


         <h2 id="pop">pop</h2>
         <p><pre class="rule-signature">unknown dict.pop(key, default=unbound)</pre></p>

     Removes a <code>key</code> from the dict, and returns the associated value. If no entry with that key was found, remove nothing and return the specified <code>default</code> value; if no default value was specified, fail instead.

           <!-- hide-from-toc is a class used by DevSite for the public Bazel site
       (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
       <h3 class="hide-from-toc">Parameters</h3>
       <table class="table table-bordered table-condensed table-params">
         <colgroup>
           <col class="col-param">
           <col class="param-description">
         </colgroup>
         <thead>
           <tr>
             <th>Parameter</th>
             <th>Description</th>
           </tr>
         </thead>
         <tbody>
                   <tr>
             <td id="pop.key">
               <code>key</code>
             </td>
             <td>
                                      required<br/>
                           The key.
             </td>
           </tr>
                   <tr>
             <td id="pop.default">
               <code>default</code>
             </td>
             <td>
                                      default is <code>unbound</code><br/>
                           a default value if the key is absent.
             </td>
           </tr>
                 </tbody>
       </table>

         <h2 id="popitem">popitem</h2>
         <p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> dict.popitem()</pre></p>

     Remove and return the first <code>(key, value)</code> pair from the dictionary. <code>popitem</code> is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, the <code>popitem</code> call fails.


         <h2 id="setdefault">setdefault</h2>
         <p><pre class="rule-signature">unknown dict.setdefault(key, default=None)</pre></p>

     If <code>key</code> is in the dictionary, return its value. If not, insert key with a value of <code>default</code> and return <code>default</code>. <code>default</code> defaults to <code>None</code>.

           <!-- hide-from-toc is a class used by DevSite for the public Bazel site
       (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
       <h3 class="hide-from-toc">Parameters</h3>
       <table class="table table-bordered table-condensed table-params">
         <colgroup>
           <col class="col-param">
           <col class="param-description">
         </colgroup>
         <thead>
           <tr>
             <th>Parameter</th>
             <th>Description</th>
           </tr>
         </thead>
         <tbody>
                   <tr>
             <td id="setdefault.key">
               <code>key</code>
             </td>
             <td>
                                      required<br/>
                           The key.
             </td>
           </tr>
                   <tr>
             <td id="setdefault.default">
               <code>default</code>
             </td>
             <td>
                                      default is <code>None</code><br/>
                           a default value if the key is absent.
             </td>
           </tr>
                 </tbody>
       </table>

         <h2 id="update">update</h2>
         <p><pre class="rule-signature"><code>None</code> dict.update(pairs=[], **kwargs)</pre></p>

     Updates the dictionary first with the optional positional argument, <code>pairs</code>,  then with the optional keyword arguments
 If the positional argument is present, it must be a dict, iterable, or None.
 If it is a dict, then its key/value pairs are inserted into this dict. If it is an iterable, it must provide a sequence of pairs (or other iterables of length 2), each of which is treated as a key/value pair to be inserted.
 Each keyword argument <code>name=value</code> causes the name/value pair to be inserted into this dict.

           <!-- hide-from-toc is a class used by DevSite for the public Bazel site
       (https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
       <h3 class="hide-from-toc">Parameters</h3>
       <table class="table table-bordered table-condensed table-params">
         <colgroup>
           <col class="col-param">
           <col class="param-description">
         </colgroup>
         <thead>
           <tr>
             <th>Parameter</th>
             <th>Description</th>
           </tr>
         </thead>
         <tbody>
                   <tr>
             <td id="update.pairs">
               <code>pairs</code>
             </td>
             <td>
                                      default is <code>[]</code><br/>
                           Either a dictionary or a list of entries. Entries must be tuples or lists with exactly two elements: key, value.
             </td>
           </tr>
                   <tr>
             <td id="update.kwargs">
               <code>kwargs</code>
             </td>
             <td>
                                      required<br/>
                           Dictionary of additional entries.
             </td>
           </tr>
                 </tbody>
       </table>

         <h2 id="values">values</h2>
         <p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dict.values()</pre></p>

     Returns the list of values:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.values() == ["a", "b", "c"]</pre>


 </body>
 </html>

 <!-- {% endraw %} -->
	<html devsite>
	<head>
	<meta name="project_path" value="/_project.yaml">
	<meta name="book_path" value="/versions/7.4.0/_book.yaml">
	</head>
	<body>

	<h1 class="page-title" id="modules.dict">dict</h1>

	{% dynamic setvar source_file "src/main/java/net/starlark/java/eval/Dict.java" %}
	{% dynamic setvar version "7.4.0" %}
	{% dynamic setvar original_path "/rules/lib/core/dict" %}
	{% include "_buttons.html" %}
	<!-- {% raw %} -->

	dict is a built-in type representing an associative mapping or <i>dictionary</i>. A dictionary supports indexing using <code>d[k]</code> and key membership testing using <code>k in d</code>; both operations take constant time. Unfrozen dictionaries are mutable, and may be updated by assigning to <code>d[k]</code> or by calling certain methods. Dictionaries are iterable; iteration yields the sequence of keys in insertion order. Iteration order is unaffected by updating the value associated with an existing key, but is affected by removing then reinserting a key.
	<pre>d = {0: 0, 2: 2, 1: 1}
	[k for k in d] # [0, 2, 1]
	d.pop(2)
	d[0], d[2] = "a", "b"
	0 in d, "a" in d # (True, False)
	[(k, v) for k, v in d.items()] # [(0, "a"), (1, 1), (2, "b")]
	</pre>
	<p>There are four ways to construct a dictionary:
	<ol>
	<li>A dictionary expression <code>{k: v, ...}</code> yields a new dictionary with the specified key/value entries, inserted in the order they appear in the expression. Evaluation fails if any two key expressions yield the same value.
	<li>A dictionary comprehension <code>{k: v for vars in seq}</code> yields a new dictionary into which each key/value pair is inserted in loop iteration order. Duplicates are permitted: the first insertion of a given key determines its position in the sequence, and the last determines its associated value.
	<pre class="language-python">
	{k: v for k, v in (("a", 0), ("b", 1), ("a", 2))} # {"a": 2, "b": 1}
	{i: 2*i for i in range(3)} # {0: 0, 1: 2, 2: 4}
	</pre>
	<li>A call to the built-in <a href="../globals/all.html#dict">dict</a> function returns a dictionary containing the specified entries, which are inserted in argument order, positional arguments before named. As with comprehensions, duplicate keys are permitted.
	<li>The union expression <code>x \| y</code> yields a new dictionary by combining two existing dictionaries. If the two dictionaries have a key <code>k</code> in common, the right hand side dictionary's value of the key (in other words, <code>y[k]</code>) wins. The <code>\|=</code> variant of the union operator modifies a dictionary in-place. Example:<br><pre class=language-python>d = {"foo": "FOO", "bar": "BAR"} \| {"foo": "FOO2", "baz": "BAZ"}
	# d == {"foo": "FOO2", "bar": "BAR", "baz": "BAZ"}
	d = {"a": 1, "b": 2}
	d \|= {"b": 3, "c": 4}
	# d == {"a": 1, "b": 3, "c": 4}</pre></ol>

	<h2>Members</h2>
	<ul>
	<li>
	<a href="#clear">clear</a>
	</li>
	<li>
	<a href="#get">get</a>
	</li>
	<li>
	<a href="#items">items</a>
	</li>
	<li>
	<a href="#keys">keys</a>
	</li>
	<li>
	<a href="#pop">pop</a>
	</li>
	<li>
	<a href="#popitem">popitem</a>
	</li>
	<li>
	<a href="#setdefault">setdefault</a>
	</li>
	<li>
	<a href="#update">update</a>
	</li>
	<li>
	<a href="#values">values</a>
	</li>
	</ul>

	<h2 id="clear">clear</h2>
	<p><pre class="rule-signature"><code>None</code> dict.clear()</pre></p>

	Remove all items from the dictionary.


	<h2 id="get">get</h2>
	<p><pre class="rule-signature">unknown dict.get(key, default=None)</pre></p>

	Returns the value for <code>key</code> if <code>key</code> is in the dictionary, else <code>default</code>. If <code>default</code> is not given, it defaults to <code>None</code>, so that this method never throws an error.

	<!-- hide-from-toc is a class used by DevSite for the public Bazel site
	(https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
	<h3 class="hide-from-toc">Parameters</h3>
	<table class="table table-bordered table-condensed table-params">
	<colgroup>
	<col class="col-param">
	<col class="param-description">
	</colgroup>
	<thead>
	<tr>
	<th>Parameter</th>
	<th>Description</th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<td id="get.key">
	<code>key</code>
	</td>
	<td>
	required<br/>
	The key to look for.
	</td>
	</tr>
	<tr>
	<td id="get.default">
	<code>default</code>
	</td>
	<td>
	default is <code>None</code><br/>
	The default value to use (instead of None) if the key is not found.
	</td>
	</tr>
	</tbody>
	</table>

	<h2 id="items">items</h2>
	<p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dict.items()</pre></p>

	Returns the list of key-value tuples:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.items() == [(2, "a"), (4, "b"), (1, "c")]</pre>



	<h2 id="keys">keys</h2>
	<p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dict.keys()</pre></p>

	Returns the list of keys:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.keys() == [2, 4, 1]</pre>



	<h2 id="pop">pop</h2>
	<p><pre class="rule-signature">unknown dict.pop(key, default=unbound)</pre></p>

	Removes a <code>key</code> from the dict, and returns the associated value. If no entry with that key was found, remove nothing and return the specified <code>default</code> value; if no default value was specified, fail instead.

	<!-- hide-from-toc is a class used by DevSite for the public Bazel site
	(https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
	<h3 class="hide-from-toc">Parameters</h3>
	<table class="table table-bordered table-condensed table-params">
	<colgroup>
	<col class="col-param">
	<col class="param-description">
	</colgroup>
	<thead>
	<tr>
	<th>Parameter</th>
	<th>Description</th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<td id="pop.key">
	<code>key</code>
	</td>
	<td>
	required<br/>
	The key.
	</td>
	</tr>
	<tr>
	<td id="pop.default">
	<code>default</code>
	</td>
	<td>
	default is <code>unbound</code><br/>
	a default value if the key is absent.
	</td>
	</tr>
	</tbody>
	</table>

	<h2 id="popitem">popitem</h2>
	<p><pre class="rule-signature"><a class="anchor" href="../core/tuple.html">tuple</a> dict.popitem()</pre></p>

	Remove and return the first <code>(key, value)</code> pair from the dictionary. <code>popitem</code> is useful to destructively iterate over a dictionary, as often used in set algorithms. If the dictionary is empty, the <code>popitem</code> call fails.


	<h2 id="setdefault">setdefault</h2>
	<p><pre class="rule-signature">unknown dict.setdefault(key, default=None)</pre></p>

	If <code>key</code> is in the dictionary, return its value. If not, insert key with a value of <code>default</code> and return <code>default</code>. <code>default</code> defaults to <code>None</code>.

	<!-- hide-from-toc is a class used by DevSite for the public Bazel site
	(https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
	<h3 class="hide-from-toc">Parameters</h3>
	<table class="table table-bordered table-condensed table-params">
	<colgroup>
	<col class="col-param">
	<col class="param-description">
	</colgroup>
	<thead>
	<tr>
	<th>Parameter</th>
	<th>Description</th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<td id="setdefault.key">
	<code>key</code>
	</td>
	<td>
	required<br/>
	The key.
	</td>
	</tr>
	<tr>
	<td id="setdefault.default">
	<code>default</code>
	</td>
	<td>
	default is <code>None</code><br/>
	a default value if the key is absent.
	</td>
	</tr>
	</tbody>
	</table>

	<h2 id="update">update</h2>
	<p><pre class="rule-signature"><code>None</code> dict.update(pairs=[], **kwargs)</pre></p>

	Updates the dictionary first with the optional positional argument, <code>pairs</code>, then with the optional keyword arguments
	If the positional argument is present, it must be a dict, iterable, or None.
	If it is a dict, then its key/value pairs are inserted into this dict. If it is an iterable, it must provide a sequence of pairs (or other iterables of length 2), each of which is treated as a key/value pair to be inserted.
	Each keyword argument <code>name=value</code> causes the name/value pair to be inserted into this dict.

	<!-- hide-from-toc is a class used by DevSite for the public Bazel site
	(https://developers.google.com/devsite/reference/styles/headings#hide_headings_from_the_toc) -->
	<h3 class="hide-from-toc">Parameters</h3>
	<table class="table table-bordered table-condensed table-params">
	<colgroup>
	<col class="col-param">
	<col class="param-description">
	</colgroup>
	<thead>
	<tr>
	<th>Parameter</th>
	<th>Description</th>
	</tr>
	</thead>
	<tbody>
	<tr>
	<td id="update.pairs">
	<code>pairs</code>
	</td>
	<td>
	default is <code>[]</code><br/>
	Either a dictionary or a list of entries. Entries must be tuples or lists with exactly two elements: key, value.
	</td>
	</tr>
	<tr>
	<td id="update.kwargs">
	<code>kwargs</code>
	</td>
	<td>
	required<br/>
	Dictionary of additional entries.
	</td>
	</tr>
	</tbody>
	</table>

	<h2 id="values">values</h2>
	<p><pre class="rule-signature"><a class="anchor" href="../core/list.html">list</a> dict.values()</pre></p>

	Returns the list of values:<pre class="language-python">{2: "a", 4: "b", 1: "c"}.values() == ["a", "b", "c"]</pre>




	</body>
	</html>

	<!-- {% endraw %} -->