value.h File Reference

A generic value type for use in arrays, datums and variables. More...

#include <stdint.h>
#include <das3/util.h>
#include <das3/units.h>

Include dependency graph for value.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	DAS_FILL_VALUE   -1e31
	Canonical fill value (.
#define	DAS_INT64_FILL   -0x7FFFFFFFFFFFFFFFL
	Conversion fill value for integer time intervals (-9.223e+18)
#define	DAS_BS_NULL   ((das_byte_seq){NULL, 0})
	Convenience macros for an empty byte sequence fat pointer.
#define	das_vt_isint(VT)   ( VT >= vtUByte && VT <= vtLong )
	Is this value type an integer of some sort.
#define	das_vt_isreal(VT)   ( VT == vtFloat || VT == vtDouble )
	Is this value type an real value of some sort.
#define	das_vt_rank(VT)   ( ((VT==vtText)||(VT==vtByteSeq)) ? 1:0)
	Get the rank of a value type.

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

Enumerations
enum	das_val_type {   vtUnknown = 0 , vtUByte = 1 , vtByte = 2 , vtUShort = 3 ,   vtShort = 4 , vtUInt = 5 , vtInt = 6 , vtULong = 7 ,   vtLong = 8 , vtFloat = 9 , vtDouble = 10 , vtTime = 11 ,   vtIndex = 12 , vtText = 13 , vtByteSeq = 15 , vtComposite = 16 }
	Enumeration of types stored in Das Array (DasAry) objects from value.h. More...

Functions
const char *	das_enc_fromStr (const char *sEncType)
	Resolve a wire-encoding string to its canonical schema value.
const char *	das_sem_default (das_val_type vt, das_units units)
	Suggest a default semantic for a (value type, units) pair.
das_val_type	das_vt_default (const char *sSemantic)
	Given a semantic meaning, suggest a default value type.
const char *	das_sem_fromStr (const char *sSemantic)
	Resolve a semantic string to its canonical schema value.
DAS_API das_valcmp_func	das_vt_getcmp (das_val_type vt)
	Get the comparison function for two values of this type.
DAS_API int	das_value_cmpAny (const ubyte *pA, das_val_type vtA, const ubyte *pB, das_val_type vtB)
	Compare any two value types for equality.
DAS_API 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.
DAS_API DasErrCode	das_value_binXform (das_val_type vtIn, const ubyte *pValIn, const ubyte *pFillIn, das_val_type vtOut, ubyte *pValOut, const ubyte *pFillOut, uint32_t uFlags)
	Convert any integral type to any other with range checking and swapping.
DAS_API DasErrCode	das_value_fmt (char *sBuf, int nBufLen, das_val_type vt, const char *sSemantic, int nFitTo)
	Generate a printf style format code for a value type, usage and buffer size.
DAS_API void	das_value_trimReal (char *sVal)
	Small helper for printing reals in less space.
DAS_API DasErrCode	das_value_fromStr (ubyte *pBuf, int uBufLen, das_val_type vt, const char *sStr)
	Get a das value from a null terminated string.
DAS_API bool	das_str2double (const char *str, double *pRes)
	Convert a string value to a 8-byte float, similar to strtod(3).
DAS_API bool	das_str2int (const char *str, int *pRes)
	Convert the initial portion of a string to an integer with explicit over/underflow checks.
DAS_API bool	das_str2bool (const char *str, bool *pRes)
	Convert a string value to a boolean value.
DAS_API bool	das_str2baseint (const char *str, int base, int *pRes)
	Convert a string to an integer with explicit base and overflow checking.
DAS_API 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.
DAS_API double *	das_csv2doubles (const char *s, int *nitems)
	Parse a comma separated list of ASCII values into a double array.
DAS_API char *	das_doubles2csv (char *pBuf, size_t uBufSz, const double *pValues, int nValues)
	Print an array of doubles into a string buffer.
DAS_API char *	das_floats2csv (char *pBuf, size_t uBufSz, const float *pValues, int nValues)
	Similar to das_doubles2csv, but for 32-bit floats.

Variables
const char *	DAS_ENC_BYTE
	The canonical wire-encoding vocabulary: the closed set that IS the schema's EncodingType pattern (das-basic-stream-v3.0.xsd, byte|ubyte|BEint|BEuint|BEreal|LEint|LEuint|LEreal|utf8|blob|base64).
const char *	DAS_SEM_BLOB
	The canonical value-semantic vocabulary: the closed set that IS the schema's Semantic pattern (das-basic-stream-v3.0.xsd, bool|datetime|integer|real|string|blob).

Detailed Description

A generic value type for use in arrays, datums and variables.

Macro Definition Documentation

das_vt_rank

#define das_vt_rank

(

VT

)

( ((VT==vtText)||(VT==vtByteSeq)) ? 1:0)

Get the rank of a value type.

Most items are scalars (rank 0), but strings and byte runs are rank 1

Function Documentation

das_value_cmpAny()

DAS_API int das_value_cmpAny	(	const ubyte *	pA,
		das_val_type	vtA,
		const ubyte *	pB,
		das_val_type	vtB
	)

Compare any two value types for equality.

If two types (vtA, vtB) are the same, memcmp is used. If two types are different the following promotion rules are applied.

1. Strings are never equal to non strings.
2. Since values have no units, times are never equal to non-times

If either side is a vtByte, vtUShort, vtShort, vtInt, or vtFloat, vtDouble, both sides are promoted to double and compared.

Returns

-1 if A is less than B, 0 if equal, +1 if A is greater than B or -2 if A is not comparable to B.

das_vt_merge()

DAS_API 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 involving times are unknown

Parameters

right
op	An operation ID.
left

Returns

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

das_value_binXform()

DAS_API DasErrCode das_value_binXform	(	das_val_type	vtIn,
		const ubyte *	pValIn,
		const ubyte *	pFillIn,
		das_val_type	vtOut,
		ubyte *	pValOut,
		const ubyte *	pFillOut,
		uint32_t	uFlags
	)

Convert any integral type to any other with range checking and swapping.

@Note this function does not trigger on resolution loss unless requested.

If one or both fill value pointers are NULL, all values are converted as if they represented valid items.

Parameters

vtIn	the value type of the input
pValIn	pointer to the input value
pFillIn	the fill value for the input type, or NULL
vtOut	the value type of the output
pValOut	pointer to the output value storage
pFillOut	the fill value for the output type, or NULL
uFlags	A set of flags or'ed together. These are: DAS_VAL_NOERR_RNG no error return on range violations DAS_VAL_ERR_RESLOSS error return or resolution loss

Returns

DAS_OKAY if the conversion was successful, a positive error value if a range violation was triggered.

das_value_fmt()

DAS_API DasErrCode das_value_fmt	(	char *	sBuf,
		int	nBufLen,
		das_val_type	vt,
		const char *	sSemantic,
		int	nFitTo
	)

Generate a printf style format code for a value type, usage and buffer size.

Note

If nFitTo is too short you might get a format string that's too long without any warning. Checking the length of text output produced when writing a formatted value is recommended.

Parameters

sBuf	where to store the format string
nBufLen	space for the format string storage
vt	the value type in need of a format string
sSemantic	how the value is used. Format code changes for binary usage versus text or regular values.
nFitTo	If -1 the format string will produce variable length output if a positive number > 2 a fixed length format will be generated.

Returns

DAS_OKAY if a format string could be generated, a positive error value otherwise.

das_value_trimReal()

DAS_API void das_value_trimReal

(

char *

sVal

)

Small helper for printing reals in less space.

Since we don't know how precise a double precision value is, it's common to want to print these to 14 digits (or similar). Many times all those extra digits are just zeros. Use this function to shorten real values that after they have been written to a buffer.

das_value_fromStr()

DAS_API DasErrCode das_value_fromStr	(	ubyte *	pBuf,
		int	uBufLen,
		das_val_type	vt,
		const char *	sStr
	)

Get a das value from a null terminated string.

This function should not exit, instead erroneous parsing triggers log messages

Returns

DAS_OKAY if parsing was successful, an error return code otherwise.

das_str2double()

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

das_str2int()

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

das_str2bool()

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

das_str2baseint()

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

das_strn2baseint()

DAS_API 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' character will still halt character accumulation.
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.

das_csv2doubles()

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

das_doubles2csv()

DAS_API char * das_doubles2csv	(	char *	pBuf,
		size_t	uBufSz,
		const double *	pValues,
		int	nValues
	)

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]	pBuf	a pointer to the buffer to receive the printed values
[in]	uBufSz	The length of the buffer to received the converted values
[in]	pValues	an array of doubles
[in]	nValues	the number of items to print to the array

Returns

A pointer to the supplied buffer.