Describes a data plane within a packet type. More...

#include <das2/plane.h>

Inheritance diagram for PlaneDesc:

Collaboration diagram for PlaneDesc:

[legend]

Public Member Functions
DAS_API PlaneDesc *	new_PlaneDesc_empty (void)
	Creates a Plane Descriptor with mostly empty settings.

DAS_API PlaneDesc *	new_PlaneDesc (plane_type_t pt, const char sGroup, DasEncoding pType, das_units units)
	Creates a new X,Y or Z plane descriptor. More...

DAS_API PlaneDesc *	new_PlaneDesc_yscan (const char sGroup, DasEncoding pZType, das_units zUnits, size_t uItems, DasEncoding pYType, const double pYTags, das_units yUnits)
	Creates a new <yscan> plane descriptor. More...

DAS_API PlaneDesc *	new_PlaneDesc_yscan_series (const char sGroup, DasEncoding pZType, das_units zUnits, size_t uItems, double yTagInter, double yTagMin, double yTagMax, das_units yUnits)
	Creates a new <yscan> plane descriptor using a yTag series. More...

DAS_API PlaneDesc *	PlaneDesc_copy (const PlaneDesc *pThis)
	Copy constructor for planes Deep copy one a plane except for the parent id. More...

DAS_API void	del_PlaneDesc (PlaneDesc *pThis)
	Free a plane object allocated on the heap. More...

DAS_API bool	PlaneDesc_equivalent (const PlaneDesc pThis, const PlaneDesc pOther)
	Check to see if two plane descriptors describe the same output. More...

DAS_API plane_type_t	PlaneDesc_getType (const PlaneDesc *pThis)
	Get a plane's type. More...

DAS_API size_t	PlaneDesc_getNItems (const PlaneDesc *pThis)
	Get the number of items in a plane YScan planes have a variable number of items, for all other types this function returns 1. More...

DAS_API double	PlaneDesc_getValue (const PlaneDesc *pThis, size_t uIdx)
	Get the a value from a plane. More...

DAS_API const das_datum *	PlaneDesc_getDatum (const PlaneDesc pThis, size_t uIdx, das_datum pD)
	Get a datum from a plane. More...

DAS_API DasErrCode	PlaneDesc_setValue (PlaneDesc *pThis, size_t uIdx, double value)
	Set a current value in a plane. More...

DAS_API DasErrCode	PlaneDesc_setTimeValue (PlaneDesc pThis, const char sTime, size_t idx)
	Set a single time value in a plane. More...

DAS_API DasEncoding *	PlaneDesc_getValEncoder (PlaneDesc *pThis)
	Get the data value encoder/decoder object for a plane The encoder returned via this pointer can be mutated and any changes will be reflected in the next data write for the plane. More...

DAS_API void	PlaneDesc_setValEncoder (PlaneDesc pThis, DasEncoding pEnc)
	Set the data value encoder/decoder object for a plane The previous encoder's memory is returned the heap via free(). More...

DAS_API const double *	PlaneDesc_getValues (const PlaneDesc *pThis)
	Get a pointer to the current set of values in a plane. More...

DAS_API void	PlaneDesc_setValues (PlaneDesc pThis, const double pData)
	Set all the current values for a plane. More...

DAS_API double	PlaneDesc_getFill (const PlaneDesc *pThis)
	Returns the fill value identified for the plane. More...

#define	PlaneDesc_isFill(P, V) ((P->rFill == 0.0 && V == 0.0) \|\| (fabs((P->rFill - V)/P->rFill)<0.00001))
	Returns non-zero if the value is the fill value identified for the data plane.

DAS_API void	PlaneDesc_setFill (PlaneDesc *pThis, double value)
	Identify the double fill value for the plane.

DAS_API const char *	PlaneDesc_getName (const PlaneDesc *pThis)
	Get the data group of a plane. More...

DAS_API void	PlaneDesc_setName (PlaneDesc pThis, const char sName)
	Set the data group of a plane. More...

DAS_API das_units	PlaneDesc_getUnits (const PlaneDesc *pThis)
	Get the units of measure for a plane's packet data. More...

DAS_API void	PlaneDesc_setUnits (PlaneDesc *pThis, das_units units)
	Set the unit type for the plane data. More...

