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 value classes: what one whole externally indexable thing is – a number, a calendar time, a string, or a composite of simple elements. More...

Functions
DAS_API const char *	das_enc_fromStr (const char *sEncType)
	Resolve a wire-encoding string to its canonical schema value.
DAS_API const char *	das_sem_default (das_val_type vt, das_units units)
	Suggest a default semantic for a (value type, units) pair.
DAS_API das_val_type	das_vt_default (const char *sSemantic)
	Given a semantic meaning, suggest a default value type.
DAS_API const char *	das_sem_fromStr (const char *sSemantic)
	Resolve a semantic string to its canonical schema value.

Variables
DAS_API const char *	DAS_ENC_BYTE
	The EncodingType pattern from das-basic-stream-v3.0.xsd namely: byte,ubyte,BEint,BEuint,BEreal,LEint,LEuint,LEreal,utf8,blob,base64 .
DAS_API const char *	DAS_SEM_BLOB
	Value meanings, which are a higher level concept then the plain storage information.

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 value classes: what one whole externally indexable thing is – a number, a calendar time, a string, or a composite of simple elements.

This is the presentation vocabulary used by datums and variables. Array STORAGE uses only the simple subset; see das_elem_type below for the storage-element view of the same numbering.

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

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

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

DAS_API 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. So a vtText field may values meant as integers, or a vtLong of TT2000 times. So storage answers "what bytes?" but semantic answers "what do they mean, and what operations make sense?".

This is the single place wire spellings are normalized (liberal-in): "int" and 'integer' both maps to DAS_SEM_INT. Output is always a canonical DAS_SEM_* singleton pointer defined above.

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.

Variable Documentation

DAS_ENC_BYTE

DAS_API const char* DAS_ENC_BYTE

extern

The EncodingType pattern from das-basic-stream-v3.0.xsd namely: byte,ubyte,BEint,BEuint,BEreal,LEint,LEuint,LEreal,utf8,blob,base64 .

An encoding says how values are serialized into a packet.

An encoding plus the element size in bytes picks the storage type. Each value is a singleton so we can compare pointers.
@See das_enc_fromStr().

DAS_SEM_BLOB

DAS_API const char* DAS_SEM_BLOB

extern

Value meanings, which are a higher level concept then the plain storage information.

Taken from das-basic-stream-v3.0.xsd, namely: bool, datetime, integer, real, string, blob A semantic is how values are interpreted, which can be orthogonal to how they're stored. For example a TT2000 integer and a UTC string are both datetime's, but in radically different representations.

Using singleton pointers here again for speed.