Classes and functions for storing and manipulating correlated data values. More...

Detailed Description

Classes and functions for storing and manipulating correlated data values.

Data Structures
struct	DasAry
	Dynamic recursive ragged arrays. More...

struct	DasDs
	Das2 Datasets. More...

struct	dasds_iterator
	Dataset iterator structure. More...

struct	DasDim
	Das2 Physical Dimensions. More...

struct	DasVar
	Das2 fexible variables. More...

class	Builder
	Builds datasets from a das2 stream. More...

Macros
#define	DasDs_rank(P) P->nRank
	Get the rank of a dataset.

Functions
ptrdiff_t	DasDs_lengthIn (const DasDs pThis, int nIdx, ptrdiff_t pLoc)
	Return the current max value index value + 1 for any partial index. More...

int	DasDs_copyInProps (DasDs pThis, const DasDesc pOther)
	Copy in dataset properties from some other descriptor. More...

char *	DasDs_toStr (const DasDs pThis, char sBuf, int nLen)
	Print a string reprenestation of this dataset. More...

ptrdiff_t	DasDim_lengthIn (const DasDim pThis, int nIdx, ptrdiff_t pLoc)
	Return the current max value index value + 1 for any partial index. More...

int	das_op_unary (const char *sOp)
	Convert a string into a unary operator token. More...

int	das_op_binary (const char *sOp)
	Convert a string into a binary operator token. More...

const char *	das_op_toStr (int nOp, int *pos)
	Provide a string representation of an operator token and an indication of where the operator normally appears. More...

bool	das_op_isBinary (int nOp)
	Return true if this is a binary operation, false otherwise.

bool	das_op_isUnary (int nOp)
	Return true if op is a unary operation, false otherwise.

DasVar *	new_DasVarEval (const DasVar *pVar)
	Evaluate all sub-variable expressions and a single array variable.

ptrdiff_t	DasVar_lengthIn (const DasVar pThis, int nIdx, ptrdiff_t pLoc)
	Return the current max value index value + 1 for any partial index. More...

char *	DasVar_toStr (const DasVar pThis, char sBuf, int nLen)
	Get a string representation of this variable. More...

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...

void	dasds_iter_init (dasds_iterator pIter, const DasDs pDs)
	Initialize a const dataset iterator. More...

bool	dasds_iter_next (dasds_iterator *pIter)
	Increment the iterator's index by one position, rolling as needed at data boundaries. 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...

DasDim *	new_DasDim (const char *sId, enum dim_type dtype, int nRank)
	Create a new dimension (not as impressive as it sounds) More...

const char *	DasDim_id (const DasDim *pThis)
	Get the dimension's id. More...

char *	DasDim_toStr (const DasDim pThis, char sBuf, int nLen)
	Print an information string describing a dimension. More...

int	DasDim_copyInProps (DasDim pThis, char cAxis, const DasDesc pOther)
	Copy in dataset properties from some other descriptor. More...

bool	DasDim_addVar (DasDim pThis, const char sRole, DasVar *pVar)
	Add a variable to a dimension. More...

const DasVar *	DasDim_getVar (const DasDim pThis, const char sRole)
	Get a variable providing values for a particular role in the dimension. More...

const DasVar *	DasDim_getPointVar (const DasDim *pThis)
	Get a variable poviding single point values in a dimension. More...

DasVar *	DasDim_popVar (DasDim pThis, const char role)
	Remove a variable by role from a dimensions. More...

void	del_DasDim (DasDim *pThis)
	Delete a dimension and drop the reference count on all contained variables. More...

int	DasDim_shape (const DasDim pThis, ptrdiff_t pShape)
	Get the maximum extent of this dimension in index space. More...

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...

Function Documentation

ptrdiff_t DasDs_lengthIn	(	const DasDs *	pThis,
		int	nIdx,
		ptrdiff_t *	pLoc
	)

Return the current max value index value + 1 for any partial index.

This is a more general version of DasDim_shape that works for both cubic arrays and with ragged dimensions, or sequence values.

