kuyper@wizard.net (James Kuyper) wrote in message news:<8b42afac.0404130714.1712b2ed@posting.google.com>...
> In section 16.2 it explains that the preprocessing directive
>
> #include "header-name"
>
> brings into a translation unit the contents of either a header or a
> source file. On the other hand, the line
>
> #include <header-name>
>
> is described as working only for headers.

That was exactly my interpretation. But it seems that this distinction
wasn't completely conscious. We discussed it briefly on the boost
list:

http://aspn.activestate.com/ASPN/Mail/Message/boost/1288726

and the discussion led to core issue 370.

--
Genny.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

hattons@globalsymmetry.com ("Steven T. Hatton") wrote in message news:<5L6dnYgUJ41X9ODd4p2dnA@speakeasy.net>...
> Jack Klein wrote:
>
> > Headers are completely defined in section 17.4.1.2 of the standard.
>
> That seems less than clear to me. Use of the term /header/ has been common
> in the C and thence the C++ community from the beginning, and has a fairly
> clear connotation that does not correspond to what is hinted at by the
> reference to 17.4.1.2 in Clause 2 paragraph 1. If the intent is to
> define /header/ to exclusively refer to headers in the Standard Library,
> needs to be stated clearly, if it is to be understood.

According to ISO rules for writing standards, the fact that "header"
appears in italics in 17.4.1.2p1 indicates that this paragraph is to
be taken as defining the term "header". That paragraph says:

"The elements of the C++ Standard Library are declared or defined (as
appropriate) in a _header_."

Interpreted as a definition of "header", that paragraph clearly
restricts the term to things that declare or define elements of the
C++ Standard Library. Since user code cannot contain such declarations
or definitions without violating 17.4.3.1, a header can only be
provided by the implementation.

> This is what Stroustrup provides as a definition of /header/.
>
> http://www.research.att.com/~bs/glossary.html#Gheader
> header - see header file
>
> header file - file holding declarations used in more than one translation
> unit. Thus, a header file acts as an interface between separately compiled
> parts of a program. A header file often contains inline function
> definitions, const definitions, enumerations, and template definitions, but
> it cannot be #included from for than one source file if it contain
> non-inline function definitions or variable definitions. TC++PL 2.4.1,
> 9.2.1. D&E 2.5, 11.3.3.

Note that Stroustrup is providing the ordinary definition of a "header
file". He is not providing the standard's definition of a "header".
Where the Standard provides a definition of a term, that definition is
the one that must apply within the context of the Standard, even if
the Standard's definition is quite different from the more widely
familiar meaning of the term.

..
> Interestingly, any sequence of the form /#include "characters"/ or /#include
> <characters>/ is called a /header-name/. ...

Not quite. Such a sequence is called a "#include pre-processing
directive". The header-name is the sub-sequence between the "" or <>
delimiters.

> ... For the most part, the standard is
> consistent with the suggestion that "header" is synonymous with "standard
> header", but there seem to be a few places where it deviates from this
> usage.

Could you identify those places?

> ... Also, if I take the standard to mean that "header" is synonymous
> with "standard header" then all sequences of the form
> #include /<characters>/ used for 3rd-party libraries are in violation of
> the standard. (c.f. 16.2)

To be precise, the behavior of code containing such constructs is
implicitly undefined, since the standard doesn't define what happens
when the header-name isn't the name of a header. Therefore, there's no
wrong way to handle such code.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Michiel.Salters@logicacmg.com (Michiel Salters) wrote in message news:<fcaee77e.0404150904.7718a203@posting.google.com>...
> hattons@globalsymmetry.com ("Steven T. Hatton") wrote in message news:<5L6dnYgUJ41X9ODd4p2dnA@speakeasy.net>...
..
> > Where does the standard specify the use of a sequence of the form /#include
> > <characters>/ that is not a header?
>
> 2.8/1 and 16.2

Not quite. If you check closely, #include <> is to be used only for
headers; #include "" can be used for both headers and source code
files.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

James Kuyper wrote:
> hattons@globalsymmetry.com ("Steven T. Hatton") wrote in message news:<5L6dnYgUJ41X9ODd4p2dnA@speakeasy.net>...
>
>>Jack Klein wrote:
>>
>>
>>>Headers are completely defined in section 17.4.1.2 of the standard.
>>
>>That seems less than clear to me. Use of the term /header/ has been common
>>in the C and thence the C++ community from the beginning, and has a fairly
>>clear connotation that does not correspond to what is hinted at by the
>>reference to 17.4.1.2 in Clause 2 paragraph 1. If the intent is to
>>define /header/ to exclusively refer to headers in the Standard Library,
>>needs to be stated clearly, if it is to be understood.

   Part of the problem is that you can use "#include" to include
