itsscb/esp-idf-hal
1
0
Fork 0
mirror of https://github.com/esp-rs/esp-idf-hal.git synced 2025-12-30 05:01:44 +00:00
Code Issues Packages Projects Releases Wiki Activity
esp-idf-hal/const_format/macro.formatcp.html

116 lines
10 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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="Formats constants of primitive types into a `&#38;&#39;static str`"><title>formatcp in const_format - 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="const_format" data-themes="" data-resource-suffix="" data-rustdoc-version="1.86.0-nightly (8361aef0d 2025-01-14)" data-channel="nightly" 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 macro"><!--[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="../const_format/index.html">const_<wbr>format</a><span class="version">0.2.34</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">formatcp</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#syntax" title="Syntax">Syntax</a></li><li><a href="#limitations" title="Limitations">Limitations</a></li><li><a href="#formating-behavior" title="Formating behavior">Formating behavior</a><ul><li><a href="#debug-like" title="Debug-like">Debug-like</a></li><li><a href="#display" title="Display">Display</a></li></ul></li><li><a href="#examples" title="Examples">Examples</a><ul><li><a href="#implicit-argument" title="Implicit argument">Implicit argument</a></li><li><a href="#repeating-arguments" title="Repeating arguments">Repeating arguments</a></li><li><a href="#debug-like-and-display-formatting" title="Debug-like and Display formatting">Debug-like and Display formatting</a></li><li><a href="#additional-specifiers" title="Additional specifiers">Additional specifiers</a></li></ul></li></ul></section><div id="rustdoc-modnav"><h2 class="in-crate"><a href="index.html">In crate const_<wbr>format</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">const_format</a></span><h1>Macro <span class="macro">formatcp</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/const_format/macros/fmt_macros.rs.html#230-241">Source</a> </span></div><pre class="rust item-decl"><code>macro_rules! formatcp {
($format_string:expr $( $(, $expr:expr )+ )? $(,)? ) =&gt; { ... };
}</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Formats constants of primitive types into a <code>&amp;'static str</code></p>
<p><a href="#examples">For <strong>examples</strong> look here</a></p>
<p><code>formatcp</code> stands for “format constants (of) primitives”</p>
<h2 id="syntax"><a class="doc-anchor" href="#syntax">§</a>Syntax</h2>
<p>This macro uses a limited version of the syntax from the standard library <a href="https://doc.rust-lang.org/std/macro.format.html"><code>format</code></a> macro,
it can do these things:</p>
<ul>
<li>
<p>Take positional arguments: <code>formatcp!("{}{0}", "hello" )</code></p>
</li>
<li>
<p>Take named arguments: <code>formatcp!("{a}{a}", a = "hello" )</code></p>
</li>
<li>
<p>Use constants from scope as arguments: <code>formatcp!("{FOO}")</code><br>
equivalent to the <a href="https://github.com/rust-lang/rfcs/blob/master/text/2795-format-args-implicit-identifiers.md"><code>format_args_implicits</code> RFC</a></p>
</li>
<li>
<p>Use Debug-like formatting (eg: <code>formatcp!("{:?}", "hello" )</code>:<br>
Similar to how <code>Debug</code> formatting in the standard library works,
except that it does not escape unicode characters.</p>
</li>
<li>
<p>Use LowerHex formatting (eg: <code>formatcp!("{:x}", "hello" )</code>):<br>
Formats numbers as lowercase hexadecimal.
The alternate version (written as <code>"{:#x}"</code>) prefixes the number with <code>0x</code></p>
</li>
<li>
<p>Use UpperHex formatting (eg: <code>formatcp!("{:X}", "hello" )</code>):<br>
Formats numbers as capitalized hexadecimal.
The alternate version (written as <code>"{:#X}"</code>) prefixes the number with <code>0x</code></p>
</li>
<li>
<p>Use Binary formatting (eg: <code>formatcp!("{:b}", "hello" )</code>)<br>
The alternate version (written as <code>"{:#b}"</code>) prefixes the number with <code>0b</code></p>
</li>
<li>
<p>Use Display formatting: <code>formatcp!("{}", "hello" )</code></p>
</li>
</ul>
<h2 id="limitations"><a class="doc-anchor" href="#limitations">§</a>Limitations</h2>
<p>This macro can only take constants of these types as inputs:</p>
<ul>
<li>
<p><code>&amp;str</code></p>
</li>
<li>
<p><code>i*</code>/<code>u*</code> (all the primitive integer types).</p>
</li>
<li>
<p><code>char</code></p>
</li>
<li>
<p><code>bool</code></p>
</li>
</ul>
<p>This macro also shares
<a href="./index.html#macro-limitations">the limitations described in here</a>
as well.</p>
<h2 id="formating-behavior"><a class="doc-anchor" href="#formating-behavior">§</a>Formating behavior</h2><h4 id="debug-like"><a class="doc-anchor" href="#debug-like">§</a>Debug-like</h4>
<p>The <code>{:?}</code> formatter formats things similarly to how Debug does it.</p>
<p>For <code>&amp;'static str</code> it does these things:</p>
<ul>
<li>Prepend and append the double quote character (<code>"</code>).</li>
<li>Escape the <code>'\t'</code>,<code>'\n'</code>,<code>'\r'</code>,<code>'\\'</code>, <code>'\''</code>, and<code>'\"'</code> characters.</li>
<li>Escape control characters with <code>\xYY</code>,
where <code>YY</code> is the hexadecimal value of the control character.</li>
</ul>
<p>Example:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>const_format::formatcp;
<span class="macro">assert_eq!</span>(<span class="macro">formatcp!</span>(<span class="string">"{:?}"</span>, <span class="string">r#" \ " ó "#</span>), <span class="string">r#"" \\ \" ó ""#</span>);</code></pre></div>
<p>For <code>char</code> it does these things:</p>
<ul>
<li>Prepend and append the single quote character (<code>'</code>).</li>
<li>Uses the same escapes as <code>&amp;'static str</code>.</li>
</ul>
<h4 id="display"><a class="doc-anchor" href="#display">§</a>Display</h4>
<p>The <code>{}</code>/<code>{:}</code> formatter produces the same output as in <a href="https://doc.rust-lang.org/std/macro.format.html"><code>format</code></a>.</p>
<h2 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h2><h4 id="implicit-argument"><a class="doc-anchor" href="#implicit-argument">§</a>Implicit argument</h4>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>const_format::formatcp;
<span class="kw">const </span>NAME: <span class="kw-2">&amp;</span>str = <span class="string">"John"</span>;
<span class="kw">const </span>MSG: <span class="kw-2">&amp;</span>str = <span class="macro">formatcp!</span>(<span class="string">"Hello {NAME}, your name is {} bytes long"</span>, NAME.len());
<span class="macro">assert_eq!</span>(MSG, <span class="string">"Hello John, your name is 4 bytes long"</span>);
</code></pre></div>
<h4 id="repeating-arguments"><a class="doc-anchor" href="#repeating-arguments">§</a>Repeating arguments</h4>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>const_format::formatcp;
<span class="kw">const </span>MSG: <span class="kw-2">&amp;</span>str = <span class="macro">formatcp!</span>(<span class="string">"{0}{S}{0}{S}{0}"</span>, <span class="string">"SPAM"</span>, S = <span class="string">" "</span>);
<span class="macro">assert_eq!</span>(MSG, <span class="string">"SPAM SPAM SPAM"</span>);
</code></pre></div>
<h4 id="debug-like-and-display-formatting"><a class="doc-anchor" href="#debug-like-and-display-formatting">§</a>Debug-like and Display formatting</h4>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>const_format::formatcp;
{
<span class="kw">const </span>TEXT: <span class="kw-2">&amp;</span>str = <span class="string">r#"hello " \ world"#</span>;
<span class="kw">const </span>MSG: <span class="kw-2">&amp;</span>str = <span class="macro">formatcp!</span>(<span class="string">"{TEXT}____{TEXT:?}"</span>);
<span class="macro">assert_eq!</span>(MSG, <span class="string">r#"hello " \ world____"hello \" \\ world""#</span>);
}
{
<span class="kw">const </span>CHARS: <span class="kw-2">&amp;</span>str = <span class="macro">formatcp!</span>(<span class="string">"{0:?} - {0} - {1} - {1:?}"</span>, <span class="string">'"'</span>, <span class="string">'👀'</span>);
<span class="macro">assert_eq!</span>(CHARS, <span class="string">r#"'\"' - " - 👀 - '👀'"#</span>);
}</code></pre></div>
<h4 id="additional-specifiers"><a class="doc-anchor" href="#additional-specifiers">§</a>Additional specifiers</h4>
<p><code>const_format</code> macros don’t support width, fill, alignment, sign,
or precision specifiers.</p>
</div></details></section></div></main></body></html>
Reference in New Issue View Git Blame Copy Permalink