Parameters

pThis	A pointer to a DasDim structure
nIdx	The number of location indices which may be less than the number needed to specify an exact value.
pLoc	A list of values for the previous indexes, must be a value greater than or equal to 0

Returns: The number of sub-elements at this index location or D2IDX_UNUSED if this variable doesn't depend on a given location, or D2IDx_FUNC if this variable returns computed results for this location

See Also: DasAry_lengthIn

int DasDs_copyInProps	(	DasDs *	pThis,
		const DasDesc *	pOther
	)

Copy in dataset properties from some other descriptor.

This is a helper for das 2.2 streams.

Any properties that don't start with a specific dimension identifier i.e. 'x','y','z','w' are copied into this dataset's properties dictionary. Only properties not present in the internal dictionary are copied in.

Parameters

pThis	this dataset object
pOther	The descriptor containing properites to copy in

Returns: The number of properties copied in

char* DasDs_toStr	(	const DasDs *	pThis,
		char *	sBuf,
		int	nLen
	)

Print a string reprenestation of this dataset.

Note: Datasets can be complicated items provide a good sized buffer (~1024 bytes), when calling this function as it triggers subcalls for all the compontent toStr as well

ptrdiff_t DasDim_lengthIn	(	const DasDim *	pThis,
		int	nIdx,
		ptrdiff_t *	pLoc
	)

Return the current max value index value + 1 for any partial index.

This is a more general version of DasDim_shape that works for both cubic arrays and with ragged dimensions, or sequence values.

Parameters

pThis	A pointer to a DasDim strutcture
nIdx	The number of location indices which may be less than the number needed to specify an exact value.
pLoc	A list of values for the previous indexes, must be a value greater than or equal to 0

Returns: The number of sub-elements at this index location or D2IDX_UNUSED if this variable doesn't depend on a given location, or D2IDx_FUNC if this variable returns computed results for this location

See Also: DasAry_lengthIn

int das_op_unary ( const char * sOp )

Convert a string into a unary operator token.

Parameters

sOp	a string such as "-", "sqrt", etc.

Returns: an operator token id or 0 if the string did not corespond to a known unary operator

int das_op_binary ( const char * sOp )

Convert a string into a binary operator token.

Parameters

sOp	a string such as "+", "-", "", "/", "*", "^" etc.

Returns: an operator token id or 0 if the string did not corespond to a known unary operator

const char* das_op_toStr	(	int	nOp,
		int *	pos
	)

Provide a string representation of an operator token and an indication of where the operator normally appears.

Parameters

nOp	The operator token value
pos	a pointer to an integer to receive one of the values D2OP_BEFORE, D2OP_BETWEEN or D2OP_AFTER. If pos is NULL the operator position is not set.

Returns: A pointer to a character representation of the operator or NULL if the token nOp is unknown.

ptrdiff_t DasVar_lengthIn	(	const DasVar *	pThis,
		int	nIdx,
		ptrdiff_t *	pLoc
	)

Return the current max value index value + 1 for any partial index.

This is a more general version of DasVar_shape that works for both cubic arrays and with ragged dimensions, or sequence values.

Parameters

pThis	A pointer to a DasVar structure
nIdx	The number of location indices which may be less than the number needed to specify an exact value.
pLoc	A list of values for the previous indexes, must be a value greater than or equal to 0

Returns: The number of sub-elements at this index location or D2IDX_UNUSED if this variable doesn't depend on a given location, or D2IDx_FUNC if this variable returns computed results for this location

See Also: DasAry_lengthIn

char* DasVar_toStr	(	const DasVar *	pThis,
		char *	sBuf,
		int	nLen
	)

Get a string representation of this variable.

Parameters

pThis	a pointer to variable in question
sBuf	a buffer to hold the output, 128 bytes should be more than enough unless describing a deeply nested set of binary operation variables are preset.
nLen	the length of the string buffer. This function will not write more than nLen - 1 bytes to the buffer and will insure NULL termination

