Das Datasets. More...

#include <das2/dataset.h>

Inheritance diagram for DasDs:

Collaboration diagram for DasDs:

[legend]

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

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

DAS_API void	DasDs_setMutable (DasDs *pThis, bool bChangeAllowed)
	Lock/Unlock the dataset for changes. More...

#define	DasDs_mutable(P) P->_mutable
	Get the lock state of the dataset.

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

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

#define	DasDs_group(P) ((const char*)(P)->sGroupId)
	Get the data set group id. More...

#define	DasDs_id(P) ((const char*)(P)->sId)
	Get the data set string id. More...

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

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

#define	DasDs_numAry(P) ((P)->uArrays)
	Get the number of arrays in the dataset.

#define	DasDs_getAry(P, I) ((P)->lArrays[(I)])
	Get the a specific array in the dataset, buy index. More...

DAS_API DasAry *	DasDs_getAryById (DasDs pThis, const char sAryId)
	Get a dataset array given it's identifier. More...

DAS_API size_t	DasDs_memUsed (const DasDs *pThis)
	Get the currently used memory of all arrays in the dataset. More...

DAS_API size_t	DasDs_memOwned (const DasDs *pThis)
	Get the currently allocated memory of all arrays in the dataset. More...

DAS_API DasErrCode	DasDs_addFixedCodec (DasDs pThis, const char sAryId, const char sSemantic, const char sEncType, int nItemBytes, int nNumItems)
	Define a packet data encoded/decoder for fixed length items and arrays. More...

DAS_API DasErrCode	DasDs_addRaggedCodec (DasDs pThis, const char sAryId, const char sEncType, int nItemBytes, int nSeps, ubyte uSepLen, const ubyte pSepByIdx)
	Define a packet data encoder for variable length items and arrays. More...

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

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

DAS_API const DasDim *	DasDs_getDim (const DasDs pThis, const char sDim)
	Get a dimension by it's basic kind. More...

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

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

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

#define	DasDesc_type(P) ((P)->type)
	Get the type of this descriptor. More...

DAS_API void	DasDesc_init (DasDesc *pThis, desc_type_t type)
	Initialize a memory location as a valid das descriptor.

DAS_API char *	DasDesc_info (const DasDesc pThis, char sBuf, int nLen, char *sIndent)
	Print 1-line versions of each property in a descriptor.

DAS_API bool	DasDesc_equals (const DasDesc pThis, const DasDesc pOther)
	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...

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

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

DAS_API const DasProp *	DasDesc_getPropByIdx (const DasDesc *pThis, size_t uIdx)
	Get a property name by an index. More...

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

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

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

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

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

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

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

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

DAS_API size_t	DasDesc_getStrAry (DasDesc pThis, const char sName, char pBuf, size_t uBufSz, char *psVals, size_t uMaxVals)
	Get a multi-valued string property. More...

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

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

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

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

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

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

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

DAS_API DasErrCode	DasDesc_setDoubleArray (DasDesc pThis, const char sName, int nItems, double *pValues)
	Set the property of type double array.

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

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

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

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

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

DAS_API DasErrCode	DasDesc_setFloatAry (DasDesc pThis, const char sName, int nItems, float *pValues)
	Set the property of type float array. More...

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

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

Data Fields
void *	pUser
	User data pointer. More...

Detailed Description

Das Datasets.

Das Datasets provide storage for arrays that contains both data values and coordinate values. Each dataset corresponds to a single index space. All variables 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).

Variables are grouped together into physical dimension by das2 dimension (DasDim) objects. Each variable in a dimension servers a role. For example providing center point values. Bin max values, bin min, uncertianty, etc.

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.

Member Function Documentation

◆ new_DasDs()

DAS_API 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

◆ del_DasDs()

DAS_API void del_DasDs ( DasDs * pThis )

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

If the underlying arrays and property values are needed else where call release on sub items.

Parameters

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

◆ DasDs_setMutable()

DAS_API void DasDs_setMutable	(	DasDs *	pThis,
		bool	bChangeAllowed
	)

Lock/Unlock the dataset for changes.

All DasDs object default to mutable. This has the side effect that certian values which could be cached for speed (such as the shape) must be re-calculated on demand. Use this function to lock the dataset from being changed so that it can cache fequent requests.

