Table Reading/Writing Routines

Detailed Description

Routines for reading/writing tables in HDF5 files.

These routines are basic routines for reading and writing tables in HDF5 files.

Prototypes
LALH5Dataset *	XLALH5TableAlloc (LALH5File UNUSED *file, const char UNUSED *name, size_t UNUSED ncols, const char UNUSED **cols, const LALTYPECODE UNUSED *types, const size_t UNUSED *offsets, size_t UNUSED rowsz)
	Allocates a LALH5Dataset dataset to hold a table. More...
int	XLALH5TableAppend (LALH5Dataset UNUSED *dset, const size_t UNUSED *offsets, const size_t UNUSED *colsz, size_t UNUSED nrows, size_t UNUSED rowsz, const void UNUSED *data)
	Appends rows of data to a LALH5Dataset dataset holding a table. More...
int	XLALH5TableRead (void UNUSED *data, const LALH5Dataset UNUSED *dset, const size_t UNUSED *offsets, const size_t UNUSED *colsz, size_t UNUSED rowsz)
	Reads table data from a LALH5Dataset. More...
int	XLALH5TableReadRows (void UNUSED *data, const LALH5Dataset UNUSED *dset, const size_t UNUSED *offsets, const size_t UNUSED *colsz, size_t UNUSED row0, size_t UNUSED nrows, size_t UNUSED rowsz)
	Reads certain rows of table data from a LALH5Dataset. More...
int	XLALH5TableReadColumns (void UNUSED *data, const LALH5Dataset UNUSED *dset, const char UNUSED *cols, const size_t UNUSED *offsets, const size_t UNUSED *colsz, size_t UNUSED row0, size_t UNUSED nrows, size_t UNUSED rowsz)
	Reads certain columns of table data from a LALH5Dataset. More...
size_t	XLALH5TableQueryNRows (const LALH5Dataset UNUSED *dset)
	Gets the number of rows in a LALH5Dataset containing table data. More...
size_t	XLALH5TableQueryNColumns (const LALH5Dataset UNUSED *dset)
	Gets the number of columns in a LALH5Dataset containing table data. More...
size_t	XLALH5TableQueryRowSize (const LALH5Dataset UNUSED *dset)
	Gets the number of bytes in a row in a LALH5Dataset containing table data. More...
int	XLALH5TableQueryColumnName (char UNUSED *name, size_t UNUSED size, const LALH5Dataset UNUSED *dset, int UNUSED pos)
	Gets the name of a column in a LALH5Dataset containing table data. More...
size_t	XLALH5TableQueryColumnSize (const LALH5Dataset UNUSED *dset, int UNUSED pos)
	Gets the size in bytes of a column in a LALH5Dataset containing table data. More...
LALTYPECODE	XLALH5TableQueryColumnType (const LALH5Dataset UNUSED *dset, int UNUSED pos)
	Gets the type of data stored in a column in a LALH5Dataset containing table data. More...
size_t	XLALH5TableQueryColumnOffset (const LALH5Dataset UNUSED *dset, int UNUSED pos)
	Gets the offset of the data in a column in a LALH5Dataset containing table data. More...

Function Documentation

XLALH5TableAlloc()

LALH5Dataset* XLALH5TableAlloc	(	LALH5File UNUSED *	file,
		const char UNUSED *	name,
		size_t UNUSED	ncols,
		const char UNUSED **	cols,
		const LALTYPECODE UNUSED *	types,
		const size_t UNUSED *	offsets,
		size_t UNUSED	rowsz
	)

Allocates a LALH5Dataset dataset to hold a table.

This routine creates a dataset with name name within an HDF5 file associated with the LALH5File file structure and allocates a LALH5Dataset structure associated with the dataset. The type of data to be stored are table data comprised of rows of size rowsz; each row having ncols columns with names cols, types types, and offsets offsets.

with the LALH5Dataset dset and stores the data in the buffer data. This buffer should be sufficiently large to hold the requested rows of the dataset, which is comprised of a number of rows each of size rowsz. Each row is comprised of a number of columns which are named in the comma-separated list in string cols. The offsets of the columns and the sizes of the columns in each row of data is provided by the arrays offsets and colsz respectively.

