2024

Author: jrper

_toc.yml

@@ -4,7 +4,9 @@ sections:
 - file: part_one/intro
   sections:
   - file: part_one/01_running
+    title: Running C++ code
   - file: part_one/02_hello_world
+  
   - file: part_one/03_simple_math
   - file: part_one/04_input-output
   - file: part_one/05_troubleshooting

part_one/01_running.md

@@ -1,8 +1,8 @@
-# Compiling & Running
+# Compiling & Running C++ Code
 ```{index} compiling
 ```
 
-Whereas Python is mostly fairly simple to get working with straight away, especially in interactive mode, C & C++ have a few extra hurdles before you can get the computer to run your code. Your program must be compiled (and sometimes linked to other external standard or third party libraries) to produce a separate executable file, before that file can be run to solve your problem. In this section we present a number of ways of approaching this, listed in order of ease of use.
+Whereas Python is mostly fairly simple to get working with straight away, especially when working in interactive mode in a terminal interpretter session or a Jupyter notebook, C & C++ have a few extra hurdles before you can get the computer to run your code. Your program must be compiled (and sometimes linked to other external standard or third party libraries) to produce a separate executable file containing native machine instructions for your system, before that file can be run to finaly solve your problem. In this section we present a number of ways of approaching this, listed in order of ease of use.
 
 ## Web based solutions
 ```{index} compiling:web-based 
@@ -21,13 +21,13 @@ On each of these platforms you can cut & paste code from the examples in this pr
 ```{index} compiling: via docker
 ```
 
-A more local option is to take advantage of the combined power of Docker and Visual studio code to provide files which you can often compile with one click.
+A more local option is to take advantage of the combined power of Docker and Visual Studio Code to provide files which again you can often compile with one click.
 
 ![](images/vscode.png)
 
 To begin, fork the accompanying [examples repository](https://github.com/ese-msc/c-examples) and download it, then with Docker desktop running, open your local repository in VS code. You will be presented with a query banner "Folder contains a Dev Container configuration file. Reopen folder to develop in a container (learn more).". Select "Reopen in Container". This will restart the VS Code editor window, while connecting to a Docker container build from the repository [C examples Dockerfile](https://ese-msc/c-examples/.devcontainer/Dockerfile). This container has `git` and `Python` installed, together a working linux C++ compiler (the GNU compiler) and some useful VS Code extensions installed.
 
-For simple non-interactive C++ files, you can now build & run them with the Run Code button (ctrl+alt+N). For interactive files, you will need to run the program yourself using (for a file `hello.cpp` in the current directory) a command like:
+For simple, non-interactive C++ programmes contained in a single file, you can now build & run them with the Run Code button (ctrl+alt+N). For interactive files, you will need to run the program yourself using (for a file `hello.cpp` in the current directory) a command like:
 
 ```
 g++ -o hello hello.cpp
@@ -62,29 +62,29 @@ Most Mac users on the course will already have Homebrew installed, but for those
 brew install gcc
 ```
 
-will install a recent version of `gcc` (version 13 as of early December 2023) as well as placing it in your standard path. Once installed, (and having openned a new terminal) you can confirm that things work by running the following command in a terminal
+will install a recent version of `gcc` (version 14 as of early December 2024) as well as placing it in your standard path. Once installed, (and having openned a new terminal) you can confirm that things work by running the following command in a terminal
 
 ```
-gcc-13 --version
+gcc-14 --version
 ```
 
 You should see a response something like
 
 ```
-gcc-13 (Homebrew GCC 13.2.0) 13.2.0
-Copyright (C) 2023 Free Software Foundation, Inc.
+gcc-14 (Homebrew GCC 14.2.0) 13.4.0
+Copyright (C) 2024 Free Software Foundation, Inc.
 This is free software; see the source for copying conditions. There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 ```
 
 To compile a C++ file called `hello.cpp` into an exectuable called `hello`, then run it, use a command like
 
 ```
