flibs/datastructures(n) 1.0 "flibs"

NAME

flibs/datastructures - Linked lists

    TABLE OF CONTENTS
    SYNOPSIS
    DESCRIPTION
    ROUTINES
    COPYRIGHT

SYNOPSIS

call list_create( list, data)

call list_destroy( list)

count = list_count( list)

next => list_next( elem )

call list_insert( elem, data )

call list_insert_head( list, data )

call list_delete_element( list, elem )

call list_get_data( elem, data )

call list_put_data( elem, data )

The linkedlist.f90 source file allows you to implement linked lists of any (derived) type without having to edit the supplied source code. To this end a simple technique is used, which is best illustrated by an example:

module MYDATA_MODULE type MYDATA character(len=20) :: string end type MYDATA end module module MYDATA_LISTS use MYDATA_MODULE, LIST_DATA => MYDATA include "linkedlist.f90" end module MYDATA_LISTS

The above code defines a module MYDATA_MODULE with the derived type that is to be stored in the linked lists. The name of that derived type can be anything.

It also defines a module MYDATA_LISTS which will be the module that holds the functionality to use linked lists:

The module MYDATA_MODULE is used, but the derived type MYDATA is renamed to the (fixed) name LIST_DATA. (This is the name used in the generic source file.)
The source code for the actual routines is simply included via the INCLUDE statement.
Nothing more is required, we can close the source text for the module.

To use a single type of linked lists in a program, we can just use the MYDATA_LISTS module. If you need more than one type of data in linked lists, then apply the same renaming trick on using the specific linked lists modules.

In fact the example in the source file "two_lists.f90" shows the general technique of how to accomplish this.

ROUTINES

The source file linkedlist.f90 provides the following routines:

call list_create( list, data)

Create a new list with one element. The given data are copied and stored in that element.

type(LINKED_LIST), pointer list: The variable that will be used for accessing the list
type(LIST_DATA), intent(in) data: The data to be stored in the first element

call list_destroy( list)

Destroy the list. All elements contained in it will be destroyed as well.

type(LINKED_LIST), pointer list: The list to be destroyed

count = list_count( list)

Function to return the number of elements in the list.

type(LINKED_LIST), pointer list: The list in question

next => list_next( elem )

Function to return the next element in the list. Note: it returns a pointer to the next element, so you must use =>.

type(LINKED_LIST), pointer elem: The element in the list

call list_insert( elem, data )

Insert a new element (with the given data) into the list, after the given element.

type(LINKED_LIST), pointer elem: The element in the list after which to insert a new one.
type(LIST_DATA), intent(in) data: The data to be stored in the new element

call list_insert_head( list, data )

Insert a new element (with the given data) before the head of list. The argument "list" will point to the new head.

type(LINKED_LIST), pointer list: The list in question
type(LIST_DATA), intent(in) data: The data to be stored at the new head

call list_delete_element( list, elem )

Delete the given element from the list. The associated data will disappear.

type(LINKED_LIST), pointer list: The list in question
type(LINKED_LIST), pointer elem: The element to be deleted

call list_get_data( elem, data )

Copy the data belonging to the given element into the argument "data".

type(LINKED_LIST), pointer list: The element in question
type(LIST_DATA), intent(out) data: The variable to hold the data

call list_put_data( elem, data )

Copy the given data into the given element (overwriting the previous)

type(LINKED_LIST), pointer list: The element in question
type(LIST_DATA), intent(in) data: The new data

Notes:

The lists can only store data of the same derived type. In that sense the code is not generic.
Currently, the lists can only store derived types that do not require an explicit destruction. If you want to store a derived type with pointers to allocated memory, you can do that however, by supplying an assignment operator. This would lead to a memory leak though. It is best to wait for the next version which will allow such derived types to be stored.