Namespaces - some basics (J. Maybury)
----------

There are a couple things that one could discuss about namespaces:

1) How to create them
2) How to use them

This file will discuss how to use them, as if you wish to create them
that information can generally be found in most newer C++ text books.

HOW TO USE A NAMESPACE
**********************

A brief background as to why namespaces may be important:

   A primary reason for having namespaces is to avoid "naming
   conflicts" between libraries.  For example let's say I include
   the:
   
   #include <iostream>
   
   library and it defines a global variable named flush (which it does)
   and I need to use another library:
   
   #include "third_party_library.h"
   
   that I bought from a "third party" (or someone in my company wrote) and
   their library also defines a global variable named flush - there would
   be a potential problem (which is hopefully obvious).
   
   Out in the real world it is common to be using many different libraries
   written by many different people and thus a high chance that one
   library might not be "compatible" with another library (as described
   above with the flush example).  When such an event happens it may result
   in the code being unable to compile and one or more of the libraries
   needing to be modified - which might not always be possible.  So, the
   need for namespaces arises (which were only recently added to the C++
   standard and thus why many texts prior to 2001 do not adequately address
   the issue).

What is a namespace?

   In it's most basic form a namespace is a "wrapper" around a set of
   global variables and (non-member) functions and classes and
   potentially other things.
   
   What this "wrapper" does is creates a UNIQUE name for each and
   every "item" within that namespace (assuming no two namespaces have
   the same name).
   
   The most common namespace is the std namespace (the standard namespace)
   which is used by most "built-in" C++ libraries like <iostream> and
   <fstream> and <string> (which is very different than <cstring>).
   
   All of the "items" (variables, functions, ...) defined in a namespace
   have a name within that namespace - like cout, cin, endl, flush,
   setiosflags(), ... (all within the std namespace) and outside of that
   namespace their name is std:: followed by their "real" name:
   
   std::cin
   std::cout
   std::setiosflags( ... )
   ...
   
Using existing namespaces:

   So if you want to use those variables defined in a namespace there
   are three ways to do so:

   ---------------------
   // Method #1 - the "painful" way
   #include <iostream>
   
   int main() {
   
      std::cout << "Hello " << std::flush;  // the flush is not needed
      std::cout << "World!" << std::endl;
   
      return 0;
   
   }
   // everytime you use a variable you must specify it's FULL NAME
   ---------------------

   ---------------------
   // Method #2 - the "cheating/easy" way
   #include <iostream>
   
   using namespace std;
   
   int main() {
   
      cout << "Hello " << flush;
      cout << "World!" << endl;
   
      return 0;
   
   }
   // This "imports" all of the variables/items in the std namespace
   // into the "global" namespace and allows you to access them
   // directly
   ---------------------

   ---------------------
   // Method #3 - the best "hybrid" way
   #include <iostream>
   
   using std::cout;   // note flush could be but doesn't have to be
   using std::endl;   //   specified - for example I might want to
                      //   create a global variable of my own named
                      //   flush and thus I couldn't say "using std::flush"
   
   int flush = 1;     // not used but I might want to sometime
   
   int main() {
   
      cout << "Hello " << std::flush;
      cout << "World!" << endl;
   
      return 0;
   
   }
   ---------------------

   NOTE: In a header file it is best to always use the "painful" method of
   accessing variables in a namespace and you should only put the #includes
   that are needed by the header file itself.  In the corresponding source
   file (for the header file) you can then put whatever using statements
   you want and #include any other libraries that may be needed.  A general
   "rule of thumb" is to NEVER put a using statement (of any kind) in a
   header file.
   
   Here is general "template" for how header files should be written:

   -------------------------------------
   #ifndef NAME_OF_FILE
   #define NAME_OF_FILE
   
      // any #includes needed by this header file (and not the source file)
      // and only those needed by this header file.
   
      // do not put using statements here
   
      // put your "interface" items here - class definitions, global variables
      // you want others to use, prototypes for global functions you want
      // others to use, ...
   
   #endif
   -------------------------------------

   and here is a general "template" for how the corresponding source file
   should be written:

   -------------------------------------
   #include "NAME_OF_FILE.h"
      // any other #includes here
   
      // any using statements here (or they could go after each of the
      // corresponding #includes).
   
      // any "local" global variables and prototypes of "local" global
      // (helping) functions you want to use in this file.
   
      // put your "implementation" here
   -------------------------------------

   If you stick to the "templates" above your header files and source
   files will generally work under most circumstances.


NOTE ABOUT #include <iostream.h> (and such similar header files).  In the
newer C++ standard generally the ".h" was listed as not being needed when
including "system" libraries and most old C style libraries are generally
renamed to be <cstdlib> or <cstring> or <c...> ... but not all libraries
may be renamed this way (one main one is stdio.h).

Thus you generally need to not include the ".h" when including "system"
libraries.

END OF FILE