things that clearly aren't headers.  This is legal:

   double bigfn(float x)
   {
#include "textoffunctionx.cpp"
   }

Program-generated source code is sometimes inserted that way.

   There are occasional suggestions that something be provided
to replace "#include", with the idea that support for precompiled
headers might be improved.  One such idea is to write

   using "filename";

to indicate the use of a "header".  Since "using" is only allowed
in a declaration context, such header files are presumably limited to
text meaningful in a declaration context.  This excludes inline code
snippets.

   There's also the hope that "using" might deal with the "include only
once" problem.  Neither "guards" nor "#pragma once" are good solutions.

    It would be nice, although not mandatory, that "using" have a more
modern search strategy than "include".  Perl searches entire subtrees for
included files; the C++ preprocessor does not.  This reflects the
era in which the systems were developed.  I'd suggest Perl-type searching
for "using".  This would tend to reduce the appearance of explicit
directory structure in program text.

    To handle ambiguous cases, if a partial path is specified, such as

 using "dirname/filename";

that should be interpreted as a requirement that "dirname/filename" must
be found somewhere in the "subtree", (or whatever other construct the header storage
system provides that maps to that concept).  This provides an escape
mechanism for projects which have multiple filenames in the same subtree.

    Inclusion by namespace would be even better, but that's probably too
radical.

    John Nagle
    Animats

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

In article <3cIfc.51826$75.2848@newssvr25.news.prodigy.com>,
 nagle@animats.com (John Nagle) wrote:

>  Perl searches entire subtrees for
> included files; the C++ preprocessor does not.

I hadve always understood the way the preprocessor searches for includes
to be entirely implementation defined, since it depends on the
filesystem.  Expecting '/' in the include name to be parsed as a
directory separator (rather than a normal character that can be present
in a filename) is certainly filesystem dependent, however common it now
is.  Does the implementation you are using really not have an option to
search subtrees?

Best wishes,
Matthew Collett

--
Those who assert that the mathematical sciences have nothing to say
about the good or the beautiful are mistaken.          -- Aristotle

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

nagle@animats.com (John Nagle) writes:

> James Kuyper wrote:
>> hattons@globalsymmetry.com ("Steven T. Hatton") wrote in message news:<5L6dnYgUJ41X9ODd4p2dnA@speakeasy.net>...
>>
>>>Jack Klein wrote:
>>>
>>>
>>>>Headers are completely defined in section 17.4.1.2 of the standard.
>>>
>>>That seems less than clear to me. Use of the term /header/ has been common
>>>in the C and thence the C++ community from the beginning, and has a fairly
>>>clear connotation that does not correspond to what is hinted at by the
>>>reference to 17.4.1.2 in Clause 2 paragraph 1. If the intent is to
>>>define /header/ to exclusively refer to headers in the Standard Library,
>>>needs to be stated clearly, if it is to be understood.
>
>    Part of the problem is that you can use "#include" to include
> things that clearly aren't headers.  This is legal:
>
>    double bigfn(float x)
>    {
> #include "textoffunctionx.cpp"
>    }
>    Program-generated source code is sometimes inserted that way.
>
>    There are occasional suggestions that something be provided
> to replace "#include", with the idea that support for precompiled
> headers might be improved.  One such idea is to write
>
>    using "filename";
>
> to indicate the use of a "header".  Since "using" is only allowed
> in a declaration context, such header files are presumably limited to
> text meaningful in a declaration context.  This excludes inline code
> snippets.   There's also the hope that "using" might deal with the
> "include only
> once" problem.  Neither "guards" nor "#pragma once" are good
> solutions.


class foo
{
   using "text_of_class_foo.hpp";
};

Which is to say, a 'using "filename"; construct would need new rules,
    specific to that construct, for where its use would be legal. The
    existing rules for where using can be use IMO would not suffice.

>
>     It would be nice, although not mandatory, that "using" have a more
> modern search strategy than "include".  Perl searches entire subtrees for
> included files; the C++ preprocessor does not.
[snip]

