#include <das2/dataset.h>

Inheritance diagram for DasDs:

Detailed Description

Das2 Datasets.

Das2 Datasets provide storage for arrays that contains both data values and coordinate values. Coordinate and Data arrays are doubly abstracted away dimensions and then a variable. Each dataset corresponds to a single index space and all variable in the dataset support the same bulk index range, though they may not produce unique values for each distinct set of indices.

Mapping from the dataset index space to individual arrays is handled by variables (DasVar).

A typical dataset consisting of a Time dimension, Frequency dimension and Amplitude dimension may have the following index ranges:

    Time(i:0..152, j:-    )   // Defined in 1st index, any 2nd index is okay
    Freq(i:-,      j:0..1440) // Defined in 2nd index, any 1st index is okay
    Amp( i:0..152, j:0..1440) // Defined in both indices
* 

Here i is the first index and j is the second.

The first two dimensions define a time and frequency coordinates space, and the last provides amplitude values collected at over time and frequency.

Todo:: explain variables in dimensions and point-spreads

Binning these values could proceed in a loops such as described in the the ::DasDs_lengthLast function.

Public Member Functions
DasDs *	new_DasDs (const char sId, const char sGroupId, int nRank)
	Create a new dataset object. More...

void	del_DasDs (DasDs *pThis)
	Delete a Correlated Data object, cleaning up it's memory. More...

int	DasDs_shape (const DasDs pThis, ptrdiff_t pShape)
	Return current valid ranges for whole data set iteration. More...

bool	DasDs_addAry (DasDs pThis, DasAry pAry)
	Add an array to the dataset, stealing it's reference. More...

DasDim *	DasDs_makeDim (DasDs pThis, enum dim_type dType, const char sId)
	Make a new dimension within this dataset. More...

const char *	DasDs_group (const DasDs *pThis)
	Get the data set group id. More...

size_t	DasDs_numDims (const DasDs *pThis, enum dim_type vt)
	Get the number of physical dimensions in this dataset. More...

const DasDim *	DasDs_getDim (const DasDs *pThis, size_t idx, enum dim_type vt)
	Get a dimension by index. More...

DasDim *	DasDs_getDimById (DasDs pThis, const char sId)
	Get a dimension by string id. More...

Descriptor Functions
These work for any type of Descriptor, including PlaneDesc , PktDesc, StreamDesc, DasDs and DasVar. To make your compiler happy you will need to cast Plane, Packet and Stream Descriptor pointers to just the generic type of Descriptor pointer when using these functions. For example: * PktDesc* pPktDesc; * hasProperty((Descriptor)pPktDesc, "SomePropName"); DasDesc
bool	DasDesc_equals (const DasDesc pOne, const DasDesc pTwo)
	Check to see if two descriptors contain the same properties Note, the order of the properties may be different between the descriptors but if the contents are the same then the descriptors are considered to be equal. More...

const DasDesc *	DasDesc_parent (DasDesc *pThis)
	The the parent of a Descriptor. More...

size_t	DasDesc_length (const DasDesc *pThis)
	Get the number of properties in a descriptor. More...

const char *	DasDesc_getNameByIdx (const DasDesc *pThis, size_t uIdx)
	Get a property name by an index. More...

const char *	DasDesc_getValByIdx (const DasDesc *pThis, size_t uIdx)
	Get a property value by an index. More...

const char *	DasDesc_getTypeByIdx (const DasDesc *pThis, size_t uIdx)
	Get a data type of a property by an index.

bool	DasDesc_has (const DasDesc pThis, const char propertyName)
	Determine if a property is present in a Descriptor or it's ancestors. More...

DasErrCode	DasDesc_set (DasDesc pThis, const char sType, const char sName, const char sVal)
	Generic property setter. More...

bool	DasDesc_remove (DasDesc pThis, const char propretyName)
	Remove a property from a descriptor, if preset. More...

const char *	DasDesc_getStr (const DasDesc pThis, const char propertyName)
	read the property of type String named propertyName.

DasErrCode	DasDesc_setStr (DasDesc pThis, const char sName, const char *sVal)
	SetProperty methods add properties to any Descriptor (stream,packet,plane). More...

DasErrCode	DasDesc_vSetStr (DasDesc pThis, const char sName, const char *sFmt,...)
	Set a string property in the manner of sprintf.

double	DasDesc_getDouble (const DasDesc pThis, const char propertyName)
	Read the property of type double named propertyName. More...

DasErrCode	DasDesc_setDouble (DasDesc pThis, const char propertyName, double value)
	Set property of type double.

double	DasDesc_getDatum (DasDesc pThis, const char sPropName, das_units units)
	Get the a numeric property in the specified units. More...

DasErrCode	DasDesc_setDatum (DasDesc pThis, const char sName, double rVal, das_units units)
	Set property of type Datum (double, UnitType pair) More...

