3D PLM Enterprise Architecture

About Lists of Pointers?

The following applies to list of pointers:

• The macro CATLISTP(T) refers to a class-collection of pointers to instances of type T (T is mostly a class)
• You will generate it very easily, using other macros
• The collection class you will obtain will gain benefits of C++ strong type checking, but is designed to reduce executable code size and to fasten heavily used operations usin inline definitions
• NULL pointers can be inserted in the collection, and duplicate pointers are allowed. The collection class can be managed as a dynamic array through resizing, or as a stack or queue
• You may get only the desired services. Minimal functionalities are provided, and if you require some more, you specify it through additional preprocessor flags.

Do not use CATLISTP(T) with T as a non-class (int or double for example), it is doesn't make sense.

[Top]

Programmer's Guide

To create a class for a list a pointers to MyClass, with the two methods Append and RemoveValue, create the following header file.

class MyClass;                     // Declare the class

#include "CATLISTP_Clean.h"        // Clean previous method requests

#define CATLISTP_Append            // Request the methods to create
#define CATLISTP_RemoveValue

#include "CATLISTP_Declare.h"      // Include macros

CATLISTP_DECLARE(MyClass);         // Declare the collection class

typedef CATLISTP(MyClass) MyClassCollection; // Define a handy name

The source file is as follows.

#include "MyClass.h"
#include "MyClassCollection.h"

#include "CATLISTP_Define.h"

CATLISTP_DEFINE(MyClass);

[Top]

Programmer's Reference

All the methods that you can set yo a list of pointers class are declared in CATLISTP_AllFunc.h.

#define	CATLISTP_CtorFromArrayPtrs
#define	CATLISTP_Append
#define	CATLISTP_AppendList
#define	CATLISTP_InsertAt
#define	CATLISTP_ReSize
#define	CATLISTP_Locate
#define	CATLISTP_RemoveValue
#define	CATLISTP_RemoveList
#define	CATLISTP_RemovePosition
#define	CATLISTP_RemoveAll
#define	CATLISTP_RemoveNulls
#define	CATLISTP_RemoveDuplicates
#define	CATLISTP_Compare
#define	CATLISTP_Swap
#define	CATLISTP_QuickSort
#define	CATLISTP_FillArrayPtrs
#define	CATLISTP_NbOccur
#define	CATLISTP_Intersection

Including first CATLISTP_Clean.h ensures that no previously declared method remains.

[Top]

Constructing a List of Pointers

You can construct a list of pointers using the following constructors.

• Constructs an empty list of pointers.

  CATLISTP(T)::CATLISTP(T) ( int iInitAlloc = 0);

  Parameters:

  iInitAlloc

  The amount of memory to be initially pre-allocated (forecasted number of items)

  By default, when no argument is specified, no pre-allocation is done.

• Copy constructor

  CATLISTP(T)::CATLISTP(T) ( const CATLISTP(T)& iCopy );

  Constructs a new list as a copy of iCopy.

  Parameters:

  iCopy

  The list of pointers to copy

• Constructs a list of pointers from a C-style array of pointers

  CATLISTP(T)::CATLISTP(T) ( T** iArray, int iSize );

  Constructs a list of iSize items from the iArray array.

  Parameters:

  iArray

  The C-style array of pointers

  iSize

  The number of items of the array

  Define the CATLISTP_CtorFromArrayPtrs preprocessor flag if you need this function.

• Constructs a list of pointers from a C-style array of values

  CATLISTP(T)::CATLISTP(T) ( T* iArray, int iSize );

  Constructs a list of iSize items from the iArray array.

  Parameters:

  iArray

  The C-style array of values

  iSize

  The number of items of the array

  Define the CATLISTP_CtorFromArrayVals preprocessor flag if you need this function.

Note that the destructor doesn't delete the pointed objects. Refer to the ApplyDelete method

[Top]

Copying a List of Pointers

You can copy a list a pointers in an existing one as follows.

• Assignment operator.

  CATLISTP(T)& CATLISTP(T)::operator= ( const CATLISTP(T)& iCopy );

  Parameters:

  iCopy

  The list of pointers to copy

[Top]

Adding Items to a List of Pointers

