-
Notifications
You must be signed in to change notification settings - Fork 10
/
Copy pathindex.html
102 lines (102 loc) · 17.7 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
<!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="A crate that provides support for half-precision 16-bit floating point types."><title>half - 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-46132b98.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="half" data-themes="" data-resource-suffix="" data-rustdoc-version="1.85.0 (4d91de4e4 2025-02-17)" data-channel="1.85.0" data-search-js="search-75f5ac3e.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="../half/index.html">half</a><span class="version">2.6.0</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="#serialization" title="Serialization">Serialization</a></li><li><a href="#hardware-support" title="Hardware support">Hardware support</a></li><li><a href="#cargo-features" title="Cargo Features">Cargo Features</a></li></ul><h3><a href="#modules">Crate Items</a></h3><ul class="block"><li><a href="#modules" title="Modules">Modules</a></li><li><a href="#structs" title="Structs">Structs</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>half</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/half/lib.rs.html#1-271">Source</a> </span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>A crate that provides support for half-precision 16-bit floating point types.</p>
<p>This crate provides the <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> type, which is an implementation of the IEEE 754-2008 standard
<a href="https://en.wikipedia.org/wiki/Half-precision_floating-point_format"><code>binary16</code></a> a.k.a “half” floating point type. This 16-bit floating point type is intended for
efficient storage where the full range and precision of a larger floating point value is not
required. This is especially useful for image storage formats.</p>
<p>This crate also provides a <a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a> type, an alternative 16-bit floating point format. The
<a href="https://en.wikipedia.org/wiki/Bfloat16_floating-point_format"><code>bfloat16</code></a> format is a truncated IEEE 754 standard <code>binary32</code> float that preserves the
exponent to allow the same range as <a href="https://doc.rust-lang.org/1.85.0/std/primitive.f32.html" title="primitive f32"><code>f32</code></a> but with only 8 bits of precision (instead of 11
bits for <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a>). See the <a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a> type for details.</p>
<p>Because <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> and <a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a> are primarily for efficient storage, floating point operations such
as addition, multiplication, etc. are not always implemented by hardware. When hardware does not
support these operations, this crate emulates them by converting the value to
<a href="https://doc.rust-lang.org/1.85.0/std/primitive.f32.html" title="primitive f32"><code>f32</code></a> before performing the operation and then back afterward.</p>
<p>Note that conversion from <a href="https://doc.rust-lang.org/1.85.0/std/primitive.f32.html" title="primitive f32"><code>f32</code></a>/<a href="https://doc.rust-lang.org/1.85.0/std/primitive.f64.html" title="primitive f64"><code>f64</code></a> to both <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> and <a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a> are lossy operations, and
just as converting a <a href="https://doc.rust-lang.org/1.85.0/std/primitive.f64.html" title="primitive f64"><code>f64</code></a> to <a href="https://doc.rust-lang.org/1.85.0/std/primitive.f32.html" title="primitive f32"><code>f32</code></a> is lossy and does not have <code>Into</code>/<code>From</code> trait
implementations, so too do these smaller types not have those trait implementations either.
Instead, use <code>from_f32</code>/<code>from_f64</code> functions for the types in this crate. If you don’t care
about lossy conversions and need trait conversions, use the appropriate <a href="https://crates.io/crates/num-traits"><code>num-traits</code></a>
traits that are implemented.</p>
<p>This crate also provides a <a href="slice/index.html" title="mod half::slice"><code>slice</code></a> module for zero-copy in-place conversions of
<a href="https://doc.rust-lang.org/1.85.0/std/primitive.u16.html" title="primitive u16"><code>u16</code></a> slices to both <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> and <a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a>, as well as efficient vectorized conversions of
larger buffers of floating point values to and from these half formats.</p>
<p>The crate supports <code>#[no_std]</code> when the <code>std</code> cargo feature is not enabled, so can be used in
embedded environments without using the Rust <a href="https://doc.rust-lang.org/std/"><code>std</code></a> library. The <code>std</code> feature enables support
for the standard library and is enabled by default, see the <a href="#cargo-features">Cargo Features</a>
section below.</p>
<p>A <a href="prelude/index.html" title="mod half::prelude"><code>prelude</code></a> module is provided for easy importing of available utility traits.</p>
<h2 id="serialization"><a class="doc-anchor" href="#serialization">§</a>Serialization</h2>
<p>When the <code>serde</code> feature is enabled, <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> and <a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a> will be serialized as a newtype of
<a href="https://doc.rust-lang.org/1.85.0/std/primitive.u16.html" title="primitive u16"><code>u16</code></a> by default. In binary formats this is ideal, as it will generally use just two bytes for
storage. For string formats like JSON, however, this isn’t as useful, and due to design
limitations of serde, it’s not possible for the default <code>Serialize</code> implementation to support
different serialization for different formats.</p>
<p>Instead, it’s up to the containter type of the floats to control how it is serialized. This can
easily be controlled when using the derive macros using <code>#[serde(serialize_with="")]</code>
attributes. For both <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> and <a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a> a <code>serialize_as_f32</code> and <code>serialize_as_string</code> are
provided for use with this attribute.</p>
<p>Deserialization of both float types supports deserializing from the default serialization,
strings, and <code>f32</code>/<code>f64</code> values, so no additional work is required.</p>
<h2 id="hardware-support"><a class="doc-anchor" href="#hardware-support">§</a>Hardware support</h2>
<p>Hardware support for these conversions and arithmetic will be used
whenever hardware support is available—either through instrinsics or targeted assembly—although
a nightly Rust toolchain may be required for some hardware. When hardware supports it the
functions and traits in the <a href="slice/index.html" title="mod half::slice"><code>slice</code></a> and <a href="vec/index.html" title="mod half::vec"><code>vec</code></a> modules will also use vectorized
SIMD intructions for increased efficiency.</p>
<p>The following list details hardware support for floating point types in this crate. When using
<code>std</code> cargo feature, runtime CPU target detection will be used. To get the most performance
benefits, compile for specific CPU features which avoids the runtime overhead and works in a
<code>no_std</code> environment.</p>
<div><table><thead><tr><th>Architecture</th><th>CPU Target Feature</th><th>Notes</th></tr></thead><tbody>
<tr><td><code>x86</code>/<code>x86_64</code></td><td><code>f16c</code></td><td>This supports conversion to/from <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> only (including vector SIMD) and does not support any <a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a> or arithmetic operations.</td></tr>
<tr><td><code>aarch64</code></td><td><code>fp16</code></td><td>This supports all operations on <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> only.</td></tr>
</tbody></table>
</div><h2 id="cargo-features"><a class="doc-anchor" href="#cargo-features">§</a>Cargo Features</h2>
<p>This crate supports a number of optional cargo features. None of these features are enabled by
default, even <code>std</code>.</p>
<ul>
<li>
<p><strong><code>alloc</code></strong> — Enable use of the <a href="https://doc.rust-lang.org/alloc/"><code>alloc</code></a> crate when not using the <code>std</code> library.</p>
<p>Among other functions, this enables the <a href="vec/index.html" title="mod half::vec"><code>vec</code></a> module, which contains zero-copy
conversions for the <a href="vec/index.html" title="mod half::vec"><code>Vec</code></a> type. This allows fast conversion between raw <code>Vec<u16></code> bits and
<code>Vec<f16></code> or <code>Vec<bf16></code> arrays, and vice versa.</p>
</li>
<li>
<p><strong><code>std</code></strong> — Enable features that depend on the Rust <a href="https://doc.rust-lang.org/std/"><code>std</code></a> library. This also enables the
<code>alloc</code> feature automatically.</p>
<p>Enabling the <code>std</code> feature enables runtime CPU feature detection of hardware support.
Without this feature detection, harware is only used when compiler target supports them.</p>
</li>
<li>
<p><strong><code>serde</code></strong> — Adds support for the <a href="https://crates.io/crates/serde"><code>serde</code></a> crate by implementing <a href="https://docs.rs/serde/*/serde/trait.Serialize.html"><code>Serialize</code></a> and
<a href="https://docs.rs/serde/*/serde/trait.Deserialize.html"><code>Deserialize</code></a> traits for both <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> and <a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a>.</p>
</li>
<li>
<p><strong><code>num-traits</code></strong> — Adds support for the <a href="https://crates.io/crates/num-traits"><code>num-traits</code></a> crate by implementing <a href="https://docs.rs/num-traits/*/num_traits/cast/trait.ToPrimitive.html"><code>ToPrimitive</code></a>,
<a href="https://docs.rs/num-traits/*/num_traits/cast/trait.FromPrimitive.html"><code>FromPrimitive</code></a>, <a href="https://docs.rs/num-traits/*/num_traits/ops/bytes/trait.ToBytes.html"><code>ToBytes</code></a>, <code>FromBytes</code>, <a href="https://docs.rs/num-traits/*/num_traits/cast/trait.AsPrimitive.html"><code>AsPrimitive</code></a>, <a href="https://docs.rs/num-traits/*/num_traits/trait.Num.html"><code>Num</code></a>, <a href="https://docs.rs/num-traits/*/num_traits/float/trait.Float.html"><code>Float</code></a>,
<a href="https://docs.rs/num-traits/*/num_traits/float/trait.FloatCore.html"><code>FloatCore</code></a>, and <a href="https://docs.rs/num-traits/*/num_traits/bounds/trait.Bounded.html"><code>Bounded</code></a> traits for both <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> and <a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a>.</p>
</li>
<li>
<p><strong><code>bytemuck</code></strong> — Adds support for the <a href="https://crates.io/crates/bytemuck"><code>bytemuck</code></a> crate by implementing <a href="https://docs.rs/bytemuck/*/bytemuck/trait.Zeroable.html"><code>Zeroable</code></a> and
<a href="https://docs.rs/bytemuck/*bytemuck/trait.Pod.html"><code>Pod</code></a> traits for both <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> and <a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a>.</p>
</li>
<li>
<p><strong><code>zerocopy</code></strong> — Adds support for the <a href="https://crates.io/crates/zerocopy"><code>zerocopy</code></a> crate by implementing <a href="https://docs.rs/zerocopy/*/zerocopy/trait.IntoBytes.html"><code>IntoBytes</code></a> and
<a href="https://docs.rs/zerocopy/*/zerocopy/trait.FromBytes.html"><code>FromBytes</code></a> traits for both <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> and <a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a>.</p>
</li>
<li>
<p><strong><code>rand_distr</code></strong> — Adds support for the <a href="https://crates.io/crates/rand_distr"><code>rand_distr</code></a> crate by implementing <a href="https://docs.rs/rand/*/rand/distr/trait.Distribution.html"><code>Distribution</code></a>
and other traits for both <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> and <a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a>.</p>
</li>
<li>
<p><strong><code>rkyv</code></strong> – Enable zero-copy deserializtion with <a href="(https://crates.io/crates/rkyv)"><code>rkyv</code></a> crate.</p>
</li>
<li>
<p><strong><code>aribtrary</code></strong> – Enable fuzzing support with <a href="(https://crates.io/crates/arbitrary)"><code>arbitrary</code></a> crate by implementing
<a href="(https://crates.io/crates/arbitrary)"><code>Arbitrary</code></a> trait.</p>
</li>
</ul>
</div></details><h2 id="modules" class="section-header">Modules<a href="#modules" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="mod" href="bfloat/index.html" title="mod half::bfloat">bfloat</a><span title="Restricted Visibility"> 🔒</span> </div></li><li><div class="item-name"><a class="mod" href="binary16/index.html" title="mod half::binary16">binary16</a><span title="Restricted Visibility"> 🔒</span> </div></li><li><div class="item-name"><a class="mod" href="leading_zeros/index.html" title="mod half::leading_zeros">leading_<wbr>zeros</a><span title="Restricted Visibility"> 🔒</span> </div></li><li><div class="item-name"><a class="mod" href="prelude/index.html" title="mod half::prelude">prelude</a></div><div class="desc docblock-short">A collection of the most used items and traits in this crate for easy importing.</div></li><li><div class="item-name"><a class="mod" href="private/index.html" title="mod half::private">private</a><span title="Restricted Visibility"> 🔒</span> </div></li><li><div class="item-name"><a class="mod" href="slice/index.html" title="mod half::slice">slice</a></div><div class="desc docblock-short">Contains utility functions and traits to convert between slices of <a href="https://doc.rust-lang.org/1.85.0/std/primitive.u16.html" title="primitive u16"><code>u16</code></a> bits and <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> or
<a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a> numbers.</div></li><li><div class="item-name"><a class="mod" href="vec/index.html" title="mod half::vec">vec</a></div><div class="desc docblock-short">Contains utility functions and traits to convert between vectors of <a href="https://doc.rust-lang.org/1.85.0/std/primitive.u16.html" title="primitive u16"><code>u16</code></a> bits and <a href="struct.f16.html" title="struct half::f16"><code>f16</code></a> or
<a href="struct.bf16.html" title="struct half::bf16"><code>bf16</code></a> vectors.</div></li></ul><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.bf16.html" title="struct half::bf16">bf16</a></div><div class="desc docblock-short">A 16-bit floating point type implementing the <a href="https://en.wikipedia.org/wiki/Bfloat16_floating-point_format"><code>bfloat16</code></a> format.</div></li><li><div class="item-name"><a class="struct" href="struct.f16.html" title="struct half::f16">f16</a></div><div class="desc docblock-short">A 16-bit floating point type implementing the IEEE 754-2008 standard <a href="https://en.wikipedia.org/wiki/Half-precision_floating-point_format"><code>binary16</code></a> a.k.a “half”
format.</div></li></ul></section></div></main></body></html>