double *	DasDesc_getDoubleAry (DasDesc pThis, const char propertyName, int *nitems)
	Get the values of an array property. More...

DasErrCode	DasDesc_setDoubleArray (DasDesc pThis, const char propertyName, int nitems, double *value)
	Set the property of type double array.

int	DasDesc_getInt (const DasDesc pThis, const char propertyName)
	Get a property integer value. More...

DasErrCode	DasDesc_setInt (DasDesc pThis, const char sName, int nVal)
	Set the property of type int.

bool	DasDesc_getBool (DasDesc pThis, const char sPropName)
	Get a property boolean value. More...

DasErrCode	DasDesc_setDatumRng (DasDesc pThis, const char sName, double beg, double end, das_units units)
	Set property of type DatumRange (double, double, UnitType triple)

DasErrCode	DasDesc_getStrRng (DasDesc pThis, const char sName, char sMin, char sMax, das_units *pUnits, size_t uLen)
	Get a property of type DatumRange with unconverted strings. More...

DasErrCode	DasDesc_setFloatAry (DasDesc pThis, const char propertyName, int nitems, float *value)
	Set the property of type float array. More...

void	DasDesc_copyIn (DasDesc pThis, const DasDesc source)
	Deepcopy properties into a descriptor. More...

DasErrCode	DasDesc_encode (DasDesc pThis, DasBuf pBuf, const char *sIndent)
	Encode a generic set of properties to a buffer. More...

Member Function Documentation

bool DasDesc_equals	(	const DasDesc *	pOne,
		const DasDesc *	pTwo
	)

inherited

Check to see if two descriptors contain the same properties Note, the order of the properties may be different between the descriptors but if the contents are the same then the descriptors are considered to be equal.

Note that parent descriptor properties are not checked when handling the comparison.

Todo:: maybe check parents too.

Parameters

pOne	The first descriptor
pTwo	The second descriptor

const DasDesc * DasDesc_parent ( DasDesc * pThis )

inherited

The the parent of a Descriptor.

Plane descriptors are owned by packet descriptors and packet descriptors are owned by stream descriptors. This function lets you craw the ownership hierarchy

Parameters

pThis

Returns: The owner of a descriptor, or NULL if this is a top level descriptor, (i.e. a Stream Descriptor)

size_t DasDesc_length ( const DasDesc * pThis )

inherited

Get the number of properties in a descriptor.

Descriptor's have a hierarchy. In general when a property is requested, if a given Descriptor does not have a property the request is passed to the parent descriptor. This function only returns the number of properties in the given descriptor. It does not include properties owned by parents or ancestors.

This is useful when iterating over all properties in a descriptor.

See Also: DasDesc_getNameByIdx(); DasDesc_getValByIdx(); DasDesc_getTypeByIdx()

Parameters

pThis A pointer to the descriptor to query

Returns: The number of properties in this, and only this, descriptor.

const char * DasDesc_getNameByIdx	(	const DasDesc *	pThis,
		size_t	uIdx
	)

inherited

Get a property name by an index.

This is useful when iterating over all properties in a Descriptor. Only properties owed by a descriptor are queried in this manner. Parent descriptors are not consulted.

See Also: DasDesc_length()

Parameters

pThis	A pointer to the descriptor to query
uIdx	The index of the property, will be a value between 0 and the return value from Desc_getNProps()

Returns: A pointer the requested property name or NULL if there is no property at the given index.

const char * DasDesc_getValByIdx	(	const DasDesc *	pThis,
		size_t	uIdx
	)

inherited

Get a property value by an index.

This is useful when iterating over all properties in a Descriptor. Only properties owned by a descriptor are queried in this manner. Parent descriptors are not consulted.

See Also: DasDesc_length()

Parameters

pThis	A pointer to the descriptor to query
uIdx	The number of the property, will be a value from 0 and 1 less than the return value from Desc_getNProps()

Returns: A pointer the requested property value or NULL if there is no property at the given index.

bool DasDesc_has	(	const DasDesc *	pThis,
		const char *	propertyName
	)

inherited

Determine if a property is present in a Descriptor or it's ancestors.

Parameters

pThis	the descriptor object to query
propertyName	the name of the property to retrieve.

Returns: true if the descriptor or one of it's ancestors has a property with the given name, false otherwise.

DasErrCode DasDesc_set	(	DasDesc *	pThis,
		const char *	sType,
		const char *	sName,
		const char *	sVal
	)

inherited

Generic property setter.

All properties are stored internally as strings. The various typed Desc_setProp* functions all call this function after converting their arguments to strings.

Warning: To insure that the string to type conversions are consistent it is strongly recommended that you use one of the typed functions instead of this generic version unless you have no choice.

