563 lines
32 KiB
HTML
563 lines
32 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 `error_chain` crate.">
|
||
<meta name="keywords" content="rust, rustlang, rust-lang, error_chain">
|
||
|
||
<title>error_chain - Rust</title>
|
||
|
||
<link rel="stylesheet" type="text/css" href="../normalize.css">
|
||
<link rel="stylesheet" type="text/css" href="../rustdoc.css">
|
||
<link rel="stylesheet" type="text/css" href="../main.css">
|
||
|
||
|
||
|
||
|
||
</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">
|
||
|
||
<p class='location'>Crate error_chain</p><div class="block items"><ul><li><a href="#modules">Modules</a></li><li><a href="#macros">Macros</a></li><li><a href="#structs">Structs</a></li><li><a href="#traits">Traits</a></li></ul></div><p class='location'></p><script>window.sidebarCurrent = {name: 'error_chain', ty: 'mod', relpath: '../'};</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">
|
||
<h1 class='fqn'><span class='in-band'>Crate <a class="mod" href=''>error_chain</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'>−</span>]
|
||
</a>
|
||
</span><a class='srclink' href='../src/error_chain/lib.rs.html#1-720' title='goto source code'>[src]</a></span></h1>
|
||
<div class='docblock'><p>A library for consistent and reliable error handling</p>
|
||
|
||
<p>error-chain makes it easy to take full advantage of Rust's
|
||
powerful error handling features without the overhead of
|
||
maintaining boilerplate error types and conversions. It implements
|
||
an opinionated strategy for defining your own error types, as well
|
||
as conversions from others' error types.</p>
|
||
|
||
<h2 id='quick-start' class='section-header'><a href='#quick-start'>Quick start</a></h2>
|
||
<p>If you just want to set up your new project with error-chain,
|
||
follow the <a href="https://github.com/brson/error-chain/blob/master/examples/quickstart.rs">quickstart.rs</a> template, and read this <a href="http://brson.github.io/2016/11/30/starting-with-error-chain">intro</a>
|
||
to error-chain.</p>
|
||
|
||
<h2 id='why-error-chain' class='section-header'><a href='#why-error-chain'>Why error chain?</a></h2>
|
||
<ul>
|
||
<li>error-chain is easy to configure. Handle errors robustly with minimal
|
||
effort.</li>
|
||
<li>Basic error handling requires no maintenance of custom error types
|
||
nor the <code>From</code> conversions that make <code>?</code> work.</li>
|
||
<li>error-chain scales from simple error handling strategies to more
|
||
rigorous. Return formatted strings for simple errors, only
|
||
introducing error variants and their strong typing as needed for
|
||
advanced error recovery.</li>
|
||
<li>error-chain makes it trivial to correctly manage the <a href="https://doc.rust-lang.org/std/error/trait.Error.html#method.cause">cause</a> of
|
||
the errors generated by your own code. This is the "chaining"
|
||
in "error-chain".</li>
|
||
</ul>
|
||
|
||
<h2 id='principles-of-error-chain' class='section-header'><a href='#principles-of-error-chain'>Principles of error-chain</a></h2>
|
||
<p>error-chain is based on the following principles:</p>
|
||
|
||
<ul>
|
||
<li>No error should ever be discarded. This library primarily
|
||
makes it easy to "chain" errors with the <code>chain_err</code> method.</li>
|
||
<li>Introducing new errors is trivial. Simple errors can be introduced
|
||
at the error site with just a string.</li>
|
||
<li>Handling errors is possible with pattern matching.</li>
|
||
<li>Conversions between error types are done in an automatic and
|
||
consistent way - <code>From</code> conversion behavior is never specified
|
||
explicitly.</li>
|
||
<li>Errors implement Send.</li>
|
||
<li>Errors can carry backtraces.</li>
|
||
</ul>
|
||
|
||
<p>Similar to other libraries like <a href="https://github.com/DanielKeep/rust-error-type">error-type</a> and <a href="https://github.com/tailhook/quick-error">quick-error</a>,
|
||
this library introduces the error chaining mechanism originally
|
||
employed by Cargo. The <code>error_chain!</code> macro declares the types
|
||
and implementation boilerplate necessary for fulfilling a
|
||
particular error-handling strategy. Most importantly it defines a
|
||
custom error type (called <code>Error</code> by convention) and the <code>From</code>
|
||
conversions that let the <code>try!</code> macro and <code>?</code> operator work.</p>
|
||
|
||
<p>This library differs in a few ways from previous error libs:</p>
|
||
|
||
<ul>
|
||
<li>Instead of defining the custom <code>Error</code> type as an enum, it is a
|
||
struct containing an <code>ErrorKind</code> (which defines the
|
||
<code>description</code> and <code>display</code> methods for the error), an opaque,
|
||
optional, boxed <code>std::error::Error + Send + 'static</code> object
|
||
(which defines the <code>cause</code>, and establishes the links in the
|
||
error chain), and a <code>Backtrace</code>.</li>
|
||
<li>The macro also defines a <code>ResultExt</code> trait that defines a
|
||
<code>chain_err</code> method. This method on all <code>std::error::Error + Send + 'static</code>
|
||
types extends the error chain by boxing the current
|
||
error into an opaque object and putting it inside a new concrete
|
||
error.</li>
|
||
<li>It provides automatic <code>From</code> conversions between other error types
|
||
defined by the <code>error_chain!</code> that preserve type information,
|
||
and facilitate seamless error composition and matching of composed
|
||
errors.</li>
|
||
<li>It provides automatic <code>From</code> conversions between any other error
|
||
type that hides the type of the other error in the <code>cause</code> box.</li>
|
||
<li>If <code>RUST_BACKTRACE</code> is enabled, it collects a single backtrace at
|
||
the earliest opportunity and propagates it down the stack through
|
||
<code>From</code> and <code>ResultExt</code> conversions.</li>
|
||
</ul>
|
||
|
||
<p>To accomplish its goals it makes some tradeoffs:</p>
|
||
|
||
<ul>
|
||
<li>The split between the <code>Error</code> and <code>ErrorKind</code> types can make it
|
||
slightly more cumbersome to instantiate new (unchained) errors,
|
||
requiring an <code>Into</code> or <code>From</code> conversion; as well as slightly
|
||
more cumbersome to match on errors with another layer of types
|
||
to match.</li>
|
||
<li>Because the error type contains <code>std::error::Error + Send + 'static</code> objects,
|
||
it can't implement <code>PartialEq</code> for easy comparisons.</li>
|
||
</ul>
|
||
|
||
<h2 id='declaring-error-types' class='section-header'><a href='#declaring-error-types'>Declaring error types</a></h2>
|
||
<p>Generally, you define one family of error types per crate, though
|
||
it's also perfectly fine to define error types on a finer-grained
|
||
basis, such as per module.</p>
|
||
|
||
<p>Assuming you are using crate-level error types, typically you will
|
||
define an <code>errors</code> module and inside it call <code>error_chain!</code>:</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">mod</span> <span class="ident">other_error</span> {
|
||
<span class="macro">error_chain</span><span class="macro">!</span> {}
|
||
}
|
||
|
||
<span class="macro">error_chain</span><span class="macro">!</span> {
|
||
<span class="comment">// The type defined for this error. These are the conventional</span>
|
||
<span class="comment">// and recommended names, but they can be arbitrarily chosen.</span>
|
||
<span class="comment">//</span>
|
||
<span class="comment">// It is also possible to leave this section out entirely, or</span>
|
||
<span class="comment">// leave it empty, and these names will be used automatically.</span>
|
||
<span class="ident">types</span> {
|
||
<span class="ident">Error</span>, <span class="ident">ErrorKind</span>, <span class="ident">ResultExt</span>, <span class="prelude-ty">Result</span>;
|
||
}
|
||
|
||
<span class="comment">// Without the `Result` wrapper:</span>
|
||
<span class="comment">//</span>
|
||
<span class="comment">// types {</span>
|
||
<span class="comment">// Error, ErrorKind, ResultExt;</span>
|
||
<span class="comment">// }</span>
|
||
|
||
<span class="comment">// Automatic conversions between this error chain and other</span>
|
||
<span class="comment">// error chains. In this case, it will e.g. generate an</span>
|
||
<span class="comment">// `ErrorKind` variant called `Another` which in turn contains</span>
|
||
<span class="comment">// the `other_error::ErrorKind`, with conversions from</span>
|
||
<span class="comment">// `other_error::Error`.</span>
|
||
<span class="comment">//</span>
|
||
<span class="comment">// Optionally, some attributes can be added to a variant.</span>
|
||
<span class="comment">//</span>
|
||
<span class="comment">// This section can be empty.</span>
|
||
<span class="ident">links</span> {
|
||
<span class="ident">Another</span>(<span class="ident">other_error</span>::<span class="ident">Error</span>, <span class="ident">other_error</span>::<span class="ident">ErrorKind</span>) <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">unix</span>)]</span>;
|
||
}
|
||
|
||
<span class="comment">// Automatic conversions between this error chain and other</span>
|
||
<span class="comment">// error types not defined by the `error_chain!`. These will be</span>
|
||
<span class="comment">// wrapped in a new error with, in the first case, the</span>
|
||
<span class="comment">// `ErrorKind::Fmt` variant. The description and cause will</span>
|
||
<span class="comment">// forward to the description and cause of the original error.</span>
|
||
<span class="comment">//</span>
|
||
<span class="comment">// Optionally, some attributes can be added to a variant.</span>
|
||
<span class="comment">//</span>
|
||
<span class="comment">// This section can be empty.</span>
|
||
<span class="ident">foreign_links</span> {
|
||
<span class="ident">Fmt</span>(::<span class="ident">std</span>::<span class="ident">fmt</span>::<span class="ident">Error</span>);
|
||
<span class="ident">Io</span>(::<span class="ident">std</span>::<span class="ident">io</span>::<span class="ident">Error</span>) <span class="attribute">#[<span class="ident">cfg</span>(<span class="ident">unix</span>)]</span>;
|
||
}
|
||
|
||
<span class="comment">// Define additional `ErrorKind` variants. The syntax here is</span>
|
||
<span class="comment">// the same as `quick_error!`, but the `from()` and `cause()`</span>
|
||
<span class="comment">// syntax is not supported.</span>
|
||
<span class="ident">errors</span> {
|
||
<span class="ident">InvalidToolchainName</span>(<span class="ident">t</span>: <span class="ident">String</span>) {
|
||
<span class="ident">description</span>(<span class="string">"invalid toolchain name"</span>)
|
||
<span class="ident">display</span>(<span class="string">"invalid toolchain name: '{}'"</span>, <span class="ident">t</span>)
|
||
}
|
||
|
||
<span class="comment">// You can also add commas after description/display.</span>
|
||
<span class="comment">// This may work better with some editor auto-indentation modes:</span>
|
||
<span class="ident">UnknownToolchainVersion</span>(<span class="ident">v</span>: <span class="ident">String</span>) {
|
||
<span class="ident">description</span>(<span class="string">"unknown toolchain version"</span>), <span class="comment">// note the ,</span>
|
||
<span class="ident">display</span>(<span class="string">"unknown toolchain version: '{}'"</span>, <span class="ident">v</span>), <span class="comment">// trailing comma is allowed</span>
|
||
}
|
||
}
|
||
}
|
||
</pre>
|
||
|
||
<p>Each section, <code>types</code>, <code>links</code>, <code>foreign_links</code>, and <code>errors</code> may
|
||
be omitted if it is empty.</p>
|
||
|
||
<p>This populates the module with a number of definitions,
|
||
the most important of which are the <code>Error</code> type
|
||
and the <code>ErrorKind</code> type. An example of generated code can be found in the
|
||
<a href="example_generated">example_generated</a> module.</p>
|
||
|
||
<h2 id='returning-new-errors' class='section-header'><a href='#returning-new-errors'>Returning new errors</a></h2>
|
||
<p>Introducing new error chains, with a string message:</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">fn</span> <span class="ident">foo</span>() <span class="op">-></span> <span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
|
||
<span class="prelude-val">Err</span>(<span class="string">"foo error!"</span>.<span class="ident">into</span>())
|
||
}</pre>
|
||
|
||
<p>Introducing new error chains, with an <code>ErrorKind</code>:</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="macro">error_chain</span><span class="macro">!</span> {
|
||
<span class="ident">errors</span> { <span class="ident">FooError</span> }
|
||
}
|
||
|
||
<span class="kw">fn</span> <span class="ident">foo</span>() <span class="op">-></span> <span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
|
||
<span class="prelude-val">Err</span>(<span class="ident">ErrorKind</span>::<span class="ident">FooError</span>.<span class="ident">into</span>())
|
||
}</pre>
|
||
|
||
<p>Note that the return type is the typedef <code>Result</code>, which is
|
||
defined by the macro as <code>pub type Result<T> = ::std::result::Result<T, Error></code>. Note that in both cases
|
||
<code>.into()</code> is called to convert a type into the <code>Error</code> type; both
|
||
strings and <code>ErrorKind</code> have <code>From</code> conversions to turn them into
|
||
<code>Error</code>.</p>
|
||
|
||
<p>When the error is emitted inside a <code>try!</code> macro or behind the
|
||
<code>?</code> operator, the explicit conversion isn't needed; <code>try!</code> will
|
||
automatically convert <code>Err(ErrorKind)</code> to <code>Err(Error)</code>. So the
|
||
below is equivalent to the previous:</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">fn</span> <span class="ident">foo</span>() <span class="op">-></span> <span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
|
||
<span class="prelude-val">Ok</span>(<span class="macro">try</span><span class="macro">!</span>(<span class="prelude-val">Err</span>(<span class="ident">ErrorKind</span>::<span class="ident">FooError</span>)))
|
||
}
|
||
|
||
<span class="kw">fn</span> <span class="ident">bar</span>() <span class="op">-></span> <span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
|
||
<span class="prelude-val">Ok</span>(<span class="macro">try</span><span class="macro">!</span>(<span class="prelude-val">Err</span>(<span class="string">"bogus!"</span>)))
|
||
}</pre>
|
||
|
||
<h2 id='the-bail-macro' class='section-header'><a href='#the-bail-macro'>The <code>bail!</code> macro</a></h2>
|
||
<p>The above method of introducing new errors works but is a little
|
||
verbose. Instead, we can use the <code>bail!</code> macro, which performs an early return
|
||
with conversions done automatically.</p>
|
||
|
||
<p>With <code>bail!</code> the previous examples look like:</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">fn</span> <span class="ident">foo</span>() <span class="op">-></span> <span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
|
||
<span class="kw">if</span> <span class="bool-val">true</span> {
|
||
<span class="macro">bail</span><span class="macro">!</span>(<span class="ident">ErrorKind</span>::<span class="ident">FooError</span>);
|
||
} <span class="kw">else</span> {
|
||
<span class="prelude-val">Ok</span>(())
|
||
}
|
||
}
|
||
|
||
<span class="kw">fn</span> <span class="ident">bar</span>() <span class="op">-></span> <span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> {
|
||
<span class="kw">if</span> <span class="bool-val">true</span> {
|
||
<span class="macro">bail</span><span class="macro">!</span>(<span class="string">"bogus!"</span>);
|
||
} <span class="kw">else</span> {
|
||
<span class="prelude-val">Ok</span>(())
|
||
}
|
||
}</pre>
|
||
|
||
<h2 id='chaining-errors' class='section-header'><a href='#chaining-errors'>Chaining errors</a></h2>
|
||
<p>error-chain supports extending an error chain by appending new errors.
|
||
This can be done on a Result or on an existing Error.</p>
|
||
|
||
<p>To extend the error chain:</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">let</span> <span class="ident">res</span>: <span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> <span class="op">=</span> <span class="ident">do_something</span>().<span class="ident">chain_err</span>(<span class="op">||</span> <span class="string">"something went wrong"</span>);</pre>
|
||
|
||
<p><code>chain_err</code> can be called on any <code>Result</code> type where the contained
|
||
error type implements <code>std::error::Error + Send + 'static</code>, as long as
|
||
the <code>Result</code> type's corresponding <code>ResultExt</code> trait is in scope. If
|
||
the <code>Result</code> is an <code>Err</code> then <code>chain_err</code> evaluates the closure,
|
||
which returns <em>some type that can be converted to <code>ErrorKind</code></em>,
|
||
boxes the original error to store as the cause, then returns a new
|
||
error containing the original error.</p>
|
||
|
||
<p>Calling <code>chain_err</code> on an existing <code>Error</code> instance has the same
|
||
signature and produces the same outcome as being called on a <code>Result</code>
|
||
matching the properties described above. This is most useful when
|
||
partially handling errors using the <code>map_err</code> function.</p>
|
||
|
||
<p>To chain an error directly, use <code>with_chain</code>:</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">let</span> <span class="ident">res</span>: <span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> <span class="op">=</span>
|
||
<span class="ident">do_something</span>().<span class="ident">map_err</span>(<span class="op">|</span><span class="ident">e</span><span class="op">|</span> <span class="ident">Error</span>::<span class="ident">with_chain</span>(<span class="ident">e</span>, <span class="string">"something went wrong"</span>));</pre>
|
||
|
||
<h2 id='linking-errors' class='section-header'><a href='#linking-errors'>Linking errors</a></h2>
|
||
<p>To convert an error from another error chain to this error chain:</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="macro">error_chain</span><span class="macro">!</span> {
|
||
<span class="ident">links</span> {
|
||
<span class="ident">OtherError</span>(<span class="ident">other</span>::<span class="ident">Error</span>, <span class="ident">other</span>::<span class="ident">ErrorKind</span>);
|
||
}
|
||
}
|
||
|
||
<span class="kw">fn</span> <span class="ident">do_other_thing</span>() <span class="op">-></span> <span class="ident">other</span>::<span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> { <span class="macro">unimplemented</span><span class="macro">!</span>() }
|
||
|
||
<span class="kw">let</span> <span class="ident">res</span>: <span class="prelude-ty">Result</span><span class="op"><</span>()<span class="op">></span> <span class="op">=</span> <span class="ident">do_other_thing</span>().<span class="ident">map_err</span>(<span class="op">|</span><span class="ident">e</span><span class="op">|</span> <span class="ident">e</span>.<span class="ident">into</span>());</pre>
|
||
|
||
<p>The <code>Error</code> and <code>ErrorKind</code> types implements <code>From</code> for the corresponding
|
||
types of all linked error chains. Linked errors do not introduce a new
|
||
cause to the error chain.</p>
|
||
|
||
<h2 id='matching-errors' class='section-header'><a href='#matching-errors'>Matching errors</a></h2>
|
||
<p>error-chain error variants are matched with simple patterns.
|
||
<code>Error</code> is a tuple struct and its first field is the <code>ErrorKind</code>,
|
||
making dispatching on error kinds relatively compact:</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="macro">error_chain</span><span class="macro">!</span> {
|
||
<span class="ident">errors</span> {
|
||
<span class="ident">InvalidToolchainName</span>(<span class="ident">t</span>: <span class="ident">String</span>) {
|
||
<span class="ident">description</span>(<span class="string">"invalid toolchain name"</span>)
|
||
<span class="ident">display</span>(<span class="string">"invalid toolchain name: '{}'"</span>, <span class="ident">t</span>)
|
||
}
|
||
}
|
||
}
|
||
|
||
<span class="kw">match</span> <span class="ident">Error</span>::<span class="ident">from</span>(<span class="string">"error!"</span>) {
|
||
<span class="ident">Error</span>(<span class="ident">ErrorKind</span>::<span class="ident">InvalidToolchainName</span>(_), _) <span class="op">=></span> { }
|
||
<span class="ident">Error</span>(<span class="ident">ErrorKind</span>::<span class="ident">Msg</span>(_), _) <span class="op">=></span> { }
|
||
}</pre>
|
||
|
||
<p>Chained errors are also matched with (relatively) compact syntax</p>
|
||
|
||
<pre class="rust rust-example-rendered">
|
||
<span class="kw">mod</span> <span class="ident">utils</span> {
|
||
<span class="macro">error_chain</span><span class="macro">!</span> {
|
||
<span class="ident">errors</span> {
|
||
<span class="ident">BadStuff</span> {
|
||
<span class="ident">description</span>(<span class="string">"bad stuff"</span>)
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
<span class="kw">mod</span> <span class="ident">app</span> {
|
||
<span class="macro">error_chain</span><span class="macro">!</span> {
|
||
<span class="ident">links</span> {
|
||
<span class="ident">Utils</span>(::<span class="ident">utils</span>::<span class="ident">Error</span>, ::<span class="ident">utils</span>::<span class="ident">ErrorKind</span>);
|
||
}
|
||
}
|
||
}
|
||
|
||
|
||
<span class="kw">match</span> <span class="ident">app</span>::<span class="ident">Error</span>::<span class="ident">from</span>(<span class="string">"error!"</span>) {
|
||
<span class="ident">app</span>::<span class="ident">Error</span>(<span class="ident">app</span>::<span class="ident">ErrorKind</span>::<span class="ident">Utils</span>(<span class="ident">utils</span>::<span class="ident">ErrorKind</span>::<span class="ident">BadStuff</span>), _) <span class="op">=></span> { }
|
||
_ <span class="op">=></span> { }
|
||
}</pre>
|
||
|
||
<h2 id='foreign-links' class='section-header'><a href='#foreign-links'>Foreign links</a></h2>
|
||
<p>Errors that do not conform to the same conventions as this library
|
||
can still be included in the error chain. They are considered "foreign
|
||
errors", and are declared using the <code>foreign_links</code> block of the
|
||
<code>error_chain!</code> macro. <code>Error</code>s are automatically created from
|
||
foreign errors by the <code>try!</code> macro.</p>
|
||
|
||
<p>Foreign links and regular links have one crucial difference:
|
||
<code>From</code> conversions for regular links <em>do not introduce a new error
|
||
into the error chain</em>, while conversions for foreign links <em>always
|
||
introduce a new error into the error chain</em>. So for the example
|
||
above all errors deriving from the <code>std::fmt::Error</code> type will be
|
||
presented to the user as a new <code>ErrorKind::Fmt</code> variant, and the
|
||
cause will be the original <code>std::fmt::Error</code> error. In contrast, when
|
||
<code>other_error::Error</code> is converted to <code>Error</code> the two <code>ErrorKind</code>s
|
||
are converted between each other to create a new <code>Error</code> but the
|
||
old error is discarded; there is no "cause" created from the
|
||
original error.</p>
|
||
|
||
<h2 id='backtraces' class='section-header'><a href='#backtraces'>Backtraces</a></h2>
|
||
<p>If the <code>RUST_BACKTRACE</code> environment variable is set to anything
|
||
but <code>0</code>, the earliest non-foreign error to be generated creates
|
||
a single backtrace, which is passed through all <code>From</code> conversions
|
||
and <code>chain_err</code> invocations of compatible types. To read the
|
||
backtrace just call the <code>backtrace()</code> method.</p>
|
||
|
||
<p>Backtrace generation can be disabled by turning off the <code>backtrace</code> feature.</p>
|
||
|
||
<h2 id='iteration' class='section-header'><a href='#iteration'>Iteration</a></h2>
|
||
<p>The <code>iter</code> method returns an iterator over the chain of error boxes.</p>
|
||
</div><h2 id='modules' class='section-header'><a href="#modules">Modules</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="mod" href="example_generated/index.html"
|
||
title='mod error_chain::example_generated'>example_generated</a></td>
|
||
<td class='docblock-short'>
|
||
<p>These modules show an example of code generated by the macro. <strong>IT MUST NOT BE
|
||
USED OUTSIDE THIS CRATE</strong>.</p>
|
||
</td>
|
||
</tr></table><h2 id='macros' class='section-header'><a href="#macros">Macros</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="macro" href="macro.bail.html"
|
||
title='macro error_chain::bail'>bail</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Exits a function early with an error</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="macro" href="macro.ensure.html"
|
||
title='macro error_chain::ensure'>ensure</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Exits a function early with an error if the condition is not satisfied</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="macro" href="macro.error_chain.html"
|
||
title='macro error_chain::error_chain'>error_chain</a></td>
|
||
<td class='docblock-short'>
|
||
<p>This macro is used for handling of duplicated and out-of-order fields. For
|
||
the exact rules, see <code>error_chain_processed</code>.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="macro" href="macro.error_chain_processed.html"
|
||
title='macro error_chain::error_chain_processed'>error_chain_processed</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Prefer to use <code>error_chain</code> instead of this macro.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="macro" href="macro.quick_error.html"
|
||
title='macro error_chain::quick_error'>quick_error</a></td>
|
||
<td class='docblock-short'>
|
||
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="macro" href="macro.quick_main.html"
|
||
title='macro error_chain::quick_main'>quick_main</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Convenient wrapper to be able to use <code>try!</code> and such in the main. You can
|
||
use it with a separated function:</p>
|
||
</td>
|
||
</tr></table><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="struct" href="struct.Backtrace.html"
|
||
title='struct error_chain::Backtrace'>Backtrace</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Representation of an owned and self-contained backtrace.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="struct" href="struct.Display.html"
|
||
title='struct error_chain::Display'>Display</a></td>
|
||
<td class='docblock-short'>
|
||
<p>A struct which formats an error for output.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="struct" href="struct.ErrorChainIter.html"
|
||
title='struct error_chain::ErrorChainIter'>ErrorChainIter</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Iterator over the error chain using the <code>Error::cause()</code> method.</p>
|
||
</td>
|
||
</tr></table><h2 id='traits' class='section-header'><a href="#traits">Traits</a></h2>
|
||
<table>
|
||
<tr class=' module-item'>
|
||
<td><a class="trait" href="trait.ChainedError.html"
|
||
title='trait error_chain::ChainedError'>ChainedError</a></td>
|
||
<td class='docblock-short'>
|
||
<p>This trait is implemented on all the errors generated by the <code>error_chain</code>
|
||
macro.</p>
|
||
</td>
|
||
</tr>
|
||
<tr class=' module-item'>
|
||
<td><a class="trait" href="trait.ExitCode.html"
|
||
title='trait error_chain::ExitCode'>ExitCode</a></td>
|
||
<td class='docblock-short'>
|
||
<p>Represents a value that can be used as the exit status of the process.
|
||
See <a href="macro.quick_main.html"><code>quick_main!</code></a>.</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>⇤</dt>
|
||
<dd>Move up in search results</dd>
|
||
<dt>⇥</dt>
|
||
<dd>Move down in search results</dd>
|
||
<dt>⏎</dt>
|
||
<dd>Go to active search result</dd>
|
||
<dt>+</dt>
|
||
<dd>Collapse/expand all sections</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 = "error_chain";
|
||
</script>
|
||
<script src="../main.js"></script>
|
||
<script defer src="../search-index.js"></script>
|
||
</body>
|
||
</html> |