Values

Basic data storage elements. More...

Detailed Description

Basic data storage elements.

Data Structures
struct	das_datum
	A value and it's units. More...

Typedefs
typedef int(*	das_valcmp_func )(const void *, const void *)
	Comparison functions look like this.

Enumerations
enum	das_val_type {   vtUnknown = 0 , vtByte, vtUShort, vtShort,   vtInt, vtLong, vtFloat, vtDouble,   vtTime, vtText, vtByteSeq }
	Enumeration of types stored in Das Array (DasAry) objects Not that any kind of value may be stored in a Das Array, but most of these types have runtime type safty checks. More...

Functions
bool	das_datum_fromStr (das_datum *pThis, const char *sStr)
	Initialize a numeric datum from a value and units string. More...
bool	das_datum_fromDbl (das_datum *pThis, double value, das_units units)
	Create a datum from a double value and units. More...
bool	das_datum_wrapStr (das_datum *pTHis, const char *sStr, das_units units)
	Wrap an external string as a datum. More...
bool	das_datum_byteSeq (das_datum *pThis, das_byteseq seq, das_units units)
	Wrap an external unknown type pointer as a datum. More...
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...
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...
double	das_datum_toDbl (const das_datum *pThis)
	Get a datum value as a double. More...
const void *	das_vt_fill (das_val_type vt)
	Get the default fill value for a given element type. More...
size_t	das_vt_size (das_val_type vt)
	Get the size in bytes for a given element type.
const char *	das_vt_toStr (das_val_type vt)
	Get a text string representation of an element type.
das_valcmp_func	das_vt_getcmp (das_val_type vt)
	Get the comparison function for two values of this type.
das_val_type	das_vt_merge (das_val_type right, int op, das_val_type left)
	What would be the resulting type given an operation on the given value type. More...
bool	das_str2double (const char *str, double *pRes)
	Convert a string value to a 8-byte float, similar to strtod(3). More...
bool	das_str2int (const char *str, int *pRes)
	Convert the initial portion of a string to an integer with explicit over/underflow checks. More...
bool	das_str2bool (const char *str, bool *pRes)
	Convert a string value to a boolean value. More...
bool	das_str2baseint (const char *str, int base, int *pRes)
	Convert a string to an integer with explicit base and overflow checking. More...
bool	das_strn2baseint (const char *str, int nLen, int base, int *pRes)
	Convert an explicit length string to an integer with explicit base with over/underflow checks. More...
double *	das_csv2doubles (const char *s, int *nitems)
	Parse a comma separated list of ASCII values into a double array. More...
char *	das_doubles2csv (char *buf, const double *value, int nitems)
	Print an array of doubles into a string buffer. More...

Enumeration Type Documentation

enum das_val_type

Enumeration of types stored in Das Array (DasAry) objects Not that any kind of value may be stored in a Das Array, but most of these types have runtime type safty checks.

Enumerator
vtUnknown	For generic storage, designates elements as unknown, you have to cast the array return values yourself.
vtByte	Indicates array values are unsigned 8-bit unsigned integers (bytes)
vtUShort	Indicates array values are unsigned 16-bit integers (shorts)
vtShort	Indicates array values are signed 16-bit integers (shorts)
vtInt	Indicates array values are signed 32-bit integers (ints)
vtLong	Indicates array values are signed 64-bit integers (longs)
vtFloat	Indicates array values are 32-bit floating point values (floats)
vtDouble	Indicates array values are 64-bit floating point values (doubles)
vtTime	Indicates array values are das_time_t structures.
vtText	Indicates datum values are const char* pointers to null terminated UTF-8 strings.
vtByteSeq	Indicates datum values are size_t plus const byte* pairs, no more is known about the bytes.

Function Documentation

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.

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.

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]);
*
* 

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 libdas2. The type of the datum will be vtByteSeq (a byte sequence)

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.

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

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

const void* das_vt_fill

(

das_val_type

vt

)

Get the default fill value for a given element type.

Returns

a pointer to the default fill value, will have to cast to the appropriate type.

das_val_type das_vt_merge	(	das_val_type	right,
		int	op,
		das_val_type	left
	)

