An iterator object keeping track of a write in progress to a CompressedVectorNode. More...

#include <E57Format.h>

Public Member Functions
	CompressedVectorWriter ()=delete

void	checkInvariant (bool doRecurse=true)
	Check whether CompressedVectorWriter class invariant is true.

void	close ()
	End the write operation.

CompressedVectorNode	compressedVectorNode () const
	Return the CompressedVectorNode being written to.

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.

bool	isOpen ()
	Test whether CompressedVectorWriter is still open for writing.

void	write (size_t recordCount)
	Request transfer of blocks of data to CompressedVectorNode from previously designated source buffers.

void	write (std::vector< SourceDestBuffer > &sbufs, size_t recordCount)
	Request transfer of block of data to CompressedVectorNode from given source buffers.

Detailed Description

An iterator object keeping track of a write in progress to a CompressedVectorNode.

A CompressedVectorWriter object is a block iterator that reads blocks of records from memory and stores them in a CompressedVectorNode. Blocks of records are processed rather than a single record-at-a-time for efficiency reasons. The CompressedVectorWriter class encapsulates all the state that must be saved in between the processing of one record block and the next (e.g. partially written disk pages, partially filled bytes in a bytestream, or data compression state). New memory buffers can be used for each record block write, or the previous buffers can be reused.

CompressedVectorWriter objects have an open/closed state. Initially a newly created CompressedVectorWriter is in the open state. After the API user calls CompressedVectorWriter::close, the object will be in the closed state and no more data transfers will be possible.

There is no CompressedVectorWriter constructor in the API. The function CompressedVectorNode::writer returns an already constructed CompressedVectorWriter object with given memory buffers (SourceDestBuffers) already associated. CompressedVectorWriter::close must explicitly be called to safely and gracefully end the transfer.

Warning: If CompressedVectorWriter::close is not called before the CompressedVectorWriter destructor is invoked, all writes to the CompressedVectorNode will be lost (it will have zero children).

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 CompressedVectorWriter::checkInvariant( bool /*doRecurse*/ )
{
   // If this CompressedVectorWriter is not open, can't test invariant (almost
   // every call would throw)
   if ( !isOpen() )
   {
      return;
   }
 
   CompressedVectorNode cv = compressedVectorNode();
   ImageFile imf = cv.destImageFile();
 
   // If destImageFile not open, can't test invariant (almost every call would
   // throw)
   if ( !imf.isOpen() )
   {
      return;
   }
 
   // Associated CompressedVectorNode must be attached to ImageFile
   if ( !cv.isAttached() )
   {
      throw E57_EXCEPTION1( ErrorInvarianceViolation );
   }
 
   // Dest ImageFile must be writable
   if ( !imf.isWritable() )
   {
      throw E57_EXCEPTION1( ErrorInvarianceViolation );
   }
 
   // Dest ImageFile must have exactly 1 writer (this one)
   if ( imf.writerCount() != 1 )
   {
      throw E57_EXCEPTION1( ErrorInvarianceViolation );
   }
 
   // Dest ImageFile can't have any readers
   if ( imf.readerCount() != 0 )
   {
      throw E57_EXCEPTION1( ErrorInvarianceViolation );
   }
}
 

See also: CompressedVectorNode, CompressedVectorReader

Constructor & Destructor Documentation

◆ CompressedVectorWriter()

e57::CompressedVectorWriter::CompressedVectorWriter ( )

delete

Member Function Documentation

◆ checkInvariant()

void CompressedVectorWriter::checkInvariant ( bool doRecurse = true )

Check whether CompressedVectorWriter class invariant is true.

This function checks at least the assertions in the documented class invariant description (see class reference page for this object). Other internal invariants that are implementation-dependent may also be checked. If any invariant clause is violated, an ErrorInvarianceViolation E57Exception is thrown.

Postcondition: No visible state is modified.

◆ close()

void CompressedVectorWriter::close ( )

End the write operation.

