<!DOCTYPE html><htmllang="en"><head><metacharset="utf-8"><metaname="viewport"content="width=device-width, initial-scale=1.0"><metaname="generator"content="rustdoc"><metaname="description"content="Represents the capture groups for a single match."><title>Captures in regex::bytes - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../../static.files/${f}">`).join(""))</script><linkrel="stylesheet"href="../../static.files/normalize-76eba96aa4d2e634.css"><linkrel="stylesheet"href="../../static.files/rustdoc-dd39b87e5fcfba68.css"><metaname="rustdoc-vars"data-root-path="../../"data-static-root-path="../../static.files/"data-current-crate="regex"data-themes=""data-resource-suffix=""data-rustdoc-version="1.80.0 (051478957 2024-07-21)"data-channel="1.80.0"data-search-js="search-d52510db62a78183.js"data-settings-js="settings-4313503d2e1961c2.js"><scriptsrc="../../static.files/storage-118b08c4c78b968e.js"></script><scriptdefersrc="sidebar-items.js"></script><scriptdefersrc="../../static.files/main-20a3ad099b048cf2.js"></script><noscript><linkrel="stylesheet"href="../../static.files/noscript-df360f571f6edeae.css"></noscript><linkrel="alternate icon"type="image/png"href="../../static.files/favicon-32x32-422f7d1d52889060.png"><linkrel="icon"type="image/svg+xml"href="../../static.files/favicon-2c020d218678b618.svg"></head><bodyclass="rustdoc struct"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><navclass="mobile-topbar"><buttonclass="sidebar-menu-toggle"title="show sidebar"></button></nav><navclass="sidebar"><divclass="sidebar-crate"><h2><ahref="../../regex/index.html">regex</a><spanclass="version">1.10.5</span></h2></div><h2class="location"><ahref="#">Captures</a></h2><divclass="sidebar-elems"><section><h3><ahref="#implementations">Methods</a></h3><ulclass="block method"><li><ahref="#method.expand">expand</a></li><li><ahref="#method.extract">extract</a></li><li><ahref="#method.get">get</a></li><li><ahref="#method.iter">iter</a></li><li><ahref="#method.len">len</a></li><li><ahref="#method.name">name</a></li></ul><h3><ahref="#trait-implementations">Trait Implementations</a></h3><ulclass="block trait-implementation"><li><ahref="#impl-Debug-for-Captures%3C'h%3E">Debug</a></li><li><ahref="#impl-Index%3C%26str%3E-for-Captures%3C'h%3E">Index<&'n str></a></li><li><ahref="#impl-Index%3Cusize%3E-for-Captures%3C'h%3E">Index<usize></a></li></ul><h3><ahref="#synthetic-implementations">Auto Trait Implementations</a></h3><ulclass="block synthetic-implementation"><li><ahref="#impl-Freeze-for-Captures%3C'h%3E">Freeze</a></li><li><ahref="#impl-RefUnwindSafe-for-Captures%3C'h%3E">RefUnwindSafe</a></li><li><ahref="#impl-Send-for-Captures%3C'h%3E">Send</a></li><li><ahref="#impl-Sync-for-Captures%3C'h%3E">Sync</a></li><li><ahref="#impl-Unpin-for-Captures%3C'h%3E">Unpin</a></li><li><ahref="#impl-UnwindSafe-for-Captures%3C'h%3E">UnwindSafe</a></li></ul><h3><ahref="#blanket-implementations">Blanket Implementations</a></h3><ulclass="block blanket-implementation"><li><ahref="#impl-Any-for-T">Any</a></li><li><ahref="#impl-Borrow%3CT%3E-for-T">Borrow<T></a></li><li><ahref="#impl-BorrowMut%3CT%3E-for-T">BorrowMut<T></a></li><li><ahref="#impl-From%3CT%3E-for-T">From<T></a></li><li><ahref="#impl-Into%3CU%3E-for-T">Into<U></a></li><li><ahref="#impl-TryFrom%3CU%3E-for-T">TryFrom<U></a></li><li><ahref="#impl-TryInto%3CU%3E-for-T">TryInto<U></a></li></ul></section><h2><ahref="index.html">In regex::bytes</a></h2></div></nav><divclass="sidebar-resizer"></div><main><divclass="width-limiter"><ru
<p>Capture groups refer to parts of a regex enclosed in parentheses. They
can be optionally named. The purpose of capture groups is to be able to
reference different parts of a match based on the original pattern. In
essence, a <code>Captures</code> is a container of <ahref="struct.Match.html"title="struct regex::bytes::Match"><code>Match</code></a> values for each group
that participated in a regex match. Each <code>Match</code> can be looked up by either
its capture group index or name (if it has one).</p>
<p>For example, say you want to match the individual letters in a 5-letter
<li>The group at index <code>0</code> corresponds to the overall match. It is always
present in every match and never has a name.</li>
<li>The group at index <code>1</code> with name <code>first</code> corresponding to the first
letter.</li>
<li>The group at index <code>2</code> with no name corresponding to the second letter.</li>
<li>The group at index <code>3</code> with name <code>last</code> corresponding to the fifth and
last letter.</li>
</ul>
<p>Notice that <code>(?:\w)</code> was not listed above as a capture group despite it
being enclosed in parentheses. That’s because <code>(?:pattern)</code> is a special
syntax that permits grouping but <em>without</em> capturing. The reason for not
treating it as a capture is that tracking and reporting capture groups
requires additional state that may lead to slower searches. So using as few
capture groups as possible can help performance. (Although the difference
in performance of a couple of capture groups is likely immaterial.)</p>
<p>Values with this type are created by <ahref="struct.Regex.html#method.captures"title="method regex::bytes::Regex::captures"><code>Regex::captures</code></a> or
</div></details><h2id="implementations"class="section-header">Implementations<ahref="#implementations"class="anchor">§</a></h2><divid="implementations-list"><detailsclass="toggle implementors-toggle"open><summary><sectionid="impl-Captures%3C'h%3E"class="impl"><aclass="src rightside"href="../../src/regex/regex/bytes.rs.html#1638-1908">source</a><ahref="#impl-Captures%3C'h%3E"class="anchor">§</a><h3class="code-header">impl<'h><aclass="struct"href="struct.Captures.html"title="struct regex::bytes::Captures">Captures</a><'h></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.get"class="method"><aclass="src rightside"href="../../src/regex/regex/bytes.rs.html#1662-1666">source</a><h4class="code-header">pub fn <ahref="#method.get"class="fn">get</a>(&self, i: <aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a>) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/option/enum.Option.html"title="enum core::option::Option">Option</a><<aclass="struct"href="struct.Match.html"title="struct regex::bytes::Match">Match</a><'h>></h4></section></summary><divclass="docblock"><p>Returns the <code>Match</code> associated with the capture group at index <code>i</code>. If
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.name"class="method"><aclass="src rightside"href="../../src/regex/regex/bytes.rs.html#1698-1702">source</a><h4class="code-header">pub fn <ahref="#method.name"class="fn">name</a>(&self, name: &<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.str.html">str</a>) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/option/enum.Option.html"title="enum core::option::Option">Option</a><<aclass="struct"href="struct.Match.html"title="struct regex::bytes::Match">Match</a><'h>></h4></section></summary><divclass="docblock"><p>Returns the <code>Match</code> associated with the capture group named <code>name</code>. If
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.expand"class="method"><aclass="src rightside"href="../../src/regex/regex/bytes.rs.html#1853-1855">source</a><h4class="code-header">pub fn <ahref="#method.expand"class="fn">expand</a>(&self, replacement: &[<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.u8.html">u8</a>], dst: &mut <aclass="struct"href="https://doc.rust-lang.org/1.80.0/alloc/vec/struct.Vec.html"title="struct alloc::vec::Vec">Vec</a><<aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.u8.html">u8</a>>)</h4></section></summary><divclass="docblock"><p>Expands all instances of <code>$ref</code> in <code>replacement</code> to the corresponding
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.iter"class="method"><aclass="src rightside"href="../../src/regex/regex/bytes.rs.html#1883-1885">source</a><h4class="code-header">pub fn <ahref="#method.iter"class="fn">iter</a><'c>(&'c self) -><aclass="struct"href="struct.SubCaptureMatches.html"title="struct regex::bytes::SubCaptureMatches">SubCaptureMatches</a><'c, 'h><ahref="#"class="tooltip"data-notable-ty="SubCaptureMatches<'c, 'h>">ⓘ</a></h4></section></summary><divclass="docblock"><p>Returns an iterator over all capture groups. This includes both
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.len"class="method"><aclass="src rightside"href="../../src/regex/regex/bytes.rs.html#1905-1907">source</a><h4class="code-header">pub fn <ahref="#method.len"class="fn">len</a>(&self) -><aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.usize.html">usize</a></h4></section></summary><divclass="docblock"><p>Returns the total number of capture groups. This includes both
<p>The length returned is always equivalent to the number of elements
yielded by <ahref="struct.Captures.html#method.iter"title="method regex::bytes::Captures::iter"><code>Captures::iter</code></a>. Consequently, the length is always
greater than zero since every <code>Captures</code> value always includes the
</div></details></div></details></div><h2id="trait-implementations"class="section-header">Trait Implementations<ahref="#trait-implementations"class="anchor">§</a></h2><divid="trait-implementations-list"><detailsclass="toggle implementors-toggle"open><summary><sectionid="impl-Debug-for-Captures%3C'h%3E"class="impl"><aclass="src rightside"href="../../src/regex/regex/bytes.rs.html#1910-1971">source</a><ahref="#impl-Debug-for-Captures%3C'h%3E"class="anchor">§</a><h3class="code-header">impl<'h><aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/fmt/trait.Debug.html"title="trait core::fmt::Debug">Debug</a> for <aclass="struct"href="struct.Captures.html"title="struct regex::bytes::Captures">Captures</a><'h></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.fmt"class="method trait-impl"><aclass="src rightside"href="../../src/regex/regex/bytes.rs.html#1911-1970">source</a><ahref="#method.fmt"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.80.0/core/fmt/trait.Debug.html#tymethod.fmt"class="fn">fmt</a>(&self, f: &mut <aclass="struct"href="https://doc.rust-lang.org/1.80.0/core/fmt/struct.Formatter.html"title="struct core::fmt::Formatter">Formatter</a><'_>) -><aclass="type"href="https://doc.rust-lang.org/1.80.0/core/fmt/type.Result.html"title="type core::fmt::Result">Result</a></h4></section></summary><divclass='docblock'>Formats the value using the given formatter. <ahref="https://doc.rust-lang.org/1.80.0/core/fmt/trait.Debug.html#tymethod.fmt">Read more</a></div></details></div></details><detailsclass="toggle implementors-toggle"open><summary><sectionid="impl-Index%3C%26str%3E-for-Captures%3C'h%3E"class="impl"><aclass="src rightside"href="../../src/regex/regex/bytes.rs.html#2015-2023">source</a><ahref="#impl-Index%3C%26str%3E-for-Captures%3C'h%3E"class="anchor">§</a><h3class="code-header">impl<'h, 'n><aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/ops/index/trait.Index.html"title="trait core::ops::index::Index">Index</a><&'n <aclass="primitive"href="https://doc.rust-lang.org/1.80.0/std/primitive.str.html">str</a>> for <aclass="struct"href="struct.Captures.html"title="struct regex::bytes::Captures">Captures</a><'h></h3></section></summary><divclass="docblock"><p>Get a matching capture group’s haystack substring by name.</p>
<code><ahref="https://doc.rust-lang.org/1.80.0/core/convert/trait.From.html"title="trait core::convert::From">From</a><T> for U</code> chooses to do.</p>
</div></details></div></details><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-TryFrom%3CU%3E-for-T"class="impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.80.0/src/core/convert/mod.rs.html#805-807">source</a><ahref="#impl-TryFrom%3CU%3E-for-T"class="anchor">§</a><h3class="code-header">impl<T, U><aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><U> for T<divclass="where">where
U: <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.Into.html"title="trait core::convert::Into">Into</a><T>,</div></h3></section></summary><divclass="impl-items"><detailsclass="toggle"open><summary><sectionid="associatedtype.Error"class="associatedtype trait-impl"><ahref="#associatedtype.Error"class="anchor">§</a><h4class="code-header">type <ahref="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html#associatedtype.Error"class="associatedtype">Error</a> = <aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/convert/enum.Infallible.html"title="enum core::convert::Infallible">Infallible</a></h4></section></summary><divclass='docblock'>The type returned in the event of a conversion error.</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.try_from"class="method trait-impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.80.0/src/core/convert/mod.rs.html#812">source</a><ahref="#method.try_from"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html#tymethod.try_from"class="fn">try_from</a>(value: U) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><T, <T as <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><U>>::<aclass="associatedtype"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html#associatedtype.Error"title="type core::convert::TryFrom::Error">Error</a>></h4></section></summary><divclass='docblock'>Performs the conversion.</div></details></div></details><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-TryInto%3CU%3E-for-T"class="impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.80.0/src/core/convert/mod.rs.html#790-792">source</a><ahref="#impl-TryInto%3CU%3E-for-T"class="anchor">§</a><h3class="code-header">impl<T, U><aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryInto.html"title="trait core::convert::TryInto">TryInto</a><U> for T<divclass="where">where
U: <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><T>,</div></h3></section></summary><divclass="impl-items"><detailsclass="toggle"open><summary><sectionid="associatedtype.Error-1"class="associatedtype trait-impl"><ahref="#associatedtype.Error-1"class="anchor">§</a><h4class="code-header">type <ahref="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryInto.html#associatedtype.Error"class="associatedtype">Error</a> = <U as <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><T>>::<aclass="associatedtype"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html#associatedtype.Error"title="type core::convert::TryFrom::Error">Error</a></h4></section></summary><divclass='docblock'>The type returned in the event of a conversion error.</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.try_into"class="method trait-impl"><aclass="src rightside"href="https://doc.rust-lang.org/1.80.0/src/core/convert/mod.rs.html#797">source</a><ahref="#method.try_into"class="anchor">§</a><h4class="code-header">fn <ahref="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryInto.html#tymethod.try_into"class="fn">try_into</a>(self) -><aclass="enum"href="https://doc.rust-lang.org/1.80.0/core/result/enum.Result.html"title="enum core::result::Result">Result</a><U, <U as <aclass="trait"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html"title="trait core::convert::TryFrom">TryFrom</a><T>>::<aclass="associatedtype"href="https://doc.rust-lang.org/1.80.0/core/convert/trait.TryFrom.html#associatedtype.Error"title="type core::convert::TryFrom::Error">Error</a>></h4></section></summary><divclass='docblock'>Performs the conversion.</div></details></div></details></div><scripttype="text/json"id="notable-traits-data">{"&'a [u8]":"<h3>Notable traits for <code>&[<a class=\"primitive\" href=\"https://doc.rust-lang.org/1.80.0/std/primitive.u8.html\">u8</a>]</code></h3><pre><code><div class=\"where\">impl <a class=\"trait\" href=\"https://doc.rust-lang.org/1.80.0/std/io/trait.Read.html\" title=\"trait std::io::Read\">Read</a> for &[<a class=\"primitive\" href=\"https://doc.rust-lang.org/1.80.0/std/primitive.u8.html\">u8</a>]</div>","SubCaptureMatches<'c, 'h>":"<h3>Notable traits for <code><a class=\"struct\" href=\"struct.SubCaptureMatches.html\" title=\"struct regex::bytes::SubCaptureMatches\">SubCaptureMatches</a><'c, 'h></code></h3><pre><code><div class=\"where\">impl<'c, 'h> <a class=\"trait\" href=\"https://doc.rust-lang.org/1.80.0/core/iter/traits/iterator/trait.Iterator.html\" title=\"trait core::iter::traits::iterator::Iterator\">Iterator</a> for <a class=\"struct\" href=\"struct.SubCaptureMatches.html\" title=\"struct regex::bytes::SubCaptureMatches\">SubCaptureMatches</a><'c, 'h></div><div class=\"where\"> type <a href=\"https://doc.rust-lang.org/1.80.0/core/iter/traits/iterator/trait.Iterator.html#associatedtype.Item\" class=\"associatedtype\">Item</a> = <a class=\"enum\" href=\"https://doc.rust-lang.org/1.80.0/core/option/enum.Option.html\" title=\"enum core::option::Option\">Option</a><<a class=\"struct\" href=\"struct.Match.html\" title=\"struct regex::bytes::Match\">Match</a><'h>>;</div>"}</script></section></div></main></body></html>
