/*
************************************************************************
**
**	Copyright (c) 2009..2013 by
**		Core|Vision B.V.
**		Cereslaan 10b
**		5384 VT  Heesch
**		The Netherlands
**
**	All Rights Reserved
**
************************************************************************
*/
/*
************************************************************************
**
**	Project name:   Dual Inventive: Zelfsignalerende Kortsluit Lans
**	Filename:       list.h
**	Author:			Jack Weeland
**	Date:			March 20, 2009
**	File version:	$Revision: 1.7 $
**					$Date: 2013/04/15 15:37:42 $
**
************************************************************************
*/
/*
************************************************************************
**
**	Linked list - definition
**
************************************************************************
*/

#ifndef _LIST_H
#define _LIST_H

/*
**	Type definition
*/

// the list itself
typedef struct __LIST *lst_t;

// list functions 'compare' (by default 'strcmp()') and 'delete' (by default 'free()')
//	first argument for 'compare' is the item in the list, the second is the
//	second argument passed into 'lst_find_item()'
typedef int (*lst_compare_fcn_t)(const void*, const void*);
typedef void (*lst_delete_fcn_t)(void*);
typedef struct __LIST_FUNCTIONS
{
	lst_compare_fcn_t compare;
	lst_delete_fcn_t  delete;
} lst_fcntable_t;

// list iteration; will be called by 'lst_iterate()' for each item in the list;
//	iteration will stop when the callback returns a value less than zero
// parameters
//	index - index of the item
//	data  - item data
//	param - as passed through 'lst_iterate()'
typedef int (*lst_iterate_fcn_t)(int index, void *data, void *param);

/*
**	Exported functions
*/

// initialization and destruction; 'chunksize' determines how many items
//	are allocated at a time (a 'chunksize' of '1' creates a classic linked
//	list); a 'chunksize' of '0' selects some default
lst_t lst_init(const lst_fcntable_t*, unsigned int chunksize);
void lst_destroy(lst_t);

// get the number of items, find an item by index or the index for an item
unsigned int lst_get_count(lst_t);
void *lst_get_item(lst_t, int);
int lst_find_item(lst_t, void*);
// type casted versions of lst_get_item(); the items in the array must be
//	strings in all cases
int lst_get_int(lst_t, int);
unsigned int lst_get_uint(lst_t, int);
unsigned long long lst_get_uint64(lst_t, int);
double lst_get_float(lst_t, int);
const char *lst_get_str(lst_t, int);

// iterate a function over the list; if the function returns a value < '0',
//	the iteration will stop
// returns the index of the item that returned '-1' or '-1' when the complete
//	list was iterated and none of the items return '-1' (huh? yup!)
int lst_iterate(lst_t, lst_iterate_fcn_t, void *param);
int lst_iterate_from(lst_t, lst_iterate_fcn_t, void *param, int start_index);

// add or delete an item from the list; returns the index for the new item
// the item data should be allocated with 'malloc()', unless you attach your
//	own 'lst_delete_fcn_t' function to the list
int lst_append(lst_t, void*);
// delete an item from the list; returns '-1' if the item is not found,
//	'0' if the list is now empty or '1' when there is still data in it
// the item is deleted with 'free()'
int lst_delete(lst_t, int);
int lst_delete_all(lst_t);

#endif /* _LIST_H */