16. Week 9 Thursday: Classes and File Organisation
≪ 15.1. A Guided Solution to Musical Chairs | Table of Contents | 17. Week 10 Tuesday: Destructors and Friends ≫A good chunk of today’s class was diverted to discussing the homework assignment, so this material is lighter than usual.
Structs vs. Classes
The first thing to make note of is the new concept of a “class”. They are identical to structs in almost every way: you can define member functions, member variables, and constructors, and they can be placed in the private or public fields. Just like structs, classes also define new variable types for C++, and they’re still called objects. In fact, you can turn a struct into a class by simply replacing struct with class.
As far as we know, the only differences between classes and structs are twofold:
- By default, members of structs are public while members of classes are private. That is, if you don’t specify either of these sections inside a struct or class, they’ll default to public and private respectively.
- By default, inheritance in a struct is public while inheritance in a class is private. We’ll discuss this more next week.
This StackExchange question has a bit more detail if you’re interested! A third difference that you may learn about in PIC 10B revolves around templates, but that’s not relevant for this quarter (I tried to say “that’s not relevant for this class”, but I think that’s confusing). The C++ FAQ describes a somewhat conventional distinction that most C++ programmers use to distinguish between structs and classes.
Programming Across Multiple Files
As we’ve seen previously, classes and structs can get quite lengthy. It’s hard to constantly scroll up and down to find where a certain struct’s member function is and then back to where it’s needed. Moreover, you can imagine that some programs need dozens of classes (think about your favourite video game, for instance)! Having this all in one file will be an unmanageable mess.
To that end, classes are often placed in separate files and “linked” to the main program. Let’s go back to Tuesday’s problem about musical chairs. We covered this in class, and by the time you are reading this, I will hopefully have posted a guided solution. We’ll make the minor change that the player struct will now be a class, to stay consistent with our class’s conventions.
The first component is a header file. These files typically share the name of the class they contain, and they should typically contain only one class. They have a .h file extension (or sometimes a .hpp file extension), making our header file player.h. These are its contents:
player.h
1// note: struct changed to class!
2class player {
3private:
4 string name;
5 int chair;
6
7 // defaults alive to true when a new player is made
8 bool alive = true;
9
10public:
11 player(string new_name, int starting_chair) {
12 name = new_name;
13 chair = starting_chair;
14 // alive = true;
15 }
16
17 // moves this player clockwise some integer number of chairs.
18 void move_clockwise(int movement, int chairs_left) {
19 chair = (chair + movement) % chairs_left;
20 if(chair == 0) {
21 chair = chairs_left;
22 }
23 }
24
25 // moves this player counterclockwise some integer number of chairs
26 void move_counterclockwise(int movement, int chairs_left) {
27 chair = (chair + movement) % chairs_left;
28 if(chair <= 0) {
29 chair += chairs_left;
30 }
31 }
32
33 // checks if this player is still in the game
34 bool is_alive() {
35 return alive;
36 }
37
38 // eliminates a player from the game
39 void eliminate() {
40 alive = false;
41 }
42
43 // gets the current player's current chair
44 int get_chair() {
45 return chair;
46 }
47
48 // gets the current player's name.
49 string get_name() {
50 return name;
51 }
52};
Inside our main file (main.cpp for me), we no longer need to keep the entire class above the main function! Instead, we can tell C++ to refer to the header file using an #include as follows:
main.cpp
1#include <iostream>
2#include <vector>
3#include <string>
4
5#include "player.h"
6
7using namespace std;
8
9int main() {
10 // 1. input the # of players
11 int n;
12 cin >> n;
13
14 // 2. set up our list of players
15 vector<player> players;
16 for(int chair = 1; chair <= n; chair++) {
17 string name;
18 cin >> name;
19
20 // creates a new player with the user's name
21 // and the starting chair.
22 player new_player(name, chair);
23 players.push_back(new_player);
24 }
25
26 // 3. for each round number 1, 2, ..., n - 1
27 int chairs_left = n;
28 for(int round = 1; round <= n - 1; round++) {
29 cout << "Enter the movement for round "
30 << round << ": ";
31
32 int movement;
33 cin >> movement;
34
35 // move each player CW or CCW, depending on the
36 // round we're in. odd rounds -> CW, even rounds -> CCW
37 for(int index = 0; index < players.size(); index++) {
38 if(players.at(index).is_alive() == false) {
39 continue;
40 }
41
42 if(round % 2 == 1) {
43 players.at(index).move_clockwise(movement, chairs_left);
44 } else {
45 players.at(index).move_counterclockwise(movement, chairs_left);
46 }
47 }
48
49 // scan through all of the players.
50 // whoever is sitting in the last chair (chair # chairs_left)
51 // should be eliminated.
52 for(int index = 0; index < players.size(); index++) {
53 if(players.at(index).is_alive() == false) {
54 continue;
55 }
56
57 if(players.at(index).get_chair() == chairs_left) {
58 players.at(index).eliminate();
59 cout << players.at(index).get_name()
60 << " has been eliminated!" << endl;
61 }
62 }
63
64 chairs_left -= 1;
65 }
66
67 // 4. look for the last guy left.
68 for(int index = 0; index < players.size(); index++) {
69 if(players.at(index).is_alive()) {
70 cout << players.at(index).get_name()
71 << " is the supreme champion!" << endl;
72 }
73 }
74
75 return 0;
76}
Note that the #include on line 5 uses quotations marks instead of angled brackets. Always use quotations when including headers, and only use angled brackets for libraries!
The #include literally tells C++ to copy-and-paste the contents of the file player.h into main.cpp during compilation. Thus, the changes to our program are actually minimal to the compiler!
You have now written your first header file! Unfortunately, there are still several issues with it.
- The code in the header file uses the
stringlibrary, but the header file doesn’t have these libraries included! Moreover, it’s missing ausing namespace std;. By including these lines in the header file, we can ensure that the header file’s code will always compile, no matter where or when it’s included. - Including this header more than once will cause a compile error due to repeated code, as everything will be copy-pasted multiple times. To fix this, we need to add a header guard, which is a trick that prevents multiple inclusions of the same header.
1#ifndef PLAYER_H // HEADER GUARD
2#define PLAYER_H // HEADER GUARD
3
4#include <string>
5using namespace std;
6
7class player {
8 // code...
9};
10
11#endif // HEADER GUARD
Common Mistake 1. Header Guards
Notice that the header guard was comprised of three separate lines — two at the top of the file and one at the bottom. It’s very easy to forget one or the other, and this can cause very mysterious compilation errors to occur. Moreover, each header file needs a unique header guard; typically, the header guards use the name of the file.
Remark 2. Pragma Once
In place of a conventional header guard, some people type the single line #pragma once at the top of their header files. This is technically not part of the C/C++ standard, and for this class you are (probably) not allowed to use it. You may see this get used in the future, as it’s way more convenient than the usual header guard.
There’s one last shift in organisation we’ll make, and it’s separating the class declaration from its implementation. As you may imagine, some classes can be very large; they can have dozens of member functions, each containing dozens of lines of code. If you write such a class, you may have a good idea of where to find everything; however, someone else that’s using your class doesn’t care at all about how you implemented it, and they only need to know which functions are available and what they do. The function bodies add extra clutter and get in the way of the code, thereby making it much harder to read and understand!
For this, we’ll place the function bodies in a separate file called an implementation file (aptly named). This means that we need to go through our header file and remove them; this is what our header file will look like after this change:
1#ifndef PLAYER_H // HEADER GUARD
2#define PLAYER_H // HEADER GUARD
3
4#include <string>
5using namespace std;
6
7class player {
8private:
9 string name;
10 int chair;
11
12 // defaults to true when a new player is made
13 bool alive = true;
14
15public:
16 // constructor - makes a new player with the given name and
17 // starting position.
18 player(string new_name, int starting_chair);
19
20 // moves this player clockwise some integer number of chairs.
21 void move_clockwise(int movement, int chairs_left);
22
23 // moves this player counterclockwise some integer number of chairs
24 void move_counterclockwise(int movement, int chairs_left);
25
26 // checks if this player is still in the game
27 bool is_alive();
28
29 // eliminates a player from the game
30 void eliminate();
31
32 // gets the current player's current chair
33 int get_chair();
34
35 // gets the current player's name.
36 string get_name();
37};
38
39#endif // HEADER GUARD
Note the semicolons at the end of each function declaration! This is a very typical header file, and it’s significantly more concise than before. Someone else trying to understand how your class interacts with the rest of the program only needs to look at the above information!
Now we still need to create the implementation file, as we need a place to put all the function bodies we deleted. Like the main program, the implementation file will have a .cpp extension, and it should typically match the name of the class. Thus, it will be called player.cpp.
We always need to include the corresponding header at the top of the implementation file, and it’s a good idea to include any libraries you’d like to use in the implementation as well, even if it’s already included in the header.
Naively, we would just paste all of our functions in the implementation file as follows:
1#include <string>
2#include "player.h"
3
4using namespace std;
5
6player(string new_name, int starting_chair) {
7 name = new_name;
8 chair = starting_chair;
9 // alive = true;
10}
11
12// moves this player clockwise some integer number of chairs.
13void move_clockwise(int movement, int chairs_left) {
14 chair = (chair + movement) % chairs_left;
15 if(chair == 0) {
16 chair += chairs_left;
17 }
18}
19
20// moves this player counterclockwise some integer number of chairs
21void move_counterclockwise(int movement, int chairs_left) {
22 chair = (chair - movement) % chairs_left;
23 if(chair <= 0) {
24 chair += chairs_left;
25 }
26}
27
28// checks if this player is still in the game
29bool is_alive() {
30 return alive;
31}
32
33// eliminates a player from the game
34void eliminate() {
35 alive = false;
36}
37
38// gets the current player's current chair
39int get_chair() {
40 return chair;
41}
42
43// gets the current player's name.
44string get_name() {
45 return name;
46}
This is not a bad idea, but it fails to compile. C++ believes that these are all just normal functions that we’re defining, and it doesn’t think that they’re part of a class! We need to specify that they belong to the player class; that way, C++ can “link” these functions to the empty function declarations we put in player.h.
To do this, we just prepend player:: to each of the function names. This clarifies that these functions belong to the player class, and from there, the compiler can figure out which function goes where. For completeness, here are the three files that now comprise this program:
main.cpp
1#include <iostream>
2#include <vector>
3#include <string>
4
5#include "player.h"
6
7using namespace std;
8
9int main() {
10 // 1. input the # of players
11 int n;
12 cin >> n;
13
14 // 2. set up our list of players
15 vector<player> players;
16 for(int chair = 1; chair <= n; chair++) {
17 string name;
18 cin >> name;
19
20 // creates a new player with the user's name
21 // and the starting chair.
22 player new_player(name, chair);
23 players.push_back(new_player);
24 }
25
26 // 3. for each round number 1, 2, ..., n - 1
27 int chairs_left = n;
28 for(int round = 1; round <= n - 1; round++) {
29 cout << "Enter the movement for round "
30 << round << ": ";
31
32 int movement;
33 cin >> movement;
34
35 // move each player CW or CCW, depending on the
36 // round we're in. odd rounds -> CW, even rounds -> CCW
37 for(int index = 0; index < players.size(); index++) {
38 if(players.at(index).is_alive() == false) {
39 continue;
40 }
41
42 if(round % 2 == 1) {
43 players.at(index).move_clockwise(movement, chairs_left);
44 } else {
45 players.at(index).move_counterclockwise(movement, chairs_left);
46 }
47 }
48
49 // scan through all of the players.
50 // whoever is sitting in the last chair (chair # chairs_left)
51 // should be eliminated.
52 for(int index = 0; index < players.size(); index++) {
53 if(players.at(index).is_alive() == false) {
54 continue;
55 }
56
57 if(players.at(index).get_chair() == chairs_left) {
58 players.at(index).eliminate();
59 cout << players.at(index).get_name()
60 << " has been eliminated!" << endl;
61 }
62 }
63
64 chairs_left -= 1;
65 }
66
67 // 4. look for the last guy left.
68 for(int index = 0; index < players.size(); index++) {
69 if(players.at(index).is_alive()) {
70 cout << players.at(index).get_name()
71 << " is the supreme champion!" << endl;
72 }
73 }
74
75 return 0;
76}
player.h
1#ifndef PLAYER_H // HEADER GUARD
2#define PLAYER_H // HEADER GUARD
3
4#include <string>
5using namespace std;
6
7class player {
8private:
9 string name;
10 int chair;
11
12 // defaults to true when a new player is made
13 bool alive = true;
14
15public:
16 // constructor - makes a new player with the given name and
17 // starting position.
18 player(string new_name, int starting_chair);
19
20 // moves this player clockwise some integer number of chairs.
21 void move_clockwise(int movement, int chairs_left);
22
23 // moves this player counterclockwise some integer number of chairs
24 void move_counterclockwise(int movement, int chairs_left);
25
26 // checks if this player is still in the game
27 bool is_alive();
28
29 // eliminates a player from the game
30 void eliminate();
31
32 // gets the current player's current chair
33 int get_chair();
34
35 // gets the current player's name.
36 string get_name();
37};
38
39#endif // HEADER GUARD
player.cpp
1#include <string>
2#include "player.h"
3
4using namespace std;
5
6player::player(string new_name, int starting_chair) {
7 name = new_name;
8 chair = starting_chair;
9 // alive = true;
10}
11
12// moves this player clockwise some integer number of chairs.
13void player::move_clockwise(int movement, int chairs_left) {
14 chair = (chair + movement) % chairs_left;
15 if(chair == 0) {
16 chair += chairs_left;
17 }
18}
19
20// moves this player counterclockwise some integer number of chairs
21void player::move_counterclockwise(int movement, int chairs_left) {
22 chair = (chair - movement) % chairs_left;
23 if(chair <= 0) {
24 chair += chairs_left;
25 }
26}
27
28// checks if this player is still in the game
29bool player::is_alive() {
30 return alive;
31}
32
33// eliminates a player from the game
34void player::eliminate() {
35 alive = false;
36}
37
38// gets the current player's current chair
39int player::get_chair() {
40 return chair;
41}
42
43// gets the current player's name.
44string player::get_name() {
45 return name;
46}
The whole point of this is modularisation. A well-designed class can be reused across multiple different programs. To continue with the musical chairs problem, we may want to implement different versions of the game, each with a different set of rules. We would be able to re-use the player.h and player.cpp files by including them directly in the new programs rather than copy-pasting the entire player class. Moreover, if we find out that adjustments need to be made to the player class, we immediately know exactly where to find it!
This kind of organisation can seem tedious and moderately pointless at first, especially since you need to keep track of what you’re doing across several different files. However, this kind of file organisation has become a standard because it allows other people to read and use complicated code!