Last Updated: 2024-08-29 Thu 14:58

CMSC216 Lab02: Basic C Application Coding

CODE DISTRIBUTION: lab02-code.zip

CHANGELOG: Empty

1 Rationale

This exercise demonstrates a number of C programming conventions through a small application. Studying the code, correcting some mistakes in it, and adding some new functionality will familiarize students with the basic edit/compile/test cycle common to coding projects. Completing the exercise will also show students a common application structure for C programs, dividing code between a main routine and a one or more "service" libraries that manipulate data structures. This approach will be used in an upcoming project.

Note: The techniques and syntax used in the provided code will eventually be described in lecture although some will not be discussed until after the exercise is due. This should encourage students to study the code carefully, experiment with it, and consult C coding resources such as The C Programming Language by Kernighan and Ritchie.

Grading Policy

Credit for this exercise is earned by completing the code/asnwers here and submitting a Zip of the work to Gradescope. Students are responsible to check that the results produced locally via make test are reflected on Gradescope after submitting their completed Zip. Successful completion earns 1 Engagement Point.

Lab Exercises are open resource/open collaboration and students are encouraged to cooperate on labs. Students may submit work as groups of up to 5 to Gradescope: one person submits then adds the names of their group members to the submission.

See the full policies in the course syllabus.

2 Codepack

The codepack for this exercise is linked at the top of this document. Always download it and unzip/unpack it. It should contain the following files which are briefly described.

File Use Description
QUESTIONS.txt EDIT Questions to answer: fill in the multiple choice selections in this file.
list_main.c EDIT Main routine for linked list application to; edit it to complete for testing
list_funcs.c EDIT Library routine for linked list application to; edit it to complete for testing
Makefile Build Enables make test and make zip
list.h Header Header file for list types and functions
QUESTIONS.txt.bk Backup Backup copy of the original file to help revert if needed
QUESTIONS.md5 Testing Checksum for answers in questions file
test_quiz_filter Testing Filter to extract answers from Questions file, used in testing
testy Testing Test running scripts
test-lab02.org Testing Tests for this lab

3 QUESTIONS.txt File Contents

For a quick overview of work involved with each discussion exercise, refer to the corresponding section in Lab01 which is here.

Below are the contents of the QUESTIONS.txt file for the exercise. Follow the instructions in it to complete the QUIZ and CODE questions for the exercise.

                           _________________

                            LAB02 QUESTIONS
                           _________________





Exercise Instructions
=====================

  Follow the instructions below to experiment with topics related to
  this exercise.
  - For sections marked QUIZ, fill in an (X) for the appropriate
    response in this file. Use the command `make test-quiz' to see if
    all of your answers are correct.
  - For sections marked CODE, complete the code indicated. Use the
    command `make test-code' to check if your code is complete.
  - DO NOT CHANGE any parts of this file except the QUIZ sections as it
    may interfere with the tests otherwise.
  - If your `QUESTIONS.txt' file seems corrupted, restore it by copying
    over the `QUESTIONS.txt.bk' backup file.
  - When you complete the exercises, check your answers with `make test'
    and if all is well, create a zip file with `make zip' and upload it
    to Gradescope. Ensure that the Autograder there reflects your local
    results.
  - IF YOU WORK IN A GROUP only one member needs to submit and then add
    the names of their group.


Linked List Application
=======================