DasDs * new_DasDs	(	const char *	sId,
		const char *	sGroupId,
		int	nRank
	)

Create a new dataset object.

Parameters

sId	An identifier for this dataset should be unique within a group but this requirement is not yet enforced.
sGroupId	An identifier for the group to which the dataset belongs. Datasets within a group can be plotted in the same physical dimensions, though the index shape need not be the same in any respect.

Said another way, datasets in the same group must have the same number of coordinate and data dimensions and the units of corresponding variables in the datasets should be identical, or at least inter-convertible.

Parameters

nRank The overall iteration rank for the dataset, i.e. the number of indicies needed to retrive values from this dataset's variables. ALL variables in a dateset accept the same number of indices in the same relative positions when reading values.

Unlike ISTP CDF's, rank is an iteration property and has no defined relationship to the number of physical dimensions of the dataset. Thus two datasets may have different ranks but be part of the same group.

Returns

void del_DasDs ( DasDs * pThis )

Delete a Correlated Data object, cleaning up it's memory.

If the underlying arrays and property values are needed else where call

Parameters

pThis The correlated data sets object to delete, provided pointer should be set to NULL after this operation.

int DasDs_shape	(	const DasDs *	pThis,
		ptrdiff_t *	pShape
	)

Return current valid ranges for whole data set iteration.

To plot all values in a dataset iterate over the entire range provided for each function. The returned shape is the maximum value + 1 of each index of the given dataset. The shape can change as data are added to the dataset.

Data variables that include point spread functions and variables that provide vectors require an inner iteration that is not part of the returned shape.

Note that for a properly defined dataset all indices below the rank of the dataset will be used.

* // Setup the shape array to contain all D2IDX_UNUSED values first
* ptrdiff_t aBulkShape[D2IDX_MAX] = D2IDX_EMPTY;
* 
* // Now get the shape
* int nRank = DasDs_shape(pDs, aBulkShape);
* 
* 

Parameters

	pThis	A pointer to a dataset object
[out]	pShape	pointer to an array to receive the current bulk iteration shape required to get all the values from all variables in the dataset.

An integer from 0 to LONG_MAX indicating the valid range of values for this index.
The constant D2IDX_RAGGED indicating that the range of values for this index depend on upper indicies.
The constant D2IDX_UNUSED to indicate that a index is un-used by this dataset.

Returns: The iteration rank sufficient to read all coordinate and data values.

void dasds_iter_init	(	dasds_iterator *	pIter,
		const DasDs *	pDs
	)

Initialize a const dataset iterator.

The initialized iterator is safe to use for datasets that are growing as it will not exceed the valid index range of the dataset at the time this function was called. However, if the dataset shrinks during iteration das_iter_next() could overstep the array bounds.

For usage see the example in ::das_iterator

Parameters

pIter	A pointer to an iterator, will be initialize to index 0
pDs	A pointer to a dataset. If the dataset changes while the iterator is in use invalid memory access could occur

bool dasds_iter_next ( dasds_iterator * pIter )

Increment the iterator's index by one position, rolling as needed at data boundaries.

For efficiency this function does not re-check array bounds on each call a slower but safer version of this function could be created if needed.

For usage see the example in ::das_iterator

Parameters

pIter A pointer to an iterator. The index member of the iterator will be incremented.

Returns: true if the new index is within range, false if the index could not be incremented without producing an invalid location.

bool DasDs_addAry	(	DasDs *	pThis,
		DasAry *	pAry
	)

Add an array to the dataset, stealing it's reference.

Arrays are raw backing storage for the dataset. They contain elements but do not provide a meaning for those elements. Variables are a semantic layer on top of the raw arrays.

Parameters

pThis	a Dataset structure pointer
pAry	The array to add. Note: This function "steals" a reference to the array. Meaning it does not increment the refenece count of the array when adding it to the function, but it does decrement the refenece when the dataset is deleted! So if you want the calling code to still have access to the array after the dataset it's attached too is removed you'll have to call inc_DasAry() on your own.

