# flibs/datastructures(n) 1.0 "flibs"

## NAME

flibs/datastructures - Linked lists

## TABLE OF CONTENTS

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 )

## DESCRIPTION

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.

## COPYRIGHT

Copyright © 2005 Arjen Markus <arjenmarkus@sourceforge.net>