dasds_iterator Struct Reference

Dataset iterator structure. More...

#include <das2/dataset.h>

Collaboration diagram for dasds_iterator:

Public Member Functions
DAS_API void	dasds_iter_init (dasds_iterator *pIter, const DasDs *pDs)
	Initialize a const dataset iterator. More...
DAS_API bool	dasds_iter_next (dasds_iterator *pIter)
	Increment the iterator's index by one position, rolling as needed at data boundaries. More...

Data Fields
bool	done
	If true the value in index is valid, false otherwise.
ptrdiff_t	index [DASIDX_MAX]
	A dataset bulk iteration index suitable for use in DasVar functions like ::DasVar_getDatum.

Detailed Description

Dataset iterator structure.

Since dataset rank and shape is a union of the shape of it's components iterating over datasets can be tricky. This structure and it's associated functions are provided to simplify this task. Usage is demonstrated by the example below:

// Assume a dataset with time, amplitude and frequency dimensions but with
// arbitrary shape in index space.
 
// pDs is a pointer to a das dataset 
 
DasDim* pDimTime = DasDs_getDimById(pDs, "time");
DasVar* pVarTime = DasDim_getPointVar(pDimTime);
 
DasDim* pDimFreq = DasDs_getDimById(pDs, "frequency");
DasVar* pVarFreq = DasDim_getPointVar(pDimFreq);
 
DasDim* pDimAmp  = DasDs_getDimById(pDs, "e_spec_dens");
DasVar* pVarAmp  = DasDim_getPointVar(pDimAmp);
 
dasds_iterator iter;
das_datum set[3];
 
for(dasds_iter_init(&iter, pDs); !iter.done; dasds_iter_next(&iter)){
   
  DasVar_getDatum(pVarTime, iter.index, set);
  DasVar_getDatum(pVarFreq, iter.index, set + 1);
  DasVar_getDatum(pVarAmp,  iter.index, set + 2);
 
  // Plot, or bin, or what-have-you, the triplet here.
   // Plot() is not a real function in the libdas2 C API
  Plot(set);
}

Member Function Documentation

dasds_iter_init()

DAS_API 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

dasds_iter_next()

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

---

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

• das2/dataset.h