The following example shows how to create a dataset named particles in which particle data can be stored.

#include <stddef.h>
#include <lal/LALStdlib.h>
#include <lal/LALH5FileIO.h>
 
struct body {REAL8 x; REAL8 y; REAL8 z; REAL8 vx; REAL8 vy; REAL8 vz;};
size_t ncols = 6;
size_t types[6] = {LAL_D_TYPE_CODE, LAL_D_TYPE_CODE, LAL_D_TYPE_CODE, LAL_D_TYPE_CODE, LAL_D_TYPE_CODE, LAL_D_TYPE_CODE};
size_t offsets[6] = {offsetof(struct body, x), offsetof(struct body, y), offsetof(struct body, z), offsetof(struct body, vx), offsetof(struct body, vy), offsetof(struct body, vz)};
size_t rowsz = sizeof(*data);
LALH5File *file = XLALH5FileOpen("example.h5", "w");
LALH5Dataset *dset = XLALH5TableAlloc(file, "particles", ncols, cols, types, offsets, rowsz);

Parameters

file	Pointer to a LALH5File in which to create the dataset.
name	Pointer to a string with the name of the dataset to create (also the table name).
ncols	Number of columns in each row.
cols	Pointer to an array of strings giving the column names.
types	Pointer to an array of LALTYPECODE values specifying the data type of each column.
offsets	Pointer to an array of offsets for each column.
rowsz	Size of each row of data.

Returns

A pointer to a LALH5Dataset structure associated with the specified dataset within a HDF5 file.

Return values

NULL	An error occurred creating the dataset.

Definition at line 3225 of file H5FileIOLowLevel.c.

XLALH5TableAppend()

int XLALH5TableAppend	(	LALH5Dataset UNUSED *	dset,
		const size_t UNUSED *	offsets,
		const size_t UNUSED *	colsz,
		size_t UNUSED	nrows,
		size_t UNUSED	rowsz,
		const void UNUSED *	data
	)

Appends rows of data to a LALH5Dataset dataset holding a table.

This routine appends nrows rows of data each having size rowsz to a HDF5 table dataset associated with the LALH5Dataset structure dset. The data is contained in data and the offsets and sizes of each column are given by the arrays offsets and colsz.

The following example shows how to append rows to a dataset named particles in which particle data is stored.

#include <stddef.h>
#include <lal/LALStdlib.h>
#include <lal/LALH5FileIO.h>
 
struct body {REAL8 x; REAL8 y; REAL8 z; REAL8 vx; REAL8 vy; REAL8 vz;} data[] = {
        { .x = +0.83, .y = -0.13, .z = -0.24, .vx = +0.60, .vy = -0.79, .vz = -0.98 },
        { .x = -0.59, .y = -0.12, .z = -0.60, .vx = +0.38, .vy = +0.61, .vz = -0.75 },
        { .x = -0.48, .y = -0.78, .z = +0.83, .vx = -0.58, .vy = -0.09, .vz = +0.44 },
        { .x = +0.99, .y = -0.13, .z = -0.48, .vx = +0.44, .vy = +0.06, .vz = -0.58 },
        { .x = -0.26, .y = +0.92, .z = -0.98, .vx = -0.75, .vy = +0.45, .vz = +0.30 },
        { .x = +0.88, .y = -0.50, .z = +0.53, .vx = -0.82, .vy = +0.50, .vz = -0.36 },
        { .x = -0.20, .y = +0.55, .z = +0.85, .vx = -0.87, .vy = +0.41, .vz = +0.38 },
        { .x = +0.48, .y = -0.09, .z = +0.29, .vx = -0.76, .vy = +0.27, .vz = -0.38 },
        { .x = +0.11, .y = -0.13, .z = -0.02, .vx = +0.69, .vy = +0.64, .vz = +0.06 },
        { .x = -0.85, .y = +0.08, .z = -0.25, .vx = -0.20, .vy = -0.69, .vz = +0.77 }
};
size_t nrows = sizeof(data)/sizeof(*data);
size_t ncols = 6;
size_t types[6] = {LAL_D_TYPE_CODE, LAL_D_TYPE_CODE, LAL_D_TYPE_CODE, LAL_D_TYPE_CODE, LAL_D_TYPE_CODE, LAL_D_TYPE_CODE};
size_t offsets[6] = {offsetof(struct body, x), offsetof(struct body, y), offsetof(struct body, z), offsetof(struct body, vx), offsetof(struct body, vy), offsetof(struct body, vz)};
size_t colsz[6] = {sizeof(data->x), sizeof(data->y), sizeof(data->z), sizeof(data->vx), sizeof(data->vy), sizeof(data->vz)};
size_t rowsz = sizeof(*data);
LALH5File *file = XLALH5FileOpen("example.h5", "w");
LALH5Dataset *dset = XLALH5TableAlloc(file, "particles", ncols, cols, types, offsets, rowsz);
XLALH5TableAppend(dset, offsets, colsz, nrows, rowsz, data);

