124 lines
17 KiB
HTML
124 lines
17 KiB
HTML
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="API documentation for the Rust `option` mod in crate `nom`."><meta name="keywords" content="rust, rustlang, rust-lang, option"><title>nom::lib::std::option - Rust</title><link rel="stylesheet" type="text/css" href="../../../../normalize.css"><link rel="stylesheet" type="text/css" href="../../../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../../../../dark.css"><link rel="stylesheet" type="text/css" href="../../../../light.css" id="themeStyle"><script src="../../../../storage.js"></script><noscript><link rel="stylesheet" href="../../../../noscript.css"></noscript><link rel="shortcut icon" href="../../../../favicon.ico"><style type="text/css">#crate-search{background-image:url("../../../../down-arrow.svg");}</style></head><body class="rustdoc mod"><!--[if lte IE 8]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu">☰</div><a href='../../../../nom/index.html'><div class='logo-container'><img src='../../../../rust-logo.png' alt='logo'></div></a><p class='location'>Module option</p><div class="sidebar-elems"><div class="block items"><ul><li><a href="#structs">Structs</a></li><li><a href="#enums">Enums</a></li></ul></div><p class='location'><a href='../../../index.html'>nom</a>::<wbr><a href='../../index.html'>lib</a>::<wbr><a href='../index.html'>std</a></p><script>window.sidebarCurrent = {name: 'option', ty: 'mod', relpath: '../'};</script><script defer src="../sidebar-items.js"></script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!"><img src="../../../../brush.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices"></div></div><script src="../../../../theme.js"></script><nav class="sub"><form class="search-form"><div class="search-container"><div><select id="crate-search"><option value="All crates">All crates</option></select><input class="search-input" name="search" disabled autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"></div><a id="settings-menu" href="../../../../settings.html"><img src="../../../../wheel.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class='fqn'><span class='out-of-band'><span class='since' title='Stable since Rust version 1.0.0'>1.0.0</span><span id='render-detail'><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class='inner'>−</span>]</a></span><a class='srclink' href='https://doc.rust-lang.org/nightly/src/core/lib.rs.html#230' title='goto source code'>[src]</a></span><span class='in-band'>Module <a href='../../../index.html'>nom</a>::<wbr><a href='../../index.html'>lib</a>::<wbr><a href='../index.html'>std</a>::<wbr><a class="mod" href=''>option</a></span></h1><div class='docblock'><p>Optional values.</p>
|
||
<p>Type <a href="enum.Option.html"><code>Option</code></a> represents an optional value: every <a href="enum.Option.html"><code>Option</code></a>
|
||
is either <a href="enum.Option.html#variant.Some"><code>Some</code></a> and contains a value, or <a href="enum.Option.html#variant.None"><code>None</code></a>, and
|
||
does not. <a href="enum.Option.html"><code>Option</code></a> types are very common in Rust code, as
|
||
they have a number of uses:</p>
|
||
<ul>
|
||
<li>Initial values</li>
|
||
<li>Return values for functions that are not defined
|
||
over their entire input range (partial functions)</li>
|
||
<li>Return value for otherwise reporting simple errors, where <a href="enum.Option.html#variant.None"><code>None</code></a> is
|
||
returned on error</li>
|
||
<li>Optional struct fields</li>
|
||
<li>Struct fields that can be loaned or "taken"</li>
|
||
<li>Optional function arguments</li>
|
||
<li>Nullable pointers</li>
|
||
<li>Swapping things out of difficult situations</li>
|
||
</ul>
|
||
<p><a href="enum.Option.html"><code>Option</code></a>s are commonly paired with pattern matching to query the presence
|
||
of a value and take action, always accounting for the <a href="enum.Option.html#variant.None"><code>None</code></a> case.</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
<span class="kw">fn</span> <span class="ident">divide</span>(<span class="ident">numerator</span>: <span class="ident">f64</span>, <span class="ident">denominator</span>: <span class="ident">f64</span>) <span class="op">-</span><span class="op">></span> <span class="prelude-ty">Option</span><span class="op"><</span><span class="ident">f64</span><span class="op">></span> {
|
||
<span class="kw">if</span> <span class="ident">denominator</span> <span class="op">=</span><span class="op">=</span> <span class="number">0.0</span> {
|
||
<span class="prelude-val">None</span>
|
||
} <span class="kw">else</span> {
|
||
<span class="prelude-val">Some</span>(<span class="ident">numerator</span> <span class="op">/</span> <span class="ident">denominator</span>)
|
||
}
|
||
}
|
||
|
||
<span class="comment">// The return value of the function is an option</span>
|
||
<span class="kw">let</span> <span class="ident">result</span> <span class="op">=</span> <span class="ident">divide</span>(<span class="number">2.0</span>, <span class="number">3.0</span>);
|
||
|
||
<span class="comment">// Pattern match to retrieve the value</span>
|
||
<span class="kw">match</span> <span class="ident">result</span> {
|
||
<span class="comment">// The division was valid</span>
|
||
<span class="prelude-val">Some</span>(<span class="ident">x</span>) <span class="op">=</span><span class="op">></span> <span class="macro">println</span><span class="macro">!</span>(<span class="string">"Result: {}"</span>, <span class="ident">x</span>),
|
||
<span class="comment">// The division was invalid</span>
|
||
<span class="prelude-val">None</span> <span class="op">=</span><span class="op">></span> <span class="macro">println</span><span class="macro">!</span>(<span class="string">"Cannot divide by 0"</span>),
|
||
}</pre></div>
|
||
<h1 id="options-and-pointers-nullable-pointers" class="section-header"><a href="#options-and-pointers-nullable-pointers">Options and pointers ("nullable" pointers)</a></h1>
|
||
<p>Rust's pointer types must always point to a valid location; there are
|
||
no "null" references. Instead, Rust has <em>optional</em> pointers, like
|
||
the optional owned box, <a href="enum.Option.html"><code>Option</code></a><code><</code><a href="../../std/boxed/struct.Box.html"><code>Box<T></code></a><code>></code>.</p>
|
||
<p>The following example uses <a href="enum.Option.html"><code>Option</code></a> to create an optional box of
|
||
<a href="../../std/primitive.i32.html"><code>i32</code></a>. Notice that in order to use the inner <a href="../../std/primitive.i32.html"><code>i32</code></a> value first, the
|
||
<code>check_optional</code> function needs to use pattern matching to
|
||
determine whether the box has a value (i.e., it is <a href="enum.Option.html#variant.Some"><code>Some(...)</code></a>) or
|
||
not (<a href="enum.Option.html#variant.None"><code>None</code></a>).</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
<span class="kw">let</span> <span class="ident">optional</span> <span class="op">=</span> <span class="prelude-val">None</span>;
|
||
<span class="ident">check_optional</span>(<span class="ident">optional</span>);
|
||
|
||
<span class="kw">let</span> <span class="ident">optional</span> <span class="op">=</span> <span class="prelude-val">Some</span>(<span class="ident">Box</span>::<span class="ident">new</span>(<span class="number">9000</span>));
|
||
<span class="ident">check_optional</span>(<span class="ident">optional</span>);
|
||
|
||
<span class="kw">fn</span> <span class="ident">check_optional</span>(<span class="ident">optional</span>: <span class="prelude-ty">Option</span><span class="op"><</span><span class="ident">Box</span><span class="op"><</span><span class="ident">i32</span><span class="op">></span><span class="op">></span>) {
|
||
<span class="kw">match</span> <span class="ident">optional</span> {
|
||
<span class="prelude-val">Some</span>(<span class="ident">p</span>) <span class="op">=</span><span class="op">></span> <span class="macro">println</span><span class="macro">!</span>(<span class="string">"has value {}"</span>, <span class="ident">p</span>),
|
||
<span class="prelude-val">None</span> <span class="op">=</span><span class="op">></span> <span class="macro">println</span><span class="macro">!</span>(<span class="string">"has no value"</span>),
|
||
}
|
||
}</pre></div>
|
||
<p>This usage of <a href="enum.Option.html"><code>Option</code></a> to create safe nullable pointers is so
|
||
common that Rust does special optimizations to make the
|
||
representation of <a href="enum.Option.html"><code>Option</code></a><code><</code><a href="../../std/boxed/struct.Box.html"><code>Box<T></code></a><code>></code> a single pointer. Optional pointers
|
||
in Rust are stored as efficiently as any other pointer type.</p>
|
||
<h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
|
||
<p>Basic pattern matching on <a href="enum.Option.html"><code>Option</code></a>:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
<span class="kw">let</span> <span class="ident">msg</span> <span class="op">=</span> <span class="prelude-val">Some</span>(<span class="string">"howdy"</span>);
|
||
|
||
<span class="comment">// Take a reference to the contained string</span>
|
||
<span class="kw">if</span> <span class="kw">let</span> <span class="prelude-val">Some</span>(<span class="ident">m</span>) <span class="op">=</span> <span class="kw-2">&</span><span class="ident">msg</span> {
|
||
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"{}"</span>, <span class="kw-2">*</span><span class="ident">m</span>);
|
||
}
|
||
|
||
<span class="comment">// Remove the contained string, destroying the Option</span>
|
||
<span class="kw">let</span> <span class="ident">unwrapped_msg</span> <span class="op">=</span> <span class="ident">msg</span>.<span class="ident">unwrap_or</span>(<span class="string">"default message"</span>);</pre></div>
|
||
<p>Initialize a result to <a href="enum.Option.html#variant.None"><code>None</code></a> before a loop:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
||
<span class="kw">enum</span> <span class="ident">Kingdom</span> { <span class="ident">Plant</span>(<span class="ident">u32</span>, <span class="kw-2">&</span><span class="lifetime">'static</span> <span class="ident">str</span>), <span class="ident">Animal</span>(<span class="ident">u32</span>, <span class="kw-2">&</span><span class="lifetime">'static</span> <span class="ident">str</span>) }
|
||
|
||
<span class="comment">// A list of data to search through.</span>
|
||
<span class="kw">let</span> <span class="ident">all_the_big_things</span> <span class="op">=</span> [
|
||
<span class="ident">Kingdom</span>::<span class="ident">Plant</span>(<span class="number">250</span>, <span class="string">"redwood"</span>),
|
||
<span class="ident">Kingdom</span>::<span class="ident">Plant</span>(<span class="number">230</span>, <span class="string">"noble fir"</span>),
|
||
<span class="ident">Kingdom</span>::<span class="ident">Plant</span>(<span class="number">229</span>, <span class="string">"sugar pine"</span>),
|
||
<span class="ident">Kingdom</span>::<span class="ident">Animal</span>(<span class="number">25</span>, <span class="string">"blue whale"</span>),
|
||
<span class="ident">Kingdom</span>::<span class="ident">Animal</span>(<span class="number">19</span>, <span class="string">"fin whale"</span>),
|
||
<span class="ident">Kingdom</span>::<span class="ident">Animal</span>(<span class="number">15</span>, <span class="string">"north pacific right whale"</span>),
|
||
];
|
||
|
||
<span class="comment">// We're going to search for the name of the biggest animal,</span>
|
||
<span class="comment">// but to start with we've just got `None`.</span>
|
||
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">name_of_biggest_animal</span> <span class="op">=</span> <span class="prelude-val">None</span>;
|
||
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">size_of_biggest_animal</span> <span class="op">=</span> <span class="number">0</span>;
|
||
<span class="kw">for</span> <span class="ident">big_thing</span> <span class="kw">in</span> <span class="kw-2">&</span><span class="ident">all_the_big_things</span> {
|
||
<span class="kw">match</span> <span class="kw-2">*</span><span class="ident">big_thing</span> {
|
||
<span class="ident">Kingdom</span>::<span class="ident">Animal</span>(<span class="ident">size</span>, <span class="ident">name</span>) <span class="kw">if</span> <span class="ident">size</span> <span class="op">></span> <span class="ident">size_of_biggest_animal</span> <span class="op">=</span><span class="op">></span> {
|
||
<span class="comment">// Now we've found the name of some big animal</span>
|
||
<span class="ident">size_of_biggest_animal</span> <span class="op">=</span> <span class="ident">size</span>;
|
||
<span class="ident">name_of_biggest_animal</span> <span class="op">=</span> <span class="prelude-val">Some</span>(<span class="ident">name</span>);
|
||
}
|
||
<span class="ident">Kingdom</span>::<span class="ident">Animal</span>(..) <span class="op">|</span> <span class="ident">Kingdom</span>::<span class="ident">Plant</span>(..) <span class="op">=</span><span class="op">></span> ()
|
||
}
|
||
}
|
||
|
||
<span class="kw">match</span> <span class="ident">name_of_biggest_animal</span> {
|
||
<span class="prelude-val">Some</span>(<span class="ident">name</span>) <span class="op">=</span><span class="op">></span> <span class="macro">println</span><span class="macro">!</span>(<span class="string">"the biggest animal is {}"</span>, <span class="ident">name</span>),
|
||
<span class="prelude-val">None</span> <span class="op">=</span><span class="op">></span> <span class="macro">println</span><span class="macro">!</span>(<span class="string">"there are no animals :("</span>),
|
||
}</pre></div>
|
||
</div><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
|
||
<table><tr class='module-item'><td><a class="struct" href="struct.IntoIter.html" title='nom::lib::std::option::IntoIter struct'>IntoIter</a></td><td class='docblock-short'><p>An iterator over the value in <a href="enum.Option.html#variant.Some"><code>Some</code></a> variant of an <a href="enum.Option.html"><code>Option</code></a>.</p>
|
||
</td></tr><tr class='module-item'><td><a class="struct" href="struct.Iter.html" title='nom::lib::std::option::Iter struct'>Iter</a></td><td class='docblock-short'><p>An iterator over a reference to the <a href="enum.Option.html#variant.Some"><code>Some</code></a> variant of an <a href="enum.Option.html"><code>Option</code></a>.</p>
|
||
</td></tr><tr class='module-item'><td><a class="struct" href="struct.IterMut.html" title='nom::lib::std::option::IterMut struct'>IterMut</a></td><td class='docblock-short'><p>An iterator over a mutable reference to the <a href="enum.Option.html#variant.Some"><code>Some</code></a> variant of an <a href="enum.Option.html"><code>Option</code></a>.</p>
|
||
</td></tr><tr class='unstable module-item'><td><a class="struct" href="struct.NoneError.html" title='nom::lib::std::option::NoneError struct'>NoneError</a></td><td class='docblock-short'><span class="stab unstable">Experimental</span><p>The error type that results from applying the try operator (<code>?</code>) to a <code>None</code> value. If you wish
|
||
to allow <code>x?</code> (where <code>x</code> is an <code>Option<T></code>) to be converted into your error type, you can
|
||
implement <code>impl From<NoneError></code> for <code>YourErrorType</code>. In that case, <code>x?</code> within a function that
|
||
returns <code>Result<_, YourErrorType></code> will translate a <code>None</code> value into an <code>Err</code> result.</p>
|
||
</td></tr></table><h2 id='enums' class='section-header'><a href="#enums">Enums</a></h2>
|
||
<table><tr class='module-item'><td><a class="enum" href="enum.Option.html" title='nom::lib::std::option::Option enum'>Option</a></td><td class='docblock-short'><p>The <code>Option</code> type. See <a href="index.html">the module level documentation</a> for more.</p>
|
||
</td></tr></table></section><section id="search" class="content hidden"></section><section class="footer"></section><script>window.rootPath = "../../../../";window.currentCrate = "nom";</script><script src="../../../../aliases.js"></script><script src="../../../../main.js"></script><script defer src="../../../../search-index.js"></script></body></html> |