CSLArrayProxy Class Template Reference

Proxy class that allows the manipulation of an array parameter in a template. More...

#include <SL_Array.h>

List of all members.

Public Member Functions
  CSLArrayProxy (CdotXSITemplate *in_pTemplate, SI_Long in_Index)
  CSLArrayProxy ()
  ~CSLArrayProxy ()
SI_Error  Connect (CdotXSITemplate *in_pTemplate, SI_Long in_lArrayIndex)
SI_Long  GetUsed () const
SI_Long  GetSize () const
SI_Long  UsedMem () const
SI_Long  AllocatedMem () const
SI_Long  Reserve (const SI_Long in_lNbElem)
SI_Long  Resize (const SI_Long in_lNewNbElem)
SI_Long  Extend (const SI_Long in_lNbElem)
SI_Long  InsertAt (const SI_Long in_lIndex, const SI_Long in_lNbElem)
SI_Long  Add (CElemType in_Elem)
SI_Void  DeleteAt (const SI_Long in_lIndex, const SI_Long in_lNbElem)
CElemType &  operator[] (const SI_Long in_lIndex) const
CElemType &  operator[] (const SI_Long in_lIndex)
SI_Long  Pack (SI_Long i_lMaxWasted=4L)
SI_Void  DisposeData (SI_Void)
SI_Int  Copy (const CSIBCArray< CElemType > &in_rSrcObject)
SI_Int  Copy (const CSLArrayProxy< CElemType, CSubElemType, StructSize > &in_rSrcObject)
CSLArrayProxy &  operator= (const CSIBCArray< CElemType > &in_rSrcObject)
CSLArrayProxy &  operator= (const CSLArrayProxy< CElemType, CSubElemType, StructSize > &in_rSrcObject)
CElemType *  ArrayPtr (SI_Void)
SI_Void  Set (SI_Long start, SI_Long in_lNbElem, CElemType value)

Detailed Description

template<class CElemType, class CSubElemType, SI_Int StructSize>
class CSLArrayProxy< CElemType, CSubElemType, StructSize >

Proxy class that allows the manipulation of an array parameter in a template.

Parameters:
CElemType  Element type contained in the array.
CSubElemType  Sub element type composing the CElemType. Can be the same as CElemType if StructSize equals one.
StructSize  Number of CSubElemType that composes a single CElemType.
Note:
The distinction between CElemType and CSubElemType hides the gory details of the way an element is stored. For instance, an RGB value array could be stored as a SI_Float array. This would normally mean that you would have to access the red, green and blue values individually. The array proxy lets you access the three elements as if the array was in fact an array of RGB structure.
Example:
    struct RGB
    {
        SI_Float m_fR;
        SI_Float m_fG;
        SI_Float m_fB;
    } l_RGB;

    // Connect the proxy to a parameter that stores an SI_Float array
    // for RGB values.  The array in the template is a sequence of
    // float triplets that represent red, green and blue values.
    CSLArrayProxy<RGB, SI_Float, 3> l_RGBArrayProxy;
    l_RGBArrayProxy.Connect( l_pParentTemplate, l_nRGBParamIndex );

    // get the first RGB entry
    l_RGB = l_RGBArrayProxy[0]; // the first 3 floats for the RGB value.

Constructor & Destructor Documentation

CSLArrayProxy ( CdotXSITemplate *  in_pTemplate,
SI_Long  in_Index  
)

Constructor. Connects to an array parameter in the parent template.

Parameters:
in_pTemplate  Pointer to the parent template
in_Index  Index of the array paramater in the template

CSLArrayProxy (  ) 

Default Constructor. Does not call Connect.

~CSLArrayProxy (  ) 

Destructor

Warning:
The destructor does not deallocate the referred parameter.

Member Function Documentation

SI_Error Connect ( CdotXSITemplate *  in_pTemplate,
SI_Long  in_lArrayIndex  
)

Connects to an array parameter in the parent template.

Parameters:
in_pTemplate  Pointer to the parent template
in_lArrayIndex  Index of the array in the template
Return values:
SI_SUCCESS 

SI_Long GetUsed (  )  const [inline]

Returns the number of used cells

Returns:
The number of used cells (i.e. the ones you can access)
Note:
The size of the internally stored array might diverge from the actual number of cells that are currently used. If you need to know the total number of allocated cells, you should use the CSLArrayProxy::GetSize function instead.

SI_Long GetSize (  )  const [inline]

Returns the number of allocated cells

Returns:
The number of cells allocated
Note:
The number of cells that are being used can be retrieved with the CSLArrayProxy::GetUsed function.

SI_Long UsedMem (  )  const [inline]

Returns The total size of the used cells

Returns:
Size in byte
See also:
CSLArrayProxy::GetUsed

SI_Long AllocatedMem (  )  const [inline]

Returns the total size of the allocated cells including the unused ones.

Returns:
Size in byte
See also:
CSLArrayProxy::GetSize

SI_Long Reserve ( const SI_Long  in_lNbElem  ) 

Adds a specific number of used cells to the array as required

Parameters:
in_lNbElem  Number of cells to add
Returns:
The number of used cells
Note:
If the allocated size is large enough, no cells are going to be allocated. If you expect to add lots of cells frequently, you should consider using CSLArrayProxy::Resize instead.
See also:
CSLArrayProxy::Resize

