BxUnion Class Reference

Class implementing the BinX data type union. More...

#include <BxUnion.h>

Inheritance diagram for BxUnion:

List of all members.

Public Member Functions
	BxUnion ()
	BxUnion (const BxUnion &copy)
virtual char *	toString (bool xml)
virtual bool	toStream (FILE *)
virtual bool	toStreamBinary (FILE *)
void	setDiscriminant (BxDataObject *)
void	setAssignedCase (BxUnionCase *p)
void	setAssignedCase (int index)
void	setAssignedCase ()
BxDataObject *	getDataObject ()
void	addUnionCase (BxUnionCase *uc)
void	addUnionCase (const char *sDiscriminantValue, BxDataObject *pArmObject)

---

Detailed Description

A BinX union contains a list of cases. Each case defines a possible data type that might be present in a binary application data file. Only one of the cases can be selected each time the union is used. Case selection is based on a discriminant value.
A BxUnion instance maintains:

• A list of the cases defined by a BinX document
• A reference pointer to the case actually selected after reading the discriminant value from a binary data file.
• A reference to the discriminant value read from the binary data file

The following is an example fragment of a type definition in a BinX document, showing the declaration of a union data type.

       <union blockSize="32" byteOrder="littleEndian">
           <discriminant><byte-8 varName="bool"/></discriminant>
           <case discriminantValue="1"><integer-32/></case>
           <case discriminantValue="0"><double-64/></case>
       </union>
   

The union type definition specifies that the discriminant value contained in the binary data file is of type xdrBool. The discriminate type must be a BinX primitive data type. The union case specifies that the discriminate can take on the values 1 or 0. If the discriminant value from the binary data file has value 1, then the next data item in the binary data file must be a 32-bit integer. If the discriminant value from the binary data file has value 0, then the next data item in the binary data file must be a 64-bit floating point number.
Since: BinX version 1.0.

---

Constructor & Destructor Documentation

BxUnion::BxUnion (   )

Default constructor. Constructs an instance of the class BxUnion. All attribute values for this object are set to NULL.

BxUnion::BxUnion (  const BxUnion &  copy  )

Construct a union object having attribute values identical to a specified instance of BxUnion. Attributes of the new union instance are initialised by copying attribute values from the specified input union. Uninitialized attribute values in the input union result in NULL valued attributes in the new array instance. If the the input union contains union cases, new instances of BxUnionCase are created, values are copied from the input union to the new instances, and the new instances are added to an attribute of this object. Upon completion of the copy operation, the two union instances are independent. They do not share union case values and they must be individually destructed. Parameters: copy  The BxUnion instance whose attribute values are to be copied.

---

Member Function Documentation

void BxUnion::addUnionCase (  const char *  sDiscriminantValue, BxDataObject *  pArmObject )

Create a BxUnionCase and add to the collection. This method allows creating a BxUnionCase object by cloning a discriminant data object and set the value to the given parameter, and pass the second parameter to the arm data object. Parameters: sDiscriminantValue  is the value of the attribute discriminantValue in case element. pArmObject  is the data object for this arm.

void BxUnion::addUnionCase (  BxUnionCase *  uc  )

Add a single, specified union case definition to the collection in a BxUnionCases object. Parameters: uc  A pointer to the union case definition to be added.

BxDataObject * BxUnion::getDataObject (   )

Read a data value from a binary data file based on the union cases defined in this object. This method reads a binary value of the appropriate data type from a binary data file. The appropriate data type is determined by matching a discriminate value against a set of union cases defined by a BinX document and stored in this BxUnion object. If the discriminate value has not been read from the binary data file, this method will: Read the discriminate value from the binary data file Match the discriminate value against the union case options stored in this BxUnion object Determine the data type associated with the union case selected by the the discriminate value Read a value of the selected data type from the binary data file Returns: A pointer to the binary data value stored in a BxDataObject instance.

void BxUnion::setAssignedCase (   )

Search the assigned case by checking the discriminant value. This method assumes that the cases are already added to the cases collection and the discriminant data object is also assigned to a real instance, and in addition, one of the the cases has the discriminant value equal to the discriminant object. It searches the cases to find the case with the discriminant value equal to the discriminant data object value and assign it to the assigned_ memeber variable.