-g++-13 -o hello hello.cpp
+g++-14 -o hello hello.cpp
 ./hello
 ```
 
-Here `g++-13` is the name of your new GNU C++ compiler (version number 13), the `-o` option specifies the name of the output file (the default is `a.out`) and we must list the `.cpp` source file to compile into it. The second line then runs our new executable file which we have just compiled.
+Here `g++-14` is the name of your new GNU C++ compiler (specifically, version number 14), the `-o` option specifies the name of the output file (the default is `a.out`) and we must list the `.cpp` source file to compile into it. The second line then runs our new executable file which we have just compiled.
 
 Remember, we only need to compile once, and then we can run the executable as many times as we like. If we make any changes to the source code, we must recompile before we can run the new version and see the results.
 
@@ -101,7 +101,7 @@ cc --version
 You should see a response something like
 
 ```
-Apple clang version 14.0.0 (clang-1400.0.29.202)
+Apple clang version 19.1.4 (clang-1900.1.4.202)
 Target: arm64-apple-darwin21.6.0
 Thread model: posix
 InstalledDir: /Library/Developer/CommandLineTools/usr/bin

part_one/02_hello_world.md

@@ -1,4 +1,4 @@
-# Hello World!
+# A "Hello World!" Program in C++
 
 ## Introduction
 
@@ -40,7 +40,7 @@ Finally, in C/C++ we **must** use the double quotes `"` to indicate a string (th
 
 ## Hello World in C++
 
-A C++ based hello world function might look something like the following:
+A canonical C++ based hello world function might look something like the following:
 
 _hello.cpp_:
 ```c++
@@ -52,14 +52,14 @@ _hello.cpp_:
     }
 ```
 
-You'll see that in this case, the code looks very similar to the C example. In fact, most C code is valid C++ code (possibly with a few small changes). The only thing that looks different is that rather than using a function like `printf` we are using the special `<<` operator (i.e. a token which works a bit like `+` or `-`) to send our message to `std::cout`, an "output stream" which in this case represents printing to the screen.
+You'll see that in this case, the code looks very similar to the C example. In fact, most C code is valid C++ code (possibly with a few small changes). The only major thing that looks different is that rather than using a function like `printf` we are using the special `<<` operator (i.e. a token which works a bit like `+` or `-`) to stream our message to `std::cout`, an "output stream" which in this case represents printing to the screen. We could have used `"\n"` again to end the line, but in C++ we can also use `std::endl` to do the same thing, as well as flushing the output buffer (which can be useful in some cases).
 
 ## Some key differences from Python
 
-1. Whitespace doesn't matter (although it still makes things easier to read when code is nicely formatted).
-2. Individual statements *must* end with a `;`.
-3. The code starts running at the top of the `main` function. There can only be one `main` in a given programme.
-4. Functions (and variables) have a fixed data type associated with them.
+1. Whitespace in your doesn't matter (although it still makes things easier to read when code is nicely formatted). Instead `{}` are used to define blocks of code.
+2. Individual statements *must* end with a `;`. It's easy to forget this at first, but the compiler will remind you (often in a way that's hard to understand until you are used to it).
+3. Rather than starting at the top of the file, the code starts running at the top of the `main` function. There can only be one `main` function in a given programme.
+4. Functions (and variables) _must_ have a fixed data type associated with them the first time they are declared.
 
 
 ## Exercise: Run the Hello World programs
@@ -70,7 +70,7 @@ Run the three different programs in Python, C and C++. You already know how to r
 
 Once you can run the programs, try using the variable based version to try changing the message:
 - What happens if you leave out the `\n` instruction in the C example?
-- Can you add a second line of text, first in the same variable, then in a second one?
+- Can you add a second line of text, fist in the same call to `printf`/`std::cout`, then by adding a second one?
 
 
 ## Summary

part_one/03_simple_math.md

@@ -135,7 +135,7 @@ Note that unlike in Python, plotting in C++ is hard work, so we're just printing
 
 ## Quadrature
 
-Now we'll implement two quadrature methods, the midpoint and the trapezium rules. We'll start with the Python code (see the Computational Mathematics course for the annotated versions):
+Now we'll implement two quadrature methods, the midpoint and the trapezium rules. We'll start with the Python code again (see the Computational Mathematics course notes for the annotated versions):
 
 ```python
 
@@ -170,11 +170,11 @@ print(midpoint_rule(0, np.pi, f))
 print(trapezium_rule(0, np.pi, f))
 ```
 