Parameters

dset	Pointer to a LALH5Dataset containing the table into which the rows will be appended.
offsets	Pointer to an array of offsets for each column.
colsz	Pointer to an array of sizes of each column.
nrows	Number of rows of data that will be appended.
rowsz	Size of each row of data.
data	Pointer to a memory in which contains the data to be appended.

Return values

0	Success.
-1	Failure.

Definition at line 3350 of file H5FileIOLowLevel.c.

XLALH5TableRead()

int XLALH5TableRead	(	void UNUSED *	data,
		const LALH5Dataset UNUSED *	dset,
		const size_t UNUSED *	offsets,
		const size_t UNUSED *	colsz,
		size_t UNUSED	rowsz
	)

Reads table data from a LALH5Dataset.

This routine reads the table data from a HDF5 dataset associated with the LALH5Dataset dset and stores the data in the buffer data. This buffer should be sufficiently large to hold the entire contents of the dataset, which is comprised of a number of rows each of size rowsz. The number of rows can be determined with the routine XLALH5TableQueryNRows(). Each row is comprised of a number of columns, which can be determined with the routine XLALH5TableQueryNColumns(). The offsets of the columns and the sizes of the columns in each row of data is provided by the arrays offsets and colsz respectively.

The following example shows how to read the data from a table named particles.

#include <stddef.h>
#include <lal/LALStdlib.h>
#include <lal/LALH5FileIO.h>
 
struct body {REAL8 x; REAL8 y; REAL8 z; REAL8 vx; REAL8 vy; REAL8 vz;} *data;
size_t offsets[] = {offsetof(struct body, x), offsetof(struct body, y), offsetof(struct body, z), offsetof(struct body, vx), offsetof(struct body, vy), offsetof(struct body, vz)};
size_t colsz[] = {sizeof(data->x), sizeof(data->y), sizeof(data->z), sizeof(data->vx), sizeof(data->vy), sizeof(data->vz)};
size_t rowsz = sizeof(*data);
LALH5File *file = XLALH5FileOpen("example.h5", "r");
LALH5Dataset *dset = XLALH5DatasetRead(file, "particles");
size_t nrows = XLALH5TableQueryNRows(dset);
data = LALMalloc(nrows * rowsz);
XLALH5TableRead(data, dset, offsets, colsz, rowsz);

Parameters

data	Pointer to a memory in which to store the data.
dset	Pointer to a LALH5Dataset from which to extract the data.
offsets	Pointer to an array of offsets for each column.
colsz	Pointer to an array of sizes of each column.
rowsz	Size of each row of data.

Return values

0	Success.
-1	Failure.

Definition at line 3404 of file H5FileIOLowLevel.c.

XLALH5TableReadRows()

int XLALH5TableReadRows	(	void UNUSED *	data,
		const LALH5Dataset UNUSED *	dset,
		const size_t UNUSED *	offsets,
		const size_t UNUSED *	colsz,
		size_t UNUSED	row0,
		size_t UNUSED	nrows,
		size_t UNUSED	rowsz
	)

Reads certain rows of table data from a LALH5Dataset.

This routine reads certain rows of table data from a HDF5 dataset associated with the LALH5Dataset dset and stores the data in the buffer data. This buffer should be sufficiently large to hold the requested nrows rows of the dataset, starting with row row0 (the first row is row 0), which is comprised of a number of rows each of size rowsz. Each row is comprised of a number of columns, which can be determined with the routine XLALH5TableQueryNColumns(). The offsets of the columns and the sizes of the columns in each row of data is provided by the arrays offsets and colsz respectively.

