Homework 8 - Linked List

From now on, we’ll assume that you work on homework by connecting to the CS portal and that you are familiar with the command line environment. If you have not been practicing with the terminal, we strongly encourage reviewing Lab 1.

We will also assume that you ran the setup script from that lab and have all modules (including clang and git) by default.

In this homework, you will implement a circular doubly-linked list in C. You will need to use malloc and free to store the list nodes on the heap.

Getting the starter code

In order to get our starter code for this homework, you’ll need to copy our starter code into your home directory. Use cd to enter your cso1-code directory, then issue the following command to copy our code.

cp /p/cso1/homework/linkedlist.* .

Now you have two files, a linkedlist.c file containing functions to implement and a linkedlist.h header file declaring the functions with documentation.

Writing your code

For this and future assignments, we are expecting that you will write your code in a command-line editor (vim, nano, etc) on the portal. If you need to refresh, please review Lab 1.

Using an IDE (such as Visual Studio Code, IntelliJ IDEA, etc, or an online editor or compiler will result in an immediate 0 on the assigment. Sorry to be strict on this, but one of the goals of this course is to gain familiarity with command-line tools.

Why a CLI editor?

It is common to interact with servers that do not have their own monitors. In these cases, you typically attach to the server via ssh and have access only to a terminal, not a full windowing environment. The more comfortable you are with doing common programming tasks in the terminal, the better these experiences will be.

Task

Edit the C file named linkedlist.c that contains implementations of functions for manipulating a circular doubly-linked list as described and declared in the header file linkedlist.h.

A doubly-linked list is a linked list where each node has a pointer to the previous and next nodes in the list (two pointers per node). In a normal doubly-linked list, the head node would have a NULL previous pointer (nothing’s before it), and the tail node would have a NULL next pointer (nothing’s after it). In a circular doubly-linked list, the head’s previous points to the tail and the tail’s next points to the head.

Your code in linkedlist.c should begin by including the given header file, #include "linkedlist.h". We will assume you use this exact linkedlist.h in our testing; if you change it, we will not use those changes in our compilation and testing of your code. Comments in linkedlist.h describe what each function is supposed to do.

To get you started, here is one of the functions required for the circular linked list implementation, fully and correctly implemented for you; it has also been included in the linkedlist.c file:

/* reference solution provided with assignment description */
void cll_show(cll_node *list) {
    cll_node *head = cll_head(list);
    cll_node *ptr = head;
    putchar('[');
    if (ptr) {
        do {
            if (!ptr->is_head) printf(", ");
            if (ptr == list) putchar('*');
            printf("%d", ptr->value);
            if (ptr == list) putchar('*');
            ptr = ptr->next;
        } while(ptr != head);
    }
    puts("]");
}

Testing your code

You should manually test your code, including using the lldb debugger and/or the debugging function provided below. Test all of the corner cases (NULL arguments; first-, last-, and middle-node arguments, finding values not in the list, etc). Do NOT rely on Gradescope to be your compiler and tester! The Gradescope submission site will open on Wednesday and will only allow a total of 15 submissions.

Example testing code

We have also provided an example of some test code in the provided main function. Once everything is implemented correctly, this code:

int main(int argc, const char *argv[]) {
    cll_node *x = NULL;
    putchar('A'); cll_show(x);
    x = cll_insert(25, x, 1);
    putchar('B'); cll_show(x);
    x = cll_insert(1, x, 0);
    putchar('C'); cll_show(x);
    x = cll_insert(98, x, 1);
    putchar('D'); cll_show(x);
    x = cll_insert(0, x, 1);
    putchar('E'); cll_show(x);
    x = cll_insert(-8, cll_tail(x), 0);
    putchar('F'); cll_show(x);
    cll_node *y = cll_head(x);
    putchar('G'); cll_show(y);
    printf("Length: %lu (or %lu)\n", cll_length(y), cll_length(x));
    x = cll_remove(x);
    putchar('H'); cll_show(x);
    putchar('I'); cll_show(y);
    x = cll_remove(cll_find(y, 98));
    putchar('J'); cll_show(x);
    putchar('K'); cll_show(y);
    
    return 0;
}

should display:

A[]
B[*25*]
C[25, *1*]
D[25, *98*, 1]
E[25, *0*, 98, 1]
F[25, 0, 98, 1, *-8*]
G[*25*, 0, 98, 1, -8]
Length: 5 (or 5)
H[]
I[*25*, 0, 98, 1]
J[25, 0, *1*]
K[*25*, 0, 1]

Tips

1. I have yet to see a student implement their first correct circular linked-list without drawing box-and-arrow pictures.

2. Debugging can be easier if you can see all of the pointers involved. You may want to write your own cll_show function similar to the one above that also prints the addresses of each node and its pointers to prev and next.

3. Don’t use after free! We will test your code with the address sanitizer enabled and may also manually check for additional memory errors.

Grading

For this assignment, the grade will consist of an autograded component (for correctness) and a code style grade. The breakdown is as follows:

• 85% code correctness (passing Gradescope tests)
• 5% well indented (readable) code
  • You should indent your code as if it were Python; that is, indent whenever you would use curly braces.
• 5% good variable names
  • Use names that express your code’s meaning.
• 5% comments
  • Document your code with comments so that you (and we) can better read what you wrote.
  • Write comments that explain any tricky sections as well as tell us (in English) what each section of your code is intended to do.
  • Hint: it might be helpful to write the comments first so that you have a rough sketch of your algorithm before implementation.

Submission

Submit your linkedlist.c to Gradescope. You may only submit a maximum of 15 times to the autograder, so you should test your code extensively by calling your functions in main(). After the 15th attempt, Gradescope will accept submissions, but the autograder will not run; Gradescope will only report the score of the 15th attempt.

Note: The submission site will be available beginning on Wednesday.