Das Datasets. More...

#include <das3/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.

DAS_API DasErrCode	DasDs_replaceAry (DasDs pThis, const char sOldId, DasAry *pNew)
	Swap a storage array in a dataset for a replacement.

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

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

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

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.

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

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

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

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

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

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

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

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

#define	DasDs_numCodecs(pThis) ( (pThis)->uCodecs )
	Number of value codecs owned by this dataset.

#define	DasDs_getCodec(pThis, I) ( &( (pThis)->lCodecs[(I)] ) )
	Get the Ith codec of a dataset.

DAS_API DasCodec *	DasDs_getCodecFor (const DasDs pThis, const char sAryId, int *pItems)
	Get the codec for a named array.

#define	DasDs_pktItems(P, I) ( (P)->lItems[(I)] )
	Get the number of values we expect the Ith codec to read from each raw packet buffer.

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

DAS_API DasCodec *	DasDs_addStringCodec (DasDs pThis, const char sAryId, const char sSemantic, const char sEncType, int nItemTerm, ubyte uTerm, int nNumItems, bool bRead)
	Define a packet data encoder for a fixed number of variable length items in each packet.

DAS_API DasCodec *	DasDs_addCodecFrom (DasDs pThis, const char sAryId, const DasCodec *pOther, int nNumItems, bool bRead)
	Add a new codec that initialized via some other codec.

DAS_API DasDs *	new_DasDs_xml (DasBuf pBuf, DasDesc pParent, int nPktId)
	Parse a das3 <dataset> XML element into a new dataset object.

DAS_API DasErrCode	DasDs_encodeHdr (DasDs pThis, DasBuf pBuf)
	Encode the dataset header as a das3 <dataset> XML element.

DAS_API DasErrCode	DasDs_decodeData (DasDs pThis, DasBuf pBuf)
	Decode one packet's worth of data into dataset memory.

DAS_API DasErrCode	DasDs_encodeData (DasDs pThis, DasBuf pBuf, ptrdiff_t iIdx0)
	Encode one record's worth of data from dataset memory.

DAS_API int	DasDs_recBytes (const DasDs *pThis)
	Get the number of bytes in each record of this dataset when serialized.

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

DAS_API DasErrCode	DasDs_addDim (DasDs pThis, DasDim pDim)
	Add a physical dimension to the dataset.

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

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

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

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

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

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

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 void	DasDesc_freeProps (DasDesc *pThis)
	For use in derived destructors, frees the property array.

DAS_API void	DasDesc_clearProps (DasDesc *pThis)
	Resets the property count to 0, but frees no memory.

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.

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

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

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

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

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

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

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

DAS_API DasErrCode	DasDesc_flexSet (DasDesc pThis, const char sType, ubyte uType, const char sName, const char sVal, char cSep, das_units units, int nStandard)
	Create or set a existing property.

DAS_API DasErrCode	DasDesc_setProp (DasDesc pThis, const DasProp pProp)
	Overwrite, or copy-in a fully formatted property.

DAS_API const char *	DasDesc_getType (const DasDesc pThis, const char sName)
	Get the type string for a property.

DAS_API const char *	DasDesc_get (const DasDesc pThis, const char sName)
	Get a raw property string.

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

DAS_API bool	DasDesc_hasLocal (const DasDesc pThis, const char sName)
	Does this descriptor alone have this property.

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

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.

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

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.

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

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

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

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

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.

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.

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.

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

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

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

DAS_API DasErrCode	DasDesc_encode3Bare (DasDesc pThis, DasBuf pBuf, const char *sIndent)
	Encode das3 properties WITHOUT the enclosing properties element.

DAS_API bool	DasDesc_hasAnyProps (const DasDesc *pThis)
	Does this descriptor hold at least one valid property?

Data Fields
void *	pUser
	User data pointer.

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, uncertainty, 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 indices needed to retrieve 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

◆ DasDs_replaceAry()

DAS_API DasErrCode DasDs_replaceAry	(	DasDs *	pThis,
		const char *	sOldId,
		DasAry *	pNew
	)

Swap a storage array in a dataset for a replacement.

