Teem: General Information

		General Information
teem

Library inter-dependencies

The inter-dependencies of the Teem libraries has slowly converged according a notion of what functionality is "fundamental" versus "specialized". This is not a clear-cut distinction, but the present arrangement has proven successful. It is graphed here, with the fundamental libraries at the bottom, and the more specialized libraries on top. The Air library depends on no other library (besides the system's math library). Libraries like Mite depend on nearly every other library, because of the integration of tasks it represents.

Naming and C namespace considerations

Teem is careful to minimize the chances of namespace clashes with other existing libraries, and is very consistent in how symbols in the library are named. All the Teem source complies fully with the policies described here.

The library names in Teem are mostly words, and considerable effort is made to find library names that are both meaningful, yet not already used in use as library names (as determined by google searches). The library names are explained elsewhere.

Every library has a primary header file with the same name as the library. Air has air.h, Hest has hest.h, and so forth. Libraries may have additional header files; Nrrd has nrrd.h, nrrdDefines.h, nrrdEnums.h, and nrrdMacros.h. However, the only header file which needs to be explicitly #included in other source files is the primary header file (such as air.h or nrrd.h). The Teem directory structure is set up so that these header files are themselves in a subdirectory of "include" called "teem", so that including Teem headers in other headers is apt to look something like this (taken from hoover.h):

#include <stdio.h>
#include <stdlib.h>
#include <math.h>

#include <teem/air.h>
#include <teem/biff.h>
#include <teem/ell.h>
#include <teem/nrrd.h>
#include <teem/limn.h>

Any #defines within the library headers will start with either the library name (in upper case), or an underscore followed by the library name. For instance, air.h defines a macro called AIR_AFFINE, and nrrdDefines.h defines an integer NRRD_DIM_MAX.

Every symbol (functions, global variables, and enum values) in a Teem library starts with the library name (in lower case), or one or more understores followed by the library name. For example, the Nrrd library supplies functions named nrrdNew, nrrdCopy, and nrrdNuke, as well as global variables nrrdDefaultSpacing and nrrdStateVerboseIO, and enum value names starting with nrrdFormat, nrrdEncoding, and nrrdType.

Function return values

Nearly all Teem functions return either an int or a pointer. The ones that return pointers are pseudo-constructors or pseudo-destructors. The int return values are interpreted as an error value: zero means "no error, everything ran okay", and non-zero means "there were problems". This means that code to check for errors will generally look like:

if (teemFunction(arg1, arg2)) {
  do error handling;
  return 1;
}
/* else no problem ... */

In general, I am not a big believer in returning different integral error codes to indicate different kinds of errors. These are often frustrating because they tell a little bit about what happened, but don't tell you everything that might be helpful in isolating and fixing the problem. Rather, I accumulate textual descriptions (in English) of the errors in the Biff library. For instance, in nrrdSwapAxes(), we find:

if (nrrdPermuteAxes(nout, nin, axes)) {
  sprintf(err, "%s: trouble swapping axes", me);
  biffAdd(NRRD, err); return 1;
}

The use of biffAdd() insures that the current error string is added to list of previous errors, with the assumption that nrrdPermuteAxes() also left some errors with Biff. This allows you to see the call stack at the time of the error, with each function giving contextual information (if any) describing what it was trying to do. Here's an example of feedback from unu:

unu minmax: error parsing "vol.nhdr" as nrrd for  option:
[nrrd] nrrdLoad:
[nrrd] nrrdRead: trouble reading NRRD file
[nrrd] _nrrdReadNrrd:
[nrrd] _nrrdReadDataRaw: fread() got only 262144 4-byte things, not 266240

See the Biff page for more specific information on Biff usage.