e57::SourceDestBuffer Class Reference

A memory buffer to transfer data to/from a CompressedVectorNode in a block. More...

#include <E57Format.h>

Public Member Functions
	SourceDestBuffer ()=delete
	SourceDestBuffer (const ImageFile &destImageFile, const ustring &pathName, bool *b, size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(bool))
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
	SourceDestBuffer (const ImageFile &destImageFile, const ustring &pathName, double *b, size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(double))
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
	SourceDestBuffer (const ImageFile &destImageFile, const ustring &pathName, float *b, size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(float))
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
	SourceDestBuffer (const ImageFile &destImageFile, const ustring &pathName, int16_t *b, size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(int16_t))
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
	SourceDestBuffer (const ImageFile &destImageFile, const ustring &pathName, int32_t *b, size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(int32_t))
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
	SourceDestBuffer (const ImageFile &destImageFile, const ustring &pathName, int64_t *b, size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(int64_t))
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
	SourceDestBuffer (const ImageFile &destImageFile, const ustring &pathName, int8_t *b, size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(int8_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block.
	SourceDestBuffer (const ImageFile &destImageFile, const ustring &pathName, std::vector< ustring > *b)
	Designate vector of strings to transfer data to/from a CompressedVector as a block.
	SourceDestBuffer (const ImageFile &destImageFile, const ustring &pathName, uint16_t *b, size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(uint16_t))
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
	SourceDestBuffer (const ImageFile &destImageFile, const ustring &pathName, uint32_t *b, size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(uint32_t))
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
	SourceDestBuffer (const ImageFile &destImageFile, const ustring &pathName, uint8_t *b, size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(uint8_t))
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
size_t	capacity () const
	Get total capacity of buffer.
void	checkInvariant (bool doRecurse=true) const
	Check whether SourceDestBuffer class invariant is true.
bool	doConversion () const
	Get whether conversions will be performed to match the memory type of buffer.
bool	doScaling () const
	Get whether scaling will be performed for ScaledIntegerNode transfers.
void	dump (int indent=0, std::ostream &os=std::cout) const
	Diagnostic function to print internal state of object to output stream in an indented format.
enum MemoryRepresentation	memoryRepresentation () const
	Get memory representation of the elements in this SourceDestBuffer.
ustring	pathName () const
	Get path name in prototype that this SourceDestBuffer will transfer data to/from.
size_t	stride () const
	Get number of bytes between consecutive memory elements in buffer.

Detailed Description

A memory buffer to transfer data to/from a CompressedVectorNode in a block.

The SourceDestBuffer is an encapsulation of a buffer in memory that will transfer data to/from a field in a CompressedVectorNode. The API user is responsible for creating the actual memory buffer, describing it correctly to the API, making sure it exists during the transfer period, and destroying it after the transfer is complete. Additionally, the SourceDestBuffer has information that specifies the connection to the CompressedVectorNode field (i.e. the field's path name in the prototype).

The type of buffer element may be an assortment of built-in C++ memory types. There are all combinations of signed/unsigned and 8/16/32/64 bit integers (except unsigned 64bit integer, which is not supported in the ASTM standard), bool, float, double, as well as a vector of variable length unicode strings. The compiler selects the appropriate constructor automatically based on the type of the buffer array. However, the API user is responsible for reporting the correct length and stride options (otherwise unspecified behavior can occur).

The connection of the SourceDestBuffer to a CompressedVectorNode field is established by specifying the pathName. There are several options to this connection: doConversion and doScaling, which are described in the constructor documentation.

Class Invariant

A class invariant is a list of statements about an object that are always true before and after any operation on the object. An invariant is useful for testing correct operation of an implementation. Statements in an invariant can involve only externally visible state, or can refer to internal implementation-specific state that is not visible to the API user. The following C++ code checks externally visible state for consistency and throws an exception if the invariant is violated:

void SourceDestBuffer::checkInvariant( bool /*doRecurse*/ ) const
{
   // Stride must be >= a memory type dependent value
   const size_t min_stride = []( MemoryRepresentation inRep ) -> size_t {
      switch ( inRep )
      {
         case Bool:
         case Int8:
         case UInt8:
            return 1;
 
         case Int16:
         case UInt16:
            return 2;
 
         case Int32:
         case UInt32:
         case Real32:
            return 4;
 
         case Int64:
         case Real64:
            return 8;
 
         case UString:
            return sizeof( ustring );
 
         default:
            throw E57_EXCEPTION1( ErrorInvarianceViolation );
      }
   }( memoryRepresentation() );
 
   if ( stride() < min_stride )
   {
      throw E57_EXCEPTION1( ErrorInvarianceViolation );
   }
}
 

See also

Node

Constructor & Destructor Documentation

SourceDestBuffer() [1/12]

e57::SourceDestBuffer::SourceDestBuffer ( )

delete

SourceDestBuffer() [2/12]

SourceDestBuffer::SourceDestBuffer	(	const ImageFile &	destImageFile,
		const ustring &	pathName,
		int8_t *	b,
		size_t	capacity,
		bool	doConversion = false,
		bool	doScaling = false,
		size_t	stride = sizeof( int8_t )
	)

Designate buffers to transfer data to/from a CompressedVectorNode in a block.

Parameters

[in]	destImageFile	The ImageFile where the new node will eventually be stored.
[in]	pathName	The pathname of the field in CompressedVectorNode that will transfer data to/from.
[in]	b	The caller allocated memory buffer.
[in]	capacity	The total number of memory elements in buffer b.
[in]	doConversion	Will a conversion be attempted between memory and ImageFile representations.
[in]	doScaling	In a ScaledInteger field, do memory elements hold scaled values, if false they hold raw values.
[in]	stride	The number of bytes between memory elements. If zero, defaults to sizeof memory element.

This overloaded form of the SourceDestBuffer constructor declares a buffer b to be the source/destination of a transfer of values stored in a CompressedVectorNode.

The pathName will be used to identify a Node in the prototype that will get/receive data from this buffer. The pathName may be an absolute path name (e.g. "/cartesianX") or a path name relative to the root of the prototype (i.e. the absolute path name without the leading "/", for example: "cartesianX").

The type of b is used to determine the MemoryRepresentation of the SourceDestBuffer. The buffer b may be used for multiple block transfers. See discussions of operation of SourceDestBuffer attributes in SourceDestBuffer::memoryRepresentation, SourceDestBuffer::capacity, SourceDestBuffer::doConversion, and SourceDestBuffer::doScaling, and SourceDestBuffer::stride.

The API user is responsible for ensuring that the lifetime of the b memory buffer exceeds the time that it is used in transfers (i.e. the E57 Foundation Implementation cannot detect that the buffer been destroyed).

The capacity must match the capacity of all other SourceDestBuffers that will participate in a transfer with a CompressedVectorNode.

Precondition

The destImageFile must be open (i.e. destImageFile.isOpen() must be true).

The stride must be >= sizeof(*b)

Exceptions

ErrorBadAPIArgument
ErrorBadPathName
ErrorBadBuffer
ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also

ImageFile::reader, ImageFile::writer, CompressedVectorReader::read(std::vector<SourceDestBuffer>&), CompressedVectorWriter::write(std::vector<SourceDestBuffer>&)

SourceDestBuffer() [3/12]

SourceDestBuffer::SourceDestBuffer	(	const ImageFile &	destImageFile,
		const ustring &	pathName,
		uint8_t *	b,
		size_t	capacity,
		bool	doConversion = false,
		bool	doScaling = false,
		size_t	stride = sizeof( uint8_t )
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SourceDestBuffer() [4/12]

SourceDestBuffer::SourceDestBuffer	(	const ImageFile &	destImageFile,
		const ustring &	pathName,
		int16_t *	b,
		size_t	capacity,
		bool	doConversion = false,
		bool	doScaling = false,
		size_t	stride = sizeof( int16_t )
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SourceDestBuffer() [5/12]

SourceDestBuffer::SourceDestBuffer	(	const ImageFile &	destImageFile,
		const ustring &	pathName,
		uint16_t *	b,
		size_t	capacity,
		bool	doConversion = false,
		bool	doScaling = false,
		size_t	stride = sizeof( uint16_t )
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SourceDestBuffer() [6/12]

SourceDestBuffer::SourceDestBuffer	(	const ImageFile &	destImageFile,
		const ustring &	pathName,
		int32_t *	b,
		size_t	capacity,
		bool	doConversion = false,
		bool	doScaling = false,
		size_t	stride = sizeof( int32_t )
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SourceDestBuffer() [7/12]

SourceDestBuffer::SourceDestBuffer	(	const ImageFile &	destImageFile,
		const ustring &	pathName,
		uint32_t *	b,
		size_t	capacity,
		bool	doConversion = false,
		bool	doScaling = false,
		size_t	stride = sizeof( uint32_t )
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SourceDestBuffer() [8/12]

SourceDestBuffer::SourceDestBuffer	(	const ImageFile &	destImageFile,
		const ustring &	pathName,
		int64_t *	b,
		size_t	capacity,
		bool	doConversion = false,
		bool	doScaling = false,
		size_t	stride = sizeof( int64_t )
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SourceDestBuffer() [9/12]

SourceDestBuffer::SourceDestBuffer	(	const ImageFile &	destImageFile,
		const ustring &	pathName,
		bool *	b,
		size_t	capacity,
		bool	doConversion = false,
		bool	doScaling = false,
		size_t	stride = sizeof( bool )
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SourceDestBuffer() [10/12]

SourceDestBuffer::SourceDestBuffer	(	const ImageFile &	destImageFile,
		const ustring &	pathName,
		float *	b,
		size_t	capacity,
		bool	doConversion = false,
		bool	doScaling = false,
		size_t	stride = sizeof( float )
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SourceDestBuffer() [11/12]

SourceDestBuffer::SourceDestBuffer	(	const ImageFile &	destImageFile,
		const ustring &	pathName,
		double *	b,
		size_t	capacity,
		bool	doConversion = false,
		bool	doScaling = false,
		size_t	stride = sizeof( double )
	)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

SourceDestBuffer() [12/12]

SourceDestBuffer::SourceDestBuffer	(	const ImageFile &	destImageFile,
		const ustring &	pathName,
		std::vector< ustring > *	b
	)

Designate vector of strings to transfer data to/from a CompressedVector as a block.

Parameters

[in]	destImageFile	The ImageFile where the new node will eventually be stored.
[in]	pathName	The pathname of the field in CompressedVectorNode that will transfer data to/from.
[in]	b	The caller created vector of ustrings to transfer from/to.

This overloaded form of the SourceDestBuffer constructor declares a vector<ustring> to be the source/destination of a transfer of StringNode values stored in a CompressedVectorNode.

The pathName will be used to identify a Node in the prototype that will get/receive data from this buffer. The pathName may be an absolute path name (e.g. "/cartesianX") or a path name relative to the root of the prototype (i.e. the absolute path name without the leading "/", for example: "cartesianX").

The b->size() must match capacity of all other SourceDestBuffers that will participate in a transfer with a CompressedVectorNode (string or any other type of buffer). In a read into the SourceDestBuffer, the previous contents of the strings in the vector are lost, and the memory space is potentially freed. The b->size() of the vector will not be changed. It is an error to request a read/write of more records that b->size() (just as it would be for buffers of integer types). The API user is responsible for ensuring that the lifetime of the b vector exceeds the time that it is used in transfers (i.e. the E57 Foundation Implementation cannot detect that the buffer been destroyed).

Precondition

b.size() must be > 0.

The destImageFile must be open (i.e. destImageFile.isOpen() must be true).

Exceptions

ErrorBadAPIArgument
ErrorBadPathName
ErrorBadBuffer
ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also

SourceDestBuffer::doConversion for discussion on representations compatible with string SourceDestBuffers.

Member Function Documentation

capacity()

size_t SourceDestBuffer::capacity

(

)

const

Get total capacity of buffer.

The API programmer is responsible for correctly specifying the length of a buffer. This function returns that declared length. If the length is incorrect (in particular, too long) memory may be corrupted or erroneous values written.

Postcondition

No visible state is modified.

Returns

Total capacity of buffer.

Exceptions

ErrorInternal

All objects in undocumented state

checkInvariant()

void SourceDestBuffer::checkInvariant

(

bool

doRecurse = true

)

const

Check whether SourceDestBuffer class invariant is true.

doConversion()

bool SourceDestBuffer::doConversion

(

)

const

Get whether conversions will be performed to match the memory type of buffer.

The API user must explicitly request conversion between basic representation groups in memory and on the disk. The four basic representation groups are: integer, boolean, floating point, and string. There is no distinction between integer and boolean groups on the disk (they both use IntegerNode). A explicit request for conversion between single and double precision floating point representations is not required.

The most useful conversion is between integer and floating point representation groups. Conversion from integer to floating point representations cannot result in an overflow, and is usually loss-less (except for extremely large integers). Conversion from floating point to integer representations can result in an overflow, and can be lossy.

Conversion between any of the integer, boolean, and floating point representation groups is supported. No conversion from the string to any other representation group is possible. Missing or unsupported conversions are detected when the first transfer is attempted (i.e. not when the CompressedVectorReader or CompressedVectorWriter is created).

Postcondition

No visible state is modified.

Returns

true if conversions will be performed to match the memory type of buffer.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

doScaling()

bool SourceDestBuffer::doScaling

(

)

const

Get whether scaling will be performed for ScaledIntegerNode transfers.

The doScaling option only applies to ScaledIntegerNodes stored in a CompressedVectorNode on the disk (it is ignored if a ScaledIntegerNode is not involved).

As a convenience, an E57 Foundation Implementation can perform scaling of data so that the API user can manipulate scaledValues rather than rawValues. For a reader, the scaling process is: scaledValue = (rawValue * scale) + offset. For a writer, the scaling process is reversed: rawValue = (scaledValue - offset) / scale. The result performing a scaling in a reader (or "unscaling" in a writer) is always a floating point number. This floating point number may have to be converted to be compatible with the destination representation. If the destination representation is not floating point, there is a risk of violating declared min/max bounds. Because of this risk, it is recommended that scaling only be requested for reading scaledValues from ScaledIntegerNodes into floating point numbers in memory.

It is also possible (and perhaps safest of all) to never request that scaling be performed, and always deal with rawValues outside the API. Note this does not mean that ScaledIntegerNodes should be avoided. ScaledIntegerNodes are essential for encoding numeric data with fractional parts in CompressedVectorNodes. Because the ASTM E57 format recommends that SI units without prefix be used (i.e. meters, not milli-meters or micro-furlongs), almost every measured value will have a fractional part.

Postcondition

No visible state is modified.

Returns

true if scaling will be performed for ScaledInteger transfers.

Exceptions

ErrorInternal

All objects in undocumented state

See also

ScaledIntegerNode

dump()

void SourceDestBuffer::dump	(	int	indent = 0,
		std::ostream &	os = std::cout
	)		const

Diagnostic function to print internal state of object to output stream in an indented format.

Parameters

[in]	indent	Number of spaces to indent all the printed lines of this object.
[in]	os	Output stream to print on.

All objects in the E57 Foundation API (with exception of E57Exception) support a dump() function. These functions print out to the console a detailed listing of the internal state of objects. The content of these printouts is not documented, and is really of interest only to implementation developers/maintainers or the really adventurous users. In implementations of the API other than the Reference Implementation, the dump() functions may produce no output (although the functions should still be defined). The output format may change from version to version.

Postcondition

No visible object state is modified.

Exceptions

No	E57Exceptions

memoryRepresentation()

MemoryRepresentation SourceDestBuffer::memoryRepresentation

(

)

const

Get memory representation of the elements in this SourceDestBuffer.

The memory representation is deduced from which overloaded SourceDestBuffer constructor was used. The memory representation is independent of the type and minimum/maximum bounds of the node in the prototype that the SourceDestBuffer will transfer to/from. However, some combinations will result in an error if doConversion is not requested (e.g. Int16 and FloatNode).

Some combinations risk an error occurring during a write, if a value is too large (e.g. writing an Int16 memory representation to an IntegerNode with minimum=-1024 maximum=1023). Some combinations risk an error occurring during a read, if a value is too large (e.g. reading an IntegerNode with minimum=-1024 maximum=1023 int an Int8 memory representation). Some combinations are never possible (e.g. Int16 and StringNode).

Postcondition

No visible state is modified.

Returns

Memory representation of the elements in buffer.

Exceptions

ErrorInternal

All objects in undocumented state

See also

MemoryRepresentation, NodeType

pathName()

ustring SourceDestBuffer::pathName

(

)

const

Get path name in prototype that this SourceDestBuffer will transfer data to/from.

The prototype of a CompressedVectorNode describes the fields that are in each record. This function returns the path name of the node in the prototype tree that this SourceDestBuffer will write/read. The correctness of this path name is checked when this SourceDestBuffer is associated with a CompressedVectorNode (either in CompressedVectorNode::writer, CompressedVectorWriter::write(std::vector<SourceDestBuffer>&, unsigned), CompressedVectorNode::reader, CompressedVectorReader::read(std::vector<SourceDestBuffer>&)).

Postcondition

No visible state is modified.

Returns

Path name in prototype that this SourceDestBuffer will transfer data to/from.

Exceptions

ErrorInternal

All objects in undocumented state

See also

CompressedVector, CompressedVectorNode::prototype

stride()

size_t SourceDestBuffer::stride

(

)

const

Get number of bytes between consecutive memory elements in buffer.

Elements in a memory buffer do not have to be consecutive. They can also be spaced at regular intervals. This allows a value to be picked out of an array of C++ structures (the stride would be the size of the structure). In the case that the element values are stored consecutively in memory, the stride equals the size of the memory representation of the element.

Postcondition

No visible state is modified.

Returns

Number of bytes between consecutive memory elements in buffer

---

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

• E57Format.h
• SourceDestBuffer.cpp