
/** @file  psArray.h
 *
 *  @brief Contains basic array definitions and operations
 *
 *  This file defines the basic type for a array struct and functions useful
 *  in manupulating arrays.
 *
 *  @ingroup Array
 *
 *  @author Robert DeSonia, MHPCC
 *  @author Ross Harman, MHPCC
 *
 *  @version $Revision: 1.17 $ $Name: not supported by cvs2svn $
 *  @date $Date: 2004-09-28 23:26:48 $
 *
 *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
 */

#ifndef PS_ARRAY_H
#define PS_ARRAY_H

#include<stdbool.h>

#include "psType.h"
#include "psCompare.h"

/// @addtogroup Array
/// @{

/** An array to support primitive types.
 *
 * Struct for maintaining an array of frequently used primitive types.
 *
 */
typedef struct
{
    unsigned int nalloc;        ///< Total number of elements available.
    unsigned int n;             ///< Number of elements in use.
    psPTR* data;                ///< An Array of pointer elements
}
psArray;

/*****************************************************************************/

/* FUNCTION PROTOTYPES                                                       */

/*****************************************************************************/

/** Allocate an array.
 *
 * Uses psLib memory allocation functions to create an array collection of 
 * data
 *
 * @return psArray* : Pointer to psArray.
 *
 */
psArray* psArrayAlloc(
    unsigned int nalloc                ///< Total number of elements to make available.
);

/** Reallocate an array.
 *
 * Uses psLib memory allocation functions to reallocate an array collection 
 * of data. 
 *
 * @return psArray* : Pointer to psArray.
 *
 */
psArray* psArrayRealloc(
    psArray* restrict psArr,           ///< array to reallocate.
    unsigned int nalloc                ///< Total number of elements to make available.
);

/** Remove an element from the array
 *
 *  Finds and removes the specified data pointer from the list.  
 *
 * @return bool:  TRUE if the specified data pointer was found and removed, 
 *                otherwise FALSE.
 *
 */
bool psArrayRemove(
    psArray* psArr,                    ///< array to operate on
    psPTR data                         ///< the data pointer to remove from psArray
);

/** Deallocate/Dereference elements of an array.
 *
 * Uses psLib memory allocation functions to deallocate/dereference elements 
 * of a array of void pointers.  The array psArr is not freed, and its elements
 * will all be set to NULL.
 *
 */
void psArrayElementFree(
    psArray* restrict psArr            ///< Void pointer array to destroy.
);

/** Sort the array according to an external compare function.
 *
 *  Sorts an array via the specification of a comparison function
 *  to specify how the objects on the array should be sorted.
 *
 *  The comparison function must return an integer less than, equal to, or 
 *  greater than zero if the first argument is considered to be respectively 
 *  less than, equal to, or greater than the second. 
 *
 *  If two members compare as equal, their order in the sorted array is 
 *  undefined.
 *
 *  @return psArray* The sorted array.
 */
psArray* psArraySort(
    psArray* in,                       ///< input array to sort.
    psComparePtrFcn compare            ///< the compare function
);

/// @}

#endif
