C-Munipack 1.2 / Application programming interface / API reference

Functions for reading and writing output data files (tables).

cmpack_table.h

Enumerations

CmpackTableType	Table type identifiers.
CmpackColumnType	Column type identifier.

Type definitions

CmpackTable	Table context.
CmpackTabColumn	Table column context.

Functions

cmpack_tab_init	Create a new table context.
cmpack_tab_load	Load a table from a file.
cmpack_tab_save	Save a table to a file.
cmpack_tab_clear	Clear table definition, header and data.
cmpack_tab_copy	Copy a table.
cmpack_tab_set_type	Set table type.
cmpack_tab_get_type	Get table type.
cmpack_tab_test	Check if the file is a table.
cmpack_tab_test_buffer	Test if the content of the buffer might be a table.
cmpack_tab_pkys	Set parameter value in file header (string).
cmpack_tab_pkyi	Set parameter value in file header (integer).
cmpack_tab_pkyd	Set parameter value in file header (integer).
cmpack_tab_gkys	Get value of parameter in file header (string).
cmpack_tab_gkyi	Get value of parameter in file header (integer).
cmpack_tab_gkyd	Get value of parameter in file header (double).
cmpack_tab_nkey	Get number of parameters in file header.
cmpack_tab_gkyn	Get the parameter from file header by its index.
cmpack_tab_dkey	Delete parameter from file header.
cmpack_tab_ncolumns	Get number of columns.
cmpack_tab_add_column	Append new column to the table.
cmpack_tab_get_column	Get column by its index.
cmpack_tab_find_column	Find column by its name.
cmpack_tab_column_set_name	Set column name.
cmpack_tab_column_get_name	Get column name.
cmpack_tab_nrows	Get number of rows in the table.
cmpack_tab_add_row	Append a new row to the table.
cmpack_tab_ptds	Set table data (string).
cmpack_tab_ptdi	Set table data (integer).
cmpack_tab_ptdd	Set table data (real number).
cmpack_tab_gtds	Get table data (string).
cmpack_tab_gtdi	Get table data (integer).
cmpack_tab_gtdd	Get table data (double).

Description

Output data files contain data in form of table. It is used for storing light curves, track lists, etc.

Use cmpack-list object to process a set of photometry files and make output data. This format was inherited from original Munipack, but it's been extended to support saving a set of parameters (file header).

CmpackTable (data type)

Table context.

Synopsis

typedef struct _CmpackTable CmpackTable

Description

This private structure holds the table header and data

CmpackTabColumn (data type)

Table column context.

Synopsis

typedef struct _CmpackTabColumn CmpackTabColumn

Description

This private structure holds the information about table column

CmpackTableType (enumeration)

Table type identifiers.

Synopsis

enum CmpackTableType
{
     CMPACK_TABLE_UNSPECIFIED,
     CMPACK_TABLE_LIGHTCURVE,
     CMPACK_TABLE_MUNIFIND,
     CMPACK_TABLE_TRACKLIST,
     CMPACK_TABLE_APERTURES,
     CMPACK_TABLE_AIRMASS
};

Enumerators

CMPACK_TABLE_UNSPECIFIED	Unspecified type.
CMPACK_TABLE_LIGHTCURVE	Light curve.
CMPACK_TABLE_MUNIFIND	Mag-dev graph, result of the Munifind tool.
CMPACK_TABLE_TRACKLIST	Track-list, frame offsets.
CMPACK_TABLE_APERTURES	Apertures and standard deviations.
CMPACK_TABLE_AIRMASS	Air-mass coefficients.

CmpackColumnType (enumeration)

Column type identifier.

Synopsis

enum CmpackColumnType
{
     CMPACK_COLUMN_STRING,
     CMPACK_COLUMN_INTEGER,
     CMPACK_COLUMN_DOUBLE
};

Enumerators

CMPACK_COLUMN_STRING	Unspecified type.
CMPACK_COLUMN_INTEGER	Identifier of a star, an aperture, .
CMPACK_COLUMN_DOUBLE	Julian date.

cmpack_tab_init (function)

Create a new table context.

Synopsis

CmpackTable * cmpack_tab_init (CmpackTableType type)

Description

This function makes an empty table

Return value

new reference to a table context

cmpack_tab_load (function)

Load a table from a file.

Synopsis

int cmpack_tab_load (CmpackTable ** tab, const char * filename, CmpackLoadMode flags)

Parameters

tab	`[out]`	new table context
filename	`[in]`	path + file name
flags	`[in]`	flags (see CMPACK_LOAD_xxx constants)

Return value

zero on success, error code on failure

cmpack_tab_save (function)

Save a table to a file.

Synopsis

int cmpack_tab_save (CmpackTable * tab, const char * filename)

Parameters

tab	`[in]`	table context
filename	`[in]`	path + file name

Return value

zero on success, error code on failure

