Merge pull request #2 from ese-msc-confidential/tmd_updates

tmd updates

Author: jrper

_toc.yml

@@ -6,7 +6,8 @@ sections:
   - file: part_one/01_running
   - file: part_one/02_hello_world
   - file: part_one/03_simple_math
-  - file: part_one/04_troubleshooting
+  - file: part_one/04_input-output.md
+  - file: part_one/05_troubleshooting
   - file: part_one/exercises_one
 - file: part_two/intro
   sections:
@@ -21,12 +22,12 @@ sections:
   - file: part_three/02_structs
   - file: part_three/03_header_files
   - file: part_three/04_build_systems
+  - file: part_three/05_combining_with_python.md
   - file: part_three/exercises_three
 - file: appendices/intro
   sections:
   - file: appendices/keywords
   - file: appendices/c-preprocessor
-  - file: appendices/combining_with_python
 - file: changelog
 - file: genindex
   title: Index

intro.md

@@ -2,19 +2,19 @@
 
 Welcome to a short primer on using the C & C++ programming languages. These notes were written for students on the ACSE and EDSML Masters courses in the Earth Science & Engineering Department at Imperial College London.
 
-These notes assume some previous programming experience in Python, equivalent to that of the Modern Programming Methods course, however they should be possible for anyone with previous experience coding in an interpretted language.
+These notes assume some previous programming experience in Python, equivalent to that of the Modern Programming Methods or Numerical Programming in Python courses, however they should be possible for anyone with previous experience coding in an interpretted language.
 
 This primer combines some notes introducing C-like languages to novice users, along with some exercises to practise your new knowledge. It is split into three sections,  It will probably take a maximum of 16 hours to work through, depending on your previous knowledge and how far you go with the exercises.
 
 ## Why do we teach C++?
 
