<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>Any Library Proposal for TR2</title>
</head>

<body>

<p>Doc. no.&nbsp;&nbsp; WG21/N1939=J16/06-0009<br>
Date:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y-%m-%d" startspan -->2006-02-24<!--webbot bot="Timestamp" endspan i-checksum="12140" --><br>
Project:&nbsp;&nbsp;&nbsp;&nbsp; Programming Language C++<br>
Reply to:&nbsp;&nbsp; Kevlin Henney &lt;<a href="mailto:kevlin@curbralan.com">kevlin@curbralan.com</a>&gt;<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 
Beman&nbsp; Dawes &lt;<a href="mailto:bdawes@acm.org">bdawes@acm.org</a>&gt;</p>
<h1><i>Any</i> Library Proposal for TR2</h1>
<h2><a name="Introduction">Introduction</a></h2>
<p>This paper proposes addition of a library component to the C++ Standard 
Library Technical Report 2. The proposal is based on the Boost Any Library (see
<a href="http://www.boost.org/libs/any">www.boost.org/libs/any</a>).</p>
<p>The library provides a type-safe container for single values of value types. 
The Boost version of the library is widely used. The library would be a pure 
addition to the C++ Standard Library TR2.</p>
<p>There are times when a generic (in the sense of <span class="emphasis"><em>
general</em></span> as opposed to <span class="emphasis"><em>template-based 
programming</em></span>) type is needed: variables that are truly variable, 
accommodating values of many other more specific types rather than C++'s normal 
strict and static types. We can distinguish three basic kinds of generic type:</p>
<ol>
  <li>Converting types that can hold one of a number of possible value types, 
  e.g. <code class="computeroutput">int</code> and <code class="computeroutput">
  string</code>, and freely convert between them, for instance interpreting
  <code class="computeroutput">5</code> as <code class="computeroutput">&quot;5&quot;</code> 
  or vice-versa. Such types are common in scripting and other interpreted 
  languages. <code class="computeroutput">boost::lexical_cast</code> supports 
  such conversion functionality.<br>
&nbsp;</li>
  <li>Discriminated types that contain values of different types but do not 
  attempt conversion between them, i.e. <code class="computeroutput">5</code> is 
  held strictly as an <code class="computeroutput">int</code> and is not 
  implicitly convertible either to <code class="computeroutput">&quot;5&quot;</code> or to
  <code class="computeroutput">5.0</code>. Their indifference to interpretation 
  but awareness of type effectively makes them safe, generic containers of 
  single values, with no scope for surprises from ambiguous conversions.<br>
&nbsp;</li>
  <li>Indiscriminate types that can refer to anything but are oblivious to the 
  actual underlying type, entrusting all forms of access and interpretation to 
  the programmer. This niche is dominated by <code class="computeroutput">void *</code>, 
  which offers plenty of scope for surprising, undefined behavior.</li>
</ol>
<p>The proposed <code>any</code> class (based on the class of the same name 
described in
<a href="http://www.two-sdg.demon.co.uk/curbralan/papers/ValuedConversions.pdf" target="_top">
&quot;Valued Conversions&quot;</a> by Kevlin Henney, <span class="emphasis"><em>C++ Report</em></span> 
12(7), July/August 2000) is a variant value type based on the second category. 
It supports copying of any value type and safe checked extraction of that value 
strictly against its type.</p>
<p>A similar design, offering more appropriate operators, could be used for a 
generalized function adaptor, a generalized iterator adaptor,&nbsp; and other 
object types that need uniform runtime treatment but support only compile-time 
template parameter conformance. Such components are not proposed here.</p>
<h2><a name="Examples">Examples</a></h2>
<p>The following code demonstrates the syntax for using implicit conversions to 
and copying of any objects:</p>
<blockquote>
  <pre class="programlisting">#include &lt;list&gt;
#include &lt;any&gt;

using <code>std::tr2</code><code class="computeroutput">::any_cast</code>;
using std::tr2::any;

typedef std::list&lt;<code class="computeroutput">any</code>&gt; many;

void append_int(many &amp; values, int value)
{
    <code class="computeroutput">any</code> to_append = value;
    values.push_back(to_append);
}

void append_string(many &amp; values, const std::string &amp; value)
{
    values.push_back(value);
}

void append_char_ptr(many &amp; values, const char * value)
{
    values.push_back(value);
}

void append_any(many &amp; values, const <code class="computeroutput">any</code> &amp; value)
{
    values.push_back(value);
}

void append_nothing(many &amp; values)
{
    values.push_back(());
}</pre>
</blockquote>
<p>The following predicates follow on from the previous definitions and 
demonstrate the use of queries on any objects:</p>
<blockquote>
  <pre class="programlisting">bool is_empty(const <code class="computeroutput">any</code> &amp; operand)
{
    return operand.<code class="computeroutput">empty</code>();
}

