#ifndef __REQUEST_LIST_H__
#define __REQUEST_LIST_H__

#include <stdbool.h>

/**
 * A request sent to a game server. A request consists of the user
 * making the request and the position they are requesting a
 * response to.
 *
 * @param user a string, non-NULL
 * @param position a string, non-NULL
 */
typedef struct _request
{
  char *user;
  char *position;
} request;

/**
 * An ordered, indexed sequence of requests.
 */
typedef struct _rlist rlist;

typedef struct _rlist_iterator rlist_iterator;

/**
 * Creates and returns an empty list.
 * If there is an error allocating the list then the returned value
 * is NULL.
 *
 * @return a pointer to the new list
 */
rlist *rlist_create();

/**
 * Destroys the given list.  The list is invalid after it has been
 * destroyed.
 *
 * @param q a pointer to a valid list, non-NULL
 */
void rlist_destroy(rlist *el);

/**
 * Returns the size of the given list.
 *
 * @param el a pointer to a valid list, non-NULL
 * @return the size of that list
 */
int rlist_size(const rlist *el);

/**
 * Adds a deep copy of the given request to the end of the given list
 * (a "deep" copy is one that copies not just the struct, but the
 * data inside the struct, which in this case is the user and
 * position strings).  The return value is false if there was an
 * error allocating space for the new copy and in that case
 * the list is not changed.
 *
 * @param el a pointer to a valid list, non-NULL
 * @param a pointer to a valid request, non-NULL
 * @return true if and only if the request was added
 */
bool rlist_add(rlist *el, const request *r);

/**
 * Copies the data in the request at the given index in this list to
 * the given request.  Any data already in that request is
 * overwritten.  The data will be NULL if there was an error
 * allocating space for the copies.  It is the responsibility of the
 * caller to free the data copied into that request.
 *
 * @param el a pointer to a valid, non-empty list, non-NULL
 * @param i an integer between 0 (inclusive) and the size of the given list
 * (exclusive)
 * @param r a pointer to a request, non-NULL
 */
void rlist_get(const rlist *el, int i, request *r);

/**
 * Returns a pointer to a newly created iterator positioned at the
 * beginning of the given list.  It is the caller's responsibility
 * to eventually destroy the iterator.  If the new iterator could
 * not be allocated then the return value is NULL.
 *
 * @return a pointer to a new iterator, or NULL
 */
rlist_iterator *rlist_start(rlist *el);

/**
 * Returns a copy of the given iterator.  It is the caller's responsibility
 * to eventually destroy the newly created copy.  If the new iterator could
 * not be allocated then the return value is NULL.
 *
 * @return a pointer to a new iterator, or NULL
 */
rlist_iterator *rlist_iterator_copy(rlist_iterator *i);

/**
 * Determines if the given iterator is positioned at the end of
 * the list it is iterating through.
 *
 * @param i a pointer to a valid iterator, non-NULL
 * @return true if and only if that iterator is at the end
 */
bool rlist_iterator_at_end(const rlist_iterator *i);

/**
 * Moves the given iterator to the next item in the list it is iterating
 * through.
 *
 * @param i a pointer to a valid iterator not at the end, non-NULL
 */
void rlist_iterator_next(rlist_iterator *i);

/**
 * Determines if the given iterator is positioned before the start of
 * the list it is iterating through.
 *
 * @param i a pointer to a valid iterator, non-NULL
 * @return true if and only if that iterator is before the start
 *
 */
bool rlist_iterator_before_start(const rlist_iterator *i);

/**
 * Moves the given iterator to the previous item in the list it is iterating
 * through.
 *
 * @param i a pointer to a valid iterator not at the start, non-NULL
 */
void rlist_iterator_prev(rlist_iterator *i);

/**
 * Destroys the given iterator.  The iterator is invalid after
 * being destroyed.
 *
 * @param i a pointer to a valid iterator, non-NULL
 */
void rlist_iterator_destroy(rlist_iterator *i);

/**
 * Copies the data the the current location of the given iterator into
 * the given request.  Any data already in that request is overwritten.
 * It is the responsibility of the caller to free the data copied into
 * that request.  The data will be NULL if there was an error allocating
 * space for the copies.
 *
 * @param i a pointer to a valid iterator not at the end, non-NULL
 * @param r a pointer to a request, non-NULL
 */
void rlist_iterator_get(const rlist_iterator *i, request *r);

/**
 * Removes data the given iterator is currently positioned at from
 * the list that iterator it iterating through.  The iterator passed in
 * is positioned after removed item.  All other iterators at or after the
 * removed item are invalidated by the removal but must still be destroyed.
 *
 * @param i a pointer to a valid iterator not at the end, non-NULL
 */
void rlist_iterator_remove(rlist_iterator *i);

#endif