#ifndef __SLIST_H__
#define __SLIST_H__

/**
 * slist.h
 *   The interface for a simple implementation of lists with cursors.
 *
 * Copyright (c) 2010-2011 Samuel A. Rebelsky, All Rights Reserved
 *
 *   This program is free software: you can redistribute it and/or
 *   modify it under the terms of the GNU Lesser General Public License
 *   as published by the Free Software Foundation, either version 3 of
 *   the License, or (at your option) any later version.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *   Lesser General Public License for more details.
 *
 *   You should have received a copy of the GNU Lesser General
 *   Public License along with this program.  If not, see
 *   <http://www.gnu.org/licenses/>.
 */

`
// +-------+----------------------------------------------------------
// | Notes |
// +-------+

/*

 These are lists *with* cursors.  That means that in order to iterate
 the list, you need to create a separate cursor.

 Encapsulation suggests that we not reveal the internals of lists at
 this stage.  In addition, we want to be able to change the implementation.
 Since lists are mutable, we will simply make them pointers.

 */

`
// +-------+----------------------------------------------------------
// | Types |
// +-------+

/**
 * Lists of strings.
 */
typedef void *SList;

/**
 * Cursors in lists of strings.
 */
typedef void *SCursor;


`
// +--------------------------+---------------------------------------
// | Construction/Destruction |
// +--------------------------+

/**
 * Create a new list.  Returns the list if successful and NULL if
 * unsuccessful.
 */
SList slist_new (void);

/**
 * Free the memory associated with a list.  Should always succeed.
 * Nonetheless, returns an integer that indicates success (1) or
 * failure (0).
 */
int slist_free (SList slist);

`
// +--------------------+---------------------------------------------
// | Information Access |
// +--------------------+

/**
 * Get a cursor at the head of the list.  Returns NULL if the cursor
 * cannot be allocated.
 */
SCursor head (SList slist);

/**
 * Get a cursor at the tail of the list (why)?  Returns NULL if the
 * cursor cannot be allocated.
 */
SCursor tail (SList slist);

`
// +-------------------+----------------------------------------------
// | List Modification |
// +-------------------+

/**
 * Add an element to the front of the list.
 */
int addHead (SList slist, static char *str);

/**
 * Add an element to the tail of the list.
 */
int addTail (SList slist, static char *str);

/**
 * Add an element immediately before the cursor.
 */
int addBefore (SList slist, SCursor cursor, static char *str);

/**
 * Add an element immediately after the cursor.
 */
int addAfter (SList slist, SCursor cursor, static char *str);

/**
 * Delete the element at the cursor, advancing the cursor to the next
 * element.
 */
int delete (SList slist, SCursor cursor);

`
// +-------------------+----------------------------------------------
// | Cursor Operations |
// +-------------------+

/**
 * Determine if the cursor is at the head of the list.
 */
int atHead (SCursor cursor);

/**
 * Determine if the cursor is at the tail of the list.
 */
int atTail (SCursor cursor);

/**
 * Determine if the cursor is likely to be "valid" for a given list.
 */
int isValid (SCursor cursor, SList slist);

/**
 * Get the value associated at the cursor's position in the list.
 */
char *scursor_get (SCursor cursor, SList slist);

/**
 * Advance the cursor to the next element.  Pre: ! atTail (cursor)
 */
int scursor_advance (SCursor cursor);

/**
 * Retreat the cursor.  Pre: ! atHead (cursor).  Warning! Can be costly.
 */
int scursor_retreat (SCursor cursor);

#endif // __SLIST_H__