Returns: Almost always returns true. The array list in the dataset requires a small malloc (array memory itself is NOT copied.) This function only returns false in the rare instance that a few dozen bytes can not be allocated.

DasDim * DasDs_makeDim	(	DasDs *	pThis,
		enum dim_type	dType,
		const char *	sId
	)

Make a new dimension within this dataset.

Adding a dimension to a dataset will change cause the parent descriptor for the variable to be set to this dataset. The dataset takes ownership of the variable and will delete it when the dataset is deleted

Parameters

pThis	A pointer to a dataset structure
dType	The type of dimension. If this is a coordinate dimension all data dimensions that vary in any of the same indices as this dimension will be set to depend on these coordinates.
sId	A name for this dimension. Standard names such as 'time', 'frequence' 'range' 'altitude' etc. should be used if possible. No standard list of dimension names are provided by this library, it is left up to the application programmers to handle this.

const char * DasDs_group ( const DasDs * pThis )

Get the data set group id.

Datasets with the same group ID are representable in the same coordinate and data types (for example time, frequency, and power), but have different locations in the coordinate space. Another way of saying this is all datasets with have the same physical units for thier coordinates and data but not the same coordinate values.

Since a dataset is defined in this library to include all items in as single index space more than one dataset may encountered in a stream. All datasets with the same groupID should be plottable on the same set of axis.

Parameters

pThis The dataset sturcture

Returns: a string pointer than is never null

size_t DasDs_numDims	(	const DasDs *	pThis,
		enum dim_type	vt
	)

Get the number of physical dimensions in this dataset.

Parameters

pThis	The dataset object
vt	The variable type, either COOR or DATA

Returns: The number of data functions provided for a dataset.

const DasDim * DasDs_getDim	(	const DasDs *	pThis,
		size_t	idx,
		enum dim_type	vt
	)

Get a dimension by index.

Parameters

pThis	a pointer to a dataset structure
idx	the index of the variable in question
vt	the variable type, either COORD or DATA

Returns: A Variable pointer or NULL if idx is invalid

DasDim * DasDs_getDimById	(	DasDs *	pThis,
		const char *	sId
	)

Get a dimension by string id.

Parameters

pThis	a pointer to a dataset structure
sId	The name of the dimension to retrieve, for example 'time' or 'frequency'

Returns: A dimesion pointer or NULL if sId does not match any dimesion name

DasDim * new_DasDim	(	const char *	sId,
		enum dim_type	dtype,
		int	nRank
	)

Create a new dimension (not as impressive as it sounds)

Parameters

sId	The id of the dimension, which should be a common name such as time, energy, frequency, latitude, longitude, solar_zenith_angle, electric_spectral_density, netural_flux_density, etc. It's much more important for coordinate dimensions to have common names than data dimensions.
dtype	One of DASDIM_COORD, DASDIM_DATA
nRank

Returns

const char * DasDim_id ( const DasDim * pThis )

Get the dimension's id.

Parameters

pThis a pointer to a das dimension structure.

Returns: The id of the dimension, which should be a common name such as time, energy, frequency, electric_spectral_density, netural_flux_density, etc.

char * DasDim_toStr	(	const DasDim *	pThis,
		char *	sBuf,
		int	nLen
	)

Print an information string describing a dimension.

Parameters

pThis	A pointer to a dimension structure
sBuf	A buffer to hold the description
nLen	Warning, these can be long so provide around 256 bytes or more of storage.

Returns: A pointer to the next write location within the buffer sBuf that can be used for appending more text.

int DasDim_copyInProps	(	DasDim *	pThis,
		char	cAxis,
		const DasDesc *	pOther
	)

Copy in dataset properties from some other descriptor.

This is a helper for das 2.2 streams as these use certian name patterns to indicate which dimension a property is for

Any properties that start with a specific dimension identifier i.e. 'x','y','z','w' are copied into this dataset's properties dictionary. Only properties not present in the internal dictionary are copied in.

