For each class written at ISIP there are two required header files: the class constants file and the class definition file. In the next two sections, we will first show the full header file and then analyze each part of it. This is done to show the proper spacing for these files without the intrusion of comments Note that this page does not cover syntax in a detailed manner. For a discussion on style, see our page on programming style.
Class constants header file:
The class constants header file contains all of the constants which are to be made available to that class and any program that uses that class. An example of such a file is shown below.
Now we will exam it piece by piece. The required components of this file are so indicated.// file: math/io/sof/sof_constants.h // // constants specific to the Sof class. // // make sure definitions are only made once // #ifndef __ISIP_SOF_CONSTANTS #define __ISIP_SOF_CONSTANTS // isip include files // #ifndef __ISIP_INTEGRAL_CONSTANTS #include <integral_constants.h> #endif // define the class name // #define SOF_CLASS_NAME (char_1*)"Sof" // define magic sequences used to identify an Sof file // #define SOF_MAX_MAGIC_LENGTH 19 #define SOF_FMT_HEADER (char_1*)"%1c%s%s%*1c%1c" // define the version number and magic number // #define SOF_VERSION (char_1*)"v1.0" #define SOF_MAGIC (float_4)27.27 // define seek directions // #define SOF_FORWARD (int_4)0 #define SOF_BACKWARD (int_4)1 // end of file // #endif
**Required** This part of the file defines the name of this file and the class to which the constants pertain. Notice that the file name is of the form: classname_constants.h. You can find a full description of filenaming conventions here.// file: math/io/sof/sof_constants.h // // constants specific to the Sof class. //
**Required** These two statements make sure that during compilation and linking, the constants are only defined once. Among other things, this makes compilation more efficient. The variable being defined by the #define statement has a particular format __ISIP_CLASSNAME_CONSTANTS . Sticking to this format insures that this definition will not interfere with other constants defined.// make sure definitions are only made once // #ifndef __ISIP_SOF_CONSTANTS #define __ISIP_SOF_CONSTANTS
**Required** These statement include the ISIP standard constants file if they have not already been included. This file contains standard constants in our environment such as the return flags ISIP_TRUE, ISIP_FALSE, ISIP_ERROR and important constants like random number seeds.// isip include files // #ifndef __ISIP_INTEGRAL_CONSTANTS #include <integral_constants.h> #endif
**Required** This statement defines the class name constant. Notice that this and all constant names are preceded by the class name (or an abbreviation of the same). Also note that the value for this and the following constants are strictly type cast.// define the class name // #define SOF_CLASS_NAME (char_1*)"Sof"
These statements define other constants which are useful in the confines of this class. The data types "char_1", "float_4", and "int_4" are defined data types in our environment. A full explanation of them is found at this location.// define magic sequences used to identify an Sof file // #define SOF_MAX_MAGIC_LENGTH 19 #define SOF_FMT_HEADER (char_1*)"%1c%s%s%*1c%1c" // define the version number and magic number // #define SOF_VERSION (char_1*)"v1.0" #define SOF_MAGIC (float_4)27.27 // define seek directions // #define SOF_FORWARD (int_4)0 #define SOF_BACKWARD (int_4)1
**Required**This is the last statement in the file and is the closing for the statement #ifndef __ISIP_SOF_CONSTANTS// end of file // #endif
Class definition header file:
The class constants header file the definition of the class. Only one class is defined per header file. This header file defines all of the data members and the methods which are available to this class. An example of the class definition header file is shown below.
// file: math/io/sof/sof.h
//
// make sure definitions are only made once
//
#ifndef __ISIP_SOF
#define __ISIP_SOF
// isip include files
//
#ifndef __ISIP_INTEGRAL
#include <integral.h>
#endif
// forward class definitions
//
#include "../class/math/io/sof/sof_index.h"
// Sof: (s)ignal (o)bject (f)ile
//
// this file defines a class that is used to read and write isip objects
// to a file (binary or ascii). this class serves as an index, keeping
// track of all objects written to a file. note that multiple objects
// of the same class name can be written to a file.
//
class Sof {
//---------------------------------------------------------------------------
//
// protected data
//
//---------------------------------------------------------------------------
protected:
// general information about a file
//
char_1* name_d; // current filename
char_1* expanded_name_d; // expanded filename
int_4 file_type_d; // type of file
// debugging parameters
//
int_4 debug_level_d; // amount of debug information
//---------------------------------------------------------------------------
//
// public methods
//
//---------------------------------------------------------------------------
public:
// required methods
//
char_1* name_cc();
volatile void error_handler_cc(char_1* method_name, char_1* message);
// destructors/constructors
//
~Sof();
Sof();
Sof(char_1* filename);
// open/close methods
//
logical_1 open_cc(char_1* filename);
logical_1 open_cc(char_1* filename, int_4 mode);
logical_1 open_cc(char_1* filename, int_4 type, int_4 mode);
logical_1 close_cc();
// useful debugging methods
//
logical_1 set_debug_cc(int_4 debug_level);
logical_1 debug_cc(FILE* fp, char_1* message);
logical_1 display_cc(FILE* fp);
//---------------------------------------------------------------------------
//
// private methods
//
//---------------------------------------------------------------------------
private:
// cleanup
//
logical_1 free_cc();
logical_1 free_index_cc();
};
// end of include file
//
#endif
Now we will exam it piece by piece. The required components
of this file are so indicated.
**Required** This is the first statement in the file and it defines the filename. As discussed here, the filename is the same as the class name ignoring capitalization.// file: math/io/sof/sof.h //
**Required** These two statements make sure that during compilation and linking, this class is only defined once. Among other things, this makes compilation more efficient. The variable being defined by the #define statement has a particular format// make sure definitions are only made once // #ifndef __ISIP_SOF #define __ISIP_SOF
Sticking to this format insures that this definition will not interfere with other definitions.__ISIP_CLASSNAME
**Required** This include file contains all of the ISIP standard integral data types. These are used to maintain data precision across platforms. For a more detailed discussion, visit this page.// isip include files // #ifndef __ISIP_INTEGRAL #include <integral.h> #endif
This statement gives the location of class definitions which will be used in this class. So, Sof_index is an object that will be used in Sof in some manner.// forward class definitions // #include "../class/math/io/sof/sof_index.h"
**Required**This comment block should give summary of how the object is intended to be used. Particularly highlight the salient features of the class.// Sof: (s)ignal (o)bject (f)ile // // this file defines a class that is used to read and write isip objects // to a file (binary or ascii). this class serves as an index, keeping // track of all objects written to a file. note that multiple objects // of the same class name can be written to a file. //
class Sof {
**Required**There are three main sections to any class header file:
protected data section, the public methods section, and the private
methods section. Each of these sections is required even if they are
empty.
**Required** The protected data section contains ALL of the class member data. Each member variable is given a name which has as its last two characters "_d" This is to distinguish these variables from local variables inside of class methods.//--------------------------------------------------------------------------- // // protected data // //---------------------------------------------------------------------------
**Required** This is a special variable which defines the amount of debugging output that the user should expect. It is set to values like ISIP_DEBUG_NONE, ISIP_DEBUG_FULL, etc. This is the only variable which is required to be in every class.protected: // general information about a file // char_1* name_d; // current filename char_1* expanded_name_d; // expanded filename int_4 file_type_d; // type of file // debugging parameters // int_4 debug_level_d; // amount of debug information
**Required** The public methods section contains the class public method prototypes. This is the interface for the class to the outside world. This section should include prototypes for methods to set and get the values of the member data, I/O methods, and any other method that the user of this class may need to interact with it. Notice that every method name is such that the last three characters are "_cc".//--------------------------------------------------------------------------- // // public methods // //---------------------------------------------------------------------------
**Required** These methods are required for every class. "name_cc" returns the name of the class as defined in the class constants file. "error_handler_cc" is an interface for writing error messages related to this class.public: // required methods // char_1* name_cc(); volatile void error_handler_cc(char_1* method_name, char_1* message);
**Required** These methods are the destructor (~Sof) and constructor (Sof) for this class. For each class there is a single destructor but there may be multiple constructors. The default constructor has no arguments.// destructors/constructors // ~Sof(); Sof(); Sof(char_1* filename);
These are examples of public methods. Though the debug methods here are not required, they are almost always necessary so it is good practice to include them in the class even if they have no use at the moment.// open/close methods // logical_1 open_cc(char_1* filename); logical_1 open_cc(char_1* filename, int_4 mode); logical_1 open_cc(char_1* filename, int_4 type, int_4 mode); logical_1 close_cc(); // useful debugging methods // logical_1 set_debug_cc(int_4 debug_level); logical_1 debug_cc(FILE* fp, char_1* message); logical_1 display_cc(FILE* fp);
**Required** The private methods section contains the class private method prototypes. These methods are ones which will only be used by the class. Typically, they do operations that should be left out of the view of the user such as memory allocation and freeing, etc. Notice that every method name is such that the last three characters are "_cc".//--------------------------------------------------------------------------- // // private methods // //--------------------------------------------------------------------------- private: // cleanup // logical_1 free_cc(); logical_1 free_index_cc();
**Required** These two items indicate the end of the class definition. The #endif closes the statement #ifndef __ISIP_CLASSNAME.}; // end of include file // #endif
