CS360 Lecture notes -- Doubly Linked Lists

Doubly Linked Lists

With a doubly linked list, each node has two pointers -- one to the next node in the list, and one to the previous node. Additionally, each list has an extra node called a "sentinel" node. This makes life nice in many ways:

• You can traverse lists forward and backward.
• You can insert anywhere in a list easily. This includes inserting before a node, after a node, at the front of the list, and at the end of the list.
• You can delete nodes very easily.

typedef struct dllist {
  struct dllist *flink;
  struct dllist *blink;
  Jval val;
} *Dllist;

Here are the essential operations supported:

• Dllist new_dllist(): Allocates and returns a new doubly linked list.
• free_dllist(Dllist l): Destroys the list, calling free() on all allocated memory in the list. The list does not have to be empty.
• dll_prepend(Dllist l, Jval val): Adds a new node at the beginning of the list. This node's value is val. Dll_prepend() has no return value.
• dll_append(Dllist l, Jval val): Adds a new node at the end of the list. This node's value is val. Dll_append() has no return value.
• dll_insert_b(Dllist n, Jval val): Adds a new node to the list right before the specified node. This node's value is val.
• dll_insert_a(Dllist n, Jval val): Adds a new node to the list right after the specified node. This node's value is val.
• dll_delete_node(Dllist): Deletes the given node from the list. Don't call this on the sentinel.
• int dll_empty(Dllist l): Returns whether l is empty.

• Dllist dll_nil(Dllist l): Returns a pointer to the nil (sentinel) node for the list. You can think of nil as a node with no value, that begins and ends the list. Since l points to the sentinel node, dll_nil returns l. You don't need to call dll_nil() to access the sentinel node. You can just use l, although it makes your code more readable if you use dll_nil().
• Dllist dll_first(Dllist l): Returns a pointer to the first node in the list. If the list is empty, this returns the sentinel. As with dll_nil(), you don't need to call dll_first(l) -- you can just use l->flink.
• Dllist dll_last(Dllist l): Returns a pointer to the last node in the list. If the list is empty, this returns the sentinel. As with dll_nil(), you don't need to call dll_last(l) -- you can just use l->blink.
• Dllist dll_next(Dllist n): Returns a pointer to the next node in the list after n. If n is the last node on the list, then dll_next(n) returns the sentinel. As with dll_first(), you don't need to call dll_next(n) -- you can just use n->flink.
• Dllist dll_prev(Dllist n): Returns a pointer to the previous node in the list before n. If n is the first node on the list, then dll_prev(n) returns the sentinel. As with dll_last(), you don't need to call dll_prev(n) -- you can just use n->blink.
• Jval dll_val(Dllist n): Returns node n's val field. Again, you don't need to use this, but sometimes it comes in handy.
• int dll_delete_node(Dllist n): Deletes and frees node n.

#define dll_traverse(ptr, list) \
  for (ptr = (list)->flink; ptr != (list); ptr = ptr->flink)
#define dll_rtraverse(ptr, list) \
  for (ptr = (list)->blink; ptr != (list); ptr = ptr->blink)

The Structure of Dllists

Once again, the typedef for a dllist node is:

typedef struct dllist {
  struct dllist *flink;
  struct dllist *blink;
  Jval val;
} *Dllist;

Note that each node has two pointers -- a forward link (flink) to the next node on the list, and a backward link (blink) to the previous node on the list. Once you have created a dllist, you'll keep a pointer to the sentinel node.

The list is circular in both directions -- the sentinel's flink points to the first node on the list, and its blink points to the last node on the list. The first node's blink points to the sentinel, as does the last node's flink.

Some ascii art: Here's an empty list l, that would be returned from new_dllist():

l ----------------> |-----------|
               /--->| flink ---------\
               | /->| blink -------\ |
               | |  | val = ?   |  | |
               | |  |-----------|  | |
               | |                 | |
               | \-----------------/ |
               |                     |
               \---------------------/

l ----------------> |-----------|       |-----------|
               /--->| flink ----------->| flink ---------\
               | /->| blink ----------->| blink -------\ |
               | |  | val = ?   |       | val.i = 3 |  | |
               | |  |-----------|       |-----------|  | |
               | |                                     | |
               | \-------------------------------------/ |
               |                                         |
               \-----------------------------------------/

