instlist.c

Software Development in C: A Practical Approach to Programming and Design 软件开发：编程与设计（C））——国外经典教材·计

//---------------------------------------------------------
/*
File Name:	InstList.c
Comments:	This file contains the functions which 
			implement all of the valid operations on the 
			instance_list type. An instance list must be
			declared using the DeclareInstanceList() macro
			in InstList.h.
*/
//---------------------------------------------------------



//---------------------------------------------------------
// Include files

#include <assert.h>
#include <stdlib.h>
#include "InstList.h"
#include "MiscType.h"


// End Include files
//---------------------------------------------------------



//---------------------------------------------------------
/* 
Function Name:	InstanceListAddItem
Parameters:
	In:			theItem - Contains the address of the item
					to be added to the list.
	Out:		None.
	In/Out:		theList - Specifies a pointer to the 
					instance list.
Return Values:	Upon success, the InstanceListAddItem() 
				function returns the identifier of the item
				in the instance list. This identifier is used
				to access the item. If this function fails,
				it returns -1.
Comments:		Programs call this function to add items
				to instance lists. Memory for the item 
				must be allocated before this function is 
				called. 
				
				Applications call InstanceListGetLastError()
				to detect whether an error occured while this 
				function was executing, 
*/

instance_identifier InstanceListAddItem(
			instance_list *theList,
			instance_list_item theItem)
{
	instance_identifier i,itemNumber = -1;
	boolean found;
	instance_list_item *temp;
	instance_list_size newListSize;

	assert(theList);

	// Scan for an available spot.
	for (i=0, found = FALSE; 
	     (i < theList->listLength) && (!found);
	     i++)
	{
		if (theList->itemArray == NULL)
		{
			itemNumber = i;
			found = TRUE;
		}
	}

	// If there are no available spots in the list...
	if (!found)
	{
		newListSize = (theList->listLength + 1) * sizeof(instance_list_item);

		// Increase the size of the list.
		temp = (instance_list_item *)realloc(theList->itemArray,newListSize);

		// If the memory was allocated...
		if (temp)
		{
			theList->itemArray = temp;

			// Add the item.
			theList->itemArray[theList->listLength] = theItem;
			itemNumber = theList->listLength;

			theList->listLength++;
		}
		// Else the memory could not be allocated...
		else
		{
			// Set an error condition.
			theList->errorStatus = ILE_CANT_ALLOCATE_LIST;
		}
	}
	// Else an available sport was found...
	else
	{
		// Add the item at the available location.
		theList->itemArray[itemNumber] = theItem;
	}

	return (itemNumber);
}

// End InstanceListAddItem
//---------------------------------------------------------



//---------------------------------------------------------
/* 
Function Name:	InstanceListGetItem
Parameters:
	In:			theList - Specifies a pointer to the 
					instance list.
				itemID - Contains the identifier of the 
					item to be retrieved from the list.
	Out:		None.
	In/Out:		None.
Return Values:	Upon success, this function returns a pointer
				to the item in the instance list. Otherwise, it
				returns NULL.
Comments:		This function retrieves a pointer to an item in
				an instance list. It does not delete the item
				from the list.
				
				Applications call InstanceListGetLastError()
				to detect whether an error occured while this 
				function was executing, 
*/

instance_list_item InstanceListGetItem(
						instance_list *theList,
						instance_identifier itemID)
{
	instance_list_item theItem = NULL;

	assert(theList);
	assert(itemID >= 0);


	// If the item identifier is out of range...
	if (itemID >= theList->listLength)
	{
		// Set the error status.
		theList->errorStatus = ITEM_IDENTIFIER_OUT_OF_RANGE;
	}
	// Else the item is in range...
	else
	{
		// Get the item.
		theItem = theList->itemArray[itemID];

		// If the item was not in the list...
		if (theItem == NULL)
		{
			theList->errorStatus = ILE_ITEM_NOT_FOUND;
		}
	}

	return(theItem);
}

// End InstanceListGetItem
//---------------------------------------------------------



//---------------------------------------------------------
/* 
Function Name:	InstanceListGetLength
Parameters:
	In:			theList - Specifies a pointer to the 
					instance list.
	Out:		None.
	In/Out:		None.
Return Values:	This function returns the number of items in an 
				instance list.
Comments:		See Return Values.
*/

instance_list_size InstanceListGetLength(
						instance_list *theList)
{
	assert(theList);

	return(theList->listLength);
}

// End InstanceListGetLength
//---------------------------------------------------------



//---------------------------------------------------------
/* 
Function Name:	InstanceListRemoveItem
Parameters:
	In:			itemID - Contains the identifier of the list
					item to be removed.
	Out:		None.
	In/Out:		theList - Specifies a pointer to the 
					instance list.
Return Values:	Upon success, this function returns a pointer 
				to the item being removed. Otherwise, it 
				returns NULL.
Comments:		This function retrieves a pointer to the 
				specified list item, and removes the item 
				from the list. Once it has been removed
				from the list, the application is responsible
				for freeing the memory it occupies.
*/

instance_list_item InstanceListRemoveItem(
						instance_list *theList,
						instance_identifier itemID)
{
	instance_list_item theItem = NULL;

	assert(theList);
	assert(itemID >= 0);

	// If the item identifier is in range...
	if (itemID < theList->listLength)
	{
		// Get the item.
		theItem = theList->itemArray[itemID];

		// Remove it from the list.
		theList->itemArray[itemID] = NULL;
	}
	// Else the item identifier is not in range...
	else
	{
		// Set the error status.
		theList->errorStatus = ITEM_IDENTIFIER_OUT_OF_RANGE;
	}

	return (theItem);
}

// End InstanceListRemoveItem
//---------------------------------------------------------



//---------------------------------------------------------
/* 
Function Name:	InstanceListGetLastError
Parameters:
	In:			theList - Specifies a pointer to the 
					instance list.
	Out:		None.
	In/Out:		None.
Return Values:	This function returns the current error 
				status associated with the specified 
				instance list.
Comments:		See Return Values.
*/

instance_list_error InstanceListGetLastError(
						instance_list *theList)
{
	assert(theList);

	return (theList->errorStatus);
}

// End InstanceListGetLastError
//---------------------------------------------------------



//---------------------------------------------------------
/* 
Function Name:	InstanceListClearError
Parameters:
	In:			None.
	Out:		None.
	In/Out:		theList - Specifies a pointer to the 
					instance list.
Return Values:	None.
Comments:		This function resets the error status
				associated with an instance list to
				ILE_NO_ERROR.
*/

void InstanceListClearError(instance_list *theList)
{
	assert(theList);

	theList->errorStatus = ILE_NO_ERROR;
}

// End InstanceListClearError
//---------------------------------------------------------

// End InstList.c
//---------------------------------------------------------