#include <das2/encoding.h>

Detailed Description

Reading and writing values on das2 streams.

Values in a Das2 Stream have can be encoded in a variety of ways. Values can be big-endian reals, little-endian floats, ASCII strings, etc. In to it's basic category values can be represented on the stream using a variable number of bytes. It is the job of this class to handle encoding and decoding values from a Das2 Stream.

This class handles syntax not semantics. The type of measurement represented by a value depends on it's das_units Any double value can be output as in any given encoding. The functions for this class are happy to output amplitudes at time strings. It's up to other classes to see that proper encodings are used.

This class contains no pointers to heap objects and thus may be handled as pure stack variables.

See Also: das_units; PlaneDesc

Public Member Functions
DasEncoding *	new_DasEncoding (int nCat, int nWidth, const char *sFmt)
	Make a new data encoder/decoder. More...

DasEncoding *	new_DasEncoding_str (const char *sType)
	Create a new encoding based on the encoding type string. More...

void	DasEnc_setAsciiFormat (DasEncoding pThis, const char sValFmt, int nFmtWidth)
	Set the output format to be used when converting interal binary values to ASCII strings. More...

void	DasEnc_setTimeFormat (DasEncoding pThis, const char sTimeFmt, int nFmtWidth)
	Set the output format to be used when converting binary time values to to ASCII strings. More...

unsigned int	DasEnc_hash (const DasEncoding *pThis)
	Get a hash value suitable for use in switch statements. More...

DasErrCode	DasEnc_toStr (DasEncoding pThis, char sType, size_t nLen)
	Get a string representation of the data type. More...

DasErrCode	DasEnc_write (DasEncoding pThis, DasBuf pBuf, double value, das_units units)
	Encode and write a value onto a string. More...

DasErrCode	DasEnc_read (const DasEncoding pThis, DasBuf pBuf, das_units units, double *pOut)
	Read and Decode a value from a string. More...

Data Fields
unsigned int	nCat
	The basic encoding category. More...

unsigned int	nWidth
	The width in bytes of the encoded values. More...

char	sFmt [DASENC_FMT_LEN]
	The sprintf format string. More...

char	sType [DASENC_TYPE_LEN]
	The type value for this encoding on a Das2 Stream. More...

Member Function Documentation

DasEncoding * new_DasEncoding_str ( const char * sType )

Create a new encoding based on the encoding type string.

Parameters

sType the type string from a Das2 Stream plane definition. This should be one of, sun_real8, little_endian_real8, sun_real4, little_endian_real4, asciiXX, or timeXX. Here XX is a field width.

Returns: a new DasEncoding allocated on the heap.

void DasEnc_setAsciiFormat	(	DasEncoding *	pThis,
		const char *	sValFmt,
		int	nFmtWidth
	)

Set the output format to be used when converting interal binary values to ASCII strings.

ASCII values are written to Das2 streams with a single space character between each formatted value. The last value of the the last plane is followed by a new-line character instead of a space character. Using this function will change the value format, but will not alter the separater character or the end-of-line characters. (Sorry, no CSV output formats.)

Use of this function is not required. ASCII values will receive a default format.

Parameters

pThis	The output plane in question
sValFmt	a printf style format string. Typical strings for general data values would be: '%9.2e', '%+13.6e'. In general strings such as '%13.3f' should not be used as these aren't guarunteed to have a fix output width and your value strings may be truncated.
nFmtWidth	the number of output characters indicated by this format. This is just the width of the formatted value, not including any field separators.

void DasEnc_setTimeFormat	(	DasEncoding *	pThis,
		const char *	sTimeFmt,
		int	nFmtWidth
	)

Set the output format to be used when converting binary time values to to ASCII strings.

ASCII Time values are always encoded for output using the following C-call:

* sprintf(buf, sValFmt, year, month, dayofmonth, hour, min, sec);

*

The seconds field is double precision. Note that you do not have to convert all the fields in your output. In this case the output time will be a truncated time.

ASCII values are written to Das2 streams with a single space character between each formatted value. The last value of the the last plane is followed by a new-line character instead of a space character. Using this function will change the value format, but will not alter the separater character or the end-of-line characters. Sorry, no CSV output formats.

Use of this function is not required. ASCII Time values will receive a default format.

Parameters

pThis	The output plane in question
sTimeFmt	a printf style format string. An example strings would be: '%04d-%02d-%02dT%02d:%02d%02.0fZ' for seconds resolution with the Zulu time character 'Z' appended.
nFmtWidth	the number of output characters indicated by this format. This is just the width of the formatted value, not including any field separators.