This is implementation dependent. I am fairly sure at least some
    versions of metrowerks search entire subtrees. And I am sure the
    standard allows this. More, every compiler I've ever used allows
    comand-line flags to influence where the preprocessor searches
    for #included files.

I think an implementor could keep all standard headers on their
    public ftp or web site, require that the user have an
    internet connection, and then provide an implementation which
    fetched standard headers from over the internet. :-) Whether or
    not this would a 'good' idea is an excercise for the reader.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

James Kuyper wrote:

> hattons@globalsymmetry.com ("Steven T. Hatton") wrote in message

> According to ISO rules for writing standards, the fact that "header"
> appears in italics in 17.4.1.2p1 indicates that this paragraph is to
> be taken as defining the term "header". That paragraph says:
>
> "The elements of the C++ Standard Library are declared or defined (as
> appropriate) in a _header_."

I don't know if it's an ISO rule, but this is from ISO/IEC 14882:2003(E)
1.3:

"Terms that are used only in a small portion of this International Standard
are defined where they are use and italicized where they are defined."

Which could be argued either way as to whether it supports the
interpretation of 17.4.1.2p1 as a definition.

> Interpreted as a definition of "header", that paragraph clearly
> restricts the term to things that declare or define elements of the
> C++ Standard Library.

> "The laws [elements] of the  US of A [C++ Standard Library] are declared
or defined (as appropriate) in a /written documents/ [_header_]."

That doesn't define /written document/.

> Note that Stroustrup is providing the ordinary definition of a "header
> file". He is not providing the standard's definition of a "header".
> Where the Standard provides a definition of a term, that definition is
> the one that must apply within the context of the Standard, even if
> the Standard's definition is quite different from the more widely
> familiar meaning of the term.

The sentence you referenced is not a definition.  At best it's a hint.

> Not quite. Such a sequence is called a "#include pre-processing
> directive". The header-name is the sub-sequence between the "" or <>
> delimiters.

To be completely pedantic, /# include pp-tokens new-line/ constitudes
a /control-line/ which is a *Preprocessor directive*.
The following are described as "header-name:"

/<h-char-sequence>/
/"q-char-sequence"/


--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

nagle@animats.com (John Nagle) wrote in message news:<3cIfc.51826$75.2848@newssvr25.news.prodigy.com>...
..
>     It would be nice, although not mandatory, that "using" have a more
> modern search strategy than "include".  Perl searches entire subtrees for
> included files; the C++ preprocessor does not.

Your assertion about Perl didn't sound right, so I've checked the perl
source, its documentation, and actually tried it and can say with some
confidence that Perl does *NOT* behave the way you describe.  If I
write the perl line
        require "foo.pl";
perl will search for a file "foo.pl" in the exact list of directories
listed in the include path without searching recursively below them.

There are two additional behaviors that may have thrown you off:
1) when building a filename to search for, perl will usually replace
   "::" with the path separator and will add a .pm suffix if no suffix
   is present.  (c.f. the perlfunc manpage's section on "require")
2) when you add a directory to perl's file search path, perl will
   also add a platform-specific subdirectory to the search path if
   it exists.  (c.f., "perldoc lib")

So, it appears to me that perl does *not* serve as an example of a
program that searches entire subtrees when looking for include files,
though it does suggest some ideas for an alternative include system,
such as the automatic generation of filenames from class names.

..
> I'd suggest Perl-type searching
> for "using".  This would tend to reduce the appearance of explicit
> directory structure in program text.

In my experience, the problem you describe is best handled by style
guidelines backed by management and having a build system that makes
it easy to 'declare' inter-module dependencies.  That is, fix the
annoyance that led the programmer to write the bad line in the first
place, then treat it like every other case of "bad style".

Philip Guenther

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

hattons@globalsymmetry.com ("Steven T. Hatton") wrote in message news:<_P-dnTGVor0yuhzdRVn-uQ@speakeasy.net>...
> James Kuyper wrote:
>
> > hattons@globalsymmetry.com ("Steven T. Hatton") wrote in message
>
> > According to ISO rules for writing standards, the fact that "header"
> > appears in italics in 17.4.1.2p1 indicates that this paragraph is to
> > be taken as defining the term "header". That paragraph says:
> >
> > "The elements of the C++ Standard Library are declared or defined (as
> > appropriate) in a _header_."
>
> I don't know if it's an ISO rule, but this is from ISO/IEC 14882:2003(E)
> 1.3:
>
> "Terms that are used only in a small portion of this International Standard
> are defined where they are use and italicized where they are defined."
>
> Which could be argued either way as to whether it supports the
> interpretation of 17.4.1.2p1 as a definition.