bool is_int(const <code class="computeroutput">any</code> &amp; operand)
{
    return operand.<code class="computeroutput">type</code>() == typeid(int);
}

bool is_char_ptr(const <code class="computeroutput">any</code> &amp; operand)
{
    try
    {
        <code class="computeroutput">any_cast</code>&lt;const char *&gt;(operand);
        return true;
    }
    catch(const <code class="computeroutput">std::tr2::bad_any_cast</code> &amp;)
    {
        return false;
    }
}

bool is_string(const <code class="computeroutput">any</code> &amp; operand)
{
    return <code class="computeroutput">any_cast</code>&lt;std::string&gt;(&amp;operand);
}

void count_all(many &amp; values, std::ostream &amp; out)
{
    out &lt;&lt; &quot;#empty == &quot;
        &lt;&lt; std::count_if(values.begin(), values.end(), is_empty) &lt;&lt; std::endl;
    out &lt;&lt; &quot;#int == &quot;
        &lt;&lt; std::count_if(values.begin(), values.end(), is_int) &lt;&lt; std::endl;
    out &lt;&lt; &quot;#const char * == &quot;
        &lt;&lt; std::count_if(values.begin(), values.end(), is_char_ptr) &lt;&lt; std::endl;
    out &lt;&lt; &quot;#string == &quot;
        &lt;&lt; std::count_if(values.begin(), values.end(), is_string) &lt;&lt; std::endl;
}
</pre>
</blockquote>
<p>The following type, patterned after the OMG's Property Service, defines 
name-value pairs for arbitrary value types:</p>
<blockquote>
  <pre class="programlisting">struct property
{
    property();
    property(const std::string &amp;, const <code class="computeroutput">any</code> &amp;);

    std::string name;
    <code class="computeroutput">any</code> value;
};

typedef std::list&lt;property&gt; properties;
</pre>
</blockquote>
<p>The following base class demonstrates one approach to runtime polymorphism 
based callbacks that also require arbitrary argument types. The absence of 
virtual member templates requires that different solutions have different 
trade-offs in terms of efficiency, safety, and generality. Using a checked 
variant type offers one approach:</p>
<blockquote>
  <pre class="programlisting">class consumer
{
public:
    virtual void notify(const <code class="computeroutput">any</code> &amp;) = 0;
    ...
};</pre>
</blockquote>

<h2><a name="Proposed-Text">Proposed Text</a></h2>

<p>This clause describes components that C++ programs may use to perform 
operations on objects of a discriminated type.</p>

<blockquote>

<p>[<i>Note:</i> The discriminated type may contain values of different types 
but does not attempt conversion between them, i.e. <code class="computeroutput">
5</code> is held strictly as an <code class="computeroutput">int</code> and is 
not implicitly convertible either to <code class="computeroutput">&quot;5&quot;</code> or 
to <code class="computeroutput">5.0</code>. This indifference to interpretation 
but awareness of type effectively allows safe, generic containers of single 
values, with no scope for surprises from ambiguous conversions. <i>-- end note.</i>]</p>

</blockquote>

<h3>ValueType requirements</h3>

<p>A <i>ValueType</i> type shall meet the requirements for CopyConstructible 
[20.1.3]. A <i>ValueType</i> type may optiionally meet the requirements for 
Assignable [23.1]. The strong exception-safety guarantee is required for all 
forms of assignment. The destructor for <i>ValueType</i> types shall provide the no-throw exception-safety 
guarantee.</p>

<blockquote>

<p>[<i>Note:</i> Values are strongly informational objects for which identity is not significant, 
i.e. the focus is principally on their state content and any behavior organized 
around that. Another distinguishing feature of values is their granularity: 
normally fine-grained objects representing simple concepts in the system such as 
quantities.</p>

<p>As the emphasis of a value lies in its state not its identity, values can be 
copied and typically assigned one to another, requiring the explicit or implicit 
definition of a public copy constructor and public assignment operator. Values 
typically live within other scopes, i.e. within objects or blocks, rather than 
on the heap. Values are therefore normally passed around and manipulated 
directly as variables or through references, but not as pointers that emphasize 
identity and indirection. <i>--end note</i>]</p>

</blockquote>

<h3>Header &lt;any.hpp&gt; synopsis</h3>
<blockquote>
  <pre>class bad_any_cast : public std::bad_cast
{
public:
  virtual const char * what() const;
};

class any
{
public:
  // construct/copy/destruct
  any();
  any(const any &amp;);

  template&lt;typename ValueType&gt; any(const ValueType &amp;);

  any &amp; operator=(const any &amp;);

  template&lt;typename ValueType&gt; any &amp; operator=(const ValueType &amp;);

 ~any();

  // modifiers
  any &amp; swap(any &amp;);

  // observers
  bool empty() const;
  const std::type_info &amp; type() const;
};