unsigned int DasEnc_hash ( const DasEncoding * pThis )

Get a hash value suitable for use in switch statements.

Combines the DasEncoding::nWidth and DasEncoding::nCategory into a single integer that represents the encoding.

Since there are only 4 binary value output encodings the following constants are defined for the binary encoding hash values.

DAS2DT_BE_REAL_4 - Big-Endian 4-byte IEEE-754 reals
DAS2DT_LE_REAL_4 - Little-Endian 4-byte IEEE-754 reals
DAS2DT_BE_REAL_8 - Big-Endian 4-byte IEEE-754 reals
DAS2DT_LE_REAL_8 - Little-Endian 4-byte IEEE-754 reals

To help with byte-swapping logic the following are also defined

DAS2DT_DOUBLE - The 8-byte real hash above that corresponds to either DAS2DT_BE_REAL_8 or DAS2DT_LE_REAL_8 depending on the host endian orber.
DAS2DT_FLOAT - The 4-byte real hash above that corresponds to either DAS2DT_BE_REAL_4 or DAS2DT_LE_REAL_4 depending on the the host endian order.

Parameters

pThis the encoding to hash

Returns: The encoding category in the lower byte and the width in the next to lowest byte.

DasErrCode DasEnc_toStr	(	DasEncoding *	pThis,
		char *	sType,
		size_t	nLen
	)

Get a string representation of the data type.

This provides a string representation of the data type that is suitable for use as the type parameter of a plane in a Das2 stream packet header. All Das2 Tools use the same string representations for encodings.

Parameters

[in]	pThis	the Das2 encoding to represent as a string.
[out]	sType	a buffer to receive this encoding's type string, should be at least 20 bytes long.
[in]	nLen	the actual length of the string buffer.

Returns: 0 on success a positive error code if there is a problem

DasErrCode DasEnc_write	(	DasEncoding *	pThis,
		DasBuf *	pBuf,
		double	value,
		das_units	units
	)

Encode and write a value onto a string.

Writes a value onto a stream without any separators. Note that the ASCII types write one fewer bytes than their DasEncoding::nWidth parameter would indicate. The last byte is left for the caller to use as a separator of thier choosing.

Parameters

pThis	the DasEncoding object to handle the translation
pBuf	a write buffer to receive the encoded bytes
value	The value to write
units	All values are held internally by the library as doubles. In the instance that the output type for this encoding is a time string this parameter will be used to determine the epoch and scale for value. Otherwise it is ignored.

Returns: 0 on success, a positive error value on an error.

DasErrCode DasEnc_read	(	const DasEncoding *	pThis,
		DasBuf *	pBuf,
		das_units	units,
		double *	pOut
	)

Read and Decode a value from a string.

Reads a value from a stream consuming and ignoring separators.

Parameters

[in]	pThis	the DasEncoding object to handle the translation
[in]	pBuf	The buffer to read from. This buffer should have at least DasEncoding::nWidth more valid bytes in the buffer from the current read location.
[in]	units	All values are held internally by the library as doubles. this means that times must be converted to some number of steps from a 0 time. The units value provides this information. It is not consulted for non-time fields.
[out]	pOut	The decoded value.

Returns: 0 on success or a positive error code if there is a problem.

Field Documentation

unsigned int nCat

The basic encoding category.

This may be one of:

DAS2DT_BE_REAL Most Significant byte First (big-endian) IEEE-754 reals
DAS2DT_LE_REAL Most Significant byte First (little-endian) IEEE-754 reals
DAS2DT_ASCII A real number formatted in some number of significant digits
DAS2DT_TIME A date-time formatted as an ASCII ISO-8601 string. Additionally the following is defined for code that just wants to work in the host byte order, which ever it happens to be:
DAS2DT_HOST_REAL

unsigned int nWidth

The width in bytes of the encoded values.

The largest width for an encoding in Das2 is 127 bytes. Not all encoding categories support all widths the REAL types only allow for 4 or 8 bytes widths.

char sFmt[DASENC_FMT_LEN]

The sprintf format string.

This is the format converting doubles and times to ASCII strings. Non-ASCII encodings do not make use of this string. In that case it is set by new_DasEncoding() and DasEnc_fromString() to NULL

char sType[DASENC_TYPE_LEN]

The type value for this encoding on a Das2 Stream.

For ASCII types the type value width is assumed to be one larger than the actual number of bytes in the formatted output to allow for a field separator of some type.

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

das2/encoding.h

Detailed Description

Public Member Functions

Data Fields

Member Function Documentation

Field Documentation