DAS_API das_units	PlaneDesc_getYTagUnits (PlaneDesc *pThis)
	Get Y axis units for a 2-D plane. More...

DAS_API const double *	PlaneDesc_getYTags (const PlaneDesc *pThis)
	Get Y axis coordinates for a 2-D plane of data. More...

DAS_API const double *	PlaneDesc_getOrMakeYTags (PlaneDesc *pThis)
	Get Y tags as an array regardless of the storage type If a yTags array is constructed via this method it is cleaned up when the plane destructor is called. More...

DAS_API DasErrCode	PlaneDesc_encode (PlaneDesc pThis, DasBuf pBuf, const char *sIndent)
	Serialize a Plane Descriptor as XML data. More...

DAS_API DasErrCode	PlaneDesc_encodeData (PlaneDesc pThis, DasBuf pBuf, bool bLast)
	Serialize a plane's current data. More...

DAS_API DasErrCode	PlaneDesc_decodeData (const PlaneDesc pThis, DasBuf pBuf)
	Read in a plane's current data. 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...

Detailed Description

Describes a data plane within a packet type.

Each packet of Das2 stream data contains values for one or more planes. To illustrate this take a look at the packet header in the X Tagged Stream Example from the Das2 ICD.

[00]000088<stream>
<properties DatumRange:xRange="2013-001T01:00:00 to 2013-01:10:00"/>
</stream>
[01]000424<packet>

</packet>
:01:2013-001T01:00:00.000  5.782e+00 -1.276e+01  3.220e+00  6.079e+00
:01:2013-001T01:01:00.000  5.782e+00 -1.274e+01  3.232e+00  6.077e+00
:01:2013-001T01:02:00.000  5.781e+00 -1.272e+01  3.244e+00  6.076e+00

Each <x> and <y> element inside the <packet> element above is a serialized PlaneDesc. The point of a PlaneDesc structure is to:

Hold the definition of a single plane within a single packet type.
Assist PacketDescriptors with serializing and de-serializing data packets.

Just as an isolated plane without a parent <packet> tag does not make sense in a Das2 Stream, PlaneDesc structures don't have much use on their own. They are typically owned by a PacketDescriptor and accessed via the PktDesc:getPlane function

Member Function Documentation

◆ new_PlaneDesc()

DAS_API PlaneDesc * new_PlaneDesc	(	plane_type_t	pt,
		const char *	sGroup,
		DasEncoding *	pType,
		das_units	units
	)

Creates a new X,Y or Z plane descriptor.

Parameters

pt	The plane_type_t, must be one of: X - Independent Values Y - Dependent or Independent Values Z - Dependent Values YScan - Dependent Values
sGroup	the name for the data group this plane belongs to, may be the empty string ""
pType	an encoding object for the new plane. The PlaneDesc will take ownership of this object and free it when del_PlaneDesc is called.
units	The units of measurement for data in this plane.

Returns: A pointer to new PlaneDesc allocated on the heap.

◆ new_PlaneDesc_yscan()

DAS_API PlaneDesc * new_PlaneDesc_yscan	(	const char *	sGroup,
		DasEncoding *	pZType,
		das_units	zUnits,
		size_t	uItems,
		DasEncoding *	pYType,
		const double *	pYTags,
		das_units	yUnits
	)

Creates a new <yscan> plane descriptor.

A <yscan> plane is an array of Z-values taken along Y for each X tag. Spectrogram amplitudes are commonly transmitted in this plane type. In that case <x> contains times, <yscan> values are amplitudes, and the frequencies are held in the yTags attribute for the plane.

Parameters

sGroup	the name for the data group this plane belongs to, may be the empty string ""
pZType	an encoding object for the new plane. The PlaneDesc will take ownership of this object and free it when del_PlaneDesc is called.
zUnits	The units of measurement for Z-axis data in this plane.
uItems	The number of data values in each packet of this plane's data. i.e. the number of yTags.
pYType	The encoding for the Y values. If NULL, a simple encoding will be defined with the format string "%.6e"
pYTags	The YTags for the new plane, if NULL the value index will be used as the YTags. I.e. the Y axis values will be 0, 1, 2, ... uItems - 1
yUnits	The units for yTag values.

