.TH G_DELETE 2 "28 September 1993" "Demeter" "Demeter Software"
.SH NAME
g_delete \- sends the generic delete message to an object.
.SH SYNOPSIS

void Universal::
.I g_delete
( char* fileName )

.SH DESCRIPTION

.I g_delete ,
when sent to a given object, regards this object as a graph and
recursively deletes a subgraph of this object graph. The subgraph used
as reference for the deletion is described textually in
.I fileName .
If
.I fileName
is not provided,
.I g_delete
deletes the entire object receiving the
.I g_delete
message. The receiving object must be a tree object. That is, it cannot
have any cycles or shared subobjects.
.I g_delete
is a generic method implemented at class Universal and inherited by any
user class.

.I g_delete
deletes the subgraph of the receiving object graph by recursively
traversing the receiving object graph in a post-order fashion,
traversing the neighbors of a given node and then deleting the node.
Since a node in an object graph is itself an object,
.I g_delete
deletes a node by invoking the C++
.I delete
operation on the corresponding object.

.SH USAGE
Here is an example of how to use
.I g_delete .
Suppose the following class dictionary graph describes an object to be
deleted:

.KS
Example = <exps> Prefix_list.
.br
Prefix_list ~ { Prefix }.
.br
Prefix : Compound | Simple.
.br
Compound = "(" <op> Op <args> Prefix_list ")".
.br
Simple = <val> DemNumber.
.br
Op : Plus.
.br
Plus = "+".
.KE

The following code reads in and makes a copy of an object of class
.I Example
and deletes the copied object.

.KS
Example* iExample = new Example();
.br
if ( ( Example* ) iExample -> g_parse( Dem_input ) == NULL )
.br
{
.br
   cerr << "Parser error." << endl;
.br
   exit(1);
.br
}
.br
Example* nExample = ( Example* ) iExample -> g_copy();
.br
nExample->g_delete();
.KE

Suppose we now want to delete only
.I Compound
objects and within them, only their
.I args
parts. The following class dictionary graph, contained in file
.I cd-delete
describes the subgraph that should be given to
.I g_delete .

.KS
Example = <exps> Prefix_list.
.br
Prefix_list ~ { Prefix }.
.br
Prefix : Compound.
.br
Compound = "(" <args> Prefix_list ")".
.br
Op : Plus.
.br
Plus = "+".
.KE

The following code should then read in and make a copy of an object of
class
.I Example
and delete the subobject described by the required subgraph from the
copied object.

.KS
Example* iExample = new Example();
.br
if ( ( Example* ) iExample -> g_parse( Dem_input ) == NULL )
.br
{
.br
   cerr << "Parser error." << endl;
.br
   exit(1);
.br
}
.br
Example* nExample = ( Example* ) iExample -> g_copy();
.br
nExample->g_delete( "cd-delete" );
.KE

Notice that the only difference between this piece of code and the
original is the argument file name.

.SH ASSUMPTIONS
Since
.I g_delete
uses the C++
.I delete
operation to delete a node once its neighbors have been traversed, it
should be noted that using
.I g_delete
assumes the following. No destructor should perform any
.I delete
operation on an immediate part, for any object of the subgraph being
deleted. The reson for this is that otherwise objects would be deleted
more than once, as the following example illustrates. Suppose the
object to be deleted is described by the following class dictionary
graph.

.KS
A = <b> B.
.br
B = <c> C.
.br
C = .
.KE

A simplified rendition of
.I g_delete
for the class dictionary graph at hand is:

.KS
void A::g_delete() { b->g_delete(); delete b; }
.br
void B::g_delete() { c->g_delete(); delete c; }
.br
void C::g_delete() { /* empty */ }
.KE

Also suppose that the assumption is not true and that the destructors
for the given classes contain the following code.

.KS
A::~A() { delete b; }
.br
B::~B() { delete c; }
.br
C::~C() { /* empty */ }
.KE

Then, executing the following code:

.KS
C *c = new C;
.br
B *b = new B(c);
.br
A *a = new A(b);
.br
a -> g_delete();
.KE

will destroy b's and c's storage twice, which may result in a memory error.

.SH SEE ALSO
g_parse(2), g_copy(2)

.SH REFERENCES 

.I User Manual for The C++ Demeter System
.br
Walter L. Hursch
.br
Northeastern University, 1993

.I The Annotated C++ Reference Manual
.br
Margaret A. Ellis and Bjarne Stroustrup
.br
Addison-Wesley, 1990

.I C++ Primer
.br
Stanley B. Lippman
.br
Addison-Wesley, 1989