You can add items to a list of pointers as follows.

• Add a pointer at the end of the list

  void CATLISTP(T)::Append ( T* iAdd );

  Appends the item iAdd to the end of the list.

  Parameters:

  iAdd

  The item to append to the end of the list

  Define the CATLISTP_Append preprocessor flag if you need this function.

• Copy the pointers of another list to the end of the list

  void CATLISTP(T)::Append ( const CATLISTP(T)& iConcat );

  Appends a copy of the iConcat list to to the end of the self list.

  Parameters:

  iConcat

  The list of pointers to append

  Define the CATLISTP_AppendList preprocessor flag if you need this function.

• Insert a pointer at a given position

  void CATLISTP(T)::InsertAt ( int iPos, T* iAdd );

  Inserts the object pointed to by iAdd at the index position iPos.

  Parameters:

  iPos

  The position where iAdd is to be inserted
  Legal values: This position must be between one and the number of items in the list plus one.

  iAdd

  The item to insert

  Define the CATLISTP_InsertAt preprocessor flag if you need this function.

• Insert a pointer before a given position

  void CATLISTP(T)::InsertBefore ( int iPos, T* iAdd );

  Inserts the item iAdd before the index position iPos.

  Parameters:

  iPos

  The position before which iAdd is to be inserted
  Legal values: This position must be between one and the number of items in the list plus one. S being the size of the list, inserting an object before the S + 1 position means to append the item to the end of the list.

  iAdd

  The item to insert

  Define the CATLISTP_InsertBefore preprocessor flag if you need this function.

[Top]

Removing Items from a List of Pointers

You can remove items to a list of pointers as follows.

• Removing the first pointer matching a given one

  int CATLISTP(T)::RemoveValue ( T* iRemove );

  Removes the first item which is equal to iRemove.

  Parameters:

  iRemove

  The pointer whose first occurrence is to be removed

  Returns:

  1 if one item was found and then removed, and 0 otherwise

  Define the CATLISTP_RemoveValue preprocessor flag if you need this function.

• Removing the pointers that are in another list

  int CATLISTP(T)::Remove ( const CATLISTP(T)& iSubstract );

  Removes the items of the iSubstract list from the list

  Parameters:

  iSubstract

  The list of pointers to remove

  Returns:

  The number of removed items

  Define the CATLISTP_RemoveList preprocessor flag if you need this function.

• Indexed removal

  void CATLISTP(T)::RemovePosition ( int iPos );

  Removes the item at the index position iPos.

  Parameters:

  iPos

  The position at which the item is to be removed
  Legal values: This position must be between zero and the number of items in the list (included).

  Define the CATLISTP_RemovePosition preprocessor flag if you need this function.

• Removing all pointers

  void CATLISTP(T)::RemoveAll ( CATCollec::MemoryHandling iMH = CATCollec::ReleaseAllocation );

  Removing all the items from the list.

  Parameters:

  iMH

  Use iMH to specify if memory allocation is to be freed (the default) or kept.
  Legal values: CATCollec::ReleaseAllocation to free, and CATCollec::KeepAllocation to keep the memory allocation.

  Define the CATLISTP_RemoveAll preprocessor flag if you need this function.

• Removing the NULL pointers

  int CATLISTP(T)::RemoveNulls();

  Removes all the NULL pointers from the list.

  Define the CATLISTP_RemoveNulls preprocessor flag if you need this function.

• Removing duplicates pointers (returning count)

  int CATLISTP(T)::RemoveDuplicates ();

  Removes duplicates from the list.

  Define the CATLISTP_RemoveDuplicatesCount preprocessor flag if you need this function.

• Removing duplicated pointers (appending removed items in another list)

  void CATLISTP(T)::RemoveDuplicates ( CATLISTP(T)& ioExtract );

  Removes duplicates from the list and appends the removed items to the ioExtract list.

  Parameters:

  ioExtract

  The list to which duplicates items are to appended

  Define the CATLISTP_RemoveDuplicatesExtract preprocessor flag if you need this function.

[Top]

Retrieving and Setting the List Size

You can retrieve and set the size of a list of pointers as follows.

