libs/spirit/doc/html/spirit/karma/reference/string/symbols.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Symbols Generator (symbols)</title>
   5 <link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="../../../../index.html" title="Spirit 2.5.2">
   8 <link rel="up" href="../string.html" title="String Generators">
   9 <link rel="prev" href="string.html" title="String Generators (string, lit)">
  10 <link rel="next" href="../../performance_measurements.html" title="Performance Measurements">
  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="string.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../string.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="../../performance_measurements.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h5 class="title">
  27 <a name="spirit.karma.reference.string.symbols"></a><a class="link" href="symbols.html" title="Symbols Generator (symbols)">Symbols Generator
  28           (<code class="computeroutput"><span class="identifier">symbols</span></code>)</a>
  29 </h5></div></div></div>
  30 <h6>
  31 <a name="spirit.karma.reference.string.symbols.h0"></a>
  32             <span class="phrase"><a name="spirit.karma.reference.string.symbols.description"></a></span><a class="link" href="symbols.html#spirit.karma.reference.string.symbols.description">Description</a>
  33           </h6>
  34 <p>
  35             The class <code class="computeroutput"><span class="identifier">symbols</span></code> implements
  36             an 'inverse' symbol table: an associative container (or map) of key-value
  37             pairs where the values are (most of the time) strings. It maps the value
  38             to be generated (the key) to any other value which will be emitted instead
  39             of the original key.
  40           </p>
  41 <p>
  42             The Karma symbol table class <code class="computeroutput"><span class="identifier">symbols</span></code>
  43             is-a generator, an instance of which may be used anywhere in the grammar
  44             specification. It is an example of a dynamic generator. A dynamic generator
  45             is characterized by its ability to modify its behavior at run time. Initially,
  46             an empty symbols object will emit nothing. At any time, symbols may be
  47             added, thus, dynamically altering its behavior.
  48           </p>
  49 <h6>
  50 <a name="spirit.karma.reference.string.symbols.h1"></a>
  51             <span class="phrase"><a name="spirit.karma.reference.string.symbols.header"></a></span><a class="link" href="symbols.html#spirit.karma.reference.string.symbols.header">Header</a>
  52           </h6>
  53 <pre class="programlisting"><span class="comment">// forwards to &lt;boost/spirit/home/karma/string/symbols.hpp&gt;</span>
  54 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma_symbols</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  55 </pre>
  56 <p>
  57             Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>.
  58           </p>
  59 <h6>
  60 <a name="spirit.karma.reference.string.symbols.h2"></a>
  61             <span class="phrase"><a name="spirit.karma.reference.string.symbols.namespace"></a></span><a class="link" href="symbols.html#spirit.karma.reference.string.symbols.namespace">Namespace</a>
  62           </h6>
  63 <div class="informaltable"><table class="table">
  64 <colgroup><col></colgroup>
  65 <thead><tr><th>
  66                     <p>
  67                       Name
  68                     </p>
  69                   </th></tr></thead>
  70 <tbody><tr><td>
  71                     <p>
  72                       <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span><span class="special">::</span><span class="identifier">symbols</span></code>
  73                     </p>
  74                   </td></tr></tbody>
  75 </table></div>
  76 <h6>
  77 <a name="spirit.karma.reference.string.symbols.h3"></a>
  78             <span class="phrase"><a name="spirit.karma.reference.string.symbols.synopsis"></a></span><a class="link" href="symbols.html#spirit.karma.reference.string.symbols.synopsis">Synopsis</a>
  79           </h6>
  80 <pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">Attrib</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Lookup</span>
  81   <span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">CharEncoding</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Tag</span><span class="special">&gt;</span>
  82 <span class="keyword">struct</span> <span class="identifier">symbols</span><span class="special">;</span>
  83 </pre>
  84 <h6>
  85 <a name="spirit.karma.reference.string.symbols.h4"></a>
  86             <span class="phrase"><a name="spirit.karma.reference.string.symbols.template_parameters"></a></span><a class="link" href="symbols.html#spirit.karma.reference.string.symbols.template_parameters">Template
  87             parameters</a>
  88           </h6>
  89 <div class="informaltable"><table class="table">
  90 <colgroup>
  91 <col>
  92 <col>
  93 <col>
  94 </colgroup>
  95 <thead><tr>
  96 <th>
  97                     <p>
  98                       Parameter
  99                     </p>
 100                   </th>
 101 <th>
 102                     <p>
 103                       Description
 104                     </p>
 105                   </th>
 106 <th>
 107                     <p>
 108                       Default
 109                     </p>
 110                   </th>
 111 </tr></thead>
 112 <tbody>
 113 <tr>
 114 <td>
 115                     <p>
 116                       <code class="computeroutput"><span class="identifier">Attrib</span></code>
 117                     </p>
 118                   </td>
 119 <td>
 120                     <p>
 121                       The type of the original attribute to be used as the key into
 122                       the symbol generator (the symbol).
 123                     </p>
 124                   </td>
 125 <td>
 126                     <p>
 127                       <code class="computeroutput"><span class="keyword">char</span></code>
 128                     </p>
 129                   </td>
 130 </tr>
 131 <tr>
 132 <td>
 133                     <p>
 134                       <code class="computeroutput"><span class="identifier">T</span></code>
 135                     </p>
 136                   </td>
 137 <td>
 138                     <p>
 139                       The data type associated with each key.
 140                     </p>
 141                   </td>
 142 <td>
 143                     <p>
 144                       <code class="computeroutput"><span class="identifier">unused_type</span></code>
 145                     </p>
 146                   </td>
 147 </tr>
 148 <tr>
 149 <td>
 150                     <p>
 151                       <code class="computeroutput"><span class="identifier">Lookup</span></code>
 152                     </p>
 153                   </td>
 154 <td>
 155                     <p>
 156                       The symbol search implementation
 157                     </p>
 158                   </td>
 159 <td>
 160                     <p>
 161                       if T is <code class="computeroutput"><span class="identifier">unused_type</span></code>,
 162                       <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">set</span><span class="special">&lt;</span><span class="identifier">Attrib</span><span class="special">&gt;</span></code>,
 163                       and <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special">&lt;</span><span class="identifier">Attrib</span><span class="special">,</span>
 164                       <span class="identifier">T</span><span class="special">&gt;</span></code>
 165                       otherwise
 166                     </p>
 167                   </td>
 168 </tr>
 169 <tr>
 170 <td>
 171                     <p>
 172                       <code class="computeroutput"><span class="identifier">CharEncoding</span></code>
 173                     </p>
 174                   </td>
 175 <td>
 176                     <p>
 177                       Used for character set selection, normally not used by end
 178                       user.
 179                     </p>
 180                   </td>
 181 <td>
 182                     <p>
 183                       <code class="computeroutput"><span class="identifier">unused_type</span></code>
 184                     </p>
 185                   </td>
 186 </tr>
 187 <tr>
 188 <td>
 189                     <p>
 190                       <code class="computeroutput"><span class="identifier">Tag</span></code>
 191                     </p>
 192                   </td>
 193 <td>
 194                     <p>
 195                       Used for character set selection, normally not used by end
 196                       user.
 197                     </p>
 198                   </td>
 199 <td>
 200                     <p>
 201                       <code class="computeroutput"><span class="identifier">unused_type</span></code>
 202                     </p>
 203                   </td>
 204 </tr>
 205 </tbody>
 206 </table></div>
 207 <h6>
 208 <a name="spirit.karma.reference.string.symbols.h5"></a>
 209             <span class="phrase"><a name="spirit.karma.reference.string.symbols.model_of"></a></span><a class="link" href="symbols.html#spirit.karma.reference.string.symbols.model_of">Model
 210             of</a>
 211           </h6>
 212 <div class="blockquote"><blockquote class="blockquote"><p>
 213               <a class="link" href="../generator_concepts/primitivegenerator.html" title="PrimitiveGenerator"><code class="computeroutput"><span class="identifier">PrimitiveGenerator</span></code></a>
 214             </p></blockquote></div>
 215 <div class="variablelist">
 216 <p class="title"><b>Notation</b></p>
 217 <dl class="variablelist">
 218 <dt><span class="term"><code class="computeroutput"><span class="identifier">Sym</span></code></span></dt>
 219 <dd><p>
 220                   A <code class="computeroutput"><span class="identifier">symbols</span></code> type.
 221                 </p></dd>
 222 <dt><span class="term"><code class="computeroutput"><span class="identifier">Attrib</span></code></span></dt>
 223 <dd><p>
 224                   An attribute type.
 225                 </p></dd>
 226 <dt><span class="term"><code class="computeroutput"><span class="identifier">T</span></code></span></dt>
 227 <dd><p>
 228                   A data type.
 229                 </p></dd>
 230 <dt><span class="term"><code class="computeroutput"><span class="identifier">sym</span></code>, <code class="computeroutput"><span class="identifier">sym2</span></code></span></dt>
 231 <dd><p>
 232                   <code class="computeroutput"><span class="identifier">symbols</span></code> objects.
 233                 </p></dd>
 234 <dt><span class="term"><code class="computeroutput"><span class="identifier">sseq</span></code></span></dt>
 235 <dd><p>
 236                   An <a href="http://www.sgi.com/tech/stl/" target="_top">STL</a> container
 237                   of strings.
 238                 </p></dd>
 239 <dt><span class="term"><code class="computeroutput"><span class="identifier">dseq</span></code></span></dt>
 240 <dd><p>
 241                   An <a href="http://www.sgi.com/tech/stl/" target="_top">STL</a> container
 242                   of data with <code class="computeroutput"><span class="identifier">value_type</span></code>
 243                   <code class="computeroutput"><span class="identifier">T</span></code>.
 244                 </p></dd>
 245 <dt><span class="term"><code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code></span></dt>
 246 <dd><p>
 247                   A <a class="link" href="../../../qi/reference/basics.html#spirit.qi.reference.basics.string">String</a>.
 248                 </p></dd>
 249 <dt><span class="term"><code class="computeroutput"><span class="identifier">d1</span></code>...<code class="computeroutput"><span class="identifier">dN</span></code></span></dt>
 250 <dd><p>
 251                   Objects of type <code class="computeroutput"><span class="identifier">T</span></code>.
 252                 </p></dd>
 253 <dt><span class="term"><code class="computeroutput"><span class="identifier">f</span></code></span></dt>
 254 <dd><p>
 255                   A callable function or function object.
 256                 </p></dd>
 257 <dt><span class="term"><code class="computeroutput"><span class="identifier">f</span></code>, <code class="computeroutput"><span class="identifier">l</span></code></span></dt>
 258 <dd><p>
 259                   <code class="computeroutput"><span class="identifier">ForwardIterator</span></code>
 260                   first/last pair.
 261                 </p></dd>
 262 </dl>
 263 </div>
 264 <h6>
 265 <a name="spirit.karma.reference.string.symbols.h6"></a>
 266             <span class="phrase"><a name="spirit.karma.reference.string.symbols.expression_semantics"></a></span><a class="link" href="symbols.html#spirit.karma.reference.string.symbols.expression_semantics">Expression
 267             Semantics</a>
 268           </h6>
 269 <p>
 270             Semantics of an expression is defined only where it differs from, or
 271             is not defined in <a class="link" href="../generator_concepts/primitivegenerator.html" title="PrimitiveGenerator"><code class="computeroutput"><span class="identifier">PrimitiveGenerator</span></code></a>.
 272           </p>
 273 <div class="informaltable"><table class="table">
 274 <colgroup>
 275 <col>
 276 <col>
 277 </colgroup>
 278 <thead><tr>
 279 <th>
 280                     <p>
 281                       Expression
 282                     </p>
 283                   </th>
 284 <th>
 285                     <p>
 286                       Semantics
 287                     </p>
 288                   </th>
 289 </tr></thead>
 290 <tbody>
 291 <tr>
 292 <td>
 293                     <p>
 294                       <code class="computeroutput"><span class="identifier">Sym</span><span class="special">()</span></code>
 295                     </p>
 296                   </td>
 297 <td>
 298                     <p>
 299                       Construct an empty symbols object instance named <code class="computeroutput"><span class="string">"symbols"</span></code>.
 300                     </p>
 301                   </td>
 302 </tr>
 303 <tr>
 304 <td>
 305                     <p>
 306                       <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></code>
 307                     </p>
 308                   </td>
 309 <td>
 310                     <p>
 311                       Construct an empty symbols object instance named <code class="computeroutput"><span class="identifier">name</span></code>.
 312                     </p>
 313                   </td>
 314 </tr>
 315 <tr>
 316 <td>
 317                     <p>
 318                       <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sym2</span><span class="special">)</span></code>
 319                     </p>
 320                   </td>
 321 <td>
 322                     <p>
 323                       Copy construct a symbols from <code class="computeroutput"><span class="identifier">sym2</span></code>
 324                       (Another <code class="computeroutput"><span class="identifier">symbols</span></code>
 325                       object).
 326                     </p>
 327                   </td>
 328 </tr>
 329 <tr>
 330 <td>
 331                     <p>
 332                       <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sseq</span><span class="special">)</span></code>
 333                     </p>
 334                   </td>
 335 <td>
 336                     <p>
 337                       Construct symbols from <code class="computeroutput"><span class="identifier">sseq</span></code>
 338                       (An <a href="http://www.sgi.com/tech/stl/" target="_top">STL</a> container
 339                       of symbols of type <code class="computeroutput"><span class="identifier">Attrib</span></code>)
 340                       named <code class="computeroutput"><span class="string">"symbols"</span></code>.
 341                     </p>
 342                   </td>
 343 </tr>
 344 <tr>
 345 <td>
 346                     <p>
 347                       <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sseq</span><span class="special">,</span>
 348                       <span class="identifier">name</span><span class="special">)</span></code>
 349                     </p>
 350                   </td>
 351 <td>
 352                     <p>
 353                       Construct symbols from <code class="computeroutput"><span class="identifier">sseq</span></code>
 354                       (an <a href="http://www.sgi.com/tech/stl/" target="_top">STL</a> container
 355                       of symbols of type <code class="computeroutput"><span class="identifier">Attrib</span></code>)
 356                       named <code class="computeroutput"><span class="identifier">name</span></code>.
 357                     </p>
 358                   </td>
 359 </tr>
 360 <tr>
 361 <td>
 362                     <p>
 363                       <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sseq</span><span class="special">,</span>
 364                       <span class="identifier">dseq</span><span class="special">)</span></code>
 365                     </p>
 366                   </td>
 367 <td>
 368                     <p>
 369                       Construct symbols from <code class="computeroutput"><span class="identifier">sseq</span></code>
 370                       and <code class="computeroutput"><span class="identifier">dseq</span></code> (An
 371                       <a href="http://www.sgi.com/tech/stl/" target="_top">STL</a> container
 372                       of symbols of type <code class="computeroutput"><span class="identifier">Attrib</span></code>
 373                       and an <a href="http://www.sgi.com/tech/stl/" target="_top">STL</a>
 374                       container of data with <code class="computeroutput"><span class="identifier">value_type</span></code>
 375                       <code class="computeroutput"><span class="identifier">T</span></code>) which is
 376                       named <code class="computeroutput"><span class="string">"symbols"</span></code>.
 377                     </p>
 378                   </td>
 379 </tr>
 380 <tr>
 381 <td>
 382                     <p>
 383                       <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sseq</span><span class="special">,</span>
 384                       <span class="identifier">dseq</span><span class="special">,</span>
 385                       <span class="identifier">name</span><span class="special">)</span></code>
 386                     </p>
 387                   </td>
 388 <td>
 389                     <p>
 390                       Construct symbols from <code class="computeroutput"><span class="identifier">sseq</span></code>
 391                       and <code class="computeroutput"><span class="identifier">dseq</span></code> (An
 392                       <a href="http://www.sgi.com/tech/stl/" target="_top">STL</a> container
 393                       of symbols of type <code class="computeroutput"><span class="identifier">Attrib</span></code>
 394                       and an <a href="http://www.sgi.com/tech/stl/" target="_top">STL</a>
 395                       container of data with <code class="computeroutput"><span class="identifier">value_type</span></code>
 396                       <code class="computeroutput"><span class="identifier">T</span></code>) which is
 397                       named <code class="computeroutput"><span class="identifier">name</span></code>.
 398                     </p>
 399                   </td>
 400 </tr>
 401 <tr>
 402 <td>
 403                     <p>
 404                       <code class="computeroutput"><span class="identifier">sym</span> <span class="special">=</span>
 405                       <span class="identifier">sym2</span></code>
 406                     </p>
 407                   </td>
 408 <td>
 409                     <p>
 410                       Assign <code class="computeroutput"><span class="identifier">sym2</span></code>
 411                       to <code class="computeroutput"><span class="identifier">sym</span></code>.
 412                     </p>
 413                   </td>
 414 </tr>
 415 <tr>
 416 <td>
 417                     <p>
 418                       <code class="computeroutput"><span class="identifier">sym</span> <span class="special">=</span>
 419                       <span class="identifier">s1</span><span class="special">,</span>
 420                       <span class="identifier">s2</span><span class="special">,</span>
 421                       <span class="special">...,</span> <span class="identifier">sN</span></code>
 422                     </p>
 423                   </td>
 424 <td>
 425                     <p>
 426                       Assign one or more symbols (<code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code>) to <code class="computeroutput"><span class="identifier">sym</span></code>.
 427                       The associated data values of type <code class="computeroutput"><span class="identifier">T</span></code>
 428                       are default constructed.
 429                     </p>
 430                   </td>
 431 </tr>
 432 <tr>
 433 <td>
 434                     <p>
 435                       <code class="computeroutput"><span class="identifier">sym</span> <span class="special">+=</span>
 436                       <span class="identifier">s1</span><span class="special">,</span>
 437                       <span class="identifier">s2</span><span class="special">,</span>
 438                       <span class="special">...,</span> <span class="identifier">sN</span></code>
 439                     </p>
 440                   </td>
 441 <td>
 442                     <p>
 443                       Add one or more symbols (<code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code>) to <code class="computeroutput"><span class="identifier">sym</span></code>.
 444                       The associated data values of type <code class="computeroutput"><span class="identifier">T</span></code>
 445                       are default constructed.
 446                     </p>
 447                   </td>
 448 </tr>
 449 <tr>
 450 <td>
 451                     <p>
 452                       <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">add</span><span class="special">(</span><span class="identifier">s1</span><span class="special">)(</span><span class="identifier">s2</span><span class="special">)...(</span><span class="identifier">sN</span><span class="special">)</span></code>
 453                     </p>
 454                   </td>
 455 <td>
 456                     <p>
 457                       Add one or more symbols (<code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code>) to <code class="computeroutput"><span class="identifier">sym</span></code>.
 458                       The associated data values of type <code class="computeroutput"><span class="identifier">T</span></code>
 459                       are default constructed.
 460                     </p>
 461                   </td>
 462 </tr>
 463 <tr>
 464 <td>
 465                     <p>
 466                       <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">add</span><span class="special">(</span><span class="identifier">s1</span><span class="special">,</span>
 467                       <span class="identifier">d1</span><span class="special">)(</span><span class="identifier">s2</span><span class="special">,</span>
 468                       <span class="identifier">d2</span><span class="special">)...(</span><span class="identifier">sN</span><span class="special">,</span>
 469                       <span class="identifier">dN</span><span class="special">)</span></code>
 470                     </p>
 471                   </td>
 472 <td>
 473                     <p>
 474                       Add one or more symbols (<code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code>) with associated data
 475                       (<code class="computeroutput"><span class="identifier">d1</span></code>...<code class="computeroutput"><span class="identifier">dN</span></code>) to <code class="computeroutput"><span class="identifier">sym</span></code>.
 476                     </p>
 477                   </td>
 478 </tr>
 479 <tr>
 480 <td>
 481                     <p>
 482                       <code class="computeroutput"><span class="identifier">sym</span> <span class="special">-=</span>
 483                       <span class="identifier">s1</span><span class="special">,</span>
 484                       <span class="identifier">s2</span><span class="special">,</span>
 485                       <span class="special">...,</span> <span class="identifier">sN</span></code>
 486                     </p>
 487                   </td>
 488 <td>
 489                     <p>
 490                       Remove one or more symbols (<code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code>) from <code class="computeroutput"><span class="identifier">sym</span></code>.
 491                     </p>
 492                   </td>
 493 </tr>
 494 <tr>
 495 <td>
 496                     <p>
 497                       <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">remove</span><span class="special">(</span><span class="identifier">s1</span><span class="special">)(</span><span class="identifier">s2</span><span class="special">)...(</span><span class="identifier">sN</span><span class="special">)</span></code>
 498                     </p>
 499                   </td>
 500 <td>
 501                     <p>
 502                       Remove one or more symbols (<code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code>) from <code class="computeroutput"><span class="identifier">sym</span></code>.
 503                     </p>
 504                   </td>
 505 </tr>
 506 <tr>
 507 <td>
 508                     <p>
 509                       <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">clear</span><span class="special">()</span></code>
 510                     </p>
 511                   </td>
 512 <td>
 513                     <p>
 514                       Erase all of the symbols in <code class="computeroutput"><span class="identifier">sym</span></code>.
 515                     </p>
 516                   </td>
 517 </tr>
 518 <tr>
 519 <td>
 520                     <p>
 521                       <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">at</span><span class="special">(</span><span class="identifier">s</span><span class="special">)</span></code>
 522                     </p>
 523                   </td>
 524 <td>
 525                     <p>
 526                       Return a reference to the object associated with symbol, <code class="computeroutput"><span class="identifier">s</span></code>. If <code class="computeroutput"><span class="identifier">sym</span></code>
 527                       does not already contain such an object, <code class="computeroutput"><span class="identifier">at</span></code>
 528                       inserts the default object <code class="computeroutput"><span class="identifier">T</span><span class="special">()</span></code>.
 529                     </p>
 530                   </td>
 531 </tr>
 532 <tr>
 533 <td>
 534                     <p>
 535                       <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="identifier">s</span><span class="special">)</span></code>
 536                     </p>
 537                   </td>
 538 <td>
 539                     <p>
 540                       Return a pointer to the object associated with symbol, <code class="computeroutput"><span class="identifier">s</span></code>. If <code class="computeroutput"><span class="identifier">sym</span></code>
 541                       does not already contain such an object, <code class="computeroutput"><span class="identifier">find</span></code>
 542                       returns a null pointer.
 543                     </p>
 544                   </td>
 545 </tr>
 546 <tr>
 547 <td>
 548                     <p>
 549                       <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">for_each</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span></code>
 550                     </p>
 551                   </td>
 552 <td>
 553                     <p>
 554                       For each symbol in <code class="computeroutput"><span class="identifier">sym</span></code>
 555                       <code class="computeroutput"><span class="identifier">s</span></code> invoke <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="keyword">typename</span> <span class="identifier">Lookup</span><span class="special">::</span><span class="identifier">value_type</span><span class="special">)</span></code>.
 556                     </p>
 557                   </td>
 558 </tr>
 559 <tr>
 560 <td>
 561                     <p>
 562                       <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span></code>
 563                     </p>
 564                   </td>
 565 <td>
 566                     <p>
 567                       Retrieve the current name of the symbols object.
 568                     </p>
 569                   </td>
 570 </tr>
 571 <tr>
 572 <td>
 573                     <p>
 574                       <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">name</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></code>
 575                     </p>
 576                   </td>
 577 <td>
 578                     <p>
 579                       Set the current name of the symbols object to be <code class="computeroutput"><span class="identifier">name</span></code>.
 580                     </p>
 581                   </td>
 582 </tr>
 583 </tbody>
 584 </table></div>
 585 <p>
 586             The symbols generator uses the supplied attribute as the key to be looked
 587             up in the internal associative container. If the key exists the generator
 588             emits the associated value and succeeds (unless the underlying output
 589             stream reports an error). If the value type stored in the symbol generator
 590             is <code class="computeroutput"><span class="identifier">unused_type</span></code> it will
 591             emit the key instead. If the key does not exist the generator fails while
 592             not emitting anything.
 593           </p>
 594 <h6>
 595 <a name="spirit.karma.reference.string.symbols.h7"></a>
 596             <span class="phrase"><a name="spirit.karma.reference.string.symbols.attributes"></a></span><a class="link" href="symbols.html#spirit.karma.reference.string.symbols.attributes">Attributes</a>
 597           </h6>
 598 <p>
 599             The attribute of <code class="computeroutput"><span class="identifier">symbol</span><span class="special">&lt;</span><span class="identifier">Attrib</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;</span></code> is <code class="computeroutput"><span class="identifier">Attrib</span></code>.
 600           </p>
 601 <p>
 602             If the supplied attribute is a <a href="../../../../../../../../libs/fusion/doc/html/index.html" target="_top">Boost.Fusion</a>
 603             sequence, then the symbol table generator will use the first element
 604             of that <a href="../../../../../../../../libs/fusion/doc/html/index.html" target="_top">Boost.Fusion</a>
 605             sequence as the key to be used for lookup. The type of that first element
 606             needs to be convertible to <code class="computeroutput"><span class="identifier">Attrib</span></code>.
 607             In this case the second element of the <a href="../../../../../../../../libs/fusion/doc/html/index.html" target="_top">Boost.Fusion</a>
 608             sequence is used as the attribute while calling a generator derived from
 609             the value stored in the symbol table for the found entry.
 610           </p>
 611 <p>
 612             If the supplied attribute is a container type (<a class="link" href="../../../advanced/customize/is_container.html" title="Determine if a Type Should be Treated as a Container (Qi and Karma)"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">is_container</span></code></a> resolves to <code class="computeroutput"><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">true_</span></code>), then the symbol table generator
 613             will use the first element stored in that container as the key to be
 614             used for lookup. The <code class="computeroutput"><span class="identifier">value_type</span></code>
 615             (returned by <a class="link" href="../../../advanced/customize/store_value/container_value.html" title="Determine the Type to be Stored in a Container (Qi)"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">container_value</span></code></a>) has to be convertible
 616             to <code class="computeroutput"><span class="identifier">Attrib</span></code>. In this case
 617             the second element stored in that container is used as the attribute
 618             while calling a generator derived from the value stored in the symbol
 619             table for the found entry.
 620           </p>
 621 <p>
 622             If the supplied attribute is not a <a href="../../../../../../../../libs/fusion/doc/html/index.html" target="_top">Boost.Fusion</a>
 623             sequence and not a container type, the supplied attribute is directly
 624             used as the key for item lookup. The attribute is used as the attribute
 625             while calling a generator derived from the value stored in the symbol
 626             table for the found entry.
 627           </p>
 628 <p>
 629             In any case, because the supplied key (i.e. either the first element
 630             of the <a href="../../../../../../../../libs/fusion/doc/html/index.html" target="_top">Boost.Fusion</a>
 631             sequence, the first container element, or the attribute otherwise) is
 632             passed as the attribute to a generator derived from the value stored
 633             in the symbol table for the found entry, the symbol table may store generators,
 634             which will produce output based on that value. For instance:
 635           </p>
 636 <pre class="programlisting"><span class="comment">// The symbol table maps a single character key to a rule&lt;&gt;</span>
 637 <span class="comment">// The rule&lt;&gt; exposes an attribute of char as well</span>
 638 <span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">output_iterator_type</span><span class="special">,</span> <span class="keyword">char</span><span class="special">()&gt;</span> <span class="identifier">r1</span> <span class="special">=</span> <span class="identifier">char_</span><span class="special">;</span>
 639
 640 <span class="identifier">symbols</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">,</span> <span class="identifier">rule</span><span class="special">&lt;</span><span class="identifier">output_iterator_type</span><span class="special">,</span> <span class="keyword">char</span><span class="special">()&gt;</span> <span class="special">&gt;</span> <span class="identifier">sym</span><span class="special">;</span>
 641 <span class="identifier">sym</span><span class="special">.</span><span class="identifier">add</span>
 642     <span class="special">(</span><span class="char">'j'</span><span class="special">,</span> <span class="identifier">r1</span><span class="special">.</span><span class="identifier">alias</span><span class="special">())</span>
 643     <span class="special">(</span><span class="char">'h'</span><span class="special">,</span> <span class="identifier">r1</span><span class="special">.</span><span class="identifier">alias</span><span class="special">())</span>
 644     <span class="special">(</span><span class="char">'t'</span><span class="special">,</span> <span class="identifier">r1</span><span class="special">.</span><span class="identifier">alias</span><span class="special">())</span>
 645     <span class="special">(</span><span class="char">'k'</span><span class="special">,</span> <span class="identifier">r1</span><span class="special">.</span><span class="identifier">alias</span><span class="special">())</span>
 646 <span class="special">;</span>
 647
 648 <span class="comment">// Supplying a fusion vector as the attribute will use the first element</span>
 649 <span class="comment">// (the 'j') as the key to be looked up, while the second element (the 'J') </span>
 650 <span class="comment">// is passed on as the attribute to the rule&lt;&gt; stored in the symbol table. </span>
 651 <span class="comment">// Consequently, the example generates a single 'J'.</span>
 652 <span class="identifier">BOOST_ASSERT</span><span class="special">(</span><span class="identifier">test</span><span class="special">(</span><span class="string">"J"</span><span class="special">,</span> <span class="identifier">sym</span><span class="special">,</span> <span class="identifier">make_vector</span><span class="special">(</span><span class="char">'j'</span><span class="special">,</span> <span class="char">'J'</span><span class="special">)));</span>
 653 </pre>
 654 <h6>
 655 <a name="spirit.karma.reference.string.symbols.h8"></a>
 656             <span class="phrase"><a name="spirit.karma.reference.string.symbols.complexity"></a></span><a class="link" href="symbols.html#spirit.karma.reference.string.symbols.complexity">Complexity</a>
 657           </h6>
 658 <p>
 659             The default implementation uses a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">map</span><span class="special">&lt;&gt;</span></code> or a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">set</span><span class="special">&lt;&gt;</span></code> with a complexity of:
 660           </p>
 661 <div class="blockquote"><blockquote class="blockquote"><p>
 662               O(log n)
 663             </p></blockquote></div>
 664 <p>
 665             Where n is the number of stored symbols.
 666           </p>
 667 <h6>
 668 <a name="spirit.karma.reference.string.symbols.h9"></a>
 669             <span class="phrase"><a name="spirit.karma.reference.string.symbols.example"></a></span><a class="link" href="symbols.html#spirit.karma.reference.string.symbols.example">Example</a>
 670           </h6>
 671 <div class="note"><table border="0" summary="Note">
 672 <tr>
 673 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td>
 674 <th align="left">Note</th>
 675 </tr>
 676 <tr><td align="left" valign="top"><p>
 677               The test harness for the example(s) below is presented in the <a class="link" href="../basics.html#spirit.karma.reference.basics.examples">Basics Examples</a>
 678               section.
 679             </p></td></tr>
 680 </table></div>
 681 <p>
 682             Some includes:
 683           </p>
 684 <p>
 685 </p>
 686 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 687 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">support_utree</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 688 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_core</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 689 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">phoenix_operator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 690 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">fusion</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">std_pair</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 691 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
 692 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
 693 </pre>
 694 <p>
 695           </p>
 696 <p>
 697             Some using declarations:
 698           </p>
 699 <p>
 700 </p>
 701 <pre class="programlisting"><span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">karma</span><span class="special">::</span><span class="identifier">symbols</span><span class="special">;</span>
 702 </pre>
 703 <p>
 704           </p>
 705 <p>
 706             Basic usage of <code class="computeroutput"><span class="identifier">symbol</span></code>
 707             generators:
 708           </p>
 709 <p>
 710 </p>
 711 <pre class="programlisting"><span class="identifier">symbols</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">const</span><span class="special">*&gt;</span> <span class="identifier">sym</span><span class="special">;</span>
 712
 713 <span class="identifier">sym</span><span class="special">.</span><span class="identifier">add</span>
 714     <span class="special">(</span><span class="char">'a'</span><span class="special">,</span> <span class="string">"Apple"</span><span class="special">)</span>
 715     <span class="special">(</span><span class="char">'b'</span><span class="special">,</span> <span class="string">"Banana"</span><span class="special">)</span>
 716     <span class="special">(</span><span class="char">'o'</span><span class="special">,</span> <span class="string">"Orange"</span><span class="special">)</span>
 717 <span class="special">;</span>
 718
 719 <span class="identifier">test_generator_attr</span><span class="special">(</span><span class="string">"Banana"</span><span class="special">,</span> <span class="identifier">sym</span><span class="special">,</span> <span class="char">'b'</span><span class="special">);</span>
 720 </pre>
 721 <p>
 722           </p>
 723 </div>
 724 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 725 <td align="left"></td>
 726 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2011 Joel de Guzman, Hartmut Kaiser<p>
 727         Distributed under the Boost Software License, Version 1.0. (See accompanying
 728         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 729       </p>
 730 </div></td>
 731 </tr></table>
 732 <hr>
 733 <div class="spirit-nav">
 734 <a accesskey="p" href="string.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../string.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="../../performance_measurements.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
 735 </div>
 736 </body>
 737 </html>