<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Identification of std</title>
</head>

<body>

<p>Doc. no.&nbsp;&nbsp; J16/03-0141=WG21/N1588<br>
Date:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 14 November 2003<br>
Project:&nbsp;&nbsp;&nbsp;&nbsp; Programming Language C++<br>
Reply to:&nbsp;&nbsp; Beman Dawes &lt;<a href="mailto:bdawes@acm.org">bdawes@acm.org</a>&gt;</p>

<h1>Library Technical Report Component Detection</h1>

<p><a href="#Motivation">Motivation</a><br>
<a href="#Requirements">Requirements and Objectives</a><br>
<a href="#Design">Design Rationale</a><br>
<a href="#Granularity">Granularity of macros</a><br>
<a href="#Transition">Transition between the TR and future standards</a><br>
<a href="#Names">Names</a><br>
<a href="#Proposed">Proposed additions to the TR</a></p>
<h2><a name="Motivation">Motivation</a></h2>
<p>Because the Library Technical Report (TR) is non-normative, implementers are 
permitted to ship partial implementations or to not implement the TR at all. At 
least one vendor has already begun shipping a partial implementation.</p>
<p>Users wishing to write portable programs that use TR components must 
therefore determine which TR components are 
actually available.</p>
<p>For example, several Boost libraries already use a component availability 
macro (BOOST_HAS_HASH) to determine if a non-standard hash map is available. If 
present, they use hash maps to speed execution, but otherwise rely on std::map.</p>
<p>Similarly, users of the Library TR code may wish to code something like this:</p>
<blockquote>
  <pre># include &lt;some_std_lib_header&gt;
# ifdef __TR12345_UNORDERED__
#   include &lt;unordered_map&gt;
# else
#   include &lt;map&gt;
# endif</pre>
</blockquote>

  <p>(For brevity, the example above ignores namespace and other naming issues.)</p>

  <p>Such usage is portable if the header and component macro are specified as 
  part of the Library TR. If not specified by the TR, then users are forced to 
  develop their own configuration mechanisms to determine TR component 
  availability. This would be a serious burden for users wishing to write 
  portable code.</p>
  <p>A second use case might occur when user code requires <i>std::tr1</i> components, and 
  wishes to issue an explicit error message when they are not present:</p>
<blockquote>
  <pre># include &lt;some_std_lib_header&gt;
# ifndef __TR12345_UNORDERED__
#   error Standard Library Technical Report &lt;unordered_map&gt; header required
# endif</pre>
</blockquote>
  <p>Note: This proposal does not deal with the question of how users request 
  that <code>std::tr1</code> components be made available by an implementation. That is an 
  orthogonal issue, and is already dealt with in the TR working paper.</p>
  <h2><a name="Requirements">Requirements</a> and Objectives</h2>
  <p>To provide a useful level of functionality to users without unduly 
  burdening implementers, a design needs to consider the following as at least 
  objectives if not downright requirements:</p>
<ol>
  <li>Portable and consistent across implementations.<br>
  <br>
  Rationale: The whole point of specifying component availability reporting in 
  the TR is to ensure it is portable. If component availability reporting is not 
  consistent across implementations, users cannot write portable code.<br>
&nbsp;</li>
  <li>Existing standard library implementations already report std::tr1 
  component availability correctly.<br>
  <br>
  Rationale: Ensures a smooth transition for users and implementers.<br>
  <br>
  Implications: Component availability must be reported by presence rather than 
  absence macros (assuming macros are the mechanism). The macros must reside in 
  a current standard library header to ensure that current implementations are 
  already conforming. <br>
&nbsp;</li>
  <li>Falsely reporting a component as not available is acceptable (although 
  obviously not desirable). Falsely reporting a component as available is not 
  acceptable.<br>
  <br>
  Rationale: Safety. Reliability.<br>
&nbsp;</li>
  <li>Works well with partial implementations of the TR.<br>
  <br>
  Rationale: Because the TR is non-normative, implementers are not required to 
  provide all components. For example, an implementation may choose not to 
  provide the special functions. Even if an implementation plans future support 
  for the full TR, such full support may take several releases to become 
  available.<br>
  <br>
  Implication: There needs to be some granularity in the reporting.<br>
&nbsp;</li>
  <li>Low overhead for users of the availability reporting, and no significant 
  cost to programs not concerned with component availability reporting.<br>
  <br>
  Implications: Component macros should appear in a nominally low-cost header - 
  not &lt;iostream&gt;, for example.<br>
&nbsp;</li>
  <li>Easy to specify, understand, implement, and use.<br>
  <br>
  Rationale: Feature detection is the appetizer, not the main meal. KISS.<br>
&nbsp;</li>
  <li>Compatible with C language. This may be a red-herring, but we should at 
  least run this proposal by the C committee to see if they have any concerns or 
  suggestions.<br>
  <br>
  Rationale: Since the C committee has indicated an intent to make the TR 
  Special Functions available to C programmers, the C++ committee should strive 
  to avoid gratuitous incompatibilities with the C language version.</li>
