2 Objects

2.1 The top-level object

The PnlObject structure is used to simulate some inheritance between the ojbects of Pnl. It must be the first element of all the objects existing in Pnl so that casting any object to a PnlObject is legal

typedef unsigned int PnlType; 
 
typedef void (DestroyFunc) (void **); 
typedef PnlObject* (CopyFunc) (PnlObject *); 
typedef PnlObject* (NewFunc) (PnlObject *); 
typedef void (CloneFunc) (PnlObject *dest, const PnlObject *src); 
struct _PnlObject 
{ 
  PnlType type; /*!< a unique integer id */ 
  const char *label; /*!< a string identifier (for the moment not useful) */ 
  PnlType parent_type; /*!< the identifier of the parent object is any, 
                          otherwise parent_type=id */ 
  int nref; /*!< number of references on the object */ 
  DestroyFunc *destroy; /*!< frees an object */ 
  NewFunc     *constructor; /*!< New function */ 
  CopyFunc    *copy; /*!< Copy function */ 
  CloneFunc   *clone; /*!< Clone function */ 
};

Here is the list of all the types actually defined

We provide several macros for manipulating PnlObejcts.

• PNL_OBJECT (o)
  Description Cast any object into a PnlObject

• PNL_VECT_OBJECT (o)
  Description Cast any object into a PnlVectObject

• PNL_MAT_OBJECT (o)
  Description Cast any object into a PnlMatObject

• PNL_SP_MAT_OBJECT (o)
  Description Cast any object into a PnlSpMatObject

• PNL_HMAT_OBJECT (o)
  Description Cast any object into a PnlHmatObject

• PNL_BAND_MAT_OBJECT (o)
  Description Cast any object into a PnlBandMatObject

• PNL_TRIDIAGMAT_OBJECT (o)
  Description Cast any object into a PnlTridiagMatObject

• PNL_BASIS_OBJECT (o)
  Description Cast any object into a PnlBasis

• PNL_RNG_OBJECT (o)
  Description Cast any object into a PnlRng

• PNL_LIST_OBJECT (o)
  Description Cast any object into a PnlList

• PNL_LIST_ARRAY (o)
  Description Cast any object into a PnlArray

• PNL_GET_TYPENAME (o)
  Description Return the name of the type of any object inheriting from PnlObject

• PNL_GET_TYPE (o)
  Description Return the type of any object inheriting from PnlObject

• PNL_GET_PARENT_TYPE (o)
  Description Return the parent type of any object inheriting from PnlObject

• PnlObject * pnl_object_create (PnlType t)
  Description Create an empty PnlObject of type t which can any of the registered types, see Table 1.

2.2 List object

This section describes functions for creating an manipulating lists. Lists are internally stored as doubly linked lists.

The structures and functions related to lists are declared in pnl/pnl_list.h.

typedef struct _PnlCell PnlCell; 
struct _PnlCell 
{ 
  struct _PnlCell *prev;  /*!< previous cell or 0 */ 
  struct _PnlCell *next;  /*!< next cell or 0 */ 
  PnlObject *self;       /*!< stored object */ 
}; 
 
 
typedef struct _PnlList PnlList; 
struct _PnlList 
{ 
  /** 
   * Must be the first element in order for the object mechanism to work 
   * properly. This allows any PnlList pointer to be cast to a PnlObject 
   */ 
  PnlObject object; 
  PnlCell *first; /*!< first element of the list */ 
  PnlCell *last; /*!< last element of the list */ 
  PnlCell *curcell; /*!< last accessed element, 
                         if never accessed is NULL */ 
  int icurcell; /*!< index of the last accessed element, 
                     if never accessed is NULLINT */ 
  int len; /*!< length of the list */ 
};

Important note: Lists only store addresses of objects. So when an object is inserted into a list, only its address is stored into the list. This implies that you must not free any objects inserted into a list. The deallocation is automatically handled by the function pnl_list_free.