Parameters

pThis	this dimension object
cAxis	the connonical axis to copy in.
pOther	The descriptor containing properites to copy in

Returns: The number of properties copied in

bool DasDim_addVar	(	DasDim *	pThis,
		const char *	sRole,
		DasVar *	pVar
	)

Add a variable to a dimension.

Parameters

pThis	the dimesion in question
pVar	the variable to add
role	The type of information this variable supplies for the dimension. Any string may be used, standard values are provided in the defines: DASVAR_CENTER, DASVAR_MIN, DASVAR_MAX, DASVAR_WIDTH, DASVAR_REF, DASVAR_OFFSET, DASVAR_MEAN, DASVAR_MEDIAN, DASVAR_MODE, DASVAR_MAX_ERR, DASVAR_MIN_ERR, DASVAR_UNCERT, DASVAR_STD_DEV, DASVAR_SPREAD, and DASVAR_WEIGHT. Any string under 32 characters is acceptable, using a single case is prefered.

Returns: true if the variable could be added, or false otherwise. Trying to add a second variable for the same role will result in a return value of false.

const DasVar * DasDim_getVar	(	const DasDim *	pThis,
		const char *	sRole
	)

Get a variable providing values for a particular role in the dimension.

Parameters

pThis	A pointer to a dimension
sRole	A string defining the role, Any string may be used, standard values are provided in the defines: DASVAR_CENTER, DASVAR_MIN, DASVAR_MAX, DASVAR_WIDTH, DASVAR_REF, DASVAR_OFFSET, DASVAR_MEAN, DASVAR_MEDIAN, DASVAR_MODE, DASVAR_MAX_ERR, DASVAR_MIN_ERR, DASVAR_UNCERT, DASVAR_STD_DEV, DASVAR_SPREAD, and DASVAR_WEIGHT.

Returns: A pointer to a DasVar or NULL if no variable exists within this dimension for the given role.

const DasVar * DasDim_getPointVar ( const DasDim * pThis )

Get a variable poviding single point values in a dimension.

The most common variable role, DASVAR_CENTER, is typically present in a dimension but not always. Sometimes other roles take this variable's place, such as the mean, median or mode or an average of the minimum and maximum values. Use this function to autoselct a variable to use as the center point when plotting data.

Parameters

pThis A pointer to a dimension

Returns: A pointer to a variable that can be used to provide single points in this dimension, or NULL in the rare instance that nothing in this dimesion can be used for single point values. A return of false from this call probably means you have an invalid or highly customized dataset.

DasVar * DasDim_popVar	(	DasDim *	pThis,
		const char *	role
	)

Remove a variable by role from a dimensions.

The caller is considered to own the variable and must delete it if no longer in use.

Parameters

pThis	The dimension in question
role	A role string. Can be anything less that 32 characters but library uses are recommened to choose from the predefined strings: D2VP_CENTER, D2VP_MIN, D2VP_MAX, D2VP_WIDTH, D2VP_MEAN, D2VP_MEDIAN, D2VP_MODE, D2VP_REF, D2VP_OFFSET, D2VP_MAXERR, D2VP_MINERR, D2VP_UNCERT, D2VP_STD_DEV

Returns: A pointer to the variable occuping the given role, or NULL if no variable occupied the specified role

void del_DasDim ( DasDim * pThis )

Delete a dimension and drop the reference count on all contained variables.

Parameters

pThis A pointer to a dimension structure. This pointer should be set to NULL after calling this function

int DasDim_shape	(	const DasDim *	pThis,
		ptrdiff_t *	pShape
	)

Get the maximum extent of this dimension in index space.

This function can be used to determine if there is a set of indices that when changed, only affect the values of the variables in one dimension without affecting the other. If such an index set exists then the dimensions are orthogonal in index space.