-Now let's convert it into a C++ version
+Now let's convert it into a C++ version:
 
 ```c++
-#include <iostream>
-#include <cmath>
+#include <iostream> // for std::cout
+#include <cmath> // for std::sin
 
 double midpoint_rule(double a, double b, double (*func)(double), int number_intervals=10) {
     double interval_size = (b - a)/number_intervals;
@@ -214,9 +214,9 @@ int main(void) {
 }
 ```
 
-Note that we've had to include the `cmath` header to get access to the `sin` function. We've also had to declare the function `f` as taking a double and returning a double, and then pass it as an argument to the quadrature functions. This is because C++ doesn't have a built-in `sin` function, but instead has a `sin` function for each of the floating point types (e.g. `float`, `double`, `long double`), and the compiler needs to know which one we want to use.
+Note that we've had to include the `cmath` header to get access to the `sin` function. We've also had to declare the function `f` as taking a double as input and returning a double, and then pass it in as an argument to the quadrature functions. This is because C++ doesn't have a single unique built-in `sin` function, but instead has a `sin` function for each of the floating point types (e.g. `float`, `double`, `long double`) in its `cmath` library, and the compiler needs to know which one we want to use.
 
-The declaration and use of function pointers in the C++ versions of the `midpoint_rule` and `trapezium_rule` is more complicated than the Python version, but it's not too bad once you get used to it. We'll talk more about this in a later section.
+The declaration and use of function pointers in the C++ versions of the `midpoint_rule` and `trapezium_rule` is more complicated than the Python version, but it's not too impossible to remember once you get used to it. We'll talk more about this in a later section.
 
 ## Exercises
 

part_one/04_input-output.md

@@ -1,10 +1,10 @@
-# Programs with input
+# C++ Programs accepting inputs
 
 Since C++ programmes are compiled, we don't have the same flexibility to change the behaviour of the program at runtime as we do with Python. However, we can still take input data from the user in a number of ways.
 
 ## Taking input from the keyboard
 
-The counterpart to `std::cout` is `std::cin`. It's usage is similar but "in the other direction". For example:
+The counterpart to `std::cout` is `std::cin`, just as the counterpart to `print()` in Python is `input()`. The usage of `std::cin` is similar to `std::cout` but "in the other direction", using the `>>` operator. For example, the following C++ program asks for the user's name and then greets them:
 
 ```c++
 #include <iostream>
@@ -28,7 +28,7 @@ To run this using Docker plus VS code, you will need to run the compile command
     ```
 ```
 
-The `>>` operator will automatically convert the input into an appropriate form for the datatype (as long as it's one of the defaults). In the example above, this is just to a string, but we can also convert to integers or floating point numbers. Let's have an example, for example a program to calculate the mean of a sequence of floating point numbers.
+The `>>` operator will automatically convert the input into an appropriate form for the datatype (as long as it's one of the standard C++ types like `int`, `float`, `double` etc. ). In the example above, this is just to a string, but we can also convert to integers or floating point numbers. Let's have an example, for example a program to calculate the mean of a sequence of floating point numbers.
 
 ```c++
 #include <iostream>
