DLISTE

Dieses Modul ist eine Listenverwaltung für eine sortierte Liste. Sie kann aber auch als unsortierte Liste verwendet werden, um damit z.B. als Container für einen Stack oder eine Queue zu dienen.

Sprachen

C, C++

Includefiles

#include <teramile/dliste.h>

Datentypen

typedef void *DlisteKeyType;

typedef void *DlisteDataType;

typedef struct dliste_element {
   DlisteKeyType Key;
   DlisteDataType Data;
   struct dliste_element *Prev;
   struct dliste_element *Next;
} DlisteElement, *DlisteKnoten;

typedef struct {
   DlisteKnoten DatenAnfang;
   DlisteKnoten DatenEnde;
   DlisteKnoten Aktuell;
   CmpFkt Compare;
} Dliste;

typedef void (*DlisteDelCbkFkt)(DlisteKnoten Blatt);

Funktionen

Dliste *DlisteCreate(CmpFkt Cmp);
Diese Funktion erzeugt eine neue Liste.
Cmp	Dies ist die Vergleichsfunktion für die Daten in der Liste. Diese Funktion bekommt zwei Argumente vom Typ ListeKeyType und muß einen Wert <0 liefern, wenn der erste Parameter kleiner als der zweite ist; 0 wenn beide gleich sind und einen Wert >0 wenn der erste Parameter grösser als der zweite ist.
Rückgabe:	Eine neue Liste im Erfolgsfall, NULL im Fehlerfall
void DlisteDestroy(Dliste *Wurzel, DlisteDelCbFkt Cb);
Diese Funktion gibt Liste wieder frei. Auch sämtliche Listenknoten werden automatisch freigegeben.
Wurzel	Dies ist die Adresse der Listenwurzel. Die Liste muss durch DlisteCreate angelegt werden.
Cb	Dies ist eine Callback Funktion, die den Key und die Daten eines Listenknotens aufräumen (freigeben) muss.
BOOL DlisteInsert(Dliste *Wurzel, DlisteKeyType Key, DlisteDataType Daten);
Diese Funktion fügt einen neuen Knoten in die Liste ein.
Wurzel	Dies ist die Adresse der Listenwurzel. Die Liste muss durch DlisteCreate angelegt werden.
Key	einzufügender Schlüssel (typloser Zeiger auf den Schlüssel).
Daten	einzufügende Daten (typloser Zeiger auf die Daten).
Rückgabe:	TRUE im Erfolgsfall, FALSE im Fehlerfall
BOOL ListeAhead(Liste *Wurzel, ListeKeyType Key, ListeDataType Daten);
Diese Funktion fügt einen neuen Knoten am Anfang der Liste ein.
Wurzel	Dies ist die Adresse der Listenwurzel. Die Liste muss durch ListeCreate angelegt werden.
Key	einzufügender Schlüssel (typloser Zeiger auf den Schlüssel).
Daten	einzufügende Daten (typloser Zeiger auf die Daten).
Rückgabe:	TRUE im Erfolgsfall, FALSE im Fehlerfall
BOOL ListeAppend(Liste *Wurzel, ListeKeyType Key, ListeDataType Daten);
Diese Funktion fügt einen neuen Knoten am Ende der Liste ein.
Wurzel	Dies ist die Adresse der Listenwurzel. Die Liste muss durch ListeCreate angelegt werden.
Key	einzufügender Schlüssel (typloser Zeiger auf den Schlüssel).
Daten	einzufügende Daten (typloser Zeiger auf die Daten).
Rückgabe:	TRUE im Erfolgsfall, FALSE im Fehlerfall
DlisteKnoten DlisteDelete(Dliste *Wurzel, DlisteKeyType Key);
Diese Funktion löscht das Element mit dem Schlüssel key aus der Liste. Der ausgehängte Listenknoten wird zurückgeliefert. Der Benutzer muss selbst den Speicher für den Schlüssel, die Daten und den zurückgelieferten Knoten freigeben!
Wurzel	Dies ist die Adresse der Listenwurzel. Die Liste muss durch DlisteCreate angelegt werden.
Key	Schlüssel für die zu löschenden Daten.
Rückgabe:	Zeiger auf den ausgehängten Datensatz oder NULL.
DlisteKnoten DlisteFinde(Dliste *Wurzel, DlisteKeyType Key);
Diese Funktion sucht das Element mit dem Schlüssel key.
Wurzel	Dies ist die Adresse der Listenwurzel. Die Liste muss durch DlisteCreate angelegt werden.
Key	Schlüesse für die zu suchenden Daten.
Rückgabe:	Zeiger auf den gefundenen Datensatz.
DlisteKnoten DlisteFirst(Dliste *Wurzel);
Diese Funktion liefert das erste Element der Liste.
Wurzel	Dies ist die Adresse der Listenwurzel. Die Liste muss durch DlisteCreate angelegt werden.
Rückgabe:	Zeiger auf den gefundenen Datensatz.
DlisteKnoten DlisteNext(Dliste *Wurzel);
Diese Funktion liefert das nächste Element der Liste. Der Benutzer muss zuerst mit DlisteFinde oder DlisteFirst ein Element gesucht haben!
Wurzel	Dies ist die Adresse der Listenwurzel. Die Liste muss durch DlisteCreate angelegt werden.
Rückgabe:	Zeiger auf den gefundenen Datensatz.
DlisteKnoten DlisteLast(Dliste *Wurzel);
Diese Funktion liefert das letzte Element der Liste.
Wurzel	Dies ist die Adresse der Listenwurzel. Die Liste muss durch DlisteCreate angelegt werden.
Rückgabe:	Zeiger auf den gefundenen Datensatz.
DlisteKnoten DlistePrev(Dliste *Wurzel);
Diese Funktion liefert das vorherige Element der Liste. Der Benutzer muss zuerst mit DlisteFinde oder DlisteLast ein Element gesucht haben!
Wurzel	Dies ist die Adresse der Listenwurzel. Die Liste muss durch DlisteCreate angelegt werden.
Rückgabe:	Zeiger auf den gefundenen Datensatz.