CSLArrayProxy::GetSize

CSLArrayProxy::GetUsed

SI_Long Resize ( const SI_Long  in_lNewNbElem  ) 

Adds used cells to the array as required.

Returns:
The number of used cells
Note:
If the allocated size is large enough, no cells are going to be allocated. Otherwise, in_lNbElem used cells are going to be added twice. This is can improve performance by allocating memory less frequently than CSLArrayProxy::Reserve would. If you will need lots of used cells in the near future, you should consider using CSLArrayProxy::Extend.
See also:
CSLArrayProxy::Reserve

CSLArrayProxy::Extend

CSLArrayProxy::GetSize

CSLArrayProxy::GetUsed

SI_Long Extend ( const SI_Long  in_lNbElem  ) 

Extends the number of used cells by a substantial amount if there's not enough used cells.

Parameters:
in_lNewNbElem  The number of additional used cells to add
Returns:
The number of used cells
Note:
This is the equivalent of calling CSLArrayProxy::Resize with the actual number of cells plus in_lNewNbElem. This means that if there's not enough room for this amout of used cells, twice as much will be allocated (that's more than twice the original size of the array). You should therefore use this function when you expect the number of used cells to grow a lot in order to improve performance.
See also:
CSLArrayProxy::Reserve

CSLArrayProxy::Resize

SI_Long InsertAt ( const SI_Long  in_lIndex,
const SI_Long  in_lNbElem  
)

Inserts an exact number of used cells at the provided index

Parameters:
in_lIndex  Insertion point
in_lNbElem  Number of used cells to add
Returns:
The number of used cells
Note:
Enough used cells are going to be added to the array if it cannot support the new number of used cells.
Note:
The array will only be increased by the number of missing used cells slots. If you expect a lot of insertion, you should consider calling CSLArrayProxy::Resize or CSLArrayProxy::Extend before using this function in order to improve performance.
See also:
CSLArrayProxy::Add

CSLArrayProxy::Extend

CSLArrayProxy::Resize

SI_Long Add ( CElemType  in_Elem  )  [inline]

Adds an element at the end of the array

Parameters:
in_Elem  Element to add
Returns:
The number of used cells
Note:
The array will resize if there is not enough unused cells.
See also:
CSLArrayProxy::InsertAt

CSLArrayProxy::Extend

CSLArrayProxy::Resize

SI_Void DeleteAt ( const SI_Long  in_lIndex,
const SI_Long  in_lNbElem  
)

Deletes a given number of element at a the specified index

Parameters:
in_lIndex  The index of the element where deletion must start
in_lNbElem  The number of elements to delete (must be positive)

CElemType & operator[] ( const SI_Long  in_lIndex  )  const [inline]

Gets an element at a given index

Parameters:
in_lIndex  Index of the element to retrieve
Returns:
The element at in_lIndex

CElemType & operator[] ( const SI_Long  in_lIndex  )  [inline]

Gets an element at a given index

Parameters:
in_lIndex  Index of the element to retrieve
Returns:
The element at in_lIndex

SI_Long Pack ( SI_Long  i_lMaxWasted = 4L  ) 

Deallocates unused cells

Parameters:
i_lMaxWasted  Maximum number of allowed unused cells
Returns:
The number of used cells
Note:
Packing is performed only if there is more than i_lMaxWasted unused cells.
Warning:
This costly function should only be called after major resizing.

SI_Void DisposeData ( SI_Void   ) 

Releases the referred array

Note:
An array of 1 element will replace the former array.

SI_Int Copy ( const CSIBCArray< CElemType > &  in_rSrcObject  ) 

Copy data from another array

Parameters:
in_rSrcObject  The array to copy data from
Returns:
The number of used cells
Warning:
The current array's content will be deallocated

SI_Int Copy ( const CSLArrayProxy< CElemType, CSubElemType, StructSize > &  in_rSrcObject  ) 

Copy data from another array

Parameters:
in_rSrcObject  The array to copy data from
Returns:
The number of used cells
Warning:
The current array's content will be deallocated

CSLArrayProxy< CElemType, CSubElemType, StructSize > & operator= ( const CSIBCArray< CElemType > &  in_rSrcObject  ) 

Copy data from another array

Parameters:
in_rSrcObject  The array to copy data from
Returns:
A reference to the current array
Warning:
The current array's content will be deallocated

CSLArrayProxy< CElemType, CSubElemType, StructSize > & operator= ( const CSLArrayProxy< CElemType, CSubElemType, StructSize > &  in_rSrcObject  ) 

Copy data from another array

Parameters:
in_rSrcObject  The array to copy data from
Returns:
Reference to the current array
Warning:
The current array's content will be deallocated

CElemType* ArrayPtr ( SI_Void   )  [inline]

Returns a pointer to the internally referred array.

Returns:
Pointer to the array

SI_Void Set ( SI_Long  start,
SI_Long  in_lNbElem,
CElemType  value  
) [inline]

Sets values in a given range

Parameters:
start  The index of first element to set
in_lNbElem  The number of elements to set
value  New value for the elements in the given range.

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