libs/core/doc/html/core/scoped_enum.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>scoped_enum</title>
   5 <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Boost.Core">
   8 <link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Boost.Core">
   9 <link rel="prev" href="../boost/unwrap_ref.html" title="Function template unwrap_ref">
  10 <link rel="next" href="swap.html" title="swap">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="../boost/unwrap_ref.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="swap.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="core.scoped_enum"></a><a class="link" href="scoped_enum.html" title="scoped_enum">scoped_enum</a>
  28 </h2></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="scoped_enum.html#core.scoped_enum.overview">Overview</a></span></dt>
  31 <dt><span class="section"><a href="scoped_enum.html#core.scoped_enum.deprecated_syntax">Deprecated syntax</a></span></dt>
  32 <dt><span class="section"><a href="scoped_enum.html#core.scoped_enum.acquiring_the_underlying_type_of">Acquiring
  33       the underlying type of the enum</a></span></dt>
  34 <dt><span class="section"><a href="scoped_enum.html#core.scoped_enum.acknowledgments">Acknowledgments</a></span></dt>
  35 </dl></div>
  36 <div class="simplesect">
  37 <div class="titlepage"><div><div><h3 class="title">
  38 <a name="idm46687073461040"></a>Authors</h3></div></div></div>
  39 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  40 <li class="listitem">
  41           Beman Dawes
  42         </li>
  43 <li class="listitem">
  44           Vicente J. Botet Escriba
  45         </li>
  46 <li class="listitem">
  47           Anthony Williams
  48         </li>
  49 </ul></div>
  50 </div>
  51 <div class="section">
  52 <div class="titlepage"><div><div><h3 class="title">
  53 <a name="core.scoped_enum.overview"></a><a class="link" href="scoped_enum.html#core.scoped_enum.overview" title="Overview">Overview</a>
  54 </h3></div></div></div>
  55 <p>
  56         The <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">core</span><span class="special">/</span><span class="identifier">scoped_enum</span><span class="special">.</span><span class="identifier">hpp</span></code> header
  57         contains a number of macros that can be used to generate C++11 scoped enums
  58         (7.2 [dcl.enum]) if the feature is supported by the compiler, otherwise emulate
  59         it with C++03 constructs. The <code class="computeroutput"><span class="identifier">BOOST_NO_CXX11_SCOPED_ENUMS</span></code>
  60         macro from Boost.Config is used to detect the feature support in the compiler.
  61       </p>
  62 <p>
  63         Some of the enumerations defined in the standard library are scoped enums.
  64       </p>
  65 <pre class="programlisting"><span class="keyword">enum</span> <span class="keyword">class</span> <span class="identifier">future_errc</span>
  66 <span class="special">{</span>
  67     <span class="identifier">broken_promise</span><span class="special">,</span>
  68     <span class="identifier">future_already_retrieved</span><span class="special">,</span>
  69     <span class="identifier">promise_already_satisfied</span><span class="special">,</span>
  70     <span class="identifier">no_state</span>
  71 <span class="special">};</span>
  72 </pre>
  73 <p>
  74         The user can portably declare such enumeration as follows:
  75       </p>
  76 <pre class="programlisting"><span class="identifier">BOOST_SCOPED_ENUM_DECLARE_BEGIN</span><span class="special">(</span><span class="identifier">future_errc</span><span class="special">)</span>
  77 <span class="special">{</span>
  78     <span class="identifier">broken_promise</span><span class="special">,</span>
  79     <span class="identifier">future_already_retrieved</span><span class="special">,</span>
  80     <span class="identifier">promise_already_satisfied</span><span class="special">,</span>
  81     <span class="identifier">no_state</span>
  82 <span class="special">}</span>
  83 <span class="identifier">BOOST_SCOPED_ENUM_DECLARE_END</span><span class="special">(</span><span class="identifier">future_errc</span><span class="special">)</span>
  84 </pre>
  85 <p>
  86         These macros allows to use <code class="computeroutput"><span class="identifier">future_errc</span></code>
  87         in almost all the cases as an scoped enum.
  88       </p>
  89 <pre class="programlisting"><span class="identifier">future_errc</span> <span class="identifier">ev</span> <span class="special">=</span> <span class="identifier">future_errc</span><span class="special">::</span><span class="identifier">no_state</span><span class="special">;</span>
  90 </pre>
  91 <p>
  92         It is possible to specify the underlying type of the enumeration:
  93       </p>
  94 <pre class="programlisting"><span class="identifier">BOOST_SCOPED_ENUM_UT_DECLARE_BEGIN</span><span class="special">(</span><span class="identifier">future_errc</span><span class="special">,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span><span class="special">)</span>
  95 <span class="special">{</span>
  96     <span class="identifier">broken_promise</span><span class="special">,</span>
  97     <span class="identifier">future_already_retrieved</span><span class="special">,</span>
  98     <span class="identifier">promise_already_satisfied</span><span class="special">,</span>
  99     <span class="identifier">no_state</span>
 100 <span class="special">}</span>
 101 <span class="identifier">BOOST_SCOPED_ENUM_DECLARE_END</span><span class="special">(</span><span class="identifier">future_errc</span><span class="special">)</span>
 102 </pre>
 103 <p>
 104         The enumeration supports explicit conversion from the underlying type.
 105       </p>
 106 <p>
 107         The enumeration can be forward declared:
 108       </p>
 109 <pre class="programlisting"><span class="identifier">BOOST_SCOPED_ENUM_FORWARD_DECLARE</span><span class="special">(</span><span class="identifier">future_errc</span><span class="special">);</span>
 110 </pre>
 111 <p>
 112         There are however some limitations. The emulated scoped enum is not a C++
 113         enum, so <code class="computeroutput"><span class="identifier">is_enum</span><span class="special">&lt;</span>
 114         <span class="identifier">future_errc</span> <span class="special">&gt;</span></code>
 115         will be <code class="computeroutput"><span class="identifier">false_type</span></code>.
 116       </p>
 117 <p>
 118         The emulated scoped enum can not be used in switch nor in template arguments.
 119         For these cases the user needs to use some helpers. Instead of
 120       </p>
 121 <pre class="programlisting"><span class="keyword">switch</span> <span class="special">(</span><span class="identifier">ev</span><span class="special">)</span>
 122 <span class="special">{</span>
 123 <span class="keyword">case</span> <span class="identifier">future_errc</span><span class="special">::</span><span class="identifier">broken_promise</span><span class="special">:</span>
 124     <span class="comment">// ...</span>
 125 </pre>
 126 <p>
 127         use
 128       </p>
 129 <pre class="programlisting"><span class="keyword">switch</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">native_value</span><span class="special">(</span><span class="identifier">ev</span><span class="special">))</span>
 130 <span class="special">{</span>
 131 <span class="keyword">case</span> <span class="identifier">future_errc</span><span class="special">::</span><span class="identifier">broken_promise</span><span class="special">:</span>
 132     <span class="comment">// ...</span>
 133 </pre>
 134 <p>
 135         and instead of
 136       </p>
 137 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;&gt;</span>
 138 <span class="keyword">struct</span> <span class="identifier">is_error_code_enum</span><span class="special">&lt;</span> <span class="identifier">future_errc</span> <span class="special">&gt;</span> <span class="special">:</span>
 139     <span class="keyword">public</span> <span class="identifier">true_type</span>
 140 <span class="special">{</span>
 141 <span class="special">};</span>
 142 </pre>
 143 <p>
 144         use
 145       </p>
 146 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;&gt;</span>
 147 <span class="keyword">struct</span> <span class="identifier">is_error_code_enum</span><span class="special">&lt;</span> <span class="identifier">BOOST_SCOPED_ENUM_NATIVE</span><span class="special">(</span><span class="identifier">future_errc</span><span class="special">)</span> <span class="special">&gt;</span> <span class="special">:</span>
 148     <span class="keyword">public</span> <span class="identifier">true_type</span>
 149 <span class="special">{</span>
 150 <span class="special">};</span>
 151 </pre>
 152 <p>
 153         Explicit conversion to the underlying type should be performed with <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">underlying_cast</span></code> instead of <code class="computeroutput"><span class="keyword">static_cast</span></code>:
 154       </p>
 155 <pre class="programlisting"><span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">val</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">underlying_cast</span><span class="special">&lt;</span> <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="special">&gt;(</span><span class="identifier">ev</span><span class="special">);</span>
 156 </pre>
 157 <p>
 158         In C++03, scoped enums behave differently in case of calling an overloaded
 159         function when one overload takes a scoped enum as a parameter, and the other
 160         takes a parameter of an integral type. Consider the following code:
 161       </p>
 162 <pre class="programlisting"><span class="keyword">enum</span> <span class="identifier">enum_regular</span> <span class="special">{</span> <span class="identifier">REGULAR_A</span><span class="special">,</span> <span class="identifier">REGULAR_B</span> <span class="special">};</span>
 163
 164 <span class="identifier">BOOST_SCOPED_ENUM_DECLARE_BEGIN</span><span class="special">(</span><span class="identifier">enum_scoped</span><span class="special">)</span>
 165 <span class="special">{</span>
 166     <span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span>
 167 <span class="special">}</span>
 168 <span class="identifier">BOOST_SCOPED_ENUM_DECLARE_END</span><span class="special">(</span><span class="identifier">enum_scoped</span><span class="special">)</span>
 169
 170 <span class="keyword">void</span> <span class="identifier">regular_or_int</span><span class="special">(</span><span class="identifier">enum_regular</span><span class="special">);</span> <span class="comment">// (1)</span>
 171 <span class="keyword">void</span> <span class="identifier">regular_or_int</span><span class="special">(</span><span class="keyword">int</span><span class="special">);</span>          <span class="comment">// (2)</span>
 172 <span class="keyword">void</span> <span class="identifier">scoped_or_int</span><span class="special">(</span><span class="identifier">enum_scoped</span><span class="special">);</span>   <span class="comment">// (3)</span>
 173 <span class="keyword">void</span> <span class="identifier">scoped_or_int</span><span class="special">(</span><span class="keyword">int</span><span class="special">);</span>           <span class="comment">// (4)</span>
 174
 175 <span class="identifier">regular_or_int</span><span class="special">(</span><span class="identifier">REGULAR_A</span><span class="special">);</span>                  <span class="comment">// calls (1) in C++03 and C++11</span>
 176 <span class="identifier">scoped_or_int</span><span class="special">(</span><span class="identifier">enum_scoped</span><span class="special">::</span><span class="identifier">a</span><span class="special">);</span>              <span class="comment">// calls (3) in C++11 but (4) in C++03!</span>
 177 <span class="identifier">scoped_or_int</span><span class="special">(</span><span class="identifier">enum_scoped</span><span class="special">(</span><span class="identifier">enum_scoped</span><span class="special">::</span><span class="identifier">a</span><span class="special">));</span> <span class="comment">// calls (3) in C++03 and C++11</span>
 178 </pre>
 179 <p>
 180         Here is usage example:
 181       </p>
 182 <pre class="programlisting"><span class="identifier">BOOST_SCOPED_ENUM_UT_DECLARE_BEGIN</span><span class="special">(</span><span class="identifier">algae</span><span class="special">,</span> <span class="keyword">char</span><span class="special">)</span>
 183 <span class="special">{</span>
 184     <span class="identifier">green</span><span class="special">,</span>
 185     <span class="identifier">red</span><span class="special">,</span>
 186     <span class="identifier">cyan</span>
 187 <span class="special">}</span>
 188 <span class="identifier">BOOST_SCOPED_ENUM_DECLARE_END</span><span class="special">(</span><span class="identifier">algae</span><span class="special">)</span>
 189 <span class="special">...</span>
 190 <span class="identifier">algae</span> <span class="identifier">sample</span><span class="special">(</span> <span class="identifier">algae</span><span class="special">::</span><span class="identifier">red</span> <span class="special">);</span>
 191 <span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span> <span class="identifier">algae</span> <span class="identifier">color</span> <span class="special">);</span>
 192 <span class="special">...</span>
 193 <span class="identifier">sample</span> <span class="special">=</span> <span class="identifier">algae</span><span class="special">::</span><span class="identifier">green</span><span class="special">;</span>
 194 <span class="identifier">foo</span><span class="special">(</span> <span class="identifier">algae</span><span class="special">::</span><span class="identifier">cyan</span> <span class="special">);</span>
 195 </pre>
 196 </div>
 197 <div class="section">
 198 <div class="titlepage"><div><div><h3 class="title">
 199 <a name="core.scoped_enum.deprecated_syntax"></a><a class="link" href="scoped_enum.html#core.scoped_enum.deprecated_syntax" title="Deprecated syntax">Deprecated syntax</a>
 200 </h3></div></div></div>
 201 <p>
 202         In early versions of the header there were two ways to declare scoped enums,
 203         with different pros and cons to each. The other way used a different set
 204         of macros:
 205       </p>
 206 <pre class="programlisting"><span class="identifier">BOOST_SCOPED_ENUM_START</span><span class="special">(</span><span class="identifier">algae</span><span class="special">)</span>
 207 <span class="special">{</span>
 208     <span class="identifier">green</span><span class="special">,</span>
 209     <span class="identifier">red</span><span class="special">,</span>
 210     <span class="identifier">cyan</span>
 211 <span class="special">};</span>
 212 <span class="identifier">BOOST_SCOPED_ENUM_END</span>
 213 <span class="special">...</span>
 214 <span class="identifier">BOOST_SCOPED_ENUM</span><span class="special">(</span><span class="identifier">algae</span><span class="special">)</span> <span class="identifier">sample</span><span class="special">(</span> <span class="identifier">algae</span><span class="special">::</span><span class="identifier">red</span> <span class="special">);</span>
 215 <span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span> <span class="identifier">BOOST_SCOPED_ENUM</span><span class="special">(</span><span class="identifier">algae</span><span class="special">)</span> <span class="identifier">color</span> <span class="special">);</span>
 216 <span class="special">...</span>
 217 <span class="identifier">sample</span> <span class="special">=</span> <span class="identifier">algae</span><span class="special">::</span><span class="identifier">green</span><span class="special">;</span>
 218 <span class="identifier">foo</span><span class="special">(</span> <span class="identifier">algae</span><span class="special">::</span><span class="identifier">cyan</span> <span class="special">);</span>
 219 </pre>
 220 <p>
 221         Here <code class="computeroutput"><span class="identifier">BOOST_SCOPED_ENUM_START</span></code>
 222         corresponds to <code class="computeroutput"><span class="identifier">BOOST_SCOPED_ENUM_DECLARE_BEGIN</span></code>,
 223         <code class="computeroutput"><span class="identifier">BOOST_SCOPED_ENUM_END</span></code> to
 224         <code class="computeroutput"><span class="identifier">BOOST_SCOPED_ENUM_DECLARE_END</span></code>
 225         and <code class="computeroutput"><span class="identifier">BOOST_SCOPED_ENUM</span></code> to
 226         <code class="computeroutput"><span class="identifier">BOOST_SCOPED_ENUM_NATIVE</span></code>.
 227         Note also the semicolon before <code class="computeroutput"><span class="identifier">BOOST_SCOPED_ENUM_END</span></code>.
 228       </p>
 229 <p>
 230         In the current version these macros produce equivalent result to the ones
 231         described above and are considered deprecated.
 232       </p>
 233 </div>
 234 <div class="section">
 235 <div class="titlepage"><div><div><h3 class="title">
 236 <a name="core.scoped_enum.acquiring_the_underlying_type_of"></a><a class="link" href="scoped_enum.html#core.scoped_enum.acquiring_the_underlying_type_of" title="Acquiring the underlying type of the enum">Acquiring
 237       the underlying type of the enum</a>
 238 </h3></div></div></div>
 239 <p>
 240         The header <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">core</span><span class="special">/</span><span class="identifier">underlying_type</span><span class="special">.</span><span class="identifier">hpp</span></code> defines
 241         the metafunction <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">underlying_type</span></code> which can be used to obtain
 242         the underlying type of the scoped enum. This metafunction has support for
 243         emulated scoped enums declared with macros in <code class="computeroutput"><span class="identifier">boost</span><span class="special">/</span><span class="identifier">core</span><span class="special">/</span><span class="identifier">scoped_enum</span><span class="special">.</span><span class="identifier">hpp</span></code>. When native scoped enums are supported
 244         by the compiler, this metafunction is equivalent to <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underlying_type</span></code>.
 245       </p>
 246 <p>
 247         Unfortunately, there are configurations which implement scoped enums but
 248         not <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">underlying_type</span></code>. In this case <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">underlying_type</span></code> has to be specialized by
 249         user. The macro <code class="computeroutput"><span class="identifier">BOOST_NO_UNDERLYING_TYPE</span></code>
 250         is defined to indicate such cases.
 251       </p>
 252 </div>
 253 <div class="section">
 254 <div class="titlepage"><div><div><h3 class="title">
 255 <a name="core.scoped_enum.acknowledgments"></a><a class="link" href="scoped_enum.html#core.scoped_enum.acknowledgments" title="Acknowledgments">Acknowledgments</a>
 256 </h3></div></div></div>
 257 <p>
 258         This scoped enum emulation was developed by Beman Dawes, Vicente J. Botet
 259         Escriba and Anthony Williams.
 260       </p>
 261 <p>
 262         Helpful comments and suggestions were also made by Kjell Elster, Phil Endecott,
 263         Joel Falcou, Mathias Gaunard, Felipe Magno de Almeida, Matt Calabrese, Daniel
 264         James and Andrey Semashev.
 265       </p>
 266 </div>
 267 </div>
 268 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 269 <td align="left"></td>
 270 <td align="right"><div class="copyright-footer">Copyright &#169; 2014 Peter Dimov<br>Copyright &#169; 2014 Glen Fernandes<br>Copyright &#169; 2014 Andrey Semashev<p>
 271         Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost
 272         Software License, Version 1.0</a>.
 273       </p>
 274 </div></td>
 275 </tr></table>
 276 <hr>
 277 <div class="spirit-nav">
 278 <a accesskey="p" href="../boost/unwrap_ref.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="swap.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 279 </div>
 280 </body>
 281 </html>