• Retrieving the size of a list of pointers

  int CATLISTP(T)::Size() const;

  Returns the number of items in the list.

  This method is provided by default and doesn't require a specific #define statement.

• Setting the size of a list of pointers

  void CATLISTP(T)::Size ( int iSize );

  Sets the number of items of a list of pointers.
  If the list size is smaller than iSize, NULL pointers are appended to match the requested size. Otherwise, the items whose index is greater from iSize are removed.

  Parameters:

  iSize

  The size to assign to the list

  Add #define CATLISTP_ReSize if you need this method.

[Top]

Retrieving and Locating Items

You can retrieve items from and locate items in a list of pointers as follows.

• Retrieving an item using its index in a constant list

  T* CATLISTP(T)::operator[] ( int iPos) const;

  Returns the iPosth item of the list.

  Parameters:

  iPos

  The index of the item to return
  Legal values: This index ranges from 1 to n, where n is the list size, as returned by the Size method

  This method is provided by default and doesn't require a specific #define statement.

• Retrieving an item using its index in a non constant list

  T*& CATLISTP(T)::operator[] ( int iPos);

  Returns the iPosth item of the list.

  Parameters:

  iPos

  The index of the item to return
  Legal values: This index ranges from 1 to n, where n is the list size, as returned by the Size method

  This method is provided by default and doesn't require a specific #define statement.

• Locating an item in a list

  int CATLISTP(T)::Locate ( T* iLocate, int iFrom = 1 ) const;

  Returns the index of the item equal to iLocate. By default, this function scans the list of pointers from the first item down to the end of the list.

  Parameters:

  iLocate

  The pointer to locate in the list

  iFrom

  The index from which the search must begin.
  Legal values: This index can range from 1 to n, where n is the list size, as returned by the Size method. The default value is 1.

  Returns:

  If 0 is returned, it means that the pointer does not exist in the list.

  Add #define CATLISTP_Locate if you need this method.

[Top]

Replacing, Swapping, and Sorting Items

You can replace, swap, and sort items in a list of pointers as follows.

• Replacing the value of an item

  void CATLISTP(T)::Replace ( int iPos, T* iReplace);

  Replaces the item at the index position iPos with the iReplace value.

  Parameters:

  iPos

  The index of the item to replace
  Legal values: This index ranges from 1 to n, where n is the list size, as returned by the Size method

  iReplace

  The replacing item

  Add #define CATLISTP_Replace if you need this method.

• Swapping two items

  void CATLISTP(T)::Swap ( int iPos1, int iPos2 );

  Swaps the items at index positions iPos1 and iPos2.

  Parameters:

  iPos1

  The index of the first item to swap
  Legal values: This index ranges from 1 to n, where n is the list size, as returned by the Size method

  iPos2

  The index of the second item to swap
  Legal values: This index ranges from 1 to n, where n is the list size, as returned by the Size method

  Add #define CATLISTP_Swap if you need this method.

• Quick sorting

  void CATLISTP(T)::QuickSort ( int (*iPFCompare) (const T*, const T*) );

  Sorts the items of the list according to a user-defined function pointed to by iPFCompare. This QuickSort function is similar to the qsort utility of the stdlib.h library.

  Returns: in iPFCompare:

  • A negative value if the first argument is smaller than the second argument
  • A positive value if the first argument is greater than the second argument
  • Zero if arguments are equal.

  Add #define CATLISTP_QuickSort if you need this method.

[Top]

Applying Operations to Pointed Objects

You can apply the following operations to items of a list of pointers as follows.

• To run a method on items (NULL ignored)

  typedef int (T::*PtrMbrFunct) (); int CATLISTP(T)::ApplyMemberFunct ( PtrMemberFunct iPF, int iFrom = 1, int iTo = 0, T** iPLast = NULL, int* iPRC = NULL ) const;

  Calls the method pointed to by iPF on items of the list  (NULLs ignored).
  Starts from the iFrom item up to the iTo item. (if iTo equals 0, it means up to the end of the list)
  Each call to iPF returns an int. If it is equal to 0, calls continue on next items, else the index of the item on which the process stops is returned.
  Optional argument iPLast is a pointer to a T pointer. If provided, it will contain the the value of the last item (a pointer) processed by the function.
  Optional argument iPRC is a pointer to an int. If provided, it will contain the value returned by the last call made by the function.
  If default values are used (i.e. only the first argument is given), apply the user-defined function pointed to by iPF to all items of the list (if each call returns 0).

  Parameters:

  iPF

  The pointer to the method

  iFrom

  The index of the first item onto which the method is called

  iTo

  The index of the last item onto which the method is called

  iPLast

  The pointer to the last processed item

  iPRC

  The pointer to the last method returned value

  Add #define CATLISTP_ApplyMemberFunct if you need this method.

