1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Symbols Parser (symbols)</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="Spirit 2.5.8"> 8<link rel="up" href="../string.html" title="String Parsers"> 9<link rel="prev" href="string.html" title="String Parsers (string, lit)"> 10<link rel="next" href="../../s04.html" title="Qi Index"> 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="../../s04.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.qi.reference.string.symbols"></a><a class="link" href="symbols.html" title="Symbols Parser (symbols)">Symbols Parser 28 (<code class="computeroutput"><span class="identifier">symbols</span></code>)</a> 29</h5></div></div></div> 30<h6> 31<a name="spirit.qi.reference.string.symbols.h0"></a> 32 <span class="phrase"><a name="spirit.qi.reference.string.symbols.description"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.description">Description</a> 33 </h6> 34<p> 35 The class <code class="computeroutput"><span class="identifier">symbols</span></code> implements 36 a symbol table: an associative container (or map) of key-value pairs 37 where the keys are strings. The <code class="computeroutput"><span class="identifier">symbols</span></code> 38 class can work efficiently with 8, 16, 32 and even 64 bit characters. 39 </p> 40<p> 41 Traditionally, symbol table management is maintained separately outside 42 the grammar through semantic actions. Contrary to standard practice, 43 the Spirit symbol table class <code class="computeroutput"><span class="identifier">symbols</span></code> 44 is-a parser, an instance of which may be used anywhere in the grammar 45 specification. It is an example of a dynamic parser. A dynamic parser 46 is characterized by its ability to modify its behavior at run time. Initially, 47 an empty symbols object matches nothing. At any time, symbols may be 48 added, thus, dynamically altering its behavior. 49 </p> 50<h6> 51<a name="spirit.qi.reference.string.symbols.h1"></a> 52 <span class="phrase"><a name="spirit.qi.reference.string.symbols.header"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.header">Header</a> 53 </h6> 54<pre class="programlisting"><span class="comment">// forwards to <boost/spirit/home/qi/string/symbols.hpp></span> 55<span class="preprocessor">#include</span> <span class="special"><</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">qi_symbols</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 56</pre> 57<p> 58 Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>. 59 </p> 60<h6> 61<a name="spirit.qi.reference.string.symbols.h2"></a> 62 <span class="phrase"><a name="spirit.qi.reference.string.symbols.namespace"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.namespace">Namespace</a> 63 </h6> 64<div class="informaltable"><table class="table"> 65<colgroup><col></colgroup> 66<thead><tr><th> 67 <p> 68 Name 69 </p> 70 </th></tr></thead> 71<tbody> 72<tr><td> 73 <p> 74 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">::</span><span class="identifier">symbols</span></code> 75 </p> 76 </td></tr> 77<tr><td> 78 <p> 79 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">::</span><span class="identifier">tst</span></code> 80 </p> 81 </td></tr> 82<tr><td> 83 <p> 84 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">qi</span><span class="special">::</span><span class="identifier">tst_map</span></code> 85 </p> 86 </td></tr> 87</tbody> 88</table></div> 89<h6> 90<a name="spirit.qi.reference.string.symbols.h3"></a> 91 <span class="phrase"><a name="spirit.qi.reference.string.symbols.synopsis"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.synopsis">Synopsis</a> 92 </h6> 93<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Char</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><span class="special">></span> 94<span class="keyword">struct</span> <span class="identifier">symbols</span><span class="special">;</span> 95</pre> 96<h6> 97<a name="spirit.qi.reference.string.symbols.h4"></a> 98 <span class="phrase"><a name="spirit.qi.reference.string.symbols.template_parameters"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.template_parameters">Template 99 parameters</a> 100 </h6> 101<div class="informaltable"><table class="table"> 102<colgroup> 103<col> 104<col> 105<col> 106</colgroup> 107<thead><tr> 108<th> 109 <p> 110 Parameter 111 </p> 112 </th> 113<th> 114 <p> 115 Description 116 </p> 117 </th> 118<th> 119 <p> 120 Default 121 </p> 122 </th> 123</tr></thead> 124<tbody> 125<tr> 126<td> 127 <p> 128 <code class="computeroutput"><span class="identifier">Char</span></code> 129 </p> 130 </td> 131<td> 132 <p> 133 The character type of the symbol strings. 134 </p> 135 </td> 136<td> 137 <p> 138 <code class="computeroutput"><span class="keyword">char</span></code> 139 </p> 140 </td> 141</tr> 142<tr> 143<td> 144 <p> 145 <code class="computeroutput"><span class="identifier">T</span></code> 146 </p> 147 </td> 148<td> 149 <p> 150 The data type associated with each symbol. 151 </p> 152 </td> 153<td> 154 <p> 155 <code class="computeroutput"><span class="identifier">unused_type</span></code> 156 </p> 157 </td> 158</tr> 159<tr> 160<td> 161 <p> 162 <code class="computeroutput"><span class="identifier">Lookup</span></code> 163 </p> 164 </td> 165<td> 166 <p> 167 The symbol search implementation 168 </p> 169 </td> 170<td> 171 <p> 172 <code class="computeroutput"><span class="identifier">tst</span><span class="special"><</span><span class="identifier">Char</span><span class="special">,</span> 173 <span class="identifier">T</span><span class="special">></span></code> 174 </p> 175 </td> 176</tr> 177</tbody> 178</table></div> 179<h6> 180<a name="spirit.qi.reference.string.symbols.h5"></a> 181 <span class="phrase"><a name="spirit.qi.reference.string.symbols.model_of"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.model_of">Model 182 of</a> 183 </h6> 184<div class="blockquote"><blockquote class="blockquote"><p> 185 <a class="link" href="../parser_concepts/primitiveparser.html" title="PrimitiveParser"><code class="computeroutput"><span class="identifier">PrimitiveParser</span></code></a> 186 </p></blockquote></div> 187<div class="variablelist"> 188<p class="title"><b>Notation</b></p> 189<dl class="variablelist"> 190<dt><span class="term"><code class="computeroutput"><span class="identifier">Sym</span></code></span></dt> 191<dd><p> 192 A <code class="computeroutput"><span class="identifier">symbols</span></code> type. 193 </p></dd> 194<dt><span class="term"><code class="computeroutput"><span class="identifier">Char</span></code></span></dt> 195<dd><p> 196 A character type. 197 </p></dd> 198<dt><span class="term"><code class="computeroutput"><span class="identifier">T</span></code></span></dt> 199<dd><p> 200 A data type. 201 </p></dd> 202<dt><span class="term"><code class="computeroutput"><span class="identifier">sym</span></code>, <code class="computeroutput"><span class="identifier">sym2</span></code></span></dt> 203<dd><p> 204 <code class="computeroutput"><span class="identifier">symbols</span></code> objects. 205 </p></dd> 206<dt><span class="term"><code class="computeroutput"><span class="identifier">sseq</span></code></span></dt> 207<dd><p> 208 An <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a> 209 container of strings. 210 </p></dd> 211<dt><span class="term"><code class="computeroutput"><span class="identifier">dseq</span></code></span></dt> 212<dd><p> 213 An <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a> 214 container of data with <code class="computeroutput"><span class="identifier">value_type</span></code> 215 <code class="computeroutput"><span class="identifier">T</span></code>. 216 </p></dd> 217<dt><span class="term"><code class="computeroutput"><span class="identifier">s1</span></code>...<code class="computeroutput"><span class="identifier">sN</span></code></span></dt> 218<dd><p> 219 A <a class="link" href="../basics.html#spirit.qi.reference.basics.string">String</a>. 220 </p></dd> 221<dt><span class="term"><code class="computeroutput"><span class="identifier">d1</span></code>...<code class="computeroutput"><span class="identifier">dN</span></code></span></dt> 222<dd><p> 223 Objects of type <code class="computeroutput"><span class="identifier">T</span></code>. 224 </p></dd> 225<dt><span class="term"><code class="computeroutput"><span class="identifier">f</span></code></span></dt> 226<dd><p> 227 A callable function or function object. 228 </p></dd> 229<dt><span class="term"><code class="computeroutput"><span class="identifier">f</span></code>, <code class="computeroutput"><span class="identifier">l</span></code></span></dt> 230<dd><p> 231 <code class="computeroutput"><span class="identifier">ForwardIterator</span></code> 232 first/last pair. 233 </p></dd> 234</dl> 235</div> 236<h6> 237<a name="spirit.qi.reference.string.symbols.h6"></a> 238 <span class="phrase"><a name="spirit.qi.reference.string.symbols.expression_semantics"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.expression_semantics">Expression 239 Semantics</a> 240 </h6> 241<p> 242 Semantics of an expression is defined only where it differs from, or 243 is not defined in <a class="link" href="../parser_concepts/primitiveparser.html" title="PrimitiveParser"><code class="computeroutput"><span class="identifier">PrimitiveParser</span></code></a>. 244 </p> 245<div class="informaltable"><table class="table"> 246<colgroup> 247<col> 248<col> 249</colgroup> 250<thead><tr> 251<th> 252 <p> 253 Expression 254 </p> 255 </th> 256<th> 257 <p> 258 Semantics 259 </p> 260 </th> 261</tr></thead> 262<tbody> 263<tr> 264<td> 265 <p> 266 <code class="computeroutput"><span class="identifier">Sym</span><span class="special">()</span></code> 267 </p> 268 </td> 269<td> 270 <p> 271 Construct an empty symbols names <code class="computeroutput"><span class="string">"symbols"</span></code>. 272 </p> 273 </td> 274</tr> 275<tr> 276<td> 277 <p> 278 <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">name</span><span class="special">)</span></code> 279 </p> 280 </td> 281<td> 282 <p> 283 Construct an empty symbols named <code class="computeroutput"><span class="identifier">name</span></code>. 284 </p> 285 </td> 286</tr> 287<tr> 288<td> 289 <p> 290 <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sym2</span><span class="special">)</span></code> 291 </p> 292 </td> 293<td> 294 <p> 295 Copy construct a symbols from <code class="computeroutput"><span class="identifier">sym2</span></code> 296 (Another <code class="computeroutput"><span class="identifier">symbols</span></code> 297 object). 298 </p> 299 </td> 300</tr> 301<tr> 302<td> 303 <p> 304 <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sseq</span><span class="special">)</span></code> 305 </p> 306 </td> 307<td> 308 <p> 309 Construct symbols from <code class="computeroutput"><span class="identifier">sseq</span></code> 310 (an <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a> 311 container of strings) named <code class="computeroutput"><span class="string">"symbols"</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">sseq</span><span class="special">,</span> 319 <span class="identifier">name</span><span class="special">)</span></code> 320 </p> 321 </td> 322<td> 323 <p> 324 Construct symbols from <code class="computeroutput"><span class="identifier">sseq</span></code> 325 (an <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a> 326 container of strings) named <code class="computeroutput"><span class="identifier">name</span></code>. 327 </p> 328 </td> 329</tr> 330<tr> 331<td> 332 <p> 333 <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sseq</span><span class="special">,</span> 334 <span class="identifier">dseq</span><span class="special">)</span></code> 335 </p> 336 </td> 337<td> 338 <p> 339 Construct symbols from <code class="computeroutput"><span class="identifier">sseq</span></code> 340 and <code class="computeroutput"><span class="identifier">dseq</span></code> (An 341 <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a> 342 container of strings and an <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a> 343 container of data with <code class="computeroutput"><span class="identifier">value_type</span></code> 344 <code class="computeroutput"><span class="identifier">T</span></code>) which is 345 named <code class="computeroutput"><span class="string">"symbols"</span></code>. 346 </p> 347 </td> 348</tr> 349<tr> 350<td> 351 <p> 352 <code class="computeroutput"><span class="identifier">Sym</span><span class="special">(</span><span class="identifier">sseq</span><span class="special">,</span> 353 <span class="identifier">dseq</span><span class="special">,</span> 354 <span class="identifier">name</span><span class="special">)</span></code> 355 </p> 356 </td> 357<td> 358 <p> 359 Construct symbols from <code class="computeroutput"><span class="identifier">sseq</span></code> 360 and <code class="computeroutput"><span class="identifier">dseq</span></code> (An 361 <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a> 362 container of strings and an <a href="https://en.wikipedia.org/wiki/Standard_Template_Library" target="_top">STL</a> 363 container of data with <code class="computeroutput"><span class="identifier">value_type</span></code> 364 <code class="computeroutput"><span class="identifier">T</span></code>) which is 365 named <code class="computeroutput"><span class="identifier">name</span></code>. 366 </p> 367 </td> 368</tr> 369<tr> 370<td> 371 <p> 372 <code class="computeroutput"><span class="identifier">sym</span> <span class="special">=</span> 373 <span class="identifier">sym2</span></code> 374 </p> 375 </td> 376<td> 377 <p> 378 Assign <code class="computeroutput"><span class="identifier">sym2</span></code> 379 to <code class="computeroutput"><span class="identifier">sym</span></code>. 380 </p> 381 </td> 382</tr> 383<tr> 384<td> 385 <p> 386 <code class="computeroutput"><span class="identifier">sym</span> <span class="special">=</span> 387 <span class="identifier">s1</span><span class="special">,</span> 388 <span class="identifier">s2</span><span class="special">,</span> 389 <span class="special">...,</span> <span class="identifier">sN</span></code> 390 </p> 391 </td> 392<td> 393 <p> 394 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>. 395 </p> 396 </td> 397</tr> 398<tr> 399<td> 400 <p> 401 <code class="computeroutput"><span class="identifier">sym</span> <span class="special">+=</span> 402 <span class="identifier">s1</span><span class="special">,</span> 403 <span class="identifier">s2</span><span class="special">,</span> 404 <span class="special">...,</span> <span class="identifier">sN</span></code> 405 </p> 406 </td> 407<td> 408 <p> 409 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>. 410 </p> 411 </td> 412</tr> 413<tr> 414<td> 415 <p> 416 <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> 417 </p> 418 </td> 419<td> 420 <p> 421 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>. 422 </p> 423 </td> 424</tr> 425<tr> 426<td> 427 <p> 428 <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> 429 <span class="identifier">d1</span><span class="special">)(</span><span class="identifier">s2</span><span class="special">,</span> 430 <span class="identifier">d2</span><span class="special">)...(</span><span class="identifier">sN</span><span class="special">,</span> 431 <span class="identifier">dN</span><span class="special">)</span></code> 432 </p> 433 </td> 434<td> 435 <p> 436 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 437 (<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>. 438 </p> 439 </td> 440</tr> 441<tr> 442<td> 443 <p> 444 <code class="computeroutput"><span class="identifier">sym</span> <span class="special">-=</span> 445 <span class="identifier">s1</span><span class="special">,</span> 446 <span class="identifier">s2</span><span class="special">,</span> 447 <span class="special">...,</span> <span class="identifier">sN</span></code> 448 </p> 449 </td> 450<td> 451 <p> 452 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>. 453 </p> 454 </td> 455</tr> 456<tr> 457<td> 458 <p> 459 <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> 460 </p> 461 </td> 462<td> 463 <p> 464 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>. 465 </p> 466 </td> 467</tr> 468<tr> 469<td> 470 <p> 471 <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">clear</span><span class="special">()</span></code> 472 </p> 473 </td> 474<td> 475 <p> 476 Erase all of the symbols in <code class="computeroutput"><span class="identifier">sym</span></code>. 477 </p> 478 </td> 479</tr> 480<tr> 481<td> 482 <p> 483 <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> 484 </p> 485 </td> 486<td> 487 <p> 488 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> 489 does not already contain such an object, <code class="computeroutput"><span class="identifier">at</span></code> 490 inserts the default object <code class="computeroutput"><span class="identifier">T</span><span class="special">()</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">find</span><span class="special">(</span><span class="identifier">s</span><span class="special">)</span></code> 498 </p> 499 </td> 500<td> 501 <p> 502 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> 503 does not already contain such an object, <code class="computeroutput"><span class="identifier">find</span></code> 504 returns a null pointer. 505 </p> 506 </td> 507</tr> 508<tr> 509<td> 510 <p> 511 <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">prefix_find</span><span class="special">(</span><span class="identifier">f</span><span class="special">,</span> 512 <span class="identifier">l</span><span class="special">)</span></code> 513 </p> 514 </td> 515<td> 516 <p> 517 Return a pointer to the object associated with longest symbol 518 that matches the beginning of the range <code class="computeroutput"><span class="special">[</span><span class="identifier">f</span><span class="special">,</span> 519 <span class="identifier">l</span><span class="special">)</span></code>, 520 and updates <code class="computeroutput"><span class="identifier">f</span></code> 521 to point to one past the end of that match. If no symbol matches, 522 then return a null pointer, and <code class="computeroutput"><span class="identifier">f</span></code> 523 is unchanged. 524 </p> 525 </td> 526</tr> 527<tr> 528<td> 529 <p> 530 <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> 531 </p> 532 </td> 533<td> 534 <p> 535 For each symbol in <code class="computeroutput"><span class="identifier">sym</span></code>, 536 <code class="computeroutput"><span class="identifier">s</span></code>, a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">basic_string</span><span class="special"><</span><span class="identifier">Char</span><span class="special">></span></code> 537 with associated data, <code class="computeroutput"><span class="identifier">d</span></code>, 538 an object of type <code class="computeroutput"><span class="identifier">T</span></code>, 539 invoke <code class="computeroutput"><span class="identifier">f</span><span class="special">(</span><span class="identifier">s</span><span class="special">,</span> 540 <span class="identifier">d</span><span class="special">)</span></code> 541 </p> 542 </td> 543</tr> 544<tr> 545<td> 546 <p> 547 <code class="computeroutput"><span class="identifier">sym</span><span class="special">.</span><span class="identifier">name</span><span class="special">()</span></code> 548 </p> 549 </td> 550<td> 551 <p> 552 Retrieve the current name of the symbols object. 553 </p> 554 </td> 555</tr> 556<tr> 557<td> 558 <p> 559 <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> 560 </p> 561 </td> 562<td> 563 <p> 564 Set the current name of the symbols object to be <code class="computeroutput"><span class="identifier">name</span></code>. 565 </p> 566 </td> 567</tr> 568</tbody> 569</table></div> 570<h6> 571<a name="spirit.qi.reference.string.symbols.h7"></a> 572 <span class="phrase"><a name="spirit.qi.reference.string.symbols.attributes"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.attributes">Attributes</a> 573 </h6> 574<p> 575 The attribute of <code class="computeroutput"><span class="identifier">symbol</span><span class="special"><</span><span class="identifier">Char</span><span class="special">,</span> <span class="identifier">T</span><span class="special">></span></code> is <code class="computeroutput"><span class="identifier">T</span></code>. 576 </p> 577<h6> 578<a name="spirit.qi.reference.string.symbols.h8"></a> 579 <span class="phrase"><a name="spirit.qi.reference.string.symbols.complexity"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.complexity">Complexity</a> 580 </h6> 581<p> 582 The default implementation uses a Ternary Search Tree (TST) with complexity: 583 </p> 584<div class="blockquote"><blockquote class="blockquote"><p> 585 O(log n+k) 586 </p></blockquote></div> 587<p> 588 Where k is the length of the string to be searched in a TST with n strings. 589 </p> 590<p> 591 TSTs are faster than hashing for many typical search problems especially 592 when the search interface is iterator based. TSTs are many times faster 593 than hash tables for unsuccessful searches since mismatches are discovered 594 earlier after examining only a few characters. Hash tables always examine 595 an entire key when searching. 596 </p> 597<p> 598 An alternative implementation uses a hybrid hash-map front end (for the 599 first character) plus a TST: <code class="computeroutput"><span class="identifier">tst_map</span></code>. 600 This gives us a complexity of 601 </p> 602<div class="blockquote"><blockquote class="blockquote"><p> 603 O(1 + log n+k-1) 604 </p></blockquote></div> 605<p> 606 This is found to be significantly faster than plain TST, albeit with 607 a bit more memory usage requirements (each slot in the hash-map is a 608 TST node). If you require a lot of symbols to be searched, use the <code class="computeroutput"><span class="identifier">tst_map</span></code> implementation. This can be 609 done by using <code class="computeroutput"><span class="identifier">tst_map</span></code> 610 as the third template parameter to the symbols class: 611 </p> 612<pre class="programlisting"><span class="identifier">symbols</span><span class="special"><</span><span class="identifier">Char</span><span class="special">,</span> <span class="identifier">T</span><span class="special">,</span> <span class="identifier">tst_map</span><span class="special"><</span><span class="identifier">Char</span><span class="special">,</span> <span class="identifier">T</span><span class="special">></span> <span class="special">></span> <span class="identifier">sym</span><span class="special">;</span> 613</pre> 614<h6> 615<a name="spirit.qi.reference.string.symbols.h9"></a> 616 <span class="phrase"><a name="spirit.qi.reference.string.symbols.example"></a></span><a class="link" href="symbols.html#spirit.qi.reference.string.symbols.example">Example</a> 617 </h6> 618<div class="note"><table border="0" summary="Note"> 619<tr> 620<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td> 621<th align="left">Note</th> 622</tr> 623<tr><td align="left" valign="top"><p> 624 The test harness for the example(s) below is presented in the <a class="link" href="../basics.html#spirit.qi.reference.basics.examples">Basics Examples</a> 625 section. 626 </p></td></tr> 627</table></div> 628<p> 629 Some using declarations: 630 </p> 631<p> 632</p> 633<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">qi</span><span class="special">::</span><span class="identifier">symbols</span><span class="special">;</span> 634</pre> 635<p> 636 </p> 637<p> 638 Symbols with data: 639 </p> 640<p> 641</p> 642<pre class="programlisting"><span class="identifier">symbols</span><span class="special"><</span><span class="keyword">char</span><span class="special">,</span> <span class="keyword">int</span><span class="special">></span> <span class="identifier">sym</span><span class="special">;</span> 643 644<span class="identifier">sym</span><span class="special">.</span><span class="identifier">add</span> 645 <span class="special">(</span><span class="string">"Apple"</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> 646 <span class="special">(</span><span class="string">"Banana"</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span> 647 <span class="special">(</span><span class="string">"Orange"</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span> 648<span class="special">;</span> 649 650<span class="keyword">int</span> <span class="identifier">i</span><span class="special">;</span> 651<span class="identifier">test_parser_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="identifier">i</span><span class="special">);</span> 652<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">i</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 653</pre> 654<p> 655 </p> 656<p> 657 When <code class="computeroutput"><span class="identifier">symbols</span></code> is used 658 for case-insensitive parsing (in a <a class="link" href="../directive/no_case.html" title="Parser Directive Inhibiting Case Sensitivity (no_case[])"><code class="computeroutput"><span class="identifier">no_case</span></code></a> directive), added symbol 659 strings should be in lowercase. Symbol strings containing one or more 660 uppercase characters will not match any input when symbols is used in 661 a <code class="computeroutput"><span class="identifier">no_case</span></code> directive. 662 </p> 663<p> 664</p> 665<pre class="programlisting"><span class="identifier">symbols</span><span class="special"><</span><span class="keyword">char</span><span class="special">,</span> <span class="keyword">int</span><span class="special">></span> <span class="identifier">sym</span><span class="special">;</span> 666 667<span class="identifier">sym</span><span class="special">.</span><span class="identifier">add</span> 668 <span class="special">(</span><span class="string">"apple"</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> <span class="comment">// symbol strings are added in lowercase...</span> 669 <span class="special">(</span><span class="string">"banana"</span><span class="special">,</span> <span class="number">2</span><span class="special">)</span> 670 <span class="special">(</span><span class="string">"orange"</span><span class="special">,</span> <span class="number">3</span><span class="special">)</span> 671<span class="special">;</span> 672 673<span class="keyword">int</span> <span class="identifier">i</span><span class="special">;</span> 674<span class="comment">// ...because sym is used for case-insensitive parsing</span> 675<span class="identifier">test_parser_attr</span><span class="special">(</span><span class="string">"Apple"</span><span class="special">,</span> <span class="identifier">no_case</span><span class="special">[</span> <span class="identifier">sym</span> <span class="special">],</span> <span class="identifier">i</span><span class="special">);</span> 676<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">i</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 677<span class="identifier">test_parser_attr</span><span class="special">(</span><span class="string">"ORANGE"</span><span class="special">,</span> <span class="identifier">no_case</span><span class="special">[</span> <span class="identifier">sym</span> <span class="special">],</span> <span class="identifier">i</span><span class="special">);</span> 678<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">i</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 679</pre> 680<p> 681 </p> 682</div> 683<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 684<td align="left"></td> 685<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p> 686 Distributed under the Boost Software License, Version 1.0. (See accompanying 687 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>) 688 </p> 689</div></td> 690</tr></table> 691<hr> 692<div class="spirit-nav"> 693<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="../../s04.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> 694</div> 695</body> 696</html> 697