cmpack_tab_clear (function)

Clear table definition, header and data.

Synopsis

void cmpack_tab_clear (CmpackTable * tab)

Description

Deletes all information stored in a table context

Parameters

tab [in] table context

cmpack_tab_copy (function)

Copy a table.

Synopsis

void cmpack_tab_copy (CmpackTable * dsttab, const CmpackTable * srctab)

Description

Makes a copy of source table to the destination table. All content of the destination table will be deleted.

Parameters

dsttab	`[in]`	destination table context
srctab	`[in]`	source table context

cmpack_tab_set_type (function)

Set table type.

Synopsis

void cmpack_tab_set_type (CmpackTable * tab, CmpackTableType type)

Parameters

tab	`[in]`	table context
type	`[in]`	table type identifier

cmpack_tab_get_type (function)

Get table type.

Synopsis

CmpackTableType cmpack_tab_get_type (CmpackTable * tab)

Description

This function returns the type of the table

Return value

the integer value that represents the type of the table

cmpack_tab_test (function)

Check if the file is a table.

Synopsis

int cmpack_tab_test (const char * filename)

Parameters

filename [in] path + file name

Return value

nonzero if the file is a table, zero otherwise

cmpack_tab_test_buffer (function)

Test if the content of the buffer might be a table.

Synopsis

int cmpack_tab_test_buffer (const char * buffer, int buflen, int filesize)

Description

The function checks the data in the buffer and returns nonzero, when the buffer contain first 'buflen' bytes from a table. This function is used for file format autodetection.

Return value

nonzero if the file is a photometry file, zero otherwise

cmpack_tab_pkys (function)

Set parameter value in file header (string).

Synopsis

void cmpack_tab_pkys (CmpackTable * tab, const char * key, const char * val)

Description

If the parameter does not exist, it makes new entry in the file header. If the parameter exists, its content is changed. Keys are case sensitive.

Parameters

tab	`[in]`	table context
key	`[in]`	parameter name
val	`[in]`	parameter value

Return value

zero on success, error code on failure

cmpack_tab_pkyi (function)

Set parameter value in file header (integer).

Synopsis

void cmpack_tab_pkyi (CmpackTable * tab, const char * key, int val)

Description

If the parameter does not exist, it makes new entry in the file header. If the parameter exists, its content is changed. Keys are case sensitive.

Parameters

tab	`[in]`	table context
key	`[in]`	parameter name
val	`[in]`	parameter value

Return value

zero on success, error code on failure

cmpack_tab_pkyd (function)

Set parameter value in file header (integer).

Synopsis

void cmpack_tab_pkyd (CmpackTable * tab, const char * key, double val, int prec)

Description

If the parameter does not exist, it makes new entry in the file header. If the parameter exists, its content is changed. Keys are case sensitive.

Parameters

tab	`[in]`	table context
key	`[in]`	parameter name
val	`[in]`	parameter value
prec	`[in]`	number of decimal places

Return value

zero on success, error code on failure

cmpack_tab_gkys (function)

Get value of parameter in file header (string).

Synopsis

const char * cmpack_tab_gkys (CmpackTable * tab, const char * key)

Description

The val parameters receives the pointer to newly allocated memory buffer. The caller is responsible to free it by calling of cmpack_free() function. Keys are case sensitive. You can set the output parameter to NULL if you want to test the value only.

Parameters

tab	`[in]`	table context
key	`[in]`	parameter name

Return value

pointer to internal buffer or NULL on failure

cmpack_tab_gkyi (function)

Get value of parameter in file header (integer).

Synopsis

int cmpack_tab_gkyi (CmpackTable * tab, const char * key, int defval)

Description

Keys are case sensitive.

Parameters

tab	`[in]`	table context
key	`[in]`	parameter name
defval	`[in]`	default value

Return value

parameter value on success, default value on failure

cmpack_tab_gkyd (function)

Get value of parameter in file header (double).

Synopsis

double cmpack_tab_gkyd (CmpackTable * tab, const char * key, double defval)

Description

Keys are case sensitive.

Parameters

tab	`[in]`	table context
key	`[in]`	parameter name
defval	`[in]`	default value

Return value

zero on success, error code on failure

cmpack_tab_nkey (function)

Get number of parameters in file header.

Synopsis

int cmpack_tab_nkey (CmpackTable * tab)

Parameters

tab [in] table context

Return value

number of parameter or zero if the file is not valid context or if the header is empty.

cmpack_tab_gkyn (function)

Get the parameter from file header by its index.

Synopsis

int cmpack_tab_gkyn (CmpackTable * tab, int index, const char ** key, const char ** val)

Description

Index of the first parameter is zero. The output parameters receive the pointers to newly allocated memory buffers. The caller is responsible to free it by calling of cmpack_free() function. You can set the value of output parameter to NULL if you do not need to read it.