• To run a const method on items (NULL ignored)

  typedef int (T::*PtrMbrFunctConst) () const; int CATLISTP(T)::ApplyMemberFunctConst ( PtrMemberFunctConst iPF, int iFrom = 1, int iTo = 0, T** iPLast = NULL, int* iPRC = NULL ) const;

  Calls the const method pointed to by iPF on items of the list  (NULLs ignored).
  Starts from the iFrom item up to the iTo item. (if iTo equals 0, it means up to the end of the list)
  Each call to iPF returns an int. If it is equal to 0, calls continue on next items, else the index of the item on which the process stops is returned.
  Optional argument iPLast is a pointer to a T pointer. If provided, it will contain the the value of the last item (a pointer) processed by the function.
  Optional argument iPRC is a pointer to an int. If provided, it will contain the value returned by the last call made by the function.
  If default values are used (i.e. only the first argument is given), apply the user-defined function pointed to by iPF to all items of the list (if each call returns 0).

  Parameters:

  iPF

  The pointer to the const method

  iFrom

  The index of the first item onto which the method is called

  iTo

  The index of the last item onto which the method is called

  iPLast

  The pointer to the last processed item

  iPRC

  The pointer to the last method returned value

  Add #define CATLISTP_ApplyMemberFunctConst if you need this method.

• To run a global function on items (NULL ignored)

  typedef int (*PtrGlbFunct) ( T* ); int CATLISTP(T)::ApplyGlobalFunct ( PtrGlbFunct iPF, int iFrom = 1, int iTo = 0, T** iPLast = NULL, int* iPRC = NULL ) const;

   

  Calls the gloabl function pointed to by iPF on items of the list  (NULLs ignored).
  Starts from the iFrom item up to the iTo item. (if iTo equals 0, it means up to the end of the list)
  Each call to iPF returns an int. If it is equal to 0, calls continue on next items, else the index of the item on which the process stops is returned.
  Optional argument iPLast is a pointer to a T pointer. If provided, it will contain the value of the last item (a pointer) processed by the function.
  Optional argument iPRC is a pointer to an int. If provided, it will contain the value returned by the last call made by the function.
  If default values are used (i.e. only the first argument is given), apply the user-defined function pointed to by iPF to all items of the list (if each call returns 0).

  Parameters:

  iPF

  The pointer to the global function

  iFrom

  The index of the first item onto which the method is called

  iTo

  The index of the last item onto which the method is called

  iPLast

  The pointer to the last processed item

  iPRC

  The pointer to the last method returned value

  Add #define CATLISTP_ApplyGlobalFunct if you need this method.

• To delete pointed instances (must have been dynamically allocated)

  void CATLISTP(T)::ApplyDelete ( CATCollec::Direction iDir = CATCollec::FromFirstToLast) const; enum CATCollec::Direction { CATCollec::FromFirstToLast, CATCollec::FromLastToFirst };

  Deletes all the instances pointed by the list. By default, will start deletion from the last element to the first one. But you may specify a more appropriate direction if you need so (i.e. a component removes itself from the container)

  Parameters:

  iDir

  The deletion direction

  Add #define CATLISTP_ApplyDelete if you need this method.

[Top]

Comparing Items

You can compare items of two lists of pointers as follows.

• Equality operator

  int CATLISTP(T)::operator== (const CATLISTP(T)& iLP) const;

  Compares iLP to the current list. Returns 1 when lists are equal.

  Parameters:

  iLP

  The list to compare with the current one

  This method is provided by default and doesn't require a specific #define statement.

