stability.html - rust-lang/rustc-dev-guide - Git at Google

 <!DOCTYPE HTML>
 <html lang="en" class="light sidebar-visible" dir="ltr">
     <head>
         <!-- Book generated using mdBook -->
         <meta charset="UTF-8">
         <title>Stability attributes - Rust Compiler Development Guide</title>


         <!-- Custom HTML head -->

         <meta name="description" content="A guide to developing the Rust compiler (rustc)">
         <meta name="viewport" content="width=device-width, initial-scale=1">
         <meta name="theme-color" content="#ffffff">

         <link rel="icon" href="favicon-de23e50b.svg">
         <link rel="shortcut icon" href="favicon-8114d1fc.png">
         <link rel="stylesheet" href="css/variables-8adf115d.css">
         <link rel="stylesheet" href="css/general-2459343d.css">
         <link rel="stylesheet" href="css/chrome-ae938929.css">
         <link rel="stylesheet" href="css/print-9e4910d8.css" media="print">

         <!-- Fonts -->
         <link rel="stylesheet" href="fonts/fonts-9644e21d.css">

         <!-- Highlight.js Stylesheets -->
         <link rel="stylesheet" id="mdbook-highlight-css" href="highlight-493f70e1.css">
         <link rel="stylesheet" id="mdbook-tomorrow-night-css" href="tomorrow-night-4c0ae647.css">
         <link rel="stylesheet" id="mdbook-ayu-highlight-css" href="ayu-highlight-3fdfc3ac.css">

         <!-- Custom theme stylesheets -->


         <!-- Provide site root and default themes to javascript -->
         <script>
             const path_to_root = "";
             const default_light_theme = "light";
             const default_dark_theme = "navy";
             window.path_to_searchindex_js = "searchindex-1dcc4ecd.js";
         </script>
         <!-- Start loading toc.js asap -->
         <script src="toc-39e8ee02.js"></script>
     </head>
     <body>
     <div id="mdbook-help-container">
         <div id="mdbook-help-popup">
             <h2 class="mdbook-help-title">Keyboard shortcuts</h2>
             <div>
                 <p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
                 <p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
                 <p>Press <kbd>?</kbd> to show this help</p>
                 <p>Press <kbd>Esc</kbd> to hide this help</p>
             </div>
         </div>
     </div>
     <div id="mdbook-body-container">
         <!-- Work around some values being stored in localStorage wrapped in quotes -->
         <script>
             try {
                 let theme = localStorage.getItem('mdbook-theme');
                 let sidebar = localStorage.getItem('mdbook-sidebar');

                 if (theme.startsWith('"') && theme.endsWith('"')) {
                     localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
                 }

                 if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
                     localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
                 }
             } catch (e) { }
         </script>

         <!-- Set the theme before any content is loaded, prevents flash -->
         <script>
             const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
             let theme;
             try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
             if (theme === null || theme === undefined) { theme = default_theme; }
             const html = document.documentElement;
             html.classList.remove('light')
             html.classList.add(theme);
             html.classList.add("js");
         </script>

         <input type="checkbox" id="mdbook-sidebar-toggle-anchor" class="hidden">

         <!-- Hide / unhide sidebar before it is displayed -->
         <script>
             let sidebar = null;
             const sidebar_toggle = document.getElementById("mdbook-sidebar-toggle-anchor");
             if (document.body.clientWidth >= 1080) {
                 try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                 sidebar = sidebar || 'visible';
             } else {
                 sidebar = 'hidden';
                 sidebar_toggle.checked = false;
             }
             if (sidebar === 'visible') {
                 sidebar_toggle.checked = true;
             } else {
                 html.classList.remove('sidebar-visible');
             }
         </script>

         <nav id="mdbook-sidebar" class="sidebar" aria-label="Table of contents">
             <!-- populated by js -->
             <mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
             <noscript>
                 <iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
             </noscript>
             <div id="mdbook-sidebar-resize-handle" class="sidebar-resize-handle">
                 <div class="sidebar-resize-indicator"></div>
             </div>
         </nav>

         <div id="mdbook-page-wrapper" class="page-wrapper">

             <div class="page">
                 <div id="mdbook-menu-bar-hover-placeholder"></div>
                 <div id="mdbook-menu-bar" class="menu-bar sticky">
                     <div class="left-buttons">
                         <label id="mdbook-sidebar-toggle" class="icon-button" for="mdbook-sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="mdbook-sidebar">
                             <span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M0 96C0 78.3 14.3 64 32 64H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32C14.3 128 0 113.7 0 96zM0 256c0-17.7 14.3-32 32-32H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32c-17.7 0-32-14.3-32-32zM448 416c0 17.7-14.3 32-32 32H32c-17.7 0-32-14.3-32-32s14.3-32 32-32H416c17.7 0 32 14.3 32 32z"/></svg></span>
                         </label>
                         <button id="mdbook-theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="mdbook-theme-list">
                             <span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M371.3 367.1c27.3-3.9 51.9-19.4 67.2-42.9L600.2 74.1c12.6-19.5 9.4-45.3-7.6-61.2S549.7-4.4 531.1 9.6L294.4 187.2c-24 18-38.2 46.1-38.4 76.1L371.3 367.1zm-19.6 25.4l-116-104.4C175.9 290.3 128 339.6 128 400c0 3.9 .2 7.8 .6 11.6c1.8 17.5-10.2 36.4-27.8 36.4H96c-17.7 0-32 14.3-32 32s14.3 32 32 32H240c61.9 0 112-50.1 112-112c0-2.5-.1-5-.2-7.5z"/></svg></span>
                         </button>
                         <ul id="mdbook-theme-list" class="theme-popup" aria-label="Themes" role="menu">
                             <li role="none"><button role="menuitem" class="theme" id="mdbook-theme-default_theme">Auto</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="mdbook-theme-light">Light</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="mdbook-theme-rust">Rust</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="mdbook-theme-coal">Coal</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="mdbook-theme-navy">Navy</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="mdbook-theme-ayu">Ayu</button></li>
                         </ul>
                         <button id="mdbook-search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="mdbook-searchbar">
                             <span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0S416 93.1 416 208zM208 352c79.5 0 144-64.5 144-144s-64.5-144-144-144S64 128.5 64 208s64.5 144 144 144z"/></svg></span>
                         </button>
                     </div>

                     <h1 class="menu-title">Rust Compiler Development Guide</h1>

                     <div class="right-buttons">
                         <a href="print.html" title="Print this book" aria-label="Print this book">
                             <span class=fa-svg id="print-button"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M128 0C92.7 0 64 28.7 64 64v96h64V64H354.7L384 93.3V160h64V93.3c0-17-6.7-33.3-18.7-45.3L400 18.7C388 6.7 371.7 0 354.7 0H128zM384 352v32 64H128V384 368 352H384zm64 32h32c17.7 0 32-14.3 32-32V256c0-35.3-28.7-64-64-64H64c-35.3 0-64 28.7-64 64v96c0 17.7 14.3 32 32 32H64v64c0 35.3 28.7 64 64 64H384c35.3 0 64-28.7 64-64V384zm-16-88c-13.3 0-24-10.7-24-24s10.7-24 24-24s24 10.7 24 24s-10.7 24-24 24z"/></svg></span>
                         </a>
                         <a href="https://github.com/rust-lang/rustc-dev-guide" title="Git repository" aria-label="Git repository">
                             <span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg></span>
                         </a>
                         <a href="https://github.com/rust-lang/rustc-dev-guide/edit/main/src/stability.md" title="Suggest an edit" aria-label="Suggest an edit" rel="edit">
                             <span class=fa-svg id="git-edit-button"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M421.7 220.3l-11.3 11.3-22.6 22.6-205 205c-6.6 6.6-14.8 11.5-23.8 14.1L30.8 511c-8.4 2.5-17.5 .2-23.7-6.1S-1.5 489.7 1 481.2L38.7 353.1c2.6-9 7.5-17.2 14.1-23.8l205-205 22.6-22.6 11.3-11.3 33.9 33.9 62.1 62.1 33.9 33.9zM96 353.9l-9.3 9.3c-.9 .9-1.6 2.1-2 3.4l-25.3 86 86-25.3c1.3-.4 2.5-1.1 3.4-2l9.3-9.3H112c-8.8 0-16-7.2-16-16V353.9zM453.3 19.3l39.4 39.4c25 25 25 65.5 0 90.5l-14.5 14.5-22.6 22.6-11.3 11.3-33.9-33.9-62.1-62.1L314.3 67.7l11.3-11.3 22.6-22.6 14.5-14.5c25-25 65.5-25 90.5 0z"/></svg></span>
                         </a>

                     </div>
                 </div>

                 <div id="mdbook-search-wrapper" class="hidden">
                     <form id="mdbook-searchbar-outer" class="searchbar-outer">
                         <div class="search-wrapper">
                             <input type="search" id="mdbook-searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="mdbook-searchresults-outer" aria-describedby="searchresults-header">
                             <div class="spinner-wrapper">
                                 <span class=fa-svg id="fa-spin"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M304 48c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zm0 416c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zM48 304c26.5 0 48-21.5 48-48s-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48zm464-48c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zM142.9 437c18.7-18.7 18.7-49.1 0-67.9s-49.1-18.7-67.9 0s-18.7 49.1 0 67.9s49.1 18.7 67.9 0zm0-294.2c18.7-18.7 18.7-49.1 0-67.9S93.7 56.2 75 75s-18.7 49.1 0 67.9s49.1 18.7 67.9 0zM369.1 437c18.7 18.7 49.1 18.7 67.9 0s18.7-49.1 0-67.9s-49.1-18.7-67.9 0s-18.7 49.1 0 67.9z"/></svg></span>
                             </div>
                         </div>
                     </form>
                     <div id="mdbook-searchresults-outer" class="searchresults-outer hidden">
                         <div id="mdbook-searchresults-header" class="searchresults-header"></div>
                         <ul id="mdbook-searchresults">
                         </ul>
                     </div>
                 </div>

                 <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                 <script>
                     document.getElementById('mdbook-sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
                     document.getElementById('mdbook-sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
                     Array.from(document.querySelectorAll('#mdbook-sidebar a')).forEach(function(link) {
                         link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
                     });
                 </script>

                 <div id="mdbook-content" class="content">
                     <main>
                         <h1 id="stability-attributes"><a class="header" href="#stability-attributes">Stability attributes</a></h1>
 <p>This section is about the stability attributes and schemes that allow stable
 APIs to use unstable APIs internally in the rustc standard library.</p>
 <p><strong>NOTE</strong>: this section is for <em>library</em> features, not <em>language</em> features. For instructions on
 stabilizing a language feature see <a href="./stabilization_guide.html">Stabilizing Features</a>.</p>
 <h2 id="unstable"><a class="header" href="#unstable">unstable</a></h2>
 <p>The <code>#[unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")]</code>
 attribute explicitly marks an item as unstable. Items that are marked as
 “unstable” cannot be used without a corresponding <code>#![feature]</code> attribute on
 the crate, even on a nightly compiler. This restriction only applies across
 crate boundaries, unstable items may be used within the crate that defines
 them.</p>
 <p>The <code>issue</code> field specifies the associated GitHub <a href="https://github.com/rust-lang/rust/issues">issue number</a>. This field is
 required and all unstable features should have an associated tracking issue. In
 rare cases where there is no sensible value <code>issue = "none"</code> is used.</p>
 <p>The <code>unstable</code> attribute infects all sub-items, where the attribute doesn’t
 have to be reapplied. So if you apply this to a module, all items in the module
 will be unstable.</p>
 <p>You can make specific sub-items stable by using the <code>#[stable]</code> attribute on
 them. The stability scheme works similarly to how <code>pub</code> works. You can have
 public functions of nonpublic modules and you can have stable functions in
 unstable modules or vice versa.</p>
 <p>Previously, due to a <a href="https://github.com/rust-lang/rust/issues/15702">rustc bug</a>, stable items inside unstable modules were
 available to stable code in that location.
 As of <!-- date-check --> September 2024, items with <a href="https://github.com/rust-lang/rust/issues/113387">accidentally stabilized
 paths</a> are marked with the <code>#[rustc_allowed_through_unstable_modules]</code> attribute
 to prevent code dependent on those paths from breaking. Do <em>not</em> add this attribute
 to any more items unless that is needed to avoid breaking changes.</p>
 <p>The <code>unstable</code> attribute may also have the <code>soft</code> value, which makes it a
 future-incompatible deny-by-default lint instead of a hard error. This is used
 by the <code>bench</code> attribute which was accidentally accepted in the past. This
 prevents breaking dependencies by leveraging Cargo’s lint capping.</p>
 <h2 id="stable"><a class="header" href="#stable">stable</a></h2>
 <p>The <code>#[stable(feature = "foo", since = "1.420.69")]</code> attribute explicitly
 marks an item as stabilized. Note that stable functions may use unstable things in their body.</p>
 <h2 id="rustc_const_unstable"><a class="header" href="#rustc_const_unstable">rustc_const_unstable</a></h2>
 <p>The <code>#[rustc_const_unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")]</code> has the same interface as the <code>unstable</code> attribute. It is used to mark
 <code>const fn</code> as having their constness be unstable. This is only needed in rare cases:</p>
 <ul>
 <li>If a <code>const fn</code> makes use of unstable language features or intrinsics.
 (The compiler will tell you to add the attribute if you run into this.)</li>
 <li>If a <code>const fn</code> is <code>#[stable]</code> but not yet intended to be const-stable.</li>
 <li>To change the feature gate that is required to call a const-unstable intrinsic.</li>
 </ul>
 <p>Const-stability differs from regular stability in that it is <em>recursive</em>: a
 <code>#[rustc_const_unstable(...)]</code> function cannot even be indirectly called from stable code. This is
 to avoid accidentally leaking unstable compiler implementation artifacts to stable code or locking
 us into the accidental quirks of an incomplete implementation. See the rustc_const_stable_indirect
 and rustc_allow_const_fn_unstable attributes below for how to fine-tune this check.</p>
 <h2 id="rustc_const_stable"><a class="header" href="#rustc_const_stable">rustc_const_stable</a></h2>
 <p>The <code>#[rustc_const_stable(feature = "foo", since = "1.420.69")]</code> attribute explicitly marks
 a <code>const fn</code> as having its constness be <code>stable</code>.</p>
 <h2 id="rustc_const_stable_indirect"><a class="header" href="#rustc_const_stable_indirect">rustc_const_stable_indirect</a></h2>
 <p>The <code>#[rustc_const_stable_indirect]</code> attribute can be added to a <code>#[rustc_const_unstable(...)]</code>
 function to make it callable from <code>#[rustc_const_stable(...)]</code> functions. This indicates that the
 function is ready for stable in terms of its implementation (i.e., it doesn’t use any unstable
 compiler features); the only reason it is not const-stable yet are API concerns.</p>
 <p>This should also be added to lang items for which const-calls are synthesized in the compiler, to
 ensure those calls do not bypass recursive const stability rules.</p>
 <h2 id="rustc_intrinsic_const_stable_indirect"><a class="header" href="#rustc_intrinsic_const_stable_indirect">rustc_intrinsic_const_stable_indirect</a></h2>
 <p>On an intrinsic, this attribute marks the intrinsic as “ready to be used by public stable functions”.
 If the intrinsic has a <code>rustc_const_unstable</code> attribute, it should be removed.
 <strong>Adding this attribute to an intrinsic requires t-lang and wg-const-eval approval!</strong></p>
 <h2 id="rustc_default_body_unstable"><a class="header" href="#rustc_default_body_unstable">rustc_default_body_unstable</a></h2>
 <p>The <code>#[rustc_default_body_unstable(feature = "foo", issue = "1234", reason = "lorem ipsum")]</code> attribute has the same interface as the <code>unstable</code> attribute.
 It is used to mark the default implementation for an item within a trait as
 unstable.
 A trait with a default-body-unstable item can be implemented stably by providing
 an explicit body for any such item, or the default body can be used by enabling
 its corresponding <code>#![feature]</code>.</p>
 <h2 id="stabilizing-a-library-feature"><a class="header" href="#stabilizing-a-library-feature">Stabilizing a library feature</a></h2>
 <p>To stabilize a feature, follow these steps:</p>
 <ol>
 <li>Ask a <strong>@T-libs-api</strong> member to start an FCP on the tracking issue and wait for
 the FCP to complete (with <code>disposition-merge</code>).</li>
 <li>Change <code>#[unstable(...)]</code> to <code>#[stable(since = "CURRENT_RUSTC_VERSION")]</code>.</li>
 <li>Remove <code>#![feature(...)]</code> from any test or doc-test for this API. If the feature is used in the
 compiler or tools, remove it from there as well.</li>
 <li>If this is a <code>const fn</code>, add <code>#[rustc_const_stable(since = "CURRENT_RUSTC_VERSION")]</code>.
 Alternatively, if this is not supposed to be const-stabilized yet,
 add <code>#[rustc_const_unstable(...)]</code> for some new feature gate (with a new tracking issue).</li>
 <li>Open a PR against <code>rust-lang/rust</code>.
 <ul>
 <li>Add the appropriate labels: <code>@rustbot modify labels: +T-libs-api</code>.</li>
 <li>Link to the tracking issue and say “Closes #XXXXX”.</li>
 </ul>
 </li>
 </ol>
 <p>You can see an example of stabilizing a feature with
 <a href="https://github.com/rust-lang/rust/issues/81656">tracking issue #81656 with FCP</a>
 and the associated
 <a href="https://github.com/rust-lang/rust/pull/84642">implementation PR #84642</a>.</p>
 <h2 id="allow_internal_unstable"><a class="header" href="#allow_internal_unstable">allow_internal_unstable</a></h2>
 <p>Macros and compiler desugarings expose their bodies to the call
 site. To work around not being able to use unstable things in the standard
 library’s macros, there’s the <code>#[allow_internal_unstable(feature1, feature2)]</code>
 attribute that allows the given features to be used in stable macros.</p>
 <p>Note that if a macro is used in const context and generates a call to a
 <code>#[rustc_const_unstable(...)]</code> function, that will <em>still</em> be rejected even with
 <code>allow_internal_unstable</code>. Add <code>#[rustc_const_stable_indirect]</code> to the function to ensure the macro
 cannot accidentally bypass the recursive const stability checks.</p>
 <h2 id="rustc_allow_const_fn_unstable"><a class="header" href="#rustc_allow_const_fn_unstable">rustc_allow_const_fn_unstable</a></h2>
 <p>As explained above, no unstable const features are allowed inside stable <code>const fn</code>, not even
 indirectly.</p>
 <p>However, sometimes we do know that a feature will get stabilized, just not when, or there is a
 stable (but e.g. runtime-slow) workaround, so we could always fall back to some stable version if we
 scrapped the unstable feature. In those cases, the <code>[rustc_allow_const_fn_unstable(feature1, feature2)]</code> attribute can be used to allow some unstable features in the body of a stable (or
 indirectly stable) <code>const fn</code>.</p>
 <p>You also need to take care to uphold the <code>const fn</code> invariant that calling it at runtime and
 compile-time needs to behave the same (see also <a href="https://www.ralfj.de/blog/2018/07/19/const.html">this blog post</a>). This means that you
 may not create a <code>const fn</code> that e.g. transmutes a memory address to an integer,
 because the addresses of things are nondeterministic and often unknown at
 compile-time.</p>
 <p><strong>Always ping @rust-lang/wg-const-eval if you are adding more
 <code>rustc_allow_const_fn_unstable</code> attributes to any <code>const fn</code>.</strong></p>
 <h2 id="staged_api"><a class="header" href="#staged_api">staged_api</a></h2>
 <p>Any crate that uses the <code>stable</code> or <code>unstable</code> attributes must include the
 <code>#![feature(staged_api)]</code> attribute on the crate.</p>
 <h2 id="deprecated"><a class="header" href="#deprecated">deprecated</a></h2>
 <p>Deprecations in the standard library are nearly identical to deprecations in
 user code. When <code>#[deprecated]</code> is used on an item, it must also have a <code>stable</code>
 or <code>unstable </code>attribute.</p>
 <p><code>deprecated</code> has the following form:</p>
 <pre><code class="language-rust ignore">#[deprecated(
     since = "1.38.0",
     note = "explanation for deprecation",
     suggestion = "other_function"
 )]</code></pre>
 <p>The <code>suggestion</code> field is optional. If given, it should be a string that can be
 used as a machine-applicable suggestion to correct the warning. This is
 typically used when the identifier is renamed, but no other significant changes
 are necessary. When the <code>suggestion</code> field is used, you need to have
 <code>#![feature(deprecated_suggestion)]</code> at the crate root.</p>
 <p>Another difference from user code is that the <code>since</code> field is actually checked
 against the current version of <code>rustc</code>. If <code>since</code> is in a future version, then
 the <code>deprecated_in_future</code> lint is triggered which is default <code>allow</code>, but most
 of the standard library raises it to a warning with
 <code>#![warn(deprecated_in_future)]</code>.</p>
 <h2 id="unstable_feature_bound"><a class="header" href="#unstable_feature_bound">unstable_feature_bound</a></h2>
 <p>The <code>#[unstable_feature_bound(foo)]</code> attribute can be used together with <code>#[unstable]</code> attribute to mark an <code>impl</code> of stable type and stable trait as unstable. In std/core, an item annotated with <code>#[unstable_feature_bound(foo)]</code> can only be used by another item that is also annotated with <code>#[unstable_feature_bound(foo)]</code>. Outside of std/core, using an item with <code>#[unstable_feature_bound(foo)]</code> requires the feature to be enabled with <code>#![feature(foo)]</code> attribute on the crate.</p>
 <p>Currently, the items that can be annotated with <code>#[unstable_feature_bound]</code> are:</p>
 <ul>
 <li><code>impl</code></li>
 <li>free function</li>
 <li>trait</li>
 </ul>

                     </main>

                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
                             <a rel="prev" href="stability-guarantees.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                 <span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M41.4 233.4c-12.5 12.5-12.5 32.8 0 45.3l160 160c12.5 12.5 32.8 12.5 45.3 0s12.5-32.8 0-45.3L109.3 256 246.6 118.6c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0l-160 160z"/></svg></span>
                             </a>

                             <a rel="next prefetch" href="stabilization_guide.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                 <span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M278.6 233.4c12.5 12.5 12.5 32.8 0 45.3l-160 160c-12.5 12.5-32.8 12.5-45.3 0s-12.5-32.8 0-45.3L210.7 256 73.4 118.6c-12.5-12.5-12.5-32.8 0-45.3s32.8-12.5 45.3 0l160 160z"/></svg></span>
                             </a>

                         <div style="clear: both"></div>
                     </nav>
                 </div>
             </div>

             <nav class="nav-wide-wrapper" aria-label="Page navigation">
                     <a rel="prev" href="stability-guarantees.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                         <span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M41.4 233.4c-12.5 12.5-12.5 32.8 0 45.3l160 160c12.5 12.5 32.8 12.5 45.3 0s12.5-32.8 0-45.3L109.3 256 246.6 118.6c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0l-160 160z"/></svg></span>
                     </a>

                     <a rel="next prefetch" href="stabilization_guide.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                         <span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M278.6 233.4c12.5 12.5 12.5 32.8 0 45.3l-160 160c-12.5 12.5-32.8 12.5-45.3 0s-12.5-32.8 0-45.3L210.7 256 73.4 118.6c-12.5-12.5-12.5-32.8 0-45.3s32.8-12.5 45.3 0l160 160z"/></svg></span>
                     </a>
             </nav>

         </div>

         <template id=fa-eye><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M288 32c-80.8 0-145.5 36.8-192.6 80.6C48.6 156 17.3 208 2.5 243.7c-3.3 7.9-3.3 16.7 0 24.6C17.3 304 48.6 356 95.4 399.4C142.5 443.2 207.2 480 288 480s145.5-36.8 192.6-80.6c46.8-43.5 78.1-95.4 93-131.1c3.3-7.9 3.3-16.7 0-24.6c-14.9-35.7-46.2-87.7-93-131.1C433.5 68.8 368.8 32 288 32zM432 256c0 79.5-64.5 144-144 144s-144-64.5-144-144s64.5-144 144-144s144 64.5 144 144zM288 192c0 35.3-28.7 64-64 64c-11.5 0-22.3-3-31.6-8.4c-.2 2.8-.4 5.5-.4 8.4c0 53 43 96 96 96s96-43 96-96s-43-96-96-96c-2.8 0-5.6 .1-8.4 .4c5.3 9.3 8.4 20.1 8.4 31.6z"/></svg></span></template>
         <template id=fa-eye-slash><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M38.8 5.1C28.4-3.1 13.3-1.2 5.1 9.2S-1.2 34.7 9.2 42.9l592 464c10.4 8.2 25.5 6.3 33.7-4.1s6.3-25.5-4.1-33.7L525.6 386.7c39.6-40.6 66.4-86.1 79.9-118.4c3.3-7.9 3.3-16.7 0-24.6c-14.9-35.7-46.2-87.7-93-131.1C465.5 68.8 400.8 32 320 32c-68.2 0-125 26.3-169.3 60.8L38.8 5.1zM223.1 149.5C248.6 126.2 282.7 112 320 112c79.5 0 144 64.5 144 144c0 24.9-6.3 48.3-17.4 68.7L408 294.5c5.2-11.8 8-24.8 8-38.5c0-53-43-96-96-96c-2.8 0-5.6 .1-8.4 .4c5.3 9.3 8.4 20.1 8.4 31.6c0 10.2-2.4 19.8-6.6 28.3l-90.3-70.8zm223.1 298L373 389.9c-16.4 6.5-34.3 10.1-53 10.1c-79.5 0-144-64.5-144-144c0-6.9 .5-13.6 1.4-20.2L83.1 161.5C60.3 191.2 44 220.8 34.5 243.7c-3.3 7.9-3.3 16.7 0 24.6c14.9 35.7 46.2 87.7 93 131.1C174.5 443.2 239.2 480 320 480c47.8 0 89.9-12.9 126.2-32.5z"/></svg></span></template>
         <template id=fa-copy><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M502.6 70.63l-61.25-61.25C435.4 3.371 427.2 0 418.7 0H255.1c-35.35 0-64 28.66-64 64l.0195 256C192 355.4 220.7 384 256 384h192c35.2 0 64-28.8 64-64V93.25C512 84.77 508.6 76.63 502.6 70.63zM464 320c0 8.836-7.164 16-16 16H255.1c-8.838 0-16-7.164-16-16L239.1 64.13c0-8.836 7.164-16 16-16h128L384 96c0 17.67 14.33 32 32 32h47.1V320zM272 448c0 8.836-7.164 16-16 16H63.1c-8.838 0-16-7.164-16-16L47.98 192.1c0-8.836 7.164-16 16-16H160V128H63.99c-35.35 0-64 28.65-64 64l.0098 256C.002 483.3 28.66 512 64 512h192c35.2 0 64-28.8 64-64v-32h-47.1L272 448z"/></svg></span></template>
         <template id=fa-play><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 384 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M73 39c-14.8-9.1-33.4-9.4-48.5-.9S0 62.6 0 80V432c0 17.4 9.4 33.4 24.5 41.9s33.7 8.1 48.5-.9L361 297c14.3-8.7 23-24.2 23-41s-8.7-32.2-23-41L73 39z"/></svg></span></template>
         <template id=fa-clock-rotate-left><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M75 75L41 41C25.9 25.9 0 36.6 0 57.9V168c0 13.3 10.7 24 24 24H134.1c21.4 0 32.1-25.9 17-41l-30.8-30.8C155 85.5 203 64 256 64c106 0 192 86 192 192s-86 192-192 192c-40.8 0-78.6-12.7-109.7-34.4c-14.5-10.1-34.4-6.6-44.6 7.9s-6.6 34.4 7.9 44.6C151.2 495 201.7 512 256 512c141.4 0 256-114.6 256-256S397.4 0 256 0C185.3 0 121.3 28.7 75 75zm181 53c-13.3 0-24 10.7-24 24V256c0 6.4 2.5 12.5 7 17l72 72c9.4 9.4 24.6 9.4 33.9 0s9.4-24.6 0-33.9l-65-65V152c0-13.3-10.7-24-24-24z"/></svg></span></template>


         <script>
             window.playground_copyable = true;
         </script>


         <script src="elasticlunr-ef4e11c1.min.js"></script>
         <script src="mark-09e88c2c.min.js"></script>
         <script src="searcher-c2a407aa.js"></script>

         <script src="clipboard-1626706a.min.js"></script>
         <script src="highlight-abc7f01d.js"></script>
         <script src="book-a0b12cfe.js"></script>

         <!-- Custom JS scripts -->
         <script src="mermaid-cc85ecea.min.js"></script>
         <script src="mermaid-init-4533fb11.js"></script>


     </div>
     </body>
 </html>