* // Given two dimension structure pointer, pLat and pLong
* int lat_shape[D2ARY_MAXIDX];
* int long_shape[D2ARY_MAXIDX];
* 
* DasDim_shape(pLat, lat_shape);
* DasDim_shape(pLong, long_shape);
* 
* if(Shape_IsOrthoginal(lat_shape, long_shape)){
*     // Yes, we can slice in latitude and longitude simply by changing the
*     // indices lat_shape but not long_shape and vice versa
* }
* else{
*     // No, we can't simply slice in index space to hold latitude or 
*    // longitude constant.  Will need to define an index of a latitude or
*     // longitude range.  I.e. will need to make a thin slab in
* }
* 

This is a convenience wrapper around Variable_shape that takes the maximum extent in all contained variables.

Parameters

pThis	the Coordinate Dimension or Data Dimension in question
pShape	a pointer to an array up to D2ARY_MAXDIM in size to receive the shape values. A -1 in any position means that the index in question does not affect any of variables within this dimension.

Returns: The rank of the variable

See Also: Variable_shape()

DasVar * new_DasVarUnary	(	const char *	sOp,
		const DasVar *	pVar
	)

Create a new variable from unary operation on an existing variable.

Create a virtual variable from Operation(SubVar) as needed on an element by element basis, for example "Var1**-2", or "- Var1". For efficency, simple powers are combined into the operator.

The new variable dose not allocate any storage, Getting elements from this variable will result in a sub-variable lookup and a calculation based on the given operator.

If a variable is to be iterated over multiple times the function new_DasVarEval() can be used to run this calculation and any sub calculations over all internal arrays and output the result into a new storage array.

Parameters

sOp	a string of lowercase letters or numbers describing the operation to apply. The following strings are understood: "-", "2", "3" "-2", "-3", "ln", "log", "sqrt", "curt", "sin", "cos", "tan"
pVar	The variable to modify

Returns: A new DasVar allocated on the heap with it's reference count set to one.

See Also: new_DasVarEval

DasVar * new_DasVarBinary	(	DasVar *	pLeft,
		const char *	sOp,
		DasVar *	pRight
	)

Create a new variable from a binary operation on two other variables.

Create a virtual variable from Var1 Operator Var2, for example Var1 + Var2.

The new variable does not allocate any storage though it does pre-calculate any needed scaling factors. Getting elements from this variable will result in two sub-variable lookups and a calculation based on the given operator.

The two variables must produce the same number of values when given the same set of indices. Most variables do not have an internal index so this is usually satisfied.

The two variables must have units that can be combined using given operator. Typically this means they must have the same units, but epoch units can be combined with pure "length" (i.e. duration) units under the addition and subtraction operators but two epoch units cannot be combined.

The new variable created by this binary combination will the units of the right sub-variable. Output of the left sub-variable will be scaled if needed before being combined on an element by element basis with the right sub-variable.

If a variable is to be iterated over multiple times the function new_DasVarEval() can be used to run this calculation and any sub calculations over all internal arrays and output the result into a new storage array

Parameters

pLeft	the left index variable for the binary operation
sOp	the operation to preform, The following strings are understood "+","-","/","*","pow"
pRight	the indexed variable in the binary operation

Returns: the new variable or NULL if an error occurred such as an unknown operator string.

See Also: new_DasVarEval

DasVar * new_DasConstant	(	das_val_type	vt,
		size_t	sz,
		const void *	val,
		das_units	units
	)

Create a constant value on the heap.

Constant variables ignore the given index value and always return the supplied constant.

Parameters

vt	The element type for the constant, must a type with a known width. See new_DasVar_custConst()
sz	The size of the data value in bytes. This is ignored for types with a known size and can just be set to 0. If using the value type vtUnknown you will need to provide the value size
val	A pointer to the value which will be copied internally. This is efficient for items less than 32 bytes long, otherwise a malloc is issued.
units	The singleton unit string for this variable.

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.

Parameters

