aboutsummaryrefslogtreecommitdiffstats
path: root/docs/source/lang/cpp/define.rst
blob: 677390d40e2b6ad2298e2634c8682914242db489 (plain)
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
.. highlight:: cpp

.. _lang-define:

``#define``
===========

``#define`` is a useful C and C++ feature that allows the programmer
to give a name to a constant value before the program is compiled.
The compiler will replace references to these constants with the
defined value at compile time.

This can have some unwanted side effects.  In general, the :ref:`const
<lang-const>` keyword is preferred for defining constants.


Syntax
------

The following line would define the name ``MY_CONSTANT`` to have value
``value``::

    #define MY_CONSTANT value

Note that the ``#`` is necessary.  It is usually good style for the
name to be capitalized, although this is not required.

There is no semicolon after the #define statement. If you include one,
the compiler will likely throw cryptic errors in unrelated places.
That is, **don't do this**::

    // DON'T DO THIS! THE SEMICOLON SHOULDN'T BE THERE!
    #define NAME value;

Similarly, including an equal sign after the ``#define`` line will
also generate a cryptic compiler error further down the page.  That
is, **don't do this, either**::

    // DON'T DO THIS, EITHER! THE EQUALS SIGN SHOULDN'T BE THERE!
    #define NAME = value

Example
-------

::

    #define LED_PIN 13
    // The compiler will replace any mention of LED_PIN with
    // the value 3 at compile time.

See Also
--------
-  :ref:`const <lang-const>`


.. include:: cc-attribution.txt