76 lines
16 KiB
HTML
76 lines
16 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="Numeric casts"><title>az - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../static.files/rustdoc-42caa33d.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="az" data-themes="" data-resource-suffix="" data-rustdoc-version="1.84.0 (9fc6b4312 2025-01-07)" data-channel="1.84.0" data-search-js="search-92e6798f.js" data-settings-js="settings-0f613d39.js" ><script src="../static.files/storage-59e33391.js"></script><script defer src="../crates.js"></script><script defer src="../static.files/main-5f194d8c.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-893ab5e7.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-6580c154.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-044be391.svg"></head><body class="rustdoc mod crate"><!--[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="../az/index.html">az</a><span class="version">1.2.1</span></h2></div><div class="sidebar-elems"><ul class="block"><li><a id="all-types" href="all.html">All Items</a></li></ul><section id="rustdoc-toc"><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#numeric-casts" title="Numeric casts">Numeric casts</a><ul><li><a href="#quick-examples" title="Quick examples">Quick examples</a></li><li><a href="#implementing-casts-for-other-types" title="Implementing casts for other types">Implementing casts for other types</a></li><li><a href="#using-the-az-crate" title="Using the az crate">Using the az crate</a></li><li><a href="#license" title="License">License</a></li></ul></li></ul><h3><a href="#structs">Crate Items</a></h3><ul class="block"><li><a href="#structs" title="Structs">Structs</a></li><li><a href="#traits" title="Traits">Traits</a></li><li><a href="#functions" title="Functions">Functions</a></li></ul></section><div id="rustdoc-modnav"></div></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><h1>Crate <span>az</span><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../src/az/lib.rs.html#16-1135">Source</a> </span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><h2 id="numeric-casts"><a class="doc-anchor" href="#numeric-casts">§</a>Numeric casts</h2>
|
|
<p>This crate provides casts and checked casts.</p>
|
|
<h3 id="quick-examples"><a class="doc-anchor" href="#quick-examples">§</a>Quick examples</h3>
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>az::{Az, OverflowingAs, WrappingAs};
|
|
<span class="kw">use </span>core::num::Wrapping;
|
|
|
|
<span class="comment">// Panics on overflow with `debug_assertions`, otherwise wraps
|
|
</span><span class="macro">assert_eq!</span>(<span class="number">12i32</span>.az::<u32>(), <span class="number">12u32</span>);
|
|
|
|
<span class="comment">// Always wraps
|
|
</span><span class="kw">let </span>wrapped = <span class="number">1u32</span>.wrapping_neg();
|
|
<span class="macro">assert_eq!</span>((-<span class="number">1</span>).wrapping_as::<u32>(), wrapped);
|
|
<span class="macro">assert_eq!</span>((-<span class="number">1</span>).overflowing_as::<u32>(), (wrapped, <span class="bool-val">true</span>));
|
|
|
|
<span class="comment">// Wrapping can also be obtained using `Wrapping`
|
|
</span><span class="macro">assert_eq!</span>((-<span class="number">1</span>).az::<Wrapping<u32>>().<span class="number">0</span>, wrapped);</code></pre></div>
|
|
<p>Conversions from floating-point to integers are also supported.
|
|
Numbers are rounded towards zero, but the <a href="struct.Round.html" title="struct az::Round"><code>Round</code></a> wrapper can be
|
|
used to convert floating-point numbers to integers with rounding to
|
|
the nearest, with ties rounded to even.</p>
|
|
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>az::{Az, CheckedAs, Round, SaturatingAs};
|
|
<span class="kw">use </span>core::f32;
|
|
|
|
<span class="macro">assert_eq!</span>(<span class="number">15.7</span>.az::<i32>(), <span class="number">15</span>);
|
|
<span class="macro">assert_eq!</span>(Round(<span class="number">15.5</span>).az::<i32>(), <span class="number">16</span>);
|
|
<span class="macro">assert_eq!</span>(<span class="number">1.5e20</span>.saturating_as::<i32>(), i32::max_value());
|
|
<span class="macro">assert_eq!</span>(f32::NAN.checked_as::<i32>(), <span class="prelude-val">None</span>);</code></pre></div>
|
|
<h3 id="implementing-casts-for-other-types"><a class="doc-anchor" href="#implementing-casts-for-other-types">§</a>Implementing casts for other types</h3>
|
|
<p>To provide casts for another type, you should implement the <a href="trait.Cast.html" title="trait az::Cast"><code>Cast</code></a>
|
|
trait and if necessary the <a href="trait.CheckedCast.html" title="trait az::CheckedCast"><code>CheckedCast</code></a>, <a href="trait.SaturatingCast.html" title="trait az::SaturatingCast"><code>SaturatingCast</code></a>,
|
|
<a href="trait.WrappingCast.html" title="trait az::WrappingCast"><code>WrappingCast</code></a>, <a href="trait.OverflowingCast.html" title="trait az::OverflowingCast"><code>OverflowingCast</code></a> and <a href="trait.UnwrappedCast.html" title="trait az::UnwrappedCast"><code>UnwrappedCast</code></a> traits.
|
|
The <a href="trait.Az.html" title="trait az::Az"><code>Az</code></a>, <a href="trait.CheckedAs.html" title="trait az::CheckedAs"><code>CheckedAs</code></a>, <a href="trait.SaturatingAs.html" title="trait az::SaturatingAs"><code>SaturatingAs</code></a>, <a href="trait.WrappingAs.html" title="trait az::WrappingAs"><code>WrappingAs</code></a>,
|
|
<a href="trait.OverflowingAs.html" title="trait az::OverflowingAs"><code>OverflowingAs</code></a> and <a href="trait.UnwrappedAs.html" title="trait az::UnwrappedAs"><code>UnwrappedAs</code></a> traits are already implemented
|
|
for all types using blanket implementations that make use of the
|
|
former traits.</p>
|
|
<p>The cast traits can also be implemented for references. This can be
|
|
useful for expensive types that are not <a href="https://doc.rust-lang.org/1.84.0/core/marker/trait.Copy.html" title="trait core::marker::Copy"><code>Copy</code></a>. For example if you
|
|
have your own integer type that does not implement <a href="https://doc.rust-lang.org/1.84.0/core/marker/trait.Copy.html" title="trait core::marker::Copy"><code>Copy</code></a>, you could
|
|
implement casts like in the following example. (The type <code>I</code> could be
|
|
an expensive type, for example a bignum integer, but for the example
|
|
it is only a wrapped <a href="https://doc.rust-lang.org/1.84.0/core/primitive.i32.html" title="primitive i32"><code>i32</code></a>.)</p>
|
|
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>az::{Az, Cast};
|
|
<span class="kw">use </span>core::borrow::Borrow;
|
|
|
|
<span class="kw">struct </span>I(i32);
|
|
<span class="kw">impl </span>Cast<i64> <span class="kw">for </span><span class="kw-2">&</span><span class="lifetime">'_ </span>I {
|
|
<span class="kw">fn </span>cast(<span class="self">self</span>) -> i64 { <span class="self">self</span>.<span class="number">0</span>.cast() }
|
|
}
|
|
|
|
<span class="kw">let </span>owned = I(<span class="number">12</span>);
|
|
<span class="macro">assert_eq!</span>((<span class="kw-2">&</span>owned).az::<i64>(), <span class="number">12</span>);
|
|
<span class="comment">// borrow can be used if chaining is required
|
|
</span><span class="macro">assert_eq!</span>(owned.borrow().az::<i64>(), <span class="number">12</span>);</code></pre></div>
|
|
<h3 id="using-the-az-crate"><a class="doc-anchor" href="#using-the-az-crate">§</a>Using the <em>az</em> crate</h3>
|
|
<p>The <em>az</em> crate is available on <a href="https://crates.io/crates/az">crates.io</a>. To use it in
|
|
your crate, add it as a dependency inside <a href="https://doc.rust-lang.org/cargo/guide/dependencies.html"><em>Cargo.toml</em></a>:</p>
|
|
<div class="example-wrap"><pre class="language-toml"><code>[dependencies]
|
|
az = "1.2"</code></pre></div>
|
|
<p>The crate requires rustc version 1.31.0 or later.</p>
|
|
<h3 id="license"><a class="doc-anchor" href="#license">§</a>License</h3>
|
|
<p>This crate is free software: you can redistribute it and/or modify it
|
|
under the terms of either</p>
|
|
<ul>
|
|
<li>the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a> or</li>
|
|
<li>the <a href="https://opensource.org/licenses/MIT">MIT License</a></li>
|
|
</ul>
|
|
<p>at your option.</p>
|
|
<h4 id="contribution"><a class="doc-anchor" href="#contribution">§</a>Contribution</h4>
|
|
<p>Unless you explicitly state otherwise, any contribution intentionally
|
|
submitted for inclusion in the work by you, as defined in the Apache
|
|
License, Version 2.0, shall be dual licensed as above, without any
|
|
additional terms or conditions.</p>
|
|
</div></details><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="struct" href="struct.Round.html" title="struct az::Round">Round</a></div><div class="desc docblock-short">Used to convert floating-point numbers to integers with rounding
|
|
to the nearest, with ties rounded to even.</div></li></ul><h2 id="traits" class="section-header">Traits<a href="#traits" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="trait" href="trait.Az.html" title="trait az::Az">Az</a></div><div class="desc docblock-short">Used to cast values.</div></li><li><div class="item-name"><a class="trait" href="trait.Cast.html" title="trait az::Cast">Cast</a></div><div class="desc docblock-short">Used to cast values.</div></li><li><div class="item-name"><a class="trait" href="trait.CastFrom.html" title="trait az::CastFrom">Cast<wbr>From</a></div><div class="desc docblock-short">Used to cast values.</div></li><li><div class="item-name"><a class="trait" href="trait.CheckedAs.html" title="trait az::CheckedAs">Checked<wbr>As</a></div><div class="desc docblock-short">Used for checked casts.</div></li><li><div class="item-name"><a class="trait" href="trait.CheckedCast.html" title="trait az::CheckedCast">Checked<wbr>Cast</a></div><div class="desc docblock-short">Used for checked casts.</div></li><li><div class="item-name"><a class="trait" href="trait.CheckedCastFrom.html" title="trait az::CheckedCastFrom">Checked<wbr>Cast<wbr>From</a></div><div class="desc docblock-short">Used for checked casts.</div></li><li><div class="item-name"><a class="trait" href="trait.OverflowingAs.html" title="trait az::OverflowingAs">Overflowing<wbr>As</a></div><div class="desc docblock-short">Used for overflowing casts.</div></li><li><div class="item-name"><a class="trait" href="trait.OverflowingCast.html" title="trait az::OverflowingCast">Overflowing<wbr>Cast</a></div><div class="desc docblock-short">Used for overflowing casts.</div></li><li><div class="item-name"><a class="trait" href="trait.OverflowingCastFrom.html" title="trait az::OverflowingCastFrom">Overflowing<wbr>Cast<wbr>From</a></div><div class="desc docblock-short">Used for overflowing casts.</div></li><li><div class="item-name"><a class="trait" href="trait.SaturatingAs.html" title="trait az::SaturatingAs">Saturating<wbr>As</a></div><div class="desc docblock-short">Used to cast into the destination type, saturating if the value does not fit.</div></li><li><div class="item-name"><a class="trait" href="trait.SaturatingCast.html" title="trait az::SaturatingCast">Saturating<wbr>Cast</a></div><div class="desc docblock-short">Used to cast into the destination type, saturating if the value does not fit.</div></li><li><div class="item-name"><a class="trait" href="trait.SaturatingCastFrom.html" title="trait az::SaturatingCastFrom">Saturating<wbr>Cast<wbr>From</a></div><div class="desc docblock-short">Used to cast, saturating if the value does not fit.</div></li><li><div class="item-name"><a class="trait" href="trait.UnwrappedAs.html" title="trait az::UnwrappedAs">Unwrapped<wbr>As</a></div><div class="desc docblock-short">Used to cast values, panicking if the value does not fit.</div></li><li><div class="item-name"><a class="trait" href="trait.UnwrappedCast.html" title="trait az::UnwrappedCast">Unwrapped<wbr>Cast</a></div><div class="desc docblock-short">Used to cast values, panicking if the value does not fit.</div></li><li><div class="item-name"><a class="trait" href="trait.UnwrappedCastFrom.html" title="trait az::UnwrappedCastFrom">Unwrapped<wbr>Cast<wbr>From</a></div><div class="desc docblock-short">Used to cast values, panicking if the value does not fit.</div></li><li><div class="item-name"><a class="trait" href="trait.WrappingAs.html" title="trait az::WrappingAs">Wrapping<wbr>As</a></div><div class="desc docblock-short">Wrapping cast.</div></li><li><div class="item-name"><a class="trait" href="trait.WrappingCast.html" title="trait az::WrappingCast">Wrapping<wbr>Cast</a></div><div class="desc docblock-short">Wrapping cast.</div></li><li><div class="item-name"><a class="trait" href="trait.WrappingCastFrom.html" title="trait az::WrappingCastFrom">Wrapping<wbr>Cast<wbr>From</a></div><div class="desc docblock-short">Wrapping cast.</div></li></ul><h2 id="functions" class="section-header">Functions<a href="#functions" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="fn" href="fn.cast.html" title="fn az::cast">cast</a></div><div class="desc docblock-short">Casts the value.</div></li><li><div class="item-name"><a class="fn" href="fn.checked_cast.html" title="fn az::checked_cast">checked_<wbr>cast</a></div><div class="desc docblock-short">Casts the value, returning <a href="https://doc.rust-lang.org/1.84.0/core/option/enum.Option.html#variant.None" title="variant core::option::Option::None"><code>None</code></a> if the value does not fit.</div></li><li><div class="item-name"><a class="fn" href="fn.overflowing_cast.html" title="fn az::overflowing_cast">overflowing_<wbr>cast</a></div><div class="desc docblock-short">Overflowing cast.</div></li><li><div class="item-name"><a class="fn" href="fn.saturating_cast.html" title="fn az::saturating_cast">saturating_<wbr>cast</a></div><div class="desc docblock-short">Casts the value, saturating if the value does not fit.</div></li><li><div class="item-name"><a class="fn" href="fn.unwrapped_cast.html" title="fn az::unwrapped_cast">unwrapped_<wbr>cast</a></div><div class="desc docblock-short">Casts the value, panicking if the value does not fit.</div></li><li><div class="item-name"><a class="fn" href="fn.wrapping_cast.html" title="fn az::wrapping_cast">wrapping_<wbr>cast</a></div><div class="desc docblock-short">Casts the value, wrapping on overflow.</div></li></ul></section></div></main></body></html> |