Finds the array registered under sOldId, re-points every array variable that reads from it at pNew (via DasVarAry_setArray, so the variables pick up the new array's value type, units and semantic), and swaps the dataset's array-list entry, fixing the reference counts so the old array is released once nothing else in this dataset holds it.

This is the companion to DasDs_copy() for stream filters that must change a value type rather than just an encoding. The motivating case is a binary -> text re-encoder that turns an epoch integer/real array into a das_time array so the codec can write ISO-8601: build the das_time array, then call this to splice it in. The replacement must have the same rank as the array it replaces.

Warning: Codecs are NOT touched. A codec still aimed at the old array reads a now-detached array; the caller must re-initialize it onto pNew (e.g. with DasCodec_init) after this returns. This keeps codec order, and therefore packet layout, stable.

Parameters

pThis	The dataset to modify.
sOldId	The id of the array to retire.
pNew	The replacement array, same rank as the retired one. The dataset takes a reference; the caller keeps its own and may drop it afterward.

Returns: DAS_OKAY on success, a positive error code if no array matched sOldId or a variable could not be re-pointed.

◆ 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 certain 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 frequent 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 VARIDX_RAGGED indicating that the range of values for this index depend on upper indices.
The constant VARIDX_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 VARIDX_UNUSED 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. This call bumps the reference count for the array. If you want the dataset to hold the array all on it's own, release your reference with dec_DasAry() on successful return. The dataset releases its own reference when it is deleted.

This is the rule for every das2C call that keeps a pointer to a reference counted object. No call in the library takes a reference away from you, if you want to give up ownership of a heap object you created, you have to manually dec the reference.

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, especially 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_getCodecFor()

DAS_API DasCodec * DasDs_getCodecFor	(	const DasDs *	pThis,
		const char *	sAryId,
		int *	pItems
	)

Get the codec for a named array.

Parameters

pThis	A dataset owning both codecs and arrays
sAryId	The string ID of the array for which a codec is needed.
pItems	A pointer to a single int to hold the number of items serialized at a time using this codec. (AKA the number of values per packet)

Returns: A const pointer to the internal codec that serializes the named array's memory. The pointer is not guaranteed to be constant. Make a copy of it's value if needed later.

◆ DasDs_addFixedCodec()

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

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. Semantics are especially important for data encoded as text. Use one of the following:

bool : Interpret as a true or false value
int : Interpret as a integer
real : Interpret as a real number
datetime : Interpret as a point in time
string : basically, don't interpret

Parameters

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 fixed number of bytes in an item. Variable size item flags not supported.
nNumItems	The number of items to read/write at a time.
bRead	If true initialize a decoder, if false initialize an encoder. For readability the macros DASENC_READ and DASENC_WRITE can be used

Returns: NULL if the codec couldn't be defined, or a pointer to the new codec otherwise

◆ DasDs_addStringCodec()

DAS_API DasCodec * DasDs_addStringCodec	(	DasDs *	pThis,
		const char *	sAryId,
		const char *	sSemantic,
		const char *	sEncType,
		int	nItemTerm,
		ubyte	uTerm,
		int	nNumItems,
		bool	bRead
	)

Define a packet data encoder for a fixed number of variable length items in each packet.

Despite the name, strings are just a run of bytes. These bytes need not be valid utf8 encoding units. With the use of DASENC_ITEM_LEN, random blobs of arbitrary bytes can be read.

Parameters

pThis

See also: DasDs_addFixedCodec

Parameters

sAryId

See also: DasDs_addFixedCodec

Parameters

sEncType

See also: DasDs_addFixedCodec

Parameters

nItemTerm	Since a variable number of bytes can be use, provide the size determination. Either DASENC_ITEM_TERM to indicate that items terminate when a special byte is read, or DASENC_ITEM_LEN to indicate that explicit lengths are provided inside the packets themselves.
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 fastest an so on. The max number of separators must equal to the rank of the array they encode. Each separator is only 1 byte long. If this is not sufficient you'll have to go with DASENC_ITEM_LEN
uSepLen	The length in bytes of the variable length separators. Must be a value from 1 through 8, inclusive.
pSepByIdx	Pointer to an array of separator bytes. This must be nSeps * uSepLen long.
bRead	If true initialize a decoder, if false initialize an encoder. For readability the macros DASENC_READ and DASENC_WRITE can be used

Returns: NULL if the codec couldn't be defined, or a pointer to the new codec otherwise

◆ DasDs_addCodecFrom()

DAS_API DasCodec * DasDs_addCodecFrom	(	DasDs *	pThis,
		const char *	sAryId,
		const DasCodec *	pOther,
		int	nNumItems,
		bool	bRead
	)

Add a new codec that initialized via some other codec.

Before calling this function make sure the array ID expected of the codec is present in the current dataset, or use sAryId.

Parameters

pThis	The dataset that should create an new internal codec.
pOther	The other codec whose values are used to initialize our new codec for this dataset.
sAryId	If not NULL, override the array ID in the old codec when creating the new one. An array with this ID should already exist in this dataset.
nNumItems	The number of items to read/write at a time.
bRead	If true initialize a decoder, if false initialize an encoder. For readability the macros DASENC_READ and DASENC_WRITE can be used

Returns: NULL if the codec couldn't be defined, or a pointer to the new codec otherwise

◆ new_DasDs_xml()

DAS_API DasDs * new_DasDs_xml	(	DasBuf *	pBuf,
		DasDesc *	pParent,
		int	nPktId
	)

Parse a das3 <dataset> XML element into a new dataset object.

Builds the complete object – dimensions, variables, backing arrays and read codecs – from a header the buffer holds. The write mirror is DasDs_encodeHdr(). When the buffer's content type isn't known in advance (any of the five stream elements), use the generic factory DasDesc_decode() in stream.h instead, which dispatches here for dataset headers.

Only the XML element is read; the caller owns the packet tag and should not send it here. Set the read point of the buffer after the packet tag first.

Parameters

pBuf	the buffer to parse, starting from its current read point
pParent	the stream this dataset belongs to (frames resolve there)
nPktId	the packet tag ID assigned to this dataset

Returns: a new dataset, or NULL on a parse failure

◆ DasDs_encodeHdr()

DAS_API DasErrCode DasDs_encodeHdr	(	DasDs *	pThis,
		DasBuf *	pBuf
	)

Encode the dataset header as a das3 <dataset> XML element.

Writes the complete declaration – name, rank, index= extents from the live shape, properties, and every dimension, variable and <packet> child. The <packet> elements reflect the CODECS' current state, so configure write codecs before calling. Marks the dataset's header as sent.

Only the element is written; the caller owns the |Hx| packet framing. The read mirror is new_DasDs_xml(); the payload siblings are DasDs_decodeData() and DasDs_encodeData().

Parameters

pThis	the dataset to describe
pBuf	the output receiver

Returns: DAS_OKAY, or a das error code

◆ DasDs_decodeData()

DAS_API DasErrCode DasDs_decodeData	(	DasDs *	pThis,
		DasBuf *	pBuf
	)

Decode one packet's worth of data into dataset memory.

Uses the dataset's read codecs, in order, to parse the buffer contents into the backing arrays, closing ragged runs (DasAry_markEnd) as needed. The buffer's read point is advanced past the consumed bytes.

This is the bare payload layer: the caller (typically the das IO layer) supplies one packet's content with the |Pd| framing already stripped.

Parameters

pThis	a dataset with decoders defined, see new_DasDs_xml()
pBuf	the buffer to read, starting from its current read point

Returns: DAS_OKAY, or a das error code

◆ DasDs_encodeData()

DAS_API DasErrCode DasDs_encodeData	(	DasDs *	pThis,
		DasBuf *	pBuf,
		ptrdiff_t	iIdx0
	)

Encode one record's worth of data from dataset memory.

The write mirror of DasDs_decodeData: runs the dataset's write codecs, in order, over one increment of the record (highest) index, emitting each variable-count run with its framing: "[idx|N]" count tags for non-text (in every packet position), idxTerm terminators for utf8.

Only the payload is written; the caller owns the |Pd| packet framing. Call in a loop over the record index to serialize a whole dataset.

Parameters

pThis	a dataset with encoders defined
pBuf	the output receiver
iIdx0	the record index value to emit

Returns: DAS_OKAY, or a das error code

◆ DasDs_recBytes()

DAS_API int DasDs_recBytes ( const DasDs * pThis )

Get the number of bytes in each record of this dataset when serialized.

Given the current codec set, determine how many bytes must be read for each packet in a stream. Works for the fixed encodings typical in *.d3b and *.d3t files but not for serializing to and from pure XML documents.

Parameters

pThis a Dataset structure pointer

Returns: The number of bytes expected in each packet payload for this dataset. It may be 0 if no codecs are defined. A values of -1 or less indicates variable length packets

◆ 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 particular variable group in a dimension. For example 'Search_Coil', 'DC_MAG', etc.

◆ DasDs_addDim()

DAS_API DasErrCode DasDs_addDim	(	DasDs *	pThis,
		DasDim *	pDim
	)

Add a physical dimension to the dataset.

Warning: The dataset takes ownership of the dimension object and will delete it when the dataset is deleted. It is important not to provide a pointer to a stack variable.

Parameters

pThis	A pointer to a dataset structure
pDim	A existing dimension object created on the heap.

Returns: DAS_OKAY if the dimension

◆ DasDs_numDims()

DAS_API size_t DasDs_numDims	(	const DasDs *	pThis,
		enum dim_type	dmt
	)

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 DasDim * DasDs_getDim	(	DasDs *	pThis,
		const char *	sDim,
		enum dim_type	dmt
	)

Get a dimension by it's basic kind.

Parameters

sDim	The general dimension type, like time, position, voltage, etc. The comparison to Dimension IDs is not case sensitive.

◆ DasDs_getDimByIdx()

DAS_API DasDim * DasDs_getDimByIdx	(	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 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'. The name is not case sensitive

Returns: A dimension pointer or NULL if sId does not match any dimension 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 component toStr as well

◆ DasDesc_freeProps()

DAS_API void DasDesc_freeProps ( DasDesc * pThis )

inherited

For use in derived destructors, frees the property array.

After calling this function, no new properties can be added

◆ DasDesc_clearProps()

DAS_API void DasDesc_clearProps ( DasDesc * pThis )

inherited

Resets the property count to 0, but frees no memory.

Call this to re-use a descriptor.

◆ 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 ( const 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_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_flexSet()

DAS_API DasErrCode DasDesc_flexSet	(	DasDesc *	pThis,
		const char *	sType,
		ubyte	uType,
		const char *	sName,
		const char *	sVal,
		char	cSep,
		das_units	units,
		int	nStandard
	)

inherited

Create or set a existing property.

Other then memory handling, this is just a wrapper on DasProp_init. See @DasProp_init for the argument description

◆ DasDesc_setProp()

DAS_API DasErrCode DasDesc_setProp	(	DasDesc *	pThis,
		const DasProp *	pProp
	)

inherited

Overwrite, or copy-in a fully formatted property.

◆ DasDesc_getType()

DAS_API const char * DasDesc_getType	(	const DasDesc *	pThis,
		const char *	sName
	)

inherited

Get the type string for a property.

◆ DasDesc_get()

DAS_API const char * DasDesc_get	(	const DasDesc *	pThis,
		const char *	sName
	)

inherited

Get a raw property string.

This function performs no transforms from the backing store.

◆ 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_hasLocal()

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

inherited

Does this descriptor alone have this property.

The question does not cascade up the tree

◆ 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 property 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 property to retrieve

Returns: The value of the named property or exits the program if the named property 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 property 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.

◆ DasDesc_encode3Bare()

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

inherited

Encode das3 properties WITHOUT the enclosing properties element.

For elements that ARE property arrays (stream context entries), whose

children ride bare.

Field Documentation

◆ pUser

void* pUser

User data pointer.

The stream -> dataset hierarchy provides a good 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:

das3/dataset.h

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ new_DasDs()

◆ DasDs_replaceAry()

◆ del_DasDs()

◆ DasDs_setMutable()

◆ DasDs_shape()

◆ DasDs_lengthIn()

◆ DasDs_addAry()

◆ DasDs_getAryById()

◆ DasDs_memUsed()

◆ DasDs_memOwned()

◆ DasDs_getCodecFor()

◆ DasDs_addFixedCodec()

◆ DasDs_addStringCodec()

◆ DasDs_addCodecFrom()

◆ new_DasDs_xml()

◆ DasDs_encodeHdr()

◆ DasDs_decodeData()

◆ DasDs_encodeData()

◆ DasDs_recBytes()

◆ DasDs_makeDim()

◆ DasDs_addDim()

◆ DasDs_numDims()

◆ DasDs_getDim()

◆ DasDs_getDimByIdx()

◆ DasDs_getDimById()

◆ DasDs_toStr()

◆ DasDesc_freeProps()

◆ DasDesc_clearProps()

◆ DasDesc_equals()

◆ DasDesc_parent()

◆ DasDesc_length()

◆ DasDesc_getPropByIdx()

◆ DasDesc_getNameByIdx()

◆ DasDesc_getValByIdx()

◆ DasDesc_set()

◆ DasDesc_flexSet()

◆ DasDesc_setProp()

◆ DasDesc_getType()

◆ DasDesc_get()

◆ DasDesc_has()

◆ DasDesc_hasLocal()

◆ 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()

◆ DasDesc_encode3Bare()

Field Documentation

◆ pUser