general.html

<cxx-clause id="general">
  <h1>General</h1>
  <cxx-section id="general.scope">
    <h1>Scope</h1>
    <p>This technical specification describes extensions to the C++
    Standard Library (<cxx-ref
    to="general.references"></cxx-ref>). These extensions are classes
    and functions that are likely to be used widely within a program
    and/or on the interface boundaries between libraries written by
    different organizations.</p>

    <p>This technical specification is non-normative. Some of the
    library components in this technical specification may be
    considered for standardization in a future version of C++, but
    they are not currently part of any C++ standard. Some of the
    components in this technical specification may never be
    standardized, and others may be standardized in a substantially
    changed form.</p>

    <p>The goal of this technical specification is to build more
    widespread existing practice for an expanded C++ standard
    library. It gives advice on extensions to those vendors who wish
    to provide them.</p>
  </cxx-section>

  <cxx-section id="general.references">
    <h1>Normative references</h1>

    <p>The following referenced document is indispensable for the
    application of this document. For dated references, only the
    edition cited applies. For undated references, the latest edition
    of the referenced document (including any amendments) applies.</p>

    <ul>
      <li>ISO/IEC 14882:2014, <cite>Programming Languages — C++</cite>
      <cxx-foreign-index id="cxx" src="cxx14_index.json" name="C++14"></cxx-foreign-index></li>
    </ul>

    <p>ISO/IEC 14882:— is herein called the <dfn>C++ Standard</dfn>.
    References to clauses within the C++ Standard are written as "C++14
    &#xa7;3.2". The library described in ISO/IEC 14882:— clauses 17–30 is
    herein called the <dfn>C++ Standard Library</dfn>.</p>

    <p>Unless otherwise specified, the whole of the C++ Standard's Library
    introduction (<cxx-ref in="cxx" to="library"></cxx-ref>) is included into this
    Technical Specification by reference.</p>
  </cxx-section>

  <cxx-section id="general.namespaces">
    <h1>Namespaces, headers, and modifications to standard classes</h1>

    <p>Since the extensions described in this technical specification
    are experimental and not part of the C++ standard library, they
    should not be declared directly within namespace
    <code>std</code>.
    Unless otherwise specified, all components described in this technical specification either:
    </p>
    <ul>
      <li>modify an existing interface in the C++ Standard Library in-place,</li>
      <li>
        are declared in a namespace whose name appends <code>::experimental::fundamentals_v2</code>
        to a namespace defined in the C++ Standard Library,
        such as <code>std</code> or <code>std::chrono</code>, or
      </li>
      <li>
        are declared in a subnamespace of a namespace described in the previous bullet,
        whose name is not the same as an existing subnamespace of namespace <code>std</code>.
      </li>
    </ul>

    <cxx-example>
      This TS does not define <code>std::experimental::fundamentals_v2::chrono</code>
      because the C++ Standard Library defines <code>std::chrono</code>.
      This TS does not define <code>std::pmr::experimental::fundamentals_v2</code>
      because the C++ Standard Library does not define <code>std::pmr</code>.
    </cxx-example>

    <p>Each header described in this technical
    specification shall import the contents of
    <code>std::experimental::fundamentals_v2</code> into
    <code>std::experimental</code> as if by</p>

    <pre><code>namespace std {
  namespace experimental {
    inline namespace fundamentals_v2 {}
  }
}</code></pre>

    <p>
      This technical specification also describes some experimental modifications to existing interfaces in the C++ Standard Library.
      These modifications are described by quoting the affected parts of the standard
      and using <ins>underlining</ins> to represent added text and <del>strike-through</del> to represent deleted text.
    </p>

    <p>Unless otherwise specified, references to other entities
    described in this technical specification are assumed to be
    qualified with <code>std::experimental::fundamentals_v2::</code>,
    and references to entities described in the standard are assumed
    to be qualified with <code>std::</code>.</p>

    <p>Extensions that are expected to eventually be added to an
    existing header <code>&lt;meow></code> are provided inside the
    <code>&lt;experimental/meow></code> header, which shall include
    the standard contents of <code>&lt;meow></code> as if by</p>
    <pre><code>#include &lt;meow></code></pre>

    <p>New headers are also provided in the
    <code>&lt;experimental/></code> directory, but without such an
    <code>#include</code>.</p>

    <table is="cxx-table" id="tab.cxx.headers" class="list" columns="3">
      <caption>C++ library headers</caption>
      <tr><td>
        <ul>
          <li><code>&lt;experimental/algorithm></code></li>
          <li><code>&lt;experimental/any></code></li>
          <li><code>&lt;experimental/array></code></li>
          <li><code>&lt;experimental/chrono></code></li>
          <li><code>&lt;experimental/deque></code></li>
          <li><code>&lt;experimental/forward_list></code></li>
          <li><code>&lt;experimental/functional></code></li>
          <li><code>&lt;experimental/future></code></li>
          <li><code>&lt;experimental/iterator></code></li>
          <li><code>&lt;experimental/list></code></li>
          <li><code>&lt;experimental/map></code></li>
          <li><code>&lt;experimental/memory></code></li>
          <li><code>&lt;experimental/memory_resource></code></li>
          <li><code>&lt;experimental/optional></code></li>
          <li><code>&lt;experimental/propagate_const></code></li>
          <li><code>&lt;experimental/random></code></li>
          <li><code>&lt;experimental/ratio></code></li>
          <li><code>&lt;experimental/regex></code></li>
          <li><code>&lt;experimental/set></code></li>
          <li><code>&lt;experimental/source_location></code></li>
          <li><code>&lt;experimental/string></code></li>
          <li><code>&lt;experimental/string_view></code></li>
          <li><code>&lt;experimental/system_error></code></li>
          <li><code>&lt;experimental/tuple></code></li>
          <li><code>&lt;experimental/type_traits></code></li>
          <li><code>&lt;experimental/unordered_map></code></li>
          <li><code>&lt;experimental/unordered_set></code></li>
          <li><code>&lt;experimental/utility></code></li>
          <li><code>&lt;experimental/vector></code></li>
        </ul>
      </td></tr>
    </table>
  </cxx-section>

  <cxx-section id="general.defns">
    <h1>Terms and definitions</h1>

    <p>For the purposes of this document, the terms and definitions
    given in the C++ Standard and the following apply.</p>

    <dl is="cxx-definition-section">
      <dt id="general.defns.direct-non-list-init">direct-non-list-initialization</dt>
      <dd>A direct-initialization that is not list-initialization.</dd>
    </dl>
  </cxx-section>

  <cxx-section id="general.plans">
    <h1>Future plans (Informative)</h1>

    <p>This section describes tentative plans for future versions of
    this technical specification and plans for moving content into
    future versions of the C++ Standard.</p>

    <p>The C++ committee intends to release a new version of this
    technical specification approximately every year, containing the
    library extensions we hope to add to a near-future version of the
    C++ Standard.  Future versions will define their contents in
    <code>std::experimental::fundamentals_v3</code>,
    <code>std::experimental::fundamentals_v4</code>, etc., with the
    most recent implemented version inlined into
    <code>std::experimental</code>.</p>

    <p>When an extension defined in this or a future version of this
    technical specification represents enough existing practice, it
    will be moved into the next version of the C++ Standard by
    removing the <code>experimental::fundamentals_v<var>N</var></code>
    segment of its namespace and by removing the
    <code>experimental/</code> prefix from its header's path.</p>
  </cxx-section>

  <cxx-section id="general.feature.test">
    <h1>Feature-testing recommendations (Informative)</h1>

    <p>
      For the sake of improved portability between partial implementations of various C++ standards,
      WG21 (the ISO technical committee for the C++ programming language) recommends
      that implementers and programmers follow the guidelines in this section concerning feature-test macros.
      <cxx-note><a href="http://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations">WG21's SD-6</a> makes similar recommendations for the C++ Standard itself.</cxx-note>
    </p>

    <p>
      Implementers who provide a new standard feature should define a macro with the recommended name,
      in the same circumstances under which the feature is available (for example, taking into account relevant command-line options),
      to indicate the presence of support for that feature.
      Implementers should define that macro with the value specified in
      the most recent version of this technical specification that they have implemented.
      The recommended macro name is "<code>__cpp_lib_experimental_</code>" followed by the string in the "Macro Name Suffix" column.
    </p>

    <p>
      Programmers who wish to determine whether a feature is available in an implementation should base that determination on
      the presence of the header (determined with <code>__has_include(&lt;header/name>)</code>) and
      the state of the macro with the recommended name.
      (The absence of a tested feature may result in a program with decreased functionality, or the relevant functionality may be provided in a different way.
      A program that strictly depends on support for a feature can just try to use the feature unconditionally;
      presumably, on an implementation lacking necessary support, translation will fail.)
    </p>

    <table is="cxx-table" class="column-rules">
      <caption>Significant features in this technical specification</caption>

      <thead>
        <tr>
          <th>Doc. No.</th>
          <th>Title</th>
          <th>Primary Section</th>
          <th>Macro Name Suffix</th>
          <th>Value</th>
          <th>Header</th>
        </tr>
      </thead>

      <!-- These rows are in the same order as their feature appears in this document. -->
      <tr>
        <td>N3915</td>
        <td>apply() call a function with arguments from a tuple</td>
        <td><cxx-ref to="tuple.apply"></cxx-ref></td>
        <td><code>apply</code></td>
        <td>201402</td>
        <td><code>&lt;experimental/tuple></code></td>
      </tr>
      <tr>
        <td>N3932</td>
        <td>Variable Templates For Type Traits</td>
        <td><cxx-ref to="meta.type.synop"></cxx-ref></td>
        <td><code>type_trait_variable_templates</code></td>
        <td>201402</td>
        <td><code>&lt;experimental/type_traits></code></td>
      </tr>
      <tr>
        <td>N3866</td>
        <td>Invocation type traits</td>
        <td><cxx-ref to="meta.trans.other"></cxx-ref></td>
        <td><code>invocation_type</code></td>
        <td>201406</td>
        <td><code>&lt;experimental/type_traits></code></td>
      </tr>
      <tr>
        <td>P0013R1</td>
        <td>Logical Operator Type Traits</td>
        <td><cxx-ref to="meta.logical"></cxx-ref></td>
        <td><code>logical_traits</code></td>
        <td>201511</td>
        <td><code>&lt;experimental/type_traits></code></td>
      </tr>
      <tr>
        <td>N4502</td>
        <td>The C++ Detection Idiom</td>
        <td><cxx-ref to="meta.detect"></cxx-ref></td>
        <td><code>detect</code></td>
        <td>201505</td>
        <td><code>&lt;experimental/type_traits></code></td>
      </tr>
      <tr>
        <td>N4388</td>
        <td>A Proposal to Add a Const-Propagating Wrapper to the Standard Library</th>
        <td><cxx-ref to="propagate_const"></cxx-ref></th>
        <td><code>propagate_const</code></th>
        <td>201505</th>
        <td><code>&lt;experimental/propagate_const></code></th>
      </tr>
      <tr>
        <td>N3916</td>
        <td>Type-erased allocator for <code>std::function</code></td>
        <td><cxx-ref to="func.wrap.func"></cxx-ref></td>
        <td><code>function_erased_allocator</code></td>
        <td>201406</td>
        <td><code>&lt;experimental/functional></code></td>
      </tr>
      <tr>
        <td>N3905</td>
        <td>Extending <code>std::search</code> to use Additional Searching Algorithms</td>
        <td><cxx-ref to="func.searchers"></cxx-ref></td>
        <td><code>boyer_moore_searching</code></td>
        <td>201411</td>
        <td><code>&lt;experimental/functional></code></td>
      </tr>
      <tr>
        <td>N4076</td>
        <td>A proposal to add a generalized callable negator</th>
        <td><cxx-ref to="func.not_fn"></cxx-ref></th>
        <td><code>not_fn</code></th>
        <td>201406</th>
        <td><code>&lt;experimental/functional></code></th>
      </tr>
      <tr>
        <td>N3672, N3793</td>
        <td>A utility class to represent optional objects</td>
        <td><cxx-ref to="optional"></cxx-ref></td>
        <td><code>optional</code></td>
        <td>201411</td>
        <td><code>&lt;experimental/optional></code></td>
      </tr>
      <tr>
        <td>N3804</td>
        <td>Any Library Proposal</td>
        <td><cxx-ref to="any"></cxx-ref></td>
        <td><code>any</code></td>
        <td>201411</td>
        <td><code>&lt;experimental/any></code></td>
      </tr>
      <tr>
        <td>N3921</td>
        <td><code>string_view</code>: a non-owning reference to a string</td>
        <td><cxx-ref to="string.view"></cxx-ref></td>
        <td><code>string_view</code></td>
        <td>201411</td>
        <td><code>&lt;experimental/string_view></code></td>
      </tr>
      <tr>
        <td>N3920</td>
        <td>Extending shared_ptr to Support Arrays</td>
        <td><cxx-ref to="memory.smartptr"></cxx-ref></td>
        <td><code>shared_ptr_arrays</code></td>
        <td>201406</td>
        <td><code>&lt;experimental/memory></code></td>
      </tr>
      <tr>
        <td>N3916</td>
        <td>Polymorphic Memory Resources</td>
        <td><cxx-ref to="memory.resource.synop"></cxx-ref></td>
        <td><code>memory_resources</code></td>
        <td>201402</td>
        <td><code>&lt;experimental/memory_resource></code></td>
      </tr>
      <tr>
        <td>N4282</td>
        <td>The World’s Dumbest Smart Pointer</th>
        <td><cxx-ref to="memory.observer.ptr"></cxx-ref></th>
        <td><code>observer_ptr</code></th>
        <td>201411</th>
        <td><code>&lt;experimental/memory></code></th>
      </tr>
      <tr>
        <td>N4273</td>
        <td>Uniform Container Erasure</td>
        <td><cxx-ref to="container.erasure"></cxx-ref></td>
        <td><code>erase_if</code></td>
        <td>201411</td>
        <td><code>&lt;experimental/vector></code></td>
      </tr>
      <tr>
        <td>N4391</td>
        <td>make_array</td>
        <td><cxx-ref to="container.array.creation"></cxx-ref></td>
        <td><code>make_array</code></td>
        <td>201505</td>
        <td><code>&lt;experimental/array></code></td>
      </tr>
      <tr>
        <td>N4257</td>
        <td>Delimited iterators</td>
        <td><cxx-ref to="iterator.ostream.joiner"></cxx-ref></td>
        <td><code>ostream_joiner</code></td>
        <td>201411</td>
        <td><code>&lt;experimental/iterator></code></td>
      </tr>
      <tr>
        <td>N3916</td>
        <td>Type-erased allocator for <code>std::promise</code></td>
        <td><cxx-ref to="futures.promise"></cxx-ref></td>
        <td><code>promise_erased_allocator</code></td>
        <td>201406</td>
        <td><code>&lt;experimental/future></code></td>
      </tr>
      <tr>
        <td>N3916</td>
        <td>Type-erased allocator for <code>std::packaged_task</code></td>
        <td><cxx-ref to="futures.task"></cxx-ref></td>
        <td><code>packaged_task_erased_allocator</code></td>
        <td>201406</td>
        <td><code>&lt;experimental/future></code></td>
      </tr>
      <tr>
        <td>N3925</td>
        <td>A <code>sample</code> Proposal</td>
        <td><cxx-ref to="alg.random.sample"></cxx-ref></td>
        <td><code>sample</code></td>
        <td>201402</td>
        <td><code>&lt;experimental/algorithm></code></td>
      </tr>
      <tr>
        <td>N4061</td>
        <td>Greatest Common Divisor and Least Common Multiple</td>
        <td><cxx-ref to="numeric.ops.gcd"></cxx-ref>, <cxx-ref to="numeric.ops.lcm"></cxx-ref></td>
        <td><code>gcd_lcm</code></td>
        <td>201411</td>
        <td><code>&lt;experimental/numeric></code></td>
      </tr>
      <tr>
        <td>N4531</td>
        <td><code>std::rand</code> replacement</td>
        <td><cxx-ref to="rand.util.randint"></cxx-ref></td>
        <td><code>randint</code></td>
        <td>201511</td>
        <td><code>&lt;experimental/random></code></td>
      </tr>
      <tr>
        <td>N4519</td>
        <td>Source-Code Information Capture</td>
        <td><cxx-ref to="reflection.src_loc"></cxx-ref></td>
        <td><code>source_location</code></td>
        <td>201505</td>
        <td><code>&lt;experimental/source_location></code></td>
      </tr>
    </table>
  </cxx-section>
</cxx-clause>