#ifndef __LINEAR_H__
#define __LINEAR_H__

/**
 * linear.h
 *  Our generic linear structures.  Can be implemented as stacks, queues, priority queues, random queues, or whatever.
 */

// +----------------------------+-------------------------------------
// | Constructors & Destructors |
// +----------------------------+

/*
 * Procedure:
 *   construct
 * Parameters:
 *   minimum_capacity, a positive integer
 * Purpose:
 *   Create a new linear structure that holds at least minimum_capacity stings.
 * Produces:
 *   linear, a lienar structure
 * Preconditions:
 *   [No additional]
 * Postconditions:
 *   If construction succeeded, linear is a linear structure with a
 *     capacity of minimum_capacity that is currently empty.
 *   If construction failed, linear is NULL.
 */
struct linear *construct (int minimum_capacity);

/**
 * Procedure:
 *   destruct
 * Parameters:
 *   linear, a linear structure
 * Purpose:
 *   Free all the memory associated with the structure (except for that 
 *     associated *   with the strings).
 * Produces:
 *   [Nothing; Called for the side effect]
 * Preconditions:
 *   linear has not already been destructed.
 * Postconditions:
 *   Memory has been freed.
 *   linear is no longer usable.
 */
void destruct (struct linear *linear);


// +-----------+------------------------------------------------------
// | Observers |
// +-----------+

/**
 * Procedure:
 *   is_empty
 * Parameters:
 *   linear, a linear structure
 * Purpose:
 *   Determine if the structure is empty
 * Produces:
 *   empty, an integer, representing a Boolean.
 * Preconditions:
 *   [No additional]
 * Postconditions:
 *   If there are elements in the structure, empty is false (0).  
 *   Otherwise, empty is true (1).
 */
int is_empty (struct linear *linear);

/**
 * Procedure:
 *   is_full
 * Parameters:
 *   linear, a linear structure
 * Purpose:
 *   Determine if the structure is full.
 * Produces:
 *   full, an integer, representing a Boolean.
 * Preconditions:
 *   [No additional]
 * Postconditions:
 *   If there are elements in the structure, full is false (0).  
 *   Otherwise, full is true (1).
 */
int is_full (struct linear *linear);

/**
 * Procedure:
 *   peek
 * Parameters:
 *   linear, a linear structure
 * Purpose:
 *   Get the next value to be returned by get.
 * Produces:
 *   str, a string
 * Preconditions:
 *   ! is_empty (linear)
 * Postconditions:
 *   If nothing went wrong,
 *     str is the value the policy dictates should be returned (most recently
 *       added, least recently added, highest priority, random, whatever)
 *     linear contains one fewer copy of str.
 *   Otherwise
 *     str is NULL.
 * Ponderings:
 *   There is no reason that this should fail.  But it's better to 
 *   provide an outlet.
 *   If nothing went wrong
 */
char *peek (struct linear *linear);


// +----------+-------------------------------------------------------
// | Mutators |
// +----------+

/**
 * Procedure:
 *   add
 * Parameters:
 *   linear, a linear structure
 *   str, a string
 * Purpose:
 *   Add str to linear.
 * Produces:
 *   ok, an integer
 * Preconditions:
 *   ! is_full (linear)
 * Postconditions:
 *   If the add succeeded, ok is 1 and
 *     The linear structure now contains another copy of str.
 *   If the add failed, ok is 0.
 * Ponderings:
 *   I don't know why this would fail if the precondition is met, but
 *   it's better to be safe than sorry.
 */
int add (struct linear *linear, char *str);

/**
 * Procedure:
 *   get
 * Parameters:
 *   linear, a linear structure
 * Purpose:
 *   Get the next value from linear
 * Produces:
 *   str, a string
 * Preconditions:
 *   ! is_empty (linear)
 *   str is a member of linear
 * Postconditions:
 *   If nothing went wrong,
 *     str is the value the policy dictates should be returned (most recently
 *       added, least recently added, highest priority, random, whatever)
 *     linear contains one fewer copy of str.
 *   Otherwise
 *     str is NULL.
 * Ponderings:
 *   There is no reason that this should fail.  But it's better to 
 *   provide an outlet.
 */
char *get (struct linear *linear);

/**
 * Procedure:
 *   clear
 * Parameters:
 *   linear, a list
 * Purpose:
 *   Remove all of the elements of a linear structure.
 * Produces:
 *   [Nothing; Called for the side effect]
 * Preconditions:
 *   [No additional]
 * Postconditions:
 *   is_empty (linear)
 */
void clear (struct linear *linear);

#endif // __LINEAR_H__