1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494 |
- <?xml version="1.0" encoding="utf-8" ?>
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html
- lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
- <head>
- <meta http-equiv="content-type" content="application/xhtml+xml; charset=UTF-8" />
- <meta name="generator" content="Docutils 0.3.8: http://docutils.sourceforge.net/" />
- <title>Appendix A - An Introduction to Preprocessor Metaprogramming</title>
- <meta name="copyright" content="From "C++ Template Metaprogramming," by David Abrahams and Aleksey Gurtovoy. Copyright (c) 2005 by Pearson Education, Inc. Reprinted with permission." />
- <style type="text/css">
- /*
- :Author: David Goodger
- :Contact: goodger@users.sourceforge.net
- :date: $Date: 2004/06/23 13:31:26 $
- :version: $Revision: 1.37 $
- :copyright: This stylesheet has been placed in the public domain.
- Default cascading style sheet for the HTML output of Docutils.
- */
- .first {
- margin-top: 0 }
- .last {
- margin-bottom: 0 }
- a.toc-backref {
- text-decoration: none ;
- color: black }
- blockquote.epigraph {
- margin: 2em 5em ; }
- dd {
- margin-bottom: 0.5em }
- /* Uncomment (& remove this text!) to get bold-faced definition list terms
- dt {
- font-weight: bold }
- */
- div.abstract {
- margin: 2em 5em }
- div.abstract p.topic-title {
- font-weight: bold ;
- text-align: center }
- div.attention, div.caution, div.danger, div.error, div.hint,
- div.important, div.note, div.tip, div.warning, div.admonition {
- margin: 2em ;
- border: medium outset ;
- padding: 1em }
- div.attention p.admonition-title, div.caution p.admonition-title,
- div.danger p.admonition-title, div.error p.admonition-title,
- div.warning p.admonition-title {
- color: red ;
- font-weight: bold ;
- font-family: sans-serif }
- div.hint p.admonition-title, div.important p.admonition-title,
- div.note p.admonition-title, div.tip p.admonition-title,
- div.admonition p.admonition-title {
- font-weight: bold ;
- font-family: sans-serif }
- div.dedication {
- margin: 2em 5em ;
- text-align: center ;
- font-style: italic }
- div.dedication p.topic-title {
- font-weight: bold ;
- font-style: normal }
- div.figure {
- margin-left: 2em }
- div.footer, div.header {
- font-size: smaller }
- div.sidebar {
- margin-left: 1em ;
- border: medium outset ;
- padding: 0em 1em ;
- background-color: #ffffee ;
- width: 40% ;
- float: right ;
- clear: right }
- div.sidebar p.rubric {
- font-family: sans-serif ;
- font-size: medium }
- div.system-messages {
- margin: 5em }
- div.system-messages h1 {
- color: red }
- div.system-message {
- border: medium outset ;
- padding: 1em }
- div.system-message p.system-message-title {
- color: red ;
- font-weight: bold }
- div.topic {
- margin: 2em }
- h1.title {
- text-align: center }
- h2.subtitle {
- text-align: center }
- hr {
- width: 75% }
- ol.simple, ul.simple {
- margin-bottom: 1em }
- ol.arabic {
- list-style: decimal }
- ol.loweralpha {
- list-style: lower-alpha }
- ol.upperalpha {
- list-style: upper-alpha }
- ol.lowerroman {
- list-style: lower-roman }
- ol.upperroman {
- list-style: upper-roman }
- p.attribution {
- text-align: right ;
- margin-left: 50% }
- p.caption {
- font-style: italic }
- p.credits {
- font-style: italic ;
- font-size: smaller }
- p.label {
- white-space: nowrap }
- p.rubric {
- font-weight: bold ;
- font-size: larger ;
- color: maroon ;
- text-align: center }
- p.sidebar-title {
- font-family: sans-serif ;
- font-weight: bold ;
- font-size: larger }
- p.sidebar-subtitle {
- font-family: sans-serif ;
- font-weight: bold }
- p.topic-title {
- font-weight: bold }
- pre.address {
- margin-bottom: 0 ;
- margin-top: 0 ;
- font-family: serif ;
- font-size: 100% }
- pre.line-block {
- font-family: serif ;
- font-size: 100% }
- pre.literal-block, pre.doctest-block {
- margin-left: 2em ;
- margin-right: 2em ;
- background-color: #eeeeee }
- span.classifier {
- font-family: sans-serif ;
- font-style: oblique }
- span.classifier-delimiter {
- font-family: sans-serif ;
- font-weight: bold }
- span.interpreted {
- font-family: sans-serif }
- span.option {
- white-space: nowrap }
- span.option-argument {
- font-style: italic }
- span.pre {
- white-space: pre }
- span.problematic {
- color: red }
- table {
- margin-top: 0.5em ;
- margin-bottom: 0.5em }
- table.citation {
- border-left: solid thin gray ;
- padding-left: 0.5ex }
- table.docinfo {
- margin: 2em 4em }
- table.footnote {
- border-left: solid thin black ;
- padding-left: 0.5ex }
- dt {
- font-weight: bold }
- td, th {
- padding-left: 0.5em ;
- padding-right: 0.5em ;
- vertical-align: top }
- th.docinfo-name, th.field-name {
- font-weight: bold ;
- text-align: left ;
- white-space: nowrap }
- h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
- font-size: 100% }
- tt {
- background-color: #eeeeee }
- ul.auto-toc {
- list-style-type: none }
- </style> </head>
- <body><br />
- <div class="document" id="preprocessor-title">
- <h1 class="title">Appendix A - An Introduction to Preprocessor
- Metaprogramming</h1>
- <table class="docinfo" frame="void" rules="none">
- <colgroup><col class="docinfo-name" /> <col class="docinfo-content" />
- </colgroup>
- <tbody valign="top">
- <tr>
- <th class="docinfo-name">Copyright:</th>
- <td>From "C++ Template Metaprogramming," by David Abrahams and
- Aleksey Gurtovoy. Copyright (c) 2005 by Pearson Education, Inc.
- Reprinted with permission.</td>
- </tr>
- <tr class="field">
- <th class="docinfo-name">ISBN:</th>
- <td class="field-body">0321227255</td>
- </tr>
- </tbody>
- </table>
- <div class="section" id="motivation">
- <h1><a name="motivation">A.1 Motivation</a></h1>
- <p>Even with the full power of template metaprogramming and the <a class="reference"
- href="http://www.boost.org/libs/mpl">Boost Metaprogramming library</a>
- at our disposal, some C++ coding jobs still require a great deal of
- boilerplate code repetition. We saw one example in Chapter 5, when we
- implemented <tt class="docutils literal"><span class="pre">tiny_size</span></tt>:</p>
- <pre class="literal-block">template <class T0, class T1, class T2>
- struct tiny_size
- : mpl::int_<3> {};
- </pre>
- <!-- : rst-mode hack -->
- <!-- @prefix.append('struct none {};') -->
- <p>Aside from the repeated pattern in the parameter list of the primary
- template above, there are three partial specializations below, which
- also follow a predictable pattern:</p>
- <pre class="literal-block">template <class T0, class T1>
- struct tiny_size<T0,T1,none>
- : mpl::int_<2> {};
- template <class T0>
- struct tiny_size<T0,none,none>
- : mpl::int_<1> {};
- template <>
- struct tiny_size<none,none,none>
- : mpl::int_<0> {};
- </pre>
- <!-- : rst-mode hack -->
- <!-- @compile('all') -->
- <p>In this case there is only a small amount of code with such a
- "mechanical" flavor, but had we been implementing <tt class="docutils literal"><span
- class="pre">large</span></tt> instead of <tt class="docutils literal"><span
- class="pre">tiny</span></tt>, there might easily have been a great
- deal more. When the number of instances of a pattern grows beyond two
- or three, writing them by hand tends to become error-prone. Perhaps
- more importantly, the code gets hard to read, because the important
- abstraction in the code is really the pattern, not the individual
- instances.</p>
- <div class="section" id="code-generation">
- <h2><a name="code-generation">A.1.1 Code Generation</a></h2>
- <p>Rather than being written out by hand, mechanical-looking code
- should really be generated mechanically. Having written a program to
- spit out instances of the code pattern, a library author has two
- choices: She can either ship pre-generated source code files, or she
- can ship the generator itself. Either approach has drawbacks. If
- clients only get the generated source, they are stuck with whatever
- the library author generated—and experience shows that if they are
- happy with three instances of a pattern today, someone will need
- four tomorrow. If clients get the generator program, on the other
- hand, they also need the resources to execute it (e.g.,
- interpreters), and they must integrate the generator into their
- build processes...</p>
- </div>
- <div class="section" id="enter-the-preprocessor">
- <h2><a name="enter-the-preprocessor">A.1.2 Enter the Preprocessor</a></h2>
- <p>...unless the generator is a preprocessor metaprogram. Though not
- designed for that purpose, the C and C++ preprocessors can be made
- to execute sophisticated programs during the preprocessing phase of
- compilation. Users can control the code generation process with
- preprocessor <tt class="docutils literal"><span class="pre">#define</span></tt>s
- in code or <tt class="docutils literal"><span class="pre">-D</span></tt>
- options on the compiler's command line, making build integration
- trivial. For example, we might parameterize the primary <tt class="docutils literal"><span
- class="pre">tiny_size</span></tt> template above as follows:</p>
- <pre class="literal-block">#include <<strong>boost/preprocessor/repetition/enum_params</strong>.hpp>
- #ifndef TINY_MAX_SIZE
- # define TINY_MAX_SIZE 3 // default maximum size is 3
- #endif
- template <<strong>BOOST_PP_ENUM_PARAMS(TINY_MAX_SIZE, class T)</strong>>
- struct tiny_size
- : mpl::int_<TINY_MAX_SIZE>
- {};
- </pre>
- <!-- : rst-mode hack -->
- <!-- @compile(pop = None) -->
- <p>To test the metaprogram, run your compiler in its "preprocessing"
- mode (usually the <tt class="docutils literal"><span class="pre">-E</span></tt>
- option), with the Boost root directory in your <tt class="docutils literal"><span
- class="pre">#include</span></tt> path. For instance:<a class="footnote-reference"
- href="#minusp" id="id2" name="id2">[1]</a></p>
- <pre class="literal-block">g++ -P -E -Ipath/to/boost_1_32_0 -I. test.cpp
- </pre>
- <!-- @ignore() -->
- <table class="docutils footnote" frame="void" id="minusp" rules="none">
- <colgroup><col class="label" /><col /></colgroup>
- <tbody valign="top">
- <tr>
- <td class="label"><a class="fn-backref" href="#id2" name="minusp">[1]</a></td>
- <td>GCC's <tt class="docutils literal"><span class="pre">-P</span></tt>
- option inhibits the generation of source file and line number
- markers in preprocessed output.</td>
- </tr>
- </tbody>
- </table>
- <p>Given the appropriate metaprograms, users would be able to adjust
- not only the number of parameters to <tt class="docutils literal"><span
- class="pre">tiny_size</span></tt>, but the maximum size of the
- entire <tt class="docutils literal"><span class="pre">tiny</span></tt>
- implementation just by <tt class="docutils literal"><span class="pre">#define</span></tt>-ing
- <tt class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>.</p>
- <p>The Boost Preprocessor library <a class="citation-reference" href="#mk04"
- id="id3" name="id3">[MK04]</a> plays a role in preprocessor
- metaprogramming similar to the one played by the MPL in template
- metaprogramming: It supplies a framework of high-level components
- (like <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM_PARAMS</span></tt>)
- that make otherwise-painful metaprogramming jobs approachable. In
- this appendix we won't attempt to cover nitty-gritty details of how
- the preprocessor works, nor principles of preprocessor
- metaprogramming in general, nor even many details of how the
- Preprocessor <em>library</em> works. We <em>will</em> show you
- enough at a high level that you'll be able to use the library
- productively and learn the rest on your own.</p>
- <table class="docutils citation" frame="void" id="mk04" rules="none">
- <colgroup><col class="label" /><col /></colgroup>
- <tbody valign="top">
- <tr>
- <td class="label"><a class="fn-backref" href="#id3" name="mk04">[MK04]</a></td>
- <td>Paul Mensonides and Vesa Karvonen. "The Boost Preprocessor
- Library." <a class="reference" href="http://www.boost.org/libs/preprocessor">http://www.boost.org/libs/preprocessor</a>.</td>
- </tr>
- </tbody>
- </table>
- </div>
- </div>
- <div class="section" id="fundamental-abstractions-of-the-preprocessor">
- <h1><a name="fundamental-abstractions-of-the-preprocessor">A.2 Fundamental
- Abstractions of the Preprocessor</a></h1>
- <p>We began our discussion of template metaprogramming in Chapter 2 by
- describing its metadata (potential template arguments) and
- metafunctions (class templates). On the basis of those two fundamental
- abstractions, we built up the entire picture of compile-time
- computation covered in the rest of this book. In this section we'll
- lay a similar foundation for the preprocessor metaprogrammer. Some of
- what we cover here may be a review for you, but it's important to
- identify the basic concepts going into detail.</p>
- <div class="section" id="preprocessing-tokens">
- <h2><a name="preprocessing-tokens">A.2.1 Preprocessing Tokens</a></h2>
- <p>The fundamental unit of data in the preprocessor is the <strong>preprocessing
- token</strong>. Preprocessing tokens correspond roughly to the
- tokens you're used to working with in C++, such as identifiers,
- operator symbols, and literals. Technically, there are some
- differences between <em>preprocessing tokens</em> and regular <em>tokens</em>
- (see section 2 of the C++ standard for details), but they can be
- ignored for the purposes of this discussion. In fact, we'll be using
- the terms interchangeably here.</p>
- </div>
- <div class="section" id="macros">
- <h2><a name="macros">A.2.2 Macros</a></h2>
- <p>Preprocessor macros come in two flavors. <strong>Object-like
- macros</strong> can be defined this way:</p>
- <blockquote>
- <div class="line-block">
- <div class="line"><tt class="docutils literal"><span class="pre">#define</span></tt>
- <em>identifier</em> <em>replacement-list</em></div>
- </div>
- </blockquote>
- <!-- @litre_translator.line_offset -= 7 -->
- <p>where the <em>identifier</em> names the macro being defined, and <em>replacement-list</em>
- is a sequence of zero or more tokens. Where the <em>identifier</em>
- appears in subsequent program text, it is <strong>expanded</strong>
- by the preprocessor into its <em>replacement-list</em>.</p>
- <p><strong>Function-like macros</strong>, which act as the
- "metafunctions of the preprocessing phase," are defined as follows:</p>
- <blockquote>
- <div class="line-block">
- <div class="line"><tt class="docutils literal"><span class="pre">#define</span></tt>
- <em>identifier</em>(<em>a</em><sub>1</sub>, <em>a</em><sub>2</sub>,
- ... <em>a</em><sub>n</sub>) <em>replacement-list</em></div>
- </div>
- </blockquote>
- <!-- @litre_translator.line_offset -= 7 -->
- <p>where each <em>a</em><sub>i</sub> is an identifier naming a <strong>macro
- parameter</strong>. When the macro name appears in subsequent
- program text followed by a suitable argument list, it is expanded
- into its <em>replacement-list</em>, except that each argument is
- substituted for the corresponding parameter where it appears in the
- <em>replacement-list</em>.<a class="footnote-reference" href="#expansion"
- id="id4" name="id4">[2]</a></p>
- <table class="docutils footnote" frame="void" id="expansion" rules="none">
- <colgroup><col class="label" /><col /></colgroup>
- <tbody valign="top">
- <tr>
- <td class="label"><a class="fn-backref" href="#id4" name="expansion">[2]</a></td>
- <td>We have omitted many details of how macro expansion works.
- We encourage you to take a few minutes to study section 16.3
- of the C++ standard, which describes that process in
- straightforward terms.</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div class="section" id="macro-arguments">
- <h2><a name="macro-arguments">A.2.3 Macro Arguments</a></h2>
- <div class="admonition-definition admonition">
- <p class="first admonition-title">Definition</p>
- <p>A <strong>macro argument</strong> is a nonempty sequence of:</p>
- <ul class="last simple">
- <li>Preprocessing tokens other than commas or parentheses, <em>and/or</em></li>
- <li>Preprocessing tokens surrounded by matched pairs of
- parentheses.</li>
- </ul>
- </div>
- <p>This definition has consequences for preprocessor metaprogramming
- that must not be underestimated. Note, first of all, that the
- following tokens have special status:</p>
- <blockquote>
- <pre class="literal-block">, ( )
- </pre> </blockquote>
- <!-- @ignore() -->
- <p>As a result, a macro argument can never contain an unmatched
- parenthesis, or a comma that is not surrounded by matched
- parentheses. For example, both lines following the definition of FOO
- below are ill-formed:</p>
- <pre class="literal-block">#define FOO(X) X // Unary identity macro
- FOO(,) // un-parenthesized comma or two empty arguments
- FOO()) // unmatched parenthesis or missing argument
- </pre>
- <!-- @def pp_failure(options = ['-E'], **kw):
- compile( expect_error = not 'mwcc' in config.compiler , options = options, **kw)pp_failure() -->
- <p>Note also that the following tokens do <em>not</em> have special
- status; the preprocessor knows nothing about matched pairs of
- braces, brackets, or angle brackets:</p>
- <blockquote>
- <pre class="literal-block">{ } [ ] < >
- </pre> </blockquote>
- <!-- @ignore() -->
- <p>As a result, these lines are also ill-formed:</p>
- <pre class="literal-block">FOO(std::pair<int<strong>,</strong> long>) // two arguments
- FOO({ int x = 1<strong>,</strong> y = 2; return x+y; }) // two arguments
- </pre>
- <!-- @example.prepend('#define FOO(X) X')
- pp_failure() -->
- <p>It <em>is</em> possible to pass either string of tokens above as
- part of a single macro argument, provided it is parenthesized:</p>
- <pre class="literal-block">FOO(<strong>(</strong>std::pair<int,int><strong>)</strong>) // one argument
- FOO(<strong>(</strong>{ int x = 1, y = 2; return x+y; }<strong>)</strong>) // one argument
- </pre>
- <!-- @example.prepend('#define FOO(X) X')
- compile(options = ['-E']) -->
- <p>However, because of the special status of commas, it is impossible
- to strip parentheses from a macro argument without knowing the
- number of comma-separated token sequences it contains.<a class="footnote-reference"
- href="#c99" id="id5" name="id5">[3]</a> If you are writing a macro
- that needs to be able to accept an argument containing a variable
- number of commas, your users will either have to parenthesize that
- argument <em>and</em> pass you the number of comma-separated token
- sequences as an additional argument, or they will have to encode the
- same information in one of the preprocessor data structures covered
- later in this appendix.</p>
- <table class="docutils footnote" frame="void" id="c99" rules="none">
- <colgroup><col class="label" /><col /></colgroup>
- <tbody valign="top">
- <tr>
- <td class="label"><a name="c99">[3]</a></td>
- <td><em>(<a class="fn-backref" href="#id5">1</a>, <a class="fn-backref"
- href="#id12">2</a>)</em> The C99 preprocessor, by virtue
- of its variadic macros, can do that and more. The C++
- standardization committee is likely to adopt C99's
- preprocessor extensions for the next version of the C++
- standard.</td>
- </tr>
- </tbody>
- </table>
- </div>
- </div>
- <div class="section" id="preprocessor-library-structure">
- <h1><a name="preprocessor-library-structure">A.3 Preprocessor Library
- Structure</a></h1>
- <p>Since in-depth coverage of the Boost Preprocessor library is beyond
- the scope of this book, we'll try to give you the <em>tools</em> to
- gain an in-depth understanding of the library here. To do that, you'll
- need to use the electronic Preprocessor library documentation, which
- begins with the index.html file in the <tt class="docutils literal"><span
- class="pre">libs/preprocessor/</span></tt> subdirectory of your
- Boost installation.</p>
- <p>On the left of your browser window you'll see an index, and if you
- follow the "Headers" link, it will reveal the structure of the <tt class="docutils literal"><span
- class="pre">boost/preprocessor/</span></tt> directory. Most of the
- library's headers are grouped into subdirectories according to related
- functionality. The top-level directory contains only a few headers
- that provide general-purpose macros, along with a header for each
- subdirectory that simply <tt class="docutils literal"><span class="pre">#include</span></tt>s
- all the headers in that subdirectory. For example, <tt class="docutils literal"><span
- class="pre">boost/preprocessor/selection.hpp</span></tt> does
- nothing more than to <tt class="docutils literal"><span class="pre">#include</span></tt>
- the <tt class="docutils literal"><span class="pre">min.hpp</span></tt>
- and <tt class="docutils literal"><span class="pre">max.hpp</span></tt>
- headers that comprise the contents of <tt class="docutils literal"><span
- class="pre">boost/preprocessor/selection/</span></tt>. The headers
- whose names <em>don't</em> correspond to subdirectories generally
- declare a macro whose name is the same as the name of the header,
- without the extension, and with a <tt class="docutils literal"><span
- class="pre">BOOST_PP_</span></tt> prefix. For example, <tt class="docutils literal"><span
- class="pre">boost/preprocessor/selection/max.hpp</span></tt>
- declares <tt class="docutils literal"><span class="pre">BOOST_PP_MAX</span></tt>.</p>
- <p>You'll also notice that often a header will declare an additional
- macro with a <tt class="docutils literal"><span class="pre">_D</span></tt>,
- <tt class="docutils literal"><span class="pre">_R</span></tt>, or <tt
- class="docutils literal"><span class="pre">_Z</span></tt> suffix.<a
- class="footnote-reference" href="#suffix" id="id6" name="id6">[4]</a>
- For instance, <tt class="docutils literal"><span class="pre">boost/preprocessor/selection/max.hpp</span></tt>
- also declares <tt class="docutils literal"><span class="pre">BOOST_PP_MAX_D</span></tt>.
- For the purposes of this appendix, you should ignore those macros.
- Eventually you will want to understand how they can be used to
- optimize preprocessing speed; consult the Topics section of the
- library documentation under the subheading "reentrancy" for that
- information.</p>
- <table class="docutils footnote" frame="void" id="suffix" rules="none">
- <colgroup><col class="label" /><col /></colgroup>
- <tbody valign="top">
- <tr>
- <td class="label"><a class="fn-backref" href="#id6" name="suffix">[4]</a></td>
- <td>Macros with <tt class="docutils literal"><span class="pre">_1ST</span></tt>,
- <tt class="docutils literal"><span class="pre">_2ND</span></tt>,
- or <tt class="docutils literal"><span class="pre">_3RD</span></tt>
- suffixes, if they appear, should be ignored for a different
- reason: They are deprecated and will be removed from the library
- soon.</td>
- </tr>
- </tbody>
- </table>
- </div>
- <div class="section" id="preprocessor-library-abstractions">
- <h1><a name="preprocessor-library-abstractions">A.4 Preprocessor
- Library Abstractions</a></h1>
- <p>In this section we'll discuss the basic abstractions of the
- Preprocessor library, and give some simple examples of each.</p>
- <div class="section" id="repetition">
- <h2><a name="repetition">A.4.1 Repetition</a></h2>
- <p>The repeated generation of <tt class="docutils literal"><span class="pre">class</span>
- <span class="pre">T0</span></tt>, <tt class="docutils literal"><span
- class="pre">class</span> <span class="pre">T1</span></tt>... <tt
- class="docutils literal"><span class="pre">class</span> <span class="pre">T</span></tt><em>n</em>
- that we achieved using <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM_PARAMS</span></tt>
- was a specific case of the general concept of <strong>horizontal
- repetition</strong>. The library also has a concept of vertical
- repetition, which we'll get to in a moment. Horizontal repetition
- macros are all found in the library's <tt class="docutils literal"><span
- class="pre">repetition/</span></tt> subdirectory.</p>
- <div class="section" id="horizontal-repetition">
- <h3><a name="horizontal-repetition">A.4.1.1 Horizontal Repetition</a></h3>
- <p>To generate the <tt class="docutils literal"><span class="pre">tiny_size</span></tt>
- specializations using horizontal repetition, we might write the
- following:</p>
- <pre class="literal-block">#include <boost/preprocessor/repetition.hpp>
- #include <boost/preprocessor/arithmetic/sub.hpp>
- #include <boost/preprocessor/punctuation/comma_if.hpp>
- #define TINY_print(z, n, data) data
- #define TINY_size(z, n, unused) \
- template <BOOST_PP_ENUM_PARAMS(n, class T)> \
- struct tiny_size< \
- BOOST_PP_ENUM_PARAMS(n,T) \
- BOOST_PP_COMMA_IF(n) \
- BOOST_PP_ENUM( \
- BOOST_PP_SUB(TINY_MAX_SIZE,n), TINY_print, none) \
- > \
- : mpl::int_<n> {};
- BOOST_PP_REPEAT(TINY_MAX_SIZE, TINY_size, ~)
- #undef TINY_size
- #undef TINY_print
- </pre>
- <!-- @import re
- compile('all', pop = None)example.sub('BOOST_PP_REPEAT.*', '', flags = re.DOTALL) -->
- <p>The code generation process is kicked off by calling <tt class="docutils literal"><span
- class="pre">BOOST_PP_REPEAT</span></tt>, a <strong>higher-order
- macro</strong> that repeatedly invokes the macro named by its
- second argument (<tt class="docutils literal"><span class="pre">TINY_size</span></tt>).
- The first argument specifies the number of repeated invocations,
- and the third one can be any data; it is passed on unchanged to
- the macro being invoked. In this case, <tt class="docutils literal"><span
- class="pre">TINY_size</span></tt> doesn't use that data, so
- the choice to pass <tt class="docutils literal"><span class="pre">~</span></tt>
- was arbitrary.<a class="footnote-reference" href="#markers" id="id7"
- name="id7">[5]</a></p>
- <table class="docutils footnote" frame="void" id="markers" rules="none">
- <colgroup><col class="label" /><col /></colgroup>
- <tbody valign="top">
- <tr>
- <td class="label"><a class="fn-backref" href="#id7" name="markers">[5]</a></td>
- <td><tt class="docutils literal"><span class="pre">~</span></tt>
- is not an <em>entirely</em> arbitrary choice. Both <tt class="docutils literal"><span
- class="pre">@</span></tt> and <tt class="docutils literal"><span
- class="pre">$</span></tt> might have been good choices,
- except that they are technically not part of the basic
- character set that C++ implementations are required to
- support. An identifier like <tt class="docutils literal"><span
- class="pre">ignored</span></tt> might be subject to
- macro expansion, leading to unexpected results.</td>
- </tr>
- </tbody>
- </table>
- <p>Each time the <tt class="docutils literal"><span class="pre">TINY_size</span></tt>
- macro is invoked by <tt class="docutils literal"><span class="pre">BOOST_PP_REPEAT</span></tt>,
- it generates a different specialization of <tt class="docutils literal"><span
- class="pre">tiny_size</span></tt>. The macro accepts three
- parameters.</p>
- <ul class="simple">
- <li><tt class="docutils literal"><span class="pre">z</span></tt>
- is related to the <tt class="docutils literal"><span class="pre">_Z</span></tt>
- macro suffix we mentioned earlier. You'll never need to use it
- except for optimization purposes, and can safely ignore it for
- now.</li>
- <li><tt class="docutils literal"><span class="pre">n</span></tt>
- is the repetition index. In repeated invocations of <tt class="docutils literal"><span
- class="pre">TINY_size</span></tt>, <tt class="docutils literal"><span
- class="pre">n</span></tt> will be <tt class="docutils literal"><span
- class="pre">0</span></tt>, then <tt class="docutils literal"><span
- class="pre">1</span></tt>, then <tt class="docutils literal"><span
- class="pre">2</span></tt>, and so on.</li>
- <li><tt class="docutils literal"><span class="pre">unused</span></tt>,
- in this case, will be <tt class="docutils literal"><span class="pre">~</span></tt>
- on each repetition. In general, the final argument to a macro
- invoked by <tt class="docutils literal"><span class="pre">BOOST_PP_REPEAT</span></tt>
- is always the same as its invoker's final argument.</li>
- </ul>
- <p>Because its <em>replacement-list</em> covers several lines, all
- but the last line of <tt class="docutils literal"><span class="pre">TINY_size</span></tt>
- is continued with a trailing backslash. The first few of those
- lines just invoke <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM_PARAMS</span></tt>
- (which we already used in the primary template) to generate
- comma-separated lists, so each invocation of <tt class="docutils literal"><span
- class="pre">TINY_size</span></tt> produces something
- equivalent to:<a class="footnote-reference" href="#cont" id="id8"
- name="id8">[6]</a></p>
- <pre class="literal-block">template <<strong>class T0, class T1, ... class T</strong><em>n-1</em>>
- struct tiny_size<
- <strong>T0, T1, ... T</strong><em>n-1</em>
- <em>...more...</em>
- >
- : mpl::int_<n> {};
- </pre>
- <table class="docutils footnote" frame="void" id="cont" rules="none">
- <colgroup><col class="label" /><col /></colgroup>
- <tbody valign="top">
- <tr>
- <td class="label"><a class="fn-backref" href="#id8" name="cont">[6]</a></td>
- <td>Note that the line continuation characters <em>and</em>
- the newlines following them are removed by the preprocessor,
- so the resulting code actually appears on a single line in
- the preprocessed output.</td>
- </tr>
- </tbody>
- </table>
- <!-- @ignore() -->
- <p><tt class="docutils literal"><span class="pre">BOOST_PP_COMMA_IF</span></tt>
- generates a comma if its numeric argument is not <tt class="docutils literal"><span
- class="pre">0</span></tt>. When <tt class="docutils literal"><span
- class="pre">n</span></tt> is <tt class="docutils literal"><span
- class="pre">0</span></tt>, the list generated by the preceding
- line will be empty, and a leading comma directly following the <tt
- class="docutils literal"><span class="pre"><</span></tt>
- character would be ill-formed.</p>
- <p>The next line uses <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM</span></tt>
- to generate <tt class="docutils literal"><span class="pre">TINY_MAX_SIZE-n</span></tt>
- comma-separated copies of <tt class="docutils literal"><span class="pre">none</span></tt>.
- <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM</span></tt>
- is just like <tt class="docutils literal"><span class="pre">BOOST_PP_REPEAT</span></tt>
- except that it generates commas between repetitions, so its second
- argument (<tt class="docutils literal"><span class="pre">TINY_print</span></tt>,
- here) must have the same signature as <tt class="docutils literal"><span
- class="pre">TINY_size</span></tt>. In this case, <tt class="docutils literal"><span
- class="pre">TINY_print</span></tt> ignores its repetition
- index <tt class="docutils literal"><span class="pre">n</span></tt>,
- and simply yields its third argument, <tt class="docutils literal"><span
- class="pre">none</span></tt>.</p>
- <p><tt class="docutils literal"><span class="pre">BOOST_PP_SUB</span></tt>
- implements token subtraction. It's crucial to understand that
- although the preprocessor <em>itself</em> can evaluate ordinary
- arithmetic expressions:</p>
- <pre class="literal-block">#define X 3
- ...
- #if <strong>X - 1 > 0</strong> // OK
- <em>whatever</em>
- #endif
- </pre>
- <!-- @compile() -->
- <!-- @litre_translator.line_offset -= 7 -->
- <p>preprocessor <em>metaprograms</em> can only operate on tokens.
- Normally, when a macro in the Preprocessor library expects a
- numeric argument, it must be passed as a single token. If we had
- written <tt class="docutils literal"><span class="pre">TINY_MAX_SIZE-n</span></tt>
- instead of <tt class="docutils literal"><span class="pre">BOOST_PP_SUB(TINY_MAX_SIZE,n)</span></tt>
- above, the first argument to <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM</span></tt>
- would have contained three tokens at each invocation: first <tt class="docutils literal"><span
- class="pre">3-0</span></tt>, then <tt class="docutils literal"><span
- class="pre">3-1</span></tt>, and finally <tt class="docutils literal"><span
- class="pre">3-2</span></tt>. <tt class="docutils literal"><span
- class="pre">BOOST_PP_SUB</span></tt>, though, generates
- single-token results: first <tt class="docutils literal"><span class="pre">3</span></tt>,
- then <tt class="docutils literal"><span class="pre">2</span></tt>,
- and finally <tt class="docutils literal"><span class="pre">1</span></tt>,
- in successive repetitions.</p>
- <div class="sidebar">
- <p class="first sidebar-title">Naming Conventions</p>
- <p class="last">Note that <tt class="docutils literal"><span class="pre">TINY_print</span></tt>
- and <tt class="docutils literal"><span class="pre">TINY_size</span></tt>
- are <tt class="docutils literal"><span class="pre">#undef</span></tt>'d
- immediately
- after they're used, with no intervening <tt class="docutils literal"><span
- class="pre">#include</span></tt>s. They can therefore be
- thought of as "local" macro definitions. Because the
- preprocessor doesn't respect scope boundaries, it's important to
- choose names carefully to prevent clashes. We recommend <tt class="docutils literal"><span
- class="pre">PREFIXED_lower_case</span></tt> names for local
- macros and <tt class="docutils literal"><span class="pre">PREFIXED_UPPER_CASE</span></tt>
- names for global ones. The only exceptions are one-letter
- lowercase names, which are safe to use for local macros: No
- other header is likely to <tt class="docutils literal"><span class="pre">#define</span></tt>
- a global single-letter lowercase macro—that would be <em>very</em>
- bad manners.</p>
- </div>
- </div>
- <div class="section" id="vertical-repetition">
- <h3><a name="vertical-repetition">A.4.1.2 Vertical Repetition</a></h3>
- <p>If you send the previous example through your preprocessor,
- you'll see one long line containing something like this:</p>
- <pre class="literal-block">template <> struct tiny_size< none , none , none > : mpl::int_<0>
- {}; template < class T0> struct tiny_size< T0 , none , none > :
- mpl::int_<1> {}; template < class T0 , class T1> struct tiny_size
- < T0 , T1 , none > : mpl::int_<2> {};
- </pre>
- <!-- @compile('all', pop = 1) -->
- <p>The distinguishing feature of horizontal repetition is that all
- instances of the repeated pattern are generated on the same line
- of preprocessed output. For some jobs, like generating the primary
- <tt class="docutils literal"><span class="pre">tiny_size</span></tt>
- template, that's perfectly appropriate. In this case, however,
- there are at least two disadvantages.</p>
- <ol class="arabic simple">
- <li>It's hard to verify that our metaprogram is doing the right
- thing without reformatting the resulting code by hand.</li>
- <li>The efficiency of nested horizontal repetitions varies widely
- across preprocessors. Each specialization generated by means of
- horizontal repetition contains three other horizontal
- repetitions: two invocations of <tt class="docutils literal"><span
- class="pre">BOOST_PP_ENUM_PARAMS</span></tt> and one
- invocation of <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM</span></tt>.
- When <tt class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>
- is <tt class="docutils literal"><span class="pre">3</span></tt>,
- you'll probably never care, but on at least one preprocessor
- still in use today, compilation begins to slow noticeably when <tt
- class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>
- reaches <tt class="docutils literal"><span class="pre">8</span></tt>.<a
- class="footnote-reference" href="#nest" id="id9" name="id9">[7]</a></li>
- </ol>
- <blockquote>
- <table class="docutils footnote" frame="void" id="nest" rules="none">
- <colgroup><col class="label" /><col /></colgroup>
- <tbody valign="top">
- <tr>
- <td class="label"><a class="fn-backref" href="#id9" name="nest">[7]</a></td>
- <td>That said, other preprocessors can handle 256 * 256
- nested repetitions without any speed problems whatsoever.</td>
- </tr>
- </tbody>
- </table>
- </blockquote>
- <p>The solution to these problems, naturally, is <strong>vertical
- repetition</strong>, which generates instances of a pattern
- across multiple lines. The Preprocessor library provides two means
- of vertical repetition: <strong>local iteration</strong> and <strong>file
- iteration</strong>.</p>
- <div class="section" id="local-iteration">
- <h4><a name="local-iteration">Local Iteration</a></h4>
- <p>The most expedient way to demonstrate local iteration in our
- example is to replace the invocation of <tt class="docutils literal"><span
- class="pre">BOOST_PP_REPEAT</span></tt> with the following:</p>
- <pre class="literal-block">#include <boost/preprocessor/<strong>iteration/local.hpp</strong>>
- #define BOOST_PP_LOCAL_MACRO(n) TINY_size(~, n, ~)
- #define BOOST_PP_LOCAL_LIMITS (0, <strong>TINY_MAX_SIZE - 1</strong>)
- <strong>#include</strong> BOOST_PP_LOCAL_ITERATE()
- </pre>
- <!-- @compile('all', pop = 1) -->
- <p>Local iteration repeatedly invokes the user-defined macro with
- the special name <tt class="docutils literal"><span class="pre">BOOST_PP_LOCAL_MACRO</span></tt>,
- whose argument will be an iteration index. Since we already had
- <tt class="docutils literal"><span class="pre">TINY_size</span></tt>
- lying around, we've just defined <tt class="docutils literal"><span
- class="pre">BOOST_PP_LOCAL_MACRO</span></tt> to invoke it.
- The range of iteration indices are given by another user-defined
- macro, <tt class="docutils literal"><span class="pre">BOOST_PP_LOCAL_LIMITS</span></tt>,
- which must expand to a parenthesized pair of integer values
- representing the <em>inclusive</em> range of index values
- passed to <tt class="docutils literal"><span class="pre">BOOST_PP_LOCAL_MACRO</span></tt>.
- Note that this is one of the rare places where the library
- expects a numeric argument that can be an expression consisting
- of multiple tokens.</p>
- <p>Finally, the repetition is initiated by <tt class="docutils literal"><span
- class="pre">#include</span></tt>-ing the result of invoking
- <tt class="docutils literal"><span class="pre">BOOST_PP_LOCAL_ITERATE</span></tt>,
- which will ultimately be a file in the Preprocessor library
- itself. You may find it surprising that many preprocessors can
- handle repeated file inclusion more quickly than nested
- horizontal repetition, but that is in fact the case.</p>
- <p>If we throw the new example at our preprocessor, we'll see the
- following, on three separate lines in the output:</p>
- <pre class="literal-block">template <> struct tiny_size< none , none , none > : mpl::int_<0>
- {};
- template < class T0> struct tiny_size< T0 , none , none > : mpl::
- int_<1> {};
- template < class T0 , class T1> struct tiny_size< T0 , T1 , none
- > : mpl::int_<2> {};
- </pre>
- <!-- @compile('all', pop = 1) -->
- <p>That represents a great improvement in verifiability, but it's
- still not ideal. As <tt class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>
- grows, it gets harder and harder to see that the pattern is
- generating what we'd like. If we could get some more line breaks
- into the output it would retain a more recognizable form.</p>
- <p>Both repetition methods we've used so far have another
- drawback, though it doesn't show up in this example. Consider
- what would happen if <tt class="docutils literal"><span class="pre">tiny_size</span></tt>
- had a member function that we wanted to debug. If you've ever
- tried to use a debugger to step through a function generated by
- a preprocessor macro, you know that it's a frustrating
- experience at best: The debugger shows you the line from which
- the macro was ultimately invoked, which usually looks nothing at
- all like the code that was generated. Worse, as far as the
- debugger is concerned, <em>every</em> statement in that
- generated function occupies that same line.</p>
- </div>
- <div class="section" id="file-iteration">
- <h4><a name="file-iteration">File Iteration</a></h4>
- <p>Clearly, debuggability depends on preserving the association
- between generated code and the lines in the source file that
- describe the code pattern. File iteration generates pattern
- instances by repeatedly <tt class="docutils literal"><span class="pre">#include</span></tt>-ing
- the same source file. The effect of file iteration on
- debuggability is similar to that of templates: Although separate
- instances appear to occupy the same source lines in the
- debugger, we do have the experience of stepping through the
- function's source code.</p>
- <p>To apply file iteration in our example, we can replace our
- earlier local iteration code and the definition of <tt class="docutils literal"><span
- class="pre">TINY_size</span></tt>, with:</p>
- <pre class="literal-block">#include <boost/preprocessor/iteration/iterate.hpp>
- #define BOOST_PP_ITERATION_LIMITS (0, TINY_MAX_SIZE - 1)
- #define BOOST_PP_FILENAME_1 "tiny_size_spec.hpp"
- #include BOOST_PP_ITERATE()
- </pre>
- <p><tt class="docutils literal"><span class="pre">BOOST_PP_ITERATION_LIMITS</span></tt>
- follows the same pattern as <tt class="docutils literal"><span
- class="pre">BOOST_PP_LOCAL_LIMITS</span></tt> did, allowing
- us to specify an inclusive range of iteration indices. <tt class="docutils literal"><span
- class="pre">BOOST_PP_FILENAME_1</span></tt> specifies the
- name of the file to repeatedly <tt class="docutils literal"><span
- class="pre">#include</span></tt> (we'll show you that file
- in a moment). The trailing <tt class="docutils literal"><span class="pre">1</span></tt>
- indicates that this is the first nesting level of file
- iteration—should we need to invoke file iteration again from
- within <tt class="docutils literal"><span class="pre">tiny_size_spec.hpp</span></tt>,
- we'd need to use <tt class="docutils literal"><span class="pre">BOOST_PP_FILENAME_2</span></tt>
- instead.</p>
- <p>The contents of <tt class="docutils literal"><span class="pre">tiny_size_spec.hpp</span></tt>
- should look familiar to you; most of it is the same as <tt class="docutils literal"><span
- class="pre">TINY_size</span></tt>'s <em>replacement-list</em>,
- without the backslashes:</p>
- <pre class="literal-block">#define n BOOST_PP_ITERATION()
- template <BOOST_PP_ENUM_PARAMS(n, class T)>
- struct tiny_size<
- BOOST_PP_ENUM_PARAMS(n,T)
- BOOST_PP_COMMA_IF(n)
- BOOST_PP_ENUM(BOOST_PP_SUB(TINY_MAX_SIZE,n), TINY_print, none)
- >
- : mpl::int_<n> {};
- #undef n
- </pre>
- <!-- @import tempfile, os
- open(os.path.join(tempfile.gettempdir(),'tiny_size_spec.hpp'), 'w' ).write(str(example))ignore()vertical_options = ['-I'+tempfile.gettempdir(), '-c']
- compile('all', options = vertical_options, pop = 1) -->
- <p>The Library transmits the iteration index to us in the result
- of <tt class="docutils literal"><span class="pre">BOOST_PP_ITERATION()</span></tt>;
- <tt class="docutils literal"><span class="pre">n</span></tt> is
- nothing more than a convenient local macro used to reduce
- syntactic noise. Note that we didn't use <tt class="docutils literal"><span
- class="pre">#include</span></tt> guards because we need <tt
- class="docutils literal"><span class="pre">tiny_size_spec.hpp</span></tt>
- to be processed multiple times.</p>
- <p>The preprocessed result should now preserve the line structure
- of the pattern and be more verifiable for larger values of <tt
- class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>.
- For instance, when <tt class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>
- is <tt class="docutils literal"><span class="pre">8</span></tt>,
- the following excerpt appears in the output of GCC's
- preprocessing phase:</p>
- <pre class="literal-block"><em>...</em>
- template < class T0 , class T1 , class T2 , class T3>
- struct tiny_size<
- T0 , T1 , T2 , T3
- ,
- none , none , none , none
- >
- : mpl::int_<4> {};
- template < class T0 , class T1 , class T2 , class T3 , class T4>
- struct tiny_size<
- T0 , T1 , T2 , T3 , T4
- ,
- none , none , none
- >
- : mpl::int_<5> {};
- <em>...etc.</em>
- </pre>
- <!-- @compile('all', options = vertical_options + ['-DTINY_MAX_SIZE=8']) -->
- </div>
- <div class="section" id="self-iteration">
- <h4><a name="self-iteration">Self-Iteration</a></h4>
- <p>Creating an entirely new file like <tt class="docutils literal"><span
- class="pre">tiny_size_spec.hpp</span></tt> each time we want
- to express a trivial code pattern for file repetition can be
- inconvenient. Fortunately, the library provides a macro that
- allows us to place the pattern right in the file that invokes
- the iteration. <tt class="docutils literal"><span class="pre">BOOST_PP_IS_ITERATING</span></tt>
- is defined to a nonzero value whenever we're inside an
- iteration. We can use that value to select between the part of a
- file that invokes the iteration and the part that provides the
- repeated pattern. Here's a complete <tt class="docutils literal"><span
- class="pre">tiny_size.hpp</span></tt> file that demonstrates
- self-iteration. Note in particular the placement and use of the
- <tt class="docutils literal"><span class="pre">#include</span></tt>
- guard <tt class="docutils literal"><span class="pre">TINY_SIZE_HPP_INCLUDED</span></tt>:</p>
- <pre class="literal-block">#ifndef <strong>BOOST_PP_IS_ITERATING</strong>
- # ifndef TINY_SIZE_HPP_INCLUDED
- # define TINY_SIZE_HPP_INCLUDED
- # include <boost/preprocessor/repetition.hpp>
- # include <boost/preprocessor/arithmetic/sub.hpp>
- # include <boost/preprocessor/punctuation/comma_if.hpp>
- # include <boost/preprocessor/iteration/iterate.hpp>
- # ifndef TINY_MAX_SIZE
- # define TINY_MAX_SIZE 3 // default maximum size is 3
- # endif
- // primary template
- template <BOOST_PP_ENUM_PARAMS(TINY_MAX_SIZE, class T)>
- struct tiny_size
- : mpl::int_<TINY_MAX_SIZE>
- {};
- // generate specializations
- # define BOOST_PP_ITERATION_LIMITS (0, TINY_MAX_SIZE - 1)
- # define BOOST_PP_FILENAME_1 "tiny_size.hpp" // this file
- # include BOOST_PP_ITERATE()
- # endif // TINY_SIZE_HPP_INCLUDED
- #else // <strong>BOOST_PP_IS_ITERATING</strong>
- # define n BOOST_PP_ITERATION()
- # define TINY_print(z, n, data) data
- // specialization pattern
- template <BOOST_PP_ENUM_PARAMS(n, class T)>
- struct tiny_size<
- BOOST_PP_ENUM_PARAMS(n,T)
- BOOST_PP_COMMA_IF(n)
- BOOST_PP_ENUM(BOOST_PP_SUB(TINY_MAX_SIZE,n), TINY_print, none)
- >
- : mpl::int_<n> {};
- # undef TINY_print
- # undef n
- #endif // <strong>BOOST_PP_IS_ITERATING</strong>
- </pre>
- <!-- @compile(source_file = 'tiny_size.hpp') --> </div>
- <div class="section" id="more">
- <h4><a name="more">More</a></h4>
- <p>There's a good deal more to file iteration than what we've been
- able to show you here. For more details, we encourage you to
- delve into the library's electronic documentation of <tt class="docutils literal"><span
- class="pre">BOOST_PP_ITERATE</span></tt> and friends. Also,
- it's important to note that no single technique for repetition
- is superior to any other: Your choice may depend on convenience,
- verifiability, debuggability, compilation speed, and your own
- sense of "logical coherence."</p>
- </div>
- </div>
- </div>
- <div class="section" id="arithmetic-logical-and-comparison-operations">
- <h2><a name="arithmetic-logical-and-comparison-operations">A.4.2 Arithmetic,
- Logical, and Comparison Operations</a></h2>
- <p>As we mentioned earlier, many of the Preprocessor library
- interfaces require single-token numeric arguments, and when those
- numbers need to be computed arithmetically, straightforward
- arithmetic expressions are inappropriate. We used <tt class="docutils literal"><span
- class="pre">BOOST_PP_SUB</span></tt> to subtract two numeric
- tokens in our <tt class="docutils literal"><span class="pre">tiny_size</span></tt>
- examples. The library contains a suite of operations for
- non-negative integral token arithmetic in its <tt class="docutils literal"><span
- class="pre">arithmetic/</span></tt> subdirectory, as shown in
- Table A.1</p>
- <table border="1" class="docutils">
- <caption>Preprocessor Library Arithmetic Operations</caption> <colgroup>
- <col width="44%" /> <col width="56%" /> </colgroup>
- <thead valign="bottom">
- <tr>
- <th>Expression</th>
- <th>Value of Single Token Result</th>
- </tr>
- </thead>
- <tbody valign="top">
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_ADD(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">+</span> <span class="pre">y</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_DEC(x)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">-</span> <span class="pre">1</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_DIV(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">/</span> <span class="pre">y</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_INC(x)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">+</span> <span class="pre">1</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_MOD(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">%</span> <span class="pre">y</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_MUL(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">*</span> <span class="pre">y</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SUB(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">-</span> <span class="pre">y</span></tt></td>
- </tr>
- </tbody>
- </table>
- <p>The <tt class="docutils literal"><span class="pre">logical/</span></tt>
- subdirectory contains the convenient Boolean token operations shown
- in Table A.2 and the more efficient operations shown in Table A.3,
- which require that their operands are either <tt class="docutils literal"><span
- class="pre">0</span></tt> or <tt class="docutils literal"><span
- class="pre">1</span></tt> (a single bit).</p>
- <table border="1" class="docutils">
- <caption>Preprocessor Library Integer Logical Operations</caption> <colgroup>
- <col width="44%" /> <col width="56%" /> </colgroup>
- <thead valign="bottom">
- <tr>
- <th>Expression</th>
- <th>Value of Single Token Result</th>
- </tr>
- </thead>
- <tbody valign="top">
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_AND(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">&&</span> <span class="pre">y</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_NOR(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">!(x</span> <span
- class="pre">||</span> <span class="pre">y)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_OR(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">||</span> <span class="pre">y</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_XOR(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(bool)x</span>
- <span class="pre">!=</span> <span class="pre">(bool)y</span>
- <span class="pre">?</span> <span class="pre">1</span> <span
- class="pre">:</span> <span class="pre">0</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_NOT(x)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">?</span> <span class="pre">0</span> <span class="pre">:</span>
- <span class="pre">1</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_BOOL(x)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
- <span class="pre">0</span></tt></td>
- </tr>
- </tbody>
- </table>
- <table border="1" class="docutils">
- <caption>Preprocessor Library Bit Logical Operations</caption> <colgroup>
- <col width="44%" /> <col width="56%" /> </colgroup>
- <thead valign="bottom">
- <tr>
- <th>Expression</th>
- <th>Value of Single Token Result</th>
- </tr>
- </thead>
- <tbody valign="top">
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_BITAND(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">&&</span> <span class="pre">y</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_BITNOR(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">!(x</span> <span
- class="pre">||</span> <span class="pre">y)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_BITOR(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">||</span> <span class="pre">y</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_BITXOR(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(bool)x</span>
- <span class="pre">!=</span> <span class="pre">(bool)y</span>
- <span class="pre">?</span> <span class="pre">1</span> <span
- class="pre">:</span> <span class="pre">0</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_COMPL(x)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">?</span> <span class="pre">0</span> <span class="pre">:</span>
- <span class="pre">1</span></tt></td>
- </tr>
- </tbody>
- </table>
- <p>Finally, the <tt class="docutils literal"><span class="pre">comparison/</span></tt>
- subdirectory provides the token integral comparison operations shown
- in Table A.4.</p>
- <table border="1" class="docutils">
- <caption>Preprocessor Library Comparison Operations</caption> <colgroup>
- <col width="46%" /> <col width="54%" /> </colgroup>
- <thead valign="bottom">
- <tr>
- <th>Expression</th>
- <th>Value of Single Token Result</th>
- </tr>
- </thead>
- <tbody valign="top">
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_EQUAL(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">==</span> <span class="pre">y</span> <span
- class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
- <span class="pre">0</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_NOT_EQUAL(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">!=</span> <span class="pre">y</span> <span
- class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
- <span class="pre">0</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_LESS(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre"><</span> <span class="pre">y</span> <span
- class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
- <span class="pre">0</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_LESS_EQUAL(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre"><=</span> <span class="pre">y</span> <span
- class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
- <span class="pre">0</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_GREATER(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">></span> <span class="pre">y</span> <span
- class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
- <span class="pre">0</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_GREATER_EQUAL(x,y)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">x</span> <span
- class="pre">>=</span> <span class="pre">y</span> <span
- class="pre">?</span> <span class="pre">1</span> <span class="pre">:</span>
- <span class="pre">0</span></tt></td>
- </tr>
- </tbody>
- </table>
- <p>Because it's common to have a choice among several workable
- comparison operators, it may be useful to know that <tt class="docutils literal"><span
- class="pre">BOOST_PP_EQUAL</span></tt> and <tt class="docutils literal"><span
- class="pre">BOOST_PP_NOT_EQUAL</span></tt> are likely to be O(1)
- while the other comparison operators are generally slower.</p>
- </div>
- <div class="section" id="control-structures">
- <h2><a name="control-structures">A.4.3 Control Structures</a></h2>
- <p>In its <tt class="docutils literal"><span class="pre">control/</span></tt>
- directory, the Preprocessor Library supplies a macro <tt class="docutils literal"><span
- class="pre">BOOST_PP_IF(c,t,f)</span></tt> that fulfills a
- similar role to the one filled by <tt class="docutils literal"><span
- class="pre">mpl::if_</span></tt>. To explore the "control"
- group, we'll generate code for a framework of generic function
- objects: the Boost Function Library.<a class="footnote-reference" href="#function"
- id="id10" name="id10">[8]</a> <tt class="docutils literal"><span
- class="pre">boost::function</span></tt> is partially specialized
- to match function type arguments of each arity up to the maximum
- supported by the library:</p>
- <pre class="literal-block">template <class Signature> struct function; // primary template
- template <class R> // arity = 0
- struct function<R()>
- <em>definition not shown...</em>
- template <class R, class A0> // arity = 1
- struct function<R(A0)>
- <em>definition not shown...</em>
- template <class R, class A0, class A1> // arity = 2
- struct function<R(A0,A1)>
- <em>definition not shown...</em>
- template <class R, class A0, class A1, class A2> // arity = 3
- struct function<R(A0,A1,A2)>
- <em>definition not shown...</em>
- <em>etc.</em>
- </pre>
- <!-- @example.replace(')>', ')>;')
- compile() -->
- <table class="docutils footnote" frame="void" id="function" rules="none">
- <colgroup><col class="label" /><col /></colgroup>
- <tbody valign="top">
- <tr>
- <td class="label"><a class="fn-backref" href="#id10" name="function">[8]</a></td>
- <td>We touched briefly on the design of Boost Function when we
- discussed type erasure in Chapter 9. See the Function library
- documentation at <tt class="docutils literal"><span class="pre">boost_1_32_0/libs/function/index.html</span></tt>
- on the CD that accompanies this book for more information.</td>
- </tr>
- </tbody>
- </table>
- <p>We've already covered a few strategies that can be used to generate
- the pattern above, so we won't belabor that part of the problem; the
- file iteration approach we used for <tt class="docutils literal"><span
- class="pre">tiny_size</span></tt> would be fine:</p>
- <pre class="literal-block">#ifndef BOOST_PP_IS_ITERATING
- # ifndef BOOST_FUNCTION_HPP_INCLUDED
- # define BOOST_FUNCTION_HPP_INCLUDED
- # include <boost/preprocessor/repetition.hpp>
- # include <boost/preprocessor/iteration/iterate.hpp>
- # ifndef FUNCTION_MAX_ARITY
- # define FUNCTION_MAX_ARITY 15
- # endif
- <strong>template <class Signature> struct function;</strong> // primary template
- // generate specializations
- # define BOOST_PP_ITERATION_LIMITS (0, FUNCTION_MAX_ARITY)
- # define BOOST_PP_FILENAME_1 "boost/function.hpp" // this file
- # include BOOST_PP_ITERATE()
- # endif // BOOST_FUNCTION_HPP_INCLUDED
- #else // BOOST_PP_IS_ITERATING
- # define n BOOST_PP_ITERATION()
- // specialization pattern
- <strong>template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)></strong>
- <strong>struct function<R ( BOOST_PP_ENUM_PARAMS(n,A) )></strong>
- <em>definition not shown...</em>
- # undef n
- #endif // BOOST_PP_IS_ITERATING
- </pre>
- <p><tt class="docutils literal"><span class="pre">BOOST_PP_ENUM_TRAILING_PARAMS</span></tt>,
- used above, is just like <tt class="docutils literal"><span class="pre">BOOST_PP_ENUM_PARAMS</span></tt>
- except that when its first argument is not <tt class="docutils literal"><span
- class="pre">0</span></tt>, it generates a leading comma.</p>
- <!-- @example.replace_emphasis(';//')
- tmpdir = tempfile.gettempdir()tmpboost = os.path.join(tmpdir,'boost')try: os.mkdir(tmpboost)except: pass
- tmp_boost_function = os.path.join(tmpdir, 'boost/function.hpp')compile( options = vertical_options , source_file = tmp_boost_function
- , pop = None) -->
- <div class="section" id="argument-selection">
- <h3><a name="argument-selection">A.4.3.1 Argument Selection</a></h3>
- <p>For the sake of interoperability with C++ standard library
- algorithms, it might be nice if <tt class="docutils literal"><span
- class="pre">function</span></tt>s of one or two arguments were
- derived from appropriate specializations of <tt class="docutils literal"><span
- class="pre">std::unary_function</span></tt> or <tt class="docutils literal"><span
- class="pre">std::binary_function</span></tt>, respectively.<a
- class="footnote-reference" href="#ebo" id="id11" name="id11">[9]</a>
- <tt class="docutils literal"><span class="pre">BOOST_PP_IF</span></tt>
- is a great tool for dealing with special cases:</p>
- <pre class="literal-block"># include <boost/preprocessor/control/if.hpp>
- # include <boost/preprocessor/comparison/equal.hpp>
- // specialization pattern
- template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)>
- struct function<R ( BOOST_PP_ENUM_PARAMS(n,A) )>
- BOOST_PP_IF(
- BOOST_PP_EQUAL(n,2), <strong>: std::binary_function<A0, A1, R></strong>
- , BOOST_PP_IF(
- BOOST_PP_EQUAL(n,1), <strong>: std::unary_function<A0, R></strong>
- , <em>...empty argument...</em>
- )
- )
- { <em>...class body omitted...</em> };
- </pre>
- <!-- @pp_failure() -->
- <table class="docutils footnote" frame="void" id="ebo" rules="none">
- <colgroup><col class="label" /><col /></colgroup>
- <tbody valign="top">
- <tr>
- <td class="label"><a class="fn-backref" href="#id11" name="ebo">[9]</a></td>
- <td>While derivation from <tt class="docutils literal"><span
- class="pre">std::unary_function</span></tt> or <tt class="docutils literal"><span
- class="pre">std::binary_function</span></tt> might be
- necessary for interoperability with some older library
- implementations, it may inhibit the Empty Base Optimization
- (EBO) from taking effect when two such derived classes are
- part of the same object. For more information, see section
- 9.4. In general, it's better to expose <tt class="docutils literal"><span
- class="pre">first_argument_type</span></tt>, <tt class="docutils literal"><span
- class="pre">second_argument_type</span></tt>, and <tt class="docutils literal"><span
- class="pre">result_type</span></tt> <tt class="docutils literal"><span
- class="pre">typedef</span></tt>s directly.</td>
- </tr>
- </tbody>
- </table>
- <p>Well, our first attempt has run into several problems. First off,
- you're not allowed to pass an empty argument to the preprocessor.<a
- class="footnote-reference" href="#c99" id="id12" name="id12">[3]</a>
- Secondly, because angle brackets don't get special treatment, the
- commas in the <tt class="docutils literal"><span class="pre">std::unary_function</span></tt>
- and <tt class="docutils literal"><span class="pre">std::binary_function</span></tt>
- specializations above are treated as macro argument separators,
- and the preprocessor will complain that we've passed the wrong
- number of arguments to <tt class="docutils literal"><span class="pre">BOOST_PP_IF</span></tt>
- in two places.</p>
- <p>Because it captures all of the issues, let's focus on the inner <tt
- class="docutils literal"><span class="pre">BOOST_PP_IF</span></tt>
- invocation for a moment. The strategy that <tt class="docutils literal"><span
- class="pre">mpl::eval_if</span></tt> uses, of selecting a
- nullary function to invoke, could work nicely here. The
- preprocessor doesn't have a direct analogue for <tt class="docutils literal"><span
- class="pre">mpl::eval_if</span></tt>, but it doesn't really
- need one: We can get the right effect by adding a second set of
- parentheses to <tt class="docutils literal"><span class="pre">BOOST_PP_IF</span></tt>.</p>
- <pre class="literal-block">#define BOOST_FUNCTION_unary() : std::unary_function<A0,R>
- #define BOOST_FUNCTION_empty() // nothing
- ...
- , BOOST_PP_IF(
- BOOST_PP_EQUAL(n,1), BOOST_FUNCTION_unary
- , BOOST_FUNCTION_empty
- )<strong>()</strong>
- #undef BOOST_FUNCTION_empty
- #undef BOOST_FUNCTION_unary
- </pre>
- <!-- @ignore() -->
- <p>A nullary macro that generates nothing is so commonly needed that
- the library's "facilities" group provides one: <tt class="docutils literal"><span
- class="pre">BOOST_PP_EMPTY</span></tt>. To complete the
- example we'll need to delay evaluation all the way to the outer <tt
- class="docutils literal"><span class="pre">BOOST_PP_IF</span></tt>
- invocation, because <tt class="docutils literal"><span class="pre">std::binary_function<A0,A1,R></span></tt>
- also has a "comma problem":</p>
- <pre class="literal-block"># include <boost/preprocessor/<strong>facilities/empty.hpp</strong>>
- # define BOOST_FUNCTION_binary() : std::binary_function<A0,A1,R>
- # define BOOST_FUNCTION_unary() : std::unary_function<A0,R>
- // specialization pattern
- template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)>
- struct function<R ( BOOST_PP_ENUM_PARAMS(n,A) )>
- BOOST_PP_IF(
- BOOST_PP_EQUAL(n,2), BOOST_FUNCTION_binary
- , BOOST_PP_IF(
- BOOST_PP_EQUAL(n,1), BOOST_FUNCTION_unary
- , <strong>BOOST_PP_EMPTY</strong>
- )
- )<strong>()</strong>
- {
- <em>...class body omitted...</em>
- };
- # undef BOOST_FUNCTION_unary
- # undef BOOST_FUNCTION_binary
- # undef n
- </pre>
- <!-- @stack.pop()
- stack[-1].replace('// specialization pattern', '////\n%s\n////' % str(example))compile(source_file = tmp_boost_function, pop = None) -->
- <p>Note that because we happened to be using file iteration, we
- could have also used <tt class="docutils literal"><span class="pre">#if</span></tt>
- on <tt class="docutils literal"><span class="pre">n</span></tt>'s
- value directly:</p>
- <pre class="literal-block"> template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)>
- struct function<R ( BOOST_PP_ENUM_PARAMS(n,A) )>
- <strong>#if n == 2</strong>
- : std::binary_function<A0, A1, R>
- <strong>#elif n == 1</strong>
- : std::unary_function<A0, R>
- <strong>#endif</strong>
- </pre>
- <!-- @stack.pop()
- stack[-1].sub( r'////.*////', '////\n%s\n////' % str(example), flags = re.DOTALL)compile(source_file = tmp_boost_function, pop = None) -->
- <p><tt class="docutils literal"><span class="pre">BOOST_PP_IF</span></tt>
- has the advantage of enabling us to encapsulate the logic in a
- reusable macro, parameterized on <tt class="docutils literal"><span
- class="pre">n</span></tt>, that is compatible with all
- repetition constructs:</p>
- <pre class="literal-block">#define BOOST_FUNCTION_BASE(n) \
- BOOST_PP_IF(BOOST_PP_EQUAL(n,2), BOOST_FUNCTION_binary \
- , BOOST_PP_IF(BOOST_PP_EQUAL(n,1), BOOST_FUNCTION_unary \
- , BOOST_PP_EMPTY \
- ) \
- )()
- </pre>
- <!-- @compile(options = ['-E']) --> </div>
- <div class="section" id="other-selection-constructs">
- <h3><a name="other-selection-constructs">A.4.3.2 Other Selection
- Constructs</a></h3>
- <p><tt class="docutils literal"><span class="pre">BOOST_PP_IDENTITY</span></tt>,
- also in the "facilities" group, is an interesting cousin of <tt class="docutils literal"><span
- class="pre">BOOST_PP_EMPTY</span></tt>:</p>
- <pre class="literal-block">#define BOOST_PP_IDENTITY(tokens) tokens BOOST_PP_EMPTY
- </pre>
- <!-- @ignore() -->
- <p>You can think of it as creating a nullary macro that returns <tt
- class="docutils literal"><span class="pre">tokens</span></tt>:
- When empty parentheses are appended, the trailing <tt class="docutils literal"><span
- class="pre">BOOST_PP_EMPTY</span></tt> is expanded leaving
- just <tt class="docutils literal"><span class="pre">tokens</span></tt>
- behind. If we had wanted inheritance from <tt class="docutils literal"><span
- class="pre">mpl::empty_base</span></tt> when <tt class="docutils literal"><span
- class="pre">function</span></tt>'s arity is not one or two, we
- could have used <tt class="docutils literal"><span class="pre">BOOST_PP_IDENTITY</span></tt>:</p>
- <pre class="literal-block">// specialization pattern
- template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)>
- struct function<R ( BOOST_PP_ENUM_PARAMS(n,A) )>
- BOOST_PP_IF(
- BOOST_PP_EQUAL(n,2), BOOST_FUNCTION_binary
- , BOOST_PP_IF(
- BOOST_PP_EQUAL(n,1), BOOST_FUNCTION_unary
- , <strong>BOOST_PP_IDENTITY(: mpl::empty_base)</strong>
- )
- )<strong>()</strong>
- {
- <em>...class body omitted...</em>
- };
- </pre>
- <!-- @stack.pop()
- stack[-1].sub( r'////.*////', '////\n%s\n////' % str(example), flags = re.DOTALL)compile(source_file = tmp_boost_function, pop = None) -->
- <p>It's also worth knowing about <tt class="docutils literal"><span
- class="pre">BOOST_PP_EXPR_IF</span></tt>, which generates its
- second argument or nothing, depending on the Boolean value of its
- first:</p>
- <pre class="literal-block">#define BOOST_PP_EXPR_IF(c,tokens) \
- BOOST_PP_IF(c,BOOST_PP_IDENTITY(tokens),BOOST_PP_EMPTY)()
- </pre>
- <!-- @example.append(
- 'int BOOST_PP_EXPR_IF(1,main) BOOST_PP_EXPR_IF(0,quack) () {}')compile() -->
- <p>So <tt class="docutils literal"><span class="pre">BOOST_PP_EXPR_IF(1,foo)</span></tt>
- expands to <tt class="docutils literal"><span class="pre">foo</span></tt>,
- while <tt class="docutils literal"><span class="pre">BOOST_PP_EXPR_IF(0,foo)</span></tt>
- expands to nothing.</p>
- </div>
- </div>
- <div class="section" id="token-pasting">
- <h2><a name="token-pasting">A.4.4 Token Pasting</a></h2>
- <p>It would be nice if there were a generic way to access the return
- and parameter types of <em>all</em> function objects, rather than
- just the unary and binary ones. A metafunction returning the
- signature as an MPL sequence would do the trick. We could just
- specialize <tt class="docutils literal"><span class="pre">signature</span></tt>
- for each <tt class="docutils literal"><span class="pre">function</span></tt>
- arity:</p>
- <pre class="literal-block">template <class F> struct signature; // primary template
- // partial specializations for boost::function
- template <class R>
- struct signature<function<R()> >
- : mpl::vector1<R> {};
- template <class R, class A0>
- struct signature<function<R(A0)> >
- : mpl::vector2<R,A0> {};
- template <class R, class A0, class A1>
- struct signature<function<R(A0,A1)> >
- : mpl::vector3<R,A0,A1> {};
- ...
- </pre>
- <!-- @example.prepend('template <class T> struct function;')
- compile() -->
- <p>To generate these specializations, we might add the following to
- our pattern:</p>
- <pre class="literal-block">template <class R BOOST_PP_ENUM_TRAILING_PARAMS(n, class A)>
- struct signature<function<R( BOOST_PP_ENUM_PARAMS(n,A) )> >
- : mpl::<strong>BOOST_PP_CAT</strong>(vector,n)<
- R BOOST_PP_ENUM_TRAILING_PARAMS(n,A)
- > {};
- </pre>
- <!-- @stack.pop()
- stack[-1].replace( ';//', ''';// template <class T> struct signature; %s''' % example)
- compile(source_file = tmp_boost_function) -->
- <p><tt class="docutils literal"><span class="pre">BOOST_PP_CAT</span></tt>
- implements <strong>token pasting</strong>; its two arguments are
- "glued" together into a single token. Since this is a
- general-purpose macro, it sits in <tt class="docutils literal"><span
- class="pre">cat.hpp</span></tt> at the top level of the
- library's directory tree.</p>
- <p>Although the preprocessor has a built-in token-pasting operator, <tt
- class="docutils literal"><span class="pre">##</span></tt>, it only
- works within a macro definition. If we'd used it here, it wouldn't
- have taken effect at all:</p>
- <pre class="literal-block">template <class R>
- struct signature<function<R()> >
- : mpl::<strong>vector##1</strong><R> {};
- template <class R, class A0>
- struct signature<function<R(A0)> >
- : mpl::<strong>vector##2</strong><R,A0> {};
- template <class R, class A0, class A1>
- struct signature<function<R(A0,A1)> >
- : mpl::<strong>vector##3</strong><R,A0,A1> {};
- ...
- </pre>
- <!-- @example.replace('##','')
- example.prepend(''' template <class T> struct function; template <class T> struct signature;''')
- compile() -->
- <p>Also, <tt class="docutils literal"><span class="pre">##</span></tt>
- often yields surprising results by taking effect before its
- arguments have been expanded:</p>
- <pre class="literal-block">#define N 10
- #define VEC(i) vector##i
- VEC(N) // vectorN
- </pre>
- <!-- @example.wrap('typedef int vectorN;', 'x;')
- compile() -->
- <p>By contrast, <tt class="docutils literal"><span class="pre">BOOST_PP_CAT</span></tt>
- delays concatenation until after its arguments have been fully
- evaluated:</p>
- <pre class="literal-block">#define N 10
- #define VEC(i) BOOST_PP_CAT(vector,i)
- VEC(N) // vector10
- </pre>
- <!-- @example.wrap('''
- #include <boost/preprocessor/cat.hpp> typedef int vector10; ''', 'x;')compile() -->
- </div>
- <div class="section" id="data-types">
- <h2><a name="data-types">A.4.5 Data Types</a></h2>
- <p>The Preprocessor library also provides <strong>data types</strong>,
- which you can think of as being analogous to the MPL's type
- sequences. Preprocessor data types store <em>macro arguments</em>
- instead of C++ types.</p>
- <div class="section" id="sequences">
- <h3><a name="sequences">A.4.5.1 Sequences</a></h3>
- <p>A <strong>sequence</strong> (or <strong>seq</strong> for short)
- is any string of nonempty parenthesized <em>macro arguments</em>.
- For instance, here's a three-element sequence:</p>
- <pre class="literal-block">#define MY_SEQ (f(12))(a + 1)(foo)
- </pre>
- <!-- @ignore() -->
- <p>Here's how we might use a sequence to generate specializations of
- the <tt class="docutils literal"><span class="pre">is_integral</span></tt>
- template from the Boost Type Traits library (see Chapter 2):</p>
- <pre class="literal-block">#include <boost/preprocessor/seq.hpp>
- template <class T>
- struct is_integral : mpl::false_ {};
- // a seq of integral types with unsigned counterparts
- #define BOOST_TT_basic_ints (char)(short)(int)(long)
- // generate a seq containing "signed t" and "unsigned t"
- #define BOOST_TT_int_pair(r,data,t) (signed t)(unsigned t)
- // a seq of all the integral types
- #define BOOST_TT_ints \
- (bool)(char) \
- BOOST_PP_SEQ_FOR_EACH(BOOST_TT_int_pair, ~, BOOST_TT_basic_ints)
- // generate an is_integral specialization for type t
- #define BOOST_TT_is_integral_spec(r,data,t) \
- template <> \
- struct is_integral<t> : mpl::true_ {};
- BOOST_PP_SEQ_FOR_EACH(BOOST_TT_is_integral_spec, ~, BOOST_TT_ints)
- #undef BOOST_TT_is_integral_spec
- #undef BOOST_TT_ints
- #undef BOOST_TT_int_pair
- #undef BOOST_TT_basic_ints
- </pre>
- <!-- @compile() -->
- <p><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FOR_EACH</span></tt>
- is a higher-order macro, similar to <tt class="docutils literal"><span
- class="pre">BOOST_PP_REPEAT</span></tt>, that invokes its
- first argument on each element of its third argument.</p>
- <p>Sequences are the most efficient, most flexible, and
- easiest-to-use of the library's data structures, provided that you
- never need to make an empty one: An empty sequence would contain
- no tokens, and so couldn't be passed as a macro argument. The
- other data structures covered here all have an empty
- representation.</p>
- <p>The facilities for manipulating sequences are all in the
- library's <tt class="docutils literal"><span class="pre">seq/</span></tt>
- subdirectory. They are summarized in Table A.5, where <tt class="docutils literal"><span
- class="pre">t</span></tt> is the sequence <tt class="docutils literal"><span
- class="pre">(</span></tt><em>t</em><sub>0</sub><tt class="docutils literal"><span
- class="pre">)(</span></tt><em>t</em><sub>1</sub><tt class="docutils literal"><span
- class="pre">)...(</span></tt><em>t</em><sub>k</sub><tt class="docutils literal"><span
- class="pre">)</span></tt>. Where <em>s</em>, <em>r</em>, and
- <em>d</em> appear, they have a similar purpose to the <tt class="docutils literal"><span
- class="pre">z</span></tt> parameters we discussed earlier (and
- suggested you ignore for now).</p>
- <table border="1" class="docutils">
- <caption>Preprocessor Sequence Operations</caption> <colgroup> <col
- width="51%" /> <col width="49%" /> </colgroup>
- <thead valign="bottom">
- <tr>
- <th>Expression</th>
- <th>Result</th>
- </tr>
- </thead>
- <tbody valign="top">
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_CAT(t)</span></tt></td>
- <td><em>t</em><sub>0</sub><em>t</em><sub>1</sub>...<em>t</em><sub>k</sub></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_ELEM(n,t)</span></tt></td>
- <td><em>t</em><sub>n</sub></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_ENUM(t)</span></tt></td>
- <td><em>t</em><sub>0</sub>, <em>t</em><sub>1</sub>, ...<em>t</em><sub>k</sub></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FILTER(pred,data,t)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">t</span></tt>
- without the elements that don't satisfy <tt class="docutils literal"><span
- class="pre">pred</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FIRST_N(n,t)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>n-1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FOLD_LEFT(op,</span>
- <span class="pre">x,</span> <span class="pre">t)</span></tt></td>
- <td>...<tt class="docutils literal"><span class="pre">op(</span></tt><em>s</em><tt
- class="docutils literal"><span class="pre">,op(</span></tt><em>s</em><tt
- class="docutils literal"><span class="pre">,op(</span></tt><em>s</em><tt
- class="docutils literal"><span class="pre">,x</span></tt>,<em>t</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">),</span></tt><em>t</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">),</span></tt><em>t</em><sub>2</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...</td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FOLD_RIGHT(op,</span>
- <span class="pre">x,</span> <span class="pre">t)</span></tt></td>
- <td>...<tt class="docutils literal"><span class="pre">op(</span></tt><em>s</em><tt
- class="docutils literal"><span class="pre">,op(</span></tt><em>s</em><tt
- class="docutils literal"><span class="pre">,op(</span></tt><em>s</em><tt
- class="docutils literal"><span class="pre">,x</span></tt>,<em>t</em><sub>k</sub><tt
- class="docutils literal"><span class="pre">),</span></tt><em>t</em><sub>k-1</sub><tt
- class="docutils literal"><span class="pre">),</span></tt>
- <em>t</em><sub>k-2</sub><tt class="docutils literal"><span class="pre">)</span></tt>...</td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FOR_EACH(f,</span>
- <span class="pre">x,</span> <span class="pre">t)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">f(</span></tt><em>r</em><tt
- class="docutils literal"><span class="pre">,</span> <span
- class="pre">x,</span></tt><em>t</em><sub>0</sub><tt class="docutils literal"><span
- class="pre">)</span> <span class="pre">f(</span></tt><em>r</em><tt
- class="docutils literal"><span class="pre">,</span> <span
- class="pre">x,</span></tt><em>t</em><sub>1</sub><tt class="docutils literal"><span
- class="pre">)</span></tt>...<tt class="docutils literal"><span
- class="pre">f(</span></tt><em>r</em><tt class="docutils literal"><span
- class="pre">,</span> <span class="pre">x,</span></tt><em>t</em><sub>k</sub><tt
- class="docutils literal"><span class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FOR_EACH_I(g,</span>
- <span class="pre">x,</span> <span class="pre">t)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">g(</span></tt><em>r</em><tt
- class="docutils literal"><span class="pre">,</span> <span
- class="pre">x,</span> <span class="pre">0,</span></tt>
- <em>t</em><sub>0</sub><tt class="docutils literal"><span class="pre">)</span>
- <span class="pre">g(</span></tt><em>r</em><tt class="docutils literal"><span
- class="pre">,</span> <span class="pre">x,</span> <span
- class="pre">1,</span></tt> <em>t</em><sub>1</sub><tt class="docutils literal"><span
- class="pre">)</span></tt>... <tt class="docutils literal"><span
- class="pre">g(</span></tt><em>r</em><tt class="docutils literal"><span
- class="pre">,</span> <span class="pre">x,</span> <span
- class="pre">k,</span></tt> <em>t</em><sub>k</sub><tt class="docutils literal"><span
- class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_FOR_EACH_PRODUCT(h,</span>
- <span class="pre">x,</span> <span class="pre">t)</span></tt></td>
- <td>
- <dl class="first last docutils">
- <dt>Cartesian product—</dt>
- <dd>see online docs</dd>
- </dl>
- </td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_INSERT(t,i,tokens)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>i-1</sub><tt
- class="docutils literal"><span class="pre">)(tokens)</span>
- <span class="pre">(</span></tt><em>t</em><sub>i</sub><tt class="docutils literal"><span
- class="pre">)(</span></tt><em>t</em><sub>i+1</sub><tt class="docutils literal"><span
- class="pre">)</span></tt>...<tt class="docutils literal"><span
- class="pre">(</span></tt><em>t</em><sub>k</sub><tt class="docutils literal"><span
- class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_POP_BACK(t)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k-1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_POP_FRONT(t)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>2</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
- class="docutils literal"><span class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_PUSH_BACK(t,tokens)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
- class="docutils literal"><span class="pre">)(tokens)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_PUSH_FRONT(t,tokens)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(tokens)(</span></tt><em>t</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
- class="docutils literal"><span class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_REMOVE(t,i)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>i-1</sub><tt
- class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>i+1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
- class="docutils literal"><span class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_REPLACE(t,i,tokens)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>i-1</sub><tt
- class="docutils literal"><span class="pre">)(tokens)(</span></tt><em>t</em><sub>i+1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
- class="docutils literal"><span class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_REST_N(n,t)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>n</sub><tt
- class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>n+1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
- class="docutils literal"><span class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_REVERSE(t)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
- class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>k-1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_HEAD(t)</span></tt></td>
- <td><em>t</em><sub>0</sub></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_TAIL(t)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>2</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>k</sub><tt
- class="docutils literal"><span class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_SIZE(t)</span></tt></td>
- <td><em>k+1</em></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_SUBSEQ(t,i,m)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>i</sub><tt
- class="docutils literal"><span class="pre">)(</span></tt><em>t</em><sub>i+1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt>...<tt
- class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>i+m-1</sub><tt
- class="docutils literal"><span class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_TO_ARRAY(t)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>k+1</em>
- <tt class="docutils literal"><span class="pre">,(</span></tt><em>t</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">,</span></tt><em>t</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...<em>t</em><sub>k</sub><tt
- class="docutils literal"><span class="pre">))</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_TO_TUPLE(t)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>t</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">,</span></tt> <em>t</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...<em>t</em><sub>k</sub><tt
- class="docutils literal"><span class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_TRANSFORM(f,</span>
- <span class="pre">x,</span> <span class="pre">t)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(f(</span></tt><em>r</em><tt
- class="docutils literal"><span class="pre">,x,</span></tt><em>t</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">))</span> <span
- class="pre">(f(</span></tt><em>r</em><tt class="docutils literal"><span
- class="pre">,x,</span></tt><em>t</em><sub>1</sub><tt class="docutils literal"><span
- class="pre">))</span></tt>...<tt class="docutils literal"><span
- class="pre">(f(</span></tt><em>r</em><tt class="docutils literal"><span
- class="pre">,x,</span></tt><em>t</em><sub>k</sub><tt class="docutils literal"><span
- class="pre">))</span></tt></td>
- </tr>
- </tbody>
- </table>
- <p>It's worth noting that while there is no upper limit on the
- length of a sequence, operations such as <tt class="docutils literal"><span
- class="pre">BOOST_PP_SEQ_ELEM</span></tt> that take numeric
- arguments will only work with values up to 256.</p>
- </div>
- <div class="section" id="tuples">
- <h3><a name="tuples">A.4.5.2 Tuples</a></h3>
- <p>A <strong>tuple</strong> is a very simple data structure for
- which the library provides random access and a few other basic
- operations. A tuple takes the form of a parenthesized,
- comma-separated list of <em>macro arguments</em>. For example,
- this is a three-element tuple:</p>
- <pre class="literal-block">#define TUPLE3 (f(12), a + 1, foo)
- </pre>
- <p>The operations in the library's <tt class="docutils literal"><span
- class="pre">tuple/</span></tt> subdirectory can handle tuples
- of up to 25 elements. For example, a tuple's <tt class="docutils literal"><span
- class="pre">N</span></tt>th element can be accessed via <tt class="docutils literal"><span
- class="pre">BOOST_PP_TUPLE_ELEM</span></tt>, as follows:</p>
- <pre class="literal-block"> // length index tuple
- BOOST_PP_TUPLE_ELEM( 3 , 1 , TUPLE3) // a + 1
- </pre>
- <!-- @def gen_id(id = 'a', hdr = 'tuple'):
- example.wrap(''' #include <boost/preprocessor/%s.hpp> int const %s = 0; int const x =''' % (hdr,id), ';')
- compile('all', pop = 1)gen_id() -->
- <p>Notice that we had to pass the tuple's length as the second
- argument to <tt class="docutils literal"><span class="pre">BOOST_PP_TUPLE_ELEM</span></tt>;
- in fact, <em>all</em> tuple operations require explicit
- specification of the tuple's length. We're not going to summarize
- the other four operations in the "tuple" group here—you can
- consult the Preprocessor library's electronic documentation for
- more details. We note, however, that sequences can be transformed
- into tuples with <tt class="docutils literal"><span class="pre">BOOST_PP_SEQ_TO_TUPLE</span></tt>,
- and nonempty tuples can be transformed back into sequences with <tt
- class="docutils literal"><span class="pre">BOOST_PP_TUPLE_TO_SEQ</span></tt>.</p>
- <p>The greatest strength of tuples is that they conveniently take
- the same representation as a macro argument list:</p>
- <pre class="literal-block">#define FIRST_OF_THREE(a1,a2,a3) a1
- #define SECOND_OF_THREE(a1,a2,a3) a2
- #define THIRD_OF_THREE(a1,a2,a3) a3
- // uses tuple as an argument list
- # define SELECT(selector, tuple) <strong>selector tuple</strong>
- SELECT(THIRD_OF_THREE, TUPLE3) // foo
- </pre>
- <!-- @gen_id('foo') --> </div>
- <div class="section" id="arrays">
- <h3><a name="arrays">A.4.5.3 Arrays</a></h3>
- <p>An <strong>array</strong> is just a tuple containing a
- non-negative integer and a tuple of that length:</p>
- <pre class="literal-block">#define ARRAY3 ( 3, TUPLE3 )
- </pre>
- <p>Because an array carries its length around with it, the library's
- interface for operating on arrays is much more convenient than the
- one used for tuples:</p>
- <pre class="literal-block">BOOST_PP_ARRAY_ELEM(1, ARRAY3) // a + 1
- </pre>
- <!-- @gen_id(hdr = 'array')
- del stack[-2:] -->
- <p>The facilities for manipulating arrays of up to 25 elements are
- all in the library's <tt class="docutils literal"><span class="pre">array/</span></tt>
- subdirectory. They are summarized in Table A.6, where <tt class="docutils literal"><span
- class="pre">a</span></tt> is the array <tt class="docutils literal"><span
- class="pre">(</span></tt><em>k</em><tt class="docutils literal"><span
- class="pre">,</span> <span class="pre">(</span></tt><em>a</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">,...</span></tt><em>a</em><sub>k-1</sub><tt
- class="docutils literal"><span class="pre">))</span></tt>.</p>
- <table border="1" class="docutils">
- <caption>Preprocessor Array Operations</caption> <colgroup> <col
- width="52%" /> <col width="48%" /> </colgroup>
- <thead valign="bottom">
- <tr>
- <th>Expression</th>
- <th>Result</th>
- </tr>
- </thead>
- <tbody valign="top">
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_DATA(a)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>a</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...
- <em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">)</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_ELEM(i,a)</span></tt></td>
- <td><em>a</em><sub>i</sub></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_INSERT(a,</span>
- <span class="pre">i,</span> <span class="pre">tokens)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>k+1</em><tt
- class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...<em>a</em><sub>i-1</sub><tt
- class="docutils literal"><span class="pre">,</span> <span
- class="pre">tokens,</span></tt> <em>a</em><sub>i</sub><tt
- class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>i+1</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...
- <em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">))</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_POP_BACK(a)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>k-1</em><tt
- class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...
- <em>a</em><sub>k-2</sub><tt class="docutils literal"><span class="pre">))</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_POP_FRONT(a)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>k-1</em><tt
- class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>2</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...
- <em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">))</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_PUSH_BACK(a,</span>
- <span class="pre">tokens)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>k+1</em><tt
- class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...
- <em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">,</span>
- <span class="pre">tokens))</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_PUSH_FRONT(a,</span>
- <span class="pre">tokens)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>k+1</em><tt
- class="docutils literal"><span class="pre">,(tokens,</span></tt>
- <em>a</em><sub>1</sub><tt class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>2</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...
- <em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">))</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_REMOVE(a,</span>
- <span class="pre">i)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>k-1</em><tt
- class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...
- <em>a</em><sub>i-1</sub><tt class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>i+1</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...
- <em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">))</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_REPLACE(a,</span>
- <span class="pre">i,</span> <span class="pre">tokens)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>k</em><tt
- class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>1</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...
- <em>a</em><sub>i-1</sub><tt class="docutils literal"><span class="pre">,</span>
- <span class="pre">tokens,</span></tt> <em>a</em><sub>i+1</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...
- <em>a</em><sub>k-1</sub><tt class="docutils literal"><span class="pre">))</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_REVERSE(a)</span></tt></td>
- <td><tt class="docutils literal"><span class="pre">(</span></tt><em>k</em><tt
- class="docutils literal"><span class="pre">,(</span></tt><em>a</em><sub>k-1</sub><tt
- class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>k-2</sub><tt
- class="docutils literal"><span class="pre">,</span></tt>...
- <em>a</em><sub>1</sub><tt class="docutils literal"><span class="pre">,</span></tt><em>a</em><sub>0</sub><tt
- class="docutils literal"><span class="pre">))</span></tt></td>
- </tr>
- <tr>
- <td><tt class="docutils literal"><span class="pre">BOOST_PP_ARRAY_SIZE(a)</span></tt></td>
- <td><em>k</em></td>
- </tr>
- </tbody>
- </table>
- </div>
- <div class="section" id="lists">
- <h3><a name="lists">A.4.5.4 Lists</a></h3>
- <p>A <strong>list</strong> is a two-element tuple whose first
- element is the first element of the list, and whose second element
- is a list of the remaining elements, or <tt class="docutils literal"><span
- class="pre">BOOST_PP_NIL</span></tt> if there are no remaining
- elements. Lists have access characteristics similar to those of a
- runtime linked list. Here is a three-element list:</p>
- <pre class="literal-block">#define LIST3 (<strong>f(12)</strong>, (<strong>a + 1</strong>, (<strong>foo</strong>, BOOST_PP_NIL)))
- </pre>
- <!-- @ignore() -->
- <p>The facilities for manipulating lists are all in the library's <tt
- class="docutils literal"><span class="pre">list/</span></tt>
- subdirectory. Because the operations are a subset of those
- provided for sequences, we're not going to summarize them here—it
- should be easy to understand the list operations by reading the
- documentation on the basis of our coverage of sequences.</p>
- <p>Like sequences, lists have no fixed upper length bound. Unlike
- sequences, lists can also be empty. It's rare to need more than 25
- elements in a preprocessor data structure, and lists tend to be
- slower to manipulate and harder to read than any of the other
- structures, so they should normally be used only as a last resort.</p>
- </div>
- </div>
- </div>
- <div class="section" id="exercise">
- <h1><a name="exercise">A.5 Exercise</a></h1>
- <dl class="docutils">
- <dt>A-0</dt>
- <dd>Fully preprocessor-ize the <tt class="docutils literal"><span class="pre">tiny</span></tt>
- type sequence implemented in Chapter 5 so that all boilerplate code
- is eliminated and the maximum size of a <tt class="docutils literal"><span
- class="pre">tiny</span></tt> sequence can be adjusted by
- changing <tt class="docutils literal"><span class="pre">TINY_MAX_SIZE</span></tt>.</dd>
- </dl>
- <!-- on hold:
- It isn't uncommon to need token-wise arithmetic operations forpurposes other than invoking Preprocessor Library repetitionmacros. For example, let's write a metafunction to generate
- function types from "signature" type sequences that specify thefunction's return and parameter types:: template <unsigned Size, class Signature>
- struct to_function_impl; template <class Signature> struct to_function
- : to_function_impl<mpl::size<Signature>::type, Signature> {};The challenge now is to implement ``to_function_impl``. For
- ``Size == 3``, an appropriate specialization might look like this:: template <class Signature> struct to_function_impl<3,Signature>
- { typedef mpl::begin<Signature>::type i0; typedef mpl::deref<i0>::type t0;
- typedef mpl::next<i0>::type i1; typedef mpl::deref<i1>::type t1; typedef mpl::next<i1>::type i2;
- typedef mpl::deref<i2>::type t2; typedef t0 type(t1,t2); };
- A local macro to generate a single ``to_function_impl``specialization would look something like this:
- .. parsed-literal:: #define to_function_impl_spec(size) \\ template <class Signature> \\
- struct to_function_impl<3,Signature> \\ { \\ typedef mpl::begin<Signature>::type i0; \\ typedef mpl::deref<i0>::type t0; \\
- \\ BOOST_PP_REPEAT_FROM_TO(1, size, to_function_t, ~) \\ \\ typedef t0 type(BOOST_PP_ENUM_SHIFTED_PARAMS(size,t)); \\
- }; #define to_function_t(z, n, unused) \\ typedef mpl::next<BOOST_PP_CAT(i,\ **BOOST_PP_DEC(n)**)>::type \\
- BOOST_PP_CAT(i,n); \\ \\ typedef mpl::deref<BOOST_PP_CAT(i,n)>::type BOOST_PP_CAT(t,n);
- We've used some new library macros above; here is a brief rundown:* ``BOOST_PP_REPEAT_FROM_TO`` is just like ``BOOST_PP_REPEAT``, except that it accepts an initial repetition index. Since every
- function has a return type, we don't need to worry about the case where ``Size == 0``.* ``BOOST_PP_ENUM_SHIFTED_PARAMS`` is just like
- ``BOOST_PP_ENUM_PARAMS``, except that repetition indices start at ``1`` instead of ``0``.* ``BOOST_PP_CAT`` implements token pasting; its two arguments are
- "glued" together into a single token. Since this is a general-purpose macro, it sits in ``cat.hpp`` at the top level of the library's directory tree. [#paste]_
- .. [#paste] The preprocessor's built-in token-pasting operator, ``##``, often yields surprising results by taking effect before its arguments have been expanded. By contrast, ``BOOST_PP_CAT`` delays concatenation until after its arguments have been fully
- evaluated.* Finally, though it only performs trivial arithmetic, ``BOOST_PP_DEC`` plays a crucial role in generating an
- appropriate prior iterator identifier for our own code in ``to_function_t``.If we didn't have ``BOOST_PP_REPEAT_FROM_TO`` at our disposal in
- the previous example, we might've had to use ``BOOST_PP_REPEAT``,which always starts iterating at ``0``. Consequently``to_function_t`` would've been responsible for producing thedeclarations of ``i0`` and ``t0`` as well as those of the other
- nested types. To manage that, it would need a way to selectdifferent expansions depending on the value of ``n``.In its ``control/`` directory, the Preprocessor Library supplies a
- macro ``BOOST_PP_IF(c,t,f)`` that fulfills a similar role to theone filled by ``mpl::if_``. Rewriting the example accordingly, weget:
- .. parsed-literal:: #define to_function_impl_spec(size) \\ template <class Signature> \\
- struct to_function_impl<3,Signature> \\ { \\ BOOST_PP_REPEAT_FROM_TO(1, size, to_function_t, ~) \\ \\
- typedef t0 type(BOOST_PP_ENUM_SHIFTED_PARAMS(size,t)); \\ }; #define to_function_t(z, n, unused) \\
- typedef BOOST_PP_IF( \\ n, \\ mpl::next<BOOST_PP_CAT(i,BOOST_PP_DEC(n))>::type, \\ typedef mpl::begin<Signature>::type i0; \\
- ) \\ BOOST_PP_CAT(i,n); \\ \\ typedef mpl::deref<BOOST_PP_CAT(i,n)>::type BOOST_PP_CAT(t,n);
- Although the formulation above will work, it does unnecessary workwhen ``n == 0``, evaluating the "true" branch of the conditionalonly to discard it. -->
- </div>
- </div>
- <hr class="docutils footer" />
- <div class="footer"> Generated on: 2005-10-17 19:34 UTC. Generated by <a class="reference"
- href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference"
- href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>
- source. </div>
- </body>
- </html>
- <!--
- FILE ARCHIVED ON 19:59:10 Mar 30, 2013 AND RETRIEVED FROM THE INTERNET ARCHIVE ON 21:06:19 May 19, 2015. JAVASCRIPT APPENDED BY WAYBACK MACHINE, COPYRIGHT INTERNET ARCHIVE.
- ALL OTHER CONTENT MAY ALSO BE PROTECTED BY COPYRIGHT (17 U.S.C. SECTION 108(a)(3)).-->
|