This function must be called to safely and gracefully end a transfer to a CompressedVectorNode. This is required because errors cannot be communicated from the CompressedVectorNode destructor (in C++ destructors can't throw exceptions). It is not an error to call this function if the CompressedVectorWriter is already closed. This function will cause the CompressedVectorWriter to enter the closed state, and any further transfers requests will fail.

Warning: If this function is not called before the CompressedVectorWriter destructor is invoked, all writes to the CompressedVectorNode will be lost (it will have zero children).

Precondition: The associated ImageFile must be open.

Postcondition: This CompressedVectorWriter is closed (i.e !isOpen())

Exceptions

ErrorImageFileNotOpen
ErrorSeekFailed	This CompressedVectorWriter, associated ImageFile in undocumented state
ErrorReadFailed	This CompressedVectorWriter, associated ImageFile in undocumented state
ErrorWriteFailed	This CompressedVectorWriter, associated ImageFile in undocumented state
ErrorBadChecksum	This CompressedVectorWriter, associated ImageFile in undocumented state
ErrorInternal	All objects in undocumented state

See also: CompressedVectorWriter::isOpen

◆ compressedVectorNode()

CompressedVectorNode CompressedVectorWriter::compressedVectorNode ( ) const

Return the CompressedVectorNode being written to.

Precondition: The associated ImageFile must be open.

Returns: A smart CompressedVectorNode handle referencing the underlying object being written to.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: CompressedVectorNode::writer

◆ dump()

void CompressedVectorWriter::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

◆ isOpen()

bool CompressedVectorWriter::isOpen ( )

Test whether CompressedVectorWriter is still open for writing.

Precondition: The associated ImageFile must be open.

Exceptions

ErrorImageFileNotOpen
ErrorInternal	All objects in undocumented state

See also: CompressedVectorWriter::close, CompressedVectorNode::writer

◆ write() [1/2]

void CompressedVectorWriter::write ( size_t recordCount )

Request transfer of blocks of data to CompressedVectorNode from previously designated source buffers.

Parameters

[in] recordCount Number of records to write.

The SourceDestBuffers used are previously designated either in CompressedVectorNode::writer where this object was created, or in the last call to CompressedVectorWriter::write(std::vector<SourceDestBuffer>&, unsigned) where new buffers were designated.

If a conversion or bounds error occurs during the transfer, the CompressedVectorWriter is left in an undocumented state (it can't be used any further), and all previously written records are deleted from the associated CompressedVectorNode which will then have zero children. If a file I/O or checksum error occurs during the transfer, both this CompressedVectorWriter and the associated ImageFile are left in an undocumented state (they can't be used any further). If CompressedVectorWriter::close is not called before the CompressedVectorWriter destructor is invoked, all writes to the CompressedVectorNode will be lost (it will have zero children).

Precondition: The associated ImageFile must be open.; This CompressedVectorWriter must be open (i.e isOpen())

Exceptions

ErrorBadAPIArgument
ErrorImageFileNotOpen
ErrorWriterNotOpen
ErrorPathUndefined
ErrorNoBufferForElement
ErrorBufferSizeMismatch
ErrorBufferDuplicatePathName
ErrorConversionRequired	This CompressedVectorWriter in undocumented state, associated CompressedVectorNode modified but consistent, associated ImageFile modified but consistent.
ErrorValueOutOfBounds	This CompressedVectorWriter in undocumented state, associated CompressedVectorNode modified but consistent, associated ImageFile modified but consistent.
ErrorValueNotRepresentable	This CompressedVectorWriter in undocumented state, associated CompressedVectorNode modified but consistent, associated ImageFile modified but consistent.
ErrorScaledValueNotRepresentable	This CompressedVectorWriter in undocumented state, associated CompressedVectorNode modified but consistent, associated ImageFile modified but consistent.
ErrorReal64TooLarge	This CompressedVectorWriter in undocumented state, associated CompressedVectorNode modified but consistent, associated ImageFile modified but consistent.
ErrorExpectingNumeric	This CompressedVectorWriter in undocumented state, associated CompressedVectorNode modified but consistent, associated ImageFile modified but consistent.
ErrorExpectingUString	This CompressedVectorWriter in undocumented state, associated CompressedVectorNode modified but consistent, associated ImageFile modified but consistent.
ErrorSeekFailed	This CompressedVectorWriter, associated ImageFile in undocumented state
ErrorReadFailed	This CompressedVectorWriter, associated ImageFile in undocumented state
ErrorWriteFailed	This CompressedVectorWriter, associated ImageFile in undocumented state
ErrorBadChecksum	This CompressedVectorWriter, associated ImageFile in undocumented state
ErrorInternal	All objects in undocumented state

See also: CompressedVectorWriter::write(std::vector<SourceDestBuffer>&,unsigned), CompressedVectorNode::writer, CompressedVectorWriter::close, SourceDestBuffer, E57Exception

◆ write() [2/2]

void CompressedVectorWriter::write	(	std::vector< SourceDestBuffer > &	sbufs,
		size_t	recordCount
	)

Request transfer of block of data to CompressedVectorNode from given source buffers.

Parameters

[in]	sbufs	Vector of memory buffers that hold data to be written to a CompressedVectorNode.
[in]	recordCount	Number of records to write.

The sbufs must all have the same capacity.

The sbufs capacity must be >= recordCount.

The specified sbufs must have same number of elements as previously designated SourceDestBuffer vector. The each SourceDestBuffer within sbufs must be identical to the previously designated SourceDestBuffer except for capacity and buffer address.

The sbufs locations are saved so that a later call to CompressedVectorWriter::write(unsigned) can be used without having to re-specify the SourceDestBuffers.

If a conversion or bounds error occurs during the transfer, the CompressedVectorWriter is left in an undocumented state (it can't be used any further), and all previously written records are deleted from the the associated CompressedVectorNode which will then have zero children. If a file I/O or checksum error occurs during the transfer, both this CompressedVectorWriter and the associated ImageFile are left in an undocumented state (they can't be used any further).

Warning: If CompressedVectorWriter::close is not called before the CompressedVectorWriter destructor is invoked, all writes to the CompressedVectorNode will be lost (it will have zero children).

Precondition: The associated ImageFile must be open.; This CompressedVectorWriter must be open (i.e isOpen())

Exceptions

ErrorBadAPIArgument
ErrorImageFileNotOpen
ErrorWriterNotOpen
ErrorPathUndefined
ErrorNoBufferForElement
ErrorBufferSizeMismatch
ErrorBufferDuplicatePathName
ErrorConversionRequired	This CompressedVectorWriter in undocumented state, associated ImageFile modified but consistent.
ErrorValueOutOfBounds	This CompressedVectorWriter in undocumented state, associated ImageFile modified but consistent.
ErrorValueNotRepresentable	This CompressedVectorWriter in undocumented state, associated ImageFile modified but consistent.
ErrorScaledValueNotRepresentable	This CompressedVectorWriter in undocumented state, associated ImageFile modified but consistent.
ErrorReal64TooLarge	This CompressedVectorWriter in undocumented state, associated ImageFile modified but consistent.
ErrorExpectingNumeric	This CompressedVectorWriter in undocumented state, associated ImageFile modified but consistent.
ErrorExpectingUString	This CompressedVectorWriter in undocumented state, associated ImageFile modified but consistent.
ErrorSeekFailed	This CompressedVectorWriter, associated ImageFile in undocumented state
ErrorReadFailed	This CompressedVectorWriter, associated ImageFile in undocumented state
ErrorWriteFailed	This CompressedVectorWriter, associated ImageFile in undocumented state
ErrorBadChecksum	This CompressedVectorWriter, associated ImageFile in undocumented state
ErrorInternal	All objects in undocumented state

See also: CompressedVectorWriter::write(unsigned), CompressedVectorNode::writer, CompressedVectorWriter::close, SourceDestBuffer, E57Exception

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

Public Member Functions

Detailed Description

Class Invariant A class invariant is a list of statements

Constructor & Destructor Documentation

◆ CompressedVectorWriter()

Member Function Documentation

◆ checkInvariant()

◆ close()

◆ compressedVectorNode()

◆ dump()

◆ isOpen()

◆ write() [1/2]

◆ write() [2/2]