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
|
The combination of the predefined symbol ti(__cplusplus) and the
possibility to define ti(extern "C") functions offers the ability to
create header files for both bf(C) and bf(C++). Such a header file might,
e.g., declare a group of functions which are to be used in both bf(C) and
bf(C++) programs.
The setup of such a header file is as follows:
verb( #ifdef __cplusplus
extern "C"
{
#endif
/* declaration of C-data and functions are inserted here. E.g., */
void *xmalloc(int size);
#ifdef __cplusplus
}
#endif)
Using this setup, a normal bf(C) header file is enclosed by tt(extern "C")
tt({) which occurs near the top of the file and by tt(}), which occurs near
the bottom of the file. The ti(#ifdef) directives test for the type of the
compilation: bf(C) or bf(C++). The `standard' bf(C) header files, such as
ti(stdio.h), are built in this manner and are therefore usable for both bf(C)
and bf(C++).
In addition bf(C++) headers should support emi(include guard)em(s).
In bf(C++) it is usually undesirable to include the same header file twice in
the same source file. Such multiple inclusions can easily be avoided by
including an ti(#ifndef) directive in the header file. For example:
verb( #ifndef MYHEADER_H_
#define MYHEADER_H_
// declarations of the header file is inserted here,
// using #ifdef __cplusplus etc. directives
#endif)
When this file is initially scanned by the preprocessor, the symbol
tt(MYHEADER_H_) is not yet defined. The tt(#ifndef) condition succeeds and all
declarations are scanned. In addition, the symbol tt(MYHEADER_H_) is defined.
When this file is scanned next while compiling the same source file,
the symbol tt(MYHEADER_H_) has been defined and consequently all information
between the tt(#ifndef) and tt(#endif) directives is skipped by the compiler.
In this context the symbol name tt(MYHEADER_H_) serves only for
recognition purposes. E.g., the name of the header file can be used for this
purpose, in capitals, with an underscore character instead of a dot.
Apart from all this, the custom has evolved to give bf(C) header files the
extension ti(.h), and to give tt(C++) header files em(no) extension. For
example, the standard em(iostreams) tt(cin, cout) and tt(cerr) are available
after including the header file ti(iostream), rather
than ti(iostream.h). In the Annotations this convention is used
with the standard bf(C++) header files, but not necessarily everywhere else.
There is more to be said about header files. Section ref(CLASSHEADER) provides
an in-depth discussion of the preferred organization of bf(C++) header files.
In addition, starting with the C2a standard em(modules) are available
resulting in a somewhat more efficient way of handling declarations than
offered by the traditional header files.
Currently, the annotations() very briefly covers em(modules) (cf. section
ref(MODULES)).
|
