Understanding Headers and Inclusions

Ok, as some of you might know, I'm working with Visual C++ 6 as my IDE.

As I read through books, tutorials, and blocks of code, I'm confused with the different styles of including headers in my programs. Let's say I want to include a basic iostream. What's the correct way to do it, and why? I've seen all these notations:

#include <iostream> // works with my compiler
#include <iostream.h> // doesn't work
#include "iostream" // works
#include "iostream.h" // doesn't work

I haven't found any definitive information about this yet. As far as I can tell, some of the formats might be for C (not C++), and some might be compiler-specific. But as it is, I'm completely baffled! I like to know exactly what's happening with a line of code before I include it in a program.

Also, what if I want to use a different header, like math or string? I know they exist, but I don't know where to find them, how to implement them, or what functions/data types/etc. they offer to me. Guess and check doesn't work here!

And finally, further down the road, I'd like to be able to write my own header files and include them in my CPP files. It sounds like there's a different protocol for doing this... am I on the right track?

Thanks very much for your help! You guys are great.

For standard headers, the correct method is to use the #include <whatever> style. Also the C++ standard headers no longer have .h at the end of them, people using iostream.h are now officially wrong.

#include <iostream>
#include <fstream>
this works for all C++ headers, for the C headers that are now part of C++, like string.h and math.h
#include <cstring>
#include <cmath>

is the correct way, this is done to avoid name collisions, cstring and string are completely different, cstring is the old string.h which has things for dealing with char*s like strcmp and strcpy. string is the header for the STL string, a much more elegant solution to string handling in C++.

Generally your own headers, and other non-standard headers should be included in quotes.

(I should note that the difference is not only a style one, <> searches the compiler include path first, while "" searches the local directory first, then the compiler include one)




If you want to know what is in a header like cmath or string, check out some documentation, the compiler, or any number of websites should have documentation on the members of the standard headers, just using google works fine for me when I need to check an obscure function.





If you are writing your own headers name them in the format yourheader.h and inside them you should have include guards to keep them from being included more than once

#ifndef __yourheader_h__
#define __yourheader_h__

//all your code goes here

#endif

__yourheader_h__ could be anything, i like to use the name of my header but it could also be random like PZEIJDFKLAJFL, but you'd then have to make sure that no 2 files had the same random string of characters, and there's just no good reason to defy convention and not use the header name.

Ok--that makes a bit more sense. But as I read more I've managed to become even more confused, particularly after browsing through the MSDN Visual Studio documentation. I found out that if I use

#include <iostream.h>

my code will work if I delete the "using namespace std" line--and I have no idea why. Does using <iostream> and the std namespace give me the same results as using <iostream.h> and no namespace? How come? Why is there this difference in the first place?

There has got to be a resource in plain english out there that explains all these differences... any links? :)

Thanks very very much again!

Just because iostream.h will work does not mean you should use it. When the h was removed from header files, the standard library was moved inside the std namespace.

using namespace std; qualifies names within the namespace, so instead of std::cout you can just type cout.

>#include <iostream> // works with my compiler
This is the new header. If your compiler supports it then don't bother with the old ones as they are not standard C++. But don't forget that when using the new headers, everything is wrapped in the std namespace, so you will have to take that into consideration when using standard names. The three ways to access a namespace are explicit qualification, a using declaration and a using directive.

Explicit qualification:

Code:

---

#include <iostream>

int main()
{
  std::cout<<"test"<<std::endl;
}

---

Using declaration:

Code:

---

#include <iostream>

using std::cout;
using std::endl;

int main()
{
  cout<<"test"<<endl;
}

---

Using directive:

Code:

---

#include <iostream>

using namespace std;

int main()
{
  cout<<"test"<<endl;
}

---

>#include <iostream.h> // doesn't work
This is the old header.

>#include "iostream" // works
This is bad style and wasteful. The double quote delimiter will cause the compiler to search in an implementation-defined place, but that place is probably not the location of the standard libraries. If that search fails (or is not supported) it will then search as if the angle brackets were used. So you will likely be performing one unnecessary search before looking in the right place.

>#include "iostream.h" // doesn't work
See my above comments.

><> searches the compiler include path first, while "" searches the local directory first, then the compiler include one
Not necessarily. The standard only says that "implementation-defined places" are searched.

>__yourheader_h__ could be anything
Preferably something without leading underscores so as not to trample the implementation's namespace. :)

Code:

---

#include <iostream>

using std::cout;

int main()
{
  cout<<"test"<<endl;
}

---

That should be

Code:

---

#include <iostream>

using std::cout;
using std::endl; //notice this

int main()
{
  cout<<"test"<<endl;
}

---

Otherwise you'd get an error with endl, because you're not telling the compiler you're using it.

EDIT: Prelude corrected the code in her post. This is just in case someone reads this later and thinks I made it up, or just doesn't know what I'm talking about.

>Otherwise you'd get an error with endl, because you're not telling the compiler you're using it.
Yes, thank you. That will teach me to not compile my examples, won't it? ;)

so is using directive the best of the 3 methods or depends on the length of the program?

>>so is using directive the best of the 3 methods or depends on the length of the program?
If you're coding a small toy program you could do it, but usually the best way to do it is declaration if you're using it a lot in the code, although I sometimes just use qualification if I'm just using it this one time or in header files, because it may cause problems in the files that include it, if you have a type with the same name in another namespace, and that would be tricky to debug.

>>I like to know exactly what's happening with a line of code before I include it in a program.

good luck looking through iostream...

>>Generally your own headers, and other non-standard headers should be included in quotes.

the only difference is that when you have the name in brackets <> it searches where your compiler tells it to search, and when you have it in quotes "" it searches the local directory, or where the file you're working on is... here's a quick overview on what your own header would look like:

Files:

Code:

---

Local Directory:
    Foo.H
    Bar.cpp
Include Directory (sometimes it's: */[compiler]/include):
    ...
    iostream
    ...

---

Foo.H:

Code:

---

#ifndef FOO_H_    //not necessary, just makes sure it's only defined once
#define FOO_H_    //same here

char*message="Hello World";    //whatever code you need/want... usually a class

#endif    //same here

---

Bar.cpp

Code:

---

#include<iostream>    //search the directory, in this case, */[compiler]/include is listed,
                                  //but don't worry about where it comes from for now
#include "Foo.H"    //search the local directory

int main()
{
    std::cout<<message<<std::endl;    //output the message
    std::cin.get();    //wait for input
    return 0;    //return 0 (not really all that necessary, but let's not start a war)
}

---

notice the std:: in front of cout,endl, and cin... that's because those are all defined in the std namespace, and instead of dumping everything into this program, I'm just using those when needed... this example is bad programming, but it was only intended to give you a little bit of insight into how it kinda works and how to do it on your own... you'll learn more when you get into classes

Thanks major, and everybody!

I understand classes, objects, etc., as I'm coming to C++ from a web-based OOP background. It's the quirky C++ synax that I'm trying to get a grip on.

Now... on the preprocessor directives in the header file. I've seen the #ifndef...#def...#endif" lines a lot in header files, which look like VB/ASP scripting. Is this part of the ANSI standard, or is it compiler-specific? What, really, is going on with these lines? What other directives can I add? I definitley don't expect you guys to waste your time spelling out the answers to these newbie questions, but a nudge in the right direction (like a link that explains these issues) would be greatly appreciated!

MSDN