1/9
KIT107 Programming 2023
Assignment 2
Due Date
The assignment is due at 11:55PM Wednesday May 3rd 2023. It is worth 24% of
your mark and you should complete it as an individual.
Background
US citizens love guns. US citizens try to buy guns. Lots of guns. Lots of US
citizens.
But which states try to buy the most? What month is the most popular? What was the
most popular year for trying to buy guns? Which type of guns are the most popular
for aspiring buyers? You’ve been asked to find out the answer to these kinds of
questions!
Specifically, you’ve been asked to show the background checks by category over time
for a given state/territory, draw a kind of histogram illustrating the total gun permit
background check numbers for the country over a given range of years, and determine
the state/territory, month, and year of the highest number of background checks. See
the section entitled Program Specification for details.
Each row of data consists of:
• the year and month (i.e. the period);
• name of the state/territory (i.e. the location);
• number of permit checks made in that month;
• number of checks relating to a handgun;
• number of checks relating to a ‘long gun’, e.g. rifle;
• number of checks relating to ‘other’ types of guns; and
2/9
• number of checks relating to multiple types of gun in the one transaction.
The dataset is organised by period (in chronological order) as rows of data but you
must re-structure the data as you read it in from the file:
• firstly, the collection of background enquiries must be grouped by period and
stored in descending order of year and month (i.e. newest first); and then
• for each combined year and month (i.e. a period), you should build the clusters
of states/territories data stored for that period in alphabetical order of
state/territory name.
You don’t know which years are involved, which months have data, how many
states/territories record enquiries in any month, how many states/territories there are,
or how many background checks (enquiries) there will be.
Task
Based only on the information above (and not what is in the text file or specified after
this point in this document):
a In two–three sentences, explain the functionality required to manage a cluster
of state/territory background check summaries within a period. Which kind
of abstract data type (binary tree, general tree, array, stack, priority queue,
double-ended queue, set, ordered/unordered list, etc.) is most appropriate for
that functionality?
b Which underlying data structure (array or linked-list) will you use as a basis to
model the cluster of state/territory background check summaries within a
period? In two–three sentences, justify your answer.
c In two–three sentences, explain the functionality required to manage a
collection of periods of clusters of state/territory background check
summaries). Which kind of abstract data type (binary tree, general tree, array,
stack, priority queue, double-ended queue, set, ordered/unordered list, etc.) is
most appropriate for that functionality?
d Which underlying data structure (array or linked-list) will you use as a basis to
model the checks (i.e. the collection of periods of clusters of state/territory
background check summaries)? In two–three sentences, justify your answer.
From this, the whole collection could be defined as a global variable as follows:
collection the_collection;
To implement this you would need to define a type called period_format to
implement your answer to (b) above to represent the cluster of state/territory
background check summaries for a period, and also another type (called
collection_format) to implement your answer to (d) above to create a
collection of period_formats.
3/9
Each of these two types (period_format and collection_format) can be
defined as either an array or as a linked-list. Given the linked-list node from
lectures:
struct node_int;
typedef struct node_int *node;
struct node_int
{
void *data;
node next;
};
you would either define period_format as a linked-list, i.e.
typedef node period_format;
or you would define it as a dynamic array1, i.e.
typedef check *period_format;
Similarly, you would either define collection_format as a linked-list, i.e.
typedef node collection_format;
or as a dynamic array, i.e.
typedef periods *collection_format;
Within the given program files, as with node above, each type (check, periods,
and collection) is defined in the format we’ve used in lectures. For example, for
a background check summary — check — the header file, check.h, has a forward
declaration of the type’s internals and also a pointer:
struct check_int;
typedef struct check_int *check;
together with function declarations for the available functions. The source file,
check.c, has the definition of the internals of the type:
struct check_int {
char *date;
char *location;
int permit;
1 It would probably be more intuitive to define it as a static array, e.g.
typedef check period_format[200];
but unfortunately this presents problems when trying to return a period_format value from a
function — C won’t allow an array to be returned — and so we’ll keep it ‘simple’ and instead define
period_format as a pointer, and use malloc() to create the array and its elements.
4/9
int hand_gun;
int long_gun;
int other;
int multiple;
};
together with function definitions for the available functions on a background check
summary.
A Visual Studio project is available on MyLO for you to download and use as a
starting point. (If you are not using Visual Studio, then just grab the source files and
data file from within the folder and use them with your chosen compiler — you don’t
have to use Visual Studio.)
A data file is included which contains the required data — this is just a text file which
can be opened and read with most applications. (The code to read this into your
program has been provided in assig_two123.c.)
This starting point comprises the following files:
• node.h and node.c — the Node ADT from lectures as the building blocks
for linked lists (should you need them). These files are complete;
• check.h and check.c — the Background Check summary ADT as
specified above. These files are complete;
• periods.h and periods.c — the Periods ADT (a cluster of background
checks) as described above. These files are incomplete;
• collection.h and collection.c — the Collection ADT (a collection
of periods) as described above. These files are incomplete;
• assig_two123.c — the file which contains the main() function, a
function to read the background checks in from the text file, and the
the_collection global variable. This file is complete.
You must complete periods.h, collection.h, periods.c, and
collection.c. You cannot alter any provided code.
Start by adding the period_format and collection_format type
definitions to periods.h and collection.h (respectively) as indicated above
according to your choices in (b) and (d).
Then, complete the missing functionality from periods.c and collection.c.
I suggest a staged approach:
1. build the collection by period (with only one background check for each
period), printing it as you go. When you are happy that this works — i.e.
when you are seeing the periods printed in descending order and without
duplicates…
2. build the collection for each period adding all background checks for that
period, printing it as you go. When you are happy that this works — i.e. when
you are seeing the background checks printed within the period in alphabetical
order of state/territory…
5/9
3. build the remaining functions, one at a time, using the nested framework of
while loops that you’ve built in stages 1 and 2.
Program specification
First you must obtain the background checks from a text file. The data must be stored
in appropriate collections. At the top level there will be a collection of periods (which
comprise the collection) in descending order of year and month, and for each period
there should be a cluster of background checks (stored in alphabetical order of
state/territory name).
Once the data have been read in and stored in the collections, the following should
occur:
i. The user should enter a (case-sensitive) string representing a state/territory’s
name (shown below in bold italics).
The collection should be searched for that state/territory with details of each
background check summary displayed as well as the total number of
background checks for the state/territory. For example:
1. Background Checks by US State/Territory
------------------------------------------
Enter location to search for: Hawaii
- In Hawaii during 2023-02 there were 1722 permit, 0 handgun, 0 long-gun, 0 other, and 0 multiple gun background check(s).
- In Hawaii during 2023-01 there were 1847 permit, 0 handgun, 0 long-gun, 0 other, and 0 multiple gun background check(s).
- In Hawaii during 2022-12 there were 1559 permit, 0 handgun, 0 long-gun, 0 other, and 0 multiple gun background check(s).
- In Hawaii during 2022-11 there were 1418 permit, 0 handgun, 0 long-gun, 0 other, and 0 multiple gun background check(s).
- In Hawaii during 2022-10 there were 1619 permit, 0 handgun, 0 long-gun, 0 other, and 0 multiple gun background check(s).
…
- In Hawaii during 1998-12 there were 374 permit, 1 hand-gun,
28 long-gun, 0 other, and 0 multiple gun background check(s).
- In Hawaii during 1998-11 there were 27 permit, 0 hand-gun,
1 long-gun, 0 other, and 0 multiple gun background check(s).
Total checks for Hawaii: 287659
And:
1. Background Checks by US State/Territory
------------------------------------------
Enter location to search for: Australia
Total checks for Australia: 0
ii. The user should enter two integers for the starting and ending values in a range
of years (shown below in italics). If the ending value is less than the starting
value then the values should be swapped.
6/9
A kind of horizontal histogram should then be shown which illustrates the
number of background checks in each month of the range. Each line should
contain the period, the number of background checks (all categories) on the
list for that year, and a row of asterisks (*) indicating the number— one
asterisk should be displayed for every 5000 background checks. For example:
2. Permit Background Checks by Year
-----------------------------------
Enter start year: 2003
Enter end year: 2009
2009-12 369765 | ************************************************
*************************
2009-11 355654 | ************************************************
***********************
2009-10 384929 | ************************************************
****************************
2009-09 361114 | ************************************************
************************
2009-08 383627 | ************************************************
****************************
…
2003-03 134018 | **************************
2003-02 119080 | ***********************
2003-01 121650 | ************************
And:
2. Permit Background Checks by Year
-----------------------------------
Enter start year: 1965
Enter end year: 1985
iii. Details of the period and location with the highest total number of background
checks should be displayed. For example:
3. Highest Background Check
---------------------------
Highest background check EVER: In North Carolina during 2014-03 there
were 522188 permit, 1054 hand-gun, 13571 long-gun, 528 other, and 227
multiple gun background check(s).
And:
3. Highest Background Check
---------------------------
No background check data!
For all of the above tasks, the formatting of your output should conform to the (linewrapped) examples shown — with the exception that some lines have been removed
from the above examples and replaced with “…”.
7/9
You may find the following functions useful (not an exhaustive list): malloc(),
strcmp(), strncat(), and atoi().
Program Style
The program you write for this assignment must be contained in nine files as follows:
• node.h and node.c — for nodes of linked lists (if relevant);
• check.h and check.c — for managing a background check summary;
• periods.h and periods.c — for managing periods (a month within a
year), i.e. clusters of background check summaries;
• collection.h and collection.c — for managing the collection of
periods;
• assig_two123.c — the main algorithm which reads the data, and
controls the management of the collection and the calling of the functions
which complete the three tasks from the previous section.
No function that you write should be longer than a screen-full of code. You cannot
change any distributed code.
Your program should follow the following coding conventions:
• const variable identifiers should be used as much as possible, should be
written all in upper case and should be declared before all other variables;
• #defined symbols should only be used for constant values if const is
inappropriate, for example the size of an array.
• global variables should be used sparingly with parameter lists used to pass
non-global information in and out of functions. (You do not need to add any.)
• local variables should only be defined at the beginning of functions and their
identifiers should start with a lower-case letter;
• identifiers should be meaningful but may be expressed in
traditional_c_style or in camelCase;
• every if and if-else statement should have a block of code (i.e.
collections of lines surrounded by { and }) for both the if part and
the else part (if used) ;
• every do, for, and while loop should have a block of code (i.e. {}s)
• the keyword continue should not be used;
• the keyword break should only be used as part of a switch statement;
• opening and closing braces of a block should be aligned;
• all code within a block should be aligned and indented 1 tab stop (or 4 spaces)
from the braces marking this block;
• commenting:
o There should be a block of header comment which includes at least
file name
student name and student identity number
a statement of the purpose of the program
date
o Each variable declaration should be commented;
o There should be a comment identifying groups of statements that do
various parts of the task; and
8/9
o Comments should describe the strategy of the code and should not
simply translate the C into English.
What and how to submit
You should submit periods.h, collection.h, periods.c, and
collection.c. If you wish, you may submit the entire project (as a ZIP file). Do
not submit a RAR archive — it will not be marked.
You may also submit an additional text file containing your answers to tasks (a)–(d),
or you may include your answers as comments in periods.h and/or
collection.h.
You should submit the files to the “Assignment 2” assignment drop-box on KIT107’s
MyLO site.
Marking scheme
Task/Topic Maximum
mark
Design
ADTs chosen wisely and justified 4
Data structures correct and justified 4
Program operates as specified
periods.c
• init_period() 1
• get_checks() 1
• set_checks() 1
• add_check_to_period()
o Added in alphabetical order by state/territory 2
collection.c
• init_collection() 1
• get_period() 1
• set_period() 1
• add_check_to_collection()
o The first background check for the collection 1
o The first background check for a new period 1
o Adding a background check to an existing period 1
o Maintain descending order of period 2
• breakdown_by_period()
o With title 1
o Getting Input 1
o Swapping values if required 1
o Correct range 1
o Correct Data 1
o Correct *s 2
• print_date()
o Showing title 1
o Input 1
o Finding and showing background check details 2
o Accumulating and showing total background checks 1
• highest_ever()
o Showing title 1
9/9
o Answer found, and shown, including no data 1
o Response provided if dataset is empty 1
Program Style
Does not unnecessarily repeat tests or have other redundant/confusing code 4
Uses correctly the C naming conventions 4
Alignment of code and use of white space makes code readable 4
Always uses blocks in branch and loop constructs 4
Meaningful identifiers 4
Variables defined at the start of functions only 4
Header comments for the program (author, date etc) 4
Each variable declaration is commented 4
Comments within the code indicate the purpose of sections of code (but DO NOT just
duplicate what the code says)
4
The program will be marked out of 72.
Plagiarism and Cheating:
Practical assignments are used in the School of ICT for students to both reinforce and
demonstrate their understanding of material which has been presented in class. They
have a role both for assessment and for learning. It is a requirement that work you
hand in for assessment is substantially your own.
Working with others
One effective way to grasp principles and concepts is to discuss the issues with your
peers and/or friends. You are encouraged to do this. We also encourage you to discuss
aspects of practical assignments with others. However, once you have clarified the
principles, you must express them in writing or electronically entirely by yourself. In
other words: you must develop the algorithm to solve the problem and write the
program which implements this algorithm alone and with the help of no one else
(other than staff). You can discuss the problem with other students, but not how to
solve it.
Cheating
• Cheating occurs if you claim work as your own when it is substantially the
work of someone else (including online systems).
• Cheating is an offence under the Ordinance of Student Academic Integrity
within the University. Furthermore, the ICT profession has ethical standards
in which cheating has no place.
• Cheating can involve two or more parties.
o If you allow written work, computer listings, or electronic version of
your code to be borrowed or copied by another student you are an
equal partner in the act of cheating.
o You should be careful to ensure that your work is not left in a situation
where it may be stolen by others.
• Where there is a reasonable cause to believe that a case of cheating has
occurred, this will be brought to the attention of the unit lecturer. If the
lecturer considers that there is evidence of cheating, then no marks will be
given to any of the students involved. The case will be referred to the Head of
the School of ICT for consideration of further action.
Julian Dermoudy, April 7th 2023.