A gentle introduction to using structures

Introduction

In the previous section, Why learn to use structures?, we stated that structures are containers that can hold different variables. We used the analogy of structures being like a grocery bag which provides a convenient container for holding many similar items that would be unwieldy to handle as individual items.

Defining a structure

Unlike a grocery bag, structures are custom fitted for the variables that you would like to incorporate. The first step in using a structure is creating these custom variable containers for the structure. This is called the structure definition. Here is an example structure definition.

//Structure definition
struct descriptiveStats {
   matrix mean;
   matrix max;
   matrix min;
   matrix std_dev;
};

The structure definition has two essential pieces. The first is the structure name, in this case, descriptiveStats. The name is also referred to as the type of the structure. The second piece of the structure is the list of member variables.

Each member variable is defined with a variable type and a name. In this example, all of the member variables are of type matrix, but you may make member variables that are strings, string arrays, multi-dimensional arrays or even other structures. The member variable name is used to access the member variable and should have a name that provides some description of its intended contents.

Declaring a structure

The next step in using a structure is to create a specific instance of a structure. Dog breeding provides a simple and informative analogy. All dog breeding associations provide the definition of German Shepherd or Yorkshire Terrier. This is like the structure definition. If your neighbor has a Yorkshire Terrier named Rover, Rover would be analogous to the structure instance. You create a structure instance with a declaration statement like this:

//Declare 'ds_gdp' to be an instance of a 'descriptiveStats' struct
struct descriptiveStats ds_gdp;

Assigning to structure members

After declaring the structure instance, the members of the structure may be assigned and used just like any other variable in GAUSS. To access them you reference the name of the structure instance, followed by the dot operator and the name of the member variable that you would like to use. You can set the mean member of the ds_gdp structure member we created above like this:

//Assign to structure member, using the dot ('.') operator
ds_gdp.mean = 4.3;

The other members may be set and referenced in the same manner. Here is an example procedure that takes in a column vector, computes some descriptive statistics and returns them in an instance of the descriptiveStats structure that we created above.

proc (1) = getDescStats(A);
   struct descriptiveStats ret_stats;
   ret_stats.mean  = meanc(A);
   ret_stats.max  = maxc(A);
   ret_stats.min = minc(A);
   ret_stats.std_dev = stdc(A);
   retp(ret_stats);
endp;

We will end this section by putting everything together and create a small self-contained program that can be run in GAUSS after copying and pasting it into a file.

//Define structure
struct descriptiveStats {
   matrix mean;
   matrix max;
   matrix min;
   matrix std_dev;
};

//Declare structure instance
struct descriptiveStats ds_gdp;

//Create a matrix on which to calculate descriptive stats
A = rndn(100, 1);

//Calculate the stats and assign to the structure instance
ds_gdp = getDescStats(A);

//Print the output
print "Mean =                " ds_gdp.mean;
print "Maximum =             " ds_gdp.max;
print "Minimum =             " ds_gdp.min;
print "Standard Deviation  = " ds_gdp.std_dev;

//Define the procedure
proc (1) = getDescStats(A);
   struct descriptiveStats ret_stats;
   ret_stats.mean  = meanc(A);
   ret_stats.max  = maxc(A);
   ret_stats.min = minc(A);
   ret_stats.std_dev = stdc(A);
   retp(ret_stats);
endp;

Summary

1. The steps required to use a structure are:
   1. Define the structure
   2. Declare a structure instance
   3. Assign its member variables.
2. Structure members are accessed by using the structure instance name followed by the dot operator and the member variable’s name.
3. Structure members may be used in exactly the same way as any other variable of the same type.