This class is used for creating events and their substructures while minimizing use of objects. More...

#include <CompactEventBuilder.h>

Public Member Functions
	CompactEventBuilder (size_t bufferSize, ByteOrder const &order, bool generateNodes=false)
	This is the constructor to use for building a new event (just the event in a buffer, not the full evio file format). More...

	CompactEventBuilder (std::shared_ptr< ByteBuffer > buffer, bool generateNodes=false)
	This is the constructor to use for building a new event (just the event in a buffer, not the full evio file format) with a user-given buffer. More...

void	setBuffer (std::shared_ptr< ByteBuffer > buffer, bool generateNodes=false)
	Set the buffer to be written into. More...

std::shared_ptr< ByteBuffer >	getBuffer ()
	Get the buffer being written into. More...

size_t	getTotalBytes () const
	Get the total number of bytes written into the buffer. More...

std::shared_ptr< EvioNode >	openSegment (uint16_t tag, DataType const &dataType)
	This method adds an evio segment structure to the buffer. More...

std::shared_ptr< EvioNode >	openTagSegment (int tag, DataType dataType)
	This method adds an evio tagsegment structure to the buffer. More...

std::shared_ptr< EvioNode >	openBank (uint16_t tag, DataType const &dataType, uint8_t num)
	This method adds an evio bank to the buffer. More...

bool	closeStructure ()
	This method ends the writing of the current evio structure and makes sure the length and padding fields are properly set. More...

void	closeAll ()
	This method finishes the event writing by setting all the proper lengths & padding and ends up at the event or top level. More...

void	setTopLevelTag (short tag)
	In the emu software package, it's necessary to change the top level tag after the top level bank has already been created. More...

void	addEvioNode (std::shared_ptr< EvioNode > node)
	Adds the evio structure represented by the EvioNode object into the buffer. More...

void	addByteData (uint8_t *data, uint32_t len)
	Appends byte data to the structure. More...

void	addIntData (uint32_t *data, uint32_t len)
	Appends int data to the structure. More...

void	addShortData (uint16_t *data, uint32_t len)
	Appends short data to the structure. More...

void	addLongData (uint64_t *data, uint32_t len)
	Appends long data to the structure. More...

void	addFloatData (float *data, uint32_t len)
	Appends float data to the structure. More...

void	addDoubleData (double *data, uint32_t len)
	Appends double data to the structure. More...

void	addStringData (std::vector< std::string > &strings)
	Appends string data to the structure. More...

void	addCompositeData (std::vector< std::shared_ptr< CompositeData >> &data)
	Appends CompositeData objects to the structure. More...

void	toFile (std::string const &fileName)
	This method writes a file in proper evio format with block header containing the single event constructed by this object. More...

Detailed Description

This class is used for creating events and their substructures while minimizing use of objects.

Evio format data of a single event is written directly, and sequentially, into a buffer. The buffer contains only the single event, not the full, evio file format.

The methods of this class are not synchronized so it is NOT threadsafe. This is done for speed. The buffer retrieved by getBuffer() is ready to read.

Author: timmer

Date: 2/6/2014 (Java); 7/5/2020 (C++)

Constructor & Destructor Documentation

evio::CompactEventBuilder::CompactEventBuilder	(	size_t	bufferSize,
		ByteOrder const &	order,
		bool	generateNodes = `false`
	)

This is the constructor to use for building a new event (just the event in a buffer, not the full evio file format).

A buffer is created in this constructor.

Parameters

bufferSize	size of byte buffer (in bytes) to create.
order	byte order of created buffer.
generateNodes	generate and store an EvioNode object for each evio structure created.

Exceptions

EvioException if bufferSize arg too small

evio::CompactEventBuilder::CompactEventBuilder	(	std::shared_ptr< ByteBuffer >	buffer,
		bool	generateNodes = `false`
	)

explicit

This is the constructor to use for building a new event (just the event in a buffer, not the full evio file format) with a user-given buffer.