l ----------------->|-----------|       |-----------|
               /--->| flink ----------->| flink ---------\
               |  /------ blink |<----------- blink |<-\ |
               |  | | val = ?   |       | val.i = 3 |  | |
               |  | |-----------|       |-----------|  | |
               |  |                                    | |
               |  \------------------------------------/ |
               |                                         |
               \-----------------------------------------/

l ---------->|-----------|       |-----------|       |-----------|
        /--->| flink ----------->| flink ----------->| flink ---------\
        |  /------ blink |<----------- blink |<----------- blink |<-\ |
        |  | | val = ?   |       | val.i = 3 |       | val.i = 5 |  | |
        |  | |-----------|       |-----------|       |-----------|  | |
        |  |                                                        | |
        |  \--------------------------------------------------------/ |
        |                                                             |
        \-------------------------------------------------------------/

Usage examples

/* Printing the lines of standard input in reverse order, by appending
   to a dllist, and then printing the dllist backward. */

#include <stdio.h>
#include <string.h>
#include "fields.h"
#include "dllist.h"

int main()
{
  IS is;
  Dllist l;
  Dllist tmp;

  is = new_inputstruct(NULL);
  l = new_dllist();

  while (get_line(is) >= 0) {
    dll_append(l, new_jval_s(strdup(is->text1)));
  }

  /* Notice how convenient this macro is! */

  dll_rtraverse(tmp, l) printf("%s", tmp->val.s);
  return 0;
}

The second example is another standard: printing the last n lines of standard input. We do this by reading standard input into a Dllist, and making sure that the Dllist always has at most n nodes. Then we print it out. The code is in src/dlltail.c.

/* This program implements tail using a dllist.  It reads lines onto the dllist until
   it contains the proper number of lines.  Then, each time it reads a line, it appends
   to the dllist and then deletes the first line of the dllist.  At the end, it simply
   prints the dllist. */

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include "fields.h"
#include "dllist.h"

int main(int argc, char **argv)
{
  IS is;
  int n;
  Dllist l;
  Dllist tmp;

  /* Error check and read the number of lines to maintain. */

  if (argc != 2) {
    fprintf(stderr, "usage: dlltail n\n");
    exit(1);
  }
  n = atoi(argv[1]);
  if (n < 0) {
    fprintf(stderr, "usage: dlltail n  -- n must be >= 0\n");
    exit(1);
  }

  /* Create the inputstruct and dllist */

  is = new_inputstruct(NULL);
  l = new_dllist();

  /* Read each line and append to the dllist. */

  while (get_line(is) >= 0) {
    dll_append(l, new_jval_s(strdup(is->text1)));

    if (is->line > n) {          /* If the dllist is too big, delete the first line on it. */
      free(l->flink->val.s);     /* You have to free it, becuase you called strdup() to create it. */
      dll_delete_node(l->flink);
    }
  }

  /* At the end, print the dllist -- again note the convenience of dll_traverse. */

  dll_traverse(tmp, l) printf("%s", tmp->val.s);
  return 0;
}

