DasEncoding Class Reference

#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 UnitType 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:: UnitType; PlaneDesc

Public Member Functions
DasEncoding *	new_DasEncoding (int nCat, int nWidth, const char *sFmt)
	Make a new data encoder/decoder.
DasEncoding *	new_DasEncoding_str (const char *sType)
	Create a new encoding based on the encoding type string.
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.
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.
unsigned int	DasEnc_hash (const DasEncoding *pThis)
	Get a hash value suitable for use in switch statements.
ErrorCode	DasEnc_toString (DasEncoding pThis, char pBuf, size_t nLen)
	Get a string representation of the data type.
ErrorCode	DasEnc_write (DasEncoding pThis, DasBuf pBuf, double value, UnitType units)
	Encode and write a value onto a string.
ErrorCode	DasEnc_read (const DasEncoding pThis, DasBuf pBuf, UnitType units, double *pOut)
	Read and Decode a value from a string.
Data Fields
unsigned int	nCat
	The basic encoding category.
unsigned int	nWidth
	The width in bytes of the encoded values.
char	sFmt [DASENC_FMT_LEN]
	The sprintf format string.
char	sType [DASENC_TYPE_LEN]
	The type value for this encoding on a Das2 Stream.

Member Function Documentation

DasEncoding * new_DasEncoding	(	int	nCat,
		int	nWidth,
		const char *	sFmt
	)

Make a new data encoder/decoder.

There is no corresponding destructor for DasEncoding structures, since these are self-contained and have no sub-pointers to heap objects. Use free() to delete structures returned by this function.

Parameters:

nCat

The basic encoding category one of:

DAS2DT_BE_REAL
DAS2DT_LE_REAL
DAS2DT_HOST_REAL
DAS2DT_ASCII
DAS2DT_TIME

nWidth

The width in bytes of each encoded value

sFmt

If not NULL then this sprintf style string will be use to format the values for output. If the encoding is just used for input then a format string is not required. If the encoding is used for output and no format string has been set the library will assign a reasonable default.

Returns:: A new DasEncoding structure allocated on the heap.

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-02dT02d:02d02.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.

ErrorCode DasEnc_toString	(	DasEncoding *	pThis,
		char *	pBuf,
		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]`	type	a Das2 encoding to represent as a string.
`[out]`	a	buffer to receive the encoding, should be at least 20 bytes long.
`[in]`	the	length buffer.

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

ErrorCode DasEnc_write	(	DasEncoding *	pThis,
		DasBuf *	pBuf,
		double	value,
		UnitType	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.

ErrorCode DasEnc_read	(	const DasEncoding *	pThis,
		DasBuf *	pBuf,
		UnitType	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]`	pRead	The location to read from. This location should have at least DasEncoding::nWidth more valid bytes in the buffer from the 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 DasEncoding::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 DasEncoding::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 DasEncoding::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 DasEncoding::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

DasEncoding Class Reference

Detailed Description

Public Member Functions

Data Fields

Member Function Documentation

Field Documentation