/**
 * collection.h
 *   The generic linear collction.  Provides a consistent interface for
 *   stacks, queues, priority queues, and the ilk.
 */

#ifndef __COLLECTION_H__
#define __COLLECTION_H__

/**
 * Procedure:
 *   collection_new
 * Purpose:
 *   Create a new collection, preferably with the given capacity.
 */
struct collection *new_collection (int recommended_capacity);

/**
 * Procedure:
 *   collection_copy
 * Purpose:
 *   Make a copy of a collection
 */
struct collection *collection_copy (struct collection *collection);

/**
 * Procedure:
 *   collection_free
 * Purpose:
 *   Free the space allocated to a collection.
 */
void collection_free (struct collection *stuff);

/**
 * Procedure:
 *   collection_put
 * Purpose:
 *    Add a COPY of str to the collection.
 */
int collection_put (struct collection *stuff, char *str);

/**
 * Procedure:
 *   collection_get
 * Purpose:
 *   Get something from the collection (as determined by the policy) and
 *   remove it from the collection.
 * Produces:
 *   A string, if the collection is nonempty.
 *   NULL, otherwise.
 * Ponderings:
 *   Since collection_put adds a copy, the client is responsible for freeing
 *   the returned value
 */
char *collection_get (struct collection *stuff);

/**
 * Procedure:
 *   collection_peek
 * Purpose:
 *   Determine the next thing to be returned by collection_get, but don't
 *   remove it.
 */
char *collection_peek (struct collection *stuff);

/**
 * Procedure:
 *   collection_size
 * Purpose:
 *   Determine how many elements are in the collection.
 */
int collection_size (struct collection *stuff);

/**
 * Procedure:
 *   collection_is_empty
 * Purpose:
 *   Determine if the collection is empty.
 */
int collection_is_empty (struct collection *stuff);

/**
 * Procedure:
 *   collection_is_full
 * Purpose:
 *   Determine if the collection is full.
 */
int collection_is_full (struct collection *stuff);


#endif // __COLLECTION_H__