Parameters

buffer	the byte buffer to write into.
generateNodes	generate and store an EvioNode object for each evio structure created.

Exceptions

EvioException if arg is null; if buffer is too small

Member Function Documentation

void evio::CompactEventBuilder::addByteData	(	uint8_t *	data,
		uint32_t	len
	)

Appends byte data to the structure.

Parameters

data	the byte data to append.
len	number of bytes to append.

Exceptions

EvioException if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

References evio::DataType::CHAR8, and evio::DataType::UCHAR8.

void evio::CompactEventBuilder::addCompositeData ( std::vector< std::shared_ptr< CompositeData >> & data )

Appends CompositeData objects to the structure.

Parameters

data	the CompositeData objects to append, or set if there is no existing data.

Exceptions

EvioException if data is empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

References evio::DataType::COMPOSITE, and evio::CompositeData::generateRawBytes().

void evio::CompactEventBuilder::addDoubleData	(	double *	data,
		uint32_t	len
	)

Appends double data to the structure.

Parameters

data	the double data to append.
len	the number of doubles from data to append.

Exceptions

EvioException if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

References evio::DataType::DOUBLE64, and evio::ByteOrder::isLocalEndian().

void evio::CompactEventBuilder::addEvioNode ( std::shared_ptr< EvioNode > node )

Adds the evio structure represented by the EvioNode object into the buffer.

Parameters

node	the EvioNode object representing the evio structure to data.

Exceptions

EvioException if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

void evio::CompactEventBuilder::addFloatData	(	float *	data,
		uint32_t	len
	)

Appends float data to the structure.

Parameters

data	the float data to append.
len	number of the floats to append.

Exceptions

EvioException if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

References evio::DataType::FLOAT32, and evio::ByteOrder::isLocalEndian().

void evio::CompactEventBuilder::addIntData	(	uint32_t *	data,
		uint32_t	len
	)

Appends int data to the structure.

Parameters

data	the int data to append.
len	the number of ints from data to append.

Exceptions

EvioException if data is null or empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

References evio::DataType::INT32, evio::ByteOrder::isLocalEndian(), evio::DataType::UINT32, and evio::DataType::UNKNOWN32.

void evio::CompactEventBuilder::addLongData	(	uint64_t *	data,
		uint32_t	len
	)

Appends long data to the structure.

Parameters

data	the long data to append.
len	the number of longs from data to append.

Exceptions

EvioException if data is null; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

References evio::ByteOrder::isLocalEndian(), evio::DataType::LONG64, and evio::DataType::ULONG64.

void evio::CompactEventBuilder::addShortData	(	uint16_t *	data,
		uint32_t	len
	)

Appends short data to the structure.

Parameters

data	the short data to append.
len	the number of shorts from data to append.

Exceptions

EvioException if data is null; if count/offset negative or too large; if adding wrong data type to structure; if structure not added first; if no room in buffer for data.

References evio::ByteOrder::isLocalEndian(), evio::DataType::SHORT16, and evio::DataType::USHORT16.

void evio::CompactEventBuilder::addStringData ( std::vector< std::string > & strings )

Appends string data to the structure.

Parameters

strings vector of strings to append.

Exceptions

EvioException if strings is empty; if adding wrong data type to structure; if structure not added first; if no room in buffer for strings.

References evio::DataType::CHARSTAR8, and evio::Util::stringsToRawBytes().

void evio::CompactEventBuilder::closeAll ( )

This method finishes the event writing by setting all the proper lengths & padding and ends up at the event or top level.

References closeStructure().

bool evio::CompactEventBuilder::closeStructure ( )

This method ends the writing of the current evio structure and makes sure the length and padding fields are properly set.

Its parent, if any, then becomes the current structure.

Returns: true

if top structure was reached (is current), else
false

.

Referenced by closeAll().

std::shared_ptr< ByteBuffer > evio::CompactEventBuilder::getBuffer ( )