Returns: A pointer to new PlaneDesc allocated on the heap.

◆ new_PlaneDesc_yscan_series()

DAS_API PlaneDesc * new_PlaneDesc_yscan_series	(	const char *	sGroup,
		DasEncoding *	pZType,
		das_units	zUnits,
		size_t	uItems,
		double	yTagInter,
		double	yTagMin,
		double	yTagMax,
		das_units	yUnits
	)

Creates a new <yscan> plane descriptor using a yTag series.

A <yscan> plane is an array of Z-values taken along Y for each X tag. Waveform packets are commonly transmitted in this plane type. In that case <x> contains first sample times, <yscan> values are amplitudes, and the time offsets are defined by the YTag series attributes of this plane

Parameters

sGroup	the name for the data group this plane belongs to, may be the empty string ""
pZType	an encoding object for the new plane. The PlaneDesc will take ownership of this object and free it when del_PlaneDesc is called.
zUnits	The units of measurement for Z-axis data in this plane.
uItems	The number of data values in each packet of this plane's data. i.e. the number of yTags.
yTagInter	the interval between values in the yTag series
yTagMin	the initial value of the series. Use DAS_FILL_VALUE to have the starting point set automatically using yTagMax.
yTagMax	the final value of the series. Use DAS_FILL_VALUE to have the ending point set automatically using yTagMin.
yUnits	The units for yTag values.

Returns: A pointer to new PlaneDesc allocated on the heap.

◆ PlaneDesc_copy()

DAS_API PlaneDesc * PlaneDesc_copy ( const PlaneDesc * pThis )

Copy constructor for planes Deep copy one a plane except for the parent id.

Parameters

pThis The plane descriptor to copy

Returns: A new plane descriptor allocated on the heap. All properties of the plane descriptor are duplicated as well.

◆ del_PlaneDesc()

DAS_API void del_PlaneDesc ( PlaneDesc * pThis )

Free a plane object allocated on the heap.

This frees the memory allocated for the main structure as well as any internal buffers allocated for storing data values and Y-tags.

Parameters

pThis The plane descriptor to free

◆ PlaneDesc_equivalent()

DAS_API bool PlaneDesc_equivalent	(	const PlaneDesc *	pThis,
		const PlaneDesc *	pOther
	)

Check to see if two plane descriptors describe the same output.

Two plane descriptors are considered to be the same if they result in an equivalent packet header definition. This means the same plane type with the same number of items and the same ytags along with the same data encoding and units.

The following items are not checked for equivalency:

The properties
The current data values (if any)
The user data pointer

Passing the same non-NULL pointer twice to this function will always result in a return of true, as planes are equivalent to themselves.

Parameters

pThis	The first plane descriptor
pOther	the second plane descriptor

Returns: true if the two are equivalent, false otherwise.

◆ PlaneDesc_getType()

DAS_API plane_type_t PlaneDesc_getType ( const PlaneDesc * pThis )

Get a plane's type.

Parameters

pThis The plane descriptor to query

Returns: The plane type, which is one of X, Y, YScan or Z

◆ PlaneDesc_getNItems()

DAS_API size_t PlaneDesc_getNItems ( const PlaneDesc * pThis )

Get the number of items in a plane YScan planes have a variable number of items, for all other types this function returns 1.

Parameters

pThis the PlaneDiscriptor

Returns: the number of items in plane

◆ PlaneDesc_getValue()

DAS_API double PlaneDesc_getValue	(	const PlaneDesc *	pThis,
		size_t	uIdx
	)

Get the a value from a plane.

Get the current value for an item in a plane, Note that X, Y and Z planes only have one item.

See also: DasEnc_write() for converting doubles to time strings.

Parameters

pThis	The Plane descriptor object
uIdx	the index of the value to retrieve, this is always 0 for X, Y, and Z planes.

Returns: the current value or DAS_FILL_VALUE in no data have been read or set.

◆ PlaneDesc_getDatum()

DAS_API const das_datum * PlaneDesc_getDatum	(	const PlaneDesc *	pThis,
		size_t	uIdx,
		das_datum *	pD
	)

Get a datum from a plane.

Get the i-th datum from a plane. Datums are a value plus a unit.

