Values

Physical data values, including time, and their units. More...

Data Structures
struct	das_time
	Basic date-time structure used throughout the Das1 & Das2 utilities. More...

Macros
#define	DAS_BS_NULL   ((das_byte_seq){NULL, 0})
	Convenience macros for an empty byte sequence fat pointer.

Typedefs
typedef const char *	das_units
	Handle SI and other units, with accommodations for Epoch systems, from units.h.

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.

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

Physical data values, including time, and their units.

No units, a pure number such as a linear ratio.

Typedef Documentation

das_units

typedef const char* das_units

Handle SI and other units, with accommodations for Epoch systems, from units.h.

Note that although these are strings, Units_fromStr() should be be used to get a reference to the enumerated string since pointer equality comparison is done in the code. Thus UnitType objects created using the functions in this module satisfy the rule:

das_unit a;
das_unit b;
 
if(a == b){
  // Units are equal
}

The Epoch Time unit types understood by this library are:

• UNIT_US2000 - Non-Leap microseconds since midnight, January 1st 2000
• UNIT_MJ1958 - Days since midnight January 1st 1958
• UNIT_T2000 - Non-Leap seconds since midnight, January 1st 2000
• UNIT_T1970 - Non-Leap seconds since midnight, January 1st 1970
• UNIT_UTC - Time strings on the gregorian calendar
• UNIT_NS2020 - Non-Leap nanoseconds since midnight Jan 1st, 2020, typically transmitted as signed 8-byte integers

As it stands the library currently does not understand SI prefixes, so each scaled unit has it's own entry. This should change.

• UNIT_SECONDS - Seconds, a time span.
• UNIT_HOURS - hours, a time span = 3600 seconds.
• UNIT_MIRCOSECONDS - A smaller time span.
• UNIT_HERTZ - Hertz, a measure of frequency.
• UNIT_KILO_HERTZ - KiloHertz, another measure of frequency.
• UNIT_E_SPECDENS - Electric Spectral Density, V**2 m**-2 Hz**-1;
• UNIT_B_SPECDENS - Magnetic Spectral Density, nT**2 Hz**-1;
• UNIT_NT - Magnetic Field intensity, nT
• UNIT_NUMBER_DENS - Number density, the number of items in a cubic centimeter
• UNIT_DB - Decibels, a ratio measure, typically versus 1.0.
• UNIT_KM - Kilometers, a unit of distance
• UNIT_DEGREES - Degrees, a ratio measure on circles: (arch length / circumference) * 360

And if you don't know what else to use, try this:

• UNIT_DIMENSIONLESS - I.E. No units

Todo:

Redo units as small structures

Enumeration Type Documentation

das_val_type

enum das_val_type

Enumeration of types stored in Das Array (DasAry) objects from value.h.

Note that any kind of value may be stored in a Das Array, but most of these types have runtime type safety checks.

See also

value.h for a list of functions for working with the the das_val_type enumeration

Enumerator
vtUnknown	For generic storage, designates elements as unknown, you have to cast the array return values yourself.
vtUByte	The basic types. Indicates array values are unsigned 8-bit integers (bytes)
vtByte	Indicates array values are signed 8-bit integers (signed bytes)
vtUShort	Indicates array values are unsigned 16-bit integers (shorts)
vtShort	Indicates array values are signed 16-bit integers (shorts)
vtUInt	Indicates array values are unsigned 32-bit integers (uints)
vtInt	Indicates array values are signed 32-bit integers (ints)
vtULong	Indicates array values are unsigned 64-bit unsigned integers (ulongs)
vtLong	Indicates array values are unsigned 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	Values are a picture element, possibly in multiple planes. Indicates values are size_t plus const ubyte* pairs, no more is known about the bytes
vtComposite	These values are run of simple elements plus the DasForm that says what they mean: a rotation, a complex pair, a matrix. To determine the actual form consult the object itself.

Function Documentation

das_enc_fromStr()

const char * das_enc_fromStr

(

const char *

sEncType

)

Resolve a wire-encoding string to its canonical schema value.

An encoding names how values are serialized in a packet, orthogonal to how they are stored (das_val_type) or interpreted (semantic). The vocabulary is CLOSED – exactly the DAS_ENC_* set, the schema's EncodingType pattern – and not application-expandable. This is the one place an encoding string is validated; output is a canonical DAS_ENC_* pointer, so callers may compare the result by pointer.

Parameters

sEncType

an encoding string from a stream header (may be NULL).

Returns

the canonical DAS_ENC_* pointer, or NULL if sEncType is NULL or names no member of the closed set (the caller should fail loud).

das_sem_default()

const char * das_sem_default	(	das_val_type	vt,
		das_units	units
	)

Suggest a default semantic for a (value type, units) pair.

Calendar units win over the value type: a TT2000 / us2000 / ... field is a datetime whatever integer or real it is stored as.

To relate this to the schema, vt here roughly corresponds to the "storage" attribute for a variable

Note

: Currently "bool" is not guessable, so it must be declared explicitly.

Returns

the schema semantic (a DAS_SEM_* pointer), or NULL when the value type has no semantic defined in the *.xsd schema (vtIndex, vtPixel, ...).

das_sem_fromStr()

const char * das_sem_fromStr

(

const char *

sSemantic

)

Resolve a semantic string to its canonical schema value.

A variable's semantic is how its values are meant to be INTERPRETED, orthogonal to how they are STORED (the das_val_type, roughly the schema "storage" attribute): a vtText field may hold values meant as integers; a vtLong of TT2000 ticks is meant as a datetime. Storage answers "what bytes?"; semantic answers "what do they mean, and what operations make sense?".

For das2C v3.0 the vocabulary is CLOSED – exactly the DAS_SEM_* set, which IS the schema's Semantic pattern (bool|datetime|integer|real|string|blob) – and is not application-expandable; a new semantic enters only with a schema version bump.

This is the single place wire spellings are normalized (liberal-in): "int" maps to DAS_SEM_INT. Output is always a canonical DAS_SEM_* pointer (conservative-out), so a caller may compare the result by pointer.

Parameters

sSemantic

a semantic string from a stream header (may be NULL).

Returns

the canonical DAS_SEM_* pointer, or NULL if sSemantic is NULL or names no member of the closed set (the caller should fail loud).

Variable Documentation

DAS_ENC_BYTE

const char* DAS_ENC_BYTE

extern

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

An encoding says how values are SERIALIZED in a packet – one level below storage (das_val_type) and semantic; encoding plus the item byte count picks the storage type. Each value has one canonical instance; store and compare encodings by these pointers. See das_enc_fromStr().

DAS_SEM_BLOB

const char* DAS_SEM_BLOB

extern

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

A semantic is how values are INTERPRETED, orthogonal to how they're STORED (the das_val_type). See das_sem_fromStr() for the concept. Each value has one canonical instance; store and compare DasVar semantics by these pointers, not by content.