The following example shows how to read rows 2 to 5 inclusive (where the first row is row 0) of data from a table named particles.

#include <stddef.h>
#include <lal/LALStdlib.h>
#include <lal/LALH5FileIO.h>
 
struct body {REAL8 x; REAL8 y; REAL8 z; REAL8 vx; REAL8 vy; REAL8 vz;} data[4];
size_t offsets[] = {offsetof(struct body, x), offsetof(struct body, y), offsetof(struct body, z), offsetof(struct body, vx), offsetof(struct body, vy), offsetof(struct body, vz)};
size_t colsz[] = {sizeof(data->x), sizeof(data->y), sizeof(data->z), sizeof(data->vx), sizeof(data->vy), sizeof(data->vz)};
size_t rowsz = sizeof(*data);
size_t row0 = 2;
size_t nrows = sizeof(data)/sizeof(*data);
LALH5File *file = XLALH5FileOpen("example.h5", "r");
LALH5Dataset *dset = XLALH5DatasetRead(file, "particles");
XLALH5TableReadRows(data, dset, offsets, colsz, row0, nrows, rowsz);

Parameters

data	Pointer to a memory in which to store the data.
dset	Pointer to a LALH5Dataset from which to extract the data.
offsets	Pointer to an array of offsets for each column.
colsz	Pointer to an array of sizes of each column.
row0	The first row to read.
nrows	The Number of rows to read.
rowsz	Size of each row of data.

Return values

0	Success.
-1	Failure.

Definition at line 3461 of file H5FileIOLowLevel.c.

XLALH5TableReadColumns()

int XLALH5TableReadColumns	(	void UNUSED *	data,
		const LALH5Dataset UNUSED *	dset,
		const char UNUSED *	cols,
		const size_t UNUSED *	offsets,
		const size_t UNUSED *	colsz,
		size_t UNUSED	row0,
		size_t UNUSED	nrows,
		size_t UNUSED	rowsz
	)

Reads certain columns of table data from a LALH5Dataset.

This routine reads certain columns of table data from a HDF5 dataset associated with the LALH5Dataset dset and stores the data in the buffer data. This buffer should be sufficiently large to hold the requested rows of the dataset, which is comprised of a number of rows each of size rowsz. Each row is comprised of a number of columns which are named in the comma-separated list in string cols. The offsets of the columns and the sizes of the columns in each row of data is provided by the arrays offsets and colsz respectively.

The following example shows how to read rows 2 to 5 inclusive (where the first row is row 0) of certain columns of data from a table named particles.

#include <stddef.h>
#include <lal/LALStdlib.h>
#include <lal/LALH5FileIO.h>
 
struct position {REAL8 x; REAL8 y; REAL8 z;} data[4];
const char *cols = "x,y,z";
size_t offsets[] = {offsetof(struct position, x), offsetof(struct position, y), offsetof(struct position, z)};
size_t colsz[] = {sizeof(data->x), sizeof(data->y), sizeof(data->z)};
size_t rowsz = sizeof(*data);
size_t row0 = 2;
size_t nrows = sizeof(data)/sizeof(*data);
LALH5File *file = XLALH5FileOpen("example.h5", "r");
LALH5Dataset *dset = XLALH5DatasetRead(file, "particles");
XLALH5TableReadColumns(data, dset, cols, offsets, colsz, row0, nrows, rowsz);

Parameters

data	Pointer to a memory in which to store the data.
dset	Pointer to a LALH5Dataset from which to extract the data.
cols	Pointer to an string listing the column names separated by commas.
offsets	Pointer to an array of offsets for each column.
colsz	Pointer to an array of sizes of each column.
row0	The first row to read.
nrows	The Number of rows to read.
rowsz	Size of each row of data.

Return values

0	Success.
-1	Failure.

Definition at line 3519 of file H5FileIOLowLevel.c.

XLALH5TableQueryNRows()

size_t XLALH5TableQueryNRows

(

const LALH5Dataset UNUSED *

dset

)

Gets the number of rows in a LALH5Dataset containing table data.

Parameters

dset	Pointer to a LALH5Dataset containing table data to be queried.