I don't think so. If you think it can be argued as not supporting that
interpretation, you should provide the argument. To me it seems quite
clear that 17.4.1.2p1 is one of many examples of defintions provided
in the manner described in 1.3.

> > Interpreted as a definition of "header", that paragraph clearly
> > restricts the term to things that declare or define elements of the
> > C++ Standard Library.
>
> > "The laws [elements] of the  US of A [C++ Standard Library] are declared
> or defined (as appropriate) in a /written documents/ [_header_]."
>
> That doesn't define /written document/.

It would if it occurred in a ISO standard, with the term "written
documents" italicized. As such, it would define "written documents" in
a manner quite different from the ordinary English usage of that term.
Standardese isn't ordinary English, and you can make serious mistakes
trying to interpret it as if it were.

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

Jack Klein wrote:

> Headers are completely defined in section 17.4.1.2 of the standard.

That seems less than clear to me. Use of the term /header/ has been common
in the C and thence the C++ community from the beginning, and has a fairly
clear connotation that does not correspond to what is hinted at by the
reference to 17.4.1.2 in Clause 2 paragraph 1. If the intent is to
define /header/ to exclusively refer to headers in the Standard Library,
needs to be stated clearly, if it is to be understood.

This is what Stroustrup provides as a definition of /header/.

http://www.research.att.com/~bs/glossary.html#Gheader
header - see header file

header file - file holding declarations used in more than one translation
unit. Thus, a header file acts as an interface between separately compiled
parts of a program. A header file often contains inline function
definitions, const definitions, enumerations, and template definitions, but
it cannot be #included from for than one source file if it contain
non-inline function definitions or variable definitions. TC++PL 2.4.1,
9.2.1. D&E 2.5, 11.3.3.

> Standard headers are referenced in a program by a preprocessor
> directive of the form:
>
> #include <header-name>

[snip]

> Any other sequence of characters that is in a #include <characters>

Where does the standard specify the use of a sequence of the form /#include
<characters>/ that is not a header?

> or
> #include "characters" is, as far as the standard is concerned, the
> valid name of a file for the host platform.  The contents of the
> character sequence is completely implementation-defined and most
> particularly is not a string literal, even if delimited with quotation
> marks.

Interestingly, any sequence of the form /#include "characters"/ or /#include
<characters>/ is called a /header-name/. For the most part, the standard is
consistent with the suggestion that "header" is synonymous with "standard
header", but there seem to be a few places where it deviates from this
usage. Also, if I take the standard to mean that "header" is synonymous
with "standard header" then all sequences of the form
#include /<characters>/ used for 3rd-party libraries are in violation of
the standard. (c.f. 16.2)


Annex C 1.2 Clause 3.5 has the following sentence: "This feature allows the
user to put const objects in header files that are included in many
compilation units."

I will grant the annex is informative, and not proscriptive.  Nonetheless,
it suggests the definition is not as clearly defined as it should be.
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

hattons@globalsymmetry.com ("Steven T. Hatton") wrote in message news:<5L6dnYgUJ41X9ODd4p2dnA@speakeasy.net>...
> Jack Klein wrote:
>
> > Headers are completely defined in section 17.4.1.2 of the standard.
>
> That seems less than clear to me. Use of the term /header/ has been common
> in the C and thence the C++ community from the beginning, and has a fairly
> clear connotation that does not correspond to what is hinted at by the
> reference to 17.4.1.2 in Clause 2 paragraph 1. If the intent is to
> define /header/ to exclusively refer to headers in the Standard Library,
> needs to be stated clearly, if it is to be understood.

The term byte is even more widely understood to mean 8 bits, yet it
doesn't in the standard. Sorry, but that's how things are in Standardese.
It's a language which looks like English, but it redefines some words.

> This is what Stroustrup provides as a definition of /header/.
>
> http://www.research.att.com/~bs/glossary.html#Gheader
> header - see header file
>
> header file - file holding declarations used in more than one translation
> unit. Thus, a header file acts as an interface between separately compiled
> parts of a program. A header file often contains inline function
> definitions, const definitions, enumerations, and template definitions, but
> it cannot be #included from for than one source file if it contain
> non-inline function definitions or variable definitions. TC++PL 2.4.1,
> 9.2.1. D&E 2.5, 11.3.3.

