NAME

dsmethod.h - methods for various DATASET instance types

SYNOPSIS

The DATASET_METHODs defined in this module can be used to transform other types into DATASETs. Methods currently in this module include ones for C matrices and the SERIES type.

#include <dsmethod.h>

DESCRIPTION

You probably only need to know about the predefined method types which are listed below in the Miscellaneous Items subsection found at the end of this section. If you wish to write your own DATASET method, then see the documentation for the DATASET_METHOD type.

A DATASET_METHOD type should be defined once for each instance type of a DATASET. Thus, there should be one defined for SERIES, and another defined for C matrices, and maybe a third to access some specific database file format, etc. In each case, functions to answer the five possible query types in a DATASET_METHOD need to be defined. The only potentially tricky part of writing a DATASET_METHOD is to come up with a reasonable convention for who owns the memory returned by the x() and y() calls.

All of the methods defined in this package assume that they ``own'' the memory. Thus, they frequently reuse this memory and only free it when the instance itself is destroyed. See the implementation of series(3) to see how I have handled this problem.

Type Declarations

The following types are defined in the header file dsmethod.h.

DATASET_METHOD

typedef struct DATASET_METHOD {
  unsigned (*size)(void *instance);
  unsigned (*x_size)(void *instance);
  unsigned (*y_size)(void *instance);
  double  *(*x)(void *instance, unsigned index);
  double  *(*y)(void *instance, unsigned index);
} DATASET_METHOD;

The function table for a specific instance needs to have five functions defined: one to return the number of patterns in the DATASET (size()), two functions to return the dimensionality of the input and output patterns (x_size() and y_size()), and two to return specific input and output patterns (x() and y()).

Don't forget: If you are writing your own method, remember that instance is going to be passed as a (void *) type; thus, you will need to cast the pointer back into its ``real'' type when you receive it. See the source code for dsmethod(3) for more information.

Miscellaneous Items

Currently defined DATASET_METHODs include:

• dsm_series_method: Method for accessing SERIES types.
• dsm_matrix_method: Method for accessing one or two C matrices.
• dsm_dblptr_method: Method for accessing one or two C double pointer matrices.
• dsm_file_method: Method for accessing enormous binary files.
• dsm_subset_method: Method for accessing a nearly contiguous portion of another DATASET.
• dsm_isubset_method: Method for accessing an indexed portion of another DATASET.
• dsm_fifo_method: Method for accessing incrementally made fifo sets.

AUTHOR

Gary William Flake (gary.flake@usa.net).

SEE ALSO

series(3), and dataset(3).