/*
 * zList.h
 * 
 * The Zen API 
 * Copyright (C) 2010 by LMI Technologies Inc.
 * 
 * Licensed under The MIT License.
 * Redistributions of files must retain the above copyright notice.
 */
#ifndef LMITECH_ZLIST_H_INCLUDED
#define LMITECH_ZLIST_H_INCLUDED

#include <zApi.h>
#include <zApiBegin.h>

typedef zHandle zList;        // Represents a list implemented with a dynamic array.

ZAPI_EXPORT(zStatus) zList_Construct(zList* list, zUIntPtr itemSize, z32u initialCapacity); //
//
//  Description:
//      Constructs a zList object.
//  Arguments:
//      list - Destination for the constructed object handle. 
//      itemSize - Size of a single list element.
//      initialCapacity - Capacity initially reserved for list items. 

ZAPI_EXPORT(zStatus) zList_Destroy(zList list); //
//
//  Description:
//      Destroys a zList object. 
//  Arguments:
//      list - The zList object to be destroyed.

ZAPI_EXPORT(zStatus) zList_Alloc(zList list, zUIntPtr itemSize, z32u initialCapacity); //
//
//  Description:
//      Resets the list item buffer.
//  Arguments:
//      list - List object. 
//      itemSize - Size of a single list element.
//      initialCapacity - Capacity initially reserved for list items. 
//  Remarks: 
//      Existing list items are not preserved.

ZAPI_EXPORT(zStatus) zList_Assign(zList list, zList source); //
//
//  Description:
//      Copies the source list. 
//  Arguments:
//      list - List object. 
//      source - Source list object to be copied.

ZAPI_EXPORT(zStatus) zList_Clear(zList list); //
//
//  Description:
//      Sets the count of list items to zero. 
//  Arguments:
//      list - List object. 

ZAPI_EXPORT(zStatus) zList_Add(zList list, const void* item); //
//
//  Description:
//      Adds the specified item to the end of the list.
//  Arguments:
//      list - List object. 
//      item - Pointer to item that will be copied (by value) into the list.
//  Remarks:
//      Increases list capacity, if necessary.

ZAPI_EXPORT(zStatus) zList_SetItem(zList list, z32u index,  const void* item); //
//
//  Description:
//      Sets the value of an item. 
//  Arguments:
//      list - List object. 
//      index - Item index. 
//      item - Item that will be copied into the list.

ZAPI_EXPORT(zStatus) zList_Item(zList list, z32u index, void* item); //
//
//  Description:
//      Gets the value of an item. 
//  Arguments:
//      list - List object. 
//      index - Item index. 
//      item - Destination for item that will be copied (by value) from the list. 

ZAPI_EXPORT(zStatus) zList_Insert(zList list, z32u before, const void* item); //
//
//  Description:
//      Inserts an item into the list at the specified position.
//  Arguments:
//      list - List object. 
//      before - Item will be inserted before the item at this index.
//      item - Pointer to item that will be copied (by value) into the list.
//  Remarks:
//      Increases list capacity, if necessary.

ZAPI_EXPORT(zStatus) zList_Remove(zList list, z32u index, void* item); //
//
//  Description:
//      Removes an item from the list at the specified index. 
//  Arguments:
//      list - List object. 
//      index - Item at this index will be removed from the list.
//      item - Destination for the removed item (copied by value, can be null).

ZAPI_EXPORT(void*) zList_Data(zList list); //
//
//  Description:
//      Returns a pointer to the list item buffer. 
//  Arguments:
//      list - List object. 

ZAPI_EXPORT(void*) zList_At(zList list, z32u index); //
//
//  Description:
//      Returns a pointer to the specified item in the list buffer. 
//  Arguments:
//      list - List object. 
//      index - Item index. 

ZAPI_EXPORT(zUIntPtr) zList_ItemSize(zList list); //
//
//  Description:
//      Returns the item size.
//  Arguments:
//      list - List object. 

ZAPI_EXPORT(z32u) zList_Count(zList list); //
//
//  Description:
//      Returns the total count of items in the list. 
//  Arguments:
//      list - List object. 

#include <zApiEnd.h>

#endif          /* #ifndef LMITECH_ZLIST_H_INCLUDED */