QccDatasetPrint.3

NAME

QccDataset - generic vector data structure

int QccDatasetInitialize(QccDataset *dataset);
int QccDatasetAlloc(QccDataset *dataset);
void QccDatasetFree(QccDataset *dataset);
int QccDatasetGetBlockSize(const QccDataset *dataset);
int QccDatasetPrint(const QccDataset *dataset);
int QccDatasetCopy(QccDataset *dataset1, const QccDataset *dataset2);

DESCRIPTION

QccPack provides data structure QccDataset for representing a generic two-dimensional dataset composed of a list of vectors of the same vector dimension. This dataset structure can be read from and written to DAT-format files, or a QccDataset structure can be used without file input or output.

The main component of a QccDataset structure is an array of vectors. For file input and output, this array of vectors is the current block of vectors being written to or read from the file. That is, access to DAT-format files is block-based, with a block of vectors being written or read at once. Optionally, the block size can be set to be the same as the file size, so that all vectors in the dataset are accessed simultaneously. QccDataset datasets that do not involve file access typically hold all vectors of the dataset in the vector array.

DATA STRUCTURE

The QccDataset data structure is defined as:

typedef struct
{
QccString filename;
FILE *fileptr;
QccString magic_num;
int major_version;
int minor_version;
int num_vectors;
int vector_dimension;
int access_block_size;
int num_blocks_accessed;
double min_val;
double max_val;
QccMatrix vectors;
} QccDataset;

The fields of QccDataset are as follows:

filename: For datasets associated with a file, this is the name of the file.
fileptr: For datasets associated with an open file, this is the FILE pointer.
magic_num, major_version, minor_version: For datasets associated with a file, these are the magic number and version of the file.
num_vectors: The total number of vectors contained in the dataset.
vector_dimension: The vector dimension of the vectors in the dataset.
access_block_size: For datasets associated with a file, this is the number of vectors that will be read or written at a time; i.e., the block size for block-based reading and writing.
num_blocks_accessed: For datasets associated with a file, this is the number of blocks of vectors that have already been read or written.
min_val, max_val: These two values give the smallest and largest vector components, respectively, contained in the dataset.
vectors: The current block of vectors from the dataset. The array contains access_block_size vectors each having dimension vector_dimension.

FILE FORMAT

For reading and writing structures of type QccDataset, QccPack provides the DAT file format. This file format starts with an ASCII header followed by binary data. The ASCII header consists of magic-number/revision information followed by any amount of white space (space, `\t' (tab), `\n' (newline), `\r' (carriage return)) and/or comments lines (lines starting with `#'). Following this white space, additional ASCII header information is given, separated by blanks and newlines. Binary data follows this ASCII header information. Note: one (and only one) newline must immediately follow the last component of ASCII header information before the start of the binary data.

The DAT file format consists of the following information:

DATX.X
<white space>
N dim
min max
v11 v12 v13...
v21 v22 v23...
.
.
.

where DAT is the magic number, X.X is the version number, <white space> is white space and/or comment lines, N is the number of vectors the file contains, dim is the number of components each vector contains (vector dimension), min and max give the smallest and largest vector components, respectively, in the file, and vij is the jth component of the ith vector. N and dim are integers. vij, min, and max are doubles. N, dim, min, and max are stored in ASCII, vij as binary (4 bytes, MSB first, see QccFileWriteDouble(3) ). No white space may exist between the vij's.

ROUTINES

QccDatasetInitialize() should be called before any use of a QccDataset structure. QccDatasetInitialize() initializes the fields of dataset to the following values:

filename: NULL string
magic_num: QCCDATASET_MAGICNUM
major_version, minor_version: initialized to output of QccGetQccPackVersion(3)
num_vectors: 0
vector_dimension: 0
access_block_size: QCCDATASET_ACCESSWHOLEFILE
num_blocks_accessed: 0
min_val, max_val: 0
vectors: NULL

QccDatasetAlloc() allocates storage space for the vectors array of dataset. If vectors is not NULL, QccDatasetAlloc() returns immediately without changing the state of any memory allocation. Otherwise, the vectors array is allocated. The fields access_block_size, num_vectors, and vector_dimension must be defined prior to calling QccDatasetAlloc(). If access_block_size equals QCCDATASET_ACCESSWHOLEFILE, then space for num_vectors vectors is allocated; otherwise, space for access_block_size vectors is allocated.

QccDatasetFree() frees the vectors array previously allocated by QccDatasetAlloc() .

QccDatasetGetBlockSize() returns the block size of the vectors array of dataset. If access_block_size is QCCDATASET_ACCESSWHOLEFILE, num_vectors is returned; otherwise, access_block_size is returned.

QccDatasetPrint() prints the contents of dataset to stdout.

QccDatasetCopy() copies dataset2 to dataset1. If dataset1 has not been allocated prior to calling QccDatasetCopy() (as is evidenced by a NULL dataset1->vectors pointer), then QccDatasetAlloc() is called to allocate space for dataset1 with the same block_size and vector_dimension as dataset2. Otherwise (non-NULL dataset1->vectors pointer), it is assumed that sufficient space as already been allocated to dataset1. In either case, QccDatasetCopy() copies the vectors array of dataset2 to the vectors array of dataset1 via QccMatrixCopy(3) .

RETURN VALUE

Except for QccDatasetGetBlockSize(), each of these routines return 0 upon successful completion, 1 on error.

AUTHOR

Table of Contents

NAME
SYNOPSIS
DESCRIPTION
DATA STRUCTURE
FILE FORMAT
ROUTINES
RETURN VALUE
SEE ALSO
AUTHOR