CSCI 2021 Lab02: Basic C Application Coding

                           __________________

                            LAB 02 QUESTIONS
                           __________________





Lab Instructions
================

  Follow the instructions below to experiment with topics related to
  this lab.
  - 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 lab 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.


CODE for Linked List Application
================================

  This lab'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

  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.tmp'
  | 3)  Get Command          : FAIL -> results in file 'test-results/list_main-03-result.tmp'
  | 4)  Contains Items       : FAIL -> results in file 'test-results/list_main-04-result.tmp'
  | ============================================================
  | 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.


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

  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 lab 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.