@@ -92,15 +92,15 @@ int main()
 {
    FILE *fptr;
 
-   fptr = fopen("example.txt","w"); // A lot like the Python open function
+   fptr = fopen("example.txt", "w"); // A lot like the Python open function
 
    if(fptr == NULL) // We have to do our own error checks
    {
-      printf("Error!");   
+      printf("File read error!");   
       exit(1);             
    }
 
-   fprintf(fptr,"%d",  1000); // Write a number
+   fprintf(fptr,"%d", 1000); // Write a number
    fclose(fptr);
 
    return 0;
@@ -110,22 +110,23 @@ int main()
 to read a file we'd use
 ```c
    int num;
-   fptr = fopen("example.txt","r"); 
+   fptr = fopen("example.txt", "r"); 
    fscanf(fptr,"%d", &num);
 ```
 instead. We'll explain the use of `*` and `&` in the code above in Part III.
 
 For C++ we can treat files like we do the screen by treating them as _streams_ and reading or writing with the `<<` and `>>` operators. So to write ouput
 
 ```c++
+#include <iostream>
 #include <fstream>
 
 int main () {
 
   std::fstream fs;
   fs.open ("example.txt", std::fstream::out);
   
-  fs << 1000; // write 1000 to example.txt
+  fs << 1000 << std::endl; // write 1000 to example.txt
   fs.close();
 
   return 0;

part_three/01_pointers.md

@@ -13,7 +13,7 @@ b = a
 b[0] = 1
 print(a)
 ```
-Running the above code in the Python interpretter gives the output `[1]`. This is because the names `a` and `b` have both been bound to the same list object, and updating the list via one name updates it via the other. C and C++ allow similar behaviour usuing a concept called "pointer"s. 
+Running the above code in the Python interpretter gives the output `[1]`. This is because the names `a` and `b` have both been bound to the same list object, and updating the list via one name updates it via the other. C and C++ allow similar behaviour using a concept called "pointers". 
 
 A C style pointer holds a location (usually called an address) in your computer's memory, along with an attached data type. This address can be looked up ("dereferenced") to get hold of the underlying value to:
 1. use in an expression

part_two/01_datatypes.md

@@ -80,6 +80,8 @@ int main() {
 since it is permissible (though definitely not advisable) to declare variables anew in a new block.
 
 ## Type conversion
+```{index} type conversion
+```
 
 C-like languages have a number of inbuilt rules which they use to convert values from one type to another. Typically they are converted into whatever type has the larger range, and the expression is then evaluated in that type. This means that code such as
 

part_two/02_operators.md

@@ -16,7 +16,36 @@ Like Python, C-like languages support the core mathematical operations on numeri
 |   *    | Multiplication|
 |   /    | Division   |
 
-Unlike Python there is no exponentiation operator (i.e. no `**`), which requires a function call instead.
+Unlike Python there is no exponentiation operator (i.e. no `**`), which requires making a function call instead.
+
+### Operations on mixed types
+```{index} type conversion
+```
+
+Remember that in C++, the type of the result of an operation is determined by the types of the operands. If the operands are of different types, the compiler may automatically convert one of them to the type of the other. This is called _type conversion_ or _type casting_. For example, if you divide an integer by a floating point number, the integer will be converted to a float before the division is performed. Generally speaking, the compiler will try to convert the "smaller" type (the one with a smaller range or less precision) to the "larger" type, but you can also force the conversion by using a _type cast_.
+
+One key difference from modern Python is that C++ does not automatically convert between integer and floating point types when performing division on integers with the `\` operator. This means that if you divide two integers, the result will be an integer, with any fractional part truncated. To get a floating point result, you must convert one of the operands to a floating point type first.
+
+```c++
+
+#include <iostream>
+
+
+int main() {
+    int a = 5;
+    int b = 2;
+
+    // This will print 2
+    std::cout << a/b << std::endl;
+
+    // This will print 2.5
+    std::cout << (float)a/b << std::endl;
+
+    return 0;
+}
+```
+
+The code above demonstrates this behaviour, as well as the syntax for casting a variable to a different type . The `(float)` in the second `std::cout` statement is a _type cast_ which converts the integer `a` to a floating point number before the division is performed, refer back to the previous section for more information on type casting.
 
 ## Logical Operators
 ```{index} operators: logical
@@ -36,7 +65,7 @@ Again, as with Python, all the binary logical operators below work in C/C++
 |  `a && b`  | and |
 |  `a \|\| b`  | or |
 
-In C++ these functions return a `bool` data type which can be equal to `true` or `false` (note the capitalization differs from Python). However, thanks to an implicit type conversion rule, _all_ positive integers evaluate to true and the value zero evaluates to false. 
+In C++ these functions return a `bool` data type which can be equal to `true` or `false` (note the capitalization differs from Python). However, thanks to an implicit type conversion rule, _all_ positive integers evaluate to true and the value zero evaluates to false. As in Python, using comparisons with floating point numbers can be tricky due to the way they are stored in memory, and you should be careful when using them to test for equality.
 
 ## Other Useful Operators
 ```{index} operators: other