Computer Programming Assignment V - Linked Lists

Transcription

1 Computer Programming Assignment V - Linked Lists Version 2.00 Contents 1 Intro Concept Interface Definitions Structures Functions Contract s Structures animal t region list t region t animal list t Contract s Functions add region get region list free region list add animal get sorted animals free animal list update animal rarity get dangerous regions reset Skeleton.c file List Roots main funcion Testing your implementation

2 1 Intro This assignment is designed to improve and test your knowledge in the C programming language in general, and specifically your understanding of the concept of linked lists as shown in class and implemented in C. 1.1 Concept Some generic, unknown animal protection organization (henceforth u.a.p.o) requested that you implement a simple data structure that will hold information about the condition of various animals in different regions in the world. This data structure must support various queries that will allow the users to keep track about the current situation, as well as updates that will allow u.a.p.o users to feed information about new events (such as animal deaths, new spottings, etc.). 2 Interface Definitions u.a.p.o supplies you with a contract - the contract is the interface of the program, as they require it. By implementing this interface, it is guranteed that u.a.p.o s users will be able to use your database correctly, by following the specifications appearing in the document which you ll implement. The contract lists all the demands from your application. You should follow it in an exact manner, as detailed further in this section. The contract has 2 parts - the first is this document, describing exactly what needs to be implemented, while the other is a skeleton.c containing all basic structure definitions and prototypes for the required functions. 2.1 Structures The skeleton.c file already contains the definitions of every one of the required structures. You MUST NOT change those definitions in any manner. You are allowed to add as many additional structures as you please. This Document contains a short explanation about each structure and its fields. Some of the query functions in the interface will require you to return pointers to structures. Users are NOT allowed to manipulate the data in the database directly (meaning other then via the update functions), so those pointers can t be to elements inside the database (otherwise, a user could change a structure pinpointed by his pointer, and thus change the structure in the database). In order to avoid this, You ll need to allocate new lists of structures and fill them, returning a pointer to their roots. 2

3 2.2 Functions The skeleton.c file contains the prototypes of required function - you MUST NOT change those prototypes. You may add as many other functions as you please. This Document contains a short explanation about each function, in the following manner: Function name Function Prototype Short description Inputs - short description + restrictions (if such exist) Outputs - short description. Possible scenario - this will appear only for some of the functions. It will show a possible scenario by which a user will use the given function (should be seen as an example of a possible use). All information under inputs other then the funtion s description is part of the restrictions for the user s input. You may assume all the restrictions are held - you are not responsible for testing input correctness; wrong inputs are user s responsibility. All functions returning pointers should return COPIES of data - you should never return actual pointers to data held in your program s database. A user must be able to manipulate such returned pointers with no side effect on data stored (which will not be the case if you ll return pointers to your own linked lists). The only method by which a user should be able to manipulate the database is by using functions described in this contract. 3

4 3 Contract s Structures 3.1 animal t This structure contains the basic definition of an animal. It contains the animal s name and a pointer to list of all regions currently (or previously) containing the animal. typedef struct animal s { char* name; region list t* regions; } animal t; 3.2 region list t This strucutre is a list-cell implementation for regions. Each cell contains the usual listcell fields (a next pointer to next list-cell and a pointer to the contents of the cell) and an additional field called rarity. This list has 2 uses - Either as a generic region list or a list of regions a specific animal inhabits (or inhabited). If used generically, all rarity values should be set to 1. If used to list the regions a given animal inhabits, rarity will tell about the animal s abundance in the that cell s region (the region pointed by that cell). Rarity can then have a value in the range of 0-10, where 10 means very abundant and 0 means extincted. Notice: when used as region-lists of a given animal, these kind of lists can only grow. If a given animal which could have been previously found in a region (meaning it was in its list of regions) can no longer be found there, the region should stay in the animal s list, and its rarity value should be updated to 0. typedef struct region list s { struct region list s* next; region t* region; int rarty; } region list t; 3.3 region t A region is a strap of land which can be the habitat of various animals. Each region has a name and a list of all animals which can be found in it. typedef struct region s { char* name; animal list t* animals; } region t; 4

5 3.4 animal list t This structure is list-cell implementation for animals. Each cell contains the usual list-cell fields (a next pointer to next list-cell and a poiner to the contents of the cell). Notice: if used as a list of animals inhabiting a given region, animals can be removed from the list - when an animal can no longer be found in a region (i.e. it becomes extinct there), it should be removed from that region s animal list. typedef struct animal list s { struct animal list s* next; animal t* animal; } animal list t; 5

6 4 Contract s Functions 4.1 add region Prototype int add region(char* name) Description Adds a new region to the data base. Inputs name - the name of the region. User is responsible to make sure that the new region s name differs from all existing regions names. Output function returns 1 upon success, 0 otherwise. 4.2 get region list Prototype region list t* get region list() Description Returns a pointer to a list of all existing regions. The region s pointers should be set to NULL (you must prevent the user from being able to access any information about animals via this list, meaning it the resulting list should not point to any animal t). All rarities should be set to -1. Inputs None Output a pointer to the required list, Null if an error occurs. Remember: This should return a new copy of the data; the user shouldn t be able to manipulate your data structures by writing to his recieved list. Possible scenario After adding Africa, Asia and Australia as regions using add region, the user requests a region list using this function. User should recieve a linked list containing Africa, Asia and Australia (order doesn t matter). 4.3 free region list Prototype int free region list(region list t* list) Description frees all memory allocated to a region list recieved via [4.2], [4.8]. includes memory allocated for region list t and region t structures. This Inputs list - pointer to a region list that needs to be freed. Output function returns 1 upon success, 0 otherwise. Notice [4.2], [4.8] need not allocate animal t structures (all animal pointers are NULL in those lists), so it s unlikely you ll free such here. 6