Well, that is trying to be helpful, not precise. Those goals are at odds.

> > Standard headers are referenced in a program by a preprocessor
> > directive of the form:
> >
> > #include <header-name>
>
> [snip]
>
> > Any other sequence of characters that is in a #include <characters>
>
> Where does the standard specify the use of a sequence of the form /#include
> <characters>/ that is not a header?

2.8/1 and 16.2
The point is that the standard says nothing about the mechanism used
by the implementation for headers. In particular, an implementation
may decide that the source file x.h also is an header, while x.cpp is
just a source file. As a result, x.h could be included as an header
using the "#include <x.h>" form or as a source file "#include "x.h"",
while x.cpp could only be included using the "#include "x.cpp""
form.

The result of <x.h> and "x.h" are identical, by 16.2/2 and /3, because
the same contents are included, but the process is slightly diferent.
Effectively, you have an header x.h and a source file x.h
( still for this particular implementation, where source files can also
  be headers  )

> > or
> > #include "characters" is, as far as the standard is concerned, the
> > valid name of a file for the host platform.  The contents of the
> > character sequence is completely implementation-defined and most
> > particularly is not a string literal, even if delimited with quotation
> > marks.
>
> Interestingly, any sequence of the form /#include "characters"/ or /#include
> <characters>/ is called a /header-name/. For the most part, the standard is
> consistent with the suggestion that "header" is synonymous with "standard
> header", but there seem to be a few places where it deviates from this
> usage. Also, if I take the standard to mean that "header" is synonymous
> with "standard header" then all sequences of the form
> #include /<characters>/ used for 3rd-party libraries are in violation of
> the standard. (c.f. 16.2)

That is the result of your incorrect assumption, but the standard doesn't
mandate this. I can imagine implementations where the < > form refers to
pre-compiled headers. In such places, a 3rd party library which wanted
the < .h> form would need to precompile its headers - all implementation
defined, but certainly legal with this standard.

>
> Annex C 1.2 Clause 3.5 has the following sentence: "This feature allows the
> user to put const objects in header files that are included in many
> compilation units."
>
> I will grant the annex is informative, and not proscriptive.  Nonetheless,
> it suggests the definition is not as clearly defined as it should be.

Good point, this may need a touch-up. IIRC, a Defect Report in comp.std.c++
is still the current process. Do you want to do this yourself (see FAQ),
or should I do it, and if the latter, should I put your name in it?

Regards,
Michiel Salters

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

I've been trying to get a clear understanding of what is meant by the
term /header/ in ISO/IEC14882:2003(E).  The term is often used in
conjunction with the term /source file/.  Sometimes it is suggested that a
header could be a source file.  Likewise it is sometimes suggested a header
need not be a source file. The one commonality all headers seem to share is
that they are #included in a translation unit.

It would also appear that a source file which is distinct from a header can
also be #included in a translation unit.  Of my many questions, the most
obvious is, what distinguishes a header from a source file? I mean to ask
this in terms of formal definitions used in the Standard. I have a
reasonably good understanding of what /header/ means when used in
relationship to C++.  I, however, have virtually no formal definition of
the term.
--
STH
http://www.kdevelop.org
http://www.suse.com
http://www.mozilla.org

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

On Tue, 13 Apr 2004 03:33:29 +0000 (UTC), hattons@globalsymmetry.com
("Steven T. Hatton") wrote in comp.std.c++:

> I've been trying to get a clear understanding of what is meant by the
> term /header/ in ISO/IEC14882:2003(E).  The term is often used in
> conjunction with the term /source file/.  Sometimes it is suggested that a
> header could be a source file.  Likewise it is sometimes suggested a header
> need not be a source file. The one commonality all headers seem to share is
> that they are #included in a translation unit.
>
> It would also appear that a source file which is distinct from a header can
> also be #included in a translation unit.  Of my many questions, the most
> obvious is, what distinguishes a header from a source file? I mean to ask
> this in terms of formal definitions used in the Standard. I have a
> reasonably good understanding of what /header/ means when used in
> relationship to C++.  I, however, have virtually no formal definition of
> the term.

Headers are completely defined in section 17.4.1.2 of the standard.
They consist of a set of C++ headers enumerated in that section, and
also of the 18 C headers enumerated in that section.  The latter may
be included in two different ways, either with the original C
<header.h> name or the preferred C++ method of <cheader>.