Returns

The number of rows of table data in the HDF5 dataset associated with the specified LALH5Dataset.

Return values

(size_t)(-1)

Failure.

Definition at line 3541 of file H5FileIOLowLevel.c.

XLALH5TableQueryNColumns()

size_t XLALH5TableQueryNColumns

(

const LALH5Dataset UNUSED *

dset

)

Gets the number of columns in a LALH5Dataset containing table data.

Parameters

dset	Pointer to a LALH5Dataset containing table data to be queried.

Returns

The number of columns of table data in the HDF5 dataset associated with the specified LALH5Dataset.

Return values

(size_t)(-1)

Failure.

Definition at line 3565 of file H5FileIOLowLevel.c.

XLALH5TableQueryRowSize()

size_t XLALH5TableQueryRowSize

(

const LALH5Dataset UNUSED *

dset

)

Gets the number of bytes in a row in a LALH5Dataset containing table data.

Parameters

dset	Pointer to a LALH5Dataset containing table data to be queried.

Returns

The number of bytes of a row of data in the HDF5 dataset associated with the specified LALH5Dataset.

Return values

(size_t)(-1)

Failure.

Definition at line 3590 of file H5FileIOLowLevel.c.

XLALH5TableQueryColumnName()

int XLALH5TableQueryColumnName	(	char UNUSED *	name,
		size_t UNUSED	size,
		const LALH5Dataset UNUSED *	dset,
		int UNUSED	pos
	)

Gets the name of a column in a LALH5Dataset containing table data.

This routines gets the name of a column of data in a LALH5Dataset dset that contains table data. The index pos identifies which column's name is returned. The result is written into the buffer pointed to by name, the size of which is size bytes. If name is NULL, no data is copied but the routine returns the length of the string. Therefore, this routine can be called once to determine the amount of memory required, the memory can be allocated, and then it can be called a second time to read the string. If the parameter size is less than or equal to the string length then only $p size-1 bytes of the string are copied to the buffer name.

Note

The return value is the length of the string, not including the terminating NUL character; thus the buffer name should be allocated to be one byte larger.

Parameters

name	Pointer to a buffer into which the string will be written.
size	Size in bytes of the buffer into which the string will be written.
dset	Pointer to a LALH5Dataset containing table data to be queried.
pos	The index identifying which column of the table.

Return values

0	Success.
-1	Failure.

Definition at line 3634 of file H5FileIOLowLevel.c.

XLALH5TableQueryColumnSize()

size_t XLALH5TableQueryColumnSize	(	const LALH5Dataset UNUSED *	dset,
		int UNUSED	pos
	)

Gets the size in bytes of a column in a LALH5Dataset containing table data.

Parameters

dset	Pointer to a LALH5Dataset containing table data to be queried.
pos	The index identifying which column of the table.

Returns

The size in bytes of the specified column entry in the HDF5 dataset associated with the specified LALH5Dataset.

Return values

-1

Failure.

Definition at line 3673 of file H5FileIOLowLevel.c.

XLALH5TableQueryColumnType()

LALTYPECODE XLALH5TableQueryColumnType	(	const LALH5Dataset UNUSED *	dset,
		int UNUSED	pos
	)

Gets the type of data stored in a column in a LALH5Dataset containing table data.

Parameters

dset	Pointer to a LALH5Dataset containing table data to be queried.
pos	The index identifying which column of the table.

Returns

The LALTYPECODE of the datatype of the specified column entry in the HDF5 dataset associated with the specified LALH5Dataset.

Return values

-1

Failure.

Definition at line 3727 of file H5FileIOLowLevel.c.

XLALH5TableQueryColumnOffset()

size_t XLALH5TableQueryColumnOffset	(	const LALH5Dataset UNUSED *	dset,
		int UNUSED	pos
	)

Gets the offset of the data in a column in a LALH5Dataset containing table data.

Parameters

dset	Pointer to a LALH5Dataset containing table data to be queried.
pos	The index identifying which column of the table.

Returns

The offset of the specified column data in a row of data in the HDF5 dataset associated with the specified LALH5Dataset.

Return values

(size_t)(-1)

Failure.

Definition at line 3769 of file H5FileIOLowLevel.c.