/** @file  psVector.h
 *
 *  @brief Contains basic vector definitions and operations
 *
 *  This file defines the basic type for a vector struct and functions useful
 *  in manupulating vectors.
 *
 *  @ingroup Vector
 *
 *  @author Robert DeSonia, MHPCC
 *  @author Ross Harman, MHPCC
 *
 *  @version $Revision: 1.13 $ $Name: not supported by cvs2svn $
 *  @date $Date: 2004-07-15 23:52:33 $
 *
 *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
 */

#ifndef PS_VECTOR_H
#define PS_VECTOR_H

#include "psType.h"

/// @addtogroup Vector
/// @{

/** An vector to support primitive types.
 *
 * Struct for maintaining an vector of frequently used primitive types.
 *
 */
typedef struct
{
    psType type;                        ///< Type of data.
    unsigned int nalloc;                ///< Total number of elements available.
    unsigned int n;                     ///< Number of elements in use.

    union {
        psU8    *U8;                    ///< Unsigned 8-bit integer data.
        psU16   *U16;                   ///< Unsigned 16-bit integer data.
        psU32   *U32;                   ///< Unsigned 32-bit integer data.
        psU64   *U64;                   ///< Unsigned 64-bit integer data.
        psS8    *S8;                    ///< Signed 8-bit integer data.
        psS16   *S16;                   ///< Signed 16-bit integer data.
        psS32   *S32;                   ///< Signed 32-bit integer data.
        psS64   *S64;                   ///< Signed 64-bit integer data.
        psF32   *F32;                   ///< Single-precision float data.
        psF64   *F64;                   ///< Double-precision float data.
        psC32   *C32;                   ///< Single-precision complex data.
        psC64   *C64;                   ///< Double-precision complex data.
        psPTR    V;                     ///< Pointer to data.
    } data;                             ///< Union for data types.
}
psVector;

/*****************************************************************************/
/* FUNCTION PROTOTYPES                                                       */
/*****************************************************************************/

/** Allocate a vector.
 *
 * Uses psLib memory allocation functions to create a vector collection of data as defined by the psType type.
 *
 * @return psVector*: Pointer to psVector.
 *
 */
psVector *psVectorAlloc(
    unsigned int nalloc,                ///< Total number of elements to make available.
    psElemType dataType                 ///< Type of data to be held by vector.
);

/** Reallocate a vector.
 *
 * Uses psLib memory allocation functions to reallocate a vector collection of data. The vector is reallocated
 * according to the psType type member contained within the vector.
 *
 * @return psVector*: Pointer to psVector.
 *
 */
psVector *psVectorRealloc(
    unsigned int nalloc,                ///< Total number of elements to make available.
    psVector *restrict psVec            ///< Vector to reallocate.
);

/** Recycle a vector.
 *
 * Uses psLib memory allocation functions to reallocate a vector collection of data. The vector is reallocated
 * according to the psElemType type parameter.
 *
 * @return psVector*: Pointer to psVector.
 *
 */
psVector *psVectorRecycle(
    psVector *restrict psVec,
    ///< Vector to recycle.  If NULL, a new vector is created.  No effort taken to preserve the values.

    unsigned int nalloc,                ///< Total number of elements to make available.
    psElemType type                     ///< the datatype of the returned vector
);

/** Sort an array of floats.
 *
 *  Sorts an array of floats in ascending order.  This function is valid for
 *  all non-complex data types.
 *
 *  @return  psFloatArray*: Pointer to sorted psFloatArray.
 */

psVector *psVectorSort(
    psVector *restrict outVector,  ///< the output vector to recycle, or NULL if new vector desired.
    const psVector *restrict inVector ///< the vector to sort.
);

/** Creates an array of indices based on sort odred of float array.
 *
 *  Sorts an array of floats and creates an integer array holding indices of 
 *  sorted float values based on pre-sort index positions.  
 *
 *  @return  psIntArray*: Pointer to psIntArray of sorted indices.
 */

psVector *psVectorSortIndex(
    psVector *restrict outVector,
    const psVector *restrict inVector
);


/// @}

#endif
