Converting Objects

Earlier in this chapter we mentioned that for each GAT class there exists a set of companion functions which convert to and from instances of the particular GAT class and an instance of a GATObject. For example in the case of GATTime these functions are given by

GATTime GATObject_ToGATTime(GATObject object)
GATObject GATTime_ToGATObject(GATTime derived)
GATTime_const GATObject_ToGATTime_const(GATObject_const object)
GATObject_const GATTime_ToGATObject_const(GATTime_const derived)

The next example will be concerned with exercising these functions.

The full code for the next example is as follows

#include "GAT.h"

int main(void)
{
  GATTime time;
  GATObject object;
  
  /* Create a GATTime corresponding to now */
  time = GATTime_Create( 0 );
  
  /* Check time is not NULL */
  if( NULL != time )
  {
    /* Convert the GATTime to a GATObject */
    object = GATTime_ToGATObject( time );
    
    /* Convert a GATObject to a GATTime */
    time = GATObject_ToGATTime( object );
  }
  
 /* Destroy the GATTime time */
  GATTime_Destroy( &time );
  
  return 0;
}

Let us now examine this example program.

The first lines

#include "GAT.h"

int main(void)
{
  GATTime time;
  GATObject object;
  
  /* Create a GATTime corresponding to now */
  time = GATTime_Create( 0 );
  
  ...
}

are now standard; thus, we will not review them here. The next lines

/* Convert the GATTime to a GATObject */
object = GATTime_ToGATObject( time );
    
/* Convert a GATObject to a GATTime */
time = GATObject_ToGATTime( object );

contain some novel code. The first lines

/* Convert the GATTime to a GATObject */
object = GATTime_ToGATObject( time );

converts the GATTime instance time to a GATObject instance object. One should think of this conversion as something akin to a cast. In particular, no new memory or resources are allocated in the processs of this conversion and the returned GATObject refers to the same allocated object as the original GATTime. Thus, one need not call the ``Destroy'' function on the resulting GATObject and the associated GATTime. One need only call the ``Destroy'' function on the GATTime or the GATObject instance. The next lines

/* Convert a GATObject to a GATTime */
time = GATObject_ToGATTime( object );

convert back from the GATObject instance object to a GATTime instance time. The remainder of the program

/* Destroy the GATTime time */
GATTime_Destroy( &time );
  
return 0;

is now standard; hence, we will not cover these lines in detail.