danvics/oxipng
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
oxipng/doc/bitflags/__core/option/index.html
Joshua Holmer f8deac1cea Update generated documentation [ci skip]
2016-04-20 15:59:23 -04:00

263 lines
No EOL
16 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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 `bitflags`.">
<meta name="keywords" content="rust, rustlang, rust-lang, option">
<title>bitflags::__core::option - Rust</title>
<link rel="stylesheet" type="text/css" href="../../../rustdoc.css">
<link rel="stylesheet" type="text/css" href="../../../main.css">
</head>
<body class="rustdoc">
<!--[if lte IE 8]>
<div class="warning">
This old browser is unsupported and will most likely display funky
things.
</div>
<![endif]-->
<nav class="sidebar">
<p class='location'><a href='../../index.html'>bitflags</a>::<wbr><a href='../index.html'>__core</a></p><script>window.sidebarCurrent = {name: 'option', ty: 'mod', relpath: '../'};</script><script defer src="../sidebar-items.js"></script>
</nav>
<nav class="sub">
<form class="search-form js-only">
<div class="search-container">
<input class="search-input" name="search"
autocomplete="off"
placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
type="search">
</div>
</form>
</nav>
<section id='main' class="content mod">
<h1 class='fqn'><span class='in-band'>Module <a href='../../index.html'>bitflags</a>::<wbr><a href='../index.html'>__core</a>::<wbr><a class='mod' href=''>option</a></span><span class='out-of-band'><span id='render-detail'>
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
[<span class='inner'>&#x2212;</span>]
</a>
</span><a id='src-30165' class='srclink' href='https://doc.rust-lang.org/nightly/core/option/index.html?gotosrc=30165' title='goto source code'>[src]</a></span></h1>
<div class='docblock'><p>Optional values.</p>
<p>Type <code>Option</code> represents an optional value: every <code>Option</code>
is either <code>Some</code> and contains a value, or <code>None</code>, and
does not. <code>Option</code> 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 <code>None</code> is
returned on error</li>
<li>Optional struct fields</li>
<li>Struct fields that can be loaned or &quot;taken&quot;</li>
<li>Optional function arguments</li>
<li>Nullable pointers</li>
<li>Swapping things out of difficult situations</li>
</ul>
<p>Options are commonly paired with pattern matching to query the presence
of a value and take action, always accounting for the <code>None</code> case.</p>
<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'>-&gt;</span> <span class='prelude-ty'>Option</span><span class='op'>&lt;</span><span class='ident'>f64</span><span class='op'>&gt;</span> {
<span class='kw'>if</span> <span class='ident'>denominator</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'>=&gt;</span> <span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;Result: {}&quot;</span>, <span class='ident'>x</span>),
<span class='comment'>// The division was invalid</span>
<span class='prelude-val'>None</span> <span class='op'>=&gt;</span> <span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;Cannot divide by 0&quot;</span>),
}</pre>
<h1 id='options-and-pointers-nullable-pointers' class='section-header'><a href='#options-and-pointers-nullable-pointers'>Options and pointers (&quot;nullable&quot; pointers)</a></h1>
<p>Rust&#39;s pointer types must always point to a valid location; there are
no &quot;null&quot; pointers. Instead, Rust has <em>optional</em> pointers, like
the optional owned box, <code>Option&lt;Box&lt;T&gt;&gt;</code>.</p>
<p>The following example uses <code>Option</code> to create an optional box of
<code>i32</code>. Notice that in order to use the inner <code>i32</code> 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 <code>Some(...)</code>) or
not (<code>None</code>).</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>let</span> <span class='ident'>optional</span>: <span class='prelude-ty'>Option</span><span class='op'>&lt;</span><span class='ident'>Box</span><span class='op'>&lt;</span><span class='ident'>i32</span><span class='op'>&gt;&gt;</span> <span class='op'>=</span> <span class='prelude-val'>None</span>;
<span class='ident'>check_optional</span>(<span class='kw-2'>&amp;</span><span class='ident'>optional</span>);
<span class='kw'>let</span> <span class='ident'>optional</span>: <span class='prelude-ty'>Option</span><span class='op'>&lt;</span><span class='ident'>Box</span><span class='op'>&lt;</span><span class='ident'>i32</span><span class='op'>&gt;&gt;</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='kw-2'>&amp;</span><span class='ident'>optional</span>);
<span class='kw'>fn</span> <span class='ident'>check_optional</span>(<span class='ident'>optional</span>: <span class='kw-2'>&amp;</span><span class='prelude-ty'>Option</span><span class='op'>&lt;</span><span class='ident'>Box</span><span class='op'>&lt;</span><span class='ident'>i32</span><span class='op'>&gt;&gt;</span>) {
<span class='kw'>match</span> <span class='op'>*</span><span class='ident'>optional</span> {
<span class='prelude-val'>Some</span>(<span class='kw-2'>ref</span> <span class='ident'>p</span>) <span class='op'>=&gt;</span> <span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;have value {}&quot;</span>, <span class='ident'>p</span>),
<span class='prelude-val'>None</span> <span class='op'>=&gt;</span> <span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;have no value&quot;</span>),
}
}</pre>
<p>This usage of <code>Option</code> to create safe nullable pointers is so
common that Rust does special optimizations to make the
representation of <code>Option&lt;Box&lt;T&gt;&gt;</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 <code>Option</code>:</p>
<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'>&quot;howdy&quot;</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='kw-2'>ref</span> <span class='ident'>m</span>) <span class='op'>=</span> <span class='ident'>msg</span> {
<span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;{}&quot;</span>, <span class='op'>*</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'>&quot;default message&quot;</span>);</pre>
<p>Initialize a result to <code>None</code> before a loop:</p>
<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'>&amp;</span><span class='lifetime'>&#39;static</span> <span class='ident'>str</span>), <span class='ident'>Animal</span>(<span class='ident'>u32</span>, <span class='kw-2'>&amp;</span><span class='lifetime'>&#39;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'>&quot;redwood&quot;</span>),
<span class='ident'>Kingdom</span>::<span class='ident'>Plant</span>(<span class='number'>230</span>, <span class='string'>&quot;noble fir&quot;</span>),
<span class='ident'>Kingdom</span>::<span class='ident'>Plant</span>(<span class='number'>229</span>, <span class='string'>&quot;sugar pine&quot;</span>),
<span class='ident'>Kingdom</span>::<span class='ident'>Animal</span>(<span class='number'>25</span>, <span class='string'>&quot;blue whale&quot;</span>),
<span class='ident'>Kingdom</span>::<span class='ident'>Animal</span>(<span class='number'>19</span>, <span class='string'>&quot;fin whale&quot;</span>),
<span class='ident'>Kingdom</span>::<span class='ident'>Animal</span>(<span class='number'>15</span>, <span class='string'>&quot;north pacific right whale&quot;</span>),
];
<span class='comment'>// We&#39;re going to search for the name of the biggest animal,</span>
<span class='comment'>// but to start with we&#39;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'>&amp;</span><span class='ident'>all_the_big_things</span> {
<span class='kw'>match</span> <span class='op'>*</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'>&gt;</span> <span class='ident'>size_of_biggest_animal</span> <span class='op'>=&gt;</span> {
<span class='comment'>// Now we&#39;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'>=&gt;</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'>=&gt;</span> <span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;the biggest animal is {}&quot;</span>, <span class='ident'>name</span>),
<span class='prelude-val'>None</span> <span class='op'>=&gt;</span> <span class='macro'>println</span><span class='macro'>!</span>(<span class='string'>&quot;there are no animals :(&quot;</span>),
}</pre>
</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='bitflags::__core::option::IntoIter'>IntoIter</a></td>
<td class='docblock short'>
<p>An iterator over the item contained inside an Option.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='struct' href='struct.Iter.html'
title='bitflags::__core::option::Iter'>Iter</a></td>
<td class='docblock short'>
<p>An iterator over a reference of the contained item in an Option.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='struct' href='struct.IterMut.html'
title='bitflags::__core::option::IterMut'>IterMut</a></td>
<td class='docblock short'>
<p>An iterator over a mutable reference of the contained item in an Option.</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='bitflags::__core::option::Option'>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>
<aside id="help" class="hidden">
<div>
<h1 class="hidden">Help</h1>
<div class="shortcuts">
<h2>Keyboard Shortcuts</h2>
<dl>
<dt>?</dt>
<dd>Show this help dialog</dd>
<dt>S</dt>
<dd>Focus the search field</dd>
<dt>&larrb;</dt>
<dd>Move up in search results</dd>
<dt>&rarrb;</dt>
<dd>Move down in search results</dd>
<dt>&#9166;</dt>
<dd>Go to active search result</dd>
</dl>
</div>
<div class="infos">
<h2>Search Tricks</h2>
<p>
Prefix searches with a type followed by a colon (e.g.
<code>fn:</code>) to restrict the search to a given type.
</p>
<p>
Accepted types are: <code>fn</code>, <code>mod</code>,
<code>struct</code>, <code>enum</code>,
<code>trait</code>, <code>type</code>, <code>macro</code>,
and <code>const</code>.
</p>
<p>
Search functions by type signature (e.g.
<code>vec -> usize</code> or <code>* -> vec</code>)
</p>
</div>
</div>
</aside>
<script>
window.rootPath = "../../../";
window.currentCrate = "bitflags";
window.playgroundUrl = "";
</script>
<script src="../../../jquery.js"></script>
<script src="../../../main.js"></script>
<script defer src="../../../search-index.js"></script>
</body>
</html>
Reference in a new issue View git blame Copy permalink