Parameters

pThis	The Descriptor to receive the property
sType	The Type of property should be one of the strings: boolean double doubleArray Datum DatumRange int String Time TimeRange
sName	The property name, which cannot contain spaces
sVal	The value, which may be anything including NULL

Returns: 0 on success or a positive error code if there is a problem.

bool DasDesc_remove	(	DasDesc *	pThis,
		const char *	propretyName
	)

inherited

Remove a property from a descriptor, if preset.

It is safe to call this function for properties not present on the descriptor, it simply does nothing and returns false.

Returns: false if the property wasn't present to begin with, true otherwise

DasErrCode DasDesc_setStr	(	DasDesc *	pThis,
		const char *	sName,
		const char *	sVal
	)

inherited

SetProperty methods add properties to any Descriptor (stream,packet,plane).

The typed methods (e.g. setPropertyDatum) property tag the property with a type so that it will be parsed into the given type.

double DasDesc_getDouble	(	const DasDesc *	pThis,
		const char *	propertyName
	)

inherited

Read the property of type double named propertyName.

The property value is parsed using sscanf.

double DasDesc_getDatum	(	DasDesc *	pThis,
		const char *	sPropName,
		das_units	units
	)

inherited

Get the a numeric property in the specified units.

Descriptor properties my be provided as Datums. Datums are a double value along with a specified measurement unit.

Parameters

pThis	The Descriptor containing the property in question.
sPropName	The name of the property to retrieve.
units	The units of measure in which the return value will be represented. If the property value is stored in a different set of units than those indicated by this parameter than the output will be converted to the given unit type.

Returns: The converted value or DAS_FILL_VALUE if conversion to the desired units is not possible.

DasErrCode DasDesc_setDatum	(	DasDesc *	pThis,
		const char *	sName,
		double	rVal,
		das_units	units
	)

inherited

Set property of type Datum (double, UnitType pair)

If a property with this name already exists it is 1st deleted and then the new property is added in its place.

Parameters

pThis	The descriptor to receive the property
sName	The name of the property to set
rVal	The numeric value of the property
units	The units of measure for the property

double * DasDesc_getDoubleAry	(	DasDesc *	pThis,
		const char *	propertyName,
		int *	nitems
	)

inherited

Get the values of an array property.

Space for the array is allocated by getDoubleArrayFromString. and nitems is set to indicate the size of the array.

Parameters

[in]	pThis	the descriptor object to query
[in]	propertyName	the name of the proprety to retrieve
[out]	nitems	a pointer to a an integer containing the number of values in the returned array.

Returns: A pointer to a double array allocated on the heap. It is the caller's responsibility to depose of the memory when it is no longer needed. If the named property doesn't exist the program exits.

See Also: hasProperty()

int DasDesc_getInt	(	const DasDesc *	pThis,
		const char *	propertyName
	)

inherited

Get a property integer value.

Parameters

pThis	the descriptor object to query
propertyName	the name of the proprety to retrieve

Returns: The value of the named property or exits the program if the named proprety doesn't exist in this descriptor.

See Also: hasProperty()

bool DasDesc_getBool	(	DasDesc *	pThis,
		const char *	sPropName
	)

inherited

Get a property boolean value.

Parameters

pThis	the descriptor object to query
sPropName	the name of the proprety to retrieve

Returns: True if the value is "true", or any positive integer, false otherwise.

DasErrCode DasDesc_getStrRng	(	DasDesc *	pThis,
		const char *	sName,
		char *	sMin,
		char *	sMax,
		das_units *	pUnits,
		size_t	uLen
	)

inherited

Get a property of type DatumRange with unconverted strings.

This version is handy if you just want to know the intrinsic units of the range without converting the values to some specific type of double value.

DasErrCode DasDesc_setFloatAry	(	DasDesc *	pThis,
		const char *	propertyName,
		int	nitems,
		float *	value
	)

inherited

Set the property of type float array.

Note the array is cast to a double array before encoding.

void DasDesc_copyIn	(	DasDesc *	pThis,
		const DasDesc *	source
	)

inherited

Deepcopy properties into a descriptor.

Parameters

pThis	the descriptor to receive a copy of the properties
source	the descriptor with the properties to be copied.

DasErrCode DasDesc_encode	(	DasDesc *	pThis,
		DasBuf *	pBuf,
		const char *	sIndent
	)

inherited

Encode a generic set of properties to a buffer.

Parameters

pThis	The descriptors who's properties should be encoded
pBuf	A buffer object to receive the XML data
sIndent	An indent level for the property strings, makes 'em look nice

Returns: 0 if the operation succeeded, a non-zero return code otherwise.

The documentation for this struct was generated from the following file:

das2/dataset.h

Detailed Description

Public Member Functions

Descriptor Functions

Member Function Documentation