Parameters

pThis	The dataset in question
bChangeAllowed	if false, the shape of the data set will be cached and all calls that would alter the dataset will fail. Note that it is possible to change a dataset in an external manner that is not visible using the DasDim_, DasVar_ and DasAry_ functions directly.

◆ DasDs_shape()

DAS_API 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 DASIDX_RAGGED indicating that the range of values for this index depend on upper indicies.
The constant DASIDX_UNUSED to indicate that a index is un-used by this dataset.

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

◆ DasDs_lengthIn()

DAS_API 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

◆ DasDs_addAry()

DAS_API DasErrCode 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: Returns DAS_OKAY so long as no previous arrays have the same array id.

◆ DasDs_getAryById()

DAS_API DasAry * DasDs_getAryById	(	DasDs *	pThis,
		const char *	sAryId
	)

Get a dataset array given it's identifier.

Every array must have a text ID, furthermore these must be unique within the dataset (enforced by DasDs_addAry).

Parameters

pThis	a dataset structure pointer
sId	A text string identifying one of the datasets arrays

Returns: A pointer to the array, or NULL if no array with the given ID could be found in the dataset.

◆ DasDs_memUsed()

DAS_API size_t DasDs_memUsed ( const DasDs * pThis )

Get the currently used memory of all arrays in the dataset.

Note that this is not the memory footprint, as DasAry's will allocate more space then needed during append operations. This is done to reduce the number of allocations.

Note: Static structures such as DasDims and DasVars also require some space. Static memory usage is not returned, only array dynamic memory usage.

Parameters

pThis a dataset structure pointer

Returns: The sum of used heap bytes in all the arrays in the dataset. These are the bytes that contain usable data values as well as the bytes used by index arrays.

See also: DasDs_memOwned() to get the allocated heap bytes for all arrays in the dataset.

◆ DasDs_memOwned()

DAS_API size_t DasDs_memOwned ( const DasDs * pThis )

Get the currently allocated memory of all arrays in the dataset.

Note: The allocated memory may not be indexed yet, especally after DasAry_clear() has been called.; Static structures such as DasDims and DasVars also require some space. Static memory usage is not returned, only array dynamic memory usage.

Parameters

pThis a dataset structure pointer

Returns: The sum of used heap bytes in all the arrays in the dataset. These are the bytes that contain usable data values.

See also: DasDs_memUse() to get the bytes currently used for dynamic storage

◆ DasDs_addFixedCodec()

DAS_API DasErrCode DasDs_addFixedCodec	(	DasDs *	pThis,
		const char *	sAryId,
		const char *	sSemantic,
		const char *	sEncType,
		int	nItemBytes,
		int	nNumItems
	)

Define a packet data encoded/decoder for fixed length items and arrays.

Parameters

pThis	a Dataset structure pointer
sAryId	The array to encode to/decode from
sSemantic	How the values are to be used. This affects parsing. For example a string meant to represent a datatime is stored differently from one that represents an annotation.
sEncType	one of the following encoding types as taken from the das-basic-stream-v3.0.xsd schema:

byte : 8-bit signed integer
ubyte : 8-bit un-signed integer
utf8 : A string of text bytes
BEint : A signed integer 2+ bytes long, most significant byte first
BEuint : An un-signed integer 2+ bytes long MSB first
LEint : Little-endian version of BEint
LEuint : Little-endian version of BEuint
BEreal : An IEEE-754 floating point value, MSB first
LEreal : An IEEE-754 floating point value, LSB first

Parameters

nItemBytes	The number of bytes in an item. For variable length items terminated by a separator, use -9 (DASENC_USE_SEP) and specify an item terminator. For variable length items with explicit lengths use -1 (DASENC_ITEM_LEN)
nNumItems	The number of items to read/write at a time.

Returns: DAS_OKAY if the array codec could be defined

◆ DasDs_addRaggedCodec()

DAS_API DasErrCode DasDs_addRaggedCodec	(	DasDs *	pThis,
		const char *	sAryId,
		const char *	sEncType,
		int	nItemBytes,
		int	nSeps,
		ubyte	uSepLen,
		const ubyte *	pSepByIdx
	)

