DasVar Struct Reference

#include <das2/variable.h>

Inheritance diagram for DasVar:

Detailed Description

Das2 fexible variables.

Like arrays, das2 variables are objects which produce values given a set of indicies. Unlike arrays the indicies provided need not correspond to the actual layout of the data on the disk.

To illustrate the difference between arrays and das2 variables consider the following arrays containing a typical set of values for time, frequency, amplitude spectrogram.

*  double time[1440];       // Time values at which frequency sweeps were triggered
*  double frequency[42];    // Center frequencies for each energy channel
*  double energy[1440][42]; // Energies measured for each frequency band in each sweep
* 

So to get a correlated triplet of two coordinate values at index (14,34) would look like

*  x = time[14] 
*  y = frequency[34]
*  z = energy[14][34]
* 

In contrast if the time, frequency and energy data were stored in a correlated set of das2 variables accessing the values would look like this:

* DasVar* vTime = new_DasVarArry(time, [0,-1]);
* DasVar* vFrequency = new_DasVarArray(frequency, [-1,-0]);
* DasVar* vEnergy = new_DasVarArray(energy, [0, 1]);
* 
* // A correlated set is now:
*  x = fTime([14,34]);
*  y = fFreqency([14,34]);
*  z = fEnergy([14,34]);
* 

In addition to wrapping arrays, das2 variables may produce data via calculations involving other variables. For example:

* 
* // The premise here is that we are reading in an array of Mars Express 
* // spacecraft altitudes.  We know the delay timing for the MARSIS instrument
* // and need a way to get the altitude at which the radar return signal was
* // generated.  We'll assume that there is nothing to bounce off of near
* // the spacecraft except the planet below.  So the altitude at which the
* // signal was generated is just the craft altitude minus a range which is
* // calculated from the return time.
* 
* // Create a dynamic array of altitudes.  We don't know how big this will
* // get or how large it is any any moment.
* Array* pAltAry = new_DasAry("altitude", etDouble, 0, NULL, RANK_1(0));
* 
* // Create a fixed array of delay times.  There are 80 delay time measurements
* // of the MARSIS radar for each altitude.
* Array* pDelayAry = new_DasAry("delay", etDouble, 0, NULl, RANK_1(80));
* // Fill in array values here
* 
* // We want an automatic variable that will give us the altitude of the 
* // return signals no mater how many altitude values we get.  To do this
* // we need to do the calculation:
* //
* //  Signal_Altitude = Craft_Altitude - (Speed_of_Light/2) * Delay_Time
* //
* // on any altitude we happen to have.  Since we have a variable number of
* // altitudes but a fixed number of delay times it's natural to store these
* // values in a 2-index array, namely: 
* // 
* // Signal_Altitude[i][j] where i marks the altitude and j marks the delay.
* //
* // So we are going to use the MAP_2 macro to map real array indices into
* // virtual indexes.
* 
* // Map index 0 pAlt to index 0 of a Rank 2 index space
* DasVar* pAlt = new_DasVar_array(pAltAry, MAP_2(0, -1), Units_fromStr("km"));
* 
* // Map index 0 of pDelay to index 1 of a Rank 2 index space
* DasVar* pDelay = new_DasVar_array(pDelayAry, MAP_2(-1, 0), "μs");
* 
* // We need a constant. (Memory note, Variables copy the contents of the
* // constant internally so it's okay to initialize constants with stack
* // variables.)
* int nConst = 299792 / 2;
* DasVar* pConst = new_DasVar_const(etInt, &nConst, "km s**-1");
* 
* // Multiply the constant times the delay time to get the range.  Constants
* // always return the same value for any index provided, thus they can be
* // combined with anything.
* DasVar* pRange = DasVar_binaryOp(&pConst, "*", pDelay);
* 
* // Subtract the range from the spacecraft altitude.  Since vAlt and vDelay
* // have the same rank (due to index remapping) we can setup an element by
* // element binary operation
* DasVar* pSigAlt = DasVar_binaryOp( &pAlt, "-", &pRange);
*
* // Here's how to get data out of the resulting variable
* double sigHeight = DasVar_double(&vSigAlt, IDX2(1234, 77));
* 
* // The component variables are evaluated in the same index space
* double craftAlt = DasVar_double(&vAlt, IDX2(1234,77));
* double range = DasVar_double(&vRange, IDX2(1234,77));
* 
* // If the same set of data are going to be evaluated multiple times it
* // might be faster to just re-write all the internal data at a certain
* // point into a new array.
* DasVar* pEvalAlt = DasVar_evaluate(pSigAlt);
* 
* 

In the example above the variable tree was created manually. To support Das2.3 general streams expressions like the following will be parsable by the dataset object:

* 
* DasVar* pSigAlt; 
* pSigAlt = Dataset_eval(pDs, "$altitude[i] - (3.0e9 / 2)*delay[j]", "km" );
* 
* 
* 

Here a pointer can be returned because the Dataset object keeps

To keep variables light weight (especially constants) they use stack value semantics instead of heap value semantics. This is a pain because you can't just return variables from functions, as they may reference other variables and you end up with dangling pointers. On the other hand, using stack semantics results in less heap fragmentation and thus faster code on current processors. Also simultaneous data reads are thread safe. Writes can be too so long as different threads write to different index ranges.

See Also

Dataset

Dimension

Array

Public Member Functions
DasVar *	new_DasVarUnary (const char *sOp, const DasVar *pVar)
	Create a new variable from unary operation on an existing variable. More...
DasVar *	new_DasVarBinary (DasVar *pLeft, const char *sOp, DasVar *pRight)
	Create a new variable from a binary operation on two other variables. More...
DasVar *	new_DasConstant (das_val_type vt, size_t sz, const void *val, das_units units)
	Create a constant value on the heap. More...
DasVar *	new_DasVarSeq (const char *sId, das_val_type vt, size_t vSz, const void *pMin, const void *pInterval, int8_t *pMap, das_units units)
	Create a sequence variable. More...
DasVar *	new_DasVarArray (DasAry *pAry, int iInternal, int8_t *pMap)
	Create a function backed by an Array. More...
DasAry *	DasVarAry_getArray (DasVar *pThis)
	Get the backing array if present. More...
bool	DasVar_orthoginal (const DasVar *pThis, const DasVar *pOther)
	Getting data from a variable. More...
int	DasVar_shape (const DasVar *pThis, ptrdiff_t *pShape)
	Return the current shape of this variable. More...
bool	DasVar_getDatum (const DasVar *pThis, ptrdiff_t *pIdx, das_datum *pDatum)
	Get a value given an index. More...
bool	DasVar_isComposite (const DasVar *pVar)
	Is this a simple variable or more than one variable combinded via operators? More...
void	dec_DasVar (DasVar *pThis)
	Decrement the reference count on a variable. More...

Data Fields
bool(*	get )(const struct das_variable *pThis, ptrdiff_t *pIdx, das_datum *pDatum)
	Get a value at a specified index.
int(*	incRef )(struct das_variable *pThis)
	Increment the reference count for this variable and return the new count.
int(*	decRef )(struct das_variable *pThis)
	Returns the number of remaining references to this variable, if the reference count drops to 0, the structure is deleted and the reference count for any owned subvariables or arrays is decremented which may trigger further deletions.

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/variable.h