Parameters

pD	A pointer to a datum structure that will be initialized the value at uIdx and the plane's data unit type.
pThis	The plane descriptor object
uIdx	The the index of the value to retrieve, this is always 0 for X, Y, and Z planes.

Returns: a pointer to the given datum, which will not be initialized if uIdx is out of range.

◆ PlaneDesc_setValue()

DAS_API DasErrCode PlaneDesc_setValue	(	PlaneDesc *	pThis,
		size_t	uIdx,
		double	value
	)

Set a current value in a plane.

Set a current value for an item in a plane. Note X, Y and Z planes only have one item.

Parameters

pThis	The plane in question
uIdx	the index of the value to set. Only YScan planes have data at indicies above 0.
value	The new value

Returns: 0 if successful or a positive error number otherwise.

◆ PlaneDesc_setTimeValue()

DAS_API DasErrCode PlaneDesc_setTimeValue	(	PlaneDesc *	pThis,
		const char *	sTime,
		size_t	idx
	)

Set a single time value in a plane.

Manually sets a current value for a plane instead of decoding it from an input stream. The given time string is converted to a broken down time using the parsetime function from daslib and then the broken down time is converted to a double in the units specified for this plane.

Parameters

pThis	The plane to get the value
sTime	a parse-able time string
idx	The index at which to write the value, for X, Y and Z planes 0 is the only valid index.

Returns: 0 if successful or a positive error number otherwise. Attempting to set a time value for planes who's units are not time is an error.

◆ PlaneDesc_getValEncoder()

DAS_API DasEncoding * PlaneDesc_getValEncoder ( PlaneDesc * pThis )

Get the data value encoder/decoder object for a plane The encoder returned via this pointer can be mutated and any changes will be reflected in the next data write for the plane.

Parameters

pThis The data plane in question

Returns: The current encoder for this plane. You may change fields within the returned encoder but do not free() the return value.

◆ PlaneDesc_setValEncoder()

DAS_API void PlaneDesc_setValEncoder	(	PlaneDesc *	pThis,
		DasEncoding *	pEnc
	)

Set the data value encoder/decoder object for a plane The previous encoder's memory is returned the heap via free().

Parameters

pThis	The data plane in question
pEnc	A pointer to the new encoder structure, the plane takes ownership of it's memory. This value must not be null

◆ PlaneDesc_getValues()

DAS_API const double * PlaneDesc_getValues ( const PlaneDesc * pThis )

Get a pointer to the current set of values in a plane.

Planes are basically wrappers around a double array with some encoding and decoding information. This function provides a pointer to the value array for the plane.

Parameters

[in] pThis The plane in question

Returns: A pointer to the current plane's data, or NULL if neither PlaneDesc_setValue() or PlaneDesc_decode() have been called.

◆ PlaneDesc_setValues()

DAS_API void PlaneDesc_setValues	(	PlaneDesc *	pThis,
		const double *	pData
	)

Set all the current values for a plane.

See also: PlaneDesc_getNItems()

Parameters

pThis	The plane to receive the values
pData	A pointer to an array of doubles that is the same length as the number of items in this plane. Values are copied in, no references are kept to the input pointer after the function completes

◆ PlaneDesc_getFill()

DAS_API double PlaneDesc_getFill ( const PlaneDesc * pThis )

Returns the fill value identified for the plane.

Note: If the value has not been explicitly specified, then the canonical value is used.

◆ PlaneDesc_getName()

DAS_API const char * PlaneDesc_getName ( const PlaneDesc * pThis )

Get the data group of a plane.

Returns: the group of the plane, or "" if it is not specified.

◆ PlaneDesc_setName()

DAS_API void PlaneDesc_setName	(	PlaneDesc *	pThis,
		const char *	sName
	)

Set the data group of a plane.

Parameters

pThis	The plane descriptor to regroup
sGroup	the new data group for the plane, will be copied into internal memory

◆ PlaneDesc_getUnits()

DAS_API das_units PlaneDesc_getUnits ( const PlaneDesc * pThis )

Get the units of measure for a plane's packet data.

Returns: the units of the data values in a plane

◆ PlaneDesc_setUnits()