sId	An identifier for this sequence, follows rules for array ids
vt	the value type must be one of the values in das_val_type
vSz	the size in bytes for the value type, only used for vtByteSeq types
pMin	The minimum value for the sequence
pInterval	The interval between values of the sequence
pMap	A mapping from DasDs indices to this sequence's lone index. The map should only have one value set to D2IDX_FUNC, the rest should be set to D2IDX_UNUSED
units	The units for values produced by this sequence

Returns

DasVar * new_DasVarArray	(	DasAry *	pAry,
		int	iInternal,
		int8_t *	pMap
	)

Create a function backed by an Array.

This variable will be backed by an array though the array indicies do not have to match the variable indicies. For example an array of frequencies for a time, frequency spectrogram might only have a single index [i], but the variable could access these as index [i][j] where j for the function maps to i for the array and i for the variable is ignored.

Parameters

pAry	The array which contains coordinate values
iInternal	The number of indicies that are global to the dataset. Alternatively the position in the map that corresponds to the first internal index (if any).

After mapping everything in pMap upto (but not including) iInternal, any remaining DasAry indices will be considered internal items and will be accessed as a group.

Having an array with an unmapped extra index is very useful for dealing with string data.

Parameters

pMap	The mapping from dataset index positions to array index positions Any element in the map may be D2IDX_UNUSED to indicate that a particular dataset index is not used, or some value equal to or greater than 0 to indicate which array index corresponds to the i-th variable index.

Returns: A pointer to the new variable object allocated on the heap

DasAry * DasVarAry_getArray ( DasVar * pThis )

Get the backing array if present.

Returns: NULL if the variable is not backed directly by an array

bool DasVar_orthoginal	(	const DasVar *	pThis,
		const DasVar *	pOther
	)

Getting data from a variable.

Answer the question: is one variable orthogonal in index space to another.

Parameters

pThis	pointer to the first variable object
pOther	pointer to the second variable object

Returns: True if the indicies that trigger a change in the first variable's output are completly separate from the indices that change the second variable's output

int DasVar_shape	(	const DasVar *	pThis,
		ptrdiff_t *	pShape
	)

Return the current shape of this variable.

Cause this variable to inspect it's managed array or sub-variables and determine the current extents in index space.

Parameters

pThis	The variable for which the shape is desired
pShape	a pointer to an array up to D2_MAXDIM in size. Each element of the array will be filled in with either one of the following:

An integer from 0 to LONG_MAX to indicate the valid index range.
The value D2IDX_UNUSED to indicate the given index position is ignored by this variable
The value D2IDX_RAGGED to indicate that the valid index is variable and depends on the values of other indices.
The value D2IDX_FUNC to indicate that the values are not stored but rather calculated from the given index itself. This is true for variables backed by un-bounded sequences instead of arrays.

Returns: The rank of the variable, which is the number of values returned in pShape which are not marked as unused.

bool DasVar_getDatum	(	const DasVar *	pThis,
		ptrdiff_t *	pIdx,
		das_datum *	pDatum
	)

Get a value given an index.

This is the "slow boat from China" way to retrieve elements but it always works, even for non-orthogonal data sets, ragged arrays and variables built on expressions involving other variables. This is useful when re-gridding a data set onto a rectangular array such as a pixel or voxel raster.

Parameters

pThis	the data set in question
pIdx	The location to retrieve. Unmapped indices are ignored.
pDatum	pointer to a datum structure to fill in with the value

Returns: false if the indices represented by pIdx are invalid, a pointer to the data value otherwise. It is up to the caller to cast the pointer to the appropriate type and difference it to get the value.

bool DasVar_isComposite ( const DasVar * pVar )

Is this a simple variable or more than one variable combinded via operators?

If variable actually represents an expression tree of variables combined via operations

void dec_DasVar ( DasVar * pThis )

Decrement the reference count on a variable.

If the reference count of a variable drops to zero then the variable decrements the reference count on all other variables and arrays that it may be using and then free's it's own memory.

You should set any local pointers refering to this variable to NULL after calling dec_DasVar as it may no longer exist.

Detailed Description

Data Structures

Macros

Functions

Function Documentation