Get the buffer being written into.

The buffer is ready to read.

Returns: buffer being written into.

size_t evio::CompactEventBuilder::getTotalBytes ( ) const

Get the total number of bytes written into the buffer.

Returns: total number of bytes written into the buffer.

std::shared_ptr< EvioNode > evio::CompactEventBuilder::openBank	(	uint16_t	tag,
		DataType const &	dataType,
		uint8_t	num
	)

This method adds an evio bank to the buffer.

Parameters

tag	tag of bank header.
dataType	data type to be contained in this bank.
num	num of bank header.

Returns: if told to generate nodes in constructor, then return the node created here; else return null

Exceptions

EvioException if containing structure does not hold banks; if no room in buffer for bank header; if too many nested evio structures;

References evio::DataType::ALSOBANK, evio::DataType::BANK, evio::ByteOrder::ENDIAN_BIG, and evio::DataType::getValue().

std::shared_ptr< EvioNode > evio::CompactEventBuilder::openSegment	(	uint16_t	tag,
		DataType const &	dataType
	)

This method adds an evio segment structure to the buffer.

Parameters

tag	tag of segment header
dataType	type of data to be contained by this segment

Returns: if told to generate nodes in constructor, then return the node created here; else return null

Exceptions

EvioException if containing structure does not hold segments; if no room in buffer for segment header; if too many nested evio structures; if top-level bank has not been added first.

References evio::DataType::ALSOSEGMENT, evio::ByteOrder::ENDIAN_BIG, evio::DataType::getValue(), and evio::DataType::SEGMENT.

std::shared_ptr< EvioNode > evio::CompactEventBuilder::openTagSegment	(	int	tag,
		DataType	dataType
	)

This method adds an evio tagsegment structure to the buffer.

Parameters

tag	tag of tagsegment header
dataType	type of data to be contained by this tagsegment

Returns: if told to generate nodes in constructor, then return the node created here; else return null

Exceptions

EvioException if containing structure does not hold tagsegments; if no room in buffer for tagsegment header; if too many nested evio structures; if top-level bank has not been added first.

References evio::ByteOrder::ENDIAN_BIG, evio::DataType::getValue(), and evio::DataType::TAGSEGMENT.

void evio::CompactEventBuilder::setBuffer	(	std::shared_ptr< ByteBuffer >	buffer,
		bool	generateNodes = `false`
	)

Set the buffer to be written into.

Parameters

buffer	buffer to be written into.
generateNodes	generate and store an EvioNode object for each evio structure created.

Exceptions

EvioException if arg is null; if buffer is too small

void evio::CompactEventBuilder::setTopLevelTag ( short tag )

In the emu software package, it's necessary to change the top level tag after the top level bank has already been created.

This method allows changing it after initially written.

Parameters

tag	new tag value of top-level, event bank.

References evio::ByteOrder::ENDIAN_BIG.

void evio::CompactEventBuilder::toFile ( std::string const & fileName )

This method writes a file in proper evio format with block header containing the single event constructed by this object.

This is useful as a test to see if event is being properly constructed. Use this in conjunction with the event viewer in order to check that format is correct. This only works with array backed buffers.

Parameters

fileName name of file

References evio::ByteBuffer::array(), evio::FileHeader::EVIO_FILE_UNIQUE_WORD, evio::ByteBuffer::flip(), evio::FileHeader::generateBitInfoWord(), evio::RecordHeader::generateSixthWord(), evio::FileHeader::HEADER_MAGIC, evio::RecordHeader::HEADER_MAGIC, evio::FileHeader::HEADER_SIZE_BYTES, evio::RecordHeader::HEADER_SIZE_BYTES, evio::FileHeader::HEADER_SIZE_WORDS, evio::RecordHeader::HEADER_SIZE_WORDS, evio::ByteBuffer::order(), evio::ByteBuffer::putInt(), and evio::ByteBuffer::putLong().

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation