Main Page | Class Hierarchy | Compound List | File List | Compound Members

BxArrayVariable Class Reference

Class for managing variable-length arrays. More...

#include <BxArrayVariable.h>

Inheritance diagram for BxArrayVariable:

BxArray BxDataObject BxObject List of all members.

Public Member Functions

 BxArrayVariable ()
 BxArrayVariable (int dim)
 BxArrayVariable (const BxArrayVariable &copy)
virtual void setBinaryFilePtr (BxBinaryFile *fp)
virtual bool toStream (FILE *)
virtual bool toStreamBinary (FILE *)
void setSizeObject (BxDataObject *sizeObj)
virtual BxDataObject * get (int index)
virtual BxDataObject * getNext ()

Detailed Description

A variable-length array is an array having one or more dimensions, where the size of the slowest-moving dimension is not fixed, but specified as part of the array data. The size value must be the first value in the binary file associated with this variable-length array. The data type of the size value can be a short integer or a long integer. The data type is specified in the BinX schema using the XML element named sizeRef.
The following is an example of a BinX schema descriptor for a variable-length array. The array is two-dimensional. The slowest-moving dimension contains a variable number of data elements. The size of that dimension is defined by a 32-bit integer value contained at the beginning of the associated binary data file. The other dimension consists of 6 data elements, identified by index values [0] to [5]. 
   <arrayVariable>
        <sizeRef><integer-32/></sizeRef>
        <dim>
            <dim indexTo="5"/>
        </dim>
   </arrayVariable>
BxArrayVariable is derived from the class BxArray and inherits numerous methods from that class.
Since: BinX version 1.0.

Constructor & Destructor Documentation

BxArrayVariable::BxArrayVariable (   ) 
 

Default constructor.

Constructs an empty instance of the class BxArrayVariable. The default values for all inherited attributes are assigned by the default base class constructor BxArray(). The attributes local to this derived class are assigned default values as follows: 

       sizeObject_ = NULL;
       bSizeObjectRead = false;
The attribute named sizeObject_ is an instance of class BxDataObject. The attribute is used to hold length information extracted from the binary file.

BxArrayVariable::BxArrayVariable (  int  dim  ) 
 

Construct a variable-length array having a specified number of dimensions.

The dims_ attribute is created to store the specified number of dimensions, but the dimension descriptions stored in this attribute are set to NULL. The other attribute values are assigned default values as defined by the default constructor for this class BxArrayVariable().

Parameters:
dim The number of dimensions for the newly constructed variable-length array.

BxArrayVariable::BxArrayVariable (  const BxArrayVariable &  copy  ) 
 

Construct a variable-length array having attribute values identical to a specified instance of BxArrayVariable.

Attributes of the new array instance are initialized by copying attribute values from the specified input array. Uninitialized attribute values in the input array result in NULL valued attributes in the new array instance. If the attributes of the input array have been initialized, then the array structure of the new instance will be the same as the array structure of the input instance.
Upon completion of the copy operation, the two array instances are independent. They do not share array element values and they must be individually destructed.

Parameters:
copy The BxArrayStreamed instance whose attribute values are to be copied.

Member Function Documentation

BxDataObject * BxArrayVariable::get (  int  index  )  [virtual]
 

Get a copy of a single data element from a variable-length array.

The data element to be retrieved from the variable-length array is identified by a single index value into the array. If the variable length array consists of multiple dimensions, then the caller is responsible for multiplying the dimension extents times the respective index values for the desired data element. The index value must be specified as a zero-based offset into the variable-length array.
If the size of the variable-length dimension of an array has not yet been read from the associated binary file, then this method reads the size value from the binary file before proceeding to get the specified array data element.
The specified array data element is copied to a BxDataObject instance and returned to the caller. The caller is responsible for destructing the returned object when it is no longer needed.
Implementation Notes:
The requested data element may or may not be resident in the buffer associated with this variable-length array. If the desired data element is not resident in the buffer, then the buffer is filled with the specified data element from the file associated with this array.

Parameters:
index Specifies the zero-based index of the array data element.
Returns:
A pointer to the data element value as a BxDataObject.

Reimplemented from BxArray.

BxDataObject * BxArrayVariable::getNext (   )  [virtual]
 

Get the next (available) single data element from a variable-length array.

Successive calls to this method result in a sequential retrieval of array data element values. This method remembers the position of the next value to be retrieved. For each method call, a single data element value is retrieved and returned based on the order in which the element values are stored within the array. The dimensionality of the array is ignored.
If the size of the variable-length dimension of an array has not yet been read from the associated binary file, then this method reads the size value from the binary file before proceeding to get the specified array data element.
The selected array data element is copied to a BxDataObject instance and returned to the caller. The caller is responsible for destructing the returned object when it is no longer needed.

Returns:
A pointer to the data element value as a BxDataObject.

Reimplemented from BxArray.

void BxArrayVariable::setBinaryFilePtr (  BxBinaryFile *  fp  )  [virtual]
 

Overriden method to set the binary file pointer to a specified file position.

This method also sets the file pointer for locating the variable size information that must be included at the beginning of the binary file. Once the value specifying the variable length of the slowest-moving array dimension has been read from the file, the file pointer for locating that information will continue to be updated (erroneously). The updated file pointer will not be used once the value specifying the length of the variable array dimension has been read from the file.

Parameters:
fp A pointer to an open BxBinaryFile, containing array data elements and the length value for the variable array dimension.

Reimplemented from BxDataObject.

void BxArrayVariable::setSizeObject (  BxDataObject *  sizeObj  ) 
 

Set or reset the size of the variable-length dimension of an array.

The size of the variable-length dimension of an array is encapsulated in an instance of class BxDataObject. If the size of the variable-length dimension of this array has been set previously, then the old size object is released, and the new size object is referenced by this variable-length array.
Upon completion of this method, the input object describing the size of the variable-length dimension of this array is tightly related to this variable-length array instance. The caller must not destruct the input parameter instance. Destruction of the BxDataObject instance will be managed by the variable array instance.

Parameters:
sizeObj A pointer to a BxDataObject defining the size of the variable-length dimension of an array.

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

Write the implicit and complete XML (DataBinX) representation for a variable-length array to a file.

The BinX XML schema for this array is combined with the array data element values to create a DataBinX file.
The input file pointer must be open for writing.
Output Example:
The following is an example of the final contents of a DataBinX file for a small variable-length array. 

   <arrayVariable varName="x" typeName="x">
    <sizeRef><byte-8>2</byte-8></sizeRef>
      <dim name="d2" index="1">
        <dim name="d1" index="1">
          <short-16>11</short-16>
        </dim>
        <dim name="d1" index="2">
          <short-16>12</short-16>
        </dim>
        <dim name="d1" index="3">
          <short-16>13</short-16>
        </dim>
        <dim name="d1" index="4">
          <short-16>14</short-16>
        </dim>
      </dim>
      <dim name="d2" index="2">
        <dim name="d1" index="1">
          <short-16>21</short-16>
        </dim>
        <dim name="d1" index="2">
          <short-16>22</short-16>
        </dim>
        <dim name="d1" index="3">
          <short-16>23</short-16>
        </dim>
        <dim name="d1" index="4">
          <short-16>24</short-16>
        </dim>
      </dim>
   </arrayVariable>
The variable-length array is a two-dimensional array. The size of the variable dimension is specified in the XML element named sizeRef. In this example, the variable size has the value 2. The other dimension is of size 4. The array contains 8 data elements.
Parameters:
stream A pointer to a file open for writing.
Returns:
true If no file I/O error occurs,
false If the file is not open for writing.

Reimplemented from BxArray.

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

Write all of the data element values of a variable-length array to a binary file.

The size of the variable-length dimension of the array is the first value written to the output file. Data element values from the variable-length array are written after the size value.
The file must be open for writing in binary mode.

Parameters:
stream A pointer to a file open for writing in binary mode.
Returns:
Always returns true, even if a file I/O error occurs.

Reimplemented from BxArray.

The documentation for this class was generated from the following files:
Generated on Fri May 6 13:36:18 2005 for edikt::BinX by doxygen 1.3.3