-Python code is relatively easy to run (although not always easy to write), but doesn't always run very quickly. By using a compiled language like C++ we can get "closer to the metal" of the computer processor and write code which generates a solution much faster (sometimes hundreds or thousands of times faster). Often this performance difference doesn't matter, and the time taken to develop & maintain the code is more important, but for certain large scale calculation, which can take hours or days to run, then these differences become important.
+Python code is relatively easy to run (although not always easy to write), but doesn't always run very quickly. By using a compiled language like C++ we can get "closer to the metal" of the computer processor and write code which generates a solution much faster (sometimes hundreds or thousands of times faster). Often this performance difference doesn't matter, and the time taken to develop & maintain the code is more important, but for certain large scale calculations, which can take hours or days to run, then these differences become important.
 
 There are many other compiled languages in existence (eg. Fortran, Java, C#, ...) but C and C++ are currently some of the most widely used, and in demand. Unlike niche scientific languages such as Fortran, they are used both for numerical and systems programming and many modern machine learning frameworks have a C or C++ interface.
 
 ## How does C/C++ differ from Python?
 
-Python is what is known as an interpreted language. To run code, you point a single program, the interpreter at your source file, and it translates and runs the instructions in a way your computer can understand. C & C++ are compiled languages. A tool called a compiler is used to convert your human-readable source files into an executable instruction file your machine understands. This file can then be run many times.
+Python is what is known as an interpreted language. To run code, you point a single program, the interpreter, at your source file, and it translates and runs the instructions in a way your computer can understand. C & C++ are compiled languages. A tool called a compiler is used to convert your human-readable source files into an executable instruction file your machine understands. This file can then be run many times.
 
 Python is also a garbage-collected language. It cleans up (eventually) all the memory you use to hold variables in your programs, once it realises you're no longer interested in them. C-like languages give you, as a programmer, more power & control on where in your computer memory things live, and how long they stay around for. In return, it is often the programmer's job to clean up once you have finished
 

part_one/01_running.md

@@ -27,7 +27,7 @@ A more local option is to take advantage of the combined power of Docker and Vis
 
 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++ 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:
 
 ```
 g++ -o hello hello.cpp
@@ -56,7 +56,7 @@ Mac users have a number of routes to set up their system for C++. We recommend t
 
 The open source third-party mac package manager [Homebrew](https://brew.sh/) provides preconfigured versions of a number of unix-like packages, including versions of the GNU C/C++ compilers.
 
-Most Mac users on th course will already have Homebrew installed, but for those that don't application itself can be downloaded using the script & instructions from the Homebrew homepage. Additional (and alternative) instructions can be found [here](https://docs.brew.sh/Installation). Once this installation is complete, running the command 
+Most Mac users on the course will already have Homebrew installed, but for those that don't, the application itself can be downloaded using the script & instructions from the Homebrew homepage. Additional (and alternative) instructions can be found [here](https://docs.brew.sh/Installation). Once this installation is complete, running the command:
 
 ```
 brew install gcc
@@ -71,15 +71,16 @@ gcc-13 --version
 You should see a response something like
 
 ```
-gcc-12 (Homebrew GCC 13.2.0) 13.2.0
+gcc-13 (Homebrew GCC 13.2.0) 13.2.0
 Copyright (C) 2023 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.
+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++-12 -o hello hello.cpp
+g++-13 -o hello hello.cpp
 ./hello
 ```
 
@@ -100,12 +101,12 @@ cc --version
 You should see a response something like
 
 ```
-Apple clang version 12.0.5 (clang-1205.0.22.11)
-Target: arm64-apple-darwin20.3.0
+Apple clang version 14.0.0 (clang-1400.0.29.202)
+Target: arm64-apple-darwin21.6.0
 Thread model: posix
-InstalledDir: /Applications/Xcode.app/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin
+InstalledDir: /Library/Developer/CommandLineTools/usr/bin
 ```
-althought the precise values may be a little different.
+although the precise values may be a little different.
 
 To compile a C++ file called `hello.cpp` into an exectuable called `hello`, then run it, use a command like
 
@@ -135,6 +136,13 @@ gcc --version
 
 You should see a response something like
 
+```
+gcc (Ubuntu 11.4.0-1unintu1~22.04) 11.4.0
+Copyright (C) 2021 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
 
 ```

part_one/02_hello_world.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-Now that you hopefully have access to a working compiler, and a place to writewe'll move on to giving you some practical code to compile. A common first program for people to code in a new programming language is to write just enough code to print the phrase "Hello World!" to the screen (or other output device) and then exit.
+Now that you hopefully have access to a working compiler, and a place to write, we'll move on to giving you some practical code to compile. A common first program for people to code in a new programming language is to write just enough code to print the phrase "Hello World!" to the screen (or other output device) and then exit.
 
 The popularity of this tradition actually dates back to the beginnings of the C programming language in 1978 and the book "The C Programming Language" by Brian Kernighan and Dennis Ritchie.
 
@@ -34,7 +34,7 @@ _hello.c_:
 
 Unlike Python, we need to use a function from outside the core language, in this case the function `printf` from the standard library `stdio`, in order to print our message to screen. At the compilation stage we do this with command `#include`, a C preprocessor directive, which in practice works very similarly to the `import` statement in Python by pulling other code into our work.
 
-Where Python runs through commands beginning at the top of a script file, in `C` programs (at least, those printing to screen in the terminal) start at the beginning of the special `main` function. This function usually returns an integer, where `0` is taken to mean that things worked successfully, while other values are generally taken as a sign that something went wrong. 
+Where Python runs through commands beginning at the top of a script file, C programs (at least, those printing to screen in the terminal) start at the beginning of the special `main` function. This function usually returns an integer, where `0` is taken to mean that things worked successfully, while other values are generally taken as a sign that something went wrong. 
 
 Finally, in C/C++ we **must** use the double quotes `"` to indicate a string (the `'` character won't work, and is only used with single characters), and since the `printf` function doesn't end lines automatically, we must do it ourselves using the special end-of-line `\n` "escape" character.
 

part_one/03_simple_math.md

@@ -133,7 +133,7 @@ int main(void){
 
 Note that unlike in Python, plotting in C++ is hard work, so we're just printing the values to screen instead.
 
-### Quadrature
+## 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):
 
@@ -153,7 +153,6 @@ def midpoint_rule(a, b, func, number_intervals=10):
     return I_M
 
 def trapezium_rule(a, b, func, number_intervals=10):
-
     interval_size = (b - a)/number_intervals
 
     I_T = 0.0

part_one/04_input-output.md

@@ -1,8 +1,8 @@
-## Programs with input
+# Programs with input
 
 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
+## 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:
 
@@ -51,15 +51,15 @@ int main(){
 }
 ```
 
-### Taking input straight from the command line
+## Taking input straight from the command line
 
 As we saw with Python, another useful way to pass information into a program is on the command line. So far we have always used `main` functions with no input, but a longer form of the input signature is
 
 ```
 int main(int argc, char* argv[])
 ```
 
-Here we have two variables which are automatically assigned by the operating system, the integer `argc`, and an array of strings, `argv`. Just like with the Python `sys.argv`, the array is populated with a space separated list of the command line arguments used to call the program, with the first entry (`argv[0]`) equal to the name used to set the program running.
+Here we have two variables which are automatically assigned by the operating system, the integer `argc` (the number of arguments), and an array of strings, `argv`. Just like with the Python `sys.argv`, the array is populated with a space separated list of the command line arguments used to call the program, with the first entry (`argv[0]`) equal to the name used to set the program running.
 
 ```c++
 #include <iostream>
@@ -77,11 +77,13 @@ int main(int argc, char* argv[]){
 }
 ```
 
-### Taking input from files
+Note that here we use the `atof` function to convert the string to a floating point number. We also have to be careful to start our loop at `i=1` since the first entry in the array is the name of the program itself.
+
+## Taking input from files
 
 The last useful way we'll talk about to pass information in to a program is via a file. This is more involved than the previous versions, so don't be too worried if you don't follow all the details.
 
-As with input/output the standard methods differ somewhat between C & C++. In C we use a collection of functions from `stdio.h`. For example to write a file:
+As with input/output, the standard methods differ somewhat between C & C++. In C we use a collection of functions from `stdio.h`. For example to write a file:
 
 ```c
 #include <stdio.h>
@@ -134,7 +136,7 @@ or
 ```c++
   int num;
   fs.open ("example.txt", std::fstream::in);
-  /* read an int from example.txt (which is assumed)
+  /* read an int from example.txt, which is assumed
   to exist already. Unlike Python, we need to write 
   additional code if that might not be true.*/
   fs >> num; 

part_three/01_pointers.md

@@ -15,7 +15,7 @@ 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. 
 
-A C style pointer holds a location (usually called an address) in you computer's memory, along with an attached data type. This address can be looked up ("dereferenced") to get hold of the underlying value to:
+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
 2. update via an assignment.
 
@@ -28,26 +28,26 @@ As a C/C++ variable, a pointer must be declared the first time it is used. The s
 int *a; // This is a pointer to an int
 ```
 
-When declared this way, `a` holds a memory location (written as a number of a fixed size, usually 64 bits on modern comuputer systems). To actually make it "point" to a "target" we need the memory address of a suitable integer. The language has an operator, `&`, which will get this for us. To dereference (i.e. look up the value) `a` points to, we use the derferencing operator `*`. To assign a new value to the target, we assign it to the dereferenced object, that is `*a`. Let's look at a short C++ program which exercises all this new behaviour
+When declared this way, `a` holds a memory location (written as a number of a fixed size, usually 64 bits on modern comuputer systems). To actually make it "point" to a "target" we need the memory address of a suitable integer. The language has an operator, `&`, which will get this for us. To dereference (i.e. look up) the value `a` points to, we use the derferencing operator `*`. To assign a new value to the target, we assign it to the dereferenced object, that is `*a`. Let's look at a short C++ program which exercises all this new behaviour
 
 ```c++
 #include <iostream>
 
 int main(){
-int *a;
-int b = 7; // B is a normal int variable holding the value 7
-a = &b; // point
+    int *a;
+    int b = 7; // B is a normal int variable holding the value 7
+    a = &b; // point
 
-std::cout << a << std::endl;; // returns b's memory address.
-std::cout << *a << std::endl; // returns b's value  (i.e. 7).
+    std::cout << a << std::endl;; // returns b's memory address.
+    std::cout << *a << std::endl; // returns b's value  (i.e. 7).
 
-*a = 10;                     // updates a's target
-std::cout << b << std::endl; // returns 10
-return 1;
+    *a = 10;                     // updates a's target
+    std::cout << b << std::endl; // returns 10
+    return 1;
 }
 ```
 
-This embeds a lot of new concepts in one go, so feel free to run this one a few tips and check you've got to grips with the new behaviour.
+This embeds a lot of new concepts in one go, so feel free to run this one a few times and check you've got to grips with the new behaviour.
 
 If you think back, we've already seen the `*` operator a few times, and the `&` operator at least once. In particular, `&` is used in C++ to indicate "pass by reference" since it's already the C reference operator. To pass by reference in C we must declare the input arguments as pointers and pass in the *value* of a reference to the object we care about by using the `&` operator.
 
@@ -57,21 +57,19 @@ Another place the * operator has turned up is when passing 2D arrays into functi
 
 ```c++
 /* swap two elements (array version) */
-int[2] swap2(int a[]){
-    out[2];
-    out[0] = a[1];
-    out[1] = a[0] ;
-    return out;
+void swap2(int a[]){
+    int tmp = a[0];
+    a[0] = a[1];
+    a[1] = tmp;
 }
 ```
 and 
 ```c++
 /* swap two elements (pointer version)*/
-int[2] swap2(int *a){
-    out[2];
-    out[0] = a[1];
-    out[1] = a[0] ;
-    return out;
+void swap2(int *a){
+    int tmp = a[0];
+    a[0] = a[1];
+    a[1] = tmp;
 }
 ```
 
@@ -174,7 +172,7 @@ We didn't need any extra libraries this time, since `new` and `delete` are baked
 
 ### Additional pointer types
 
- In C++, traditional pointers are now considered less useful and alternative constructs such as "smart pointers" (which clean themselves up when they pass out of scope) and unique pointers (which prevent multiple pointers all being directed at the same target) are in greater use. You will learn more about these techniques during the rest of the course.
+ In C++, traditional pointers are now considered less useful and alternative constructs such as "smart pointers" (which clean themselves up when they pass out of scope) and unique pointers (which prevent multiple pointers all being directed at the same target) are in greater use. You will learn more about these techniques during the rest of the Advanced Programming course.
 
 ## Summary