Standard headers are referenced in a program by a preprocessor
directive of the form:

#include <header-name>

Doing so makes all macros, types, prototypes, etc., that the standard
requires standard headers to provide, available to the translation
unit including them.

Standard headers do not have to be files, they could be built-in to
the compiler and "automagically" turned on when they are #include-d.
That is why they are called "headers" and not "header files".  Their
spelling, in the implementation's source character set, is completely
independent of the implementation's file name conventions.  <stdio.h>
is <stdio.h> even if the platform's file system does not allow the "."
character in file names.

Any other sequence of characters that is in a #include <characters> or
#include "characters" is, as far as the standard is concerned, the
valid name of a file for the host platform.  The contents of the
character sequence is completely implementation-defined and most
particularly is not a string literal, even if delimited with quotation
marks.  The character sequence is resolved by the preprocessor and
underlying OS to a file.  The contents of the file are fed by the
preprocessor to the compiler in place of the #include directive.

There are no restrictions or requirements on the contents of such an
included file, other than that it be acceptable to the compiler.

The most common use for such included files is similar to that for
standard headers in C and C++, namely to define types, provide
function prototypes, declare external linkage, and so on.  For that
reason they are frequently called "header files" or often just
"headers", but this is casual terminology.  Nothing about included
files makes them headers in the meaning defined by the standard.

Note also that included files do not need to have the characteristics
of standard headers.  Consider a function that needed a very large
array of constant data to operate on.  There might be a file such as
"my_array.dat", that looked like this:

const int my_data [1000000] =
{
   /* 1,000,000 int values */
};

..and another file named (implementation's file system permitting)
some_file.cpp that started off with:

#include "my_array.dat"

This would make editing the second file, containing the source code,
quicker and easier.

--
Jack Klein
Home: http://JK-Technology.Com
FAQs for
comp.lang.c http://www.eskimo.com/~scs/C-faq/top.html
comp.lang.c++ http://www.parashift.com/c++-faq-lite/
alt.comp.lang.learn.c-c++
http://www.contrib.andrew.cmu.edu/~ajo/docs/FAQ-acllc.html

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

In article <-qidnSx_yo8eQefdRVn-vg@speakeasy.net>, Steven T. Hatton
<hattons@globalsymmetry.com> writes
>I've been trying to get a clear understanding of what is meant by the
>term /header/ in ISO/IEC14882:2003(E).  The term is often used in
>conjunction with the term /source file/.  Sometimes it is suggested that a
>header could be a source file.  Likewise it is sometimes suggested a header
>need not be a source file. The one commonality all headers seem to share is
>that they are #included in a translation unit.

Indeed, #include of a Standard header does not require that the header
actually be any kind of file. All it does is to inform the compiler that
various Standard entities (types, functions etc.) are available. The
compiler can 'know' what those are directly. I do not know of a C++
compiler that takes advantage of that licence but I have used C
compilers that did so.

>
>It would also appear that a source file which is distinct from a header can
>also be #included in a translation unit.  Of my many questions, the most
>obvious is, what distinguishes a header from a source file? I mean to ask
>this in terms of formal definitions used in the Standard. I have a
>reasonably good understanding of what /header/ means when used in
>relationship to C++.  I, however, have virtually no formal definition of
>the term.

The #include directive can include any Standard header. It can also
include any other file (whatever that means on the platform in use) into
the current file. It is usually used to include either Standard headers
or user written header files (which idiomatically provide declarations
of free functions, definitions of classes, inline definitions of
functions and other declarations but not other definitions that would
break the one definition rule).



--
Francis Glassborow      ACCU
Author of 'You Can Do It!' see http://www.spellen.org/youcandoit
For project ideas and contributions: http://www.spellen.org/youcandoit/projects

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

hattons@globalsymmetry.com ("Steven T. Hatton") wrote in message news:<-qidnSx_yo8eQefdRVn-vg@speakeasy.net>...
> I've been trying to get a clear understanding of what is meant by the
> term /header/ in ISO/IEC14882:2003(E).  The term is often used in
> conjunction with the term /source file/.  Sometimes it is suggested that a
> header could be a source file.  Likewise it is sometimes suggested a header
> need not be a source file. The one commonality all headers seem to share is
> that they are #included in a translation unit.
>
> It would also appear that a source file which is distinct from a header can
> also be #included in a translation unit.  Of my many questions, the most
> obvious is, what distinguishes a header from a source file? I mean to ask
> this in terms of formal definitions used in the Standard. I have a
> reasonably good understanding of what /header/ means when used in
> relationship to C++.  I, however, have virtually no formal definition of
> the term.

In ordinary usage, "header" is short for "header file". Header files
are source code that is brought into your translation unit via a
#include directive. Certain header files are usually provided as part
of the standard library, and those are referred to as "standard header
files", or simply "standard headers".

The standard doesn't adhere to the ordinary usage of this term.
However, since it is the standard, the unconventional usage it defines
is the way that the term must be used when discussing the standard.
The term "header" is defined in 17.4.1.2p1 - the fact that the word
"header" is italicized in that paragraph is what indicates that this
paragraph is to be taken as a definition of that term. Footnote 158
clarifies the fact that the standard deliberately avoids specifying
that a header is stored as a file, or that the header-name indicates
the name of the corresponding file. These are common features of many
implementations of the C++ standard library, but they are not
required.

There are many sections of the standard that, if written for the
ordinary meanings of the term, could have referred to "header files".
However, given the standard's desire to reserve "header" for the
standard library, those clauses say "header or source file", which
indicates that headers are not to be thought of as a special case of
source files. User provided files that are to be #included into
translation unit are simply referred to as source files in the
standard, even though conventional usage calls them "header files".

This can lead to confusion. The term "header-name" would seem to mean
the name of a header, but like many phrases in the standard, you can't
figure out what this one means by breaking it down into it's component
parts. In section 16.2 it explains that the preprocessing directive

#include "header-name"

brings into a translation unit the contents of either a header or a
source file. On the other hand, the line

#include <header-name>

is described as working only for headers.

As someone famous once said about quantum mechanics: if you understand
what I've just said, you should feel a bit confused. If it seems
perfectly clear, then you've probably misunderstood something. :-)

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]

