![]() |
das2C
das core C utilities (v3)
|
Das Physical Dimensions. More...
#include <das2/dimension.h>
Public Member Functions | |
DAS_API DasDim * | new_DasDim (const char *sDim, const char *sName, enum dim_type dtype, int nRank) |
Create a new dimension (not as impressive as it sounds) More... | |
#define | DasDim_id(P) ((const char*)(P->sId)) |
Get the dimension's id. More... | |
#define | DasDim_dim(P) ((const char*)(P->sDim)) |
Get the dimension's category. More... | |
DAS_API char * | DasDim_toStr (const DasDim *pThis, char *sBuf, int nLen) |
Print an information string describing a dimension. More... | |
DAS_API bool | DasDim_addVar (DasDim *pThis, const char *sRole, DasVar *pVar) |
Add a variable to a dimension. More... | |
DAS_API const DasVar * | DasDim_getVar (const DasDim *pThis, const char *sRole) |
Get a variable providing values for a particular role in the dimension. More... | |
#define | DasDim_numVars(P) ((P)->uVars); |
Get the number of vars in a dimension. More... | |
#define | DasDim_getVarByIdx(P, I) ( (I)<((P)->uVars) ? ((const DasVar*)((P)->aVars[(I)])) : NULL ) |
Get a variable by index. More... | |
#define | DasDim_getRoleByIdx(P, I) ( (I)<((P)->uVars) ? ((const char*)((P)->aRoles[(I)])) : NULL ) |
Get a variable's role by index. More... | |
DAS_API const DasVar * | DasDim_getPointVar (const DasDim *pThis) |
Get a variable poviding single point values in a dimension. More... | |
DAS_API DasVar * | DasDim_popVar (DasDim *pThis, const char *role) |
Remove a variable by role from a dimensions. More... | |
DAS_API void | del_DasDim (DasDim *pThis) |
Delete a dimension and drop the reference count on all contained variables. More... | |
DAS_API int | DasDim_shape (const DasDim *pThis, ptrdiff_t *pShape) |
Get the maximum extent of this dimension in index space. More... | |
DAS_API 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... | |
#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... | |
Das Physical Dimensions.
Das dimensions are groups of variables within a single dataset that describe the same physical thing. For example the "Time" coordinate dimension would groups all variables that locate data in time. An "Ex" dimension would provide a group of variables describing the electric field in a spacecraft X direction.
A dimension needs to have at least one variable, but it may have many. For example, a dataset that only provides time values by single points would only have a single variable in the time dimension. Hovever a dataset providing extended duration events would need two time variables. One time variable could provide the event start times and another the end times.
There are two basic types of dimensions, coordinates and data. Coordinate dimensions provide variables to locate data in an independent parameter space, these are typically the X-axis values (or X and Y for spectrograms). Data dimensions typically group together related measurements.
DAS_API DasDim * new_DasDim | ( | const char * | sDim, |
const char * | sName, | ||
enum dim_type | dtype, | ||
int | nRank | ||
) |
Create a new dimension (not as impressive as it sounds)
sDim | 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. |
sName | The name of this particular variable group in this dimension If NULL, defaults to sDim. This matters because sometimes we may have multiple things that take data in the same coordinates. |
dtype | One of DASDIM_COORD, DASDIM_DATA |
nRank |
DAS_API char * DasDim_toStr | ( | const DasDim * | pThis, |
char * | sBuf, | ||
int | nLen | ||
) |
Print an information string describing a dimension.
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. |
Add a variable to a dimension.
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. |
Get a variable providing values for a particular role in the dimension.
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. |
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.
pThis | A pointer to a dimension |
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.
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 |
DAS_API void del_DasDim | ( | DasDim * | pThis | ) |
Delete a dimension and drop the reference count on all contained variables.
pThis | A pointer to a dimension structure. This pointer should be set to NULL after calling this function |
DAS_API 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.
This is a convenience wrapper around Variable_shape that takes the maximum extent in all contained variables.
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. |
DAS_API 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.
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 |
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.
pThis | The first descriptor |
pOther | The second descriptor |
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
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.
pThis | A pointer to the descriptor to query |
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.
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. |
|
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.
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() |
|
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.
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() |
|
inherited |
Determine if a property is present in a Descriptor or it's ancestors.
pThis | the descriptor object to query |
sName | the name of the property to retrieve. |
|
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.
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 |
|
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.
|
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.
[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. |
|
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.
|
inherited |
Read the property of type double named sName.
The property value is parsed using sscanf.
|
inherited |
Set property of type double.
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.
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. |
|
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.
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 |
|
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.
[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. |
|
inherited |
Get a property integer value.
pThis | the descriptor object to query |
sName | the name of the proprety to retrieve |
|
inherited |
Get a property boolean value.
pThis | the descriptor object to query |
sName | the name of the proprety to retrieve |
|
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.
|
inherited |
Set the property of type float array.
Note the array is cast to a double array before encoding.
Deepcopy properties into a descriptor.
pThis | the descriptor to receive a copy of the properties |
pOther | the descriptor with the properties to be copied. |
|
inherited |
Encode a generic set of properties to a buffer.
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 |
void* pUser |
User data pointer.
The stream -> dataset -> dimension 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.