edlang/anstream/macro.panic.html
2024-05-05 09:43:20 +00:00

53 lines
8.8 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="Panics the current thread."><title>panic in anstream - Rust</title><script> if (window.location.protocol !== "file:") document.write(`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2">`)</script><link rel="stylesheet" href="../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../static.files/rustdoc-e935ef01ae1c1829.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="anstream" data-themes="" data-resource-suffix="" data-rustdoc-version="1.78.0 (9b00956e5 2024-04-29)" data-channel="1.78.0" data-search-js="search-42d8da7a6b9792c2.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../static.files/storage-4c98445ec4002617.js"></script><script defer src="sidebar-items.js"></script><script defer src="../static.files/main-12cf3b4f4f9dc36d.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-04d5337699b92874.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-16x16-8b506e7a72182f1c.png"><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc macro"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../anstream/index.html">anstream</a><span class="version">0.6.14</span></h2></div><div class="sidebar-elems"></div></nav><div class="sidebar-resizer"></div>
<main><div class="width-limiter"><nav class="sub"><form class="search-form"><span></span><div id="sidebar-button" tabindex="-1"><a href="../anstream/all.html" title="show sidebar"></a></div><input class="search-input" name="search" aria-label="Run search in the documentation" autocomplete="off" spellcheck="false" placeholder="Click or press S to search, ? for more options…" type="search"><div id="help-button" tabindex="-1"><a href="../help.html" title="help">?</a></div><div id="settings-menu" tabindex="-1"><a href="../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1>Macro <a href="index.html">anstream</a>::<wbr><a class="macro" href="#">panic</a><button id="copy-path" title="Copy item path to clipboard"><img src="../static.files/clipboard-7571035ce49a181d.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="src" href="../src/anstream/macros.rs.html#371-389">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><pre class="rust item-decl"><span class="macro">macro_rules!</span> panic {
() =&gt; { ... };
($(<span class="macro-nonterminal">$arg</span>:tt)<span class="kw-2">*</span>) =&gt; { ... };
}</pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Panics the current thread.</p>
<p>This allows a program to terminate immediately and provide feedback
to the caller of the program.</p>
<p>This macro is the perfect way to assert conditions in example code and in
tests. <code>panic!</code> is closely tied with the <code>unwrap</code> method of both
<a href="https://doc.rust-lang.org/1.78.0/core/option/enum.Option.html#method.unwrap" title="method core::option::Option::unwrap"><code>Option</code></a> and <a href="https://doc.rust-lang.org/1.78.0/core/result/enum.Result.html#method.unwrap" title="method core::result::Result::unwrap"><code>Result</code></a> enums. Both implementations call
<code>panic!</code> when they are set to <a href="https://doc.rust-lang.org/1.78.0/core/option/enum.Option.html#variant.None" title="variant core::option::Option::None"><code>None</code></a> or <a href="https://doc.rust-lang.org/1.78.0/core/result/enum.Result.html#variant.Err" title="variant core::result::Result::Err"><code>Err</code></a> variants.</p>
<p>When using <code>panic!()</code> you can specify a string payload, that is built using
the <a href="../std/macro.format.html"><code>format!</code></a> syntax. That payload is used when injecting the panic into
the calling Rust thread, causing the thread to panic entirely.</p>
<p>The behavior of the default <code>std</code> hook, i.e. the code that runs directly
after the panic is invoked, is to print the message payload to
<code>stderr</code> along with the file/line/column information of the <code>panic!()</code>
call. You can override the panic hook using <a href="../std/panic/fn.set_hook.html"><code>std::panic::set_hook()</code></a>.
Inside the hook a panic can be accessed as a <code>&amp;dyn Any + Send</code>,
which contains either a <code>&amp;str</code> or <code>String</code> for regular <code>panic!()</code> invocations.
To panic with a value of another other type, <a href="../std/panic/fn.panic_any.html"><code>panic_any</code></a> can be used.</p>
<p>See also the macro <a href="https://doc.rust-lang.org/1.78.0/core/macro.compile_error.html" title="macro core::compile_error"><code>compile_error!</code></a>, for raising errors during compilation.</p>
<h2 id="when-to-use-panic-vs-result"><a class="doc-anchor" href="#when-to-use-panic-vs-result">§</a>When to use <code>panic!</code> vs <code>Result</code></h2>
<p>The Rust language provides two complementary systems for constructing /
representing, reporting, propagating, reacting to, and discarding errors. These
responsibilities are collectively known as “error handling.” <code>panic!</code> and
<code>Result</code> are similar in that they are each the primary interface of their
respective error handling systems; however, the meaning these interfaces attach
to their errors and the responsibilities they fulfill within their respective
error handling systems differ.</p>
<p>The <code>panic!</code> macro is used to construct errors that represent a bug that has
been detected in your program. With <code>panic!</code> you provide a message that
describes the bug and the language then constructs an error with that message,
reports it, and propagates it for you.</p>
<p><code>Result</code> on the other hand is used to wrap other types that represent either
the successful result of some computation, <code>Ok(T)</code>, or error types that
represent an anticipated runtime failure mode of that computation, <code>Err(E)</code>.
<code>Result</code> is used alongside user defined types which represent the various
anticipated runtime failure modes that the associated computation could
encounter. <code>Result</code> must be propagated manually, often with the the help of the
<code>?</code> operator and <code>Try</code> trait, and they must be reported manually, often with
the help of the <code>Error</code> trait.</p>
<p>For more detailed information about error handling check out the <a href="../book/ch09-00-error-handling.html">book</a> or the
<a href="../std/result/index.html"><code>std::result</code></a> module docs.</p>
<h2 id="current-implementation"><a class="doc-anchor" href="#current-implementation">§</a>Current implementation</h2>
<p>If the main thread panics it will terminate all your threads and end your
program with code <code>101</code>.</p>
<h2 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h2>
<div class="example-wrap should_panic"><a href="#" class="tooltip" title="This example panics"></a><pre class="rust rust-example-rendered"><code><span class="kw">use </span>anstream::panic;
<span class="macro">panic!</span>();
<span class="macro">panic!</span>(<span class="string">"this is a terrible mistake!"</span>);
<span class="macro">panic!</span>(<span class="string">"this is a {} {message}"</span>, <span class="string">"fancy"</span>, message = <span class="string">"message"</span>);</code></pre></div>
</div></details></section></div></main></body></html>