Contents of the SORTLIST.DOC file

SORTED LIST DATA TYPEIMPLEMENTED IN ANSI C

Version 1.1 8/25/93

by Walt Karas

This document accompanies several ANSI C source files that implementthe "sorted list" data structure. This implementation can be usedwhenever the set of possible elements of the sorted list have thefollowing characteristics:

1. All elements are of a single fixed size.

2. Each element is associated with a unique key value.

3. The set of key values has a well-defined "less than, greater than" relation.

A symbol table would be a typical application for the sorted list datastructure.

The sorted list data structure is implemented as an AVL tree. AVLtrees were invented by Adelson-Velskii and Landis. The reference fromwhich I obtained the algorithms is Horowitz and Sahni, "Fundamentalsof Data Structures" (Computer Science Press). The add, find, anddelete operations on an AVL tree have worst-case O(log n) timecomplexity.

USAGE

The sorted list data type is initialized by calling init_sort_list().Elements are added to the sorted list by calling add_sort_list(). Thefunction find_sort_list() is called to search for an element in thelist using its associated key value. Calling the functionapply_sort_list() causes another function (passed as a parameter) tobe called for an (in order) series of elements in the list. A sortedlist can be created from an ascendingly sorted sequence of elements bycalling the function build_sort_list(). Elements are deleted from thelist by calling delete_sort_list(). The function clear_sort_list()deletes all elements in the list. For detailed information about howto call these functions, please see the function prototypes andassociated comments in the file SORTLIST.H. An example of how to usethe sorted list data type is provided in the file EXAMPLE.C.

For this code to be portable to a particular architecture/ANSI Cimplementation, the following condition must be true: there exists atleast one data type, called ALIGN_TYPE, such that if A is a validstarting address for an instance of ALIGN_TYPE, than A is a validstarting address for any data structure. ALIGN_TYPE is defined inalign.h. The default for ALIGN_TYPE is short int. The default shouldwork for any reasonable ANSI C implementation for the followingarchitectures: 8086, 80x86, DEC VAX-11, 68000, DEC PDP-11. For allbut the last two of these architectures, ALIGN_TYPE could be changedto char. You may want to make ALIGN_TYPE larger than it needs to beto reduce skewed word memory references, the trade-off being morewasted "pad" bytes.

The constant TARGET_ALLOC defines the minimum number of bytes thatshould be requested by a call to malloc(). This constant is definedin the file STCKALLC.C. The allocation function in STCKALLC.C callsmalloc() to get a block of at least TARGET_ALLOC size, then doles itout node-by-node to the sorted list functions. Set the value ofTARGET_ALLOC to make the appropriate trade-off between minimizing heapoverhead/fragmentation and minimizing wasted unused portions ofallocated memory blocks.

The add, find, and delete functions have worst-case O(log n) timecomplexity only if the malloc() function has worst-case O(1) timecomplexity. I doubt this will be true for most, if any, malloc()implementations. To eliminate this problem, change the routines inSTCKALLC.C so that all needed memory for a sorted list is allocatedwhen the sorted list is initialized.