<!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 `quick_error` crate.">
<meta name="keywords" content="rust, rustlang, rust-lang, quick_error">
<title>quick_error - Rust</title>
<link rel="stylesheet" type="text/css" href="../rustdoc.css">
<link rel="stylesheet" type="text/css" href="../main.css">
</head>
<body class="rustdoc">
<nav class="sidebar">
<p class='location'></p><script>window.sidebarCurrent = {name: 'quick_error', 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 mod">
<h1 class='fqn'><span class='in-band'>Crate <a class='mod' href=''>quick_error</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 id='src-0' class='srclink' href='../src/quick_error/lib.rs.html#1-668' title='goto source code'>[src]</a></span></h1>
<div class='docblock'><p>A macro which makes errors easy to write</p>
<p>Minimum type is like this:</p>
<pre class='rust rust-example-rendered'>
<span class='attribute'>#[<span class='ident'>macro_use</span>]</span> <span class='kw'>extern</span> <span class='kw'>crate</span> <span class='ident'>quick_error</span>;
<span class='macro'>quick_error</span><span class='macro'>!</span> {
<span class='attribute'>#[<span class='ident'>derive</span>(<span class='ident'>Debug</span>)]</span>
<span class='kw'>pub</span> <span class='kw'>enum</span> <span class='ident'>SomeError</span> {
<span class='ident'>Variant1</span> {}
}
}</pre>
<p>Both <code>pub</code> and non-public types may be declared, and all meta attributes
(such as <code>#[derive(Debug)]</code>) are forwarded as is. The <code>Debug</code> must be
implemented (but you may do that yourself if you like). The documentation
comments <code>/// something</code> (as well as other meta attrbiutes) on variants
are allowed.</p>
<p>You may add arbitrary parameters to any struct variant:</p>
<pre class='rust rust-example-rendered'>
<span class='macro'>quick_error</span><span class='macro'>!</span> {
<span class='attribute'>#[<span class='ident'>derive</span>(<span class='ident'>Debug</span>)]</span>
<span class='kw'>pub</span> <span class='kw'>enum</span> <span class='ident'>SomeError</span> {
<span class='doccomment'>/// IO Error</span>
<span class='ident'>Io</span>(<span class='ident'>err</span>: <span class='ident'>io</span>::<span class='ident'>Error</span>) {}
<span class='doccomment'>/// Arbitrary system error</span>
<span class='ident'>Sys</span>(<span class='ident'>errno</span>: <span class='ident'>nix</span>::<span class='ident'>Errno</span>) {}
}
}</pre>
<p>Note unlike in normal Enum decarations you declare names of fields (which
are omitted from type). How they can be used is outlined below.</p>
<p>Now you might have noticed trailing braces <code>{}</code>. They are used to define
implementations. By default:</p>
<ul>
<li><code>Error::description()</code> returns variant name as static string</li>
<li><code>Error::cause()</code> returns None (even if type wraps some value)</li>
<li><code>Display</code> outputs <code>description()</code></li>
<li>No <code>From</code> implementations are defined</li>
</ul>
<p>To define description simply add <code>description(value)</code> inside braces:</p>
<pre class='rust rust-example-rendered'>
<span class='macro'>quick_error</span><span class='macro'>!</span> {
<span class='attribute'>#[<span class='ident'>derive</span>(<span class='ident'>Debug</span>)]</span>
<span class='kw'>pub</span> <span class='kw'>enum</span> <span class='ident'>SomeError</span> {
<span class='ident'>Io</span>(<span class='ident'>err</span>: <span class='ident'>io</span>::<span class='ident'>Error</span>) {
<span class='ident'>description</span>(<span class='ident'>err</span>.<span class='ident'>description</span>())
}
<span class='ident'>Sys</span>(<span class='ident'>errno</span>: <span class='ident'>nix</span>::<span class='ident'>Errno</span>) {
<span class='ident'>description</span>(<span class='string'>"system error"</span>)
}
}
}</pre>
<p>Normal rules for borrowing apply. So most of the time description either
returns constant string or forwards description from enclosed type.</p>
<p>To change <code>cause</code> method to return some error, add <code>cause(value)</code>, for
example:</p>
<pre class='rust rust-example-rendered'>
<span class='macro'>quick_error</span><span class='macro'>!</span> {
<span class='attribute'>#[<span class='ident'>derive</span>(<span class='ident'>Debug</span>)]</span>
<span class='kw'>pub</span> <span class='kw'>enum</span> <span class='ident'>SomeError</span> {
<span class='ident'>Io</span>(<span class='ident'>err</span>: <span class='ident'>io</span>::<span class='ident'>Error</span>) {
<span class='ident'>cause</span>(<span class='ident'>err</span>)
<span class='ident'>description</span>(<span class='ident'>err</span>.<span class='ident'>description</span>())
}
<span class='ident'>Sys</span>(<span class='ident'>errno</span>: <span class='ident'>nix</span>::<span class='ident'>Errno</span>) {
<span class='ident'>description</span>(<span class='string'>"system error"</span>)
}
}
}</pre>
<p>Note you don't need to wrap value in <code>Some</code>, its implicit. In case you want
<code>None</code> returned just omit the <code>cause</code>. You can't return <code>None</code>
conditionally.</p>
<p>To change how each clause is <code>Display</code>ed add <code>display(pattern,..args)</code>,
for example:</p>
<pre class='rust rust-example-rendered'>
<span class='macro'>quick_error</span><span class='macro'>!</span> {
<span class='attribute'>#[<span class='ident'>derive</span>(<span class='ident'>Debug</span>)]</span>
<span class='kw'>pub</span> <span class='kw'>enum</span> <span class='ident'>SomeError</span> {
<span class='ident'>Io</span>(<span class='ident'>err</span>: <span class='ident'>io</span>::<span class='ident'>Error</span>) {
<span class='ident'>display</span>(<span class='string'>"I/O error: {}"</span>, <span class='ident'>err</span>)
}
<span class='ident'>Sys</span>(<span class='ident'>errno</span>: <span class='ident'>nix</span>::<span class='ident'>Errno</span>) {
<span class='ident'>display</span>(<span class='string'>"System error, errno ({:x})"</span>, <span class='ident'>errno</span>)
}
}
}</pre>
<p>To convert to the type from any other, use one of the three forms of
<code>from</code> clause.</p>
<p>For example, to convert simple wrapper use bare <code>from()</code>:</p>
<pre class='rust rust-example-rendered'>
<span class='macro'>quick_error</span><span class='macro'>!</span> {
<span class='attribute'>#[<span class='ident'>derive</span>(<span class='ident'>Debug</span>)]</span>
<span class='kw'>pub</span> <span class='kw'>enum</span> <span class='ident'>SomeError</span> {
<span class='ident'>Io</span>(<span class='ident'>err</span>: <span class='ident'>io</span>::<span class='ident'>Error</span>) {
<span class='ident'>from</span>()
}
}</pre>
<p>This implements <code>From<io::Error></code>.</p>
<p>To convert to singleton enumeration type (discarding the value), use
the <code>from(type)</code> form:</p>
<pre class='rust rust-example-rendered'>
<span class='macro'>quick_error</span><span class='macro'>!</span> {
<span class='attribute'>#[<span class='ident'>derive</span>(<span class='ident'>Debug</span>)]</span>
<span class='kw'>pub</span> <span class='kw'>enum</span> <span class='ident'>SomeError</span> {
<span class='ident'>FormatError</span> {
<span class='ident'>from</span>(<span class='ident'>std</span>::<span class='ident'>fmt</span>::<span class='ident'>Error</span>)
}
}</pre>
<p>And the most powerful form is <code>from(var: type) -> (arguments...)</code>. It
might be used to convert to type with multiple arguments or for arbitrary
value conversions:</p>
<pre class='rust rust-example-rendered'>
<span class='macro'>quick_error</span><span class='macro'>!</span> {
<span class='attribute'>#[<span class='ident'>derive</span>(<span class='ident'>Debug</span>)]</span>
<span class='kw'>pub</span> <span class='kw'>enum</span> <span class='ident'>SomeError</span> {
<span class='ident'>FailedOperation</span>(<span class='ident'>s</span>: <span class='kw-2'>&</span><span class='lifetime'>'static</span> <span class='ident'>str</span>, <span class='ident'>errno</span>: <span class='ident'>i32</span>) {
<span class='ident'>from</span>(<span class='ident'>errno</span>: <span class='ident'>i32</span>) <span class='op'>-></span> (<span class='string'>"os error"</span>, <span class='ident'>i32</span>)
<span class='ident'>from</span>(<span class='ident'>e</span>: <span class='ident'>io</span>::<span class='ident'>Error</span>) <span class='op'>-></span> (<span class='string'>"io error"</span>, <span class='ident'>e</span>.<span class='ident'>raw_os_error</span>().<span class='ident'>unwrap</span>())
}
<span class='doccomment'>/// Converts from both kinds of utf8 errors</span>
<span class='ident'>Utf8</span>(<span class='ident'>err</span>: <span class='ident'>std</span>::<span class='ident'>str</span>::<span class='ident'>Utf8Error</span>) {
<span class='ident'>from</span>()
<span class='ident'>from</span>(<span class='ident'>err</span>: <span class='ident'>std</span>::<span class='ident'>string</span>::<span class='ident'>FromUtf8Error</span>) <span class='op'>-></span> (<span class='ident'>err</span>.<span class='ident'>utf8_error</span>())
}
}</pre>
<p>All forms of <code>from</code>, <code>display</code>, <code>description</code>, <code>cause</code> clauses can be
combined and put in arbitrary order. Only <code>from</code> may be used multiple times
in single variant of enumeration. Docstrings are also okay.
Empty braces can be omitted as of quick_error 0.1.3.</p>
</div><h2 id='macros' class='section-header'><a href="#macros">Macros</a></h2>
<table>
<tr class=' module-item'>
<td><a class='macro' href='macro.quick_error!.html'
title='quick_error::quick_error!'>quick_error!</a></td>
<td class='docblock short'>
<p>Main macro that does all the work</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>
</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>)
</p>
</div>
</div>
</aside>
<script>
window.rootPath = "../";
window.currentCrate = "quick_error";
window.playgroundUrl = "";
</script>
<script src="../jquery.js"></script>
<script src="../main.js"></script>
<script defer src="../search-index.js"></script>
</body>
</html>