github-actions[bot]
97 lines
19 KiB
HTML
97 lines
19 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="Implementation of functionality for `PyByteArray`."><title>PyByteArrayMethods in pyo3::prelude - 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="pyo3" data-themes="" data-resource-suffix="" data-rustdoc-version="1.85.1 (4eb161250 2025-03-15)" data-channel="1.85.1" data-search-js="search-75f5ac3e.js" data-settings-js="settings-0f613d39.js" ><script src="../../static.files/storage-59e33391.js"></script><script defer src="sidebar-items.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 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="../../pyo3/index.html">pyo3</a><span class="version">0.24.1</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">PyByte<wbr>Array<wbr>Methods</a></h2><h3><a href="#required-methods">Required Methods</a></h3><ul class="block"><li><a href="#tymethod.as_bytes" title="as_bytes">as_bytes</a></li><li><a href="#tymethod.as_bytes_mut" title="as_bytes_mut">as_bytes_mut</a></li><li><a href="#tymethod.data" title="data">data</a></li><li><a href="#tymethod.is_empty" title="is_empty">is_empty</a></li><li><a href="#tymethod.len" title="len">len</a></li><li><a href="#tymethod.resize" title="resize">resize</a></li><li><a href="#tymethod.to_vec" title="to_vec">to_vec</a></li></ul><h3><a href="#implementors">Implementors</a></h3></section><div id="rustdoc-modnav"><h2><a href="index.html">In pyo3::<wbr>prelude</a></h2></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"><span class="rustdoc-breadcrumbs"><a href="../index.html">pyo3</a>::<wbr><a href="index.html">prelude</a></span><h1>Trait <span class="trait">PyByteArrayMethods</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/pyo3/types/bytearray.rs.html#125-271">Source</a> </span></div><pre class="rust item-decl"><code>pub trait PyByteArrayMethods<'py>: Sealed {
|
||
// Required methods
|
||
fn <a href="#tymethod.len" class="fn">len</a>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.usize.html">usize</a>;
|
||
<span class="item-spacer"></span> fn <a href="#tymethod.is_empty" class="fn">is_empty</a>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.bool.html">bool</a>;
|
||
<span class="item-spacer"></span> fn <a href="#tymethod.data" class="fn">data</a>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.pointer.html">*mut </a><a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.u8.html">u8</a>;
|
||
<span class="item-spacer"></span> unsafe fn <a href="#tymethod.as_bytes" class="fn">as_bytes</a>(&self) -> &[<a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.u8.html">u8</a>] <a href="#" class="tooltip" data-notable-ty="&[u8]">ⓘ</a>;
|
||
<span class="item-spacer"></span> unsafe fn <a href="#tymethod.as_bytes_mut" class="fn">as_bytes_mut</a>(&self) -> &mut [<a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.u8.html">u8</a>] <a href="#" class="tooltip" data-notable-ty="&mut [u8]">ⓘ</a>;
|
||
<span class="item-spacer"></span> fn <a href="#tymethod.to_vec" class="fn">to_vec</a>(&self) -> <a class="struct" href="https://doc.rust-lang.org/1.85.1/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a><<a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.u8.html">u8</a>> <a href="#" class="tooltip" data-notable-ty="Vec<u8>">ⓘ</a>;
|
||
<span class="item-spacer"></span> fn <a href="#tymethod.resize" class="fn">resize</a>(&self, len: <a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.usize.html">usize</a>) -> <a class="type" href="../type.PyResult.html" title="type pyo3::PyResult">PyResult</a><<a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.unit.html">()</a>>;
|
||
}</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Implementation of functionality for <a href="../types/struct.PyByteArray.html" title="struct pyo3::types::PyByteArray"><code>PyByteArray</code></a>.</p>
|
||
<p>These methods are defined for the <code>Bound<'py, PyByteArray></code> smart pointer, so to use method call
|
||
syntax these methods are separated into a trait, because stable Rust does not yet support
|
||
<code>arbitrary_self_types</code>.</p>
|
||
</div></details><h2 id="required-methods" class="section-header">Required Methods<a href="#required-methods" class="anchor">§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="tymethod.len" class="method"><a class="src rightside" href="../../src/pyo3/types/bytearray.rs.html#127">Source</a><h4 class="code-header">fn <a href="#tymethod.len" class="fn">len</a>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.usize.html">usize</a></h4></section></summary><div class="docblock"><p>Gets the length of the bytearray.</p>
|
||
</div></details><details class="toggle method-toggle" open><summary><section id="tymethod.is_empty" class="method"><a class="src rightside" href="../../src/pyo3/types/bytearray.rs.html#130">Source</a><h4 class="code-header">fn <a href="#tymethod.is_empty" class="fn">is_empty</a>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.bool.html">bool</a></h4></section></summary><div class="docblock"><p>Checks if the bytearray is empty.</p>
|
||
</div></details><details class="toggle method-toggle" open><summary><section id="tymethod.data" class="method"><a class="src rightside" href="../../src/pyo3/types/bytearray.rs.html#137">Source</a><h4 class="code-header">fn <a href="#tymethod.data" class="fn">data</a>(&self) -> <a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.pointer.html">*mut </a><a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.u8.html">u8</a></h4></section></summary><div class="docblock"><p>Gets the start of the buffer containing the contents of the bytearray.</p>
|
||
<h5 id="safety"><a class="doc-anchor" href="#safety">§</a>Safety</h5>
|
||
<p>See the safety requirements of <a href="../types/trait.PyByteArrayMethods.html#tymethod.as_bytes" title="method pyo3::types::PyByteArrayMethods::as_bytes"><code>PyByteArrayMethods::as_bytes</code></a> and <a href="../types/trait.PyByteArrayMethods.html#tymethod.as_bytes_mut" title="method pyo3::types::PyByteArrayMethods::as_bytes_mut"><code>PyByteArrayMethods::as_bytes_mut</code></a>.</p>
|
||
</div></details><details class="toggle method-toggle" open><summary><section id="tymethod.as_bytes" class="method"><a class="src rightside" href="../../src/pyo3/types/bytearray.rs.html#234">Source</a><h4 class="code-header">unsafe fn <a href="#tymethod.as_bytes" class="fn">as_bytes</a>(&self) -> &[<a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.u8.html">u8</a>] <a href="#" class="tooltip" data-notable-ty="&[u8]">ⓘ</a></h4></section></summary><div class="docblock"><p>Extracts a slice of the <code>ByteArray</code>’s entire buffer.</p>
|
||
<h5 id="safety-1"><a class="doc-anchor" href="#safety-1">§</a>Safety</h5>
|
||
<p>Mutation of the <code>bytearray</code> invalidates the slice. If it is used afterwards, the behavior is
|
||
undefined.</p>
|
||
<p>These mutations may occur in Python code as well as from Rust:</p>
|
||
<ul>
|
||
<li>Calling methods like <a href="../types/trait.PyByteArrayMethods.html#tymethod.as_bytes_mut" title="method pyo3::types::PyByteArrayMethods::as_bytes_mut"><code>PyByteArrayMethods::as_bytes_mut</code></a> and <a href="../types/trait.PyByteArrayMethods.html#tymethod.resize" title="method pyo3::types::PyByteArrayMethods::resize"><code>PyByteArrayMethods::resize</code></a> will
|
||
invalidate the slice.</li>
|
||
<li>Actions like dropping objects or raising exceptions can invoke <code>__del__</code>methods or signal
|
||
handlers, which may execute arbitrary Python code. This means that if Python code has a
|
||
reference to the <code>bytearray</code> you cannot safely use the vast majority of PyO3’s API whilst
|
||
using the slice.</li>
|
||
</ul>
|
||
<p>As a result, this slice should only be used for short-lived operations without executing any
|
||
Python code, such as copying into a Vec.</p>
|
||
<h5 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h5>
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>pyo3::prelude::<span class="kw-2">*</span>;
|
||
<span class="kw">use </span>pyo3::exceptions::PyRuntimeError;
|
||
<span class="kw">use </span>pyo3::types::PyByteArray;
|
||
|
||
<span class="attr">#[pyfunction]
|
||
</span><span class="kw">fn </span>a_valid_function(bytes: <span class="kw-2">&</span>Bound<<span class="lifetime">'_</span>, PyByteArray>) -> PyResult<()> {
|
||
<span class="kw">let </span>section = {
|
||
<span class="comment">// SAFETY: We promise to not let the interpreter regain control
|
||
// or invoke any PyO3 APIs while using the slice.
|
||
</span><span class="kw">let </span>slice = <span class="kw">unsafe </span>{ bytes.as_bytes() };
|
||
|
||
<span class="comment">// Copy only a section of `bytes` while avoiding
|
||
// `to_vec` which copies the entire thing.
|
||
</span><span class="kw">let </span>section = slice
|
||
.get(<span class="number">6</span>..<span class="number">11</span>)
|
||
.ok_or_else(|| PyRuntimeError::new_err(<span class="string">"input is not long enough"</span>))<span class="question-mark">?</span>;
|
||
Vec::from(section)
|
||
};
|
||
|
||
<span class="comment">// Now we can do things with `section` and call PyO3 APIs again.
|
||
// ...
|
||
|
||
</span><span class="prelude-val">Ok</span>(())
|
||
}</code></pre></div>
|
||
<h5 id="incorrect-usage"><a class="doc-anchor" href="#incorrect-usage">§</a>Incorrect usage</h5>
|
||
<p>The following <code>bug</code> function is unsound ⚠️</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code>
|
||
<span class="attr">#[pyfunction]
|
||
</span><span class="kw">fn </span>bug(py: Python<<span class="lifetime">'_</span>>, bytes: <span class="kw-2">&</span>Bound<<span class="lifetime">'_</span>, PyByteArray>) {
|
||
<span class="kw">let </span>slice = <span class="kw">unsafe </span>{ bytes.as_bytes() };
|
||
|
||
<span class="comment">// This explicitly yields control back to the Python interpreter...
|
||
// ...but it's not always this obvious. Many things do this implicitly.
|
||
</span>py.allow_threads(|| {
|
||
<span class="comment">// Python code could be mutating through its handle to `bytes`,
|
||
// which makes reading it a data race, which is undefined behavior.
|
||
</span><span class="macro">println!</span>(<span class="string">"{:?}"</span>, slice[<span class="number">0</span>]);
|
||
});
|
||
|
||
<span class="comment">// Python code might have mutated it, so we can not rely on the slice
|
||
// remaining valid. As such this is also undefined behavior.
|
||
</span><span class="macro">println!</span>(<span class="string">"{:?}"</span>, slice[<span class="number">0</span>]);
|
||
}</code></pre></div>
|
||
</div></details><details class="toggle method-toggle" open><summary><section id="tymethod.as_bytes_mut" class="method"><a class="src rightside" href="../../src/pyo3/types/bytearray.rs.html#244">Source</a><h4 class="code-header">unsafe fn <a href="#tymethod.as_bytes_mut" class="fn">as_bytes_mut</a>(&self) -> &mut [<a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.u8.html">u8</a>] <a href="#" class="tooltip" data-notable-ty="&mut [u8]">ⓘ</a></h4></section></summary><div class="docblock"><p>Extracts a mutable slice of the <code>ByteArray</code>’s entire buffer.</p>
|
||
<h5 id="safety-2"><a class="doc-anchor" href="#safety-2">§</a>Safety</h5>
|
||
<p>Any other accesses of the <code>bytearray</code>’s buffer invalidate the slice. If it is used
|
||
afterwards, the behavior is undefined. The safety requirements of <a href="../types/trait.PyByteArrayMethods.html#tymethod.as_bytes" title="method pyo3::types::PyByteArrayMethods::as_bytes"><code>PyByteArrayMethods::as_bytes</code></a>
|
||
apply to this function as well.</p>
|
||
</div></details><details class="toggle method-toggle" open><summary><section id="tymethod.to_vec" class="method"><a class="src rightside" href="../../src/pyo3/types/bytearray.rs.html#264">Source</a><h4 class="code-header">fn <a href="#tymethod.to_vec" class="fn">to_vec</a>(&self) -> <a class="struct" href="https://doc.rust-lang.org/1.85.1/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a><<a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.u8.html">u8</a>> <a href="#" class="tooltip" data-notable-ty="Vec<u8>">ⓘ</a></h4></section></summary><div class="docblock"><p>Copies the contents of the bytearray to a Rust vector.</p>
|
||
<h5 id="examples-1"><a class="doc-anchor" href="#examples-1">§</a>Examples</h5>
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let </span>bytearray = PyByteArray::new(py, <span class="string">b"Hello World."</span>);
|
||
<span class="kw">let </span><span class="kw-2">mut </span>copied_message = bytearray.to_vec();
|
||
<span class="macro">assert_eq!</span>(<span class="string">b"Hello World."</span>, copied_message.as_slice());
|
||
|
||
copied_message[<span class="number">11</span>] = <span class="string">b'!'</span>;
|
||
<span class="macro">assert_eq!</span>(<span class="string">b"Hello World!"</span>, copied_message.as_slice());
|
||
|
||
<span class="macro">pyo3::py_run!</span>(py, bytearray, <span class="string">"assert bytearray == b'Hello World.'"</span>);</code></pre></div>
|
||
</div></details><details class="toggle method-toggle" open><summary><section id="tymethod.resize" class="method"><a class="src rightside" href="../../src/pyo3/types/bytearray.rs.html#270">Source</a><h4 class="code-header">fn <a href="#tymethod.resize" class="fn">resize</a>(&self, len: <a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.usize.html">usize</a>) -> <a class="type" href="../type.PyResult.html" title="type pyo3::PyResult">PyResult</a><<a class="primitive" href="https://doc.rust-lang.org/1.85.1/std/primitive.unit.html">()</a>></h4></section></summary><div class="docblock"><p>Resizes the bytearray object to the new length <code>len</code>.</p>
|
||
<p>Note that this will invalidate any pointers obtained by <a href="../types/trait.PyByteArrayMethods.html#tymethod.data" title="method pyo3::types::PyByteArrayMethods::data">PyByteArrayMethods::data</a>, as well as
|
||
any (unsafe) slices obtained from <a href="../types/trait.PyByteArrayMethods.html#tymethod.as_bytes" title="method pyo3::types::PyByteArrayMethods::as_bytes">PyByteArrayMethods::as_bytes</a> and <a href="../types/trait.PyByteArrayMethods.html#tymethod.as_bytes_mut" title="method pyo3::types::PyByteArrayMethods::as_bytes_mut">PyByteArrayMethods::as_bytes_mut</a>.</p>
|
||
</div></details></div><h2 id="implementors" class="section-header">Implementors<a href="#implementors" class="anchor">§</a></h2><div id="implementors-list"><section id="impl-PyByteArrayMethods%3C'py%3E-for-Bound%3C'py,+PyByteArray%3E" class="impl"><a class="src rightside" href="../../src/pyo3/types/bytearray.rs.html#273-311">Source</a><a href="#impl-PyByteArrayMethods%3C'py%3E-for-Bound%3C'py,+PyByteArray%3E" class="anchor">§</a><h3 class="code-header">impl<'py> <a class="trait" href="../types/trait.PyByteArrayMethods.html" title="trait pyo3::types::PyByteArrayMethods">PyByteArrayMethods</a><'py> for <a class="struct" href="../struct.Bound.html" title="struct pyo3::Bound">Bound</a><'py, <a class="struct" href="../types/struct.PyByteArray.html" title="struct pyo3::types::PyByteArray">PyByteArray</a>></h3></section></div><script src="../../trait.impl/pyo3/types/bytearray/trait.PyByteArrayMethods.js" async></script><script type="text/json" id="notable-traits-data">{"&[u8]":"<h3>Notable traits for <code>&[<a class=\"primitive\" href=\"https://doc.rust-lang.org/1.85.1/std/primitive.u8.html\">u8</a>]</code></h3><pre><code><div class=\"where\">impl <a class=\"trait\" href=\"https://doc.rust-lang.org/1.85.1/std/io/trait.Read.html\" title=\"trait std::io::Read\">Read</a> for &[<a class=\"primitive\" href=\"https://doc.rust-lang.org/1.85.1/std/primitive.u8.html\">u8</a>]</div>","&mut [u8]":"<h3>Notable traits for <code>&mut [<a class=\"primitive\" href=\"https://doc.rust-lang.org/1.85.1/std/primitive.u8.html\">u8</a>]</code></h3><pre><code><div class=\"where\">impl <a class=\"trait\" href=\"https://doc.rust-lang.org/1.85.1/std/io/trait.Write.html\" title=\"trait std::io::Write\">Write</a> for &mut [<a class=\"primitive\" href=\"https://doc.rust-lang.org/1.85.1/std/primitive.u8.html\">u8</a>]</div>","Vec<u8>":"<h3>Notable traits for <code><a class=\"struct\" href=\"https://doc.rust-lang.org/1.85.1/alloc/vec/struct.Vec.html\" title=\"struct alloc::vec::Vec\">Vec</a><<a class=\"primitive\" href=\"https://doc.rust-lang.org/1.85.1/std/primitive.u8.html\">u8</a>, A></code></h3><pre><code><div class=\"where\">impl<A> <a class=\"trait\" href=\"https://doc.rust-lang.org/1.85.1/std/io/trait.Write.html\" title=\"trait std::io::Write\">Write</a> for <a class=\"struct\" href=\"https://doc.rust-lang.org/1.85.1/alloc/vec/struct.Vec.html\" title=\"struct alloc::vec::Vec\">Vec</a><<a class=\"primitive\" href=\"https://doc.rust-lang.org/1.85.1/std/primitive.u8.html\">u8</a>, A><div class=\"where\">where\n A: <a class=\"trait\" href=\"https://doc.rust-lang.org/1.85.1/core/alloc/trait.Allocator.html\" title=\"trait core::alloc::Allocator\">Allocator</a>,</div></div>"}</script></section></div></main></body></html> |