#include <E57Format.h>

Public Member Functions
size_t	capacity () const
	Get total capacity of buffer. More...

void	checkInvariant (bool doRecurse=true) const
	Check whether SourceDestBuffer class invariant is true. More...

bool	doConversion () const
	Get whether conversions will be performed to match the memory type of buffer. More...

bool	doScaling () const
	Get whether scaling will be performed for ScaledIntegerNode transfers. More...

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

enum MemoryRepresentation	memoryRepresentation () const
	Get memory representation of the elements in this SourceDestBuffer. More...

ustring	pathName () const
	Get path name in prototype that this SourceDestBuffer will transfer data to/from. More...

	SourceDestBuffer ()=delete

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, bool *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(bool))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, double *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(double))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, float *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(float))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, int16_t *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(int16_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, int32_t *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(int32_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, int64_t *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(int64_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, int8_t *b, const 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. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, std::vector< ustring > *b)
	Designate vector of strings to transfer data to/from a CompressedVector as a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, uint16_t *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(uint16_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, uint32_t *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(uint32_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

	SourceDestBuffer (ImageFile destImageFile, const ustring &pathName, uint8_t *b, const size_t capacity, bool doConversion=false, bool doScaling=false, size_t stride=sizeof(uint8_t))
	Designate buffers to transfer data to/from a CompressedVectorNode in a block. More...

size_t	stride () const
	Get number of bytes between consecutive memory elements in buffer. More...

Constructor & Destructor Documentation

◆ SourceDestBuffer() [1/12]

e57::SourceDestBuffer::SourceDestBuffer ( )

delete

◆ SourceDestBuffer() [2/12]

SourceDestBuffer::SourceDestBuffer	(	ImageFile	destImageFile,
		const ustring &	pathName,
		int8_t *	b,
		const 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)

Returns: A smart SourceDestBuffer handle referencing the underlying object.

Exceptions

E57_ERROR_BAD_API_ARGUMENT
E57_ERROR_BAD_PATH_NAME
E57_ERROR_BAD_BUFFER
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNAL	All objects in undocumented state

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

References stride().

◆ SourceDestBuffer() [3/12]

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

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

References stride().

◆ SourceDestBuffer() [4/12]

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

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

References stride().

◆ SourceDestBuffer() [5/12]

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

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

References stride().

◆ SourceDestBuffer() [6/12]

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

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

References stride().

◆ SourceDestBuffer() [7/12]

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

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

References stride().

◆ SourceDestBuffer() [8/12]

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

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

References stride().

◆ SourceDestBuffer() [9/12]

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

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

References stride().

◆ SourceDestBuffer() [10/12]

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

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

References stride().

◆ SourceDestBuffer() [11/12]

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

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

References stride().

◆ SourceDestBuffer() [12/12]

SourceDestBuffer::SourceDestBuffer	(	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).

Returns: A smart SourceDestBuffer handle referencing the underlying object.

Exceptions

E57_ERROR_BAD_API_ARGUMENT
E57_ERROR_BAD_PATH_NAME
E57_ERROR_BAD_BUFFER
E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNAL	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

E57_ERROR_INTERNAL All objects in undocumented state

Referenced by e57::DecodeChannel::isOutputBlocked().

◆ checkInvariant()

void SourceDestBuffer::checkInvariant ( bool doRecurse = true ) const

Check whether SourceDestBuffer class invariant is true.

References e57::E57_BOOL, e57::E57_ERROR_INVARIANCE_VIOLATION, e57::E57_INT16, e57::E57_INT32, e57::E57_INT64, e57::E57_INT8, e57::E57_REAL32, e57::E57_REAL64, e57::E57_UINT16, e57::E57_UINT32, e57::E57_UINT8, e57::E57_USTRING, memoryRepresentation(), and stride().

◆ 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

E57_ERROR_IMAGEFILE_NOT_OPEN
E57_ERROR_INTERNAL	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. ScaledIntgerNodes 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

E57_ERROR_INTERNAL 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. E57_INT16 and FloatNode).

Some combinations risk an error occurring during a write, if a value is too large (e.g. writing a E57_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 E57_INT8 memory representation). Some combinations are never possible (e.g. E57_INT16 and StringNode).

Postcondition: No visible state is modified.

Returns: Memory representation of the elements in buffer.

Exceptions

E57_ERROR_INTERNAL All objects in undocumented state

See also: MemoryRepresentation, NodeType

Referenced by checkInvariant().

◆ 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

E57_ERROR_INTERNAL All objects in undocumented state

See also: CompressedVector, CompressedVectorNode::prototype

Referenced by e57::Encoder::EncoderFactory().

◆ 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

Referenced by checkInvariant(), and SourceDestBuffer().

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

FreeCAD/src/3rdParty/libE57Format/include/E57Format.h
FreeCAD/src/3rdParty/libE57Format/src/E57Format.cpp

Public Member Functions

Constructor & Destructor Documentation

◆ SourceDestBuffer() [1/12]

◆ SourceDestBuffer() [2/12]

◆ SourceDestBuffer() [3/12]

◆ SourceDestBuffer() [4/12]

◆ SourceDestBuffer() [5/12]

◆ SourceDestBuffer() [6/12]

◆ SourceDestBuffer() [7/12]

◆ SourceDestBuffer() [8/12]

◆ SourceDestBuffer() [9/12]

◆ SourceDestBuffer() [10/12]

◆ SourceDestBuffer() [11/12]

◆ SourceDestBuffer() [12/12]

Member Function Documentation

◆ capacity()

◆ checkInvariant()

◆ doConversion()

◆ doScaling()

◆ dump()

◆ memoryRepresentation()

◆ pathName()

◆ stride()