• Inequality operator

  int CATLISTP(T)::operator!= (const CATLISTP(T)& iLP) const;

  Compares iLP to the current list. Returns 1 when lists are different.

  Parameters:

  iLP

  The list to compare with the current one

  This method is provided by default and doesn't require a specific #define statement.

• Less-than or equal operator

  int CATLISTP(T)::operator<= (const CATLISTP(T)& iLP) const;

  Compares iLP to to the current list. Returns 1 when to the current list is less or equal to iLP.

  Parameters:

  iLP

  The list to compare with the current one

  Add #define CATLISTP_leOP if you need this method.

• Greater-than or equal operator

  int CATLISTP(T)::operator>= (const CATLISTP(T)& iLP) const;

  Compares iLP to to the current list. Returns 1 when to the current list is greater or equal to iLP.

  Parameters:

  iLP

  The list to compare with the current one

  Add #define CATLISTP_geOP if you need this method.

• Less-than operator

  int CATLISTP(T)::operator≤ (const CATLISTP(T)& iLP) const;

  Compares iLP to the current list. Returns 1 when the current list is less than iLP.

  Parameters:

  iLP

  The list to compare with the current one

  Add #define CATLISTP_ltOP if you need this method.

• Greater-than operator

  int CATLISTP(T)::operator> (const CATLISTP(T)& iLP) const;

  Compares iLP to the current list. Returns 1 when  the current list is greater than iLP.

  Parameters:

  iLP

  The list to compare with the current one

  Add #define CATLISTP_gtOP if you need this method.

• Parameterized compare of two lists

  int CATLISTP(T)::Compare ( const CATLISTP(T)& iLP1, const CATLISTP(T)& iLP2, int (*iPFCompare) (const T*, const T*) );

  Returns 1 if iLP1 is greater, -1 if iLP2 is greater, or 0 if they are equal. The first discriminator is the size, then each element is compared using the function pointed by iPFCompare.

  Parameters:

  iLP1

  The first list to compare

  iLP2

  The second list to compare

  Add #define CATLISTP_Compare if you need this method.

[Top]

Doing More

You can do the following:

• Copy the pointers of the list inside a C-style array of pointers

  void CATLISTP(T)::FillArray ( T** ioArray, int iMaxSize ) const;

  Copies each item of the list to the ioArray array of pointers. (It should have the same size than the list.)

  Parameters:

  ioArray

  The array of pointers to which the list of pointers is to be copied

  iMaxSize

  The common size of the list and of the array

  Add #define CATLISTP_FillArrayPtrs if you need this method.

• Compute the intersection of two lists

  static void CATLISTP(T)::Intersection ( const CATLISTP(T)& iLP1, const CATLISTP(T)& iLP2, CATLISTP(T)& ioResult );

  Appends in the ioResult list the intersection of iLP1 and iLP2 list. If iLP1 contains duplicates, the ioResult may also contain duplicates.

  Parameters:

  iLP1

  The first list to intersect

  iLP2

  The second list to intersect

  ioResult

  The resulting intersection list

  Add #define CATLISTP_Intersection if you need this method.

• Number of occurrences of a pointer

  int CATLISTP(T)::NbOccur ( T* iTest );

  Returns the number of items (duplicates, if any, are counted) in the list that are equal to iTest.

  Parameters:

  iTest

  The item to test

  Add #define CATLISTP_NbOccur if you need this method.

• ostream OPERATOR<< output pointed instances on a ostream

  ostream& ::operator<< ( ostream& ioOS, const CATLISTP(T)& iLP ) const;

  Uses ::operator<< defined for type T on each instance pointed by the list

  Parameters:

  ioOS

  The ostream

  iLP

  The list to output to the stream

  Add #define CATLISTP_ostreamOP if you need this method.

• Print pointers values (for debug purposes)

  void CATLISTP(T)::PrintAddr ( ostream& ioOS ) const;

  Writes the list items on the ioOS ostream. (displays pointers values, i.e. addresses)

  Parameters:

  ioOS

  The item to append to the end of the list

  Add #define CATLISTP_PrintAddr if you need this method.

History

Copyright © 2000, Dassault Systèmes. All rights reserved.