void BxUnion::setAssignedCase (  int  index  )

Set the assigned_ attribute of this object to reference the currently selected union case definition. The selected (matched) case value is indicated by an input index number, identifying the zero-based position of the matched case in the ordered collection of union cases options. Parameters: index  A zero-based index into the collection of union cases.

void BxUnion::setAssignedCase (  BxUnionCase *  p  )

Set the assigned_ attribute of this object to reference the currently selected union case definition. The selected (matched) case value is indicated by an input pointer referencing a particular matched case value. Parameters: p  A pointer to the BxUnionCase instance that matched a discriminate value.

void BxUnion::setDiscriminant (  BxDataObject *  pd  )

Set the discriminate_ attribute of this object to reference a specified value from a binary data file. The specified discriminate value (most recently read from a binary data file) is indicated by an input pointer referencing that value. If the union definition stored in this object has been previously applied to the binary data file, then the specified input value replaces the previously stored discriminate value. The old discriminate value is released. The new value is retained until it is later released by this same process. Parameters: pd  A pointer to the BxDataObject containing the recently read discriminate value.

bool BxUnion::toStream (  FILE *  stream  )  [virtual]

Write a string containing the DataBinX representation of a union data type to a DataBinX file. The DataBinX representation of a BinX union data type includes: All BinX XML schema tags required to specify a union data type The discriminant value, as read from the binary data file, and converted to a printable representation The binary data value (following the discriminant value) read from the binary data file, and converted to a printable representation. The data type of the binary data value is determined by the discriminate value and the matching of that value to the union data type specification in a BinX document. Example Return Result: <union> <discriminant> <byte-8>10</byte-8> </discriminant> <case discriminantValue="10"> ... </union> The above example is broken over multiple lines for readability. This method writes a stream of consecutive bytes formed by the concatenation of the above substrings. The output example shows the BinX XML schema tags contained in the output. The discriminate value is an 8 byte quantity with value 10. The sequence of three dots at the end of the string represent the binary BinX XML tag for the data type, followed by the data value read from the binary data file, followed by the closing data type tag. The file must be open for writing in text mode. Parameters: stream  A file pointer to a file open for writing in text mode. Returns: true If no file I/O error occurs, false If any file I/O errors occur. Reimplemented from BxDataObject.

bool BxUnion::toStreamBinary (  FILE *  stream  )  [virtual]

Write the union discriminant data value and case value to a binary data file. The file must be open for writing in binary mode. Parameters: stream  A file pointer to an open file for writing in binary mode. Returns: true If no file I/O error occurs, false If any file I/O errors occur. Reimplemented from BxDataObject.

char * BxUnion::toString (  bool  xml  )  [virtual]

Return a string containing the DataBinX representation a union data type from a binary data file. The DataBinX representation of a BinX union data type includes: All BinX XML schema tags required to specify a union data type The discriminant value, as read from the binary data file, and converted to a printable representation The binary data value (following the discriminant value) read from the binary data file, and converted to a printable representation. The data type of the binary data value is determined by the discriminate value and the matching of that value to the union data type specification in a BinX document. Example Return Result: <union> <discriminant> <byte-8>10</byte-8> </discriminant> <case discriminantValue="10"> ... </union> The above example is broken over multiple lines for readability. This method returns a single string containing the concatenation of the above substrings. The output example shows the BinX XML schema tags contained in the result string. The discriminate value is an 8 byte quantity with value 10. The sequence of three dots at the end of the string represent the binary BinX XML tag for the data type, followed by the data value read from the binary data file, followed by the closing data type tag. This method allocates memory to hold the returned string. The caller is responsible for releasing the memory when the string is no longer needed. If the BinX XML tags are not required, then the input boolean flag can be used to request that only the converted binary data values be included in the result string. Parameters: xml  A boolean indicating whether to include BinX XML tags or not. Returns: A string buffer containing the DataBinX representation of an element, if the input flag is true, A string buffer containing the printable representation of two binary data values from a binary data file, if the input flag is false. Reimplemented from BxDataObject.

---

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

• BxUnion.h
• BxUnion.cpp

---