/*####COPYRIGHTBEGIN####
 -------------------------------------------
 Copyright (C) 2003 Steve Karg

 This program is free software; you can redistribute it and/or
 modify it under the terms of the GNU General Public License
 as published by the Free Software Foundation; either version 2
 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 General Public License for more details.

 You should have received a copy of the GNU General Public License
 along with this program; if not, write to
 The Free Software Foundation, Inc.
 59 Temple Place - Suite 330 
 Boston, MA  02111-1307, USA.

 As a special exception, if other files instantiate templates or
 use macros or inline functions from this file, or you compile
 this file and link it with other works to produce a work based
 on this file, this file does not by itself cause the resulting
 work to be covered by the GNU General Public License. However
 the source code for this file must still be made available in
 accordance with section (3) of the GNU General Public License.

 This exception does not invalidate any other reasons why a work
 based on this file might be covered by the GNU General Public
 License.
 -------------------------------------------
####COPYRIGHTEND####*/
#ifndef KEYLIST_H
#define KEYLIST_H

#include "key.h"

// This is a key sorted linked list data library that
// uses a key or index to access the data.

// list data and datatype
struct Keylist_Node;
typedef struct Keylist_Node *OS_Keylist;
typedef struct Keylist_Node
{
  struct Keylist_Node *next; // points to the next node in the list
  KEY key; // unique number that is sorted in the list
  void *data; // pointer to some data that is stored
} KEYLIST_NODE_TYPE;

// returns head of the list or NULL on failure.
OS_Keylist Keylist_Create(void);

// delete specified list
// note: you should pop all the nodes off the list first.
void Keylist_Delete(OS_Keylist list);

// inserts a node into its sorted position
// returns the index where it was added
int Keylist_Data_Add(
  OS_Keylist list,
  KEY key,
  void *data);

// deletes a node specified by its key
// returns the data from the node
void *Keylist_Data_Delete(
  OS_Keylist list,
  KEY key);

// deletes a node specified by its index
// returns the data from the node
void *Keylist_Data_Delete_By_Index(
  OS_Keylist list,
  int index);

// returns the data from last node, and removes it from the list
void *Keylist_Data_Pop(
  OS_Keylist list);

// returns the data from the node specified by key
void *Keylist_Data(
  OS_Keylist list,
  KEY key);

// returns the data specified by key
void *Keylist_Data_Index(
  OS_Keylist list,
  int index);

// returns the next empty key from the list
int Keylist_Next_Empty_Key(
  OS_Keylist list,
  KEY key);

// returns the number of items in the list
int Keylist_Count(
  OS_Keylist list);

#endif