Define a packet data encoder for variable length items and arrays.

Parameters

pThis

See also: DasDs_addFixedCodec

Parameters

sAryId

See also: DasDs_addFixedCodec

Parameters

sEncType

See also: DasDs_addFixedCodec

Parameters

nItemBytes The number of bytes in an item. For variable length items terminated by a separator, use -9 (DASENC_USE_SEP) and specify an item terminator.

Note: At present, variable length items with explicit length in packets are not yet supported

Parameters

nSeps

The number of separators for variable length items.

   For text items, item separator is first.  Next are the separators
   that indicate the end of fastest moving dataset index, followed
   by the end of the next fastests an so on.  The max number of
   separators must be 1 less then the rank of the dataset for not
   text encodings, and not greater then the rank of the dataset
   for non-text encodings.

uSepLen The length in bytes of the variable length separators. Must be a value from 1 through 8, inclusive.

pSepByIdx An array of pointers to separator values.

Returns: DAS_OKAY if the array codec could be defined

◆ DasDs_makeDim()

DAS_API DasDim * DasDs_makeDim	(	DasDs *	pThis,
		enum dim_type	dType,
		const char *	sDim,
		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.
sDim	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.
sId	An identifier for this paritiular variable group in a dimension. For example 'Search_Coil', 'DC_MAG', etc.

◆ DasDs_numDims()

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

◆ DasDs_getDim()

DAS_API const DasDim * DasDs_getDim	(	const DasDs *	pThis,
		const char *	sDim
	)

Get a dimension by it's basic kind.

Parameters

sDim	The general dimension type, like time, position, voltage, etc.

◆ DasDs_getDimByIdx()

DAS_API const DasDim * DasDs_getDimByIdx	(	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

◆ DasDs_getDimById()

DAS_API const DasDim * DasDs_getDimById	(	const 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

◆ DasDs_toStr()

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

Print a string representation 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

◆ DasDesc_equals()

DAS_API bool DasDesc_equals	(	const DasDesc *	pThis,
		const DasDesc *	pOther
	)

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

pThis	The first descriptor
pOther	The second descriptor

◆ DasDesc_parent()

DAS_API 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)

◆ DasDesc_length()

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

◆ DasDesc_getPropByIdx()

DAS_API const DasProp * DasDesc_getPropByIdx	(	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 valid 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_length(). For efficient storage properties that have been erased or over-written are left in place internally and just marked as invalid.

Returns: A pointer the requested property, or NULL if the property is not valid. A NULL return does not mean than the next higher index has an invalid property

◆ DasDesc_getNameByIdx()

DAS_API 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_length()

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

◆ DasDesc_getValByIdx()

DAS_API 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_length()

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

◆ DasDesc_has()

DAS_API bool DasDesc_has	(	const DasDesc *	pThis,
		const char *	sName
	)

inherited

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

Parameters

pThis	the descriptor object to query
sName	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.

◆ DasDesc_set()

DAS_API 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. This value is passed down to DasProp_init2(), see that function for a list of known values.
sName	The property name. For das2 & das3 this can't 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.

◆ DasDesc_remove()

DAS_API bool DasDesc_remove	(	DasDesc *	pThis,
		const char *	sName
	)

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

◆ DasDesc_getStrAry()

DAS_API size_t DasDesc_getStrAry	(	DasDesc *	pThis,
		const char *	sName,
		char *	pBuf,
		size_t	uBufSz,
		char **	psVals,
		size_t	uMaxVals
	)

inherited

Get a multi-valued string property.

Some properties, especially those from DSDF files, contain multiple string values in a single field separated by pipe "|" characters. For example:

data_01 = 'efield | Electric field intensity | V m**-1'

This function breaks these values into multiple strings without requiring heap memory.

Output bytes are copied into the given val_buf. Then null values are then written over all leading and trailing whitespace for each element as well as the pipe characters.

Finally a pointer to each starting string is copied into ptr_buf. If an element contains not data, for example:

coord_01 = 'frequency | | Hz'

then the corresponding character pointer will be NULL, but the number of character pointers is unchanged.

Parameters

[in]	pThis	the descriptor to query
[in]	name	the name of the property to retrieve
[out]	val_buf	will hold the full output property data
[in]	val_buf_sz	the maximum number of bytes to copy out including the terminating null character.
[out]	ptr_buf	will hold pointers to the start of each property value. If a value is empty, the corresponding pointer is null.
[in]	ptr_buf_sz	the maximum number of string pointers write to ptr_buf.

Returns: The number of string values for this property, which is zero if a property with the given name is not present.

See also: DasDesc_getStr to retrieve the original property value in a single buffer unaltered.

◆ DasDesc_setStr()

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

◆ DasDesc_getDouble()

DAS_API double DasDesc_getDouble	(	const DasDesc *	pThis,
		const char *	sName
	)

inherited

Read the property of type double named sName.

The property value is parsed using sscanf.

◆ DasDesc_setDouble()

DAS_API DasErrCode DasDesc_setDouble	(	DasDesc *	pThis,
		const char *	sName,
		double	value
	)

inherited

Set property of type double.

◆ DasDesc_getDatum()

DAS_API double DasDesc_getDatum	(	DasDesc *	pThis,
		const char *	sName,
		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.
sName	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.

◆ DasDesc_setDatum()

DAS_API 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

◆ DasDesc_getDoubleAry()

DAS_API double * DasDesc_getDoubleAry	(	DasDesc *	pThis,
		const char *	sName,
		int *	pNumItems
	)

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]	sName	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: DasDesc_has()

◆ DasDesc_getInt()

DAS_API int DasDesc_getInt	(	const DasDesc *	pThis,
		const char *	sName
	)

inherited

Get a property integer value.

Parameters

pThis	the descriptor object to query
sName	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: DasDesc_has()

◆ DasDesc_getBool()

DAS_API bool DasDesc_getBool	(	DasDesc *	pThis,
		const char *	sName
	)

inherited

Get a property boolean value.

Parameters

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

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

◆ DasDesc_getStrRng()

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

◆ DasDesc_setFloatAry()

DAS_API DasErrCode DasDesc_setFloatAry	(	DasDesc *	pThis,
		const char *	sName,
		int	nItems,
		float *	pValues
	)

inherited

Set the property of type float array.

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

◆ DasDesc_copyIn()

DAS_API void DasDesc_copyIn	(	DasDesc *	pThis,
		const DasDesc *	pOther
	)

inherited

Deepcopy properties into a descriptor.

Parameters

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

◆ DasDesc_encode2()

DAS_API DasErrCode DasDesc_encode2	(	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.

Field Documentation

◆ pUser

void* pUser

User data pointer.

The stream -> dataset hierarchy provides a goood organizational structure for application data, especially applications that filter streams. It is initialized to NULL when a variable is created but otherwise the library dosen't deal with it.

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

das2/dataset.h

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ new_DasDs()

◆ del_DasDs()

◆ DasDs_setMutable()

◆ DasDs_shape()

◆ DasDs_lengthIn()

◆ DasDs_addAry()

◆ DasDs_getAryById()

◆ DasDs_memUsed()

◆ DasDs_memOwned()

◆ DasDs_addFixedCodec()

◆ DasDs_addRaggedCodec()

◆ DasDs_makeDim()

◆ DasDs_numDims()

◆ DasDs_getDim()

◆ DasDs_getDimByIdx()

◆ DasDs_getDimById()

◆ DasDs_toStr()

◆ DasDesc_equals()

◆ DasDesc_parent()

◆ DasDesc_length()

◆ DasDesc_getPropByIdx()

◆ DasDesc_getNameByIdx()

◆ DasDesc_getValByIdx()

◆ DasDesc_has()

◆ DasDesc_set()

◆ DasDesc_remove()

◆ DasDesc_getStrAry()

◆ DasDesc_setStr()

◆ DasDesc_getDouble()

◆ DasDesc_setDouble()

◆ DasDesc_getDatum()

◆ DasDesc_setDatum()

◆ DasDesc_getDoubleAry()

◆ DasDesc_getInt()

◆ DasDesc_getBool()

◆ DasDesc_getStrRng()

◆ DasDesc_setFloatAry()

◆ DasDesc_copyIn()

◆ DasDesc_encode2()

Field Documentation

◆ pUser