(P) Theatre¶

Goal: I will revise how to read STL containers, iterators and files.

I will especially practice choosing the correct data structure among the different data structures of STL. I will possibly practice using classes.

You have two choices in implementing the exercise:

You can use classes, whereupon the necessary STL structures will most probably be simpler, but they are still needed. Suitable candidates for class would be Theatre (in files theatre.hh and theatre.cpp) or Play (in files play.hh and play.cpp). You can implement either of these classes or both of them. If you use classes, they must reasonable and useful (see Style issues at Object-oriented programming from round 4).
You can use STL container without classes. Now you most probable need more STL containers as elements of other STL containers.

Instructions: Retrieve the code template: templates/07/theatre/ -> student/07/theatre/. The code template mainly provides you an implementation for such a split function that can handle quote marks in proper way.

Implement a program that reads the play collection data of different theatres from a file at startup, stores them in a suitable data structure and gives the user the opportunity to search the data structure in question.

Important

Before starting to write code, read carefully the whole assignment. Especially, note the points Implementing the program in parts (required commits) and Special requirements.

From the point Evaluation note especially that the program must first pass all automated test. Otherwise the work will not be evaluated by assistants, and no points will be given.

Note

This project can be done either in pairs or independently. If you do the project in pairs, you need to form a group. If you have not created a group yet or you wish to change your working partner, choose ”Form a group” from the menu on the left to register a new group. In addition, the submission box at the very end of the current page shows two choices: “Submit alone” / “Submit with…”. You should be careful when selecting the choice, because you cannot change it afterwards. Enter only the address of the Git repository owned by either of you (not both) in the submit box. The code files must contain (in comments) the personal data of both of you.

You can look for a group via Kooditorio’s Discord link (see Timetable & links).

Header comment and feedback language¶

In the same way as in the first project, the header comment is again required. This time we provide no ready-made header comment, but you should write it by yourself. You can use the first project’s assignment as an example (see 4.5 (P) Checkers).

The feedback language will be chosen in the submission box (at the very end of this page). By default, the feedback language is Finnish, but you can change it, if you want to have the feedback, given by an assistant, in English. We will use the language you have given in the submission box of the final submission.

If you are working in pairs, add personal data of both of you.

The data handled by the program¶

We would now like to take a look at the following information on plays in different theatres:

Helsinki
    KOM-teatteri
        Rikkaruoho
            Vilma Melasniemi 10
            Juho Milonoff    4
            Niko Saarela     none
        Nukkekoti/A doll's house
            Aleksi Holkko    30
            Niko Saarela     40
            Vilma Melasniemi 43
        The Pimpsons
            Lotta Kaihua     40
            Ria Kataja       none
    Suomen Komediateatteri
        Viimeinen illuusio
            Janne Kataja     28
            Kiti Kokkonen    17
            Joni Pakanen     23
            Katja Lappi      22
        Ilta pilalla
            Ria Kataja       34
            Kiti Kokkonen    5
Tampere
    Tampereen Teatteri
        Piaf
            Annuska Hannula  7
            Pia Piltz        34
            Arttu Ratinen    2
        Anastasia
            Pia Piltz        1
            Sinikka Sokka    4
            Elina Rintala    3
            Arttu Ratinen    none
        Klaani
            Matti Hakulinen  6
            Eeva Hakulinen   8
            Elina Rintala    7
            Tommi Raitolehto 2
    Tampereen Tyovaen Teatteri
        Saituri/Miser
            Samuli Muje      34
            Auvo Vihro       23
        Evita
            Maija Rissanen   2
            Lari Halme       3
Pori
    Porin Teatteri
        Evita
            Heidi Rantakeisu 7
            Maria Pere       none
        Idan pikajunan arvoitus/Murder on the Orient Express
            Janne Turkki     8
            Maria Palmu      none
            Maria Pere       none

The data you see above can be presented as a csv file with lines formatted like this:

<town>;<theatre>;<play>;<player>;<number_of_free_seats>

where <number_of_free_seats> can be a positive integer or a literal string ”none”.

You can assume that <town> consists only of one word. Instead, <theatre>, <play>, and <player> may consist of several words. If there are several words, the user can give them enclosed with quotes, which can be seen in the example execution later. (However, you need not care about quotes, since the code template provides you a split function for this purpose.)

You can also assume that a play cannot have several players with the same name.

Besides an actual name, a play may have also another name (alias). Most often the actual name is the name of the play in Finnish, and the alias is its English counterpart. In such case, these two names have been separated by a slash ('/').

So, as an input file, the example from above looks like this:

Helsinki;KOM-teatteri;Rikkaruoho;Vilma Melasniemi;10
Tampere;Tampereen Teatteri;Piaf;Pia Piltz;34
Helsinki;KOM-teatteri;Rikkaruoho;Juho Milonoff;4
Pori;Porin Teatteri;Evita;Heidi Rantakeisu;7
Helsinki;Suomen Komediateatteri;Viimeinen illuusio;Kiti Kokkonen;17
Helsinki;KOM-teatteri;Rikkaruoho;Niko Saarela;none
Tampere;Tampereen Teatteri;Piaf;Annuska Hannula;7
Helsinki;KOM-teatteri;Nukkekoti/A doll's house;Niko Saarela;40
Tampere;Tampereen Teatteri;Anastasia;Sinikka Sokka;4
Helsinki;KOM-teatteri;The Pimpsons;Lotta Kaihua;40
Pori;Porin Teatteri;Idan pikajunan arvoitus/Murder on the Orient Express;Maria Palmu;none
Helsinki;KOM-teatteri;The Pimpsons;Ria Kataja;none
Helsinki;Suomen Komediateatteri;Viimeinen illuusio;Janne Kataja;28
Tampere;Tampereen Teatteri;Klaani;Matti Hakulinen;6
Helsinki;Suomen Komediateatteri;Viimeinen illuusio;Joni Pakanen;23
Pori;Porin Teatteri;Evita;Maria Pere;none
Helsinki;Suomen Komediateatteri;Viimeinen illuusio;Katja Lappi;22
Helsinki;Suomen Komediateatteri;Ilta pilalla;Ria Kataja;34
Tampere;Tampereen Teatteri;Klaani;Elina Rintala;7
Helsinki;Suomen Komediateatteri;Ilta pilalla;Kiti Kokkonen;5
Tampere;Tampereen Tyovaen Teatteri;Saituri/Miser;Samuli Muje;34
Tampere;Tampereen Teatteri;Piaf;Arttu Ratinen;2
Tampere;Tampereen Teatteri;Anastasia;Pia Piltz;1
Pori;Porin Teatteri;Idan pikajunan arvoitus/Murder on the Orient Express;Janne Turkki;8
Tampere;Tampereen Teatteri;Anastasia;Elina Rintala;3
Tampere;Tampereen Teatteri;Anastasia;Arttu Ratinen;none
Helsinki;KOM-teatteri;Nukkekoti/A doll's house;Aleksi Holkko;30
Tampere;Tampereen Teatteri;Klaani;Eeva Hakulinen;8
Pori;Porin Teatteri;Idan pikajunan arvoitus/Murder on the Orient Express;Maria Pere;none
Tampere;Tampereen Teatteri;Klaani;Tommi Raitolehto;2
Tampere;Tampereen Tyovaen Teatteri;Saituri/Miser;Auvo Vihro;23
Helsinki;KOM-teatteri;Nukkekoti/A doll's house;Vilma Melasniemi;43
Tampere;Tampereen Tyovaen Teatteri;Evita;Maija Rissanen;2
Tampere;Tampereen Tyovaen Teatteri;Evita;Lari Halme;3

There are five fields on each line, and none of the fields can be empty or filled with spaces only. The last field must be a string presenting a positive integer or the word ”none”. (You can consider that none means 0 as the number of free seats, but you can assume that the input file never has 0, but in the place of zero there is always the text none).

Please note that the lines of the csv file do not have to be in a certain order. Also, the input file does not use Scandinavian letters.

Even if the number of free seats occurs after a player, it concers the play in question. The last given number for each play is always the valid one. For example in the play Miser (Saituri) the number is first 34 (with the player Samuli Muje), and after that the number is 23 (with the player Auvo Vihro). Therefore, the final number of free seats is 23.

The program in action¶

When the program starts up, it reads the name of the input file from the user:

Input file: theatres.txt

If it cannot open the input file in a readable mode, the program will print the text:

Error: input file cannot be opened

After that, the program terminates with no other prints with the return value EXIT_FAILURE.

If the input file can be opened but the file does not correspond to the definition, for example, a field is totally missing or one field is missing a value, the program prints the error message shown below and terminates with the return value EXIT_FAILURE. For example, if the first line in the input file shown above was:

Helsinki;KOM-teatteri;Rikkaruoho;10

or:

Helsinki;KOM-teatteri;Rikkaruoho;;10

or:

Helsinki;KOM-teatteri;Rikkaruoho;   ;10

the program would print:

Error: empty field in line 1

As can be seen, the error message gives also a line number, and thus, you shall count the lines of the input file.

The program analyzes the file lines it has read and stores the book information from different libraries into a suitable data structure. The programmer can freely choose the data structure, as long as it follows all the additional conditions mentioned at Special requirements below.

After the file has been read, the program starts its actual operation. Every time it expects input from the user, it prints the command prompt the> (and a space) at the beginning of the line as follows:

the>