QUIZ Build Commands
~~~~~~~~~~~~~~~~~~~

  After downloading and unzipping the exercise code, TAs will
  demonstrate how to compile the `list_main' application using a
  provided `Makefile' and the command `make'. They will demonstrate how
  to run several other useful commands via `make'. These are as follows:

  To remove all the compiled files (executable programs and `.o' files),
  the use `make' as follows:
  - ( ) make sanitize
  - ( ) make clean
  - ( ) make remove
  - ( ) make gc

  To run ALL the automated tests for the code through the given
  `Makefile' use the following command
  - ( ) make test
  - ( ) make verify
  - ( ) make examine
  - ( ) make unit
  Note: the default is to run all tests and you may need to specify WHAT
  to test, like a quiz, code, or an individual problem.

  To run only test #2 for the CODE portion of the tests and show the
  results, use the following `make' command:
  - ( ) make test2
  - ( ) make test-code 2
  - ( ) make unit test=2
  - ( ) make test-code testnum=2

  If I change code and want to see if any more tests pass after the
  change, I should type
  - ( ) `make' to rebuild followed by `make test' to run tests
  - ( ) `make clean' followed by `make' followed by `make test'
  - ( ) `make test' will rebuild based on changes AND then run tests
  - ( ) ALL of these will work but `make test' is the shortest and
    sweetest.

  Since compiling C programs involving several files is a bit tedious,
  we will provide a `Makefile' on all of the course projects and the
  conventions outlined here will be followed to make life easier.
  Importantly, **passing automated tests will be part of project
  grades** so make sure you know how to run the tests.


Linked List Application
=======================

  This exercise's code pack contains an application featuring a linked
  list. The code is divided into an interactive `main()' function in
  `list_main.c' and a number of application. This application is
  described in some more detail in HW02 which is released this
  week. Refer to HW02 for more information on it.  You are encouraged to
  *study this program carefully* because
  - It demonstrates MANY common and useful techniques in C
  - You will need to write one like it in an upcoming project


QUIZ Header Files
~~~~~~~~~~~~~~~~~

  Examine the Header File `list.h'. Its contents are representative of
  many header files in C programs.

  Which of the following elements appear in the `list.h' header file?
  CHECK ALL THAT APPLY

  - ( ) Declarations / Prototypes for functions showing parameters and
    return value for the functions
  - ( ) Definitions / bodies for the functions which shows what they do
  - ( ) Definitions of standard functions like `printf() / scanf()'
  - ( ) Definitions of the data types (structs) that are used in the
    program


QUIZ list_main Insertion
~~~~~~~~~~~~~~~~~~~~~~~~

  Which of the following commands are the correct way to quickly compile
  all necessary files and run the `list_main' program that is the focus
  of this exercise?
  - ( ) gcc list_main.c; ./list_main
  - ( ) make; ./list_main
  - ( ) make; ./a.out
  - ( ) make test; ./a.out

  Compile and run the `list_main' application on the command line. Feel
  free to experiment but after playing around a bit, restart the program
  and perform the following sequence of insertions followed by a print.
  ,----
  | list> insert Link
  | list> insert Zelda
  | list> insert Ganondorf
  | list> insert Impa
  | list> insert Link
  | ...
  | list> print
  | ...
  `----
  Which of the following is the correct output given by the program for
  how the list is created?
  - ( ) Order A 0: Link 1: Zelda 2: Ganondorf 3: Impa
  - ( ) Order B 0: Link 1: Zelda 2: Ganondorf 3: Impa 0: Link
  - ( ) Order C 0: Ganondorf 1: Impa 2: Link 3: Zelda
  - ( ) Order D 0: Zelda 1: Link 2: Link 3: Impa 4: Ganondorf

  Trace through the code in `list_main.c' to find where insert commands
  are handled. Find the function which does most of the work for
  insertion in `list_funcs.c' and study its code.

  Which of the following techniques is used to determine the order
  elements are inserted into the linked list?
  - ( ) The library function `strcmp()' is used to compare strings and
    insert them in alphabetically sorted order; duplicate strings are
    NOT inserted
  - ( ) The overloaded operators `>' and `==' are used to compare
    strings and insert them in alphabetically sorted order; duplicate
    strings are not inserted
  - ( ) The library function `strcmp()' is used to compare strings and
    insert them in alphabetically sorted order; duplicate strings ARE
    inserted before their previous occurrences
  - ( ) The overloaded operators `>' and `==' are used to compare
    strings and insert them in alphabetically sorted order; duplicate
    strings ARE inserted before their previous occurrences


CODE Edits to Make `list_main.c' and `list_funcs.c'
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  The `list_main' program has several problems that must be corrected to
  complete it. The application will compile and run but produce errors
  during testing.
  ,----
  | > make
  | gcc -Wall -Werror -g  -c list_main.c
  | gcc -Wall -Werror -g  -c list_funcs.c
  | gcc -Wall -Werror -g  -o list_main list_main.o list_funcs.o list.h
  | 
  | > make test-code
  | ./testy test_list_main.org 
  | ============================================================
  | == test_list_main.org : list_main application tests
  | == Running 4 / 4 tests
  | 1)  Print then Exit      : ok
  | 2)  Insert 3 and Print   : FAIL -> results in file 'test-results/list_main-02-result.org'
  | 3)  Get Command          : FAIL -> results in file 'test-results/list_main-03-result.org'
  | 4)  Contains Items       : FAIL -> results in file 'test-results/list_main-04-result.org'
  | ============================================================
  | RESULTS: 1 / 4 tests passed
  `----
  The goal is to correct all the errors to pass all tests and learn
  something about C coding along the way.

  There are 3 overarching problems with the list application.


