-
Notifications
You must be signed in to change notification settings - Fork 13
Expand file tree
/
Copy pathpreprocessor.html
More file actions
357 lines (285 loc) · 100 KB
/
preprocessor.html
File metadata and controls
357 lines (285 loc) · 100 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>C++ | Preprocessor</title>
<meta name="generator" content="VuePress 1.8.2">
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
<link rel="manifest" href="/site.webmanifest">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">
<link rel="mask-icon" href="/safari-pinned-tab.svg" color="#5bbad5">
<meta name="description" content="Include Guards, Conditional logic and cross-platform handling, Macros, X-macros, Preprocessor error messages , Predefined macros, #pragma once, Preprocessor Operators">
<meta property="og:site_name" content="DevTut">
<meta property="og:title" content="C++ | Preprocessor">
<meta property="og:description" content="Include Guards, Conditional logic and cross-platform handling, Macros, X-macros, Preprocessor error messages , Predefined macros, #pragma once, Preprocessor Operators">
<meta property="og:type" content="article">
<meta property="og:url" content="/cpp/preprocessor.html">
<meta property="og:image" content="/logo.png">
<meta name="twitter:title" content="C++ | Preprocessor">
<meta name="twitter:description" content="Include Guards, Conditional logic and cross-platform handling, Macros, X-macros, Preprocessor error messages , Predefined macros, #pragma once, Preprocessor Operators">
<meta name="twitter:url" content="/cpp/preprocessor.html">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:image" content="/logo.png">
<meta name="theme-color" content="#ffffff">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<meta name="msapplication-TileImage" content="/mstile-150x150.png">
<meta name="msapplication-TileColor" content="#da532c">
<meta name="google-site-verification" content="76_rKXgwMVIjd-axJC_1zPV9OS4mEjvtgjYOWVkAdnQ">
<link rel="preload" href="/assets/css/0.styles.60619e34.css" as="style"><link rel="preload" href="/assets/js/app.1779e102.js" as="script"><link rel="preload" href="/assets/js/3.2cfa8016.js" as="script"><link rel="preload" href="/assets/js/694.b4d61745.js" as="script">
<link rel="stylesheet" href="/assets/css/0.styles.60619e34.css">
</head>
<body>
<div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar"><div class="sidebar-button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"><path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path></svg></div> <a href="/" class="home-link router-link-active"><!----> <span class="site-name">DevTut</span></a> <div class="links"><form id="search-form" role="search" class="algolia-search-wrapper search-box"><input id="algolia-search-input" class="search-query"></form> <nav class="nav-links can-hide"> <a href="https://github.com/devtut/generate" target="_blank" rel="noopener noreferrer" class="repo-link">
GitHub
<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></nav></div></header> <div class="sidebar-mask"></div> <aside class="sidebar"><nav class="nav-links"> <a href="https://github.com/devtut/generate" target="_blank" rel="noopener noreferrer" class="repo-link">
GitHub
<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></nav> <ul class="sidebar-links"><li><section class="sidebar-group depth-0"><p class="sidebar-heading open"><span>C++</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/cpp/" aria-current="page" class="sidebar-link">Disclaimer</a></li><li><a href="/cpp/getting-started-with-cpp.html" class="sidebar-link">Getting started with C++</a></li><li><a href="/cpp/literals.html" class="sidebar-link">Literals</a></li><li><a href="/cpp/operator-precedence.html" class="sidebar-link">operator precedence</a></li><li><a href="/cpp/floating-point-arithmetic.html" class="sidebar-link">Floating Point Arithmetic</a></li><li><a href="/cpp/bit-operators.html" class="sidebar-link">Bit Operators</a></li><li><a href="/cpp/bit-manipulation.html" class="sidebar-link">Bit Manipulation</a></li><li><a href="/cpp/bit-fields.html" class="sidebar-link">Bit fields</a></li><li><a href="/cpp/arrays.html" class="sidebar-link">Arrays</a></li><li><a href="/cpp/iterators.html" class="sidebar-link">Iterators</a></li><li><a href="/cpp/basic-input-output-in-c.html" class="sidebar-link">Basic input/output in c++</a></li><li><a href="/cpp/loops.html" class="sidebar-link">Loops</a></li><li><a href="/cpp/file-i-o.html" class="sidebar-link">File I/O</a></li><li><a href="/cpp/cpp-streams.html" class="sidebar-link">C++ Streams</a></li><li><a href="/cpp/stream-manipulators.html" class="sidebar-link">Stream manipulators</a></li><li><a href="/cpp/flow-control.html" class="sidebar-link">Flow Control</a></li><li><a href="/cpp/metaprogramming.html" class="sidebar-link">Metaprogramming</a></li><li><a href="/cpp/const-keyword.html" class="sidebar-link">const keyword</a></li><li><a href="/cpp/mutable-keyword.html" class="sidebar-link">mutable keyword</a></li><li><a href="/cpp/friend-keyword.html" class="sidebar-link">Friend keyword</a></li><li><a href="/cpp/type-keywords.html" class="sidebar-link">Type Keywords</a></li><li><a href="/cpp/basic-type-keywords.html" class="sidebar-link">Basic Type Keywords</a></li><li><a href="/cpp/variable-declaration-keywords.html" class="sidebar-link">Variable Declaration Keywords</a></li><li><a href="/cpp/keywords.html" class="sidebar-link">Keywords</a></li><li><a href="/cpp/returning-several-values-from-a-function.html" class="sidebar-link">Returning several values from a function</a></li><li><a href="/cpp/polymorphism.html" class="sidebar-link">Polymorphism</a></li><li><a href="/cpp/references.html" class="sidebar-link">References</a></li><li><a href="/cpp/value-and-reference-semantics.html" class="sidebar-link">Value and Reference Semantics</a></li><li><a href="/cpp/c-function-call-by-value-vs-call-by-reference.html" class="sidebar-link">C++ function "call by value" vs. "call by reference"</a></li><li><a href="/cpp/copying-vs-assignment.html" class="sidebar-link">Copying vs Assignment</a></li><li><a href="/cpp/pointers.html" class="sidebar-link">Pointers</a></li><li><a href="/cpp/pointers-to-members.html" class="sidebar-link">Pointers to members</a></li><li><a href="/cpp/the-this-pointer.html" class="sidebar-link">The This Pointer</a></li><li><a href="/cpp/smart-pointers.html" class="sidebar-link">Smart Pointers</a></li><li><a href="/cpp/classes-structures.html" class="sidebar-link">Classes/Structures</a></li><li><a href="/cpp/function-overloading.html" class="sidebar-link">Function Overloading</a></li><li><a href="/cpp/operator-overloading.html" class="sidebar-link">Operator Overloading</a></li><li><a href="/cpp/function-template-overloading.html" class="sidebar-link">Function Template Overloading</a></li><li><a href="/cpp/virtual-member-functions.html" class="sidebar-link">Virtual Member Functions</a></li><li><a href="/cpp/inline-functions.html" class="sidebar-link">Inline functions</a></li><li><a href="/cpp/special-member-functions.html" class="sidebar-link">Special Member Functions</a></li><li><a href="/cpp/non-static-member-functions.html" class="sidebar-link">Non-Static Member Functions</a></li><li><a href="/cpp/constant-class-member-functions.html" class="sidebar-link">Constant class member functions</a></li><li><a href="/cpp/c-containers.html" class="sidebar-link">C++ Containers</a></li><li><a href="/cpp/namespaces.html" class="sidebar-link">Namespaces</a></li><li><a href="/cpp/header-files.html" class="sidebar-link">Header Files</a></li><li><a href="/cpp/using-declaration.html" class="sidebar-link">Using declaration</a></li><li><a href="/cpp/std-string.html" class="sidebar-link">std::string</a></li><li><a href="/cpp/std-array.html" class="sidebar-link">std::array</a></li><li><a href="/cpp/std-vector.html" class="sidebar-link">std::vector</a></li><li><a href="/cpp/std-map.html" class="sidebar-link">std::map</a></li><li><a href="/cpp/std-optional.html" class="sidebar-link">std::optional</a></li><li><a href="/cpp/std-function-to-wrap-any-element-that-is-callable.html" class="sidebar-link">std::function: To wrap any element that is callable</a></li><li><a href="/cpp/std-forward-list.html" class="sidebar-link">std::forward_list</a></li><li><a href="/cpp/std-pair.html" class="sidebar-link">std::pair</a></li><li><a href="/cpp/std-atomics.html" class="sidebar-link">std::atomics</a></li><li><a href="/cpp/std-variant.html" class="sidebar-link">std::variant</a></li><li><a href="/cpp/std-iomanip.html" class="sidebar-link">std::iomanip</a></li><li><a href="/cpp/std-any.html" class="sidebar-link">std::any</a></li><li><a href="/cpp/std-set-and-std-multiset.html" class="sidebar-link">std::set and std::multiset</a></li><li><a href="/cpp/std-integer-sequence.html" class="sidebar-link">std::integer_sequence</a></li><li><a href="/cpp/using-std-unordered-map.html" class="sidebar-link">Using std::unordered_map</a></li><li><a href="/cpp/standard-library-algorithms.html" class="sidebar-link">Standard Library Algorithms</a></li><li><a href="/cpp/the-iso-c-standard.html" class="sidebar-link">The ISO C++ Standard</a></li><li><a href="/cpp/inline-variables.html" class="sidebar-link">Inline variables</a></li><li><a href="/cpp/random-number-generation.html" class="sidebar-link">Random number generation</a></li><li><a href="/cpp/date-and-time-using-chrono-header.html" class="sidebar-link">Date and time using header</a></li><li><a href="/cpp/sorting.html" class="sidebar-link">Sorting</a></li><li><a href="/cpp/enumeration.html" class="sidebar-link">Enumeration</a></li><li><a href="/cpp/iteration.html" class="sidebar-link">Iteration</a></li><li><a href="/cpp/regular-expressions.html" class="sidebar-link">Regular expressions</a></li><li><a href="/cpp/implementation-defined-behavior.html" class="sidebar-link">Implementation-defined behavior</a></li><li><a href="/cpp/exceptions.html" class="sidebar-link">Exceptions</a></li><li><a href="/cpp/lambdas.html" class="sidebar-link">Lambdas</a></li><li><a href="/cpp/value-categories.html" class="sidebar-link">Value Categories</a></li><li><a href="/cpp/preprocessor.html" aria-current="page" class="active sidebar-link">Preprocessor</a><ul class="sidebar-sub-headers"><li class="sidebar-sub-header"><a href="/cpp/preprocessor.html#include-guards" class="sidebar-link">Include Guards</a></li><li class="sidebar-sub-header"><a href="/cpp/preprocessor.html#conditional-logic-and-cross-platform-handling" class="sidebar-link">Conditional logic and cross-platform handling</a></li><li class="sidebar-sub-header"><a href="/cpp/preprocessor.html#macros" class="sidebar-link">Macros</a></li><li class="sidebar-sub-header"><a href="/cpp/preprocessor.html#x-macros" class="sidebar-link">X-macros</a></li><li class="sidebar-sub-header"><a href="/cpp/preprocessor.html#preprocessor-error-messages" class="sidebar-link">Preprocessor error messages</a></li><li class="sidebar-sub-header"><a href="/cpp/preprocessor.html#predefined-macros" class="sidebar-link">Predefined macros</a></li><li class="sidebar-sub-header"><a href="/cpp/preprocessor.html#pragma-once" class="sidebar-link">#pragma once</a></li><li class="sidebar-sub-header"><a href="/cpp/preprocessor.html#preprocessor-operators" class="sidebar-link">Preprocessor Operators</a></li></ul></li><li><a href="/cpp/data-structures-in-c.html" class="sidebar-link">Data Structures in C++</a></li><li><a href="/cpp/templates.html" class="sidebar-link">Templates</a></li><li><a href="/cpp/expression-templates.html" class="sidebar-link">Expression templates</a></li><li><a href="/cpp/curiously-recurring-template-pattern-crtp.html" class="sidebar-link">Curiously Recurring Template Pattern (CRTP)</a></li><li><a href="/cpp/threading.html" class="sidebar-link">Threading</a></li><li><a href="/cpp/thread-synchronization-structures.html" class="sidebar-link">Thread synchronization structures</a></li><li><a href="/cpp/the-rule-of-three-five-and-zero.html" class="sidebar-link">The Rule of Three, Five, And Zero</a></li><li><a href="/cpp/raii-resource-acquisition-is-initialization.html" class="sidebar-link">RAII: Resource Acquisition Is Initialization</a></li><li><a href="/cpp/rtti-run-time-type-information.html" class="sidebar-link">RTTI: Run-Time Type Information</a></li><li><a href="/cpp/mutexes.html" class="sidebar-link">Mutexes</a></li><li><a href="/cpp/recursive-mutex.html" class="sidebar-link">Recursive Mutex</a></li><li><a href="/cpp/semaphore.html" class="sidebar-link">Semaphore</a></li><li><a href="/cpp/futures-and-promises.html" class="sidebar-link">Futures and Promises</a></li><li><a href="/cpp/atomic-types.html" class="sidebar-link">Atomic Types</a></li><li><a href="/cpp/type-erasure.html" class="sidebar-link">Type Erasure</a></li><li><a href="/cpp/explicit-type-conversions.html" class="sidebar-link">Explicit type conversions</a></li><li><a href="/cpp/unnamed-types.html" class="sidebar-link">Unnamed types</a></li><li><a href="/cpp/type-traits.html" class="sidebar-link">Type Traits</a></li><li><a href="/cpp/return-type-covariance.html" class="sidebar-link">Return Type Covariance</a></li><li><a href="/cpp/layout-of-object-types.html" class="sidebar-link">Layout of object types</a></li><li><a href="/cpp/type-inference.html" class="sidebar-link">Type Inference</a></li><li><a href="/cpp/typedef-and-type-aliases.html" class="sidebar-link">Typedef and type aliases</a></li><li><a href="/cpp/type-deduction.html" class="sidebar-link">type deduction</a></li><li><a href="/cpp/trailing-return-type.html" class="sidebar-link">Trailing return type</a></li><li><a href="/cpp/alignment.html" class="sidebar-link">Alignment</a></li><li><a href="/cpp/perfect-forwarding.html" class="sidebar-link">Perfect Forwarding</a></li><li><a href="/cpp/decltype.html" class="sidebar-link">decltype</a></li><li><a href="/cpp/sfinae-substitution-failure-is-not-an-error.html" class="sidebar-link">SFINAE (Substitution Failure Is Not An Error)</a></li><li><a href="/cpp/undefined-behavior.html" class="sidebar-link">Undefined Behavior</a></li><li><a href="/cpp/overload-resolution.html" class="sidebar-link">Overload resolution</a></li><li><a href="/cpp/move-semantics.html" class="sidebar-link">Move Semantics</a></li><li><a href="/cpp/pimpl-idiom.html" class="sidebar-link">Pimpl Idiom</a></li><li><a href="/cpp/auto.html" class="sidebar-link">auto</a></li><li><a href="/cpp/copy-elision.html" class="sidebar-link">Copy Elision</a></li><li><a href="/cpp/fold-expressions.html" class="sidebar-link">Fold Expressions</a></li><li><a href="/cpp/unions.html" class="sidebar-link">Unions</a></li><li><a href="/cpp/design-pattern-implementation-in-c.html" class="sidebar-link">Design pattern implementation in C++</a></li><li><a href="/cpp/singleton-design-pattern.html" class="sidebar-link">Singleton Design Pattern</a></li><li><a href="/cpp/user-defined-literals.html" class="sidebar-link">User-Defined Literals</a></li><li><a href="/cpp/memory-management.html" class="sidebar-link">Memory management</a></li><li><a href="/cpp/c-11-memory-model.html" class="sidebar-link">C++11 Memory Model</a></li><li><a href="/cpp/scopes.html" class="sidebar-link">Scopes</a></li><li><a href="/cpp/static-assert.html" class="sidebar-link">static_assert</a></li><li><a href="/cpp/constexpr.html" class="sidebar-link">constexpr</a></li><li><a href="/cpp/one-definition-rule-odr.html" class="sidebar-link">One Definition Rule (ODR)</a></li><li><a href="/cpp/unspecified-behavior.html" class="sidebar-link">Unspecified behavior</a></li><li><a href="/cpp/argument-dependent-name-lookup.html" class="sidebar-link">Argument Dependent Name Lookup</a></li><li><a href="/cpp/attributes.html" class="sidebar-link">Attributes</a></li><li><a href="/cpp/recursion-in-c.html" class="sidebar-link">Recursion in C++</a></li><li><a href="/cpp/arithmitic-metaprogramming.html" class="sidebar-link">Arithmitic Metaprogramming</a></li><li><a href="/cpp/callable-objects.html" class="sidebar-link">Callable Objects</a></li><li><a href="/cpp/client-server-examples.html" class="sidebar-link">Client server examples</a></li><li><a href="/cpp/const-correctness.html" class="sidebar-link">Const Correctness</a></li><li><a href="/cpp/parameter-packs.html" class="sidebar-link">Parameter packs</a></li><li><a href="/cpp/build-systems.html" class="sidebar-link">Build Systems</a></li><li><a href="/cpp/concurrency-with-openmp.html" class="sidebar-link">Concurrency With OpenMP</a></li><li><a href="/cpp/resource-management.html" class="sidebar-link">Resource Management</a></li><li><a href="/cpp/storage-class-specifiers.html" class="sidebar-link">Storage class specifiers</a></li><li><a href="/cpp/linkage-specifications.html" class="sidebar-link">Linkage specifications</a></li><li><a href="/cpp/digit-separators.html" class="sidebar-link">Digit separators</a></li><li><a href="/cpp/c-incompatibilities.html" class="sidebar-link">C incompatibilities</a></li><li><a href="/cpp/side-by-side-comparisons-of-classic-c-examples-solved-via-c-vs-c-11-vs-c-14-vs-c-17.html" class="sidebar-link">Side by Side Comparisons of classic C++ examples solved via C++ vs C++11 vs C++14 vs C++17</a></li><li><a href="/cpp/compiling-and-building.html" class="sidebar-link">Compiling and Building</a></li><li><a href="/cpp/common-compile-linker-errors-gcc.html" class="sidebar-link">Common compile/linker errors (GCC)</a></li><li><a href="/cpp/more-undefined-behaviors-in-c.html" class="sidebar-link">More undefined behaviors in C++</a></li><li><a href="/cpp/unit-testing-in-c.html" class="sidebar-link">Unit Testing in C++</a></li><li><a href="/cpp/c-debugging-and-debug-prevention-tools-techniques.html" class="sidebar-link">C++ Debugging and Debug-prevention Tools & Techniques</a></li><li><a href="/cpp/optimization-in-c.html" class="sidebar-link">Optimization in C++</a></li><li><a href="/cpp/optimization.html" class="sidebar-link">Optimization</a></li><li><a href="/cpp/profiling.html" class="sidebar-link">Profiling</a></li><li><a href="/cpp/refactoring-techniques.html" class="sidebar-link">Refactoring Techniques</a></li><li><a href="/cpp/internationalization-in-c.html" class="sidebar-link">Internationalization in C++</a></li><li><a href="/cpp/contributors.html" class="sidebar-link">The Contributors</a></li></ul></section></li></ul> </aside> <main class="page"> <div class="theme-default-content content__default"><h1 id="preprocessor"><a href="#preprocessor" class="header-anchor">#</a> Preprocessor</h1> <p>The C preprocessor is a simple text parser/replacer that is run before the actual compilation of the code. Used to extend and ease the use of the C (and later C++) language, it can be used for:</p> <p>a. <strong>Including other files</strong> using <code>#include</code></p> <p>b. <strong>Define a text-replacement macro</strong> using <code>#define</code></p> <p>c. <strong>Conditional Compilation</strong> using<code>#if</code> <code>#ifdef</code></p> <p>d. <strong>Platform/Compiler specific logic</strong> (as an extension of conditional compilation)</p> <h2 id="include-guards"><a href="#include-guards" class="header-anchor">#</a> Include Guards</h2> <p>A header file may be included by other header files. A source file (compilation unit) that includes multiple headers may therefore, indirectly, include some headers more than once. If such a header file that is included more than once contains definitions, the compiler (after preprocessing) detects a violation of the One Definition Rule (e.g. §3.2 of the 2003 C++ standard) and therefore issues a diagnostic and compilation fails.</p> <p>Multiple inclusion is prevented using "include guards", which are sometimes also known as header guards or macro guards. These are implemented using the preprocessor <code>#define</code>, <code>#ifndef</code>, <code>#endif</code> directives.</p> <p>e.g.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token comment">// Foo.h</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">ifndef</span> <span class="token expression">FOO_H_INCLUDED </span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name">FOO_H_INCLUDED</span></span>
<span class="token keyword">class</span> <span class="token class-name">Foo</span> <span class="token comment">// a class definition</span>
<span class="token punctuation">{</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">endif</span></span>
</code></pre></div><p>The key advantage of using include guards is that they will work with all standard-compliant compilers and preprocessors.</p> <p>However, include guards also cause some problems for developers, as it is necessary to ensure the macros are unique within all headers used in a project. Specifically, if two (or more) headers use <code>FOO_H_INCLUDED</code> as their include guard, the first of those headers included in a compilation unit will effectively prevent the others from being included. Particular challenges are introduced if a project uses a number of third-party libraries with header files that happen to use include guards in common.</p> <p>It is also necessary to ensure that the macros used in include guards do not conflict with any other macros defined in header files.</p> <p><a href="https://en.wikipedia.org/wiki/Pragma_once#Portability" target="_blank" rel="noopener noreferrer">Most C++ implementations<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> also support the <code>#pragma once</code> directive which ensures the file is only included once within a single compilation. This is a <a href="https://en.wikipedia.org/wiki/De_facto_standard" target="_blank" rel="noopener noreferrer"><strong>de facto</strong> standard<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> directive, but it is not part of any ISO C++ standard. For example:</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token comment">// Foo.h</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">pragma</span> <span class="token expression">once</span></span>
<span class="token keyword">class</span> <span class="token class-name">Foo</span>
<span class="token punctuation">{</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>
</code></pre></div><p>While <code>#pragma once</code> avoids some problems associated with include guards, a <code>#pragma</code> - by definition in the standards - is inherently a compiler-specific hook, and will be silently ignored by compilers that don't support it. Projects which use <code>#pragma once</code> are more difficult to port to compilers that don't support it.</p> <p>A number of coding guidelines and assurance standards for C++ specifically discourage any use of the preprocessor other than to <code>#include</code> header files or for the purposes of placing include guards in headers.</p> <h2 id="conditional-logic-and-cross-platform-handling"><a href="#conditional-logic-and-cross-platform-handling" class="header-anchor">#</a> Conditional logic and cross-platform handling</h2> <p>In a nutshell, conditional pre-processing logic is about making code-logic available or unavailable for compilation using macro definitions.</p> <p>Three prominent use-cases are:</p> <ul><li>different <strong>app profiles</strong> (e.g. debug, release, testing, optimised) that can be candidates of the same app (e.g. with extra logging).</li> <li><strong>cross-platform compiles</strong> - single code-base, multiple compilation platforms.</li> <li>utilising a common code-base for multiple <strong>application versions</strong> (e.g. Basic, Premium and Pro versions of a software) - with slightly different features.</li></ul> <p><strong>Example a:</strong> A cross-platform approach for removing files (illustrative):</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">ifdef</span> <span class="token expression">_WIN32</span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">include</span> <span class="token string"><windows.h></span> <span class="token comment">// and other windows system files</span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">endif</span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">include</span> <span class="token string"><cstdio></span></span>
<span class="token keyword">bool</span> <span class="token function">remove_file</span><span class="token punctuation">(</span><span class="token keyword">const</span> std<span class="token double-colon punctuation">::</span>string <span class="token operator">&</span>path<span class="token punctuation">)</span>
<span class="token punctuation">{</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">ifdef</span> <span class="token expression">_WIN32</span></span>
<span class="token keyword">return</span> <span class="token function">DeleteFile</span><span class="token punctuation">(</span>path<span class="token punctuation">.</span><span class="token function">c_str</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">elif</span> <span class="token expression"><span class="token function">defined</span><span class="token punctuation">(</span>_POSIX_VERSION<span class="token punctuation">)</span> <span class="token operator">||</span> <span class="token function">defined</span><span class="token punctuation">(</span>__unix__<span class="token punctuation">)</span></span></span>
<span class="token keyword">return</span> <span class="token punctuation">(</span><span class="token number">0</span> <span class="token operator">==</span> <span class="token function">remove</span><span class="token punctuation">(</span>path<span class="token punctuation">.</span><span class="token function">c_str</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">elif</span> <span class="token expression"><span class="token function">defined</span><span class="token punctuation">(</span>__APPLE__<span class="token punctuation">)</span></span></span>
<span class="token comment">//TODO: check if NSAPI has a more specific function with permission dialog</span>
<span class="token keyword">return</span> <span class="token punctuation">(</span><span class="token number">0</span> <span class="token operator">==</span> <span class="token function">remove</span><span class="token punctuation">(</span>path<span class="token punctuation">.</span><span class="token function">c_str</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">else</span> </span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">error</span> <span class="token string">"This platform is not supported"</span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">endif</span></span>
<span class="token punctuation">}</span>
</code></pre></div><p>Macros like <code>_WIN32</code>, <code>__APPLE__</code> or <code>__unix__</code> are normally predefined by corresponding implementations.</p> <p><strong>Example b:</strong> Enabling additional logging for a debug build:</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token keyword">void</span> <span class="token function">s_PrintAppStateOnUserPrompt</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
<span class="token punctuation">{</span>
std<span class="token double-colon punctuation">::</span>cout <span class="token operator"><<</span> <span class="token string">"--------BEGIN-DUMP---------------\n"</span>
<span class="token operator"><<</span> <span class="token class-name">AppState</span><span class="token double-colon punctuation">::</span><span class="token function">Instance</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token operator">-></span><span class="token function">Settings</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">ToString</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator"><<</span> <span class="token string">"\n"</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">if</span> <span class="token expression"><span class="token punctuation">(</span> <span class="token number">1</span> <span class="token operator">==</span> TESTING_MODE <span class="token punctuation">)</span> </span><span class="token comment">//privacy: we want user details only when testing</span></span>
<span class="token operator"><<</span> <span class="token function">ListToString</span><span class="token punctuation">(</span><span class="token class-name">AppState</span><span class="token double-colon punctuation">::</span><span class="token function">UndoStack</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token operator">-></span><span class="token function">GetActionNames</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
<span class="token operator"><<</span> <span class="token class-name">AppState</span><span class="token double-colon punctuation">::</span><span class="token function">Instance</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token operator">-></span><span class="token function">CrntDocument</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">Name</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
<span class="token operator"><<</span> <span class="token class-name">AppState</span><span class="token double-colon punctuation">::</span><span class="token function">Instance</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token operator">-></span><span class="token function">CrntDocument</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">SignatureSHA</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator"><<</span> <span class="token string">"\n"</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">endif</span></span>
<span class="token operator"><<</span> <span class="token string">"--------END-DUMP---------------\n"</span>
<span class="token punctuation">}</span>
</code></pre></div><p><strong>Example c:</strong> Enable a premium feature in a separate product build (note: this is illustrative. it is often a better idea to allow a feature to be unlocked without the need to reinstall an application)</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token keyword">void</span> <span class="token class-name">MainWindow</span><span class="token double-colon punctuation">::</span><span class="token function">OnProcessButtonClick</span><span class="token punctuation">(</span><span class="token punctuation">)</span>
<span class="token punctuation">{</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">ifndef</span> <span class="token expression">_PREMIUM</span></span>
<span class="token function">CreatePurchaseDialog</span><span class="token punctuation">(</span><span class="token string">"Buy App Premium"</span><span class="token punctuation">,</span> <span class="token string">"This feature is available for our App Premium users. Click the Buy button to purchase the Premium version at our website"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">return</span><span class="token punctuation">;</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">endif</span></span>
<span class="token comment">//...actual feature logic here</span>
<span class="token punctuation">}</span>
</code></pre></div><p><strong>Some common tricks:</strong></p> <p><strong>Defining symbols at invocation time:</strong></p> <p>The preprocessor can be called with predefined symbols (with optional initialisation). For example this command (<code>gcc -E</code> runs only the preprocessor)</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code>gcc <span class="token operator">-</span>E <span class="token operator">-</span>DOPTIMISE_FOR_OS_X <span class="token operator">-</span>DTESTING_MODE<span class="token operator">=</span><span class="token number">1</span> Sample<span class="token punctuation">.</span>cpp
</code></pre></div><p>processes Sample.cpp in the same way as it would if <code>#define OPTIMISE_FOR_OS_X</code> and <code>#define TESTING_MODE 1</code> were added to the top of Sample.cpp.</p> <p><strong>Ensuring a macro is defined:</strong></p> <p>If a macro isn't defined and its value is compared or checked, the preprocessor almost always silently assumes the value to be <code>0</code>. There are a few ways to work with this. One approach is to assume that the default settings are represented as 0, and any changes (e.g. to the app build profile) needs to be explicitly done (e.g. ENABLE_EXTRA_DEBUGGING=0 by default, set -DENABLE_EXTRA_DEBUGGING=1 to override). Another approach is make all definitions and defaults explicit. This can be achieved using a combination of <code>#ifndef</code> and <code>#error</code> directives:</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">ifndef</span> <span class="token expression"><span class="token punctuation">(</span>ENABLE_EXTRA_DEBUGGING<span class="token punctuation">)</span></span></span>
<span class="token comment">// please include DefaultDefines.h if not already included.</span>
<span class="token macro property"><span class="token directive-hash">#</span> <span class="token directive keyword">error</span> <span class="token string">"ENABLE_EXTRA_DEBUGGING is not defined"</span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">else</span></span>
<span class="token macro property"><span class="token directive-hash">#</span> <span class="token directive keyword">if</span> <span class="token expression"><span class="token punctuation">(</span> <span class="token number">1</span> <span class="token operator">==</span> ENABLE_EXTRA_DEBUGGING <span class="token punctuation">)</span></span></span>
<span class="token comment">//code</span>
<span class="token macro property"><span class="token directive-hash">#</span> <span class="token directive keyword">endif</span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">endif</span></span>
</code></pre></div><h2 id="macros"><a href="#macros" class="header-anchor">#</a> Macros</h2> <p>Macros are categorized into two main groups: object-like macros and function-like macros. Macros are treated as a token substitution early in the compilation process. This means that large (or repeating) sections of code can be abstracted into a preprocessor macro.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token comment">// This is an object-like macro</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name">PI</span> <span class="token expression"><span class="token number">3.14159265358979</span></span></span>
<span class="token comment">// This is a function-like macro.</span>
<span class="token comment">// Note that we can use previously defined macros</span>
<span class="token comment">// in other macro definitions (object-like or function-like)</span>
<span class="token comment">// But watch out, its quite useful if you know what you're doing, but the</span>
<span class="token comment">// Compiler doesnt know which type to handle, so using inline functions instead</span>
<span class="token comment">// is quite recommended (But e.g. for Minimum/Maximum functions it is quite useful)</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">AREA</span><span class="token expression"><span class="token punctuation">(</span>r<span class="token punctuation">)</span> <span class="token punctuation">(</span>PI<span class="token operator">*</span><span class="token punctuation">(</span>r<span class="token punctuation">)</span><span class="token operator">*</span><span class="token punctuation">(</span>r<span class="token punctuation">)</span><span class="token punctuation">)</span></span></span>
<span class="token comment">// They can be used like this:</span>
<span class="token keyword">double</span> pi_macro <span class="token operator">=</span> PI<span class="token punctuation">;</span>
<span class="token keyword">double</span> area_macro <span class="token operator">=</span> <span class="token function">AREA</span><span class="token punctuation">(</span><span class="token number">4.6</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre></div><p>The Qt library makes use of this technique to create a meta-object system by having the user declare the Q_OBJECT macro at the head of the user-defined class extending QObject.</p> <p>Macro names are usually written in all caps, to make them easier to differentiate from normal code. This isn't a requirement, but is merely considered good style by many programmers.</p> <p>When an object-like macro is encountered, it's expanded as a simple copy-paste operation, with the macro's name being replaced with its definition. When a function-like macro is encountered, both its name and its parameters are expanded.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token keyword">double</span> pi_squared <span class="token operator">=</span> PI <span class="token operator">*</span> PI<span class="token punctuation">;</span>
<span class="token comment">// Compiler sees:</span>
<span class="token keyword">double</span> pi_squared <span class="token operator">=</span> <span class="token number">3.14159265358979</span> <span class="token operator">*</span> <span class="token number">3.14159265358979</span><span class="token punctuation">;</span>
<span class="token keyword">double</span> area <span class="token operator">=</span> <span class="token function">AREA</span><span class="token punctuation">(</span><span class="token number">5</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// Compiler sees:</span>
<span class="token keyword">double</span> area <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token number">3.14159265358979</span><span class="token operator">*</span><span class="token punctuation">(</span><span class="token number">5</span><span class="token punctuation">)</span><span class="token operator">*</span><span class="token punctuation">(</span><span class="token number">5</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
</code></pre></div><p>Due to this, function-like macro parameters are often enclosed within parentheses, as in <code>AREA()</code> above. This is to prevent any bugs that can occur during macro expansion, specifically bugs caused by a single macro parameter being composed of multiple actual values.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">BAD_AREA</span><span class="token expression"><span class="token punctuation">(</span>r<span class="token punctuation">)</span> PI <span class="token operator">*</span> r <span class="token operator">*</span> r</span></span>
<span class="token keyword">double</span> bad_area <span class="token operator">=</span> <span class="token function">BAD_AREA</span><span class="token punctuation">(</span><span class="token number">5</span> <span class="token operator">+</span> <span class="token number">1.6</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// Compiler sees:</span>
<span class="token keyword">double</span> bad_area <span class="token operator">=</span> <span class="token number">3.14159265358979</span> <span class="token operator">*</span> <span class="token number">5</span> <span class="token operator">+</span> <span class="token number">1.6</span> <span class="token operator">*</span> <span class="token number">5</span> <span class="token operator">+</span> <span class="token number">1.6</span><span class="token punctuation">;</span>
<span class="token keyword">double</span> good_area <span class="token operator">=</span> <span class="token function">AREA</span><span class="token punctuation">(</span><span class="token number">5</span> <span class="token operator">+</span> <span class="token number">1.6</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// Compiler sees:</span>
<span class="token keyword">double</span> good_area <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token number">3.14159265358979</span><span class="token operator">*</span><span class="token punctuation">(</span><span class="token number">5</span> <span class="token operator">+</span> <span class="token number">1.6</span><span class="token punctuation">)</span><span class="token operator">*</span><span class="token punctuation">(</span><span class="token number">5</span> <span class="token operator">+</span> <span class="token number">1.6</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre></div><p>Also note that due to this simple expansion, care must be taken with the parameters passed to macros, to prevent unexpected side effects. If the parameter is modified during evaluation, it will be modified each time it is used in the expanded macro, which usually isn't what we want. This is true even if the macro encloses the parameters in parentheses to prevent expansion from breaking anything.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token keyword">int</span> oops <span class="token operator">=</span> <span class="token number">5</span><span class="token punctuation">;</span>
<span class="token keyword">double</span> incremental_damage <span class="token operator">=</span> <span class="token function">AREA</span><span class="token punctuation">(</span>oops<span class="token operator">++</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// Compiler sees:</span>
<span class="token keyword">double</span> incremental_damage <span class="token operator">=</span> <span class="token punctuation">(</span><span class="token number">3.14159265358979</span><span class="token operator">*</span><span class="token punctuation">(</span>oops<span class="token operator">++</span><span class="token punctuation">)</span><span class="token operator">*</span><span class="token punctuation">(</span>oops<span class="token operator">++</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre></div><p>Additionally, macros provide no type-safety, leading to hard-to-understand errors about type mismatch.</p> <p>As programmers normally terminate lines with a semicolon, macros that are intended to be used as standalone lines are often designed to "swallow" a semicolon; this prevents any unintended bugs from being caused by an extra semicolon.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">IF_BREAKER</span><span class="token expression"><span class="token punctuation">(</span>Func<span class="token punctuation">)</span> <span class="token function">Func</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span></span>
<span class="token keyword">if</span> <span class="token punctuation">(</span>some_condition<span class="token punctuation">)</span>
<span class="token comment">// Oops.</span>
<span class="token function">IF_BREAKER</span><span class="token punctuation">(</span>some_func<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">else</span>
std<span class="token double-colon punctuation">::</span>cout <span class="token operator"><<</span> <span class="token string">"I am accidentally an orphan."</span> <span class="token operator"><<</span> std<span class="token double-colon punctuation">::</span>endl<span class="token punctuation">;</span>
</code></pre></div><p>In this example, the inadvertent double semicolon breaks the <code>if...else</code> block, preventing the compiler from matching the <code>else</code> to the <code>if</code>. To prevent this, the semicolon is omitted from the macro definition, which will cause it to "swallow" the semicolon immediately following any usage of it.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">IF_FIXER</span><span class="token expression"><span class="token punctuation">(</span>Func<span class="token punctuation">)</span> <span class="token function">Func</span><span class="token punctuation">(</span><span class="token punctuation">)</span></span></span>
<span class="token keyword">if</span> <span class="token punctuation">(</span>some_condition<span class="token punctuation">)</span>
<span class="token function">IF_FIXER</span><span class="token punctuation">(</span>some_func<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">else</span>
std<span class="token double-colon punctuation">::</span>cout <span class="token operator"><<</span> <span class="token string">"Hooray! I work again!"</span> <span class="token operator"><<</span> std<span class="token double-colon punctuation">::</span>endl<span class="token punctuation">;</span>
</code></pre></div><p>Leaving off the trailing semicolon also allows the macro to be used without ending the current statement, which can be beneficial.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">DO_SOMETHING</span><span class="token expression"><span class="token punctuation">(</span>Func<span class="token punctuation">,</span> Param<span class="token punctuation">)</span> <span class="token function">Func</span><span class="token punctuation">(</span>Param<span class="token punctuation">,</span> <span class="token number">2</span><span class="token punctuation">)</span></span></span>
<span class="token comment">// ...</span>
<span class="token function">some_function</span><span class="token punctuation">(</span><span class="token function">DO_SOMETHING</span><span class="token punctuation">(</span>some_func<span class="token punctuation">,</span> <span class="token number">3</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token function">DO_SOMETHING</span><span class="token punctuation">(</span>some_func<span class="token punctuation">,</span> <span class="token number">42</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre></div><p>Normally, a macro definition ends at the end of the line. If a macro needs to cover multiple lines, however, a backslash can be used at the end of a line to indicate this. This backslash must be the last character in the line, which indicates to the preprocessor that the following line should be concatenated onto the current line, treating them as a single line. This can be used multiple times in a row.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name">TEXT</span> <span class="token string">"I \
am \
many \
lines."</span></span>
<span class="token comment">// ...</span>
std<span class="token double-colon punctuation">::</span>cout <span class="token operator"><<</span> TEXT <span class="token operator"><<</span> std<span class="token double-colon punctuation">::</span>endl<span class="token punctuation">;</span> <span class="token comment">// Output: I am many lines.</span>
</code></pre></div><p>This is especially useful in complex function-like macros, which may need to cover multiple lines.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">CREATE_OUTPUT_AND_DELETE</span><span class="token expression"><span class="token punctuation">(</span>Str<span class="token punctuation">)</span> </span><span class="token punctuation">\</span>
<span class="token expression">std<span class="token double-colon punctuation">::</span>string<span class="token operator">*</span> tmp <span class="token operator">=</span> <span class="token keyword">new</span> std<span class="token double-colon punctuation">::</span><span class="token function">string</span><span class="token punctuation">(</span>Str<span class="token punctuation">)</span><span class="token punctuation">;</span> </span><span class="token punctuation">\</span>
<span class="token expression">std<span class="token double-colon punctuation">::</span>cout <span class="token operator"><<</span> <span class="token operator">*</span>tmp <span class="token operator"><<</span> std<span class="token double-colon punctuation">::</span>endl<span class="token punctuation">;</span> </span><span class="token punctuation">\</span>
<span class="token expression"><span class="token keyword">delete</span> tmp<span class="token punctuation">;</span></span></span>
<span class="token comment">// ...</span>
<span class="token function">CREATE_OUTPUT_AND_DELETE</span><span class="token punctuation">(</span><span class="token string">"There's no real need for this to use 'new'."</span><span class="token punctuation">)</span>
</code></pre></div><p>In the case of more complex function-like macros, it can be useful to give them their own scope to prevent possible name collisions or to cause objects to be destroyed at the end of the macro, similar to an actual function. A common idiom for this is <strong>do while 0</strong>, where the macro is enclosed in a <strong>do-while</strong> block. This block is generally <strong>not</strong> followed with a semicolon, allowing it to swallow a semicolon.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">DO_STUFF</span><span class="token expression"><span class="token punctuation">(</span>Type<span class="token punctuation">,</span> Param<span class="token punctuation">,</span> ReturnVar<span class="token punctuation">)</span> <span class="token keyword">do</span> <span class="token punctuation">{</span> </span><span class="token punctuation">\</span>
<span class="token expression">Type <span class="token function">temp</span><span class="token punctuation">(</span>some_setup_values<span class="token punctuation">)</span><span class="token punctuation">;</span> </span><span class="token punctuation">\</span>
<span class="token expression">ReturnVar <span class="token operator">=</span> temp<span class="token punctuation">.</span><span class="token function">process</span><span class="token punctuation">(</span>Param<span class="token punctuation">)</span><span class="token punctuation">;</span> </span><span class="token punctuation">\</span>
<span class="token expression"><span class="token punctuation">}</span> <span class="token keyword">while</span> <span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">)</span></span></span>
<span class="token keyword">int</span> x<span class="token punctuation">;</span>
<span class="token function">DO_STUFF</span><span class="token punctuation">(</span>MyClass<span class="token punctuation">,</span> <span class="token number">41153.7</span><span class="token punctuation">,</span> x<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// Compiler sees:</span>
<span class="token keyword">int</span> x<span class="token punctuation">;</span>
<span class="token keyword">do</span> <span class="token punctuation">{</span>
MyClass <span class="token function">temp</span><span class="token punctuation">(</span>some_setup_values<span class="token punctuation">)</span><span class="token punctuation">;</span>
x <span class="token operator">=</span> temp<span class="token punctuation">.</span><span class="token function">process</span><span class="token punctuation">(</span><span class="token number">41153.7</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span> <span class="token keyword">while</span> <span class="token punctuation">(</span><span class="token number">0</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre></div><p>There are also variadic macros; similarly to variadic functions, these take a variable number of arguments, and then expand them all in place of a special "Varargs" parameter, <code>__VA_ARGS__</code>.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">VARIADIC</span><span class="token expression"><span class="token punctuation">(</span>Param<span class="token punctuation">,</span> <span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">)</span> <span class="token function">Param</span><span class="token punctuation">(</span>__VA_ARGS__<span class="token punctuation">)</span></span></span>
<span class="token function">VARIADIC</span><span class="token punctuation">(</span>printf<span class="token punctuation">,</span> <span class="token string">"%d"</span><span class="token punctuation">,</span> <span class="token number">8</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// Compiler sees:</span>
<span class="token function">printf</span><span class="token punctuation">(</span><span class="token string">"%d"</span><span class="token punctuation">,</span> <span class="token number">8</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre></div><p>Note that during expansion, <code>__VA_ARGS__</code> can be placed anywhere in the definition, and will be expanded correctly.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">VARIADIC2</span><span class="token expression"><span class="token punctuation">(</span>POne<span class="token punctuation">,</span> PTwo<span class="token punctuation">,</span> PThree<span class="token punctuation">,</span> <span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">)</span> <span class="token function">POne</span><span class="token punctuation">(</span>PThree<span class="token punctuation">,</span> __VA_ARGS__<span class="token punctuation">,</span> PTwo<span class="token punctuation">)</span></span></span>
<span class="token function">VARIADIC2</span><span class="token punctuation">(</span>some_func<span class="token punctuation">,</span> <span class="token number">3</span><span class="token punctuation">,</span> <span class="token number">8</span><span class="token punctuation">,</span> <span class="token number">6</span><span class="token punctuation">,</span> <span class="token number">9</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// Compiler sees:</span>
<span class="token function">some_func</span><span class="token punctuation">(</span><span class="token number">8</span><span class="token punctuation">,</span> <span class="token number">6</span><span class="token punctuation">,</span> <span class="token number">9</span><span class="token punctuation">,</span> <span class="token number">3</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre></div><p>In the case of a zero-argument variadic parameter, different compilers will handle the trailing comma differently. Some compilers, such as Visual Studio, will silently swallow the comma without any special syntax. Other compilers, such as GCC, require you to place <code>##</code> immediately before <code>__VA_ARGS__</code>. Due to this, it is wise to conditionally define variadic macros when portability is a concern.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token comment">// In this example, COMPILER is a user-defined macro specifying the compiler being used.</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">if</span> <span class="token expression">COMPILER <span class="token operator">==</span> </span><span class="token string">"VS"</span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">VARIADIC3</span><span class="token expression"><span class="token punctuation">(</span>Name<span class="token punctuation">,</span> Param<span class="token punctuation">,</span> <span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">)</span> <span class="token function">Name</span><span class="token punctuation">(</span>Param<span class="token punctuation">,</span> __VA_ARGS__<span class="token punctuation">)</span></span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">elif</span> <span class="token expression">COMPILER <span class="token operator">==</span> </span><span class="token string">"GCC"</span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">VARIADIC3</span><span class="token expression"><span class="token punctuation">(</span>Name<span class="token punctuation">,</span> Param<span class="token punctuation">,</span> <span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">)</span> <span class="token function">Name</span><span class="token punctuation">(</span>Param<span class="token punctuation">,</span> </span><span class="token punctuation">##</span><span class="token expression">__VA_ARGS__<span class="token punctuation">)</span></span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">endif</span> <span class="token comment">/* COMPILER */</span></span>
</code></pre></div><h2 id="x-macros"><a href="#x-macros" class="header-anchor">#</a> X-macros</h2> <p>An idiomatic technique for generating repeating code structures at compile time.</p> <p>An X-macro consists of two parts: the list, and the execution of the list.</p> <p>Example:</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name">LIST</span> <span class="token punctuation">\</span>
<span class="token expression"><span class="token function">X</span><span class="token punctuation">(</span>dog<span class="token punctuation">)</span> </span><span class="token punctuation">\</span>
<span class="token expression"><span class="token function">X</span><span class="token punctuation">(</span>cat<span class="token punctuation">)</span> </span><span class="token punctuation">\</span>
<span class="token expression"><span class="token function">X</span><span class="token punctuation">(</span>racoon<span class="token punctuation">)</span></span></span>
<span class="token comment">// class Animal {</span>
<span class="token comment">// public:</span>
<span class="token comment">// void say();</span>
<span class="token comment">// };</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">X</span><span class="token expression"><span class="token punctuation">(</span>name<span class="token punctuation">)</span> Animal name<span class="token punctuation">;</span></span></span>
LIST
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">undef</span> <span class="token expression">X</span></span>
<span class="token keyword">int</span> <span class="token function">main</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">X</span><span class="token expression"><span class="token punctuation">(</span>name<span class="token punctuation">)</span> name<span class="token punctuation">.</span><span class="token function">say</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span></span>
LIST
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">undef</span> <span class="token expression">X</span></span>
<span class="token keyword">return</span> <span class="token number">0</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
</code></pre></div><p>which is expanded by the preprocessor into the following:</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code>Animal dog<span class="token punctuation">;</span>
Animal cat<span class="token punctuation">;</span>
Animal racoon<span class="token punctuation">;</span>
<span class="token keyword">int</span> <span class="token function">main</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
dog<span class="token punctuation">.</span><span class="token function">say</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
cat<span class="token punctuation">.</span><span class="token function">say</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
racoon<span class="token punctuation">.</span><span class="token function">say</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">return</span> <span class="token number">0</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
</code></pre></div><p>As lists become bigger (let's say, more than 100 elements), this technique helps to avoid excessive copy-pasting.</p> <p>Source: <a href="https://en.wikipedia.org/wiki/X_Macro" target="_blank" rel="noopener noreferrer">https://en.wikipedia.org/wiki/X_Macro<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></p> <p>See also: <a href="http://stackoverflow.com/documentation/c/628/x-macros" target="_blank" rel="noopener noreferrer">X-macros<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></p> <p>If defining a seamingly irrelevant <code>X</code> before using <code>LIST</code> is not to your liking, you can pass a macro name as an argument as well:</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">LIST</span><span class="token expression"><span class="token punctuation">(</span>MACRO<span class="token punctuation">)</span> </span><span class="token punctuation">\</span>
<span class="token expression"><span class="token function">MACRO</span><span class="token punctuation">(</span>dog<span class="token punctuation">)</span> </span><span class="token punctuation">\</span>
<span class="token expression"><span class="token function">MACRO</span><span class="token punctuation">(</span>cat<span class="token punctuation">)</span> </span><span class="token punctuation">\</span>
<span class="token expression"><span class="token function">MACRO</span><span class="token punctuation">(</span>racoon<span class="token punctuation">)</span></span></span>
</code></pre></div><p>Now, you explicitly specify which macro should be used when expanding the list, e.g.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">FORWARD_DECLARE_ANIMAL</span><span class="token expression"><span class="token punctuation">(</span>name<span class="token punctuation">)</span> Animal name<span class="token punctuation">;</span></span></span>
<span class="token function">LIST</span><span class="token punctuation">(</span>FORWARD_DECLARE_ANIMAL<span class="token punctuation">)</span>
</code></pre></div><p>If each invocation of the <code>MACRO</code> should take additional parameters - constant with respect to the list, variadic macros can be used</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token comment">//a walkaround for Visual studio</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">EXPAND</span><span class="token expression"><span class="token punctuation">(</span>x<span class="token punctuation">)</span> x</span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">LIST</span><span class="token expression"><span class="token punctuation">(</span>MACRO<span class="token punctuation">,</span> <span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">.</span><span class="token punctuation">)</span> </span><span class="token punctuation">\</span>
<span class="token expression"><span class="token function">EXPAND</span><span class="token punctuation">(</span><span class="token function">MACRO</span><span class="token punctuation">(</span>dog<span class="token punctuation">,</span> __VA_ARGS__<span class="token punctuation">)</span><span class="token punctuation">)</span> </span><span class="token punctuation">\</span>
<span class="token expression"><span class="token function">EXPAND</span><span class="token punctuation">(</span><span class="token function">MACRO</span><span class="token punctuation">(</span>cat<span class="token punctuation">,</span> __VA_ARGS__<span class="token punctuation">)</span><span class="token punctuation">)</span> </span><span class="token punctuation">\</span>
<span class="token expression"><span class="token function">EXPAND</span><span class="token punctuation">(</span><span class="token function">MACRO</span><span class="token punctuation">(</span>racoon<span class="token punctuation">,</span> __VA_ARGS__<span class="token punctuation">)</span><span class="token punctuation">)</span></span></span>
</code></pre></div><p>The first argument is supplied by the <code>LIST</code>, while the rest is provided by the user in the <code>LIST</code> invocation. For example:</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">FORWARD_DECLARE</span><span class="token expression"><span class="token punctuation">(</span>name<span class="token punctuation">,</span> type<span class="token punctuation">,</span> prefix<span class="token punctuation">)</span> type prefix</span><span class="token punctuation">##</span><span class="token expression">name<span class="token punctuation">;</span></span></span>
<span class="token function">LIST</span><span class="token punctuation">(</span>FORWARD_DECLARE<span class="token punctuation">,</span>Animal<span class="token punctuation">,</span>anim_<span class="token punctuation">)</span>
<span class="token function">LIST</span><span class="token punctuation">(</span>FORWARD_DECLARE<span class="token punctuation">,</span>Object<span class="token punctuation">,</span>obj_<span class="token punctuation">)</span>
</code></pre></div><p>will expand to</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code>Animal anim_dog<span class="token punctuation">;</span>
Animal anim_cat<span class="token punctuation">;</span>
Animal anim_racoon<span class="token punctuation">;</span>
Object obj_dog<span class="token punctuation">;</span>
Object obj_cat<span class="token punctuation">;</span>
Object obj_racoon<span class="token punctuation">;</span>
</code></pre></div><h2 id="preprocessor-error-messages"><a href="#preprocessor-error-messages" class="header-anchor">#</a> Preprocessor error messages</h2> <p>Compile errors can be generated using the preprocessor. This is useful for a number of reasons some of which include, notifying a user if they are on an unsupported platform or an unsupported compiler.</p> <p>e.g. Return Error if gcc version is 3.0.0 or earlier.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">if</span> <span class="token expression">__GNUC__ <span class="token operator"><</span> <span class="token number">3</span></span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">error</span> <span class="token string">"This code requires gcc > 3.0.0"</span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">endif</span></span>
</code></pre></div><p>e.g. Return Error if compiling on an Apple computer.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">ifdef</span> <span class="token expression">__APPLE__</span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">error</span> <span class="token string">"Apple products are not supported in this release"</span></span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">endif</span></span>
</code></pre></div><h2 id="predefined-macros"><a href="#predefined-macros" class="header-anchor">#</a> Predefined macros</h2> <p>Predefined macros are those that the compiler defines (in contrast to those user defines in the source file). Those macros must not be re-defined or undefined by user.</p> <p>The following macros are predefined by the C++ standard:</p> <ul><li><p><code>__LINE__</code> contains the line number of the line this macro is used on, and can be changed by the <code>#line</code> directive.</p></li> <li><p><code>__FILE__</code> contains the filename of the file this macro is used in, and can be changed by the <code>#line</code> directive.</p></li> <li><p><code>__DATE__</code> contains date (in <code>"Mmm dd yyyy"</code> format) of the file compilation, where <strong>Mmm</strong> is formatted as if obtained by a call to <code>std::asctime()</code>.</p></li> <li><p><code>__TIME__</code> contains time (in <code>"hh:mm:ss"</code> format) of the file compilation.</p></li> <li><p><code>__cplusplus</code> is defined by (conformant) C++ compilers while compiling C++ files. Its value is the standard version the compiler is <strong>fully</strong> conformant with, i.e. <code>199711L</code> for C++98 and C++03, <code>201103L</code> for C++11 and <code>201402L</code> for C++14 standard.</p></li> <li><p><code>__STDC_HOSTED__</code> is defined to <code>1</code> if the implementation is <strong>hosted</strong>, or <code>0</code> if it is <strong>freestanding</strong>.</p></li> <li><p><code>__STDCPP_DEFAULT_NEW_ALIGNMENT__</code> contains a <code>size_t</code> literal, which is the alignment used for a call to alignment-unaware <code>operator new</code>.</p></li></ul> <p>Additionally, the following macros are allowed to be predefined by implementations, and may or may not be present:</p> <ul><li><p><code>__STDC__</code> has implementation-dependent meaning, and is usually defined only when compiling a file as C, to signify full C standard compliance. (Or never, if the compiler decides not to support this macro.)</p></li> <li><p><code>__STDC_VERSION__</code> has implementation-dependent meaning, and its value is usually the C version, similarly to how <code>__cplusplus</code> is the C++ version. (Or is not even defined, if the compiler decides not to support this macro.)</p></li> <li><p><code>__STDC_MB_MIGHT_NEQ_WC__</code> is defined to <code>1</code>, if values of the narrow encoding of the basic character set might not be equal to the values of their wide counterparts (e.g. if <code>(uintmax_t)'x' != (uintmax_t)L'x'</code>)</p></li> <li><p><code>__STDC_ISO_10646__</code> is defined if <code>wchar_t</code> is encoded as Unicode, and expands to an integer constant in the form <code>yyyymmL</code>, indicating the latest Unicode revision supported.</p></li> <li><p><code>__STDCPP_STRICT_POINTER_SAFETY__</code> is defined to <code>1</code>, if the implementation has <strong>strict pointer safety</strong> (otherwise it has <strong>relaxed pointer safety</strong>)</p></li> <li><p><code>__STDCPP_THREADS__</code> is defined to <code>1</code>, if the program can have more than one thread of execution (applicable to <strong>freestanding implementation</strong> — <strong>hosted implementations</strong> can always have more than one thread)</p></li></ul> <p>It is also worth mentioning <code>__func__</code>, which is not an macro, but a predefined function-local variable. It contains the name of the function it is used in, as a static character array in an implementation-defined format.</p> <p>On top of those standard predefined macros, compilers can have their own set of predefined macros. One must refer to the compiler documentation to learn those. E.g.:</p> <ul><li><a href="https://gcc.gnu.org/onlinedocs/cpp/Predefined-Macros.html" target="_blank" rel="noopener noreferrer">gcc<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></li> <li><a href="https://msdn.microsoft.com/en-us/library/b0084kay.aspx#Anchor_2" target="_blank" rel="noopener noreferrer">Microsoft Visual C++<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></li> <li><a href="http://clang.llvm.org/docs/LanguageExtensions.html#builtin-macros" target="_blank" rel="noopener noreferrer">clang<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></li> <li><a href="https://software.intel.com/en-us/node/514528" target="_blank" rel="noopener noreferrer">Intel C++ Compiler<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></li></ul> <p>Some of the macros are just to query support of some feature:</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">ifdef</span> <span class="token expression">__cplusplus </span><span class="token comment">// if compiled by C++ compiler</span></span>
<span class="token keyword">extern</span> <span class="token string">"C"</span><span class="token punctuation">{</span> <span class="token comment">// C code has to be decorated</span>
<span class="token comment">// C library header declarations here</span>
<span class="token punctuation">}</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">endif</span></span>
</code></pre></div><p>Others are very useful for debugging:</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token keyword">bool</span> success <span class="token operator">=</span> <span class="token function">doSomething</span><span class="token punctuation">(</span> <span class="token comment">/*some arguments*/</span> <span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token keyword">if</span><span class="token punctuation">(</span> <span class="token operator">!</span>success <span class="token punctuation">)</span><span class="token punctuation">{</span>
std<span class="token double-colon punctuation">::</span>cerr <span class="token operator"><<</span> <span class="token string">"ERROR: doSomething() failed on line "</span> <span class="token operator"><<</span> <span class="token constant">__LINE__</span> <span class="token operator">-</span> <span class="token number">2</span>
<span class="token operator"><<</span> <span class="token string">" in function "</span> <span class="token operator"><<</span> <span class="token constant">__func__</span> <span class="token operator"><<</span> <span class="token string">"()"</span>
<span class="token operator"><<</span> <span class="token string">" in file "</span> <span class="token operator"><<</span> <span class="token constant">__FILE__</span>
<span class="token operator"><<</span> std<span class="token double-colon punctuation">::</span>endl<span class="token punctuation">;</span>
<span class="token punctuation">}</span>
</code></pre></div><p>And others for trivial version control:</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token keyword">int</span> <span class="token function">main</span><span class="token punctuation">(</span> <span class="token keyword">int</span> argc<span class="token punctuation">,</span> <span class="token keyword">char</span> <span class="token operator">*</span>argv<span class="token punctuation">[</span><span class="token punctuation">]</span> <span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token keyword">if</span><span class="token punctuation">(</span> argc <span class="token operator">==</span> <span class="token number">2</span> <span class="token operator">&&</span> std<span class="token double-colon punctuation">::</span><span class="token function">string</span><span class="token punctuation">(</span> argv<span class="token punctuation">[</span><span class="token number">1</span><span class="token punctuation">]</span> <span class="token punctuation">)</span> <span class="token operator">==</span> <span class="token string">"-v"</span> <span class="token punctuation">)</span><span class="token punctuation">{</span>
std<span class="token double-colon punctuation">::</span>cout <span class="token operator"><<</span> <span class="token string">"Hello World program\n"</span>
<span class="token operator"><<</span> <span class="token string">"v 1.1\n"</span> <span class="token comment">// I have to remember to update this manually</span>
<span class="token operator"><<</span> <span class="token string">"compiled: "</span> <span class="token operator"><<</span> <span class="token constant">__DATE__</span> <span class="token operator"><<</span> <span class="token string">' '</span> <span class="token operator"><<</span> <span class="token constant">__TIME__</span> <span class="token comment">// this updates automagically</span>
<span class="token operator"><<</span> std<span class="token double-colon punctuation">::</span>endl<span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token keyword">else</span><span class="token punctuation">{</span>
std<span class="token double-colon punctuation">::</span>cout <span class="token operator"><<</span> <span class="token string">"Hello World!\n"</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token punctuation">}</span>
</code></pre></div><h2 id="pragma-once"><a href="#pragma-once" class="header-anchor">#</a> #pragma once</h2> <p><a href="https://en.wikipedia.org/wiki/Pragma_once#Portability" target="_blank" rel="noopener noreferrer">Most, but not all, C++ implementations<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> support the <code>#pragma once</code> directive which ensures the file is only included once within a single compilation. It is not part of any ISO C++ standard. For example:</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token comment">// Foo.h</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">pragma</span> <span class="token expression">once</span></span>
<span class="token keyword">class</span> <span class="token class-name">Foo</span>
<span class="token punctuation">{</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>
</code></pre></div><p>While <code>#pragma once</code> avoids some problems associated with <a href="http://stackoverflow.com/documentation/c%2b%2b/1098/preprocessor/3525/include-guards" target="_blank" rel="noopener noreferrer">include guards<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>, a <code>#pragma</code> - by definition in the standards - is inherently a compiler-specific hook, and will be silently ignored by compilers that don't support it. Projects which use <code>#pragma once</code> must be modified to be standard-compliant.</p> <p>With some compilers - particularly those that employ <a href="https://en.wikipedia.org/wiki/Precompiled_header" target="_blank" rel="noopener noreferrer">precompiled headers<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - <code>#pragma once</code> can result in a considerable speedup of the compilation process. Similarly, some preprocessors achieve speedup of compilation by tracking which headers have employed include guards. The net benefit, when both <code>#pragma once</code> and include guards are employed, depends on the implementation and can be either an increase or decrease of compilation times.</p> <p><code>#pragma once</code> combined with <a href="http://stackoverflow.com/documentation/c%2b%2b/1098/preprocessor/3525/include-guards" target="_blank" rel="noopener noreferrer">include guards<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> was the recommended layout for header files when writing MFC based applications on windows, and was generated by Visual Studio’s <code>add class</code>, <code>add dialog</code>, <code>add windows</code> wizards. Hence it is very common to find them combined in C++ Windows Applicants.</p> <h2 id="preprocessor-operators"><a href="#preprocessor-operators" class="header-anchor">#</a> Preprocessor Operators</h2> <p><code>#</code> operator or stringizing operator is used to convert a Macro parameter to a string literal. It can only be used with the Macros having arguments.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token comment">// preprocessor will convert the parameter x to the string literal x</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">PRINT</span><span class="token expression"><span class="token punctuation">(</span>x<span class="token punctuation">)</span> <span class="token function">printf</span><span class="token punctuation">(</span>#x </span><span class="token string">"\n"</span><span class="token expression"><span class="token punctuation">)</span></span></span>
<span class="token function">PRINT</span><span class="token punctuation">(</span>This line will be converted to string by preprocessor<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// Compiler sees</span>
<span class="token function">printf</span><span class="token punctuation">(</span><span class="token string">"This line will be converted to string by preprocessor"</span><span class="token string">"\n"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre></div><p>Compiler concatenate two strings and the final <code>printf()</code> argument will be a string literal with newline character at its end.</p> <p>Preprocessor will ignore the spaces before or after the macro argument. So below print statement will give us the same result.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token function">PRINT</span><span class="token punctuation">(</span> This line will be converted to string by preprocessor <span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre></div><p>If the parameter of the string literal requires an escape sequence like before a double quote() it will automatically be inserted by the preprocessor.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token function">PRINT</span><span class="token punctuation">(</span>This <span class="token string">"line"</span> will be converted to <span class="token string">"string"</span> by preprocessor<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">// Compiler sees</span>
<span class="token function">printf</span><span class="token punctuation">(</span><span class="token string">"This \"line\" will be converted to \"string\" by preprocessor"</span><span class="token string">"\n"</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre></div><p><code>##</code> operator or Token pasting operator is used to concatenate two parameters or tokens of a Macro.</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code><span class="token comment">// preprocessor will combine the variable and the x</span>
<span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">define</span> <span class="token macro-name function">PRINT</span><span class="token expression"><span class="token punctuation">(</span>x<span class="token punctuation">)</span> <span class="token function">printf</span><span class="token punctuation">(</span></span><span class="token string">"variable"</span> <span class="token expression"><span class="token macro property"><span class="token directive-hash">#</span><span class="token directive keyword">x</span> </span></span><span class="token string">" = %d"</span><span class="token expression"><span class="token punctuation">,</span> variable</span><span class="token punctuation">##</span><span class="token expression">x<span class="token punctuation">)</span></span></span>
<span class="token keyword">int</span> variableY <span class="token operator">=</span> <span class="token number">15</span><span class="token punctuation">;</span>
<span class="token function">PRINT</span><span class="token punctuation">(</span>Y<span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token comment">//compiler sees</span>
<span class="token function">printf</span><span class="token punctuation">(</span><span class="token string">"variable"</span><span class="token string">"Y"</span><span class="token string">" = %d"</span><span class="token punctuation">,</span> variableY<span class="token punctuation">)</span><span class="token punctuation">;</span>
</code></pre></div><p>and the final output will be</p> <div class="language-cpp extra-class"><pre class="language-cpp"><code>variableY <span class="token operator">=</span> <span class="token number">15</span>
</code></pre></div><h4 id="remarks"><a href="#remarks" class="header-anchor">#</a> Remarks</h4> <p>Preprocessor statements are executed before your source files are handed to the compiler. They are capable of very low level conditional logic. Since preprocessor constructs (e.g. object-like macros) aren't typed like normal functions (the preprocessing step happens before compilation) the compiler cannot enforce type checks, they should therefore be carefully used.</p></div> <footer class="page-edit"><div class="edit-link"><a href="https://github.com/devtut/generate/edit/master/docs/cpp/preprocessor.md" target="_blank" rel="noopener noreferrer">Edit this page on GitHub</a> <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></div> <!----></footer> <div class="page-nav"><p class="inner"><span class="prev">
←
<a href="/cpp/value-categories.html" class="prev">
Value Categories
</a></span> <span class="next"><a href="/cpp/data-structures-in-c.html">
Data Structures in C++
</a>
→
</span></p></div> </main></div><div class="global-ui"><!----></div></div>
<script src="/assets/js/app.1779e102.js" defer></script><script src="/assets/js/3.2cfa8016.js" defer></script><script src="/assets/js/694.b4d61745.js" defer></script>
</body>
</html>