libbdiobject_array_declaration_template.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 2019 VT MAK
 ** All rights reserved.
 *********************************************************************/



class bdiDataTracker;

#ifdef LIBBDIOBJECT_ARRAY_DECLSPEC_bdiutil
#  include <declspec_bdiutil.h>
#else
#  ifdef LIBBDIOBJECT_ARRAY_DECLSPEC_bdigraphics
#     include <declspec_bdigraphics.h>
#  endif
#endif

#ifdef LIBBDIOBJECT_ARRAY_INLINE
#define BDI_INLINE inline
#else 
#define BDI_INLINE
#endif

namespace makVrv
{
   /****************************************************************************/
/*l
 **  This class implements an array of LIBBDIOBJECT_ARRAY_TYPE objects.
 */
#ifdef LIBBDIOBJECT_ARRAY_DECLSPEC_bdiutil
   class BDI_DECLSPEC_bdiutil LIBBDIOBJECT_ARRAY_CLASS_NAME
#else
#  ifdef LIBBDIOBJECT_ARRAY_DECLSPEC_bdigraphics
   class BDI_DECLSPEC_bdigraphics LIBBDIOBJECT_ARRAY_CLASS_NAME
#  else
   class LIBBDIOBJECT_ARRAY_CLASS_NAME
#  endif
#endif
   {

   public:

      /*
       *========================================
       *2  Constructors
       */

       /*l
        **  Default constructor.
        */
      BDI_INLINE LIBBDIOBJECT_ARRAY_CLASS_NAME(int initial_size = 16,
         int increment = 16);

      /*l
       **  Virtual destructor.
       */
      BDI_INLINE virtual ~LIBBDIOBJECT_ARRAY_CLASS_NAME();

      /*
       *========================================
       *2  Class-specific Functions
       */

       /*l
        **  Adds the specified object to the front of the array.
        **
        *a  object - pointer to object.
        */
      BDI_INLINE int push_front(LIBBDIOBJECT_ARRAY_TYPE* object);

      /*l
       **  Removes the object at the front of the array, and returns it.
       */
      BDI_INLINE LIBBDIOBJECT_ARRAY_TYPE* pop_front(void);

      /*l
       **  Adds the specified object to the end of the array.
       **
       *a  object - pointer to object.
       */
      BDI_INLINE int push_back(LIBBDIOBJECT_ARRAY_TYPE* object);

      /*l
       **  Removes the object at the end of the array, and returns
       **  it.
       */
      BDI_INLINE LIBBDIOBJECT_ARRAY_TYPE* pop_back(void);

      /*l
       **  Replaces the previous object at the specified index of the array
       **  with the specified object.  Returns the previous object at the index
       **  or NULL if index is invalid.  If NULL is returned, the object could
       **  not be replaced.  Does not delete the previous object.
       **
       *a  index      - index into objects array where object will be replaced
       *a  object_ptr - pointer to object to place in the array
       */
      BDI_INLINE LIBBDIOBJECT_ARRAY_TYPE* replace_at_index(int index, LIBBDIOBJECT_ARRAY_TYPE* object);

      /*l
       **  Inserts the specified object at the specified index of the array.
       **
       *a  index      - index into objects array where object will be inserted
       *a  object_ptr - pointer to object
       */
      BDI_INLINE int insert_at_index(int index, LIBBDIOBJECT_ARRAY_TYPE* object);

      /*l
       **  Removes the object at the specified index of the array, and returns it.
       **
       *a  index          - index into objects array where object will be removed
       */
      BDI_INLINE LIBBDIOBJECT_ARRAY_TYPE* remove_at_index(int index);

      /*l
       **  Removes the object with the given pointer, and returns it.
       **
       *a  object          - pointer to object that will be removed
       */
      BDI_INLINE LIBBDIOBJECT_ARRAY_TYPE* remove(LIBBDIOBJECT_ARRAY_TYPE* object);

      /*l
       **  Removes all objects in the array.  Unlike other remove functions,
       **  objects will be deleted if the array owns its objects.
       */
      BDI_INLINE int remove_all(void);

      /*l
       **  Removes and deletes the object at the specified index of the array.
       **
       *a  index          - index into objects array where object will be deleted
       */
      BDI_INLINE int delete_at_index(int index);

      /*l
       **  Gets the object at the specified index of the array and returns it.
       **
       *a  index      - index into objects array
       *a  returns    - pointer to the object; NULL if index invalid
       */
      BDI_INLINE LIBBDIOBJECT_ARRAY_TYPE* get_at_index(int index) const;

      /*l
       **  Gets the object at the specified index of the array and returns it.
       **
       *a  index      - index into objects array
       *a  returns    - pointer to the object; NULL if index invalid
       */
      BDI_INLINE LIBBDIOBJECT_ARRAY_TYPE* operator [] (int index) const;

      /*l
       **  Finds the passed object in the array, if it's there, and returns its index.
       **
       *a  object          - pointer to object that to be checked
       *a  returns         - index of the object, -1 if not found
       */
      BDI_INLINE int get_index(LIBBDIOBJECT_ARRAY_TYPE* object) const;

      /*l
       **  Perform multiple get_index calls.
       **  The length of indexes must be at least src->size() long.
       **  If items in `src' are not found in `this', then -1 is filled in.
       */
      BDI_INLINE void get_indices(int* indices, const LIBBDIOBJECT_ARRAY_CLASS_NAME& src) const;

      /*l
       **  Same as above, but use unsigned shorts for indices.
       */
      BDI_INLINE void get_ushort_indices(unsigned short* indices, const LIBBDIOBJECT_ARRAY_CLASS_NAME& src) const;

      /*l
       **  Returns the number of objects currently in the array.
       */
      BDI_INLINE int size(void) const { return m_num_objects; }

      /*l
       **  Resizes the number of objects currently allocated for the array.
       **  Note that no new objects will be added to the array if the new
       **  allocation if larger (size() will return the same value), but some
       **  may be removed if the new allocation is smaller.
       */
      BDI_INLINE int resize_allocation(int num_objects);

      /*l
       **  Returns the flag determining whether the array owns the objects.
       **  If the array owns the object and the array is deleted, the object is
       **  deleted as well.
       **
       **  Default value is 0.
       */
      BDI_INLINE int get_own_objects(void) const { return m_own_objects; }

      /*l
       **  Sets the flag determining whether the array owns the objects.
       **  See get_own_objects().
       */
      BDI_INLINE void set_own_objects(int own_objects) { m_own_objects = own_objects; }

      /*l
       **  Returns the flag determining whether the objects in the array
       **  are pointers to arrays, in which case delete[] rather than delete
       **  should be called to destroy the objects.
       **
       **  Default value is 0.
       */
      BDI_INLINE int get_array_delete(void) const { return m_array_delete; }

      /*l
       **  Returns the flag determining whether the objects in the array
       **  are pointers to arrays.  See get_array_delete().
       */
      BDI_INLINE void set_array_delete(int array_delete) { m_array_delete = array_delete; }

      /*l
       **  Returns the flag determining whether the array will be cleared
       **  by successive pop_back() calls, or whether a more optimized
       **  method can be used.  This should be set to 1 if, when objects in
       **  the array are deleted, they remove themselves from the array
       **  automatically.
       **
       **  Default value is 0.
       */
      BDI_INLINE int get_pop_back_delete(void) { return m_pop_back_delete; }

      /*l
       **  Returns the flag determining whether the objects in the array
       **  will be cleared by successive pop_back() calls.  See
       **  get_pop_back_delete().
       */
      BDI_INLINE void set_pop_back_delete(int pop_back_delete) { m_pop_back_delete = pop_back_delete; }

      /*l
       **  Sets the name of the array.
       **
       *a  name - The passed string is copied.  If NULL is passed, the name will
       *a         be set to the character string "" (0 length string).
       */
      BDI_INLINE void set_name(const char* name);

      /*l
       **  Returns the name of the array.  The char pointer returned will never
       **  be NULL; if the object has no name, the pointer will point to the
       **  character string "" (0 length string).
       */
      BDI_INLINE const char* get_name(void) const;

      /*l
       **  Returns if we are using a geometric growth pattern
       */
      BDI_INLINE int get_geometric_growth() const { return m_geometric_growth; }

      /*l
       **  set if we are using a geometric growth pattern
       */
      BDI_INLINE void set_geometric_growth(const int growth) { m_geometric_growth = growth; }

      /*l
      **  use with caution
      */
      LIBBDIOBJECT_ARRAY_TYPE** get_array_data() { return m_objects; }

      virtual size_t get_memory_usage();
      virtual size_t get_children_memory_usage();

#ifdef LIBBDIOBJECT_ARRAY_DEEP_COPY

      /*l
      **  use with caution
      */
      BDI_INLINE void deep_copy(const LIBBDIOBJECT_ARRAY_CLASS_NAME & rhs);

#endif

#ifdef LIBBDIOBJECT_ARRAY_PACKABLE

      BDI_INLINE bdiCfgEntry * create_cfg_entry(bdiCfgEntry *e, const char * array_name);
      BDI_INLINE void parse_cfg_entry(bdiCfgEntry *e);

#endif

#ifdef   LIBBDIOBJECT_ARRAY_PACKABLE_SUBENTRIES

      BDI_INLINE bdiCfgEntry * create_cfg_entry(bdiCfgEntry *e, const char * array_name);
      BDI_INLINE void parse_cfg_entry(bdiCfgEntry *e);

#endif
      /*l
       **  Tracker object for keeping track of who needs to update, who doesn't.
       */
      bdiDataTracker* data_tracker;

   protected:

      /*l
       **  Ensures that at least min_objects are allocated.
       **
       *a  min_objects - minimum number of objects allocated
       */
      BDI_INLINE int check_object_allocation(int min_objects);

      /*
       *========================================
       *2  Data Members
       */

       /*l
        **  Number of objects currently in the array.
        */
      int m_num_objects;

      /*l
       **  Number of objects allocated in the array.  Will be >= to m_num_objects.
       */
      int m_num_objects_allocated;

      /*l
       **  Array of object pointers.  Grow the array by
       **  calling check_object_allocation().
       */
      LIBBDIOBJECT_ARRAY_TYPE** m_objects;

      /*l
       **  Flag determining whether the array owns the objects.
       **  See get_own_objects().
       */
      int m_own_objects;

      /*l
       **  Flag determining whether the objects in the array
       **  are pointers to arrays.  See get_array_delete().
       */
      int m_array_delete;

      /*l
       **  See get_pop_back_delete().
       */
      int m_pop_back_delete;

      /*l
       **  Name of the array.
       */
      char* m_name;

      /*l
       **  Amount by which array grows when more space is needed.
       */
      int m_increment;

      /*l
       **  weather or not the increment flag is ignored and a 2x growth method is used.
       */
      int m_geometric_growth;

   private:

      /*l
       **  The default copy constructor is disabled by declaring it private
       */
      LIBBDIOBJECT_ARRAY_CLASS_NAME(const LIBBDIOBJECT_ARRAY_CLASS_NAME &);

      /*l
       **  The default assignment operator is disabled by declaring it private.
       */
      LIBBDIOBJECT_ARRAY_CLASS_NAME& operator= (const LIBBDIOBJECT_ARRAY_CLASS_NAME &);

   };

#ifdef BDI_INLINE
#undef BDI_INLINE 
#endif

}