After that prompt, the user can give the following commands:

quit - The program terminates with the return value EXIT_SUCCESS without printing anything.
theatres - Prints all the known theatres in alphabetical order, one below the other, for example:
the> theatres
KOM-teatteri
Porin Teatteri
Suomen Komediateatteri
Tampereen Teatteri
Tampereen Tyovaen Teatteri
the>
plays - Prints, one below the other, all the plays in alphabetical order. Even if an identical play could be found from several theatres, its name shall be printed only once. If a play has an alias, it is also printed (*** as a separator) as follows:
the> plays
Anastasia
Evita
Idan pikajunan arvoitus *** Murder on the Orient Express
Ilta pilalla
Klaani
Nukkekoti *** A doll's house
Piaf
Rikkaruoho
Saituri *** Miser
The Pimpsons
Viimeinen illuusio
the>
theatres_of_play <play> - The command prints all the theatres that offer the given play. Theatres shall be printed in alphabetical order based on their names:
the> theatres_of_play "Ilta pilalla"
Suomen Komediateatteri
the> theatres_of_play Evita
Porin Teatteri
Tampereen Tyovaen Teatteri
the>
The above example shows how to use quote marks, if the the name of the play consists of several words. Even if the name consisted only of a single word, you could use quotes. For example, the commands theatres_of_play Evita and theatres_of_play "Evita" have the same output.

The command allows both the actual name of the play or its alias, but not a combination of them:
the> theatres_of_play Saituri
Tampereen Tyovaen Teatteri
the> theatres_of_play Miser
Tampereen Tyovaen Teatteri
the> theatres_of_play Saituri/Miser
Error: unknown play
the>
Moreover, a play cannot be found with a part of its name, but you must give the whole name or the whole alias. More information about error messages will be given in the next section called Errors.
plays_in_theatre <theatre> - The command prints the plays of the given theatre in alphabetical order:
the> plays_in_theatre "Tampereen Teatteri"
Anastasia
Klaani
Piaf
the>
plays_in_town <town> - The command prints those plays in the given town that has free seats. If a play has an alias, it is also printed (--- as a separator). The print first follows alphabetical order based theatres, and the plays in the same theatre shall be printed in alphabetical order based on the name of the play. The number of free seats is printed as well:
the> plays_in_town Helsinki
KOM-teatteri : Nukkekoti --- A doll's house : 43
Suomen Komediateatteri : Ilta pilalla : 5
Suomen Komediateatteri : Viimeinen illuusio : 22
the>
If the given town has no plays with free seats, the program prints the message:
the> plays_in_town Pori
No plays available
the>
players_in_play <play> [<theatre>] - The command prints players in the given play. There can be identical plays in different theatres, and thus, the command allows theatre name as an optional parameter. If the theatre is given, the command prints the players of the play only from the given theatre. If no theatre is given, the players of the play are printed from all theatres, from which the given play can be found. Anyway, the command first prints the name of a theatre and after that the name of an player in a way shown below. The print first follows alphabetical order based on theatres, and players in the same theatre are printed in alphabetical order based player’s forenames. For example:
the> players_in_play Evita "Tampereen Tyovaen Teatteri"
Tampereen Tyovaen Teatteri : Lari Halme
Tampereen Tyovaen Teatteri : Maija Rissanen
the> players_in_play Evita "Porin Teatteri"
Porin Teatteri : Heidi Rantakeisu
Porin Teatteri : Maria Pere
the> players_in_play Evita
Porin Teatteri : Heidi Rantakeisu
Porin Teatteri : Maria Pere
Tampereen Tyovaen Teatteri : Lari Halme
Tampereen Tyovaen Teatteri : Maija Rissanen
the>
A play can be searched with its actual name or with its alias, in the same way as with the command theatres_of_play:
the> players_in_play Saituri
Tampereen Tyovaen Teatteri : Auvo Vihro
Tampereen Tyovaen Teatteri : Samuli Muje
the> players_in_play Miser
Tampereen Tyovaen Teatteri : Auvo Vihro
Tampereen Tyovaen Teatteri : Samuli Muje
the> players_in_play Saituri/Miser
Error: unknown play
the>

After completing the user’s command, the program prints the prompt once again. It will continue printing the prompt until the user gives the command quit.

Errors¶

If the user input has an error, the program prints the relevant error message, and after that, returns to waiting for user input. In other words, the execution of the program does not end if the user input contains errors.

After the user gives an unknown command, the program prints the following error message:

the> xx
Error: unknown command
the> xx yy
Error: unknown command
the>

If the user gives the command the wrong amount of parameters, the program prints the following error message:

the> plays KOM-teatteri
Error: wrong number of parameters
the>

Commands theatres_of_play and players_in_play receive a play name as a parameter. If the given play cannot be found, the program prints the error message:

the> theatres_of_play xx
Error: unknown play
the> players_in_play xx
Error: unknown play
the> players_in_play xx "Porin Teatteri"
Error: unknown play
the>

However, if the latter parameter (a theatre) of the latter command (players_in_play) cannot be found, the program prints the error message:

the> players_in_play xx yy
Error: unknown theatre
the> players_in_play Evita yy
Error: unknown theatre
the>

In other words, if the user gave an optional parameter, it must be an existing theatre. This (the presence and validity of the optional parameter) is checked first. Only after that, the program checks the validity of the first parameter.

The command plays_in_theatre receives a theatre name as its parameter, and the command plays_in_town receives a town name. If these parameters cannot be found, the program prints accordingly:

the> plays_in_theatre xx
Error: unknown theatre
the> plays_in_town xx
Error: unknown town
the>

Special requirements¶

If you want your assignment to pass the evaluation, you must meet these requirements:

You can only read the input file once during the program execution.
- This means that you must read the data from the input file to STL data structures. After that all searches, additions, and removals must be done in the chosen data structures (not in the input file).
Whichever STL data structure or their combination you choose to use in your assignment, you must use at least one map structure. That map must be part of the structure where you store the information read from the input file for later searches.

Tips¶

Recall that as a default, the program will be compiled into a build- directory. So, for testing purposes, you can move possible input data files to this same directory.
For splitting the file input and the user input, you can use the split function given in the template code.
Please remember the order in which to go through the elements in map and set with the iterator.
Examples on combinations of STL containers can be found from round 5 (see 05/examples/).
Examples on classes can be found from round 3 (see Plussa material and weekly exercises).

Implementing the program in stages¶

There are basically the following parts in the implementation of the program:

choice of the data structure and reading the file into the data structure
possibly implementation of a class or classes
user interface
search algorithms.

Consider carefully in which order you want to implement them so that it is possible for you to create and test them one by one before moving on to the next step. The minimum requirement for using the version control is these 3-4 parts having been executed as separate commits, but it would, of course, be best if you had more commits.

The commits listed above can divided into several parts.

Evaluation¶

To end up to assistents’ evaluation, your work must first pass automatic tests. Automatic tests do not accept a program producing warnings while compiling. If the automated tests give 0 points for your work, also your final points will be 0, and your work will not be evaluated by an assistant.

The assistant evaluates the submissions that have passed the automated testing (= 1 p) and fulfilled the special requirements of the assignment based on the last commit before the deadline, according to the following criteria:

The overall principle of the solution: 0-30 points:
- The learning goals of the exercise have been achieved.
- The program code has been split into logical, suitably long segments using functions, classes, and/or methods.
- If the program uses classes and objects, these have been implemented according to the basics of object-oriented programming (see from round 4 the section About programming style at Object-oriented programming).
- The data structure does not include repetitive data nor unnecessary parts. The chosen data structures have been used in a reasonable way.
- The program code does not include unnecessary repetitions nor other unnecessary parts.
- The program code does not include unnecessary limitations or assumptions or other forced solutions.
- The implementations of the program’s structures are easy to understand.
- Global variables have not been used in the program code (global constants are OK).
- The program does not terminate with the exit function.
Programming style: 0-10 points:
- Variables and functions are named clearly and appropriately. These items have named by using only one language, not e.g. Finnish and English mixed.
- Named constants have been used instead of magic numbers.
- The program code is neatly formatted.
- The length of program code lines do not exceed 80 characters.
- At the beginning of each file, there is a comment explaining the purpose of the file, the creator(s) of the project and other necessary information (see the assignment fo the first project on round 4).
- At the beginning of each function/method (in the header file if such exists), there is a comment describing its working, return value and parameters.
- There are comments in the code where necessary.
- Comments are related to the current version of the program, not to an older one.
- All comments have written in the same language (fi/en), but comments can be written in a language different from that used in naming variables and such.
- All the variables have been initialized.
- The compiler does not give warnings while compiling.
Using the version control: 0-10 points:
- There are enough commits.
- The content of commit messages is clear and relevant.

Note about evaluation

Automated tests check if your program works, but assistants pay attention to your coding style and other evaluation criteria listed above. Therefore, it could be possible that a fully working program brings you only zero points, if the above criteria are not met.

Requirements concerning especially good programming style can be found from the earlier material section on the current round.

Note about submission versions

The version to be evaluated is the one that corresponds to your latest successful Plussa submission (within the deadline). A successful submission means such a submission that passed automated tests.

After the first successful submission, you most probably want to improve your coding style (e.g. add comments), assuming that the deadline is not too close.

Anyway, remember finally this: After the final Git push, submit your work also in Plussa.

A+ presents the exercise submission form here.