A couple of notes about this program. First, you have to call strdup() to copy the string that you have read from standard input. Otherwise, get_line() will overwrite the string, and all of your lines will be the same (we've gone over this concept multiple times, but I like to keep hammering the point home).

Second, when you call dll_delete_node() it removes the node from the list and frees the node. However, if the val field points to data that has been allocated with malloc(), then that data is not freed automatically. That is because the dllist library has no idea what the data is. Perhaps you want it freed, or perhaps you don't, because it is on mutiple data structures.

In this program, you most definitely want to free the data -- suppose you read a file that has 10G worth of text and you simply want to read the last 10 lines -- if you don't free the data when you delete a node, you'll burn 10G of memory. If you do free the data, then you only store 10 lines in memory at a time.

A Last Example

UNIX> cat txt/input1.txt
1 Fred 2 3 Binky Dontonio
UNIX> bin/cos < txt/input1.txt
Fred                                         1.0000
Binky                                        2.0000
Dontonio                                     3.0000
UNIX> cat txt/input2.txt
1 2 3 Fred
UNIX> cos < txt/input2.txt
Fred                                         1.0000
                                             2.0000
                                             3.0000
UNIX> cat txt/input3.txt
1 2 Fred Binky Dontonio
UNIX> bin/cos < txt/input3.txt
Fred                                         1.0000
Binky                                        2.0000
Dontonio                                           
UNIX> bin/cos < txt/input3.txt | cat -e
Fred                                         1.0000$
Binky                                        2.0000$
Dontonio                                           $
UNIX> 

The solution is to use two Dllists -- one for doubles and one for strings. When you read stdin, you use sscanf() to determine if a word is a double, and if it is, you put it on the double lists. Otherwise, you call strdup() and put the string on the string lists. Then you print out in three phases. In the first, you print all the lines which have both doubles and strings. When you're done with that loop, you may have doubles or strings leftover. The remaining two loops handle each case. The code is in src/cos.c:

/* This program reads words and puts each word onto one of two lists.  If the word is
   a double, it puts it on one list.  If it's not, it puts it on the other list.  It
   then prints the two lists in two columns, formatted.  Please see the lecture notes
   for a precise definition of the format. */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "fields.h"
#include "dllist.h"

int main()
{
  Dllist dl, dtmp;  /* The list for doubles */
  Dllist sl, stmp;  /* The list for strings */
  double d;
  int i;
  IS is;

  /* Create the lists and the inputstruct */

  dl = new_dllist();
  sl = new_dllist();
  is = new_inputstruct(NULL);

  /* Append to the two lists, using sscanf to differentiate between numbers and strings. */

  while (get_line(is) >= 0) {
    for (i = 0; i < is->NF; i++) {
      if (sscanf(is->fields[i], "%lf", &d) == 1) {
        dll_append(dl, new_jval_d(d));
      } else {
        dll_append(sl, new_jval_s(strdup(is->fields[i])));
      }
    }
  }

  /* Print the lines that have both doubles and strings.   
     You'll note -- I'm using the sentinel to test for the end of each list */

  dtmp = dl->flink;
  stmp = sl->flink;
  while (dtmp != dl && stmp != sl) {
    printf("%-30s %20.4lf\n", stmp->val.s, dtmp->val.d);
    dtmp = dtmp->flink;
    stmp = stmp->flink;
  }

  /* Now print the lines that have strings only: */

  while (stmp != sl) {
    printf("%-30s %20s\n", stmp->val.s, "");
    stmp = stmp->flink;
  }

  /* And print the lines that have doubles only: */

  while (dtmp != dl) {
    printf("%-30s %20.4lf\n", "", dtmp->val.d);
    dtmp = dtmp->flink;
  }

  return 0;
}

Implementation Details

Many of the procedure implementations are trivial procedures or macros:

 
Dllist new_dllist()
{
  Dllist d;

  d = (Dllist) malloc (sizeof(struct dllist));
  d->flink = d;
  d->blink = d;
  return d;
}

dll_empty(Dllist l)
{
  return (l->flink == l);
}


free_dllist(Dllist l)
{
  while (!dll_empty(l)) {
    dll_delete_node(dll_first(l));
  }
  free(l);
}


#define dll_first(d) ((d)->flink)
#define dll_next(d) ((d)->flink)
#define dll_last(d) ((d)->blink)
#define dll_prev(d) ((d)->blink)
#define dll_nil(d) (d)

dll_insert_b(Dllist node, Jval v)       /* Inserts before a given node */
{
  Dllist new;

  new = (Dllist) malloc (sizeof(struct dllist));
  new->val = v;

  new->flink = node;
  new->blink = node->blink;
  new->flink->blink = new;
  new->blink->flink = new;
}

dll_insert_a(Dllist n, Jval val)        /* Inserts after a given node */
{
  dll_insert_b(n->flink, val);
} 

dll_append(Dllist l, Jval val)     /* Inserts at the end of the list */
{ 
  dll_insert_b(l, val);
}

dll_prepend(Dllist l, Jval val)    /* Inserts at the beginning of the list */
{ 
  dll_insert_b(l->flink, val);
} 

dll_delete_node(Dllist node)            /* Deletes an arbitrary iterm */
{
  node->flink->blink = node->blink;
  node->blink->flink = node->flink;
  free(node);
}