DAS_API void PlaneDesc_setUnits	(	PlaneDesc *	pThis,
		das_units	units
	)

Set the unit type for the plane data.

All Das2 Stream values are stored as doubles within the library the units property indicates what these doubles mean

Parameters

pThis	The Plane to alter
units	The new units setting. Note this value may be NULL in which case the Plane will be set to UNIT_DIMENSIONLESS.

◆ PlaneDesc_getYTagUnits()

DAS_API das_units PlaneDesc_getYTagUnits ( PlaneDesc * pThis )

Get Y axis units for a 2-D plane.

Returns: the Units of the YTags of a <yscan> plane.

◆ PlaneDesc_getYTags()

DAS_API const double * PlaneDesc_getYTags ( const PlaneDesc * pThis )

Get Y axis coordinates for a 2-D plane of data.

Returns: an array of doubles containing the yTags for the YSCAN plane or null if yTags are just a simple series.

See also: PlaneDesc_getOrMakeYTags() for a function that always creates a set of YTags; PlaneDesc_getYTagInterval()

◆ PlaneDesc_getOrMakeYTags()

DAS_API const double * PlaneDesc_getOrMakeYTags ( PlaneDesc * pThis )

Get Y tags as an array regardless of the storage type If a yTags array is constructed via this method it is cleaned up when the plane destructor is called.

See also: PlaneDesc_getYTagSpec() getYTags()

◆ PlaneDesc_encode()

DAS_API DasErrCode PlaneDesc_encode	(	PlaneDesc *	pThis,
		DasBuf *	pBuf,
		const char *	sIndent
	)

Serialize a Plane Descriptor as XML data.

This function is almost the opposite of new_PlaneDesc_pairs()

Parameters

pThis	The plane descriptor to store as string data
pBuf	A buffer object to receive the bytes
sIndent	A string to place before each line of output

Returns: 0 if successful, or a positive integer if not.

◆ PlaneDesc_encodeData()

DAS_API DasErrCode PlaneDesc_encodeData	(	PlaneDesc *	pThis,
		DasBuf *	pBuf,
		bool	bLast
	)

Serialize a plane's current data.

In addition to holding the format information for a single data plane in a Packet, PlaneDesc objects also hold one set of samples for the plane. For the plane types <x>, <y>, and <z> a single plane's data is just one value. For the <yscan> type a single plane's data is 1-N values. Use this function to encode a planes current data values for output.

Parameters

pThis	The plane descriptor that has been loaded with data
pBuf	A buffer to receive the encoded bytes
bLast	All ASCII type values are written with a single space after the value except for the last value of the last plane which has a newline character appended. Set this to true if this is the last plane in the packet which is being encoded.

Returns: 0 if successful, or a positive integer if not.

◆ PlaneDesc_decodeData()

DAS_API DasErrCode PlaneDesc_decodeData	(	const PlaneDesc *	pThis,
		DasBuf *	pBuf
	)

Read in a plane's current data.

Parameters

pThis	The plane to receive the data values
pBuf	The buffer containing values to decode.

Returns: 0 if successful, or a positive integer if not.

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

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

das2/plane.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ new_PlaneDesc()

◆ new_PlaneDesc_yscan()

◆ new_PlaneDesc_yscan_series()

◆ PlaneDesc_copy()

◆ del_PlaneDesc()

◆ PlaneDesc_equivalent()

◆ PlaneDesc_getType()

◆ PlaneDesc_getNItems()

◆ PlaneDesc_getValue()

◆ PlaneDesc_getDatum()

◆ PlaneDesc_setValue()

◆ PlaneDesc_setTimeValue()

◆ PlaneDesc_getValEncoder()

◆ PlaneDesc_setValEncoder()

◆ PlaneDesc_getValues()

◆ PlaneDesc_setValues()

◆ PlaneDesc_getFill()

◆ PlaneDesc_getName()

◆ PlaneDesc_setName()

◆ PlaneDesc_getUnits()

◆ PlaneDesc_setUnits()

◆ PlaneDesc_getYTagUnits()

◆ PlaneDesc_getYTags()

◆ PlaneDesc_getOrMakeYTags()

◆ PlaneDesc_encode()

◆ PlaneDesc_encodeData()

◆ PlaneDesc_decodeData()

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