PageSourceSearch

https://cpp-core-guidelines-docs.vercel.app/functions

html cpp-core-guidelines-docs.vercel.app collected 2026-10-03 06:34:30 UTC 335,169 bytes, 118 lines download raw bytes

1<!DOCTYPE html><html><head><meta charSet="utf-8"/>
1<script>!function(){try {var d=document.documentElement.classList;d.remove('light','dark');var e=localStorage.getItem('theme');if(!e)return localStorage.setItem('theme','light'),d.add('light');if("system"===e){var t="(prefers-color-scheme: dark)",m=window.matchMedia(t);m.media!==t||m.matches?d.add('dark'):d.add('light')}else d.add(e)}catch(e){}}()</script>
1<link rel="stylesheet" href="https://rsms.me/inter/inter.css"/><title>F: Functions – C++</title><style>html{font-family:Inter,sans-serif}@supports(font-variation-settings:normal){html{font-family:'Inter var',sans-serif}}</style><meta name="msapplication-TileColor" content="#ffffff"/><meta name="theme-color" content="#ffffff"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><meta http-equiv="Content-Language" content="en"/><meta name="description" content="C++ Core Guidelines"/><meta name="og:description" content="C++ Core Guidelines"/><meta name="twitter:card" content="summary_large_image"/><meta name="twitter:image" content="/og.png"/><meta name="twitter:site:domain" content="cpp-core-guidelines-docs.vercel.app"/><meta name="twitter:url" content="https://cpp-core-guidelines-docs.vercel.app/"/><meta name="og:title" content="C++ Core Guidelines"/><meta name="og:image" content="/og.png"/><meta name="apple-mobile-web-app-title" content="C++ Core Guidelines"/><link rel="icon" type="image/png" sizes="196x196" href="/favicon-196x196.png"/><link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png"/><link rel="icon" type="image/png" sizes="96x96" href="/favicon-96x96.png"/><link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png"/><meta name="msapplication-TileImage" content="/ms-icon-144x144.png"/><meta name="next-head-count" content="23"/><link rel="preload" href="/_next/static/css/b2cc816d3551ec97.css" as="style"/><link rel="stylesheet" href="/_next/static/css/b2cc816d3551ec97.css" data-n-g=""/><noscript data-n-css=""></noscript>
1<script defer="" nomodule="" src="/_next/static/chunks/polyfills-5cd94c89d3acac5f.js"></script>
1<script src="/_next/static/chunks/webpack-d7b038a63b619762.js" defer=""></script>
1<script src="/_next/static/chunks/framework-5f4595e5518b5600.js" defer=""></script>
1<script src="/_next/static/chunks/main-01df828e572375b9.js" defer=""></script>
1<script src="/_next/static/chunks/pages/_app-c9482e1feb19cf8c.js" defer=""></script>
1<script src="/_next/static/chunks/58-681738de630b2586.js" defer=""></script>
1<script src="/_next/static/chunks/pages/functions-b010688edcb1c410.js" defer=""></script>
1<script src="/_next/static/-EYFV5cGB6Gs4jJDYIQHc/_buildManifest.js" defer=""></script>
1<script src="/_next/static/-EYFV5cGB6Gs4jJDYIQHc/_ssgManifest.js" defer=""></script>
1<script src="/_next/static/-EYFV5cGB6Gs4jJDYIQHc/_middlewareManifest.js" defer=""></script>
1</head><body><div id="__next" data-reactroot=""><div class="nextra-container main-container flex flex-col"><nav class="flex items-center bg-white z-20 fixed top-0 left-0 right-0 h-16 border-b border-gray-200 px-6 dark:bg-dark dark:border-gray-900 bg-opacity-[.97] dark:bg-opacity-100"><div class="w-full flex items-center mr-2"><a class="no-underline text-current inline-flex items-center hover:opacity-75" href="/"><span class="mr-2 font-extrabold hidden md:inline">C++</span><span class="text-gray-600 font-normal hidden md:inline">Core Guidelines</span></a></div><div class="flex-1"><div class="hidden md:inline-block mr-2"><div class="nextra-search relative w-full md:w-64"><input type="search" class="appearance-none border rounded py-2 px-3 leading-tight focus:outline-none focus:ring w-full" placeholder="Search (&quot;/&quot; to focus)"/></div></div></div><a class="text-current p-2 cursor-pointer" tabindex="0"><svg viewBox="0 0 24 24" width="24" height="24" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" fill="none" shape-rendering="geometricPrecision"></svg></a><a class="text-current p-2" href="https://github.com/isocpp/CppCoreGuidelines" target="_blank"><svg height="24" viewBox="2 2 20 20" fill="none"><path fill-rule="evenodd" clip-rule="evenodd" d="M12 3C7.0275 3 3 7.12937 3 12.2276C3 16.3109 5.57625 19.7597 9.15374 20.9824C9.60374 21.0631 9.77249 20.7863 9.77249 20.5441C9.77249 20.3249 9.76125 19.5982 9.76125 18.8254C7.5 19.2522 6.915 18.2602 6.735 17.7412C6.63375 17.4759 6.19499 16.6569 5.8125 16.4378C5.4975 16.2647 5.0475 15.838 5.80124 15.8264C6.51 15.8149 7.01625 16.4954 7.18499 16.7723C7.99499 18.1679 9.28875 17.7758 9.80625 17.5335C9.885 16.9337 10.1212 16.53 10.38 16.2993C8.3775 16.0687 6.285 15.2728 6.285 11.7432C6.285 10.7397 6.63375 9.9092 7.20749 9.26326C7.1175 9.03257 6.8025 8.08674 7.2975 6.81794C7.2975 6.81794 8.05125 6.57571 9.77249 7.76377C10.4925 7.55615 11.2575 7.45234 12.0225 7.45234C12.7875 7.45234 13.5525 7.55615 14.2725 7.76377C15.9937 6.56418 16.7475 6.81794 16.7475 6.81794C17.2424 8.08674 16.9275 9.03257 16.8375 9.26326C17.4113 9.9092 17.76 10.7281 17.76 11.7432C17.76 15.2843 15.6563 16.0687 13.6537 16.2993C13.98 16.5877 14.2613 17.1414 14.2613 18.0065C14.2613 19.2407 14.25 20.2326 14.25 20.5441C14.25 20.7863 14.4188 21.0746 14.8688 20.9824C16.6554 20.364 18.2079 19.1866 19.3078 17.6162C20.4077 16.0457 20.9995 14.1611 21 12.2276C21 7.12937 16.9725 3 12 3Z" fill="currentColor"></path></svg></a><button class="block md:hidden p-2"><svg fill="none" width="24" height="24" viewBox="0 0 24 24" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 6h16M4 12h16M4 18h16"></path></svg></button><div class="-mr-2"></div></nav><div class="flex flex-1 h-full"><aside class="fixed h-screen bg-white dark:bg-dark flex-shrink-0 w-full md:w-64 md:sticky z-10 hidden md:block" style="top:4rem;height:calc(100vh - 4rem)"><div class="sidebar border-gray-200 dark:border-gray-900 w-full p-4 pb-40 md:pb-16 h-full overflow-y-auto"><div class="mb-4 block md:hidden"><div class="nextra-search relative w-full md:w-64"><input type="search" class="appearance-none border rounded py-2 px-3 leading-tight focus:outline-none focus:ring w-full" placeholder="Search (&quot;/&quot; to focus)"/></div></div><div class="hidden md:block"><ul><li class=""><a href="/">Top</a></li><li class=""><a href="/introduction">In: Introduction</a></li><li class=""><a href="/philosophy">P: Philosophy</a></li><li class=""><a href="/interfaces">I: Interfaces</a></li><li class="active"><a href="/functions">F: Functions</a><ul><li><a href="#fdef-function-definitions" class="active-anchor"><span class="flex text-sm"><span class="opacity-25">#</span><span class="mr-2"></span><span class="inline-block">F.def: Function definitions</span></span></a></li><li><a href="#fcall-parameter-passing" class=""><span class="flex text-sm"><span class="opacity-25">#</span><span class="mr-2"></span><span class="inline-block">F.call: Parameter passing</span></span></a></li></ul></li><li class=""><a href="/class">C: Classes and class hierarchies</a></li><li class=""><a href="/enum">Enum: Enumerations</a></li><li class=""><a href="/resource">R: Resource management</a></li><li class=""><a href="/expr">ES: Expressions and statements</a></li><li class=""><a href="/performance">Per: Performance</a></li><li class=""><a href="/concurrency">CP: Concurrency and parallelism</a></li><li class=""><a href="/errors">E: Error handling</a></li><li class=""><a href="/const">Con: Constants and immutability</a></li><li class=""><a href="/templates">T: Templates and generic programming</a></li><li class=""><a href="/cpl">CPL: C-style programming</a></li><li class=""><a href="/source">SF: Source files</a></li><li class=""><a href="/stdlib">SL: The Standard Library</a></li><li class=""><a href="/A">A: Architectural ideas</a></li><li class=""><a href="/not">NR: Non-Rules and myths</a></li><li class=""><a href="/references">RF: References</a></li><li class=""><a href="/profile">Pro: Profiles</a></li><li class=""><a href="/gsl">GSL: Guidelines support library</a></li><li class=""><a href="/naming">NL: Naming and layout suggestions</a></li><li class=""><a href="/faq">FAQ: Answers to frequently asked questions</a></li><li class=""><a href="/libraries">Appendix A: Libraries</a></li><li class=""><a href="/modernizing">Appendix B: Modernizing code</a></li><li class=""><a href="/discussion">Appendix C: Discussion</a></li><li class=""><a href="/tools">Appendix D: Supporting tools</a></li><li class=""><a href="/glossary">Glossary</a></li><li class=""><a href="/unclassified">To-do: Unclassified proto-rules</a></li></ul></div><div class="md:hidden"><ul><li class=""><a href="/">Top</a></li><li class=""><a href="/introduction">In: Introduction</a></li><li class=""><a href="/philosophy">P: Philosophy</a></li><li class=""><a href="/interfaces">I: Interfaces</a></li><li class="active"><a href="/functions">F: Functions</a><ul><li><a href="#fdef-function-definitions" class="active-anchor"><span class="flex text-sm"><span class="opacity-25">#</span><span class="mr-2"></span><span class="inline-block">F.def: Function definitions</span></span></a></li><li><a href="#fcall-parameter-passing" class=""><span class="flex text-sm"><span class="opacity-25">#</span><span class="mr-2"></span><span class="inline-block">F.call: Parameter passing</span></span></a></li></ul></li><li class=""><a href="/class">C: Classes and class hierarchies</a></li><li class=""><a href="/enum">Enum: Enumerations</a></li><li class=""><a href="/resource">R: Resource management</a></li><li class=""><a href="/expr">ES: Expressions and statements</a></li><li class=""><a href="/performance">Per: Performance</a></li><li class=""><a href="/concurrency">CP: Concurrency and parallelism</a></li><li class=""><a href="/errors">E: Error handling</a></li><li class=""><a href="/const">Con: Constants and immutability</a></li><li class=""><a href="/templates">T: Templates and generic programming</a></li><li class=""><a href="/cpl">CPL: C-style programming</a></li><li class=""><a href="/source">SF: Source files</a></li><li class=""><a href="/stdlib">SL: The Standard Library</a></li><li class=""><a href="/A">A: Architectural ideas</a></li><li class=""><a href="/not">NR: Non-Rules and myths</a></li><li class=""><a href="/references">RF: References</a></li><li class=""><a href="/profile">Pro: Profiles</a></li><li class=""><a href="/gsl">GSL: Guidelines support library</a></li><li class=""><a href="/naming">NL: Naming and layout suggestions</a></li><li class=""><a href="/faq">FAQ: Answers to frequently asked questions</a></li><li class=""><a href="/libraries">Appendix A: Libraries</a></li><li class=""><a href="/modernizing">Appendix B: Modernizing code</a></li><li class=""><a href="/discussion">Appendix C: Discussion</a></li><li class=""><a href="/tools">Appendix D: Supporting tools</a></li><li class=""><a href="/glossary">Glossary</a></li><li class=""><a href="/unclassified">To-do: Unclassified proto-rules</a></li></ul></div></div></aside><div id="reach-skip-nav" data-reach-skip-nav-content=""></div><article class="docs-container relative pt-20 pb-16 px-6 md:px-8 w-full max-w-full overflow-x-hidden"><main class="max-w-screen-md mx-auto"><h1><a href="#" name="S-functions"></a>F: Functions</h1><p>A function specifies an action or a computation that takes the system from one consistent state to the next. It is the fundamental building block of programs.</p><p>It should be possible to name a function meaningfully, to specify the requirements of its argument, and clearly state the relationship between the arguments and the result. An implementation is not a specification. Try to think about what a function does as well as about how 
1it does it.
2Functions are the most critical part in most interfaces, so see the interface rules.</p><p>Function rule summary:</p><p>Function definition rules:</p><ul><li><a href="/functions#Rf-package">(F.1: &quot;Package&quot; meaningful operations as carefully named functions)</a></li><li><a href="/functions#Rf-logical">(F.2: A function should perform a single logical operation)</a></li><li><a href="/functions#Rf-single">(F.3: Keep functions short and simple)</a></li><li><a href="/functions#Rf-constexpr">(F.4: If a function might have to be evaluated at compile time, declare it <code>constexpr</code>)</a></li><li><a href="/functions#Rf-inline">(F.5: If a function is very small and time-critical, declare it inline)</a></li><li><a href="/functions#Rf-noexcept">(F.6: If your function must not throw, declare it <code>noexcept</code>)</a></li><li><a href="/functions#Rf-smart">(F.7: For general use, take <code>T*</code> or <code>T&amp;</code> arguments rather than smart pointers)</a></li><li><a href="/functions#Rf-pure">(F.8: Prefer pure functions)</a></li><li><a href="/functions#Rf-unused">(F.9: Unused parameters should be unnamed)</a></li></ul><p>Parameter passing expression rules:</p><ul><li><a href="/functions#Rf-conventional">(F.15: Prefer simple and conventional ways of passing information)</a></li><li><a href="/functions#Rf-in">(F.16: For &quot;in&quot; parameters, pass cheaply-copied types by value and others by reference to <code>const</code>)</a></li><li><a href="/functions#Rf-inout">(F.17: For &quot;in-out&quot; parameters, pass by reference to non-<code>const</code>)</a></li><li><a href="/functions#Rf-consume">(F.18: For &quot;will-move-from&quot; parameters, pass by <code>X&amp;&amp;</code> and <code>std::move</code> the parameter)</a></li><li><a href="/functions#Rf-forward">(F.19: For &quot;forward&quot; parameters, pass by <code>TP&amp;&amp;</code> and only <code>std::forward</code> the parameter)</a></li><li><a href="/functions#Rf-out">(F.20: For &quot;out&quot; output values, prefer return values to output parameters)</a></li><li><a href="/functions#Rf-out-multi">(F.21: To return multiple &quot;out&quot; values, prefer returning a struct or tuple)</a></li><li><a href="/functions#Rf-ptr-ref">(F.60: Prefer <code>T*</code> over <code>T&amp;</code> when &quot;no argument&quot; is a valid option)</a></li></ul><p>Parameter passing semantic rules:</p><ul><li><a href="/functions#Rf-ptr">(F.22: Use <code>T*</code> or <code>owner&lt;T*&gt;</code> to designate a single object)</a></li><li><a href="/functions#Rf-nullptr">(F.23: Use a <code>not_null&lt;T&gt;</code> to indicate that &quot;null&quot; is not a valid value)</a></li><li><a href="/functions#Rf-range">(F.24: Use a <code>span&lt;T&gt;</code> or a <code>span_p&lt;T&gt;</code> to designate a half-open sequence)</a></li><li><a href="/functions#Rf-zstring">(F.25: Use a <code>zstring</code> or a <code>not_null&lt;zstring&gt;</code> to designate a C-style string)</a></li><li><a href="#Rf-unique_ptr">F.26: Use a <code>unique_ptr&lt;T&gt;</code> to transfer ownership where a pointer is needed</a></li><li><a href="#Rf-shared_ptr">F.27: Use a <code>shared_ptr&lt;T&gt;</code> to share ownership</a></li></ul><p><a href="#" name="Rf-value-return"></a>Value return semantic rules:</p><ul><li><a href="/functions#Rf-return-ptr">(F.42: Return a <code>T*</code> to indicate a position (only))</a></li><li><a href="/functions#Rf-dangle">(F.43: Never (directly or indirectly) return a pointer or a reference to a local object)</a></li><li><a href="/functions#Rf-return-ref">(F.44: Return a <code>T&amp;</code> when copy is undesirable and &quot;returning no object&quot; isn&#x27;t needed)</a></li><li><a href="/functions#Rf-return-ref-ref">(F.45: Don&#x27;t return a <code>T&amp;&amp;</code>)</a></li><li><a href="/functions#Rf-main">(F.46: <code>int</code> is the return type for <code>main()</code>)</a></li><li><a href="/functions#Rf-assignment-op">(F.47: Return <code>T&amp;</code> from assignment operators)</a></li><li><a href="/functions#Rf-return-move-local">(F.48: Don&#x27;t <code>
2return std::move(local)</code>)</a></li></ul><p>Other function rules:</p><ul><li><a href="/functions#Rf-capture-vs-overload">(F.50: Use a lambda when a function won&#x27;t do (to capture local variables, or to write a local function))</a></li><li><a href="/functions#Rf-default-args">(F.51: Where there is a choice, prefer default arguments over overloading)</a></li><li><a href="/functions#Rf-reference-capture">(F.52: Prefer capturing by reference in lambdas that will be used locally, including passed to algorithms)</a></li><li><a href="/functions#Rf-value-capture">(F.53: Avoid capturing by reference in lambdas that will be used non-locally, including returned, stored on the heap, or passed to another thread)</a></li><li><a href="/functions#Rf-this-capture">(F.54: If you capture <code>this</code>, capture all variables explicitly (no default capture))</a></li><li><a href="/functions#F-varargs">(F.55: Don&#x27;t use <code>va_arg</code> arguments)</a></li><li><a href="/functions#F-nesting">(F.56: Avoid unnecessary condition nesting)</a></li></ul><p>Functions have strong similarities to lambdas and function objects.</p><p><strong>See also</strong>: <a href="/class#SS-lambdas">(C.lambdas: Function objects and lambdas)</a></p><h2><span class="subheading-anchor" id="fdef-function-definitions"></span><a href="#fdef-function-definitions" class="text-current no-underline no-outline"><a href="#" name="SS-fct-def"></a>F.def: Function definitions<span class="anchor-icon" aria-hidden="true">#</span></a></h2><p>A function definition is a function declaration that also specifies the function&#x27;s implementation, the function body.</p><h3><span class="subheading-anchor" id="f1-package-meaningful-operations-as-carefully-named-functions"></span><a href="#f1-package-meaningful-operations-as-carefully-named-functions" class="text-current no-underline no-outline"><a href="#" name="Rf-package"></a>F.1: &quot;Package&quot; meaningful operations as carefully named functions<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason"></span><a href="#reason" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Factoring out common code makes code more readable, more likely to be reused, and limit errors from complex code.
3If something is a well-specified action, separate it out from its surrounding code and give it a name.</p><h5><span class="subheading-anchor" id="example-dont"></span><a href="#example-dont" class="text-current no-underline no-outline">Example, don&#x27;t<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">read_and_print</span><span class="token punctuation">(</span><span class="token plain">istream</span><span class="token operator">&amp;</span><span class="token plain"> is</span><span class="token punctuation">)</span><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// read and print an int</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> x</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">is </span><span class="token operator">&gt;&gt;</span><span class="token plain"> x</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        cout </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&quot;the int is &quot;</span><span class="token plain"> </span><span class="token operator">&lt;&lt;</span><span class="token plain"> x </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&#x27;\n&#x27;</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">else</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        cerr </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&quot;no int on input\n&quot;</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>Almost everything is wrong with <code>read_and_print</code>.
4It reads, it writes (to a fixed <code>ostream</code>), it writes error messages (to a fixed <code>ostream</code>), it handles only <code>int</code>s.
5There is nothing to reuse, logically separate operations are intermingled and local variables are in scope after the end of their logical use.
6For a tiny example, this looks OK, but if the input operation, the output operation, and the error handling had been more complicated the tangled
7mess could become hard to understand.</p><h5><span class="subheading-anchor" id="note"></span><a href="#note" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">
7#</span></a></h5><p>If you write a non-trivial lambda that potentially can be used in more than one place, give it a name by assigning it to a (usually non-local) variable.</p><h5><span class="subheading-anchor" id="example"></span><a href="#example" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token function">sort</span><span class="token punctuation">(</span><span class="token plain">a</span><span class="token punctuation">,</span><span class="token plain"> b</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">(</span><span class="token plain">T x</span><span class="token punctuation">,</span><span class="token plain"> T y</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> x</span><span class="token punctuation">.</span><span class="token function">rank</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token operator">&lt;</span><span class="token plain"> y</span><span class="token punctuation">.</span><span class="token function">rank</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token operator">&amp;&amp;</span><span class="token plain"> x</span><span class="token punctuation">.</span><span class="token function">value</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token operator">&lt;</span><span class="token plain"> y</span><span class="token punctuation">.</span><span class="token function">value</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><p>Naming that lambda breaks up the expression into its logical parts and provides a strong hint to the meaning of the lambda.</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> lessT </span><span class="token operator">=</span><span class="token plain"> </span><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">(</span><span class="token plain">T x</span><span class="token punctuation">,</span><span class="token plain"> T y</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> x</span><span class="token punctuation">.</span><span class="token function">rank</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token operator">&lt;</span><span class="token plain"> y</span><span class="token punctuation">.</span><span class="token function">rank</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token operator">&amp;&amp;</span><span class="token plain"> x</span><span class="token punctuation">.</span><span class="token function">value</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token operator">&lt;</span><span class="token plain"> y</span><span class="token punctuation">.</span><span class="token function">value</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token function">
7sort</span><span class="token punctuation">(</span><span class="token plain">a</span><span class="token punctuation">,</span><span class="token plain"> b</span><span class="token punctuation">,</span><span class="token plain"> lessT</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><p>The shortest code is not always the best for performance or maintainability.</p><h5><span class="subheading-anchor" id="exception"></span><a href="#exception" class="text-current no-underline no-outline">Exception<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Loop bodies, including lambdas used as loop bodies, rarely need to be named.
8However, large loop bodies (e.g., dozens of lines or dozens of pages) can be a problem.
9The rule <a href="/functions#Rf-single">(Keep functions short and simple)</a> implies &quot;Keep loop bodies short.&quot;
10Similarly, lambdas used as callback arguments are sometimes non-trivial, yet unlikely to be reusable.</p><h5><span class="subheading-anchor" id="enforcement"></span><a href="#enforcement" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>See <a href="/functions#Rf-single">(Keep functions short and simple)</a></li><li>Flag identical and very similar lambdas used in different places.</li></ul><h3><span class="subheading-anchor" id="f2-a-function-should-perform-a-single-logical-operation"></span><a href="#f2-a-function-should-perform-a-single-logical-operation" class="text-current no-underline no-outline"><a href="#" name="Rf-logical"></a>F.2: A function should perform a single logical operation<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-1"></span><a href="#reason-1" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>A function that performs a single operation is simpler to understand, test, and reuse.</p><h5><span class="subheading-anchor" id="example-1"></span><a href="#example-1" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Consider:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">read_and_print</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// bad</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> x</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    cin </span><span class="token operator">&gt;&gt;</span><span class="token plain"> x</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// check for errors</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    cout </span><span class="token operator">&lt;&lt;</span><span class="token plain"> x </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&quot;\n&quot;</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>This is a monolith that is tied to a specific input and will never find another (different) use. Instead, break functions up into suitable logical parts and parameterize:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">read</span><span class="token punctuation">(</span><span class="token plain">istream</span><span class="token operator">&amp;</span><span class="token plain"> is</span><span class="token punctuation">)</span><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// better</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> x</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    is </span><span class="token operator">&gt;&gt;</span><span class="token plain"> x</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// check for errors</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> x</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">print</span><span class="token punctuation">(</span><span class="token plain">ostream</span><span class="token operator">&amp;</span><span class="token plain"> os</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> x</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    os </span><span class="token operator">&lt;&lt;</span><span class="token plain"> x </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&quot;\n&quot;</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>These can now be combined where needed:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">read_and_print</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> x </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">read</span><span class="token punctuation">(</span><span class="token plain">cin</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">print</span><span class="token punctuation">(</span><span class="token plain">cout</span><span class="token punctuation">,</span><span class="token plain"> x</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>If there was a need, we could further templatize <code>read()</code> and <code>print()</code> on the data type, the I/O mechanism, the response to errors, etc. Example:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> read </span><span class="token operator">=</span><span class="token plain"> </span><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token operator">&amp;</span><span class="token plain"> input</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token operator">&amp;</span><span class="token plain"> value</span><span class="token punctuation">)</span><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// better</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    input </span><span class="token operator">&gt;&gt;</span><span class="token plain"> value</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// check for errors</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> </span><span class="token function">print</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token operator">&amp;</span><span class="token plain"> output</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token operator">&amp;</span><span class="token plain"> value</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    output </span><span class="token operator">&lt;&lt;</span><span class="token plain"> value </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&quot;\n&quot;</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="enforcement-1"></span><a href="#enforcement-1" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">
10#</span></a></h5><ul><li>Consider functions with more than one &quot;out&quot; parameter suspicious. Use return values instead, including <code>tuple</code> for multiple return values.</li><li>Consider &quot;large&quot; functions that don&#x27;t fit on one editor screen suspicious. Consider factoring such a function into smaller well-named suboperations.</li><li>Consider functions with 7 or more parameters suspicious.</li></ul><h3><span class="subheading-anchor" id="f3-keep-functions-short-and-simple"></span><a href="#f3-keep-functions-short-and-simple" class="text-current no-underline no-outline"><a href="#" name="Rf-single"></a>F.3: Keep functions short and simple<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-2"></span><a href="#reason-2" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Large functions are hard to read, more likely to contain complex code, and more likely to have variables in larger than minimal scopes.
11Functions with complex control structures are more likely to be long and more likely to hide logical errors</p><h5><span class="subheading-anchor" id="example-2"></span><a href="#example-2" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Consider:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">double</span><span class="token plain"> </span><span class="token function">simple_func</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">double</span><span class="token plain"> val</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> flag1</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain">
11 flag2</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// simple_func: takes a value and calculates the expected ASIC output,</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// given the two mode flags.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">double</span><span class="token plain"> intermediate</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">flag1 </span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token number">0</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        intermediate </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">func1</span><span class="token punctuation">(</span><span class="token plain">val</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">flag2 </span><span class="token operator">%</span><span class="token plain"> </span><span class="token number">2</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">             intermediate </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">sqrt</span><span class="token punctuation">(</span><span class="token plain">intermediate</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">else</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">flag1 </span><span class="token operator">==</span><span class="token plain"> </span><span class="token operator">-</span><span class="token number">1</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        intermediate </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">func1</span><span class="token punctuation">(</span><span class="token operator">-</span><span class="token plain">val</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">flag2 </span><span class="token operator">%</span><span class="token plain"> </span><span class="token number">2</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">             intermediate </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">sqrt</span><span class="token punctuation">(</span><span class="token operator">-</span><span class="token plain">intermediate</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        flag1 </span><span class="token operator">=</span><span class="token plain"> </span><span class="token operator">-</span><span class="token plain">flag1</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token function">abs</span><span class="token punctuation">(</span><span class="token plain">
11flag2</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token number">10</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        intermediate </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">func2</span><span class="token punctuation">(</span><span class="token plain">intermediate</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">switch</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">flag2 </span><span class="token operator">/</span><span class="token plain"> </span><span class="token number">10</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">case</span><span class="token plain"> </span><span class="token number">1</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">flag1 </span><span class="token operator">==</span><span class="token plain"> </span><span class="token operator">-</span><span class="token number">1</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token function">finalize</span><span class="token punctuation">(</span><span class="token plain">intermediate</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token number">1.171</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">            </span><span class="token keyword" style="color:#ff0078;font-weight:bold">break</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">case</span><span class="token plain"> </span><span class="token number">2</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token function">finalize</span><span class="token punctuation">(</span><span class="token plain">intermediate</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token number">13.1</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">default</span><span class="token operator">:</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">break</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token function">finalize</span><span class="token punctuation">(</span><span class="token plain">intermediate</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token number">0.</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>This is too complex.
12How would you know if all possible alternatives have been correctly handled?
13Yes, it breaks other rules also.</p><p>We can refactor:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">double</span><span class="token plain"> </span><span class="token function">func1_muon</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">double</span><span class="token plain"> val</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> flag</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ???</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">double</span><span class="token plain"> </span><span class="token function">func1_tau</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">double</span><span class="token plain"> val</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> flag1</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain">
13 flag2</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ???</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">double</span><span class="token plain"> </span><span class="token function">simple_func</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">double</span><span class="token plain"> val</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> flag1</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain">
13 flag2</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// simple_func: takes a value and calculates the expected ASIC output,</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// given the two mode flags.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">flag1 </span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token number">0</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token function">func1_muon</span><span class="token punctuation">(</span><span class="token plain">val</span><span class="token punctuation">,</span><span class="token plain">
13 flag2</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">flag1 </span><span class="token operator">==</span><span class="token plain"> </span><span class="token operator">-</span><span class="token number">1</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token comment" style="color:#999;font-style:italic">// handled by func1_tau: flag1 = -flag1;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token function">func1_tau</span><span class="token punctuation">(</span><span class="token operator">-</span><span class="token plain">val</span><span class="token punctuation">,</span><span class="token plain"> flag1</span><span class="token punctuation">,</span><span class="token plain">
13 flag2</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token number">0.</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="note-1"></span><a href="#note-1" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>&quot;It doesn&#x27;t fit on a screen&quot; is often a good practical definition of &quot;far too large.&quot;
14One-to-five-line functions should be considered normal.</p><h5><span class="subheading-anchor" id="note-2"></span><a href="#note-2" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Break large functions up into smaller cohesive and named functions.
15Small simple functions are easily inlined where the cost of a function call is significant.</p><h5><span class="subheading-anchor" id="enforcement-2"></span><a href="#enforcement-2" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>Flag functions that do not &quot;fit on a screen.&quot;
16How big is a screen? Try 60 lines by 140 characters; that&#x27;s roughly the maximum that&#x27;s comfortable for a book page.</li><li>Flag functions that are too complex. How complex is too complex?
17You could use cyclomatic complexity. Try &quot;more than 10 logical path through.&quot; Count a simple switch as one path.</li></ul><h3><span class="subheading-anchor" id="f4-if-a-function-might-have-to-be-evaluated-at-compile-time-declare-it-constexpr"></span><a href="#f4-if-a-function-might-have-to-be-evaluated-at-compile-time-declare-it-constexpr" class="text-current no-underline no-outline"><a href="#" name="Rf-constexpr"></a>F.4: If a function might have to be evaluated at compile time, declare it <code>constexpr</code><span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-3"></span><a href="#reason-3" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p><code>constexpr</code> is needed to tell the compiler to allow compile-time evaluation.</p><h5><span class="subheading-anchor" id="example-3"></span><a href="#example-3" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>The (in)famous factorial:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">constexpr</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">fac</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> n</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">constexpr</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> max_exp </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">17</span><span class="token punctuation">;</span><span class="token plain">      </span><span class="token comment" style="color:#999;font-style:italic">// constexpr enables max_exp to be used in Expects</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">Expects</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token plain"> </span><span class="token operator">&lt;=</span><span class="token plain">
17 n </span><span class="token operator">&amp;&amp;</span><span class="token plain"> n </span><span class="token operator">&lt;</span><span class="token plain"> max_exp</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// prevent silliness and overflow</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> x </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">1</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">for</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> i </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">2</span><span class="token punctuation">;</span><span class="token plain"> i </span><span class="token operator">&lt;=</span><span class="token plain"> n</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token operator">++</span><span class="token plain">i</span><span class="token punctuation">)</span><span class="token plain"> x </span><span class="token operator">*=</span><span class="token plain"> i</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> x</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>This is C++14.
18For C++11, use a recursive formulation of <code>fac()</code>.</p><h5><span class="subheading-anchor" id="note-3"></span><a href="#note-3" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p><code>constexpr</code> does not guarantee compile-time evaluation;
19it just guarantees that the function can be evaluated at compile time for constant expression arguments if the programmer requires it or the compiler decides to do so to optimize.</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">constexpr</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">min</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> x</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> y</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> x </span><span class="token operator">&lt;</span><span class="token plain"> y </span><span class="token operator">?</span><span class="token plain"> x </span><span class="token operator">:</span><span class="token plain"> y</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">test</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> v</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain">
19 m1 </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">min</span><span class="token punctuation">(</span><span class="token operator">-</span><span class="token number">1</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token number">2</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">            </span><span class="token comment" style="color:#999;font-style:italic">// probably compile-time evaluation</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">constexpr</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> m2 </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">min</span><span class="token punctuation">(</span><span class="token operator">-</span><span class="token number">1</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token number">2</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// compile-time evaluation</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> m3 </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">min</span><span class="token punctuation">(</span><span class="token operator">-</span><span class="token number">1</span><span class="token punctuation">,</span><span class="token plain"> v</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">            </span><span class="token comment" style="color:#999;font-style:italic">// run-time evaluation</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">constexpr</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> m4 </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">min</span><span class="token punctuation">(</span><span class="token operator">-</span><span class="token number">1</span><span class="token punctuation">,</span><span class="token plain"> v</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// error: cannot evaluate at compile time</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="note-4"></span><a href="#note-4" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Don&#x27;t try to make all functions <code>constexpr</code>.
20Most computation is best done at run time.</p><h5><span class="subheading-anchor" id="note-5"></span><a href="#note-5" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Any API that might eventually depend on high-level run-time configuration or
21business logic should not be made <code>constexpr</code>. Such customization can not be
22evaluated by the compiler, and any <code>constexpr</code> functions that depended upon
23that API would have to be refactored or drop <code>constexpr</code>.</p><h5><span class="subheading-anchor" id="enforcement-3"></span><a href="#enforcement-3" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">
23#</span></a></h5><p>Impossible and unnecessary.
24The compiler gives an error if a non-<code>constexpr</code> function is called where a constant is required.</p><h3><span class="subheading-anchor" id="f5-if-a-function-is-very-small-and-time-critical-declare-it-inline"></span><a href="#f5-if-a-function-is-very-small-and-time-critical-declare-it-inline" class="text-current no-underline no-outline"><a href="#" name="Rf-inline"></a>F.5: If a function is very small and time-critical, declare it <code>inline</code><span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-4"></span><a href="#reason-4" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Some optimizers are good at inlining without hints from the programmer, but don&#x27;t rely on it.
25Measure! Over the last 40 years or so, we have been promised compilers that can inline better than humans without hints from humans.
26We are still waiting.
27Specifying inline (explicitly, or implicitly when writing member functions inside a class definition) encourages the compiler to do a better job.</p><h5><span class="subheading-anchor" id="example-4"></span><a href="#example-4" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">inline</span><span class="token plain"> string </span><span class="token function">cat</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> string</span><span class="token operator">&amp;</span><span class="token plain"> s</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> string</span><span class="token operator">&amp;</span><span class="token plain"> s2</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> s </span><span class="token operator">+</span><span class="token plain"> s2</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="exception-1"></span><a href="#exception-1" class="text-current no-underline no-outline">Exception<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Do not put an <code>inline</code> function in what is meant to be a stable interface unless you are certain that it will not change.
28An inline function is part of the ABI.</p><h5><span class="subheading-anchor" id="note-6"></span><a href="#note-6" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p><code>constexpr</code> implies <code>inline</code>.</p><h5><span class="subheading-anchor" id="note-7"></span><a href="#note-7" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Member functions defined in-class are <code>inline</code> by default.</p><h5><span class="subheading-anchor" id="exception-2"></span><a href="#exception-2" class="text-current no-underline no-outline">Exception<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Function templates (including member functions of class templates <code>A&lt;T&gt;::function()</code> and member function templates <code>A::function&lt;T&gt;()</code>) are normally defined in headers and therefore inline.</p><h5><span class="subheading-anchor" id="enforcement-4"></span><a href="#enforcement-4" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">
28#</span></a></h5><p>Flag <code>inline</code> functions that are more than three statements and could have been declared out of line (such as class member functions).</p><h3><span class="subheading-anchor" id="f6-if-your-function-must-not-throw-declare-it-noexcept"></span><a href="#f6-if-your-function-must-not-throw-declare-it-noexcept" class="text-current no-underline no-outline"><a href="#" name="Rf-noexcept"></a>F.6: If your function must not throw, declare it <code>noexcept</code><span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-5"></span><a href="#reason-5" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>If an exception is not supposed to be thrown, the program cannot be assumed to cope with the error and should be terminated as soon as possible. Declaring a function <code>noexcept</code> helps optimizers by reducing the number of alternative execution paths. It also speeds up the exit after failure.</p><h5><span class="subheading-anchor" id="example-5"></span><a href="#example-5" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Put <code>noexcept</code> on every function written completely in C or in any other language without exceptions.
29The C++ Standard Library does that implicitly for all functions in the C Standard Library.</p><h5><span class="subheading-anchor" id="note-8"></span><a href="#note-8" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p><code>constexpr</code> functions can throw when evaluated at run time, so you might need conditional <code>noexcept</code> for some of those.</p><h5><span class="subheading-anchor" id="example-6"></span><a href="#example-6" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>You can use <code>noexcept</code> even on functions that can throw:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">vector</span><span class="token operator">&lt;</span><span class="token plain">string</span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token function">collect</span><span class="token punctuation">(</span><span class="token plain">istream</span><span class="token operator">&amp;</span><span class="token plain"> is</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">noexcept</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    vector</span><span class="token operator">&lt;</span><span class="token plain">string</span><span class="token operator">&gt;</span><span class="token plain"> res</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">for</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">string s</span><span class="token punctuation">;</span><span class="token plain"> is </span><span class="token operator">&gt;&gt;</span><span class="token plain"> s</span><span class="token punctuation">;</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        res</span><span class="token punctuation">.</span><span class="token function">push_back</span><span class="token punctuation">(</span><span class="token plain">s</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> res</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>If <code>collect()</code> runs out of memory, the program crashes.
30Unless the program is crafted to survive memory exhaustion, that might be just the right thing to do;
31<code>terminate()</code> might generate suitable error log information (but after memory runs out it is hard to do anything clever).</p><h5><span class="subheading-anchor" id="note-9"></span><a href="#note-9" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">
31#</span></a></h5><p>You must be aware of the execution environment that your code is running when
32deciding whether to tag a function <code>noexcept</code>, especially because of the issue
33of throwing and allocation. Code that is intended to be perfectly general (like
34the standard library and other utility code of that sort) needs to support
35environments where a <code>bad_alloc</code> exception could be handled meaningfully.
36However, most programs and execution environments cannot meaningfully
37handle a failure to allocate, and aborting the program is the cleanest and
38simplest response to an allocation failure in those cases. If you know that
39your application code cannot respond to an allocation failure, it could be
40appropriate to add <code>noexcept</code> even on functions that allocate.</p><p>Put another way: In most programs, most functions can throw (e.g., because they
41use <code>new</code>, call functions that do, or use library functions that reports failure
42by throwing), so don&#x27;t just sprinkle <code>noexcept</code> all over the place without
43considering whether the possible exceptions can be handled.</p><p><code>noexcept</code> is most useful (and most clearly correct) for frequently used,
44low-level functions.</p><h5><span class="subheading-anchor" id="note-10"></span><a href="#note-10" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Destructors, <code>swap</code> functions, move operations, and default constructors should never throw.
45See also <a href="/class#Rc-default00">(C.44)</a>.</p><h5><span class="subheading-anchor" id="enforcement-5"></span><a href="#enforcement-5" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>Flag functions that are not <code>noexcept</code>, yet cannot throw.</li><li>Flag throwing <code>swap</code>, <code>move</code>, destructors, and default constructors.</li></ul><h3><span class="subheading-anchor" id="f7-for-general-use-take-t-or-t-arguments-rather-than-smart-pointers"></span><a href="#f7-for-general-use-take-t-or-t-arguments-rather-than-smart-pointers" class="text-current no-underline no-outline"><a href="#" name="Rf-smart"></a>F.7: For general use, take <code>T*</code> or <code>T&amp;</code> arguments rather than smart pointers<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-6"></span><a href="#reason-6" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Passing a smart pointer transfers or shares ownership and should only be used when ownership semantics are intended.
46A function that does not manipulate lifetime should take raw pointers or references instead.</p><p>Passing by smart pointer restricts the use of a function to callers that use smart pointers.
47A function that needs a <code>widget</code> should be able to accept any <code>widget</code> object, not just ones whose lifetimes are managed by a particular kind of smart pointer.</p><p>Passing a shared smart pointer (e.g., <code>std::shared_ptr</code>) implies a run-time cost.</p><h5><span class="subheading-anchor" id="example-7"></span><a href="#example-7" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">// accepts any int*</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">*</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// can only accept ints for which you want to transfer ownership</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">g</span><span class="token punctuation">(</span><span class="token plain">unique_ptr</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&gt;</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// can only accept ints for which you are willing to share ownership</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">g</span><span class="token punctuation">(</span><span class="token plain">shared_ptr</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&gt;</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// doesn&#x27;t change ownership, but requires a particular ownership of the caller</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">h</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> unique_ptr</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&gt;</span><span class="token operator">&amp;</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// accepts any int</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">h</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&amp;</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><h5><span class="subheading-anchor" id="example-bad"></span><a href="#example-bad" class="text-current no-underline no-outline">Example, bad<span class="anchor-icon" aria-hidden="true">
47#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">// callee</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token plain">shared_ptr</span><span class="token operator">&lt;</span><span class="token plain">widget</span><span class="token operator">&gt;</span><span class="token operator">&amp;</span><span class="token plain"> w</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">use</span><span class="token punctuation">(</span><span class="token operator">*</span><span class="token plain">w</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// only use of w -- the lifetime is not used at all</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// caller</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">shared_ptr</span><span class="token operator">&lt;</span><span class="token plain">widget</span><span class="token operator">&gt;</span><span class="token plain"> my_widget </span><span class="token operator">=</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">/* ... */</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token function">f</span><span class="token punctuation">(</span><span class="token plain">my_widget</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">widget stack_widget</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token function">f</span><span class="token punctuation">(</span><span class="token plain">
47stack_widget</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// error</span></div></code></pre><h5><span class="subheading-anchor" id="example-good"></span><a href="#example-good" class="text-current no-underline no-outline">Example, good<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">// callee</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token plain">widget</span><span class="token operator">&amp;</span><span class="token plain"> w</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">use</span><span class="token punctuation">(</span><span class="token plain">w</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// caller</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">shared_ptr</span><span class="token operator">&lt;</span><span class="token plain">widget</span><span class="token operator">&gt;</span><span class="token plain"> my_widget </span><span class="token operator">=</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">/* ... */</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token function">f</span><span class="token punctuation">(</span><span class="token operator">*</span><span class="token plain">my_widget</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">widget stack_widget</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token function">f</span><span class="token punctuation">(</span><span class="token plain">
47stack_widget</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// ok -- now this works</span></div></code></pre><h5><span class="subheading-anchor" id="note-11"></span><a href="#note-11" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>We can catch many common cases of dangling pointers statically (see <a href="/profile#SS-lifetime">(lifetime safety profile)</a>). Function arguments naturally live for the lifetime of the function call, and so have fewer lifetime problems.</p><h5><span class="subheading-anchor" id="enforcement-6"></span><a href="#enforcement-6" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>(Simple) Warn if a function takes a parameter of a smart pointer type (that overloads <code>operator-&gt;</code> or <code>operator*</code>) that is copyable but the function only calls any of: <code>operator*</code>, <code>operator-&gt;</code> or <code>get()</code>.
48Suggest using a <code>T*</code> or <code>T&amp;</code> instead.</li><li>Flag a parameter of a smart pointer type (a type that overloads <code>operator-&gt;</code> or <code>operator*</code>) that is copyable/movable but never copied/moved from in the function body, and that is never modified, and that is not passed along to another function that could do so. That means the ownership semantics are not used.
49Suggest using a <code>T*</code> or <code>T&amp;</code> instead.</li></ul><p><strong>See also</strong>:</p><ul><li><a href="/functions#Rf-ptr-ref">(Prefer <code>T*</code> over <code>T&amp;</code> when &quot;no argument&quot; is a valid option)</a></li><li><a href="/resource#Rr-summary-smartptrs">(Smart pointer rule summary)</a></li></ul><h3><span class="subheading-anchor" id="f8-prefer-pure-functions"></span><a href="#f8-prefer-pure-functions" class="text-current no-underline no-outline"><a href="#" name="Rf-pure"></a>F.8: Prefer pure functions<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-7"></span><a href="#reason-7" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Pure functions are easier to reason about, sometimes easier to optimize (and even parallelize), and sometimes can be memoized.</p><h5><span class="subheading-anchor" id="example-8"></span><a href="#example-8" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">template</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">class</span><span class="token plain"> </span><span class="token class-name">T</span><span class="token operator">&gt;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> </span><span class="token function">square</span><span class="token punctuation">(</span><span class="token plain">T t</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> t </span><span class="token operator">*</span><span class="token plain"> t</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="enforcement-7"></span><a href="#enforcement-7" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">
49#</span></a></h5><p>Not possible.</p><h3><span class="subheading-anchor" id="f9-unused-parameters-should-be-unnamed"></span><a href="#f9-unused-parameters-should-be-unnamed" class="text-current no-underline no-outline"><a href="#" name="Rf-unused"></a>F.9: Unused parameters should be unnamed<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-8"></span><a href="#reason-8" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Readability.
50Suppression of unused parameter warnings.</p><h5><span class="subheading-anchor" id="example-9"></span><a href="#example-9" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">widget</span><span class="token operator">*</span><span class="token plain"> </span><span class="token function">find</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> set</span><span class="token operator">&lt;</span><span class="token plain">widget</span><span class="token operator">&gt;</span><span class="token operator">&amp;</span><span class="token plain"> s</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> widget</span><span class="token operator">&amp;</span><span class="token plain"> w</span><span class="token punctuation">,</span><span class="token plain"> Hint</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">   </span><span class="token comment" style="color:#999;font-style:italic">// once upon a time, a hint was used</span></div></code></pre><h5><span class="subheading-anchor" id="note-12"></span><a href="#note-12" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Allowing parameters to be unnamed was introduced in the early 1980 to address this problem.</p><p>If parameters are conditionally unused, declare them with the <code>[[maybe_unused]]</code> attribute.
51For example:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">template</span><span class="token plain"> </span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">typename</span><span class="token plain"> Value</span><span class="token operator">&gt;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">Value</span><span class="token operator">*</span><span class="token plain"> </span><span class="token function">find</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> set</span><span class="token operator">&lt;</span><span class="token plain">Value</span><span class="token operator">&gt;</span><span class="token operator">&amp;</span><span class="token plain"> s</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> Value</span><span class="token operator">&amp;</span><span class="token plain"> v</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token punctuation">[</span><span class="token punctuation">[</span><span class="token plain">maybe_unused</span><span class="token punctuation">]</span><span class="token punctuation">]</span><span class="token plain"> Hint h</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">constexpr</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">sizeof</span><span class="token punctuation">(</span><span class="token plain">Value</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token operator">&gt;</span><span class="token plain"> CacheSize</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token comment" style="color:#999;font-style:italic">// a hint is used only if Value is of a certain size</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="enforcement-8"></span><a href="#enforcement-8" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">
51#</span></a></h5><p>Flag named unused parameters.</p><h2><span class="subheading-anchor" id="fcall-parameter-passing"></span><a href="#fcall-parameter-passing" class="text-current no-underline no-outline"><a href="#" name="SS-call"></a>F.call: Parameter passing<span class="anchor-icon" aria-hidden="true">#</span></a></h2><p>There are a variety of ways to pass parameters to a function and to return values.</p><h3><span class="subheading-anchor" id="f15-prefer-simple-and-conventional-ways-of-passing-information"></span><a href="#f15-prefer-simple-and-conventional-ways-of-passing-information" class="text-current no-underline no-outline"><a href="#" name="Rf-conventional"></a>F.15: Prefer simple and conventional ways of passing information<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-9"></span><a href="#reason-9" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Using &quot;unusual and clever&quot; techniques causes surprises, slows understanding by other programmers, and encourages bugs.
52If you really feel the need for an optimization beyond the common techniques, measure to ensure that it really is an improvement, and document/comment because the improvement might not be portable.</p><p>The following tables summarize the advice in the following Guidelines, F.16-21.</p><p>Normal parameter passing:</p><span style="box-sizing:border-box;display:inline-block;overflow:hidden;width:initial;height:initial;background:none;opacity:1;border:0;margin:0;padding:0;position:relative;max-width:100%"><span style="box-sizing:border-box;display:block;width:initial;height:initial;background:none;opacity:1;border:0;margin:0;padding:0;max-width:100%"><img style="display:block;max-width:100%;width:initial;height:initial;background:none;opacity:1;border:0;margin:0;padding:0" alt="" aria-hidden="true" src="data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%271412%27%20height=%27604%27/%3e"/></span><img alt="Normal parameter passing table" src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" decoding="async" data-nimg="intrinsic" style="position:absolute;top:0;left:0;bottom:0;right:0;box-sizing:border-box;padding:0;border:none;margin:auto;display:block;width:0;height:0;min-width:100%;max-width:100%;min-height:100%;max-height:100%;filter:blur(20px);background-size:cover;background-image:url(&quot;data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAADCAMAAACZFr56AAAAFVBMVEXR1eDFx9Goqrfe4OfEyNnt7vGsssiDybFKAAAABnRSTlP0Kjj8zoEtU3i3AAAACXBIWXMAABcRAAAXEQHKJvM/AAAAG0lEQVQImWNgZWEDAwZmZgYIYGRkZGJiYmQEAASaAD9NjOi6AAAAAElFTkSuQmCC&quot;);background-position:0% 0%"/><noscript><img alt="Normal parameter passing table" srcSet="/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fparam-passing-normal.cbeee628.png&amp;w=1920&amp;q=75 1x, /_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fparam-passing-normal.cbeee628.png&amp;w=3840&amp;q=75 2x" src="/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fparam-passing-normal.cbeee628.png&amp;w=3840&amp;q=75" decoding="async" data-nimg="intrinsic" style="position:absolute;top:0;left:0;bottom:0;right:0;box-sizing:border-box;padding:0;border:none;margin:auto;display:block;width:0;height:0;min-width:100%;max-width:100%;min-height:100%;max-height:100%" loading="lazy"/></noscript></span><p>Advanced parameter passing:</p><span style="box-sizing:border-box;display:inline-block;overflow:hidden;width:initial;height:initial;background:none;opacity:1;border:0;margin:0;padding:0;position:relative;max-width:100%"><span style="box-sizing:border-box;display:block;width:initial;height:initial;background:none;opacity:1;border:0;margin:0;padding:0;max-width:100%"><img style="display:block;max-width:100%;width:initial;height:initial;background:none;opacity:1;border:0;margin:0;padding:0" alt="" aria-hidden="true" src="data:image/svg+xml,%3csvg%20xmlns=%27http://www.w3.org/2000/svg%27%20version=%271.1%27%20width=%271412%27%20height=%27619%27/%3e"/></span><img alt="Advanced parameter passing table" src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" decoding="async" data-nimg="intrinsic" style="position:absolute;top:0;left:0;bottom:0;right:0;box-sizing:border-box;padding:0;border:none;margin:auto;display:block;width:0;height:0;min-width:100%;max-width:100%;min-height:100%;max-height:100%;filter:blur(20px);background-size:cover;background-image:url(&quot;data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAADCAMAAACZFr56AAAAG1BMVEWts8nCyNHU2d7EyNmorsXv7/PT1uHc3+XK0NcDn7CdAAAABnRSTlP7fnPJ+3weHhc5AAAACXBIWXMAABcRAAAXEQHKJvM/AAAAIElEQVQImWNgZWZgYGFgYGBgZ2dj42BjY2NgYmIEASYABDcATOigE0EAAAAASUVORK5CYII=&quot;);background-position:0% 0%"/><noscript><img alt="Advanced parameter passing table" srcSet="/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fparam-passing-advanced.752df229.png&amp;w=1920&amp;q=75 1x, /_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fparam-passing-advanced.752df229.png&amp;w=3840&amp;q=75 2x" src="/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fparam-passing-advanced.752df229.png&amp;w=3840&amp;q=75" decoding="async" data-nimg="intrinsic" style="position:absolute;top:0;left:0;bottom:0;right:0;box-sizing:border-box;padding:0;border:none;margin:auto;display:block;width:0;height:0;min-width:100%;max-width:100%;min-height:100%;max-height:100%" loading="lazy"/></noscript></span>
52<p>Use the advanced techniques only after demonstrating need, and document that need in a comment.</p><p>For passing sequences of characters see <a href="/stdlib#SS-string">(String)</a>.</p><h3><span class="subheading-anchor" id="f16-for-in-parameters-pass-cheaply-copied-types-by-value-and-others-by-reference-to-const"></span><a href="#f16-for-in-parameters-pass-cheaply-copied-types-by-value-and-others-by-reference-to-const" class="text-current no-underline no-outline"><a href="#" name="Rf-in"></a>F.16: For &quot;in&quot; parameters, pass cheaply-copied types by value and others by reference to <code>const</code><span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-10"></span><a href="#reason-10" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Both let the caller know that a function will not modify the argument, and both allow initialization by rvalues.</p><p>What is &quot;cheap to copy&quot; depends on the machine architecture, but two or three words (doubles, pointers, references) are usually best passed by value.
53When copying is cheap, nothing beats the simplicity and safety of copying, and for small objects (up to two or three words) it is also faster than passing by reference because it does not require an extra indirection to access from the function.</p><h5><span class="subheading-anchor" id="example-10"></span><a href="#example-10" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">f1</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> string</span><span class="token operator">&amp;</span><span class="token plain"> s</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// OK: pass by reference to const; always cheap</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">f2</span><span class="token punctuation">(</span><span class="token plain">string s</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">         </span><span class="token comment" style="color:#999;font-style:italic">// bad: potentially expensive</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">f3</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> x</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">            </span><span class="token comment" style="color:#999;font-style:italic">// OK: Unbeatable</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">f4</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&amp;</span><span class="token plain"> x</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">     </span><span class="token comment" style="color:#999;font-style:italic">// bad: overhead on access in f4()</span></div></code></pre><p>For advanced uses (only), where you really need to optimize for rvalues passed to &quot;input-only&quot; parameters:</p><ul><li>If the function is going to unconditionally move from the argument, take it by <code>&amp;&amp;</code>. See <a href="/functions#Rf-consume">(F.18)</a>.</li><li>If the function is going to keep a copy of the argument, in addition to passing by <code>const&amp;</code> (for lvalues),
54add an overload that passes the parameter by <code>&amp;&amp;</code> (for rvalues) and in the body <code>std::move</code>s it to its destination. Essentially this overloads a &quot;will-move-from&quot;; see <a href="/functions#Rf-consume">(F.18)</a>.</li><li>In special cases, such as multiple &quot;input + copy&quot; parameters, consider using perfect forwarding. See <a href="/functions#Rf-forward">(F.19)</a>.</li></ul><h5><span class="subheading-anchor" id="example-11"></span><a href="#example-11" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">
54#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">multiply</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// just input ints, pass by value</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// suffix is input-only but not as cheap as an int, pass by const&amp;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">string</span><span class="token operator">&amp;</span><span class="token plain"> </span><span class="token function">concatenate</span><span class="token punctuation">(</span><span class="token plain">string</span><span class="token operator">&amp;</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> string</span><span class="token operator">&amp;</span><span class="token plain"> suffix</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">sink</span><span class="token punctuation">(</span><span class="token plain">unique_ptr</span><span class="token operator">&lt;</span><span class="token plain">widget</span><span class="token operator">&gt;</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// input only, and moves ownership of the widget</span></div></code></pre><p>Avoid &quot;esoteric techniques&quot; such as passing arguments as <code>T&amp;&amp;</code> &quot;for efficiency&quot;.
55Most rumors about performance advantages from passing by <code>&amp;&amp;</code> are false or brittle (but see <a href="/functions#Rf-consume">((F.18)</a> and <a href="/functions#Rf-forward">F.19)</a>).</p><h5><span class="subheading-anchor" id="notes"></span><a href="#notes" class="text-current no-underline no-outline">Notes<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>A reference can be assumed to refer to a valid object (language rule).
56There is no (legitimate) &quot;null reference.&quot;
57If you need the notion of an optional value, use a pointer, <code>std::optional</code>, or a special value used to denote &quot;no value.&quot;</p><h5><span class="subheading-anchor" id="enforcement-9"></span><a href="#enforcement-9" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>(Simple) ((Foundation)) Warn when a parameter being passed by value has a size greater than <code>2 * sizeof(void*)</code>.
58Suggest using a reference to <code>const</code> instead.</li><li>(Simple) ((Foundation)) Warn when a parameter passed by reference to <code>const</code> has a size less than <code>2 * sizeof(void*)</code>. Suggest passing by value instead.</li><li>(Simple) ((Foundation)) Warn when a parameter passed by reference to <code>const</code> is <code>move</code>d.</li></ul><h3><span class="subheading-anchor" id="f17-for-in-out-parameters-pass-by-reference-to-non-const"></span><a href="#f17-for-in-out-parameters-pass-by-reference-to-non-const" class="text-current no-underline no-outline"><a href="#" name="Rf-inout"></a>F.17: For &quot;in-out&quot; parameters, pass by reference to non-<code>const</code><span class="anchor-icon" aria-hidden="true">
58#</span></a></h3><h5><span class="subheading-anchor" id="reason-11"></span><a href="#reason-11" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>This makes it clear to callers that the object is assumed to be modified.</p><h5><span class="subheading-anchor" id="example-12"></span><a href="#example-12" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">update</span><span class="token punctuation">(</span><span class="token plain">Record</span><span class="token operator">&amp;</span><span class="token plain"> r</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// assume that update writes to r</span></div></code></pre><h5><span class="subheading-anchor" id="note-13"></span><a href="#note-13" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>A <code>T&amp;</code> argument can pass information into a function as well as out of it.
59Thus <code>T&amp;</code> could be an in-out-parameter. That can in itself be a problem and a source of errors:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token plain">string</span><span class="token operator">&amp;</span><span class="token plain"> s</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    s </span><span class="token operator">=</span><span class="token plain"> </span><span class="token string">&quot;New York&quot;</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// non-obvious error</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">g</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    string buffer </span><span class="token operator">=</span><span class="token plain"> </span><span class="token string">&quot;.................................&quot;</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token plain">buffer</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>Here, the writer of <code>g()</code> is supplying a buffer for <code>
59f()</code> to fill, but <code>f()</code> simply replaces it (at a somewhat higher cost than a simple copy of the characters).
60A bad logic error can happen if the writer of <code>g()</code> incorrectly assumes the size of the <code>buffer</code>.</p><h5><span class="subheading-anchor" id="enforcement-10"></span><a href="#enforcement-10" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>(Moderate) ((Foundation)) Warn about functions regarding reference to non-<code>const</code> parameters that do <em>not</em> write to them.</li><li>(Simple) ((Foundation)) Warn when a non-<code>const</code> parameter being passed by reference is <code>move</code>d.</li></ul><h3><span class="subheading-anchor" id="f18-for-will-move-from-parameters-pass-by-x-and-stdmove-the-parameter"></span><a href="#f18-for-will-move-from-parameters-pass-by-x-and-stdmove-the-parameter" class="text-current no-underline no-outline"><a href="#" name="Rf-consume"></a>F.18: For &quot;will-move-from&quot; parameters, pass by <code>X&amp;&amp;</code> and <code>std::move</code> the parameter<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-12"></span><a href="#reason-12" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>It&#x27;s efficient and eliminates bugs at the call site: <code>X&amp;&amp;</code> binds to rvalues, which requires an explicit <code>std::move</code> at the call site if passing an lvalue.</p><h5><span class="subheading-anchor" id="example-13"></span><a href="#example-13" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">sink</span><span class="token punctuation">(</span><span class="token plain">vector</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&gt;</span><span class="token operator">&amp;&amp;</span><span class="token plain"> v</span><span class="token punctuation">)</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// sink takes ownership of whatever the argument owned</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// usually there might be const accesses of v here</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">store_somewhere</span><span class="token punctuation">(</span><span class="token plain">std</span><span class="token operator">::</span><span class="token function">move</span><span class="token punctuation">(</span><span class="token plain">v</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// usually no more use of v here; it is moved-from</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>Note that the <code>std::move(v)</code> makes it possible for <code>store_somewhere()</code> to leave <code>v</code> in a moved-from state.
61<a href="/class#Rc-move-semantic">(That could be dangerous)</a>.</p><h5><span class="subheading-anchor" id="exception-3"></span><a href="#exception-3" class="text-current no-underline no-outline">Exception<span class="anchor-icon" aria-hidden="true">
61#</span></a></h5><p>Unique owner types that are move-only and cheap-to-move, such as <code>unique_ptr</code>, can also be passed by value which is simpler to write and achieves the same effect. Passing by value does generate one extra (cheap) move operation, but prefer simplicity and clarity first.</p><p>For example:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">template</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">class</span><span class="token plain"> </span><span class="token class-name">T</span><span class="token operator">&gt;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">sink</span><span class="token punctuation">(</span><span class="token plain">std</span><span class="token operator">::</span><span class="token plain">unique_ptr</span><span class="token operator">&lt;</span><span class="token plain">T</span><span class="token operator">&gt;</span><span class="token plain"> p</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">
61// use p ... possibly std::move(p) onward somewhere else</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain">   </span><span class="token comment" style="color:#999;font-style:italic">// p gets destroyed</span></div></code></pre><h5><span class="subheading-anchor" id="enforcement-11"></span><a href="#enforcement-11" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>Flag all <code>X&amp;&amp;</code> parameters (where <code>X</code> is not a template type parameter name) where the function body uses them without <code>std::move</code>.</li><li>Flag access to moved-from objects.</li><li>Don&#x27;t conditionally move from objects</li></ul><h3><span class="subheading-anchor" id="f19-for-forward-parameters-pass-by-tp-and-only-stdforward-the-parameter"></span><a href="#f19-for-forward-parameters-pass-by-tp-and-only-stdforward-the-parameter" class="text-current no-underline no-outline"><a href="#" name="Rf-forward"></a>F.19: For &quot;forward&quot; parameters, pass by <code>TP&amp;&amp;</code> and only <code>std::forward</code> the parameter<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-13"></span><a href="#reason-13" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>If the object is to be passed onward to other code and not directly used by this function, we want to make this function agnostic to the argument <code>const</code>-ness and rvalue-ness.</p><p>In that case, and only that case, make the parameter <code>TP&amp;&amp;</code> where <code>TP</code> is a template type parameter -- it both <em>ignores</em> and <em>preserves</em> <code>const</code>-ness and rvalue-ness. Therefore any code that uses a <code>TP&amp;&amp;</code> is implicitly declaring that it itself doesn&#x27;t care about the variable&#x27;s <code>const</code>-ness and rvalue-ness (because it is ignored), but that intends to pass the value onward to other code that does care about <code>const</code>-ness and rvalue-ness (because it is preserved). When used as a parameter <code>TP&amp;&amp;</code> is safe because any temporary objects passed from the caller will live for the duration of the function call. A parameter of type <code>TP&amp;&amp;</code> should essentially always be passed onward via <code>std::forward</code> in the body of the function.</p><h5><span class="subheading-anchor" id="example-14"></span><a href="#example-14" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">template</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">class</span><span class="token plain"> </span><span class="token class-name">F</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">class</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token plain"> Args</span><span class="token operator">&gt;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">inline</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> </span><span class="token function">invoke</span><span class="token punctuation">(</span><span class="token plain">F f</span><span class="token punctuation">,</span><span class="token plain"> Args</span><span class="token operator">&amp;&amp;</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token plain"> args</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token plain">forward</span><span class="token operator">&lt;</span><span class="token plain">Args</span><span class="token operator">&gt;</span><span class="token punctuation">(</span><span class="token plain">args</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token operator">?</span><span class="token operator">?</span><span class="token operator">?</span><span class="token plain"> calls </span><span class="token operator">?</span><span class="token operator">?</span><span class="token operator">?</span></div></code></pre><h5><span class="subheading-anchor" id="enforcement-12"></span><a href="#enforcement-12" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">
61#</span></a></h5><ul><li>Flag a function that takes a <code>TP&amp;&amp;</code> parameter (where <code>TP</code> is a template type parameter name) and does anything with it other than <code>std::forward</code>ing it exactly once on every static path.</li></ul><h3><span class="subheading-anchor" id="f20-for-out-output-values-prefer-return-values-to-output-parameters"></span><a href="#f20-for-out-output-values-prefer-return-values-to-output-parameters" class="text-current no-underline no-outline"><a href="#" name="Rf-out"></a>F.20: For &quot;out&quot; output values, prefer return values to output parameters<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-14"></span><a href="#reason-14" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>A return value is self-documenting, whereas a <code>&amp;</code> could be either in-out or out-only and is liable to be misused.</p><p>This includes large objects like standard containers that use implicit move operations for performance and to avoid explicit memory management.</p><p>If you have multiple values to return, <a href="/functions#Rf-out-multi">(use a tuple)</a> or similar multi-member type.</p><h5><span class="subheading-anchor" id="example-15"></span><a href="#example-15" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">// OK: return pointers to elements with the value x</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">vector</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">*</span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token function">find_all</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> vector</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&gt;</span><span class="token operator">&amp;</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> x</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// Bad: place pointers to elements with value x in-out</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">find_all</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> vector</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&gt;</span><span class="token operator">&amp;</span><span class="token punctuation">,</span><span class="token plain"> vector</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">*</span><span class="token operator">&gt;</span><span class="token operator">&amp;</span><span class="token plain"> out</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> x</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><h5><span class="subheading-anchor" id="note-14"></span><a href="#note-14" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">
61#</span></a></h5><p>A <code>struct</code> of many (individually cheap-to-move) elements might be in aggregate expensive to move.</p><h5><span class="subheading-anchor" id="note-15"></span><a href="#note-15" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>It is not recommended to return a <code>const</code> value.
62Such older advice is now obsolete; it does not add value, and it interferes with move semantics.</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> vector</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token function">fct</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// bad: that &quot;const&quot; is more trouble than it is worth</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">g</span><span class="token punctuation">(</span><span class="token plain">vector</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&gt;</span><span class="token operator">&amp;</span><span class="token plain"> vx</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">fct</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> vx</span><span class="token punctuation">;</span><span class="token plain">   </span><span class="token comment" style="color:#999;font-style:italic">// prevented by the &quot;const&quot;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    vx </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">fct</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// expensive copy: move semantics suppressed by the &quot;const&quot;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>The argument for adding <code>const</code> to a return value is that it prevents (very rare) accidental access to a temporary.
63The argument against is that it prevents (very frequent) use of move semantics.</p><h5><span class="subheading-anchor" id="exceptions"></span><a href="#exceptions" class="text-current no-underline no-outline">Exceptions<span class="anchor-icon" aria-hidden="true">
63#</span></a></h5><ul><li>For non-concrete types, such as types in an inheritance hierarchy, return the object by <code>unique_ptr</code> or <code>shared_ptr</code>.</li><li>If a type is expensive to move (e.g., <code>array&lt;BigPOD&gt;</code>), consider allocating it on the free store and return a handle (e.g., <code>unique_ptr</code>), or passing it in a reference to non-<code>const</code> target object to fill (to be used as an out-parameter).</li><li>To reuse an object that carries capacity (e.g., <code>std::string</code>, <code>std::vector</code>) across multiple calls to the function in an inner loop: <a href="/functions#Rf-out-multi">(treat it as an in/out parameter and pass by reference)</a>.</li></ul><h5><span class="subheading-anchor" id="example-16"></span><a href="#example-16" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Assuming that <code>Matrix</code> has move operations (possibly by keeping its elements in a <code>std::vector</code>):</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">Matrix </span><span class="token keyword" style="color:#ff0078;font-weight:bold">operator</span><span class="token operator">+</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> Matrix</span><span class="token operator">&amp;</span><span class="token plain"> a</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> Matrix</span><span class="token operator">&amp;</span><span class="token plain"> b</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    Matrix res</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ... fill res with the sum ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> res</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">Matrix x </span><span class="token operator">=</span><span class="token plain"> m1 </span><span class="token operator">+</span><span class="token plain"> m2</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// move constructor</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">y </span><span class="token operator">=</span><span class="token plain"> m3 </span><span class="token operator">+</span><span class="token plain"> m3</span><span class="token punctuation">;</span><span class="token plain">         </span><span class="token comment" style="color:#999;font-style:italic">// move assignment</span></div></code></pre><h5><span class="subheading-anchor" id="note-16"></span><a href="#note-16" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>The return value optimization doesn&#x27;t handle the assignment case, but the move assignment does.</p><h5><span class="subheading-anchor" id="example-17"></span><a href="#example-17" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">
63#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">struct</span><span class="token plain"> </span><span class="token class-name">Package</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain">      </span><span class="token comment" style="color:#999;font-style:italic">// exceptional case: expensive-to-move object</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">char</span><span class="token plain"> header</span><span class="token punctuation">[</span><span class="token number">16</span><span class="token punctuation">]</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">char</span><span class="token plain"> load</span><span class="token punctuation">[</span><span class="token number">2024</span><span class="token plain"> </span><span class="token operator">-</span><span class="token plain"> </span><span class="token number">16</span><span class="token punctuation">]</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">Package </span><span class="token function">fill</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">       </span><span class="token comment" style="color:#999;font-style:italic">// Bad: large return value</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">fill</span><span class="token punctuation">(</span><span class="token plain">Package</span><span class="token operator">&amp;</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// OK</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">val</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">            </span><span class="token comment" style="color:#999;font-style:italic">// OK</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">val</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&amp;</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">       </span><span class="token comment" style="color:#999;font-style:italic">// Bad: Is val reading its argument</span></div></code></pre><h5><span class="subheading-anchor" id="enforcement-13"></span><a href="#enforcement-13" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>Flag reference to non-<code>const</code> parameters that are not read before being written to and are a type that c
63ould be cheaply returned; they should be &quot;out&quot; return values.</li><li>Flag returning a <code>const</code> value. To fix: Remove <code>const</code> to return a non-<code>const</code> value instead.</li></ul><h3><span class="subheading-anchor" id="f21-to-return-multiple-out-values-prefer-returning-a-struct-or-tuple"></span><a href="#f21-to-return-multiple-out-values-prefer-returning-a-struct-or-tuple" class="text-current no-underline no-outline"><a href="#" name="Rf-out-multi"></a>F.21: To return multiple &quot;out&quot; values, prefer returning a struct or tuple<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-15"></span><a href="#reason-15" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>A return value is self-documenting as an &quot;output-only&quot; value.
64Note that C++ does have multiple return values, by convention of using a <code>tuple</code> (including <code>pair</code>), possibly with the extra convenience of <code>tie</code> or structured bindings (C++17) at the call site.
65Prefer using a named struct where there are semantics to the returned value. Otherwise, a nameless <code>tuple</code> is useful in generic code.</p><h5><span class="subheading-anchor" id="example-18"></span><a href="#example-18" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">// BAD: output-only parameter documented in a comment</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> string</span><span class="token operator">&amp;</span><span class="token plain"> input</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">/*output only*/</span><span class="token plain"> string</span><span class="token operator">&amp;</span><span class="token plain"> output_data</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    output_data </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">something</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> status</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// GOOD: self-documenting</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">tuple</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token punctuation">,</span><span class="token plain"> string</span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> string</span><span class="token operator">&amp;</span><span class="token plain"> input</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">
65// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token function">make_tuple</span><span class="token punctuation">(</span><span class="token plain">status</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token function">something</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>C++98&#x27;s standard library already used this style, because a <code>pair</code> is like a two-element <code>tuple</code>.
66For example, given a <code>set&lt;string&gt; my_set</code>, consider:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">// C++98</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">result </span><span class="token operator">=</span><span class="token plain"> my_set</span><span class="token punctuation">.</span><span class="token function">insert</span><span class="token punctuation">(</span><span class="token string">&quot;Hello&quot;</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">result</span><span class="token punctuation">.</span><span class="token plain">second</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token function">do_something_with</span><span class="token punctuation">(</span><span class="token plain">result</span><span class="token punctuation">.</span><span class="token plain">first</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// workaround</span></div></code></pre><p>With C++11 we can write this, putting the results directly in existing local variables:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">Sometype iter</span><span class="token punctuation">;</span><span class="token plain">                                </span><span class="token comment" style="color:#999;font-style:italic">// default initialize if we haven&#x27;t already</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">Someothertype success</span><span class="token punctuation">;</span><span class="token plain">                        </span><span class="token comment" style="color:#999;font-style:italic">// used these variables for some other purpose</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token function">tie</span><span class="token punctuation">(</span><span class="token plain">iter</span><span class="token punctuation">,</span><span class="token plain"> success</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> my_set</span><span class="token punctuation">.</span><span class="token function">insert</span><span class="token punctuation">(</span><span class="token string">&quot;Hello&quot;</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">   </span><span class="token comment" style="color:#999;font-style:italic">// normal return value</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">success</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token function">do_something_with</span><span class="token punctuation">(</span><span class="token plain">iter</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><p>With C++17 we are able to use &quot;structured bindings&quot; to declare and initialize the multiple variables:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> </span><span class="token punctuation">[</span><span class="token plain"> iter</span><span class="token punctuation">,</span><span class="token plain"> success </span><span class="token punctuation">]</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> my_set</span><span class="token punctuation">.</span><span class="token function">insert</span><span class="token punctuation">(</span><span class="token string">&quot;Hello&quot;</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> success</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token function">do_something_with</span><span class="token punctuation">(</span><span class="token plain">iter</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><h5><span class="subheading-anchor" id="exception-4"></span><a href="#exception-4" class="text-current no-underline no-outline">Exception<span class="anchor-icon" aria-hidden="true">
66#</span></a></h5><p>Sometimes, we need to pass an object to a function to manipulate its state.
67In such cases, passing the object by reference <a href="/functions#Rf-inout">(<code>T&amp;</code>)</a> is usually the right technique.
68Explicitly passing an in-out parameter back out again as a return value is often not necessary.
69For example:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">istream</span><span class="token operator">&amp;</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">operator</span><span class="token operator">&gt;&gt;</span><span class="token punctuation">(</span><span class="token plain">istream</span><span class="token operator">&amp;</span><span class="token plain"> is</span><span class="token punctuation">,</span><span class="token plain"> string</span><span class="token operator">&amp;</span><span class="token plain"> s</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// much like std::operator&gt;&gt;()</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">for</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">string s</span><span class="token punctuation">;</span><span class="token plain"> cin </span><span class="token operator">&gt;&gt;</span><span class="token plain"> s</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// do something with line</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>Here, both <code>s</code> and <code>cin</code> are used as in-out parameters.
70We pass <code>cin</code> by (non-<code>const</code>) reference to be able to manipulate its state.
71We pass <code>s</code> to avoid repeated allocations.
72By reusing <code>s</code> (passed by reference), we allocate new memory only when we need to expand <code>s</code>&#x27;s capacity.
73This technique is sometimes called the &quot;caller-allocated out&quot; pattern and is particularly useful for types,
74such as <code>string</code> and <code>vector</code>, that needs to do free store allocations.</p><p>To compare, if we passed out all values as return values, we would something like this:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">pair</span><span class="token operator">&lt;</span><span class="token plain">istream</span><span class="token operator">&amp;</span><span class="token punctuation">,</span><span class="token plain"> string</span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token function">get_string</span><span class="token punctuation">(</span><span class="token plain">istream</span><span class="token operator">&amp;</span><span class="token plain"> is</span><span class="token punctuation">)</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// not recommended</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    string s</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    is </span><span class="token operator">&gt;&gt;</span><span class="token plain"> s</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain">is</span><span class="token punctuation">,</span><span class="token plain"> s</span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">for</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> p </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">get_string</span><span class="token punctuation">(</span><span class="token plain">cin</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> p</span><span class="token punctuation">.</span><span class="token plain">first</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// do something with p.second</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>We consider that significantly less elegant with significantly less performance.</p><p>For a truly strict reading of this rule (F.21), the exception isn&#x27;t really an exception because it relies on in-out parameters,
75rather than the plain out parameters mentioned in the rule.
76However, we prefer to be explicit, rather than subtle.</p><h5><span class="subheading-anchor" id="note-17"></span><a href="#note-17" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">
76#</span></a></h5><p>In many cases, it can be useful to return a specific, user-defined type.
77For example:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">struct</span><span class="token plain"> </span><span class="token class-name">Distance</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> value</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> unit </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">1</span><span class="token punctuation">;</span><span class="token plain">   </span><span class="token comment" style="color:#999;font-style:italic">// 1 means meters</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">Distance d1 </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">measure</span><span class="token punctuation">(</span><span class="token plain">obj1</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">        </span><span class="token comment" style="color:#999;font-style:italic">// access d1.value and d1.unit</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> d2 </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">measure</span><span class="token punctuation">(</span><span class="token plain">obj2</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">            </span><span class="token comment" style="color:#999;font-style:italic">// access d2.value and d2.unit</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> </span><span class="token punctuation">[</span><span class="token plain">value</span><span class="token punctuation">,</span><span class="token plain"> unit</span><span class="token punctuation">]</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">measure</span><span class="token punctuation">(</span><span class="token plain">obj3</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// access value and unit; somewhat redundant</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">                                    </span><span class="token comment" style="color:#999;font-style:italic">// to people who know measure()</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> </span><span class="token punctuation">[</span><span class="token plain">x</span><span class="token punctuation">,</span><span class="token plain"> y</span><span class="token punctuation">]</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">measure</span><span class="token punctuation">(</span><span class="token plain">obj4</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">        </span><span class="token comment" style="color:#999;font-style:italic">// don&#x27;t; it&#x27;s likely to be confusing</span></div></code></pre><p>The overly-generic <code>pair</code> and <code>tuple</code> should be used only when the value returned represents independent entities rather than an abstraction.</p><p>Another example, use a specific type along the lines of <code>variant&lt;T, error_code&gt;</code>, rather than using the generic <code>tuple</code>.</p><h5><span class="subheading-anchor" id="enforcement-14"></span><a href="#enforcement-14" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">
77#</span></a></h5><ul><li>Output parameters should be replaced by return values.
78An output parameter is one that the function writes to, invokes a non-<code>const</code> member function, or passes on as a non-<code>const</code>.</li></ul><h3><span class="subheading-anchor" id="f60-prefer-t-over-t-when-no-argument-is-a-valid-option"></span><a href="#f60-prefer-t-over-t-when-no-argument-is-a-valid-option" class="text-current no-underline no-outline"><a href="#" name="Rf-ptr-ref"></a>F.60: Prefer <code>T*</code> over <code>T&amp;</code> when &quot;no argument&quot; is a valid option<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-16"></span><a href="#reason-16" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>A pointer (<code>T*</code>) can be a <code>nullptr</code> and a reference (<code>T&amp;</code>) cannot, there is no valid &quot;null reference&quot;.
79Sometimes having <code>nullptr</code> as an alternative to indicated &quot;no object&quot; is useful, but if it is not, a reference is notationally simpler and might yield better code.</p><h5><span class="subheading-anchor" id="example-19"></span><a href="#example-19" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">string </span><span class="token function">zstring_to_string</span><span class="token punctuation">(</span><span class="token plain">zstring p</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// zstring is a char*; that is a C-style string</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token operator">!</span><span class="token plain">p</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> string</span><span class="token punctuation">{</span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// p might be nullptr; remember to check</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> string</span><span class="token punctuation">{</span><span class="token plain">p</span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">print</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> vector</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&gt;</span><span class="token operator">&amp;</span><span class="token plain"> r</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// r refers to a vector&lt;int&gt;; no check needed</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="note-18"></span><a href="#note-18" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">
79#</span></a></h5><p>It is possible, but not valid C++ to construct a reference that is essentially a <code>nullptr</code> (e.g., <code>T* p = nullptr; T&amp; r = *p;</code>).
80That error is very uncommon.</p><h5><span class="subheading-anchor" id="note-19"></span><a href="#note-19" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>If you prefer the pointer notation (<code>-&gt;</code> and/or <code>*</code> vs. <code>.</code>), <code>not_null&lt;T*&gt;</code> provides the same guarantee as <code>T&amp;</code>.</p><h5><span class="subheading-anchor" id="enforcement-15"></span><a href="#enforcement-15" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>Flag ???</li></ul><h3><span class="subheading-anchor" id="f22-use-t-or-ownert-to-designate-a-single-object"></span><a href="#f22-use-t-or-ownert-to-designate-a-single-object" class="text-current no-underline no-outline"><a href="#" name="Rf-ptr"></a>F.22: Use <code>T*</code> or <code>owner&lt;T*&gt;</code> to designate a single object<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-17"></span><a href="#reason-17" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Readability: it makes the meaning of a plain pointer clear.
81Enables significant tool support.</p><h5><span class="subheading-anchor" id="note-20"></span><a href="#note-20" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>In traditional C and C++ code, plain <code>T*</code> is used for many weakly-related purposes, such as:</p><ul><li>Identify a (single) object (not to be deleted by this function)</li><li>Point to an object allocated on the free store (and delete it later)</li><li>Hold the <code>nullptr</code></li><li>Identify a C-style string (zero-terminated array of characters)</li><li>Identify an array with a length specified separately</li><li>Identify a location in an array</li></ul><p>This makes it hard to understand what the code does and is supposed to do.
82It complicates checking and tool support.</p><h5><span class="subheading-anchor" id="example-20"></span><a href="#example-20" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">use</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">*</span><span class="token plain"> p</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> n</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">char</span><span class="token operator">*</span><span class="token plain"> s</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">*</span><span class="token plain"> q</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    p</span><span class="token punctuation">[</span><span class="token plain">n </span><span class="token operator">-</span><span class="token plain"> </span><span class="token number">1</span><span class="token punctuation">]</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">666</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// Bad: we don&#x27;t know if p points to n elements;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">                    </span><span class="token comment" style="color:#999;font-style:italic">// assume it does not or use span&lt;int&gt;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    cout </span><span class="token operator">&lt;&lt;</span><span class="token plain"> s</span><span class="token punctuation">;</span><span class="token plain">      </span><span class="token comment" style="color:#999;font-style:italic">// Bad: we don&#x27;t know if that s points to a zero-terminated array of char;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">                    </span><span class="token comment" style="color:#999;font-style:italic">// assume it does not or use zstring</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">delete</span><span class="token plain"> q</span><span class="token punctuation">;</span><span class="token plain">       </span><span class="token comment" style="color:#999;font-style:italic">// Bad: we don&#x27;t know if *q is allocated on the free store;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">                    </span><span class="token comment" style="color:#999;font-style:italic">// assume it does not or use owner</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>better</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">use2</span><span class="token punctuation">(</span><span class="token plain">span</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&gt;</span><span class="token plain"> p</span><span class="token punctuation">,</span><span class="token plain"> zstring s</span><span class="token punctuation">,</span><span class="token plain"> owner</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">*</span><span class="token operator">&gt;</span><span class="token plain"> q</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    p</span><span class="token punctuation">[</span><span class="token plain">p</span><span class="token punctuation">.</span><span class="token function">size</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token operator">-</span><span class="token plain"> </span><span class="token number">1</span><span class="token punctuation">]</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">666</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// OK, a range error can be caught</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    cout </span><span class="token operator">&lt;&lt;</span><span class="token plain"> s</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// OK</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">delete</span><span class="token plain"> q</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// OK</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="note-21"></span><a href="#note-21" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">
82#</span></a></h5><p><code>owner&lt;T*&gt;</code> represents ownership, <code>zstring</code> represents a C-style string.</p><p><strong>Also</strong>: Assume that a <code>T*</code> obtained from a smart pointer to <code>T</code> (e.g., <code>unique_ptr&lt;T&gt;</code>) points to a single element.</p><p><strong>See also</strong>: <a href="/gsl#S-gsl">(Support library)</a></p><p><strong>See also</strong>: <a href="/interfaces#Ri-array">(Do not pass an array as a single pointer)</a></p><h5><span class="subheading-anchor" id="enforcement-16"></span><a href="#enforcement-16" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>(Simple) ((Bounds)) Warn for any arithmetic operation on an expression of pointer type that results in a value of pointer type.</li></ul><h3><span class="subheading-anchor" id="f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value"></span><a href="#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value" class="text-current no-underline no-outline"><a href="#" name="Rf-nullptr"></a>F.23: Use a <code>not_null&lt;T&gt;</code> to indicate that &quot;null&quot; is not a valid value<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-18"></span><a href="#reason-18" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Clarity. A function with a <code>not_null&lt;T&gt;</code> parameter makes it clear that the caller of the function is responsible for any <code>nullptr</code> checks that might be necessary.
83Similarly, a function with a return value of <code>not_null&lt;T&gt;</code> makes it clear that the caller of the function does not need to check for <code>nullptr</code>.</p><h5><span class="subheading-anchor" id="example-21"></span><a href="#example-21" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p><code>not_null&lt;T*&gt;</code> makes it obvious to a reader (human or machine) that a test for <code>nullptr</code> is not necessary before dereference.
84Additionally, when debugging, <code>owner&lt;T*&gt;</code> and <code>not_null&lt;T&gt;</code>
84 can be instrumented to check for correctness.</p><p>Consider:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">length</span><span class="token punctuation">(</span><span class="token plain">Record</span><span class="token operator">*</span><span class="token plain"> p</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><p>When I call <code>length(p)</code> should I check if <code>p</code> is <code>nullptr</code> first? Should the implementation of <code>length()</code> check if <code>p</code> is <code>nullptr</code>?</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">// it is the caller&#x27;s job to make sure p != nullptr</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">length</span><span class="token punctuation">(</span><span class="token plain">not_null</span><span class="token operator">&lt;</span><span class="token plain">Record</span><span class="token operator">*</span><span class="token operator">&gt;</span><span class="token plain"> p</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// the implementor of length() must assume that p == nullptr is possible</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">length</span><span class="token punctuation">(</span><span class="token plain">Record</span><span class="token operator">*</span><span class="token plain"> p</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><h5><span class="subheading-anchor" id="note-22"></span><a href="#note-22" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>A <code>not_null&lt;T*&gt;</code> is assumed not to be the <code>nullptr</code>; a <code>T*</code> might be the <code>nullptr</code>; both can be represented in memory as a <code>T*</code> (so no run-time overhead is implied).</p><h5><span class="subheading-anchor" id="note-23"></span><a href="#note-23" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p><code>not_null</code> is not just for built-in pointers. It works for <code>unique_ptr</code>, <code>shared_ptr</code>, and other pointer-like types.</p><h5><span class="subheading-anchor" id="enforcement-17"></span><a href="#enforcement-17" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>(Simple) Warn if a raw pointer is dereferenced without being tested against <code>nullptr</code> (or equivalent) within a function, suggest it is declared <code>not_null</code> instead.</li><li>(Simple) Error if a raw pointer is sometimes dereferenced after first being tested against <code>nullptr</code> (or equivalent) within the function and sometimes is not.</li><li>(Simple) Warn if a <code>not_null</code> pointer is tested against <code>nullptr</code> within a function.</li></ul><h3><span class="subheading-anchor" id="f24-use-a-spant-or-a-span_pt-to-designate-a-half-open-sequence"></span><a href="#f24-use-a-spant-or-a-span_pt-to-designate-a-half-open-sequence" class="text-current no-underline no-outline"><a href="#" name="Rf-range"></a>F.24: Use a <code>span&lt;T&gt;</code> or a <code>span_p&lt;T&gt;</code> to designate a half-open sequence<span class="anchor-icon" aria-hidden="true">
84#</span></a></h3><h5><span class="subheading-anchor" id="reason-19"></span><a href="#reason-19" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Informal/non-explicit ranges are a source of errors.</p><h5><span class="subheading-anchor" id="example-22"></span><a href="#example-22" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">X</span><span class="token operator">*</span><span class="token plain"> </span><span class="token function">find</span><span class="token punctuation">(</span><span class="token plain">span</span><span class="token operator">&lt;</span><span class="token plain">X</span><span class="token operator">&gt;</span><span class="token plain"> r</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> X</span><span class="token operator">&amp;</span><span class="token plain"> v</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// find v in r</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">vector</span><span class="token operator">&lt;</span><span class="token plain">X</span><span class="token operator">&gt;</span><span class="token plain"> vec</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> p </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">find</span><span class="token punctuation">(</span><span class="token punctuation">{</span><span class="token plain">vec</span><span class="token punctuation">.</span><span class="token function">begin</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span><span class="token plain"> vec</span><span class="token punctuation">.</span><span class="token function">end</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">}</span><span class="token punctuation">,</span><span class="token plain"> X</span><span class="token punctuation">{</span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// find X{} in vec</span></div></code></pre><h5><span class="subheading-anchor" id="note-24"></span><a href="#note-24" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Ranges are extremely common in C++ code. Typically, they are implicit and their correct use is very hard to ensure.
85In particular, given a pair of arguments <code>(p, n)</code> designating an array <code>[p:p+n)</code>,
86it is in general impossible to know if there really are <code>n</code> elements to access following <code>*p</code>.
87<code>span&lt;T&gt;</code> and <code>span_p&lt;T&gt;</code> are simple helper classes designating a <code>[p:q)</code> range and a range starting with <code>p</code> and ending with the first element for which a predicate is true, respectively.</p><h5><span class="subheading-anchor" id="example-23"></span><a href="#example-23" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">
87#</span></a></h5><p>A <code>span</code> represents a range of elements, but how do we manipulate elements of that range?</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token plain">span</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&gt;</span><span class="token plain"> s</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// range traversal (guaranteed correct)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">for</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> x </span><span class="token operator">:</span><span class="token plain"> s</span><span class="token punctuation">)</span><span class="token plain"> cout </span><span class="token operator">&lt;&lt;</span><span class="token plain"> x </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&#x27;\n&#x27;</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// C-style traversal (potentially checked)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">for</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">gsl</span><span class="token operator">::</span><span class="token plain">index i </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">0</span><span class="token punctuation">;</span><span class="token plain"> i </span><span class="token operator">&lt;</span><span class="token plain"> s</span><span class="token punctuation">.</span><span class="token function">size</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token operator">++</span><span class="token plain">i</span><span class="token punctuation">)</span><span class="token plain"> cout </span><span class="token operator">&lt;&lt;</span><span class="token plain"> s</span><span class="token punctuation">[</span><span class="token plain">i</span><span class="token punctuation">]</span><span class="token plain"> </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&#x27;\n&#x27;</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// random access (potentially checked)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    s</span><span class="token punctuation">[</span><span class="token number">7</span><span class="token punctuation">]</span><span class="token plain"> </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">9</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// extract pointers (potentially checked)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    std</span><span class="token operator">::</span><span class="token function">
87sort</span><span class="token punctuation">(</span><span class="token operator">&amp;</span><span class="token plain">s</span><span class="token punctuation">[</span><span class="token number">0</span><span class="token punctuation">]</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token operator">&amp;</span><span class="token plain">s</span><span class="token punctuation">[</span><span class="token plain">s</span><span class="token punctuation">.</span><span class="token function">size</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token operator">/</span><span class="token plain"> </span><span class="token number">2</span><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="note-25"></span><a href="#note-25" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>A <code>span&lt;T&gt;</code> object does not own its elements and is so small that it can be passed by value.</p><p>Passing a <code>span</code> object as an argument is exactly as efficient as passing a pair of pointer arguments or passing a pointer and an integer count.</p><p><strong>See also</strong>: <a href="/gsl#S-gsl">(Support library)</a></p><h5><span class="subheading-anchor" id="enforcement-18"></span><a href="#enforcement-18" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>(Complex) Warn where accesses to pointer parameters are bounded by other parameters that are integral types and suggest they could use <code>span</code> instead.</p><h3><span class="subheading-anchor" id="f25-use-a-zstring-or-a-not_nullzstring-to-designate-a-c-style-string"></span><a href="#f25-use-a-zstring-or-a-not_nullzstring-to-designate-a-c-style-string" class="text-current no-underline no-outline"><a href="#" name="Rf-zstring"></a>F.25: Use a <code>zstring</code> or a <code>not_null&lt;zstring&gt;</code> to designate a C-style string<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-20"></span><a href="#reason-20" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>C-style strings are ubiquitous. They are defined by convention: zero-terminated arrays of characters.
88We must distinguish C-style strings from a pointer to a single character or an old-fashioned pointer to an array of characters.</p><p>If you don&#x27;t need null termination, use <code>string_view</code>.</p><h5><span class="subheading-anchor" id="example-24"></span><a href="#example-24" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Consider:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">length</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">char</span><span class="token operator">*</span><span class="token plain"> p</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><p>When I call <code>length(s)</code> should I check if <code>s</code> is <code>nullptr</code> first? Should the implementation of <code>length()</code> check if <code>p</code> is <code>nullptr</code>?</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">// the implementor of length() must assume that p == nullptr is possible</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">length</span><span class="token punctuation">(</span><span class="token plain">
88zstring p</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// it is the caller&#x27;s job to make sure p != nullptr</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">length</span><span class="token punctuation">(</span><span class="token plain">not_null</span><span class="token operator">&lt;</span><span class="token plain">zstring</span><span class="token operator">&gt;</span><span class="token plain"> p</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><h5><span class="subheading-anchor" id="note-26"></span><a href="#note-26" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p><code>zstring</code> does not represent ownership.</p><p><strong>See also</strong>: <a href="/gsl#S-gsl">(Support library)</a></p><h3><span class="subheading-anchor" id="f26-use-a-unique_ptrt-to-transfer-ownership-where-a-pointer-is-needed"></span><a href="#f26-use-a-unique_ptrt-to-transfer-ownership-where-a-pointer-is-needed" class="text-current no-underline no-outline"><a href="#" name="Rf-unique_ptr"></a>F.26: Use a <code>unique_ptr&lt;T&gt;</code> to transfer ownership where a pointer is needed<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-21"></span><a href="#reason-21" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Using <code>unique_ptr</code> is the cheapest way to pass a pointer safely.</p><p><strong>See also</strong>: <a href="/class#Rc-factory">(C.50)</a> regarding when to return a <code>shared_ptr</code> from a factory.</p><h5><span class="subheading-anchor" id="example-25"></span><a href="#example-25" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">unique_ptr</span><span class="token operator">&lt;</span><span class="token plain">Shape</span><span class="token operator">&gt;</span><span class="token plain"> </span><span class="token function">get_shape</span><span class="token punctuation">(</span><span class="token plain">istream</span><span class="token operator">&amp;</span><span class="token plain"> is</span><span class="token punctuation">)</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// assemble shape from input stream</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> kind </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">read_header</span><span class="token punctuation">(</span><span class="token plain">is</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// read header and identify the next shape on input</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">switch</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">kind</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">case</span><span class="token plain"> kCircle</span><span class="token operator">:</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> make_unique</span><span class="token operator">&lt;</span><span class="token plain">Circle</span><span class="token operator">&gt;</span><span class="token punctuation">(</span><span class="token plain">is</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">case</span><span class="token plain"> kTriangle</span><span class="token operator">:</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> make_unique</span><span class="token operator">&lt;</span><span class="token plain">Triangle</span><span class="token operator">&gt;</span><span class="token punctuation">(</span><span class="token plain">is</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">
88// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="note-27"></span><a href="#note-27" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>You need to pass a pointer rather than an object if what you are transferring is an object from a class hierarchy that is to be used through an interface (base class).</p><h5><span class="subheading-anchor" id="enforcement-19"></span><a href="#enforcement-19" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>(Simple) Warn if a function returns a locally allocated raw pointer. Suggest using either <code>unique_ptr</code> or <code>shared_ptr</code> instead.</p><h3><span class="subheading-anchor" id="f27-use-a-shared_ptrt-to-share-ownership"></span><a href="#f27-use-a-shared_ptrt-to-share-ownership" class="text-current no-underline no-outline"><a href="#" name="Rf-shared_ptr"></a>F.27: Use a <code>shared_ptr&lt;T&gt;</code> to share ownership<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-22"></span><a href="#reason-22" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Using <code>std::shared_ptr</code> is the standard way to represent shared ownership. That is, the last owner deletes the object.</p><h5><span class="subheading-anchor" id="example-26"></span><a href="#example-26" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">shared_ptr</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> Image</span><span class="token operator">&gt;</span><span class="token plain"> im </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token function">read_image</span><span class="token punctuation">(</span><span class="token plain">somewhere</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">std</span><span class="token operator">::</span><span class="token plain">thread t0 </span><span class="token punctuation">{</span><span class="token plain">shade</span><span class="token punctuation">,</span><span class="token plain"> args0</span><span class="token punctuation">,</span><span class="token plain"> top_left</span><span class="token punctuation">,</span><span class="token plain"> im</span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">std</span><span class="token operator">::</span><span class="token plain">thread t1 </span><span class="token punctuation">{</span><span class="token plain">shade</span><span class="token punctuation">,</span><span class="token plain"> args1</span><span class="token punctuation">,</span><span class="token plain"> top_right</span><span class="token punctuation">,</span><span class="token plain"> im</span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">std</span><span class="token operator">::</span><span class="token plain">thread t2 </span><span class="token punctuation">{</span><span class="token plain">
88shade</span><span class="token punctuation">,</span><span class="token plain"> args2</span><span class="token punctuation">,</span><span class="token plain"> bottom_left</span><span class="token punctuation">,</span><span class="token plain"> im</span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">std</span><span class="token operator">::</span><span class="token plain">thread t3 </span><span class="token punctuation">{</span><span class="token plain">shade</span><span class="token punctuation">,</span><span class="token plain"> args3</span><span class="token punctuation">,</span><span class="token plain"> bottom_right</span><span class="token punctuation">,</span><span class="token plain"> im</span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// detach threads</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// last thread to finish deletes the image</span></div></code></pre><h5><span class="subheading-anchor" id="note-28"></span><a href="#note-28" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Prefer a <code>unique_ptr</code> over a <code>shared_ptr</code> if there is never more than one owner at a time.
89<code>shared_ptr</code> is for shared ownership.</p><p>Note that pervasive use of <code>shared_ptr</code> has a cost (atomic operations on the <code>shared_ptr</code>&#x27;s reference count have a measurable aggregate cost).</p><h5><span class="subheading-anchor" id="alternative"></span><a href="#alternative" class="text-current no-underline no-outline">Alternative<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Have a single object own the shared object (e.g. a scoped object) and destroy that (preferably implicitly) when all users have completed.</p><h5><span class="subheading-anchor" id="enforcement-20"></span><a href="#enforcement-20" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>(Not enforceable) This is a too complex pattern to reliably detect.</p><h3><span class="subheading-anchor" id="f42-return-a-t-to-indicate-a-position-only"></span><a href="#f42-return-a-t-to-indicate-a-position-only" class="text-current no-underline no-outline"><a href="#" name="Rf-return-ptr"></a>F.42: Return a <code>T*</code> to indicate a position (only)<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-23"></span><a href="#reason-23" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>That&#x27;s what pointers are good for.
90Returning a <code>T*</code> to transfer ownership is a misuse.</p><h5><span class="subheading-anchor" id="example-27"></span><a href="#example-27" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">Node</span><span class="token operator">*</span><span class="token plain"> </span><span class="token function">find</span><span class="token punctuation">(</span><span class="token plain">Node</span><span class="token operator">*</span><span class="token plain"> t</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> string</span><span class="token operator">&amp;</span><span class="token plain"> s</span><span class="token punctuation">)</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// find s in a binary tree of Nodes</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token operator">!</span><span class="token plain">t </span><span class="token operator">||</span><span class="token plain"> t</span><span class="token operator">-&gt;</span><span class="token plain">name </span><span class="token operator">==</span><span class="token plain"> s</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> t</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> p </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">find</span><span class="token punctuation">(</span><span class="token plain">t</span><span class="token operator">-&gt;</span><span class="token plain">left</span><span class="token punctuation">,</span><span class="token plain"> s</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> p</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> p </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">find</span><span class="token punctuation">(</span><span class="token plain">t</span><span class="token operator">-&gt;</span><span class="token plain">right</span><span class="token punctuation">,</span><span class="token plain"> s</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> p</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">nullptr</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>If it isn&#x27;t the <code>nullptr</code>, the pointer returned by <code>find</code> indicates a <code>Node</code> holding <code>s</code>.
91Importantly, that does not imply a transfer of ownership of the pointed-to object to the caller.</p><h5><span class="subheading-anchor" id="note-29"></span><a href="#note-29" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">
91#</span></a></h5><p>Positions can also be transferred by iterators, indices, and references.
92A reference is often a superior alternative to a pointer <a href="/functions#Rf-ptr-ref">(if there is no need to use <code>nullptr</code>)</a> or <a href="???">if the object referred to should not change</a>.</p><h5><span class="subheading-anchor" id="note-30"></span><a href="#note-30" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Do not return a pointer to something that is not in the caller&#x27;s scope; see <a href="/functions#Rf-dangle">(F.43)</a>.</p><p><strong>See also</strong>: <a href="#???">discussion of dangling pointer prevention</a></p><h5><span class="subheading-anchor" id="enforcement-21"></span><a href="#enforcement-21" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>Flag <code>delete</code>, <code>std::free()</code>, etc. applied to a plain <code>T*</code>.
93Only owners should be deleted.</li><li>Flag <code>new</code>, <code>malloc()</code>, etc. assigned to a plain <code>T*</code>.
94Only owners should be responsible for deletion.</li></ul><h3><span class="subheading-anchor" id="f43-never-directly-or-indirectly-return-a-pointer-or-a-reference-to-a-local-object"></span><a href="#f43-never-directly-or-indirectly-return-a-pointer-or-a-reference-to-a-local-object" class="text-current no-underline no-outline"><a href="#" name="Rf-dangle"></a>F.43: Never (directly or indirectly) return a pointer or a reference to a local object<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-24"></span><a href="#reason-24" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>To avoid the crashes and data corruption that can result from the use of such a dangling pointer.</p><h5><span class="subheading-anchor" id="example-bad-1"></span><a href="#example-bad-1" class="text-current no-underline no-outline">Example, bad<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>After the return from a function its local objects no longer exist:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">*</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> fx </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">9</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token operator">&amp;</span><span class="token plain">fx</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// BAD</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">g</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">*</span><span class="token plain"> p</span><span class="token punctuation">)</span><span class="token plain">   </span><span class="token comment" style="color:#999;font-style:italic">// looks innocent enough</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> gx</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    cout </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&quot;*p == &quot;</span><span class="token plain"> </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token operator">*</span><span class="token plain">
94p </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&#x27;\n&#x27;</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token operator">*</span><span class="token plain">p </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">999</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    cout </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&quot;gx == &quot;</span><span class="token plain"> </span><span class="token operator">&lt;&lt;</span><span class="token plain"> gx </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&#x27;\n&#x27;</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">h</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">*</span><span class="token plain"> p </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> z </span><span class="token operator">=</span><span class="token plain"> </span><span class="token operator">*</span><span class="token plain">p</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// read from abandoned stack frame (bad)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">g</span><span class="token punctuation">(</span><span class="token plain">p</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">        </span><span class="token comment" style="color:#999;font-style:italic">// pass pointer to abandoned stack frame to function (bad)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>Here on one popular implementation I got the output:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token operator">*</span><span class="token plain">p </span><span class="token operator">==</span><span class="token plain"> </span><span class="token number">999</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">gx </span><span class="token operator">==</span><span class="token plain"> </span><span class="token number">999</span></div></code></pre><p>I expected that because the call of <code>g()</code> reuses the stack space abandoned by the call of <code>f()</code> so <code>*p</code> refers to the space now occupied by <code>gx</code>.</p><ul><li>Imagine what would happen if <code>fx</code> and <code>gx</code> were of different types.</li><li>Imagine what would happen if <code>fx</code> or <code>gx</code> was a type with an invariant.</li><li>Imagine what would happen if more that dangling pointer was passed around among a larger set of functions.</li><li>Imagine what a cracker could do with that dangling pointer.</li></ul><p>Fortunately, most (all?) modern compilers catch and warn against this simple case.</p><h5><span class="subheading-anchor" id="note-31"></span><a href="#note-31" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">
94#</span></a></h5><p>This applies to references as well:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">&amp;</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> x </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">7</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> x</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// Bad: returns reference to object that is about to be destroyed</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="note-32"></span><a href="#note-32" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>This applies only to non-<code>static</code> local variables.
95All <code>static</code> variables are (as their name indicates) statically allocated, so that pointers to them cannot dangle.</p><h5><span class="subheading-anchor" id="example-bad-2"></span><a href="#example-bad-2" class="text-current no-underline no-outline">Example, bad<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Not all examples of leaking a pointer to a local variable are that obvious:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token operator">*</span><span class="token plain"> glob</span><span class="token punctuation">;</span><span class="token plain">       </span><span class="token comment" style="color:#999;font-style:italic">// global variables are bad in so many ways</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">template</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">class</span><span class="token plain"> </span><span class="token class-name">T</span><span class="token operator">&gt;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">steal</span><span class="token punctuation">(</span><span class="token plain">T x</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    glob </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">x</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// BAD</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain">
95 i </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">99</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">steal</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token operator">&amp;</span><span class="token punctuation">]</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token operator">&amp;</span><span class="token plain">i</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">main</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    cout </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token operator">*</span><span class="token plain">glob </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&#x27;\n&#x27;</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>Here I managed to read the location abandoned by the call of <code>f</code>.
96The pointer stored in <code>glob</code> could be used much later and cause trouble in unpredictable ways.</p><h5><span class="subheading-anchor" id="note-33"></span><a href="#note-33" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>The address of a local variable can be &quot;returned&quot;/leaked by a return statement, by a <code>T&amp;</code> out-parameter, as a member of a returned object, as an element of a returned array, and more.</p><h5><span class="subheading-anchor" id="note-34"></span><a href="#note-34" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Similar examples can be constructed &quot;leaking&quot; a pointer from an inner scope to an outer one;
97such examples are handled equivalently to leaks of pointers out of a function.</p><p>A slightly different variant of the problem is placing pointers in a container that outlives the objects pointed to.</p><p><strong>See also</strong>: Another way of getting dangling pointers is <a href="#???">pointer invalidation</a>.
98It can be detected/prevented with similar techniques.</p><h5><span class="subheading-anchor" id="enforcement-22"></span><a href="#enforcement-22" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>Compilers tend to catch return of reference to locals and could in many cases catch return of pointers to locals.</li><li>Static analysis can catch many common patterns of the use of pointers indicating positions (thus eliminating dangling pointers)</li></ul><h3><span class="subheading-anchor" id="f44-return-a-t-when-copy-is-undesirable-and-returning-no-object-isnt-needed"></span><a href="#f44-return-a-t-when-copy-is-undesirable-and-returning-no-object-isnt-needed" class="text-current no-underline no-outline"><a href="#" name="Rf-return-ref"></a>F.44: Return a <code>T&amp;</code> when copy is undesirable and &quot;returning no object&quot; isn&#x27;t needed<span class="anchor-icon" aria-hidden="true">
98#</span></a></h3><h5><span class="subheading-anchor" id="reason-25"></span><a href="#reason-25" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>The language guarantees that a <code>T&amp;</code> refers to an object, so that testing for <code>nullptr</code> isn&#x27;t necessary.</p><p><strong>See also</strong>: The return of a reference must not imply transfer of ownership:
99<a href="#???">discussion of dangling pointer prevention</a> and <a href="#???">discussion of ownership</a>.</p><h5><span class="subheading-anchor" id="example-28"></span><a href="#example-28" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">class</span><span class="token plain"> </span><span class="token class-name">Car</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    array</span><span class="token operator">&lt;</span><span class="token plain">wheel</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token number">4</span><span class="token operator">&gt;</span><span class="token plain"> w</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">public</span><span class="token operator">:</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    wheel</span><span class="token operator">&amp;</span><span class="token plain"> </span><span class="token function">get_wheel</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> i</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token function">Expects</span><span class="token punctuation">(</span><span class="token plain">i </span><span class="token operator">&lt;</span><span class="token plain"> w</span><span class="token punctuation">.</span><span class="token function">size</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> w</span><span class="token punctuation">[</span><span class="token plain">i</span><span class="token punctuation">]</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">use</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    Car c</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    wheel</span><span class="token operator">&amp;</span><span class="token plain"> w0 </span><span class="token operator">=</span><span class="token plain"> c</span><span class="token punctuation">.</span><span class="token function">get_wheel</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// w0 has the same lifetime as c</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="enforcement-23"></span><a href="#enforcement-23" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">
99#</span></a></h5><p>Flag functions where no <code>return</code> expression could yield <code>nullptr</code></p><h3><span class="subheading-anchor" id="f45-dont-return-a-t"></span><a href="#f45-dont-return-a-t" class="text-current no-underline no-outline"><a href="#" name="Rf-return-ref-ref"></a>F.45: Don&#x27;t return a <code>T&amp;&amp;</code><span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-26"></span><a href="#reason-26" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>It&#x27;s asking to return a reference to a destroyed temporary object.
100A <code>&amp;&amp;</code> is a magnet for temporary objects.</p><h5><span class="subheading-anchor" id="example-29"></span><a href="#example-29" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>A returned rvalue reference goes out of scope at the end of the full expression to which it is returned:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token operator">&amp;&amp;</span><span class="token plain"> x </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">max</span><span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token number">1</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">   </span><span class="token comment" style="color:#999;font-style:italic">// OK, so far</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token function">foo</span><span class="token punctuation">(</span><span class="token plain">x</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">                 </span><span class="token comment" style="color:#999;font-style:italic">// Undefined behavior</span></div></code></pre><p>This kind of use is a frequent source of bugs, often incorrectly reported as a compiler bug.
101An implementer of a function should avoid setting such traps for users.</p><p>The <a href="/profile#SS-lifetime">(lifetime safety profile)</a> will (when completely implemented) catch such problems.</p><h5><span class="subheading-anchor" id="example-30"></span><a href="#example-30" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Returning an rvalue reference is fine when the reference to the temporary is being passed &quot;downward&quot; to a callee;
102then, the temporary is guaranteed to outlive the function call (see <a href="/functions#Rf-consume">((F.18)</a> and <a href="/functions#Rf-forward">F.19)</a>).
103However, it&#x27;s not fine when passing such a reference &quot;upward&quot; to a larger caller scope.
104For passthrough functions that pass in parameters (by ordinary reference or by perfect forwarding) and want to return values, use simple <code>auto</code> return type deduction (not <code>auto&amp;&amp;</code>).</p><p>Assume that <code>F</code> returns by value:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">template</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">class</span><span class="token plain"> </span><span class="token class-name">F</span><span class="token operator">&gt;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token operator">&amp;&amp;</span><span class="token plain"> </span><span class="token function">wrapper</span><span class="token punctuation">(</span><span class="token plain">F f</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">
104log_call</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">typeid</span><span class="token punctuation">(</span><span class="token plain">f</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// or whatever instrumentation</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">          </span><span class="token comment" style="color:#999;font-style:italic">// BAD: returns a reference to a temporary</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><p>Better:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">template</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">class</span><span class="token plain"> </span><span class="token class-name">F</span><span class="token operator">&gt;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> </span><span class="token function">wrapper</span><span class="token punctuation">(</span><span class="token plain">F f</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">log_call</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">typeid</span><span class="token punctuation">(</span><span class="token plain">f</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// or whatever instrumentation</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">          </span><span class="token comment" style="color:#999;font-style:italic">// OK</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="exception-5"></span><a href="#exception-5" class="text-current no-underline no-outline">Exception<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p><code>std::move</code> and <code>std::forward</code> do return <code>&amp;&amp;</code>, but they are just casts -- used by convention only in expression contexts where a reference to a temporary object is passed along within the same expression before the temporary is destroyed. We don&#x27;t know of any other good examples of returning <code>&amp;&amp;</code>.</p><h5><span class="subheading-anchor" id="enforcement-24"></span><a href="#enforcement-24" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Flag any use of <code>&amp;&amp;</code> as a return type, except in <code>std::move</code> and <code>std::forward</code>.</p><h3><span class="subheading-anchor" id="f46-int-is-the-return-type-for-main"></span><a href="#f46-int-is-the-return-type-for-main" class="text-current no-underline no-outline"><a href="#" name="Rf-main"></a>F.46: <code>int</code> is the return type for <code>main()</code><span class="anchor-icon" aria-hidden="true">
104#</span></a></h3><h5><span class="subheading-anchor" id="reason-27"></span><a href="#reason-27" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>It&#x27;s a language rule, but violated through &quot;language extensions&quot; so often that it is worth mentioning.
105Declaring <code>main</code> (the one global <code>main</code> of a program) <code>void</code> limits portability.</p><h5><span class="subheading-anchor" id="example-31"></span><a href="#example-31" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">main</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">/* ... */</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// bad, not C++</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">main</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        std</span><span class="token operator">::</span><span class="token plain">cout </span><span class="token operator">&lt;&lt;</span><span class="token plain"> </span><span class="token string">&quot;This is the way to do it\n&quot;</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="note-35"></span><a href="#note-35" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>We mention this only because of the persistence of this error in the community.
106Note that despite its non-void return type, the main function does not require an explicit return statement.</p><h5><span class="subheading-anchor" id="enforcement-25"></span><a href="#enforcement-25" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>The compiler should do it</li><li>If the compiler doesn&#x27;t do it, let tools flag it</li></ul><h3><span class="subheading-anchor" id="f47-return-t-from-assignment-operators"></span><a href="#f47-return-t-from-assignment-operators" class="text-current no-underline no-outline"><a href="#" name="Rf-assignment-op"></a>F.47: Return <code>T&amp;</code> from assignment operators<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-28"></span><a href="#reason-28" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>The convention for operator overloads (especially on concrete types) is for
107<code>operator=(const T&amp;)</code> to perform the assignment and then return (non-<code>const</code>)
108<code>*this</code>. This ensures consistency with standard-library types and follows the
109principle of &quot;do as the ints do.&quot;</p><h5><span class="subheading-anchor" id="note-36"></span><a href="#note-36" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">
109#</span></a></h5><p>Historically there was some guidance to make the assignment operator return <code>const T&amp;</code>.
110This was primarily to avoid code of the form <code>(a = b) = c</code> -- such code is not common enough to warrant violating consistency with standard types.</p><h5><span class="subheading-anchor" id="example-32"></span><a href="#example-32" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">class</span><span class="token plain"> </span><span class="token class-name">Foo</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">public</span><span class="token operator">:</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    Foo</span><span class="token operator">&amp;</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">operator</span><span class="token operator">=</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> Foo</span><span class="token operator">&amp;</span><span class="token plain"> rhs</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">      </span><span class="token comment" style="color:#999;font-style:italic">// Copy members.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">      </span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">      </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token operator">*</span><span class="token keyword" style="color:#ff0078;font-weight:bold">this</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token punctuation">;</span></div></code></pre><h5><span class="subheading-anchor" id="enforcement-26"></span><a href="#enforcement-26" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>This should be enforced by tooling by checking the return type (and return
111value) of any assignment operator.</p><h3><span class="subheading-anchor" id="f48-dont-return-stdmovelocal"></span><a href="#f48-dont-return-stdmovelocal" class="text-current no-underline no-outline"><a href="#" name="Rf-return-move-local"></a>F.48: Don&#x27;t <code>return std::move(local)</code><span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-29"></span><a href="#reason-29" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>With guaranteed copy elision, it is now almost always a pessimization to expressly use <code>std::move</code> in a return statement.</p><h5><span class="subheading-anchor" id="example-bad-3"></span><a href="#example-bad-3" class="text-current no-underline no-outline">Example, bad<span class="anchor-icon" aria-hidden="true">
111#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">S </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">  S result</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">  </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> std</span><span class="token operator">::</span><span class="token function">move</span><span class="token punctuation">(</span><span class="token plain">result</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="example-good-1"></span><a href="#example-good-1" class="text-current no-underline no-outline">Example, good<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">S </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">  S result</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">  </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> result</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="enforcement-27"></span><a href="#enforcement-27" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>This should be enforced by tooling by checking the return expression .</p><h3><span class="subheading-anchor" id="f50-use-a-lambda-when-a-function-wont-do-to-capture-local-variables-or-to-write-a-local-function"></span><a href="#f50-use-a-lambda-when-a-function-wont-do-to-capture-local-variables-or-to-write-a-local-function" class="text-current no-underline no-outline"><a href="#" name="Rf-capture-vs-overload"></a>F.50: Use a lambda when a function won&#x27;t do (to capture local variables, or to write a local function)<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-30"></span><a href="#reason-30" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Functions can&#x27;t capture local variables or be defined at local scope; if you need those things, prefer a lambda where possible, and a handwritten function object where not. On the other hand, lambdas and function objects don&#x27;t overload; if you need to overload, prefer a function (the workarounds to make lambdas overload are ornate). If either will work, prefer writing a function; use the simplest tool necessary.</p><h5><span class="subheading-anchor" id="example-33"></span><a href="#example-33" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">// writing a function that should only take an int or a string</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// -- overloading is natural</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> string</span><span class="token operator">&amp;</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// writing a function object that needs to capture local state and appear</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// at statement or expression scope -- a lambda is natural</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">vector</span><span class="token operator">&lt;</span><span class="token plain">work</span><span class="token operator">&gt;</span><span class="token plain"> v </span><span class="token operator">=</span><span class="token plain"> </span><span class="token function">lots_of_work</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">for</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> tasknum </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">0</span><span class="token punctuation">;</span><span class="token plain"> tasknum </span><span class="token operator">&lt;</span><span class="token plain"> max</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token operator">++</span><span class="token plain">tasknum</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    pool</span><span class="token punctuation">.</span><span class="token function">run</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token operator">=</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token operator">&amp;</span><span class="token plain">v</span><span class="token punctuation">]</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token comment" style="color:#999;font-style:italic">/*</span></div><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">        ...</span></div><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">        ... process 1 / max - th of v, the tasknum - th chunk</span></div><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">        ...</span></div><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">        */</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">
111pool</span><span class="token punctuation">.</span><span class="token function">join</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><h5><span class="subheading-anchor" id="exception-6"></span><a href="#exception-6" class="text-current no-underline no-outline">Exception<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Generic lambdas offer a concise way to write function templates and so can be useful even when a normal function template would do equally well with a little more syntax. This advantage will probably disappear in the future once all functions gain the ability to have Concept parameters.</p><h5><span class="subheading-anchor" id="enforcement-28"></span><a href="#enforcement-28" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>Warn on use of a named non-generic lambda (e.g., <code>auto x = [](int i) { /*...*/; };</code>) that captures nothing and appears at global scope. Write an ordinary function instead.</li></ul><h3><span class="subheading-anchor" id="f51-where-there-is-a-choice-prefer-default-arguments-over-overloading"></span><a href="#f51-where-there-is-a-choice-prefer-default-arguments-over-overloading" class="text-current no-underline no-outline"><a href="#" name="Rf-default-args"></a>F.51: Where there is a choice, prefer default arguments over overloading<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-31"></span><a href="#reason-31" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Default arguments simply provide alternative interfaces to a single implementation.
112There is no guarantee that a set of overloaded functions all implement the same semantics.
113The use of default arguments can avoid code replication.</p><h5><span class="subheading-anchor" id="note-37"></span><a href="#note-37" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>There is a choice between using default argument and overloading when the alternatives are from a set of arguments of the same types.
114For example:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">print</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> string</span><span class="token operator">&amp;</span><span class="token plain"> s</span><span class="token punctuation">,</span><span class="token plain"> format f </span><span class="token operator">=</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><p>as opposed to</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">print</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> string</span><span class="token operator">&amp;</span><span class="token plain"> s</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// use default format</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">print</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> string</span><span class="token operator">&amp;</span><span class="token plain"> s</span><span class="token punctuation">,</span><span class="token plain"> format f</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><p>There is not a choice when a set of functions are used to do a semantically equivalent operation to a set of types. For example:</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">print</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">const</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">char</span><span class="token operator">&amp;</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">print</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">print</span><span class="token punctuation">(</span><span class="token plain">
114zstring</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><h5><span class="subheading-anchor" id="see-also"></span><a href="#see-also" class="text-current no-underline no-outline">See also<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p><a href="/class#Rh-virtual-default-arg">(Default arguments for virtual functions)</a></p><h5><span class="subheading-anchor" id="enforcement-29"></span><a href="#enforcement-29" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>Warn on an overload set where the overloads have a common prefix of parameters (e.g., <code>f(int)</code>, <code>f(int, const string&amp;)</code>, <code>f(int, const string&amp;, double)</code>). (Note: Review this enforcement if it&#x27;s too noisy in practice.)</li></ul><h3><span class="subheading-anchor" id="f52-prefer-capturing-by-reference-in-lambdas-that-will-be-used-locally-including-passed-to-algorithms"></span><a href="#f52-prefer-capturing-by-reference-in-lambdas-that-will-be-used-locally-including-passed-to-algorithms" class="text-current no-underline no-outline"><a href="#" name="Rf-reference-capture"></a>F.52: Prefer capturing by reference in lambdas that will be used locally, including passed to algorithms<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-32"></span><a href="#reason-32" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>For efficiency and correctness, you nearly always want to capture by reference when using the lambda locally. This includes when writing or calling parallel algorithms that are local because they join before returning.</p><h5><span class="subheading-anchor" id="discussion"></span><a href="#discussion" class="text-current no-underline no-outline">Discussion<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>The efficiency consideration is that most types are cheaper to pass by reference than by value.</p><p>The correctness consideration is that many calls want to perform side effects on the original object at the call site (see example below). Passing by value prevents this.</p><h5><span class="subheading-anchor" id="note-38"></span><a href="#note-38" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Unfortunately, there is no simple way to capture by reference to <code>const</code> to get the efficiency for a local call but also prevent side effects.</p><h5><span class="subheading-anchor" id="example-34"></span><a href="#example-34" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Here, a large object (a network message) is passed to an iterative algorithm, and it is not efficient or correct to copy the message (which might not be copyable):</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token plain">std</span><span class="token operator">::</span><span class="token function">for_each</span><span class="token punctuation">(</span><span class="token function">begin</span><span class="token punctuation">(</span><span class="token plain">sockets</span><span class="token punctuation">)</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token function">end</span><span class="token punctuation">(</span><span class="token plain">sockets</span><span class="token punctuation">)</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token punctuation">[</span><span class="token operator">&amp;</span><span class="token plain">message</span><span class="token punctuation">]</span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token operator">&amp;</span><span class="token plain"> socket</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    socket</span><span class="token punctuation">.</span><span class="token function">send</span><span class="token punctuation">(</span><span class="token plain">message</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><h5><span class="subheading-anchor" id="example-35"></span><a href="#example-35" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">
114#</span></a></h5><p>This is a simple three-stage parallel pipeline. Each <code>stage</code> object encapsulates a worker thread and a queue, has a <code>process</code> function to enqueue work, and in its destructor automatically blocks waiting for the queue to empty before ending the thread.</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">send_packets</span><span class="token punctuation">(</span><span class="token plain">buffers</span><span class="token operator">&amp;</span><span class="token plain"> bufs</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    stage </span><span class="token function">encryptor</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token punctuation">]</span><span class="token punctuation">(</span><span class="token plain">buffer</span><span class="token operator">&amp;</span><span class="token plain"> b</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token function">encrypt</span><span class="token punctuation">(</span><span class="token plain">b</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    stage </span><span class="token function">compressor</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token operator">&amp;</span><span class="token punctuation">]</span><span class="token punctuation">(</span><span class="token plain">buffer</span><span class="token operator">&amp;</span><span class="token plain"> b</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token function">compress</span><span class="token punctuation">(</span><span class="token plain">b</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> encryptor</span><span class="token punctuation">.</span><span class="token function">process</span><span class="token punctuation">(</span><span class="token plain">b</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    stage </span><span class="token function">decorator</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token operator">&amp;</span><span class="token punctuation">]</span><span class="token punctuation">(</span><span class="token plain">buffer</span><span class="token operator">&amp;</span><span class="token plain"> b</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token function">decorate</span><span class="token punctuation">(</span><span class="token plain">b</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> compressor</span><span class="token punctuation">.</span><span class="token function">process</span><span class="token punctuation">(</span><span class="token plain">b</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">for</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token operator">&amp;</span><span class="token plain"> b </span><span class="token operator">:</span><span class="token plain"> bufs</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain">
114 decorator</span><span class="token punctuation">.</span><span class="token function">process</span><span class="token punctuation">(</span><span class="token plain">b</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain">  </span><span class="token comment" style="color:#999;font-style:italic">// automatically blocks waiting for pipeline to finish</span></div></code></pre><h5><span class="subheading-anchor" id="enforcement-30"></span><a href="#enforcement-30" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Flag a lambda that captures by reference, but is used other than locally within the function scope or passed to a function by reference. (Note: This rule is an approximation, but does flag passing by pointer as those are more likely to be stored by the callee, writing to a heap location accessed via a parameter, returning the lambda, etc. The Lifetime rules will also provide general rules that flag escaping pointers and references including via lambdas.)</p><h3><span class="subheading-anchor" id="f53-avoid-capturing-by-reference-in-lambdas-that-will-be-used-non-locally-including-returned-stored-on-the-heap-or-passed-to-another-thread"></span><a href="#f53-avoid-capturing-by-reference-in-lambdas-that-will-be-used-non-locally-including-returned-stored-on-the-heap-or-passed-to-another-thread" class="text-current no-underline no-outline"><a href="#" name="Rf-value-capture"></a>F.53: Avoid capturing by reference in lambdas that will be used non-locally, including returned, stored on the heap, or passed to another thread<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-33"></span><a href="#reason-33" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Pointers and references to locals shouldn&#x27;t outlive their scope. Lambdas that capture by reference are just another place to store a reference to a local object, and shouldn&#x27;t do so if they (or a copy) outlive the scope.</p><h5><span class="subheading-anchor" id="example-bad-4"></span><a href="#example-bad-4" class="text-current no-underline no-outline">Example, bad<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> local </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">42</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// Want a reference to local.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// Note, that after program exits this scope,</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// local no longer exists, therefore</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// process() call will have undefined behavior!</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">thread_pool</span><span class="token punctuation">.</span><span class="token function">queue_work</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token operator">&amp;</span><span class="token punctuation">]</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token function">process</span><span class="token punctuation">(</span><span class="token plain">local</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><h5><span class="subheading-anchor" id="example-good-2"></span><a href="#example-good-2" class="text-current no-underline no-outline">Example, good<span class="anchor-icon" aria-hidden="true">
114#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> local </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">42</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// Want a copy of local.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// Since a copy of local is made, it will</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// always be available for the call.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">thread_pool</span><span class="token punctuation">.</span><span class="token function">queue_work</span><span class="token punctuation">(</span><span class="token punctuation">[</span><span class="token operator">=</span><span class="token punctuation">]</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token function">process</span><span class="token punctuation">(</span><span class="token plain">local</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span></div></code></pre><h5><span class="subheading-anchor" id="enforcement-31"></span><a href="#enforcement-31" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>(Simple) Warn when capture-list contains a reference to a locally declared variable</li><li>(Complex) Flag when capture-list contains a reference to a locally declared variable and the lambda is passed to a non-<code>const</code> and non-local context</li></ul><h3><span class="subheading-anchor" id="f54-if-you-capture-this-capture-all-variables-explicitly-no-default-capture"></span><a href="#f54-if-you-capture-this-capture-all-variables-explicitly-no-default-capture" class="text-current no-underline no-outline"><a href="#" name="Rf-this-capture"></a>F.54: If you capture <code>this</code>, capture all variables explicitly (no default capture)<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-34"></span><a href="#reason-34" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>It&#x27;s confusing. Writing <code>[=]</code> in a member function appears to capture by value, but actually captures data members by reference because it actually captures the invisible <code>this</code> pointer by value. If you meant to do that, write <code>this</code> explicitly.</p><h5><span class="subheading-anchor" id="example-36"></span><a href="#example-36" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">class</span><span class="token plain"> </span><span class="token class-name">My_class</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> x </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">0</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">
114// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">f</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> i </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">0</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">        </span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> lambda </span><span class="token operator">=</span><span class="token plain"> </span><span class="token punctuation">[</span><span class="token operator">=</span><span class="token punctuation">]</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token function">use</span><span class="token punctuation">(</span><span class="token plain">i</span><span class="token punctuation">,</span><span class="token plain"> x</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain">   </span><span class="token comment" style="color:#999;font-style:italic">// BAD: &quot;looks like&quot; copy/value capture</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token comment" style="color:#999;font-style:italic">// [&amp;] has identical semantics and copies the this pointer under the current rules</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token comment" style="color:#999;font-style:italic">// [=,this] and [&amp;,this] are not much better, and confusing</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">        x </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">42</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token function">lambda</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// calls use(0, 42);</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        x </span><span class="token operator">=</span><span class="token plain"> </span><span class="token number">43</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token function">lambda</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// calls use(0, 43);</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">        </span><span class="token comment" style="color:#999;font-style:italic">
114// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">        </span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> lambda2 </span><span class="token operator">=</span><span class="token plain"> </span><span class="token punctuation">[</span><span class="token plain">i</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">this</span><span class="token punctuation">]</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"> </span><span class="token function">use</span><span class="token punctuation">(</span><span class="token plain">i</span><span class="token punctuation">,</span><span class="token plain"> x</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token punctuation">}</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// ok, most explicit and least confusing</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">        </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token punctuation">;</span></div></code></pre><h5><span class="subheading-anchor" id="note-39"></span><a href="#note-39" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>This is under active discussion in standardization, and might be addressed in a future version of the standard by adding a new capture mode or possibly adjusting the meaning of <code>[=]</code>. For now, just be explicit.</p><h5><span class="subheading-anchor" id="enforcement-32"></span><a href="#enforcement-32" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>Flag any lambda capture-list that specifies a default capture and also captures <code>this</code> (whether explicitly or via default capture)</li></ul><h3><span class="subheading-anchor" id="f55-dont-use-va_arg-arguments"></span><a href="#f55-dont-use-va_arg-arguments" class="text-current no-underline no-outline"><a href="#" name="F-varargs"></a>F.55: Don&#x27;t use <code>va_arg</code> arguments<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-35"></span><a href="#reason-35" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Reading from a <code>va_arg</code> assumes that the correct type was actually passed.
115Passing to varargs assumes the correct type will be read.
116This is fragile because it cannot generally be enforced to be safe in the language and so relies on programmer discipline to get it right.</p><h5><span class="subheading-anchor" id="example-37"></span><a href="#example-37" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token plain"> </span><span class="token function">sum</span><span class="token punctuation">(</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">
116// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">while</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token comment" style="color:#999;font-style:italic">/*...*/</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        result </span><span class="token operator">+=</span><span class="token plain"> </span><span class="token function">va_arg</span><span class="token punctuation">(</span><span class="token plain">list</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token keyword" style="color:#ff0078;font-weight:bold">int</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// BAD, assumes it will be passed ints</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token comment" style="color:#999;font-style:italic">// ...</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token function">sum</span><span class="token punctuation">(</span><span class="token number">3</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token number">2</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// ok</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token function">sum</span><span class="token punctuation">(</span><span class="token number">3.14159</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token number">2.71828</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// BAD, undefined</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">template</span><span class="token operator">&lt;</span><span class="token keyword" style="color:#ff0078;font-weight:bold">class</span><span class="token plain"> </span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token plain">Args</span><span class="token operator">&gt;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">auto</span><span class="token plain"> </span><span class="token function">sum</span><span class="token punctuation">(</span><span class="token plain">Args</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token plain"> args</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// GOOD, and much more flexible</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token plain"> </span><span class="token operator">+</span><span class="token plain"> args</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// note: C++17 &quot;fold expression&quot;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token function">sum</span><span class="token punctuation">(</span><span class="token number">3</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token number">2</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// ok: 5</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token function">sum</span><span class="token punctuation">(</span><span class="token number">3.14159</span><span class="token punctuation">,</span><span class="token plain"> </span><span class="token number">2.71828</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"> </span><span class="token comment" style="color:#999;font-style:italic">// ok: ~5.85987</span></div></code></pre><h5><span class="subheading-anchor" id="alternatives"></span><a href="#alternatives" class="text-current no-underline no-outline">Alternatives<span class="anchor-icon" aria-hidden="true">
116#</span></a></h5><ul><li>overloading</li><li>variadic templates</li><li><code>variant</code> arguments</li><li><code>initializer_list</code> (homogeneous)</li></ul><h5><span class="subheading-anchor" id="note-40"></span><a href="#note-40" class="text-current no-underline no-outline">Note<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Declaring a <code>...</code> parameter is sometimes useful for techniques that don&#x27;t involve actual argument passing, notably to declare &quot;take-anything&quot; functions so as to disable &quot;everything else&quot; in an overload set or express a catchall case in a template metaprogram.</p><h5><span class="subheading-anchor" id="enforcement-33"></span><a href="#enforcement-33" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">#</span></a></h5><ul><li>Issue a diagnostic for using <code>va_list</code>, <code>va_start</code>, or <code>va_arg</code>.</li><li>Issue a diagnostic for passing an argument to a vararg parameter of a function that does not offer an overload for a more specific type in the position of the vararg. To fix: Use a different function, or <code>[[suppress(types)]]</code>.</li></ul><h3><span class="subheading-anchor" id="f56-avoid-unnecessary-condition-nesting"></span><a href="#f56-avoid-unnecessary-condition-nesting" class="text-current no-underline no-outline"><a href="#" name="F-nesting"></a>F.56: Avoid unnecessary condition nesting<span class="anchor-icon" aria-hidden="true">#</span></a></h3><h5><span class="subheading-anchor" id="reason-36"></span><a href="#reason-36" class="text-current no-underline no-outline">Reason<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Shallow nesting of conditions makes the code easier to follow. It also makes the intent clearer.
117Strive to place the essential code at outermost scope, unless this obscures intent.</p><h5><span class="subheading-anchor" id="example-38"></span><a href="#example-38" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">#</span></a></h5><p>Use a guard-clause to take care of exceptional cases and return early.</p><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">// Bad: Deep nesting</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">foo</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">x</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token function">computeImportantThings</span><span class="token punctuation">(</span><span class="token plain">x</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// Bad: Still a redundant else.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">foo</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token operator">!</span><span class="token plain">x</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">else</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token function">computeImportantThings</span><span class="token punctuation">(</span><span class="token plain">x</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// Good: Early return, no redundant else</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">foo</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token operator">!</span><span class="token plain">x</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">computeImportantThings</span><span class="token punctuation">(</span><span class="token plain">x</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="example-39"></span><a href="#example-39" class="text-current no-underline no-outline">Example<span class="anchor-icon" aria-hidden="true">
117#</span></a></h5><pre><code class="prism-code language-cpp" style="background-color:transparent"><div class="token-line"><span class="token comment" style="color:#999;font-style:italic">// Bad: Unnecessary nesting of conditions</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">foo</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">x</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token plain">y</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">            </span><span class="token function">computeImportantThings</span><span class="token punctuation">(</span><span class="token plain">x</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain"></span><span class="token comment" style="color:#999;font-style:italic">// Good: Merge conditions + return early</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token keyword" style="color:#ff0078;font-weight:bold">void</span><span class="token plain"> </span><span class="token function">foo</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token plain"> </span><span class="token punctuation">{</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">    </span><span class="token keyword" style="color:#ff0078;font-weight:bold">if</span><span class="token plain"> </span><span class="token punctuation">(</span><span class="token operator">!</span><span class="token punctuation">(</span><span class="token plain">x </span><span class="token operator">&amp;&amp;</span><span class="token plain"> y</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token plain"></span></div><div class="token-line"><span class="token plain">        </span><span class="token keyword" style="color:#ff0078;font-weight:bold">return</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain" style="display:inline-block"></span></div><div class="token-line"><span class="token plain">    </span><span class="token function">computeImportantThings</span><span class="token punctuation">(</span><span class="token plain">x</span><span class="token punctuation">)</span><span class="token punctuation">;</span><span class="token plain"></span></div><div class="token-line"><span class="token plain"></span><span class="token punctuation">}</span></div></code></pre><h5><span class="subheading-anchor" id="enforcement-34"></span><a href="#enforcement-34" class="text-current no-underline no-outline">Enforcement<span class="anchor-icon" aria-hidden="true">
117#</span></a></h5><p>Flag a redundant <code>else</code>.
118Flag a functions whose body is simply a conditional statement enclosing a block.</p><footer class="mt-24"><div class="flex flex-row items-center justify-between"><div><a class="text-lg font-medium p-4 -m-4 no-underline text-gray-600 hover:text-blue-600 flex items-center mr-2" title="I: Interfaces" href="/interfaces"><svg height="24" fill="none" viewBox="0 0 24 24" stroke="currentColor" class="transform inline flex-shrink-0 rotate-180 mr-1"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7"></path></svg>I: Interfaces</a></div><div><a class="text-lg font-medium p-4 -m-4 no-underline text-gray-600 hover:text-blue-600 flex items-center ml-2" title="C: Classes and class hierarchies" href="/class">C: Classes and class hierarchies<svg height="24" fill="none" viewBox="0 0 24 24" stroke="currentColor" class="transform inline flex-shrink-0 ml-1"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5l7 7-7 7"></path></svg></a></div></div><hr/><div class="mt-24 flex justify-between flex-col-reverse md:flex-row items-center md:items-end"><span class="text-gray-600">C++ Core Guidelines <!-- -->2022<!-- -->.</span><div class="mt-6"></div></div></footer></main></article></div></div></div>
118<script id="__NEXT_DATA__" type="application/json">{"props":{"pageProps":{}},"page":"/functions","query":{},"buildId":"-EYFV5cGB6Gs4jJDYIQHc","nextExport":true,"autoExport":true,"isFallback":false,"scriptLoader":[]}</script>
118</body></html>

Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.