get command and list_get()
--------------------------

  The builtin `get' command produces some errors. This will require
  editing the associated `list_get()' C function in `list_funcs.c' to
  correct it. The function is missing some bounds checking which cause
  requests for out-of-bounds accesses to crash the application.


list_insert
-----------

  The `list_insert()' function has a problem with its return value which
  causes `main()' to report incorrect results for it.  Read the
  documentation carefully about what this function is intended to
  return. Check these and check that the list_main.c application behaves
  appropriately for the return values as well. Adjust as needed.


list_contains
-------------

  The `contains' command is not implemented which will require adding a
  function to `list_funcs.c' and adding that command to `list_main.c'.
  Start with the `list_contains()' C function which only has a "stub"
  implementation in `list_funcs.c'.
  ,----
  | int list_contains(list_t *list, char *query){
  |   //IMPLEMENT ME
  |   return 0;
  | }
  `----
  You will need to fill in code to complete it according to the
  documentation provided.

  Do not do any printing in `list_contains()' : this is to be done in
  `list_main()' based on the return value received from the function.

  After writing some code in `list_funcs.c', visit the `list_main.c'
  file and add a case there which will allow the `contains xyz' command
  to run and produce output when running `list_main' like the following
  example:
  ,----
  | list> insert Mario
  | list> insert Luigi
  | list> insert Toad
  | list> insert Bowser
  | list> insert Princess
  | list> contains Mario
  | 'Mario' is present
  | list> contains Luigi
  | 'Luigi' is present
  | list> contains Princess
  | 'Princess' is present
  | list> contains Gumba
  | not found
  | list> contains Bob-omb
  | not found
  `----


Testing Your Code
~~~~~~~~~~~~~~~~~

  If all functions are behaving correctly, you should pass all tests as
  shown below.
  ,----
  | > make test-code
  | gcc -Wall -Wno-comment -Werror -g  -c list_main.c
  | gcc -Wall -Wno-comment -Werror -g  -c list_funcs.c
  | gcc -Wall -Wno-comment -Werror -g  -o list_main list_main.o list_funcs.o list.h
  | ./testy test_list_main.org 
  | ============================================================
  | == test_list_main.org : list_main application tests
  | == Running 4 / 4 tests
  | 1)  Print then Exit      : ok
  | 2)  Insert 3 and Print   : ok
  | 3)  Get Command          : ok
  | 4)  Contains Items       : ok
  | ============================================================
  | RESULTS: 4 / 4 tests passed
  `----


Additional Practice
~~~~~~~~~~~~~~~~~~~

  While not part of the exercise requirements, you can practice
  additionally by further extending the list application. All of these
  are likely to follow the same basic structure of 1 or more C functions
  being added to `list_funcs.c' and a corresponding command added to
  `list_main.c'. Note that you will also need to add new function
  prototypes to `list.h' for any new functions so that the compiler is
  aware of them.

  Some possible additions are.
  - `count' which returns the number of items currently in the list
  - `remove_index <N>' to remove a specific list item number;
    e.g. `remove_indx 4' to remove element 4 of the list
  - `remove_item <item>' to remove a specific item by name such as
    `remove_item apple'
  - `drop_from <N>' which deletes all items starting at index `<N>' to
    the end of the list from the list
  - `drop_upto <N>' which deletes items from the beginning of the list
    up to index `<N>'
  - `load <file>' and `save <file>' which read a list from a file or
    store the current file in a list. These will require knowledge of
    C's basic I/O functions which we will study later but will required
    functionality for an upcoming project.

4 Submission

Follow the instructions at the end of Lab01 if you need a refresher on how to upload your completed lab zip to Gradescope.


Author: Chris Kauffman (profk@umd.edu)
Date: 2024-08-29 Thu 14:58