Benutzung

Ein Program muss für jede neue Liste eine Variable vom Typ Dliste* anlegen. Als erste Aktion muss ListeCreate aufgerufen werden. Der Parameter ist eine Vergleichsfunktion, die zwei Keys übergeben bekommt und einen Wert <0 liefert, wenn der erste Key kleiner als der zweite ist, 0 bei Gleichheit und >0 wenn der erste Key grösser ist. Danach können neue Knoten eigefügt werden, nach Knoten mit einem vorgegebenen Schlüssel gesucht werden und Knoten gelöscht werden.

Das Beispiel benutzt als Schlüssel und füer die Daten einen long. Da ein Pointer auf 68K Systemen gleich einem long ist, wird anstelle eines Pointers der long übergeben. Sollen Daten abgespeichert werden, die sich nicht per Cast in dem Pointer abspeichern lassen, muss per malloc Speicher angefordert werden und der Zeiger auf diese Daten uebergeben werden.

Wenn die Liste nicht mehr benötigt wird, sollten die Elemente wieder freigegeben werden. Dies kann dadurch geschehen, dass in einer Schleife das erste Element geholt wird und anschliessend gelöscht wird.

#include 
#include 
#include 
#include 

int MyCmp(void *d1, void *d2)
{
   return((long)d2 - (long)d1);
}

int main(void)
{  Dliste *TestListe;
   DlisteKnoten Node;

   /* Liste anlegen */
   TestListe = DlisteCreate(MyCmp);
   if (TestListe != NULL)
   {
      /* ein Element einfuegen */
      DlisteInsert(TestListe, (DlisteKeyType)3L, (DlisteDataType)5L);
      /* Ein element suchen */
      Node = DlisteFinde(TestListe, (DlisteKeyType)3L);
      if (Node != NULL)
         printf("gefunden, Daten = %ld\n", (long)(Node->Data));
      /* Alle Elemente wieder freigebene */
      Node = DlisteFirst(TestListe);
      while (Node != NULL)
      {
         DlisteDelete(MyListe, Node->Key);
         Node = DlisteFirst(TestListe);
      }
      DlisteDestroy(TestListe);
   }
   else
      puts("Fehler beim Anlegen der Liste");
}