<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>library/portable-simd/README.md - fork/rust @ master</title>
<meta name="description" content="library/portable-simd/README.md in fork/rust at master.">
<meta property="og:title" content="library/portable-simd/README.md - fork/rust @ master">
<meta property="og:description" content="library/portable-simd/README.md in fork/rust at master.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="master" data-tip="3bcad65fbf67b6edf87c949531fbc13435882e6b">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/rust</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/rust</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">bors</span><span class="commit-message" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">Auto merge of #103046 - JanBeh:PR_clarify_cmp_terminology, r=workingjubilee</span><span class="snapshot-sha sha" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">3bcad65fbf6</span><time datetime="2023-10-05T15:24:54+00:00" title="2023-10-05 15:24:54 +0000">2023-10-05</time></p>
<header class="topbar"><details class="switcher"><summary>master</summary><div class="menu"><strong>branches</strong><a class="current" href="/fork/rust/ref/master/">master</a><strong>tags</strong><a href="/fork/rust/ref/1.39.0/">1.39.0</a><a href="/fork/rust/ref/1.40.0/">1.40.0</a><a href="/fork/rust/ref/1.41.0/">1.41.0</a><a href="/fork/rust/ref/1.41.1/">1.41.1</a><a href="/fork/rust/ref/1.42.0/">1.42.0</a><a href="/fork/rust/ref/1.43.0/">1.43.0</a><a href="/fork/rust/ref/1.43.1/">1.43.1</a><a href="/fork/rust/ref/1.44.0/">1.44.0</a><a class="all" href="/fork/rust/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/rust/">rust</a> / <a href="/fork/rust/ref/master/tree/library/">library</a> / <a href="/fork/rust/ref/master/tree/library/portable-simd/">portable-simd</a> / <span class="cur">README.md</span></nav>
<span class="view-stats"><span>2.7 KiB</span><span>59 lines</span></span><span class="actions"><a class="raw" href="/fork/rust/raw/e8ac600debe67881c33b1301aceb4945eb56206f/library/portable-simd/README.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>The Rust standard library's portable SIMD API</h1>
<p><img src="https://github.com/rust-lang/portable-simd/actions/workflows/ci.yml/badge.svg?branch=master" alt="Build Status" /></p>
<p>Code repository for the <a href="https://github.com/rust-lang/project-portable-simd">Portable SIMD Project Group</a>.
Please refer to <a href="/fork/rust/ref/master/blob/library/portable-simd/CONTRIBUTING.md">CONTRIBUTING.md</a> for our contributing guidelines.</p>
<p>The docs for this crate are published from the main branch.
You can <a href="https://rust-lang.github.io/portable-simd/core_simd">read them here</a>.</p>
<p>If you have questions about SIMD, we have begun writing a <a href="/fork/rust/ref/master/blob/library/portable-simd/beginners-guide.md">guide</a>.
We can also be found on <a href="https://rust-lang.zulipchat.com/#narrow/stream/257879-project-portable-simd">Zulip</a>.</p>
<p>If you are interested in support for a specific architecture, you may want <a href="https://github.com/rust-lang/stdarch">stdarch</a> instead.</p>
<h2>Hello World</h2>
<p>Now we're gonna dip our toes into this world with a small SIMD "Hello, World!" example. Make sure your compiler is up to date and using <code>nightly</code>. We can do that by running</p>
<pre class="language-bash"><a-f>rustup</a-f> update <a-co>--</a-co> nightly</pre>
<p>or by setting up <code>rustup default nightly</code> or else with <code>cargo +nightly {build,test,run}</code>. After updating, run</p>
<pre class="language-bash"><a-f>cargo</a-f> new hellosimd</pre>
<p>to create a new crate. Finally write this in <code>src/main.rs</code>:</p>
<pre class="language-rust"><a-at>#!</a-at><a-p>[</a-p><a-at>feature</a-at><a-p>(</a-p><a-at>portable_simd</a-at><a-p>)]</a-p>
<a-k>use</a-k> std<a-p>::</a-p>simd<a-p>::</a-p>f32x4<a-p>;</a-p>
<a-k>fn</a-k> <a-f>main</a-f><a-p>()</a-p> <a-p>{</a-p>
    <a-k>let</a-k> a = f32x4<a-p>::</a-p><a-f>splat</a-f><a-p>(</a-p><a-co>10.0</a-co><a-p>);</a-p>
    <a-k>let</a-k> b = f32x4<a-p>::</a-p><a-f>from_array</a-f><a-p>([</a-p><a-co>1.0</a-co><a-p>,</a-p> <a-co>2.0</a-co><a-p>,</a-p> <a-co>3.0</a-co><a-p>,</a-p> <a-co>4.0</a-co><a-p>]);</a-p>
    <a-m>println!</a-m><a-p>(</a-p><a-s>&quot;{:?}&quot;</a-s><a-p>,</a-p> a + b<a-p>);</a-p>
<a-p>}</a-p></pre>
<p>Explanation: We construct our SIMD vectors with methods like <code>splat</code> or <code>from_array</code>. Next, we can use operators like <code>+</code> on them, and the appropriate SIMD instructions will be carried out. When we run <code>cargo run</code> you should get <code>[11.0, 12.0, 13.0, 14.0]</code>.</p>
<h2>Supported vectors</h2>
<p>Currently, vectors may have up to 64 elements, but aliases are provided only up to 512-bit vectors.</p>
<p>Depending on the size of the primitive type, the number of lanes the vector will have varies. For example, 128-bit vectors have four <code>f32</code> lanes and two <code>f64</code> lanes.</p>
<p>The supported element types are as follows:</p>
<ul>
<li><strong>Floating Point:</strong> <code>f32</code>, <code>f64</code></li>
<li><strong>Signed Integers:</strong> <code>i8</code>, <code>i16</code>, <code>i32</code>, <code>i64</code>, <code>isize</code> (<code>i128</code> excluded)</li>
<li><strong>Unsigned Integers:</strong> <code>u8</code>, <code>u16</code>, <code>u32</code>, <code>u64</code>, <code>usize</code> (<code>u128</code> excluded)</li>
<li><strong>Pointers:</strong> <code>*const T</code> and <code>*mut T</code> (zero-sized metadata only)</li>
<li><strong>Masks:</strong> 8-bit, 16-bit, 32-bit, 64-bit, and <code>usize</code>-sized masks</li>
</ul>
<p>Floating point, signed integers, unsigned integers, and pointers are the <a href="https://doc.rust-lang.org/core/primitive/index.html">primitive types</a> you're already used to.
The mask types have elements that are "truthy" values, like <code>bool</code>, but have an unspecified layout because different architectures prefer different layouts for mask types.</p>
</section><div class="code-panel"><pre class="code src" data-hl="library/portable-simd/README.md"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"># The Rust standard library's portable SIMD API</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text">![Build Status](https://github.com/rust-lang/portable-simd/actions/workflows/ci.yml/badge.svg?branch=master)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">Code repository for the [Portable SIMD Project Group](https://github.com/rust-lang/project-portable-simd).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">Please refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for our contributing guidelines.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">The docs for this crate are published from the main branch.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text">You can [read them here][docs].</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text">If you have questions about SIMD, we have begun writing a [guide][simd-guide].</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">We can also be found on [Zulip][zulip-project-portable-simd].</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">If you are interested in support for a specific architecture, you may want [stdarch] instead.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">## Hello World</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">Now we're gonna dip our toes into this world with a small SIMD &quot;Hello, World!&quot; example. Make sure your compiler is up to date and using `nightly`. We can do that by running </span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">```bash</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">rustup update -- nightly</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text">or by setting up `rustup default nightly` or else with `cargo +nightly {build,test,run}`. After updating, run </span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text">```bash</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">cargo new hellosimd</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">to create a new crate. Finally write this in `src/main.rs`:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text">```rust</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">#![feature(portable_simd)]</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text">use std::simd::f32x4;</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text">fn main() {</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text">    let a = f32x4::splat(10.0);</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text">    let b = f32x4::from_array([1.0, 2.0, 3.0, 4.0]);</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text">    println!(&quot;{:?}&quot;, a + b);</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text">}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text">Explanation: We construct our SIMD vectors with methods like `splat` or `from_array`. Next, we can use operators like `+` on them, and the appropriate SIMD instructions will be carried out. When we run `cargo run` you should get `[11.0, 12.0, 13.0, 14.0]`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text">## Supported vectors</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text">Currently, vectors may have up to 64 elements, but aliases are provided only up to 512-bit vectors.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text">Depending on the size of the primitive type, the number of lanes the vector will have varies. For example, 128-bit vectors have four `f32` lanes and two `f64` lanes.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text">The supported element types are as follows:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text">* **Floating Point:** `f32`, `f64`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text">* **Signed Integers:** `i8`, `i16`, `i32`, `i64`, `isize` (`i128` excluded)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text">* **Unsigned Integers:** `u8`, `u16`, `u32`, `u64`, `usize` (`u128` excluded)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text">* **Pointers:** `*const T` and `*mut T` (zero-sized metadata only)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text">* **Masks:** 8-bit, 16-bit, 32-bit, 64-bit, and `usize`-sized masks</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text">Floating point, signed integers, unsigned integers, and pointers are the [primitive types](https://doc.rust-lang.org/core/primitive/index.html) you're already used to.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text">The mask types have elements that are &quot;truthy&quot; values, like `bool`, but have an unspecified layout because different architectures prefer different layouts for mask types.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text">[simd-guide]: ./beginners-guide.md</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text">[zulip-project-portable-simd]: https://rust-lang.zulipchat.com/#narrow/stream/257879-project-portable-simd</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text">[stdarch]: https://github.com/rust-lang/stdarch</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text">[docs]: https://rust-lang.github.io/portable-simd/core_simd</span></span></pre></div></div>
</main>
</body>
</html>