</ol>
<h2><a name="Design">Design</a> Rationale</h2>
<p>Much of the design is driven by the <a href="#Requirements">Requirements and Objectives</a>.</p>
<p>The &lt;limits&gt; header is chosen as the location of the macros since it best 
meets requirements (2), (5). Requirement (5) implies the 
macros are defined in existing headers, so a new header can't be used.</p>
<p>The proposed granularity is based on intuition rather than any hard-and-fast 
rule. If the granularity is too fine, implementations will diverge through 
honest confusion, and the names will be hard to remember. If the granularity is 
too coarse, there will be a mismatch between what components some implementers 
will wish to actually deliver and what components the macros identify.</p>
<h2><a name="Granularity">Granularity</a> of macros</h2>
<p>Pete Becker expressed concern over the fine granularity of the macros in
<a href="http://www.research.att.com/~ark/cgi-bin/wg21/message?wg=lib&msg=12274">
c++std-lib-12274</a>. Discussion followed.</p>
<p>Given that implementers are already shipping partial implementations of the 
TR, I continue to propose moderately macros with some granularity. I'm not 
adverse to reducing the granularity somewhat, but I feel it greatly benefits 
users to have some granularity.</p>
<h2><a name="Transition">Transition</a> between the TR and future standards</h2>
<p>Several LWG members expressed concern over the transition between the TR and 
future standards.</p>
<p>Two notes have been added to the proposal to make it clear to users that in 
the transition from the TR to future standards, the TR components will not 
remain in namespace <code>std::tr1</code> and the configuration macros will 
disappear.</p>
<h2><a name="Names">Names</a></h2>
<p>The proposed text below uses <code>__TRn</code> as a macro name prefix, where 
n is to be replaced by the ISO/IEC&nbsp; number assigned to the Technical Report. 
Other prefixes are possible.</p>
<h2><a name="Proposed">Proposed</a> Additions to the Library Technical Report</h2>
<h3>Proposed addition 1 (after [tr.intro.namespaces])</h3>
<p>[<i>Note:</i> Should any library components from this technical report become 
part of a future version of the C++ standard, they will be placed in a namespace 
other than <code>std::tr1</code>. <i>--end note</i>]</p>
<h3>Proposed addition 2 (at the end of [tr.intro])</h3>
<p>The availability of components described in this technical report are 
reported by the presence of the macros described in the Component Availability 
Macros Table. Each macro shall be defined if and only if the entire component it 
identifies is available. Each macro definition shall appear in the standard's &lt;limits&gt; 
header and in all other standard library or technical report headers containing the component or 
partial component that it identifies . The value of each macro is unspecified.</p>
<p>[<i>Note:</i> These macros will not appear in future versions of the C++ 
standard. Future versions of the standard can be identified by the value of the 
predefined macro <code>__cplusplus</code>. <i>--end note]</i></p>
<h3>Component Availability Macros Table</h3>
<p><i>[Note to editor: replace n below by the ISO/IEC&nbsp; number assigned to 
the Technical Report.]</i></p>
<table border="1" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="100%" cellpadding="5">
  <tr>
    <td width="28%" align="center"><b>Macro</b></td>
    <td width="72%" align="center"><b>Component</b></td>
  </tr>
  <tr>
    <td width="28%"><code>__TRn__</code></td>
    <td width="72%">All. [note - not defined unless all TR components are 
    available. - end note]</td>
  </tr>
  <tr>
    <td width="28%"><code>__TRn_UTILITY__</code></td>
    <td width="72%">Reference wrappers ([tr.util.refwrp.synopsis])</td>
  </tr>
  <tr>
    <td width="28%"><code>__TRn_MEMORY__</code></td>
    <td width="72%">Smart Pointers ([tr.util.smartptr])</td>
  </tr>
  <tr>
    <td width="28%"><code>__TRn_FUNCTIONAL__</code></td>
    <td width="72%">Function objects and higher-order programming. ([tr.func])</td>
  </tr>
  <tr>
    <td width="28%"><code>__TRn_TYPE_TRAITS__</code></td>
    <td width="72%">Metaprogramming and type traits ([tr.meta])</td>
  </tr>
  <tr>
    <td width="28%"><code>__TRn_RANDOM__</code></td>
    <td width="72%">Random number generation ([tr.rand])</td>
  </tr>
  <tr>
    <td width="28%"><code>__TRn_MATH__</code></td>
    <td width="72%">Mathematical special functions ([tr.rand])</td>
  </tr>
  <tr>
    <td width="28%"><code>__TRn_TUPLE__</code></td>
    <td width="72%">Tuple types ([tr.tuple])</td>
  </tr>
  <tr>
    <td width="28%"><code>__TRn_UNORDERED__</code></td>
    <td width="72%">Unordered associative containers ([tr.hash]) [note - also 
    defined in &lt;functional&gt;. - end note]</td>
  </tr>
  <tr>
    <td width="28%"><code>__TRn_REGEX__</code></td>
    <td width="72%">Regular expressions ([tr.re])</td>
  </tr>
  <tr>
    <td width="28%"><code>__TRn_ARRAY__</code></td>
    <td width="72%">Fixed size array wrapper ([TBD])</td>
  </tr>
  <tr>
    <td width="28%"><code>__TRn_ITERATOR__</code></td>
    <td width="72%">Iterator concepts, facades, and adaptors ([TBD])</td>
  </tr>
  <tr>
    <td width="28%"><code>__TRn_C99__</code></td>
    <td width="72%">C99 library ([TBD])</td>
  </tr>
</table>
<hr>
<p> Copyright Beman Dawes, 2003.</p>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->14 November, 2003<!--webbot bot="Timestamp" endspan i-checksum="39360" --></p>
<p>&nbsp;</p>

</body>

</html>