template&lt;typename ValueType&gt; ValueType any_cast(const any &amp;);
template&lt;typename ValueType&gt; const ValueType * any_cast(const any *);
template&lt;typename ValueType&gt; ValueType * any_cast(any *);</pre>
</blockquote>
<h3>Class bad_any_cast</h3>
<p>Objects of type <code>bad_any_cast</code> are thrown by a failed <code>
any_cast</code>.</p>
<h3>Class any</h3>
<p>Objects of class <code>any</code> can hold instances of any type that 
satisfies ValueType requirements.</p>
<h4>construct/copy/destruct</h4>
<pre>any();</pre>
<blockquote>
  <p><i>Postconditions:</i> <code>this-&gt;empty()</code></p>
</blockquote>
<pre>any(const any &amp; other);</pre>
<blockquote>
  <p><i>Effects:</i> Copy constructor that copies content of other into new 
  instance, so that any content is equivalent in both type and value to the 
  content of other, or empty if other is empty.</p>
  <p><i>Throws:</i> May throw a <code>bad_alloc</code> exception or any 
  exceptions arising from the copy constructor of the contained type.</p>
</blockquote>
<pre>template&lt;typename ValueType&gt; any(const ValueType &amp; value);</pre>
<blockquote>
  <p><i>Effects:</i> Makes a copy of <code>value</code>, so that the initial 
  content of the new instance is equivalent in both type and value to value.</p>
  <p><i>Throws:</i> <code>bad_alloc</code> or any exceptions arising from the 
  copy constructor of the contained type.</p>
</blockquote>
<pre>any &amp; operator=(const any &amp; rhs);</pre>
<blockquote>
  <p><i>Effects:</i> Copies content of <code>rhs</code> into current instance, 
  discarding previous content, so that the new content is equivalent in both 
  type and value to the content of <code>rhs</code>, or empty if <code>rhs.empty()</code>.</p>
  <p><i>Throws:</i> <code>std::bad_alloc</code> or any exceptions arising from 
  the copy constructor of the contained type. Assignment satisfies the strong 
  guarantee of exception safety.</p>
</blockquote>
<pre>template&lt;typename ValueType&gt; any &amp; operator=(const ValueType &amp; rhs);</pre>
<blockquote>
  <p><i>Effects:</i> Makes a copy of <code>rhs</code>, discarding previous 
  content, so that the new content of is equivalent in both type and value to
  <code>rhs</code>.</p>
  <p><i>Throws:</i> <code>bad_alloc</code> or any exceptions arising from the 
  copy constructor of the contained type. Assignment satisfies the strong 
  guarantee of exception safety.</p>
</blockquote>
<pre>~any();</pre>
<blockquote>
  <p><i>Effects:</i> Releases any and all resources used in management of 
  instance.</p>
  <p><i>Throws:</i> Nothing.</p>
</blockquote>
<h4>any modifiers</h4>
<p>any &amp; swap(any &amp; rhs);</p>
<blockquote>
  <p><i>Effects:</i> Exchange of the contents of <code>*this</code> and <code>
  rhs</code>.</p>
  <p><i>Returns:</i> <code>*this</code></p>
  <p><i>Throws:</i> Nothing.</p>
</blockquote>
<h4>any queries</h4>
<pre>bool empty() const;</pre>
<blockquote>
  <p><i>Returns:</i> <code>true</code> if instance is empty, otherwise <code>
  false</code>.</p>
  <p><i>Throws:</i> Does not throw.</p>
</blockquote>
<p><code>const std::type_info &amp; type() const;</code></p>
<blockquote>
  <p><i>Returns:</i> the typeid of the contained value if instance is non-empty, 
  otherwise <code>typeid(void)</code>. </p>
  <p>[<i>Note:</i> Useful for querying against types known either at compile 
  time or only at runtime. <i>--end note</i>]</p>
</blockquote>
<h3>Non-member functions</h3>
<pre>template&lt;typename ValueType&gt; ValueType any_cast(const any &amp; operand);</pre>
<blockquote>
  <p><i>Returns:</i> The value contained by <code>operand</code>.</p>
  <p><i>Throws:</i> <code>bad_any_cast</code> if unsuccessful.</p>
  <p>[<i>Note: </i>A copy is returned because the C++ keyword casts return 
  copies.<i>--end note.</i>]</p>
</blockquote>
<pre>template&lt;typename ValueType&gt; const ValueType * any_cast(const any * operand);
template&lt;typename ValueType&gt; ValueType * any_cast(any * operand);</pre>
<blockquote>
  <p><i>Returns: </i>A similarly qualified pointer to the value content if 
  successful, otherwise null.</p>
</blockquote>
<hr>
<p> Copyright 2001 Kevlin Henney<br>
 Copyright 2006 Beman Dawes</p>
<p>Revised
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y-%m-%d" startspan -->2006-02-24<!--webbot bot="Timestamp" endspan i-checksum="12140" --></p>

</body>

</html>