sascha
/
difftastic
mirror of https://github.com/Wilfred/difftastic/
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
difftastic/rustdoc/bstr/trait.ByteVec.html

494 lines
63 KiB
HTML
Raw Permalink Blame History Unescape Escape

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

<!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 trait that extends `Vec&lt;u8&gt;` with string oriented methods."><title>ByteVec in bstr - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><link rel="stylesheet" href="../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../static.files/rustdoc-ac92e1bbe349e143.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="bstr" data-themes="" data-resource-suffix="" data-rustdoc-version="1.76.0 (07dca489a 2024-02-04)" data-channel="1.76.0" data-search-js="search-2b6ce74ff89ae146.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../static.files/storage-f2adc0d6ca4d09fb.js"></script><script defer src="sidebar-items.js"></script><script defer src="../static.files/main-305769736d49e732.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-feafe1bb7466e4bd.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-16x16-8b506e7a72182f1c.png"><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-2c020d218678b618.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">&#9776;</button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../bstr/index.html">bstr</a><span class="version">1.9.1</span></h2></div><h2 class="location"><a href="#">ByteVec</a></h2><div class="sidebar-elems"><section><h3><a href="#provided-methods">Provided Methods</a></h3><ul class="block"><li><a href="#method.drain_bytes">drain_bytes</a></li><li><a href="#method.from_os_str_lossy">from_os_str_lossy</a></li><li><a href="#method.from_os_string">from_os_string</a></li><li><a href="#method.from_path_buf">from_path_buf</a></li><li><a href="#method.from_path_lossy">from_path_lossy</a></li><li><a href="#method.from_slice">from_slice</a></li><li><a href="#method.insert_char">insert_char</a></li><li><a href="#method.insert_str">insert_str</a></li><li><a href="#method.into_os_string">into_os_string</a></li><li><a href="#method.into_os_string_lossy">into_os_string_lossy</a></li><li><a href="#method.into_path_buf">into_path_buf</a></li><li><a href="#method.into_path_buf_lossy">into_path_buf_lossy</a></li><li><a href="#method.into_string">into_string</a></li><li><a href="#method.into_string_lossy">into_string_lossy</a></li><li><a href="#method.into_string_unchecked">into_string_unchecked</a></li><li><a href="#method.pop_byte">pop_byte</a></li><li><a href="#method.pop_char">pop_char</a></li><li><a href="#method.push_byte">push_byte</a></li><li><a href="#method.push_char">push_char</a></li><li><a href="#method.push_str">push_str</a></li><li><a href="#method.remove_char">remove_char</a></li><li><a href="#method.replace_range">replace_range</a></li><li><a href="#method.unescape_bytes">unescape_bytes</a></li></ul><h3><a href="#foreign-impls">Implementations on Foreign Types</a></h3><ul class="block"><li><a href="#impl-ByteVec-for-Vec%3Cu8%3E">Vec&lt;u8&gt;</a></li></ul><h3><a href="#object-safety">Object Safety</a></h3><h3><a href="#implementors">Implementors</a></h3></section><h2><a href="index.html">In crate bstr</a></h2></div></nav><div class="sidebar-resizer"></div>
<main><div class="width-limiter"><nav class="sub"><form class="search-form"><span></span><div id="sidebar-button" tabindex="-1"><a href="../bstr/all.html" title="show sidebar"></a></div><input class="search-input" name="search" aria-label="Run search in the documentation" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><div id="help-button" tabindex="-1"><a href="../help.html" title="help">?</a></div><div id="settings-menu" tabindex="-1"><a href="../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1>Trait <a href="index.html">bstr</a>::<wbr><a class="trait" href="#">ByteVec</a><button id="copy-path" title="Copy item path to clipboard"><img src="../static.files/clipboard-7571035ce49a181d.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="src" href="../src/bstr/ext_vec.rs.html#123-1000">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><pre class="rust item-decl"><code>pub trait ByteVec: Sealed {
<details class="toggle type-contents-toggle"><summary class="hideme"><span>Show 23 methods</span></summary> // Provided methods
fn <a href="#method.from_slice" class="fn">from_slice</a>&lt;B: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;[<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>]&gt;&gt;(bytes: B) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>&gt; <a href="#" class="tooltip" data-notable-ty="Vec&lt;u8&gt;">ⓘ</a> { ... }
<span class="item-spacer"></span> fn <a href="#method.from_os_string" class="fn">from_os_string</a>(os_str: <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/ffi/os_str/struct.OsString.html" title="struct std::ffi::os_str::OsString">OsString</a>) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>&gt;, <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/ffi/os_str/struct.OsString.html" title="struct std::ffi::os_str::OsString">OsString</a>&gt; { ... }
<span class="item-spacer"></span> fn <a href="#method.from_os_str_lossy" class="fn">from_os_str_lossy</a>&lt;'a&gt;(os_str: &amp;'a <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/ffi/os_str/struct.OsStr.html" title="struct std::ffi::os_str::OsStr">OsStr</a>) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/alloc/borrow/enum.Cow.html" title="enum alloc::borrow::Cow">Cow</a>&lt;'a, [<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>]&gt; { ... }
<span class="item-spacer"></span> fn <a href="#method.from_path_buf" class="fn">from_path_buf</a>(path: <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/path/struct.PathBuf.html" title="struct std::path::PathBuf">PathBuf</a>) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>&gt;, <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/path/struct.PathBuf.html" title="struct std::path::PathBuf">PathBuf</a>&gt; { ... }
<span class="item-spacer"></span> fn <a href="#method.from_path_lossy" class="fn">from_path_lossy</a>&lt;'a&gt;(path: &amp;'a <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/path/struct.Path.html" title="struct std::path::Path">Path</a>) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/alloc/borrow/enum.Cow.html" title="enum alloc::borrow::Cow">Cow</a>&lt;'a, [<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>]&gt; { ... }
<span class="item-spacer"></span> fn <a href="#method.unescape_bytes" class="fn">unescape_bytes</a>&lt;S: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.str.html">str</a>&gt;&gt;(escaped: S) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>&gt; <a href="#" class="tooltip" data-notable-ty="Vec&lt;u8&gt;">ⓘ</a> { ... }
<span class="item-spacer"></span> fn <a href="#method.push_byte" class="fn">push_byte</a>(&amp;mut self, byte: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>) { ... }
<span class="item-spacer"></span> fn <a href="#method.push_char" class="fn">push_char</a>(&amp;mut self, ch: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.char.html">char</a>) { ... }
<span class="item-spacer"></span> fn <a href="#method.push_str" class="fn">push_str</a>&lt;B: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;[<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>]&gt;&gt;(&amp;mut self, bytes: B) { ... }
<span class="item-spacer"></span> fn <a href="#method.into_string" class="fn">into_string</a>(self) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/string/struct.String.html" title="struct alloc::string::String">String</a>, <a class="struct" href="struct.FromUtf8Error.html" title="struct bstr::FromUtf8Error">FromUtf8Error</a>&gt;
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
<span class="item-spacer"></span> fn <a href="#method.into_string_lossy" class="fn">into_string_lossy</a>(self) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/string/struct.String.html" title="struct alloc::string::String">String</a>
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
<span class="item-spacer"></span> unsafe fn <a href="#method.into_string_unchecked" class="fn">into_string_unchecked</a>(self) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/string/struct.String.html" title="struct alloc::string::String">String</a>
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
<span class="item-spacer"></span> fn <a href="#method.into_os_string" class="fn">into_os_string</a>(self) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="struct" href="https://doc.rust-lang.org/1.76.0/std/ffi/os_str/struct.OsString.html" title="struct std::ffi::os_str::OsString">OsString</a>, <a class="struct" href="struct.FromUtf8Error.html" title="struct bstr::FromUtf8Error">FromUtf8Error</a>&gt;
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
<span class="item-spacer"></span> fn <a href="#method.into_os_string_lossy" class="fn">into_os_string_lossy</a>(self) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/ffi/os_str/struct.OsString.html" title="struct std::ffi::os_str::OsString">OsString</a>
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
<span class="item-spacer"></span> fn <a href="#method.into_path_buf" class="fn">into_path_buf</a>(self) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="struct" href="https://doc.rust-lang.org/1.76.0/std/path/struct.PathBuf.html" title="struct std::path::PathBuf">PathBuf</a>, <a class="struct" href="struct.FromUtf8Error.html" title="struct bstr::FromUtf8Error">FromUtf8Error</a>&gt;
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
<span class="item-spacer"></span> fn <a href="#method.into_path_buf_lossy" class="fn">into_path_buf_lossy</a>(self) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/path/struct.PathBuf.html" title="struct std::path::PathBuf">PathBuf</a>
<span class="where">where Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
<span class="item-spacer"></span> fn <a href="#method.pop_byte" class="fn">pop_byte</a>(&amp;mut self) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>&gt; { ... }
<span class="item-spacer"></span> fn <a href="#method.pop_char" class="fn">pop_char</a>(&amp;mut self) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.char.html">char</a>&gt; { ... }
<span class="item-spacer"></span> fn <a href="#method.remove_char" class="fn">remove_char</a>(&amp;mut self, at: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.char.html">char</a> { ... }
<span class="item-spacer"></span> fn <a href="#method.insert_char" class="fn">insert_char</a>(&amp;mut self, at: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a>, ch: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.char.html">char</a>) { ... }
<span class="item-spacer"></span> fn <a href="#method.insert_str" class="fn">insert_str</a>&lt;B: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;[<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>]&gt;&gt;(&amp;mut self, at: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a>, bytes: B) { ... }
<span class="item-spacer"></span> fn <a href="#method.replace_range" class="fn">replace_range</a>&lt;R, B&gt;(&amp;mut self, range: R, replace_with: B)
<span class="where">where R: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/ops/range/trait.RangeBounds.html" title="trait core::ops::range::RangeBounds">RangeBounds</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a>&gt;,
B: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;[<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>]&gt;</span> { ... }
<span class="item-spacer"></span> fn <a href="#method.drain_bytes" class="fn">drain_bytes</a>&lt;R&gt;(&amp;mut self, range: R) -&gt; <a class="struct" href="struct.DrainBytes.html" title="struct bstr::DrainBytes">DrainBytes</a>&lt;'_&gt; <a href="#" class="tooltip" data-notable-ty="DrainBytes&lt;&#39;_&gt;">ⓘ</a>
<span class="where">where R: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/ops/range/trait.RangeBounds.html" title="trait core::ops::range::RangeBounds">RangeBounds</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a>&gt;</span> { ... }
</details>}</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>A trait that extends <code>Vec&lt;u8&gt;</code> with string oriented methods.</p>
<p>Note that when using the constructor methods, such as
<code>ByteVec::from_slice</code>, one should actually call them using the concrete
type. For example:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::{B, ByteVec};
<span class="kw">let </span>s = Vec::from_slice(<span class="string">b"abc"</span>); <span class="comment">// NOT ByteVec::from_slice("...")
</span><span class="macro">assert_eq!</span>(s, B(<span class="string">"abc"</span>));</code></pre></div>
<p>This trait is sealed and cannot be implemented outside of <code>bstr</code>.</p>
</div></details><h2 id="provided-methods" class="section-header">Provided Methods<a href="#provided-methods" class="anchor">§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="method.from_slice" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#157-159">source</a><h4 class="code-header">fn <a href="#method.from_slice" class="fn">from_slice</a>&lt;B: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;[<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>]&gt;&gt;(bytes: B) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>&gt; <a href="#" class="tooltip" data-notable-ty="Vec&lt;u8&gt;">ⓘ</a></h4></section></summary><div class="docblock"><p>Create a new owned byte string from the given byte slice.</p>
<h5 id="examples"><a href="#examples">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::{B, ByteVec};
<span class="kw">let </span>s = Vec::from_slice(<span class="string">b"abc"</span>);
<span class="macro">assert_eq!</span>(s, B(<span class="string">"abc"</span>));</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.from_os_string" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#182-198">source</a><h4 class="code-header">fn <a href="#method.from_os_string" class="fn">from_os_string</a>(os_str: <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/ffi/os_str/struct.OsString.html" title="struct std::ffi::os_str::OsString">OsString</a>) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>&gt;, <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/ffi/os_str/struct.OsString.html" title="struct std::ffi::os_str::OsString">OsString</a>&gt;</h4></section></summary><div class="docblock"><p>Create a new byte string from an owned OS string.</p>
<p>When the underlying bytes of OS strings are accessible, then this
always succeeds and is zero cost. Otherwise, this returns the given
<code>OsString</code> if it is not valid UTF-8.</p>
<h5 id="examples-1"><a href="#examples-1">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>std::ffi::OsString;
<span class="kw">use </span>bstr::{B, ByteVec};
<span class="kw">let </span>os_str = OsString::from(<span class="string">"foo"</span>);
<span class="kw">let </span>bs = Vec::from_os_string(os_str).expect(<span class="string">"valid UTF-8"</span>);
<span class="macro">assert_eq!</span>(bs, B(<span class="string">"foo"</span>));</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.from_os_str_lossy" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#223-242">source</a><h4 class="code-header">fn <a href="#method.from_os_str_lossy" class="fn">from_os_str_lossy</a>&lt;'a&gt;(os_str: &amp;'a <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/ffi/os_str/struct.OsStr.html" title="struct std::ffi::os_str::OsStr">OsStr</a>) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/alloc/borrow/enum.Cow.html" title="enum alloc::borrow::Cow">Cow</a>&lt;'a, [<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>]&gt;</h4></section></summary><div class="docblock"><p>Lossily create a new byte string from an OS string slice.</p>
<p>When the underlying bytes of OS strings are accessible, then this is
zero cost and always returns a slice. Otherwise, a UTF-8 check is
performed and if the given OS string is not valid UTF-8, then it is
lossily decoded into valid UTF-8 (with invalid bytes replaced by the
Unicode replacement codepoint).</p>
<h5 id="examples-2"><a href="#examples-2">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>std::ffi::OsStr;
<span class="kw">use </span>bstr::{B, ByteVec};
<span class="kw">let </span>os_str = OsStr::new(<span class="string">"foo"</span>);
<span class="kw">let </span>bs = Vec::from_os_str_lossy(os_str);
<span class="macro">assert_eq!</span>(bs, B(<span class="string">"foo"</span>));</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.from_path_buf" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#265-267">source</a><h4 class="code-header">fn <a href="#method.from_path_buf" class="fn">from_path_buf</a>(path: <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/path/struct.PathBuf.html" title="struct std::path::PathBuf">PathBuf</a>) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>&gt;, <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/path/struct.PathBuf.html" title="struct std::path::PathBuf">PathBuf</a>&gt;</h4></section></summary><div class="docblock"><p>Create a new byte string from an owned file path.</p>
<p>When the underlying bytes of paths are accessible, then this always
succeeds and is zero cost. Otherwise, this returns the given <code>PathBuf</code>
if it is not valid UTF-8.</p>
<h5 id="examples-3"><a href="#examples-3">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>std::path::PathBuf;
<span class="kw">use </span>bstr::{B, ByteVec};
<span class="kw">let </span>path = PathBuf::from(<span class="string">"foo"</span>);
<span class="kw">let </span>bs = Vec::from_path_buf(path).expect(<span class="string">"must be valid UTF-8"</span>);
<span class="macro">assert_eq!</span>(bs, B(<span class="string">"foo"</span>));</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.from_path_lossy" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#292-294">source</a><h4 class="code-header">fn <a href="#method.from_path_lossy" class="fn">from_path_lossy</a>&lt;'a&gt;(path: &amp;'a <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/path/struct.Path.html" title="struct std::path::Path">Path</a>) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/alloc/borrow/enum.Cow.html" title="enum alloc::borrow::Cow">Cow</a>&lt;'a, [<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>]&gt;</h4></section></summary><div class="docblock"><p>Lossily create a new byte string from a file path.</p>
<p>When the underlying bytes of paths are accessible, then this is
zero cost and always returns a slice. Otherwise, a UTF-8 check is
performed and if the given path is not valid UTF-8, then it is lossily
decoded into valid UTF-8 (with invalid bytes replaced by the Unicode
replacement codepoint).</p>
<h5 id="examples-4"><a href="#examples-4">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>std::path::Path;
<span class="kw">use </span>bstr::{B, ByteVec};
<span class="kw">let </span>path = Path::new(<span class="string">"foo"</span>);
<span class="kw">let </span>bs = Vec::from_path_lossy(path);
<span class="macro">assert_eq!</span>(bs, B(<span class="string">"foo"</span>));</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.unescape_bytes" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#392-395">source</a><h4 class="code-header">fn <a href="#method.unescape_bytes" class="fn">unescape_bytes</a>&lt;S: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.str.html">str</a>&gt;&gt;(escaped: S) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>&gt; <a href="#" class="tooltip" data-notable-ty="Vec&lt;u8&gt;">ⓘ</a></h4></section></summary><div class="docblock"><p>Unescapes the given string into its raw bytes.</p>
<p>This looks for the escape sequences <code>\xNN</code>, <code>\0</code>, <code>\r</code>, <code>\n</code>, <code>\t</code>
and <code>\</code> and translates them into their corresponding unescaped form.</p>
<p>Incomplete escape sequences or things that look like escape sequences
but are not (for example, <code>\i</code> or <code>\xYZ</code>) are passed through literally.</p>
<p>This is the dual of <a href="trait.ByteSlice.html#method.escape_bytes" title="method bstr::ByteSlice::escape_bytes"><code>ByteSlice::escape_bytes</code></a>.</p>
<p>Note that the zero or NUL byte may be represented as either <code>\0</code> or
<code>\x00</code>. Both will be unescaped into the zero byte.</p>
<h5 id="examples-5"><a href="#examples-5">Examples</a></h5>
<p>This shows basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::{B, BString, ByteVec};
<span class="macro">assert_eq!</span>(
BString::from(<span class="string">b"foo\xFFbar"</span>),
Vec::unescape_bytes(<span class="string">r"foo\xFFbar"</span>),
);
<span class="macro">assert_eq!</span>(
BString::from(<span class="string">b"foo\nbar"</span>),
Vec::unescape_bytes(<span class="string">r"foo\nbar"</span>),
);
<span class="macro">assert_eq!</span>(
BString::from(<span class="string">b"foo\tbar"</span>),
Vec::unescape_bytes(<span class="string">r"foo\tbar"</span>),
);
<span class="macro">assert_eq!</span>(
BString::from(<span class="string">b"foo\\bar"</span>),
Vec::unescape_bytes(<span class="string">r"foo\\bar"</span>),
);
<span class="macro">assert_eq!</span>(
BString::from(<span class="string">"foo☃bar"</span>),
Vec::unescape_bytes(<span class="string">r"foo☃bar"</span>),
);
</code></pre></div>
<p>This shows some examples of how incomplete or “incorrect” escape
sequences get passed through literally.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::{B, BString, ByteVec};
<span class="comment">// Show some incomplete escape sequences.
</span><span class="macro">assert_eq!</span>(
BString::from(<span class="string">br"\"</span>),
Vec::unescape_bytes(<span class="string">r"\"</span>),
);
<span class="macro">assert_eq!</span>(
BString::from(<span class="string">br"\"</span>),
Vec::unescape_bytes(<span class="string">r"\\"</span>),
);
<span class="macro">assert_eq!</span>(
BString::from(<span class="string">br"\x"</span>),
Vec::unescape_bytes(<span class="string">r"\x"</span>),
);
<span class="macro">assert_eq!</span>(
BString::from(<span class="string">br"\xA"</span>),
Vec::unescape_bytes(<span class="string">r"\xA"</span>),
);
<span class="comment">// And now some that kind of look like escape
// sequences, but aren't.
</span><span class="macro">assert_eq!</span>(
BString::from(<span class="string">br"\xZ"</span>),
Vec::unescape_bytes(<span class="string">r"\xZ"</span>),
);
<span class="macro">assert_eq!</span>(
BString::from(<span class="string">br"\xZZ"</span>),
Vec::unescape_bytes(<span class="string">r"\xZZ"</span>),
);
<span class="macro">assert_eq!</span>(
BString::from(<span class="string">br"\i"</span>),
Vec::unescape_bytes(<span class="string">r"\i"</span>),
);
<span class="macro">assert_eq!</span>(
BString::from(<span class="string">br"\u"</span>),
Vec::unescape_bytes(<span class="string">r"\u"</span>),
);
<span class="macro">assert_eq!</span>(
BString::from(<span class="string">br"\u{2603}"</span>),
Vec::unescape_bytes(<span class="string">r"\u{2603}"</span>),
);
</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.push_byte" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#417-419">source</a><h4 class="code-header">fn <a href="#method.push_byte" class="fn">push_byte</a>(&amp;mut self, byte: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>)</h4></section></summary><div class="docblock"><p>Appends the given byte to the end of this byte string.</p>
<p>Note that this is equivalent to the generic <code>Vec::push</code> method. This
method is provided to permit callers to explicitly differentiate
between pushing bytes, codepoints and strings.</p>
<h5 id="examples-6"><a href="#examples-6">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span><span class="kw-2">mut </span>s = &lt;Vec&lt;u8&gt;&gt;::from(<span class="string">"abc"</span>);
s.push_byte(<span class="string">b'\xE2'</span>);
s.push_byte(<span class="string">b'\x98'</span>);
s.push_byte(<span class="string">b'\x83'</span>);
<span class="macro">assert_eq!</span>(s, <span class="string">"abc☃"</span>.as_bytes());</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.push_char" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#437-444">source</a><h4 class="code-header">fn <a href="#method.push_char" class="fn">push_char</a>(&amp;mut self, ch: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.char.html">char</a>)</h4></section></summary><div class="docblock"><p>Appends the given <code>char</code> to the end of this byte string.</p>
<h5 id="examples-7"><a href="#examples-7">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span><span class="kw-2">mut </span>s = &lt;Vec&lt;u8&gt;&gt;::from(<span class="string">"abc"</span>);
s.push_char(<span class="string">'1'</span>);
s.push_char(<span class="string">'2'</span>);
s.push_char(<span class="string">'3'</span>);
<span class="macro">assert_eq!</span>(s, <span class="string">"abc123"</span>.as_bytes());</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.push_str" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#462-464">source</a><h4 class="code-header">fn <a href="#method.push_str" class="fn">push_str</a>&lt;B: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;[<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>]&gt;&gt;(&amp;mut self, bytes: B)</h4></section></summary><div class="docblock"><p>Appends the given slice to the end of this byte string. This accepts
any type that be converted to a <code>&amp;[u8]</code>. This includes, but is not
limited to, <code>&amp;str</code>, <code>&amp;BStr</code>, and of course, <code>&amp;[u8]</code> itself.</p>
<h5 id="examples-8"><a href="#examples-8">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span><span class="kw-2">mut </span>s = &lt;Vec&lt;u8&gt;&gt;::from(<span class="string">"abc"</span>);
s.push_str(<span class="string">b"123"</span>);
<span class="macro">assert_eq!</span>(s, <span class="string">"abc123"</span>.as_bytes());</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.into_string" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#505-517">source</a><h4 class="code-header">fn <a href="#method.into_string" class="fn">into_string</a>(self) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/string/struct.String.html" title="struct alloc::string::String">String</a>, <a class="struct" href="struct.FromUtf8Error.html" title="struct bstr::FromUtf8Error">FromUtf8Error</a>&gt;<div class="where">where
Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Converts a <code>Vec&lt;u8&gt;</code> into a <code>String</code> if and only if this byte string is
valid UTF-8.</p>
<p>If it is not valid UTF-8, then a
<a href="struct.FromUtf8Error.html"><code>FromUtf8Error</code></a>
is returned. (This error can be used to examine why UTF-8 validation
failed, or to regain the original byte string.)</p>
<h5 id="examples-9"><a href="#examples-9">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span>bytes = Vec::from(<span class="string">"hello"</span>);
<span class="kw">let </span>string = bytes.into_string().unwrap();
<span class="macro">assert_eq!</span>(<span class="string">"hello"</span>, string);</code></pre></div>
<p>If this byte string is not valid UTF-8, then an error will be returned.
That error can then be used to inspect the location at which invalid
UTF-8 was found, or to regain the original byte string:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::{B, ByteVec};
<span class="kw">let </span>bytes = Vec::from_slice(<span class="string">b"foo\xFFbar"</span>);
<span class="kw">let </span>err = bytes.into_string().unwrap_err();
<span class="macro">assert_eq!</span>(err.utf8_error().valid_up_to(), <span class="number">3</span>);
<span class="macro">assert_eq!</span>(err.utf8_error().error_len(), <span class="prelude-val">Some</span>(<span class="number">1</span>));
<span class="comment">// At no point in this example is an allocation performed.
</span><span class="kw">let </span>bytes = Vec::from(err.into_vec());
<span class="macro">assert_eq!</span>(bytes, B(<span class="string">b"foo\xFFbar"</span>));</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.into_string_lossy" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#535-547">source</a><h4 class="code-header">fn <a href="#method.into_string_lossy" class="fn">into_string_lossy</a>(self) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/string/struct.String.html" title="struct alloc::string::String">String</a><div class="where">where
Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Lossily converts a <code>Vec&lt;u8&gt;</code> into a <code>String</code>. If this byte string
contains invalid UTF-8, then the invalid bytes are replaced with the
Unicode replacement codepoint.</p>
<h5 id="examples-10"><a href="#examples-10">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span>bytes = Vec::from_slice(<span class="string">b"foo\xFFbar"</span>);
<span class="kw">let </span>string = bytes.into_string_lossy();
<span class="macro">assert_eq!</span>(string, <span class="string">"foo\u{FFFD}bar"</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.into_string_unchecked" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#576-581">source</a><h4 class="code-header">unsafe fn <a href="#method.into_string_unchecked" class="fn">into_string_unchecked</a>(self) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/string/struct.String.html" title="struct alloc::string::String">String</a><div class="where">where
Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Unsafely convert this byte string into a <code>String</code>, without checking for
valid UTF-8.</p>
<h5 id="safety"><a href="#safety">Safety</a></h5>
<p>Callers <em>must</em> ensure that this byte string is valid UTF-8 before
calling this method. Converting a byte string into a <code>String</code> that is
not valid UTF-8 is considered undefined behavior.</p>
<p>This routine is useful in performance sensitive contexts where the
UTF-8 validity of the byte string is already known and it is
undesirable to pay the cost of an additional UTF-8 validation check
that <a href="#method.into_string"><code>into_string</code></a> performs.</p>
<h5 id="examples-11"><a href="#examples-11">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="comment">// SAFETY: This is safe because string literals are guaranteed to be
// valid UTF-8 by the Rust compiler.
</span><span class="kw">let </span>s = <span class="kw">unsafe </span>{ Vec::from(<span class="string">"☃βツ"</span>).into_string_unchecked() };
<span class="macro">assert_eq!</span>(<span class="string">"☃βツ"</span>, s);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.into_os_string" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#604-623">source</a><h4 class="code-header">fn <a href="#method.into_os_string" class="fn">into_os_string</a>(self) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="struct" href="https://doc.rust-lang.org/1.76.0/std/ffi/os_str/struct.OsString.html" title="struct std::ffi::os_str::OsString">OsString</a>, <a class="struct" href="struct.FromUtf8Error.html" title="struct bstr::FromUtf8Error">FromUtf8Error</a>&gt;<div class="where">where
Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Converts this byte string into an OS string, in place.</p>
<p>When OS strings can be constructed from arbitrary byte sequences, this
always succeeds and is zero cost. Otherwise, if this byte string is not
valid UTF-8, then an error (with the original byte string) is returned.</p>
<h5 id="examples-12"><a href="#examples-12">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>std::ffi::OsStr;
<span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span>bs = Vec::from(<span class="string">"foo"</span>);
<span class="kw">let </span>os_str = bs.into_os_string().expect(<span class="string">"should be valid UTF-8"</span>);
<span class="macro">assert_eq!</span>(os_str, OsStr::new(<span class="string">"foo"</span>));</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.into_os_string_lossy" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#648-667">source</a><h4 class="code-header">fn <a href="#method.into_os_string_lossy" class="fn">into_os_string_lossy</a>(self) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/ffi/os_str/struct.OsString.html" title="struct std::ffi::os_str::OsString">OsString</a><div class="where">where
Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Lossily converts this byte string into an OS string, in place.</p>
<p>When OS strings can be constructed from arbitrary byte sequences, this
is zero cost and always returns a slice. Otherwise, this will perform a
UTF-8 check and lossily convert this byte string into valid UTF-8 using
the Unicode replacement codepoint.</p>
<p>Note that this can prevent the correct roundtripping of file paths when
the representation of <code>OsString</code> is opaque.</p>
<h5 id="examples-13"><a href="#examples-13">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span>bs = Vec::from_slice(<span class="string">b"foo\xFFbar"</span>);
<span class="kw">let </span>os_str = bs.into_os_string_lossy();
<span class="macro">assert_eq!</span>(os_str.to_string_lossy(), <span class="string">"foo\u{FFFD}bar"</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.into_path_buf" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#688-693">source</a><h4 class="code-header">fn <a href="#method.into_path_buf" class="fn">into_path_buf</a>(self) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="struct" href="https://doc.rust-lang.org/1.76.0/std/path/struct.PathBuf.html" title="struct std::path::PathBuf">PathBuf</a>, <a class="struct" href="struct.FromUtf8Error.html" title="struct bstr::FromUtf8Error">FromUtf8Error</a>&gt;<div class="where">where
Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Converts this byte string into an owned file path, in place.</p>
<p>When paths can be constructed from arbitrary byte sequences, this
always succeeds and is zero cost. Otherwise, if this byte string is not
valid UTF-8, then an error (with the original byte string) is returned.</p>
<h5 id="examples-14"><a href="#examples-14">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span>bs = Vec::from(<span class="string">"foo"</span>);
<span class="kw">let </span>path = bs.into_path_buf().expect(<span class="string">"should be valid UTF-8"</span>);
<span class="macro">assert_eq!</span>(path.as_os_str(), <span class="string">"foo"</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.into_path_buf_lossy" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#718-723">source</a><h4 class="code-header">fn <a href="#method.into_path_buf_lossy" class="fn">into_path_buf_lossy</a>(self) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.76.0/std/path/struct.PathBuf.html" title="struct std::path::PathBuf">PathBuf</a><div class="where">where
Self: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Lossily converts this byte string into an owned file path, in place.</p>
<p>When paths can be constructed from arbitrary byte sequences, this is
zero cost and always returns a slice. Otherwise, this will perform a
UTF-8 check and lossily convert this byte string into valid UTF-8 using
the Unicode replacement codepoint.</p>
<p>Note that this can prevent the correct roundtripping of file paths when
the representation of <code>PathBuf</code> is opaque.</p>
<h5 id="examples-15"><a href="#examples-15">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span>bs = Vec::from_slice(<span class="string">b"foo\xFFbar"</span>);
<span class="kw">let </span>path = bs.into_path_buf_lossy();
<span class="macro">assert_eq!</span>(path.to_string_lossy(), <span class="string">"foo\u{FFFD}bar"</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.pop_byte" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#750-752">source</a><h4 class="code-header">fn <a href="#method.pop_byte" class="fn">pop_byte</a>(&amp;mut self) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>&gt;</h4></section></summary><div class="docblock"><p>Removes the last byte from this <code>Vec&lt;u8&gt;</code> and returns it.</p>
<p>If this byte string is empty, then <code>None</code> is returned.</p>
<p>If the last codepoint in this byte string is not ASCII, then removing
the last byte could make this byte string contain invalid UTF-8.</p>
<p>Note that this is equivalent to the generic <code>Vec::pop</code> method. This
method is provided to permit callers to explicitly differentiate
between popping bytes and codepoints.</p>
<h5 id="examples-16"><a href="#examples-16">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span><span class="kw-2">mut </span>s = Vec::from(<span class="string">"foo"</span>);
<span class="macro">assert_eq!</span>(s.pop_byte(), <span class="prelude-val">Some</span>(<span class="string">b'o'</span>));
<span class="macro">assert_eq!</span>(s.pop_byte(), <span class="prelude-val">Some</span>(<span class="string">b'o'</span>));
<span class="macro">assert_eq!</span>(s.pop_byte(), <span class="prelude-val">Some</span>(<span class="string">b'f'</span>));
<span class="macro">assert_eq!</span>(s.pop_byte(), <span class="prelude-val">None</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.pop_char" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#796-804">source</a><h4 class="code-header">fn <a href="#method.pop_char" class="fn">pop_char</a>(&amp;mut self) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.76.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.char.html">char</a>&gt;</h4></section></summary><div class="docblock"><p>Removes the last codepoint from this <code>Vec&lt;u8&gt;</code> and returns it.</p>
<p>If this byte string is empty, then <code>None</code> is returned. If the last
bytes of this byte string do not correspond to a valid UTF-8 code unit
sequence, then the Unicode replacement codepoint is yielded instead in
accordance with the
<a href="index.html#handling-of-invalid-utf8-8">replacement codepoint substitution policy</a>.</p>
<h5 id="examples-17"><a href="#examples-17">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span><span class="kw-2">mut </span>s = Vec::from(<span class="string">"foo"</span>);
<span class="macro">assert_eq!</span>(s.pop_char(), <span class="prelude-val">Some</span>(<span class="string">'o'</span>));
<span class="macro">assert_eq!</span>(s.pop_char(), <span class="prelude-val">Some</span>(<span class="string">'o'</span>));
<span class="macro">assert_eq!</span>(s.pop_char(), <span class="prelude-val">Some</span>(<span class="string">'f'</span>));
<span class="macro">assert_eq!</span>(s.pop_char(), <span class="prelude-val">None</span>);</code></pre></div>
<p>This shows the replacement codepoint substitution policy. Note that
the first pop yields a replacement codepoint but actually removes two
bytes. This is in contrast with subsequent pops when encountering
<code>\xFF</code> since <code>\xFF</code> is never a valid prefix for any valid UTF-8
code unit sequence.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span><span class="kw-2">mut </span>s = Vec::from_slice(<span class="string">b"f\xFF\xFF\xFFoo\xE2\x98"</span>);
<span class="macro">assert_eq!</span>(s.pop_char(), <span class="prelude-val">Some</span>(<span class="string">'\u{FFFD}'</span>));
<span class="macro">assert_eq!</span>(s.pop_char(), <span class="prelude-val">Some</span>(<span class="string">'o'</span>));
<span class="macro">assert_eq!</span>(s.pop_char(), <span class="prelude-val">Some</span>(<span class="string">'o'</span>));
<span class="macro">assert_eq!</span>(s.pop_char(), <span class="prelude-val">Some</span>(<span class="string">'\u{FFFD}'</span>));
<span class="macro">assert_eq!</span>(s.pop_char(), <span class="prelude-val">Some</span>(<span class="string">'\u{FFFD}'</span>));
<span class="macro">assert_eq!</span>(s.pop_char(), <span class="prelude-val">Some</span>(<span class="string">'\u{FFFD}'</span>));
<span class="macro">assert_eq!</span>(s.pop_char(), <span class="prelude-val">Some</span>(<span class="string">'f'</span>));
<span class="macro">assert_eq!</span>(s.pop_char(), <span class="prelude-val">None</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.remove_char" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#840-850">source</a><h4 class="code-header">fn <a href="#method.remove_char" class="fn">remove_char</a>(&amp;mut self, at: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.char.html">char</a></h4></section></summary><div class="docblock"><p>Removes a <code>char</code> from this <code>Vec&lt;u8&gt;</code> at the given byte position and
returns it.</p>
<p>If the bytes at the given position do not lead to a valid UTF-8 code
unit sequence, then a
<a href="index.html#handling-of-invalid-utf8-8">replacement codepoint is returned instead</a>.</p>
<h5 id="panics"><a href="#panics">Panics</a></h5>
<p>Panics if <code>at</code> is larger than or equal to this byte string’s length.</p>
<h5 id="examples-18"><a href="#examples-18">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span><span class="kw-2">mut </span>s = Vec::from(<span class="string">"foo☃bar"</span>);
<span class="macro">assert_eq!</span>(s.remove_char(<span class="number">3</span>), <span class="string">'☃'</span>);
<span class="macro">assert_eq!</span>(s, <span class="string">b"foobar"</span>);</code></pre></div>
<p>This example shows how the Unicode replacement codepoint policy is
used:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span><span class="kw-2">mut </span>s = Vec::from_slice(<span class="string">b"foo\xFFbar"</span>);
<span class="macro">assert_eq!</span>(s.remove_char(<span class="number">3</span>), <span class="string">'\u{FFFD}'</span>);
<span class="macro">assert_eq!</span>(s, <span class="string">b"foobar"</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.insert_char" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#874-876">source</a><h4 class="code-header">fn <a href="#method.insert_char" class="fn">insert_char</a>(&amp;mut self, at: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a>, ch: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.char.html">char</a>)</h4></section></summary><div class="docblock"><p>Inserts the given codepoint into this <code>Vec&lt;u8&gt;</code> at a particular byte
position.</p>
<p>This is an <code>O(n)</code> operation as it may copy a number of elements in this
byte string proportional to its length.</p>
<h5 id="panics-1"><a href="#panics-1">Panics</a></h5>
<p>Panics if <code>at</code> is larger than the byte string’s length.</p>
<h5 id="examples-19"><a href="#examples-19">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span><span class="kw-2">mut </span>s = Vec::from(<span class="string">"foobar"</span>);
s.insert_char(<span class="number">3</span>, <span class="string">'☃'</span>);
<span class="macro">assert_eq!</span>(s, <span class="string">"foo☃bar"</span>.as_bytes());</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.insert_str" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#904-934">source</a><h4 class="code-header">fn <a href="#method.insert_str" class="fn">insert_str</a>&lt;B: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;[<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>]&gt;&gt;(&amp;mut self, at: <a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a>, bytes: B)</h4></section></summary><div class="docblock"><p>Inserts the given byte string into this byte string at a particular
byte position.</p>
<p>This is an <code>O(n)</code> operation as it may copy a number of elements in this
byte string proportional to its length.</p>
<p>The given byte string may be any type that can be cheaply converted
into a <code>&amp;[u8]</code>. This includes, but is not limited to, <code>&amp;str</code> and
<code>&amp;[u8]</code>.</p>
<h5 id="panics-2"><a href="#panics-2">Panics</a></h5>
<p>Panics if <code>at</code> is larger than the byte string’s length.</p>
<h5 id="examples-20"><a href="#examples-20">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span><span class="kw-2">mut </span>s = Vec::from(<span class="string">"foobar"</span>);
s.insert_str(<span class="number">3</span>, <span class="string">"☃☃☃"</span>);
<span class="macro">assert_eq!</span>(s, <span class="string">"foo☃☃☃bar"</span>.as_bytes());</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.replace_range" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#956-962">source</a><h4 class="code-header">fn <a href="#method.replace_range" class="fn">replace_range</a>&lt;R, B&gt;(&amp;mut self, range: R, replace_with: B)<div class="where">where
R: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/ops/range/trait.RangeBounds.html" title="trait core::ops::range::RangeBounds">RangeBounds</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a>&gt;,
B: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/convert/trait.AsRef.html" title="trait core::convert::AsRef">AsRef</a>&lt;[<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>]&gt;,</div></h4></section></summary><div class="docblock"><p>Removes the specified range in this byte string and replaces it with
the given bytes. The given bytes do not need to have the same length
as the range provided.</p>
<h5 id="panics-3"><a href="#panics-3">Panics</a></h5>
<p>Panics if the given range is invalid.</p>
<h5 id="examples-21"><a href="#examples-21">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span><span class="kw-2">mut </span>s = Vec::from(<span class="string">"foobar"</span>);
s.replace_range(<span class="number">2</span>..<span class="number">4</span>, <span class="string">"xxxxx"</span>);
<span class="macro">assert_eq!</span>(s, <span class="string">"foxxxxxar"</span>.as_bytes());</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.drain_bytes" class="method"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#994-999">source</a><h4 class="code-header">fn <a href="#method.drain_bytes" class="fn">drain_bytes</a>&lt;R&gt;(&amp;mut self, range: R) -&gt; <a class="struct" href="struct.DrainBytes.html" title="struct bstr::DrainBytes">DrainBytes</a>&lt;'_&gt; <a href="#" class="tooltip" data-notable-ty="DrainBytes&lt;&#39;_&gt;">ⓘ</a><div class="where">where
R: <a class="trait" href="https://doc.rust-lang.org/1.76.0/core/ops/range/trait.RangeBounds.html" title="trait core::ops::range::RangeBounds">RangeBounds</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.usize.html">usize</a>&gt;,</div></h4></section></summary><div class="docblock"><p>Creates a draining iterator that removes the specified range in this
<code>Vec&lt;u8&gt;</code> and yields each of the removed bytes.</p>
<p>Note that the elements specified by the given range are removed
regardless of whether the returned iterator is fully exhausted.</p>
<p>Also note that is is unspecified how many bytes are removed from the
<code>Vec&lt;u8&gt;</code> if the <code>DrainBytes</code> iterator is leaked.</p>
<h5 id="panics-4"><a href="#panics-4">Panics</a></h5>
<p>Panics if the given range is not valid.</p>
<h5 id="examples-22"><a href="#examples-22">Examples</a></h5>
<p>Basic usage:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bstr::ByteVec;
<span class="kw">let </span><span class="kw-2">mut </span>s = Vec::from(<span class="string">"foobar"</span>);
{
<span class="kw">let </span><span class="kw-2">mut </span>drainer = s.drain_bytes(<span class="number">2</span>..<span class="number">4</span>);
<span class="macro">assert_eq!</span>(drainer.next(), <span class="prelude-val">Some</span>(<span class="string">b'o'</span>));
<span class="macro">assert_eq!</span>(drainer.next(), <span class="prelude-val">Some</span>(<span class="string">b'b'</span>));
<span class="macro">assert_eq!</span>(drainer.next(), <span class="prelude-val">None</span>);
}
<span class="macro">assert_eq!</span>(s, <span class="string">"foar"</span>.as_bytes());</code></pre></div>
</div></details></div><h2 id="object-safety" class="section-header">Object Safety<a href="#object-safety" class="anchor">§</a></h2><div class="object-safety-info">This trait is <b>not</b> <a href="https://doc.rust-lang.org/1.76.0/reference/items/traits.html#object-safety">object safe</a>.</div><h2 id="foreign-impls" class="section-header">Implementations on Foreign Types<a href="#foreign-impls" class="anchor">§</a></h2><section id="impl-ByteVec-for-Vec%3Cu8%3E" class="impl"><a class="src rightside" href="../src/bstr/ext_vec.rs.html#85-100">source</a><a href="#impl-ByteVec-for-Vec%3Cu8%3E" class="anchor">§</a><h3 class="code-header">impl <a class="trait" href="trait.ByteVec.html" title="trait bstr::ByteVec">ByteVec</a> for <a class="struct" href="https://doc.rust-lang.org/1.76.0/alloc/vec/struct.Vec.html" title="struct alloc::vec::Vec">Vec</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.76.0/std/primitive.u8.html">u8</a>&gt;</h3></section><h2 id="implementors" class="section-header">Implementors<a href="#implementors" class="anchor">§</a></h2><div id="implementors-list"></div><script src="../trait.impl/bstr/ext_vec/trait.ByteVec.js" data-ignore-extern-crates="alloc" async></script><script type="text/json" id="notable-traits-data">{"DrainBytes<'_>":"<h3>Notable traits for <code><a class=\"struct\" href=\"struct.DrainBytes.html\" title=\"struct bstr::DrainBytes\">DrainBytes</a>&lt;'a&gt;</code></h3><pre><code><div class=\"where\">impl&lt;'a&gt; <a class=\"trait\" href=\"https://doc.rust-lang.org/1.76.0/core/iter/traits/iterator/trait.Iterator.html\" title=\"trait core::iter::traits::iterator::Iterator\">Iterator</a> for <a class=\"struct\" href=\"struct.DrainBytes.html\" title=\"struct bstr::DrainBytes\">DrainBytes</a>&lt;'a&gt;</div><div class=\"where\"> type <a href=\"https://doc.rust-lang.org/1.76.0/core/iter/traits/iterator/trait.Iterator.html#associatedtype.Item\" class=\"associatedtype\">Item</a> = <a class=\"primitive\" href=\"https://doc.rust-lang.org/1.76.0/std/primitive.u8.html\">u8</a>;</div>","Vec<u8>":"<h3>Notable traits for <code><a class=\"struct\" href=\"https://doc.rust-lang.org/1.76.0/alloc/vec/struct.Vec.html\" title=\"struct alloc::vec::Vec\">Vec</a>&lt;<a class=\"primitive\" href=\"https://doc.rust-lang.org/1.76.0/std/primitive.u8.html\">u8</a>, A&gt;</code></h3><pre><code><div class=\"where\">impl&lt;A&gt; <a class=\"trait\" href=\"https://doc.rust-lang.org/1.76.0/std/io/trait.Write.html\" title=\"trait std::io::Write\">Write</a> for <a class=\"struct\" href=\"https://doc.rust-lang.org/1.76.0/alloc/vec/struct.Vec.html\" title=\"struct alloc::vec::Vec\">Vec</a>&lt;<a class=\"primitive\" href=\"https://doc.rust-lang.org/1.76.0/std/primitive.u8.html\">u8</a>, A&gt;<div class=\"where\">where\n A: <a class=\"trait\" href=\"https://doc.rust-lang.org/1.76.0/core/alloc/trait.Allocator.html\" title=\"trait core::alloc::Allocator\">Allocator</a>,</div></div>"}</script></section></div></main></body></html>
Reference in New Issue View Git Blame Copy Permalink