das_datum Struct Reference

An atomic data processing unit, and it's units. More...

#include <das2/datum.h>

Public Member Functions
#define	das_datum_valid(p)   ((p)->vsize > 0)
	Check to seef if a datum has been initialized. More...
DAS_API bool	das_datum_fromStr (das_datum *pThis, const char *sStr)
	Initialize a numeric datum from a value and units string. More...
DAS_API bool	das_datum_fromDbl (das_datum *pThis, double value, das_units units)
	Create a datum from a double value and units. More...
DAS_API bool	das_datum_wrapStr (das_datum *pTHis, const char *sStr, das_units units)
	Wrap an external string as a datum. More...
DAS_API bool	das_datum_byteSeq (das_datum *pThis, das_byteseq seq, das_units units)
	Wrap an external unknown type pointer as a datum. More...
DAS_API char *	das_datum_toStr (const das_datum *pThis, char *sStr, size_t uLen, int nFracDigits)
	Write a UTF-8 string representation of a datum to a buffer. More...
DAS_API char *	das_datum_toStrValOnly (const das_datum *pThis, char *sStr, size_t uLen, int nFracDigits)
	Same as das_datum_toStr, but never print the units. More...
DAS_API double	das_datum_toDbl (const das_datum *pThis)
	Get a datum value as a double. More...
DAS_API bool	das_datum_toEpoch (const das_datum *pThis, das_units epoch, double *pResult)
	Get a time datum value as a double at a given epoch an scale. More...
#define	das_datum_asStr(dm)   *((char**)&dm)
	Get the value form a string datum.

Detailed Description

An atomic data processing unit, and it's units.

Datum objects can be created as stack variables. For any object up to DATUM_BUF_SZ all memory is internal and the plain old C equals (=) operator can be used to assign the contents of one datum to another.

For larger objects an external constant pointer is used to denote the value. So copy by = still works. Use das_datum_islocal() to determine if the datum value is contained in local memory or if it's an external reference.

Datums have thier byte array stored first in their structure so it is possible to cast pointers to datums as pointers to their type if the type is known. For example:

das_datum dm;
das_datum_fromStr(&dm, "2017-01-02T12:14");
 
int year = ((*das_time)(&dm))->year;
 
// This works
das_datum_Double(&dm, "2.145 meters");
double length = *((*double)dm);

The datum class is made to work with Variable, to provide a single "value" of a variable, however these values may contain internal structure. Two prime examples are geometric vectors and strings.

Member Function Documentation

das_datum_fromStr()

DAS_API bool das_datum_fromStr	(	das_datum *	pThis,
		const char *	sStr
	)

Initialize a numeric datum from a value and units string.

Note that this function will not initialize text datums. This is because text datums only carry a const char* pointer, but not the string itself. Call Datum_wrapStr() to make text datums.

Parameters

pThis	pointer to the datum structure to initialize
sStr	the value plus it's units.

Returns

true if the string was parseable as a datum, false otherwise.

das_datum_fromDbl()

DAS_API bool das_datum_fromDbl	(	das_datum *	pThis,
		double	value,
		das_units	units
	)

Create a datum from a double value and units.

This is the most commonly used type of datum, followed by time datums

Parameters

pThis
value
units

Returns

Always returns true.

das_datum_wrapStr()

DAS_API bool das_datum_wrapStr	(	das_datum *	pTHis,
		const char *	sStr,
		das_units	units
	)

Wrap an external string as a datum.

This is useful for events lists as well as non-numeric coordinate points. For example:

static const char** cites[] = {
   "Iowa City", "Coralville", "North Liberty", "Cedar Rapids"
};
 
Make a datum array representing a few cities in Eastern Iowa with units
of "city".
 
datum locations[4];
for(int i = 0; i < 4; ++i)
    das_datum_initStr(locations + i, "city", cities[i]);

das_datum_byteSeq()

DAS_API bool das_datum_byteSeq	(	das_datum *	pThis,
		das_byteseq	seq,
		das_units	units
	)

Wrap an external unknown type pointer as a datum.

This is for special user defined data types unknown to das2C. The type of the datum will be vtByteSeq (a byte sequence)

das_datum_toStr()

DAS_API char * das_datum_toStr	(	const das_datum *	pThis,
		char *	sStr,
		size_t	uLen,
		int	nFracDigits
	)

Write a UTF-8 string representation of a datum to a buffer.

Time values are printed as ISO-8601 time strings, all floating point values are printed using a generic exponential notation. String datums are simply printed, and byteseq datums are printed as hex-digits.

Parameters

pThis	The datum to write
sStr	The buffer to write the reprenestation to
uLen	The amount of space available for writing
nFracDigits	Number of digits after the decimal place to print. for multi-part values, such a calendar times this refers to the number of digits after the decimal point for the last component only. Use -1 to get default fractional digits which are 5 for a float, 9 for a double and millisec precision for times.

Returns

The write point for adding more text to the buffer. To see how much text was written subtract the initial buffer (sBuf) from this return value.

das_datum_toStrValOnly()

DAS_API char * das_datum_toStrValOnly	(	const das_datum *	pThis,
		char *	sStr,
		size_t	uLen,
		int	nFracDigits
	)

Same as das_datum_toStr, but never print the units.

See also

das_datum_toStr

das_datum_toDbl()

DAS_API double das_datum_toDbl

(

const das_datum *

pThis

)

Get a datum value as a double.

This function throws an error if the given datum is not convertable as a double value

Parameters

pThis

Returns

The double value

das_datum_toEpoch()

DAS_API bool das_datum_toEpoch	(	const das_datum *	pThis,
		das_units	epoch,
		double *	pResult
	)

Get a time datum value as a double at a given epoch an scale.

Parameters

pThis	pointer to the value to convert
units	The desired time base units, expects one of UNIT_US2000 and friends. Do not use UNIT_UTC, that's only ment for broken down time values.
pResult	Pointer to location to store the converted value.

Returns

true if the conversion was successful, false otherwise and das_error is called.

---

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

• das2/datum.h