/***********************************************************************
 * Element
 * A collection of function to operate on elements
 ***********************************************************************/
#ifndef _ELEMENT_H_
#define _ELEMENT_H_

#include <stddef.h>
#include <stdbool.h>

/* Opaque Structure */
typedef struct element_t Element;


/***********************************************************************
 * Tests whether two elements are equal
 *
 * PARAMETERS
 * a       Pointer to the first element
 * b       Size of the array
 *
 * RETURN
 * true    If a is equal to b (and vice versa)
 * false   Otherwise
 ***********************************************************************/
bool areEqual(const Element* a, const Element* b);


/***********************************************************************
 * Returns an integer code for the given element
 *
 * PARAMETERS
 * element    Pointer to an element
 *
 * RETURN
 * code       An integer code representing the element
 *            (there might be collisions!)
 ***********************************************************************/
int getCode(const Element* element);


/***********************************************************************
 * Returns a pointer to a random sequence of elements
 *
 * PARAMETERS
 * length       The size of the array
 *
 * RETURN
 * sequence     A valid pointer to a sequence
 * NULL         In case of error
 ***********************************************************************/
Element** createRandomSequence(size_t length);



/***********************************************************************
 * Returns a pointer to a sequence which contains a majority element
 *
 * PARAMETERS
 * length       The size of the array
 *
 * RETURN
 * sequence     A valid pointer to a sequence
 * NULL         In case of error
 ***********************************************************************/
Element** createMajoritySequence(size_t length);





/***********************************************************************
 * Returns a pointer to a sequence which contains few uniques elements
 *
 * PARAMETERS
 * length       The size of the array
 * nbUniques    The number of different elements
 *
 * RETURN
 * sequence     A valid pointer to a sequence
 * NULL         In case of error
 ***********************************************************************/
Element** createFewUniquesSequence(size_t nbUniques, size_t length);



/***********************************************************************
 * Releases the resources held by the sequence
 *
 * PARAMETERS
 * length       The size of the array
 ***********************************************************************/
void deleteSequence(Element** sequence, size_t length);




#endif // !_ELEMENT_H_