What would be the resulting type given an operation on the given value type.

Currently the binary type combining rules are:

1. Unknown combined with anything is unknown.
2. Index combined with anything is unknown.
3. ByteSeq combined with anything is unknown.
4. Text combined with anything is unknown.
5. Byte, UShort and Short math results in floats.
6. Int, Long, Float and Double math results in doubles.

7. If time in involved the following rules apply:

   Time - Time = Double Time +/- (Byte, UShort, Short, Int, Float Double) => Time

   All other operations invalving times are unknown

Parameters

right
op	An operation ID.
left

Returns

The resulting type or vtUnknown if the types cannot be combinded via any known operations

bool das_str2double	(	const char *	str,
		double *	pRes
	)

Convert a string value to a 8-byte float, similar to strtod(3).

Parameters

str	the string to convert. Conversion stops at the first improper character. Whitespace and leading 0's are ignored in the input.
pRes	The location to store the resulting 8-byte float.

Returns

true if the conversion succeeded, false otherwise. Among other reason, conversion will fail if the resulting value won't fit in a 8 byte float.

bool das_str2int	(	const char *	str,
		int *	pRes
	)

Convert the initial portion of a string to an integer with explicit over/underflow checks.

Parameters

str	the string to convert. Conversion stops at the first improper character. Whitespace and leading 0's are ignored in the input. The number is assumed to be in base 10, unless the first non-whitespace characters after the optional '+' or '-' sign are '0x'.
pRes	The location to store the resulting integer.

Returns

true if the conversion succeeded, false otherwise.

bool das_str2bool	(	const char *	str,
		bool *	pRes
	)

Convert a string value to a boolean value.

Parameters

str	the string to convert. The following values are accepted as representing true: 'true' (any case), 'yes' (any case), 'T', 'Y', '1'. The following values are accepted as representing false: 'false' (any case), 'no', (any case), 'F', 'N', '0'. Anything else results in no conversion.
pRes	the location to store the resulting boolean value

Returns

true if the string could be converted to a boolean, false otherwise.

bool das_str2baseint	(	const char *	str,
		int	base,
		int *	pRes
	)

Convert a string to an integer with explicit base and overflow checking.

Parameters

str	the string to convert. Conversion stops at the first improper character. Whitespace and leading 0's are ignored in the input. No assumptions are made about the base of the string. So anything that is not a proper character is the given base is causes an error return.
base	an integer from 1 to 60 inclusive.
pRes	The location to store the resulting integer.

Returns

true if the conversion succeeded, false otherwise.

bool das_strn2baseint	(	const char *	str,
		int	nLen,
		int	base,
		int *	pRes
	)

Convert an explicit length string to an integer with explicit base with over/underflow checks.

Parameters

str	the string to convert. Conversion stops at the first improper character. Whitespace and leading 0's are ignored in the input. No assumptions are made about the base of the string. So anything that is not a proper character is the given base is causes an error return.
base	an integer from 1 to 60 inclusive.
nLen	only look at up to this many characters of input. Encountering whitespace or a '\0' characater will still halt character accumlation.
pRes	The location to store the resulting integer.

Returns

true if the conversion succeeded, false otherwise.

Will only inspect up to 64 non-whitespace characters when converting a value.

double* das_csv2doubles	(	const char *	s,
		int *	nitems
	)

Parse a comma separated list of ASCII values into a double array.

Parameters

[in]	s	The string of comma separated values
[out]	nitems	a pointer to an integer which will be set to the length of the newly allocated array.

Returns

a new double array allocated on the heap.

char* das_doubles2csv	(	char *	buf,
		const double *	value,
		int	nitems
	)

Print an array of doubles into a string buffer.

Prints an array of doubles into a string buffer with commas and spaces between each entry. Note there is no precision limit for the printing so the space needed to hold the array may 24 bytes times the number number of values, or more.

Todo:

this function is a potential source of buffer overruns, fix it.

Parameters

[out]	buf	a pointer to the buffer to receive the printed values
[in]	value	an array of doubles
[in]	nitems	the number of items to print to the array

Returns

A pointer to the supplied buffer.