Parameters

tab	`[in]`	table context
index	`[in]`	parameter index (starting by zero)
key	`[out]`	parameter name (can be NULL)
val	`[out]`	parameter value (can be NULL)

Return value

zero on success, error code on failure

cmpack_tab_dkey (function)

Delete parameter from file header.

Synopsis

void cmpack_tab_dkey (CmpackTable * tab, const char * key)

Description

Keys are case sensitive.

Parameters

tab	`[in]`	table context
key	`[in]`	parameter name

cmpack_tab_ncolumns (function)

Get number of columns.

Synopsis

int cmpack_tab_ncolumns (CmpackTable * tab)

Parameters

tab [in] table context

Return value

number of columns or zero if the table is not valid context or if it is empty.

cmpack_tab_add_column (function)

Append new column to the table.

Synopsis

int cmpack_tab_add_column (CmpackTable * tab, const char * name, CmpackColumnType type, int prec)

Parameters

tab	`[in]`	table context
name	`[in]`	column name
type	`[in]`	data type
prec	`[in]`	number of places after the decimal point

Return value

index of new column or negative value on failure

cmpack_tab_get_column (function)

Get column by its index.

Synopsis

CmpackTabColumn * cmpack_tab_get_column (CmpackTable * tab, int index)

Parameters

tab	`[in]`	table context
index	`[in]`	column index

Return value

new reference to table column

cmpack_tab_find_column (function)

Find column by its name.

Synopsis

int cmpack_tab_find_column (CmpackTable * tab, const char * name)

Parameters

tab	`[in]`	table context
name	`[in]`	column name

Return value

index of table column or negative value on failure

cmpack_tab_column_set_name (function)

Set column name.

Synopsis

void cmpack_tab_column_set_name (CmpackTabColumn * col, const char * name)

Description

The function returns pointer to the internal structure. You must not call the cmpack_free() function to it.

Parameters

col	`[in]`	column context
name	`[in]`	new column name

cmpack_tab_column_get_name (function)

Get column name.

Synopsis

const char * cmpack_tab_column_get_name (CmpackTabColumn * col)

Description

The function returns pointer to the internal structure. You must not call the cmpack_free() function to it.

Parameters

col [in] column context

Return value

pointer to the column name

cmpack_tab_nrows (function)

Get number of rows in the table.

Synopsis

int cmpack_tab_nrows (CmpackTable * tab)

Parameters

tab [in] table context

Return value

If context is not valid or contains no data, returns zero

cmpack_tab_add_row (function)

Append a new row to the table.

Synopsis

int cmpack_tab_add_row (CmpackTable * tab)

Description

The function appends a new row to the end of the table

Parameters

tab [in] table context

Return value

index of new row or negative number on failure

cmpack_tab_ptds (function)

Set table data (string).

Synopsis

void cmpack_tab_ptds (CmpackTable * tab, int row, int col, const char * val)

Description

The function modifies table data in specified row and column.

Parameters

tab	`[in]`	table context
row	`[in]`	row index
col	`[in]`	column index
val	`[in]`	new value

Return value

zero on success, error code on failure.

cmpack_tab_ptdi (function)

Set table data (integer).

Synopsis

void cmpack_tab_ptdi (CmpackTable * tab, int row, int col, int val)

Description

The function modifies table data in specified row and column.

Parameters

tab	`[in]`	table context
row	`[in]`	row index
col	`[in]`	column index
val	`[in]`	new value

Return value

zero on success, error code on failure.

cmpack_tab_ptdd (function)

Set table data (real number).

Synopsis

void cmpack_tab_ptdd (CmpackTable * tab, int row, int col, double val)

Description

The function modifies table data in specified row and column.

Parameters

tab	`[in]`	table context
row	`[in]`	row index
col	`[in]`	column index
val	`[in]`	new value

Return value

zero on success, error code on failure.

cmpack_tab_gtds (function)

Get table data (string).

Synopsis

int cmpack_tab_gtds (CmpackTable * tab, int row, int col, char ** val)

Parameters

tab	`[in]`	table context
row	`[in]`	row index
col	`[in]`	column index
val	`[out]`	pointer to internal buffer

Return value

nonzero on success, zero on failure

cmpack_tab_gtdi (function)

Get table data (integer).

Synopsis

int cmpack_tab_gtdi (CmpackTable * tab, int row, int col, int * val)

Parameters

tab	`[in]`	table context
row	`[in]`	row index
col	`[in]`	column index
val	`[out]`	value

Return value

nonzero on success, zero on failure

cmpack_tab_gtdd (function)

Get table data (double).

Synopsis

int cmpack_tab_gtdd (CmpackTable * tab, int row, int col, double * val)

Parameters

tab	`[in]`	table context
row	`[in]`	row index
col	`[in]`	column index
val	`[out]`	value

Return value

nonzero on success, zero on failure