hattons@globalsymmetry.com ("Steven T. Hatton") wrote in message news:<-qidnSx_yo8eQefdRVn-vg@speakeasy.net>...
> I've been trying to get a clear understanding of what is meant by the
> term /header/ in ISO/IEC14882:2003(E).  The term is often used in
> conjunction with the term /source file/.  Sometimes it is suggested that a
> header could be a source file.  Likewise it is sometimes suggested a header
> need not be a source file. The one commonality all headers seem to share is
> that they are #included in a translation unit.

To understand headers, you must know there are two kinds. The first kind
is the system header, e.g. <vector>. This header is provided by the
implementation, and in general only its effects may be observed (ie
a vendor could ship it precompiled, in binary form).

The second kind is the user header, i.e. "MyClass.h". This is a source file,
and since you wrote it, you're quite likely able to read it. In Standardese,
this is /not/ an header, even though it is identified by a /header name/
in an include preprocessing directive.

Implementations may reuse the same mechanism for both, i.e. map both
concepts to their notion of a file. It would also be legal if a 'source
file' in fact does not map to a file in the filesystem, but e.g. to a
certain revision of that file, to a database entry, or to some process
which dynamically generates the file (#include "/dev/tty", anyone ?)

If the mechanism is shared, one might say that headers are source files,
but formally this is as wrong as saying char* is a void*, even when both
are 32 bits native memory adresses.

> It would also appear that a source file which is distinct from a header can
> also be #included in a translation unit.  Of my many questions, the most
> obvious is, what distinguishes a header from a source file? I mean to ask
> this in terms of formal definitions used in the Standard. I have a
> reasonably good understanding of what /header/ means when used in
> relationship to C++.  I, however, have virtually no formal definition of
> the term.

Since - formally - source files and headers are distinct, I will answer
the question 'which source files can be #included?'. The answer is all,
except
 * those that cannot be named in an #include /header-name/
and ( indirectly )
 * those that would violate the ODR or other rules by their inclusion.

The latter is a bit of a catch-all, #include /header-name/ just adds
text from a source file to a translation unit, and it shouldn't add
illegal text.

Regards,
Michiel Salters

---
[ comp.std.c++ is moderated.  To submit articles, try just posting with ]
[ your news-reader.  If that fails, use mailto:std-c++@ncar.ucar.edu    ]
[              --- Please see the FAQ before posting. ---               ]
[ FAQ: http://www.jamesd.demon.co.uk/csc/faq.html                       ]