• PnlList * pnl_list_new ()
  Description Create an empty list

• PnlCell * pnl_cell_new ()
  Description Create an cell list

• PnlList * pnl_list_copy (const PnlList *A)
  Description Create a copy of a PnlList . Each element of the list A is copied by calling the its copy member.

• void pnl_list_clone (PnlList *dest, const PnlList *src)
  Description Copy the content of src into the already existing list dest. The list dest is automatically resized. This is a hard copy, the contents of both lists are independent after cloning.

• void pnl_list_free (PnlList **L)
  Description Free a list

• void pnl_cell_free (PnlCell **c)
  Description Free a list

• PnlObject * pnl_list_get ( PnlList *L, int i)
  Description This function returns the content of the i–th cell of the list L. This function is optimized for linearly accessing all the elements, so it can be used inside a for loop for instance.

• void pnl_list_insert_first (PnlList *L, PnlObject *o)
  Description Insert the object o on top of the list L. Note that o is not copied in L, so do not free o yourself, it will be done automatically when calling pnl_list_free

• void pnl_list_insert_last (PnlList *L, PnlObject *o)
  Description Insert the object o at the bottom of the list L. Note that o is not copied in L, so do not free o yourself, it will be done automatically when calling pnl_list_free

• void pnl_list_remove_last (PnlList *L)
  Description Remove the last element of the list L and frees it.

• void pnl_list_remove_first (PnlList *L)
  Description Remove the first element of the list L and frees it.

• void pnl_list_remove_i (PnlList *L, int i)
  Description Remove the i-th element of the list L and frees it.

• void pnl_list_concat (PnlList *L1, PnlList *L2)
  Description Concatenate the two lists L1 and L2. The resulting list is store in L1 on exit. Do not free L2 since concatenation does not actually copy objects but only manipulates addresses.

• void pnl_list_resize (PnlList *L, int n)
  Description Change the length of L to become n. If the length of L id increased, the extra elements are set to NULL.

• void pnl_list_print (const PnlList *L)
  Description Only prints the types of each element. When the PnlObject object has a print member, we will use it.

2.3 Array object

This section describes functions for creating and manipulating arrays of PnlObjects.

The structures and functions related to arrays are declared in pnl/pnl_array.h.

typedef struct _PnlArray PnlArray; 
struct _PnlArray 
{ 
  /** 
   * Must be the first element in order for the object mechanism to work 
   * properly. This allows any PnlArray pointer to be cast to a PnlObject 
   */ 
  PnlObject object; 
  int size; 
  PnlObject **array; 
  int mem_size; 
};

Important note: Arrays only store addresses of objects. So when an object is inserted into an array, only its address is stored into the array. This implies that you must not free any objects inserted into a array. The deallocation is automatically handled by the function pnl_array_free.

• PnlArray * pnl_array_new ()
  Description Create an empty array

• PnlArray * pnl_array_create (int n)
  Description Create an array of length n.

• PnlArray * pnl_array_copy (const PnlArray *A)
  Description Create a copy of a PnlArray . Each element of the array A is copied by calling the A[i].object.copy.

• void pnl_array_clone (PnlArray *dest, const PnlArray *src)
  Description Copy the content of src into the already existing array dest. The array dest is automatically resized. This is a hard copy, the contents of both arrays are independent after cloning.

• void pnl_array_free (PnlArray **)
  Description Free an array and all the objects hold by the array.

• int pnl_array_resize (PnlArray *T, int size)
  Description Resize T to be size long. As much as possible of the original data is kept.

• PnlObject * pnl_array_get ( PnlArray *T, int i)
  Description This function returns the content of the i–th cell of the array T. No copy is made.

• PnlObject * pnl_array_set ( PnlArray *T, int i, PnlObject *O)
  Description T[i] = O. No copy is made, so the object O must not be freed manually.

• void pnl_array_print (PnlArray *)
  Description Not yet implemented because it would require that the structure PnlObject has a field copy.