7 4.4 add animal Prototype int add animal(char* name, region list t* regions) Description Adds a new animal to the database, in one or more regions. Inputs name - the name of the newly defined animal. Animals with this name can t already be in the database (user s responsibility). regions - region list. Animal should be added to every region in the list which has rarity 1. All rarities in the list should be either -1, meaning animal shouldn t be added to those regions, or in range of 1-10 (new animals can t be added in extinct form). The region list must contain at least one region with a positive rarity. Output function returns 1 upon success, 0 otherwise. Possible scenario - Assume User wants to add a new animal Rabbit to the database, with rarity 9 in Africa and 8 in Europe. Assume User has previously added both Africa and Europe to the database using [4.1]. User gets a list of all regions via [4.2]. He then changes the rarity values in that list in the cells correponding to Africa from -1 to 9 and for Europe from -1 to 8. User then passes the modified list as an argument for this function, together with the new animal s name Rabbit ; 7

8 4.5 get sorted animals Prototype animal list t* get sorted animals(char* region name) Description returns an animals list with all animals that can be found in a given region, in descending rarity (beginning with most common). Region pointers for all animals should be set to NULL (user shouldn t be able to access regions via this list). Inputs region name - name of the region from which to retrieve the animal list. The region must exist. Output pointer to the animal s list. Remember: This should be a new copy of the data; the user shouldn t be able to manipulate your data structures by writing to his recieved list. Possible scenario after adding elephant with rarity 2 to Africa, and zebra with rarity 6 in Africa, the user asks for a a sorted animal list of Africa using this query. He should recieve an animal list containing both elephant and zebra, and the zebra should appear first in the list (due to it being more common in Africa). Notice animals which became extinct in a given region can t be found there no more, therefore they shouldn t appear in this list. Remember high rarity values means animal is common. Therefore animals with higher rarity comes first. 4.6 free animal list Prototype int free animal list(animal list t* animals) Description Frees all memory allocated to an animal list retrieved via [4.5]. This includes all memory allocated for animal list t, animal t structures. Inputs animals - pointer to a list of animals. Output function returns 1 upon success, 0 otherwise. Notice [4.5] shouldn t allocate region list t structures, so you probably won t free such here. 8

9 4.7 update animal rarity Prototype int update animal rarity(char* animal name, char* region name, int rarity) Description Updates an animal s rarity in a given region. Notice that the change might result in an animal becoming extinct in the region, or the addition of a new animal which couldn t have been previously found in the region. (can even make an animal which was thought to be extinct in the region present there). Inputs animal name - name of the animal whose rarity needs to be changed. region name - name of the region in which the rarity of the animal needs to be changed. rarity - a new valid rarity: can be in range of 1-10 or 0 (meaning it is now extinct). Output 1 if the update is successful, 0 otherwise. Remember extinct animals differ from animals that could never have been found in a region - [4.8] is affected by the difference. 4.8 get dangerous regions Prototype region list t* get dangerous regions() Description returns a list of regions, in an ascending order by number of extincted animals in the region. Inputs None Output a pointer to a list of regions. Rarities should be set to -1, region s animal pointers should be set to Null. Possible scenario Assume User added the regions Africa and Australia. In Africa, Quagga and Western black rhino are extinct while in Australia Thylacine is extinct. By using this function, User should recieve a region list containing both Africa and Australia, and Africa should come last (since it has the largest number of extincted animals). 9

10 4.9 reset Prototype void reset() Description frees all dynamically allocated memory, resets all initial values. after reset should behave exactly like starting the program anew. All work Inputs None Outputs None 10

11 5 Skeleton.c file 5.1 List Roots In your database you will keep information in various linked list (will be later defined in this document). The skeleton.c file contains root pointers that might help you to hold those linked list (You will probably have to anchor the lists to something, and those pointers could be used exactly for that). Those pointers are not part of the interface - you may or may not use them to your discretion (you re allowed to remove them, add additional root pointers, etc.). 5.2 main funcion Since you re implementing a contract, your main function won t be tested - there is no menu you need to implement. You can use your main to test your implementation (the HOWTO will be explained later on), but when submitting the work make sure your main is the same as the one defined in the skeleton.c file: int main(int argc, char argv[]){ return 0; } 5.3 Testing your implementation Since there is no menu, and your implementation will recive no inputs from users in the normal sense (all inputs will be added via the contract s function), there will be no input/output files made that you can test your work with. Instead, you will be supplied with testcases: small sections of code, each with its own required output. The skeleton.c file will contain auxillary print functions. To use a given testcase, simply copy its code into your main. The testcase will perform several calls to functions you ll need to implement and then print some of the data it recieved on the screen using the auxillary print functions. For each test case there will be an associated output file, which is the correct output that testcase should produce; Your implementation should output exactly the same output as the correct output file (you can compare this using the usual text-diff tools seen in the labs). Notice - DO NOT change the auxillary printing functions. If you recieve bad output, find the error in your code and correct it; don t fix it by changing the printing functions. animal list t* animal; add region( Africa ); animal=get sorted animals( Africa ); printf( [Animals] ); print animal list(animal); printf( \n ); [Animals] Animals: NULL An example of a possible testcase code (left) and correct output (right) 11