129 lines
44 KiB
HTML
129 lines
44 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="Marker trait for types that can be represented as a fixed size array."><title>ArrayCast in cosmic::cosmic_theme::palette::cast - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.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-aa0817cf.css"><meta name="rustdoc-vars" data-root-path="../../../../" data-static-root-path="../../../../static.files/" data-current-crate="cosmic" data-themes="" data-resource-suffix="" data-rustdoc-version="1.90.0-nightly (3048886e5 2025-07-30)" data-channel="nightly" data-search-js="search-fa3e91e5.js" data-settings-js="settings-5514c975.js" ><script src="../../../../static.files/storage-68b7e25d.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../../../static.files/main-eebb9057.js"></script><noscript><link rel="stylesheet" href="../../../../static.files/noscript-32bb7600.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 trait"><!--[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="../../../../cosmic/index.html">cosmic</a><span class="version">1.0.0</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">Array<wbr>Cast</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#deriving" title="Deriving">Deriving</a><ul><li><a href="#field-attributes" title="Field Attributes">Field Attributes</a></li><li><a href="#examples" title="Examples">Examples</a></li><li><a href="#safety" title="Safety">Safety</a></li></ul></li></ul><h3><a href="#required-associated-types">Required Associated Types</a></h3><ul class="block"><li><a href="#associatedtype.Array" title="Array">Array</a></li></ul><h3><a href="#dyn-compatibility">Dyn Compatibility</a></h3><h3><a href="#implementors">Implementors</a></h3></section><div id="rustdoc-modnav"><h2><a href="index.html">In cosmic::<wbr>cosmic_<wbr>theme::<wbr>palette::<wbr>cast</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../../../index.html">cosmic</a>::<wbr><a href="../../index.html">cosmic_theme</a>::<wbr><a href="../index.html">palette</a>::<wbr><a href="index.html">cast</a></div><h1>Trait <span class="trait">ArrayCast</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="https://docs.rs/palette/0.7.6/src/palette/cast/array.rs.html#141">Source</a> </span></div><pre class="rust item-decl"><code>pub unsafe trait ArrayCast: <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a> {
|
|||
|
|
type <a href="#associatedtype.Array" class="associatedtype">Array</a>: <a class="trait" href="../trait.ArrayExt.html" title="trait cosmic::cosmic_theme::palette::ArrayExt">ArrayExt</a>;
|
|||
|
|
}</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Marker trait for types that can be represented as a fixed size array.</p>
|
|||
|
|
<p>A type that implements this trait is assumed to have the exact same memory
|
|||
|
|
layout and representation as a fixed size array. This implies a couple of
|
|||
|
|
useful properties:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>Casting between <code>T</code> and <code>T::Array</code> is free and will (or should) be
|
|||
|
|
optimized away.</li>
|
|||
|
|
<li><code>[T]</code> can be cast to and from <code>[T::Array]</code>, which can be cast to and from
|
|||
|
|
<code>[U]</code> where <code>T::Array = [U; N]</code> and the length is a multiple of <code>N</code>.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>This allows a number of common and useful optimizations, including casting
|
|||
|
|
buffers and reusing memory. It does however come with some strict
|
|||
|
|
requirements and the recommendation is to use <code>#[derive(ArrayCast)]</code> which
|
|||
|
|
checks for them automatically.</p>
|
|||
|
|
<h2 id="deriving"><a class="doc-anchor" href="#deriving">§</a>Deriving</h2>
|
|||
|
|
<p><code>ArrayCast</code> can be automatically derived. The only requirements are that the
|
|||
|
|
type is a <code>struct</code>, that it has a <code>#[repr(C)]</code> or <code>#[repr(transparent)]</code>
|
|||
|
|
attribute, and that all of its fields have the same types. It stays on the
|
|||
|
|
conservative side and will show an error if any of those requirements are
|
|||
|
|
not fulfilled. If some fields have different types, but the same memory
|
|||
|
|
layout, or are zero-sized, they can be marked with attributes to show that
|
|||
|
|
their types are safe to use.</p>
|
|||
|
|
<h3 id="field-attributes"><a class="doc-anchor" href="#field-attributes">§</a>Field Attributes</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li>
|
|||
|
|
<p><code>#[palette_unsafe_same_layout_as = "SomeType"]</code>: Mark the field as having
|
|||
|
|
the same memory layout as <code>SomeType</code>.</p>
|
|||
|
|
<p><strong>Safety:</strong> corrupt data and undefined behavior may occur if this is not
|
|||
|
|
true!</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p><code>#[palette_unsafe_zero_sized]</code>: Mark the field as being zero-sized, and
|
|||
|
|
thus not taking up any memory space. This means that it can be ignored.</p>
|
|||
|
|
<p><strong>Safety:</strong> corrupt data and undefined behavior may occur if this is not
|
|||
|
|
true!</p>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
<h3 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h3>
|
|||
|
|
<p>Basic use:</p>
|
|||
|
|
|
|||
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>palette::cast::{<span class="self">self</span>, ArrayCast};
|
|||
|
|
|
|||
|
|
<span class="attr">#[derive(PartialEq, Debug, ArrayCast)]
|
|||
|
|
#[repr(C)]
|
|||
|
|
</span><span class="kw">struct </span>MyCmyk {
|
|||
|
|
cyan: f32,
|
|||
|
|
magenta: f32,
|
|||
|
|
yellow: f32,
|
|||
|
|
key: f32,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
<span class="kw">let </span>buffer = [<span class="number">0.1</span>, <span class="number">0.2</span>, <span class="number">0.3</span>, <span class="number">0.4</span>];
|
|||
|
|
<span class="kw">let </span>color: MyCmyk = cast::from_array(buffer);
|
|||
|
|
|
|||
|
|
<span class="macro">assert_eq!</span>(
|
|||
|
|
color,
|
|||
|
|
MyCmyk {
|
|||
|
|
cyan: <span class="number">0.1</span>,
|
|||
|
|
magenta: <span class="number">0.2</span>,
|
|||
|
|
yellow: <span class="number">0.3</span>,
|
|||
|
|
key: <span class="number">0.4</span>,
|
|||
|
|
}
|
|||
|
|
);</code></pre></div>
|
|||
|
|
<p>Heterogenous field types:</p>
|
|||
|
|
|
|||
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>std::marker::PhantomData;
|
|||
|
|
|
|||
|
|
<span class="kw">use </span>palette::{cast::{<span class="self">self</span>, ArrayCast}, encoding::Srgb, RgbHue};
|
|||
|
|
|
|||
|
|
<span class="attr">#[derive(PartialEq, Debug, ArrayCast)]
|
|||
|
|
#[repr(C)]
|
|||
|
|
</span><span class="kw">struct </span>MyCoolColor<S> {
|
|||
|
|
<span class="attr">#[palette(unsafe_zero_sized)]
|
|||
|
|
</span>standard: PhantomData<S>,
|
|||
|
|
<span class="comment">// RgbHue is a wrapper with `#[repr(C)]`, so it can safely
|
|||
|
|
// be converted straight from `f32`.
|
|||
|
|
</span><span class="attr">#[palette(unsafe_same_layout_as = <span class="string">"f32"</span>)]
|
|||
|
|
</span>hue: RgbHue<f32>,
|
|||
|
|
lumen: f32,
|
|||
|
|
chroma: f32,
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
<span class="kw">let </span>buffer = [<span class="number">172.0</span>, <span class="number">100.0</span>, <span class="number">0.3</span>];
|
|||
|
|
<span class="kw">let </span>color: MyCoolColor<Srgb> = cast::from_array(buffer);
|
|||
|
|
|
|||
|
|
<span class="macro">assert_eq!</span>(
|
|||
|
|
color,
|
|||
|
|
MyCoolColor {
|
|||
|
|
hue: <span class="number">172.0</span>.into(),
|
|||
|
|
lumen: <span class="number">100.0</span>,
|
|||
|
|
chroma: <span class="number">0.3</span>,
|
|||
|
|
standard: PhantomData,
|
|||
|
|
}
|
|||
|
|
);</code></pre></div>
|
|||
|
|
<h3 id="safety"><a class="doc-anchor" href="#safety">§</a>Safety</h3>
|
|||
|
|
<ul>
|
|||
|
|
<li>The type must be inhabited (eg: no
|
|||
|
|
<a href="../../../iced/enum.Never.html" title="enum cosmic::iced::Never">Infallible</a>).</li>
|
|||
|
|
<li>The type must allow any values in the array items (eg: either no
|
|||
|
|
requirements or some ability to recover from invalid values).</li>
|
|||
|
|
<li>The type must be homogeneous (eg: all fields have the same type, or are
|
|||
|
|
wrappers that implement <code>ArrayCast</code> with the same field type, or are zero
|
|||
|
|
sized).</li>
|
|||
|
|
<li>The length of <code>Array</code> must be the sum of the number of color component
|
|||
|
|
fields in the type and in any possible compound fields.</li>
|
|||
|
|
<li>The type must be <code>repr(C)</code> or <code>repr(transparent)</code>.</li>
|
|||
|
|
<li>The type must have the same size and alignment as <code>Self::Array</code>.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Note also that the type is assumed to not implement <code>Drop</code>. This will
|
|||
|
|
rarely, if ever, be an issue. The requirements above ensures that the
|
|||
|
|
underlying field types stay the same and will be dropped.</p>
|
|||
|
|
<p>For example:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>Srgb<T></code> can be cast to <code>[T; 3]</code> because it has three non-zero sized
|
|||
|
|
fields of type <code>T</code>.</li>
|
|||
|
|
<li><code>Alpha<Srgb<T>, T></code> can be cast to <code>[T; 4]</code>, that is <code>3 + 1</code> items,
|
|||
|
|
because it’s the sum of the three items from <code>Srgb</code> and the one extra
|
|||
|
|
<code>alpha</code> field.</li>
|
|||
|
|
<li><code>Alpha<Srgb<T>, U></code> is not allowed because <code>T</code> and <code>U</code> are different
|
|||
|
|
types.</li>
|
|||
|
|
</ul>
|
|||
|
|
</div></details><h2 id="required-associated-types" class="section-header">Required Associated Types<a href="#required-associated-types" class="anchor">§</a></h2><div class="methods"><details class="toggle" open><summary><section id="associatedtype.Array" class="method"><a class="src rightside" href="https://docs.rs/palette/0.7.6/src/palette/cast/array.rs.html#143">Source</a><h4 class="code-header">type <a href="#associatedtype.Array" class="associatedtype">Array</a>: <a class="trait" href="../trait.ArrayExt.html" title="trait cosmic::cosmic_theme::palette::ArrayExt">ArrayExt</a></h4></section></summary><div class="docblock"><p>The output type of a cast to an array.</p>
|
|||
|
|
</div></details></div><h2 id="dyn-compatibility" class="section-header">Dyn Compatibility<a href="#dyn-compatibility" class="anchor">§</a></h2><div class="dyn-compatibility-info"><p>This trait is <b>not</b> <a href="https://doc.rust-lang.org/nightly/reference/items/traits.html#dyn-compatibility">dyn compatible</a>.</p><p><i>In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.</i></p></div><h2 id="implementors" class="section-header">Implementors<a href="#implementors" class="anchor">§</a></h2><div id="implementors-list"><details class="toggle implementors-toggle"><summary><section id="impl-ArrayCast-for-Alpha%3CC,+%3C%3CC+as+ArrayCast%3E::Array+as+ArrayExt%3E::Item%3E" class="impl"><a class="src rightside" href="https://docs.rs/palette/0.7.6/src/palette/alpha/alpha.rs.html#437-440">Source</a><a href="#impl-ArrayCast-for-Alpha%3CC,+%3C%3CC+as+ArrayCast%3E::Array+as+ArrayExt%3E::Item%3E" class="anchor">§</a><h3 class="code-header">impl<C> <a class="trait" href="trait.ArrayCast.html" title="trait cosmic::cosmic_theme::palette::cast::ArrayCast">ArrayCast</a> for <a class="struct" href="../struct.Alpha.html" title="struct cosmic::cosmic_theme::palette::Alpha">Alpha</a><C, <<C as <a class="trait" href="trait.ArrayCast.html" title="trait cosmic::cosmic_theme::palette::cast::ArrayCast">ArrayCast</a>>::<a class="associatedtype" href="trait.ArrayCast.html#associatedtype.Array" title="type cosmic::cosmic_theme::palette::cast::ArrayCast::Array">Array</a> as <a class="trait" href="../trait.ArrayExt.html" title="trait cosmic::cosmic_theme::palette::ArrayExt">ArrayExt</a>>::<a class="associatedtype" href="../trait.ArrayExt.html#associatedtype.Item" title="type cosmic::cosmic_theme::palette::ArrayExt::Item">Item</a>><div class="where">where
|
|||
|
|
C: <a class="trait" href="trait.ArrayCast.html" title="trait cosmic::cosmic_theme::palette::cast::ArrayCast">ArrayCast</a>,
|
|||
|
|
<C as <a class="trait" href="trait.ArrayCast.html" title="trait cosmic::cosmic_theme::palette::cast::ArrayCast">ArrayCast</a>>::<a class="associatedtype" href="trait.ArrayCast.html#associatedtype.Array" title="type cosmic::cosmic_theme::palette::cast::ArrayCast::Array">Array</a>: <a class="trait" href="../trait.NextArray.html" title="trait cosmic::cosmic_theme::palette::NextArray">NextArray</a>,</div></h3></section></summary><div class="impl-items"><section id="associatedtype.Array-1" class="associatedtype trait-impl"><a class="src rightside" href="https://docs.rs/palette/0.7.6/src/palette/alpha/alpha.rs.html#442">Source</a><a href="#associatedtype.Array-1" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Array" class="associatedtype">Array</a> = <<C as <a class="trait" href="trait.ArrayCast.html" title="trait cosmic::cosmic_theme::palette::cast::ArrayCast">ArrayCast</a>>::<a class="associatedtype" href="trait.ArrayCast.html#associatedtype.Array" title="type cosmic::cosmic_theme::palette::cast::ArrayCast::Array">Array</a> as <a class="trait" href="../trait.NextArray.html" title="trait cosmic::cosmic_theme::palette::NextArray">NextArray</a>>::<a class="associatedtype" href="../trait.NextArray.html#associatedtype.Next" title="type cosmic::cosmic_theme::palette::NextArray::Next">Next</a></h4></section></div></details><details class="toggle implementors-toggle"><summary><section id="impl-ArrayCast-for-PreAlpha%3CC%3E" class="impl"><a class="src rightside" href="https://docs.rs/palette/0.7.6/src/palette/blend/pre_alpha.rs.html#158-161">Source</a><a href="#impl-ArrayCast-for-PreAlpha%3CC%3E" class="anchor">§</a><h3 class="code-header">impl<C, T> <a class="trait" href="trait.ArrayCast.html" title="trait cosmic::cosmic_theme::palette::cast::ArrayCast">ArrayCast</a> for <a class="struct" href="../alpha/struct.PreAlpha.html" title="struct cosmic::cosmic_theme::palette::alpha::PreAlpha">PreAlpha</a><C><div class="where">where
|
|||
|
|
C: <a class="trait" href="trait.ArrayCast.html" title="trait cosmic::cosmic_theme::palette::cast::ArrayCast">ArrayCast</a> + <a class="trait" href="../blend/trait.Premultiply.html" title="trait cosmic::cosmic_theme::palette::blend::Premultiply">Premultiply</a><Scalar = T>,
|
|||
|
|
<C as <a class="trait" href="trait.ArrayCast.html" title="trait cosmic::cosmic_theme::palette::cast::ArrayCast">ArrayCast</a>>::<a class="associatedtype" href="trait.ArrayCast.html#associatedtype.Array" title="type cosmic::cosmic_theme::palette::cast::ArrayCast::Array">Array</a>: <a class="trait" href="../trait.NextArray.html" title="trait cosmic::cosmic_theme::palette::NextArray">NextArray</a> + <a class="trait" href="../trait.ArrayExt.html" title="trait cosmic::cosmic_theme::palette::ArrayExt">ArrayExt</a><Item = T>,</div></h3></section></summary><div class="impl-items"><section id="associatedtype.Array-2" class="associatedtype trait-impl"><a class="src rightside" href="https://docs.rs/palette/0.7.6/src/palette/blend/pre_alpha.rs.html#163">Source</a><a href="#associatedtype.Array-2" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Array" class="associatedtype">Array</a> = <<C as <a class="trait" href="trait.ArrayCast.html" title="trait cosmic::cosmic_theme::palette::cast::ArrayCast">ArrayCast</a>>::<a class="associatedtype" href="trait.ArrayCast.html#associatedtype.Array" title="type cosmic::cosmic_theme::palette::cast::ArrayCast::Array">Array</a> as <a class="trait" href="../trait.NextArray.html" title="trait cosmic::cosmic_theme::palette::NextArray">NextArray</a>>::<a class="associatedtype" href="../trait.NextArray.html#associatedtype.Next" title="type cosmic::cosmic_theme::palette::NextArray::Next">Next</a></h4></section></div></details><details class="toggle implementors-toggle"><summary><section id="impl-ArrayCast-for-Packed%3CO,+%5BT;+N%5D%3E" class="impl"><a class="src rightside" href="https://docs.rs/palette/0.7.6/src/palette/cast/packed.rs.html#116">Source</a><a href="#impl-ArrayCast-for-Packed%3CO,+%5BT;+N%5D%3E" class="anchor">§</a><h3 class="code-header">impl<O, T, const N: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>> <a class="trait" href="trait.ArrayCast.html" title="trait cosmic::cosmic_theme::palette::cast::ArrayCast">ArrayCast</a> for <a class="struct" href="struct.Packed.html" title="struct cosmic::cosmic_theme::palette::cast::Packed">Packed</a><O, <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.array.html">[T; N]</a>></h3></section></summary><div class="impl-items"><section id="associatedtype.Array-3" class="associatedtype trait-impl"><a class="src rightside" href="https://docs.rs/palette/0.7.6/src/palette/cast/packed.rs.html#117">Source</a><a href="#associatedtype.Array-3" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Array" class="associatedtype">Array</a> = <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.array.html">[T; N]</a></h4></section></div></details><details class="toggle implementors-toggle"><summary><section id="impl-ArrayCast-for-Luma%3CS,+T%3E" class="impl"><a class="src rightside" href="https://docs.rs/palette/0.7.6/src/palette/luma/luma.rs.html#33">Source</a><a href="#impl-ArrayCast-for-Luma%3CS,+T%3E" class="anchor">§</a><h3 class="code-header">impl<S, T> <a class="trait" href="trait.ArrayCast.html" title="trait cosmic::cosmic_theme::palette::cast::ArrayCast">ArrayCast</a> for <a class="struct" href="../luma/struct.Luma.html" title="struct cosmic::cosmic_theme::palette::luma::Luma">Luma</a><S, T></h3></section></summary><div class="impl-items"><section id="associatedtype.Array-4" class="associatedtype trait-impl"><a class="src rightside" href="https://docs.rs/palette/0.7.6/src/palette/luma/luma.rs.html#33">Source</a><a href="#associatedtype.Array-4" class="anchor">§</a><h4 class="code-header">type <a href="#associatedtype.Array" class="associatedtype">Array</a> = <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.array.html">[T; 1]</a></h4></section></div></details><details class="toggle implementors-toggle"><summary><section id="impl-ArrayCast-for-Rgb%3CS,+T%3E" class="impl"><a class="src rightside" href="https://docs.rs/palette/0.7.6/src/palett
|