ch03: Migration to consistent styling and C++17 for first part of ch03

Author: oraqlle

src/ch03-common-concepts/comments.md

@@ -1,30 +1,26 @@
 # Comments
 
-```admonish warning
-🚧 Page Under Construction! 🏗️
-```
-
 Comments are a way to document code for other people, and yourself. In C++ there are two
 types of comments, single line and multi-line. We've seen single line comments in many of
 the previous examples but to reiterate, a single line comment is started with `//` and
 any text written after it until a newline is ignored by the compiler.
 
-```cpp
+```cpp,icon=%cplusplus
 // Comment on its own line
 
-auto const x = 5; // Comment
+const auto x = 5; // Comment
 ```
 
 Multi-line comments are specified using `/* */` *quoting* ie. the comment extends from
 `/*` comment opener and continues until `*/`. This allows comments to extend multiple
 lines or be nested amongst code (if you really want).
 
-```cpp
+```cpp,icon=%cplusplus
 /*
 multi-line comment
 another line
 */
 
-auto const /* int */ x = 5;
+const auto /* int */ x = 5;
 ```
 

src/ch03-common-concepts/data-types.md

@@ -1,9 +1,5 @@
 # Data Types
 
-```admonish warning
-🚧 Page Under Construction! 🏗️
-```
-
 As we mentioned on the last page, C++ is a *statically typed* language which means the
 type of data must be known (or deducable) to the compiler. C++ has a large selection of
 types available to use, some are language primitives and others are defined in the
@@ -22,9 +18,9 @@ diffenent bit widths. The default `int` is 32-bits wide on most platforms. By de
 integer types are signed ie. they can represent both positive and negative numbers. If
 you need unsigned numbers we can use the `unsigned` qualifier.
 
-```cpp
-int const x = -5;
-unsigned int const y = 5;
+```cpp,icon=%cplusplus
+const int x = -5;
+const unsigned int y = 5;
 ```
 
 If you need integers of a different sizes you can either use size qualifiers with the
@@ -110,18 +106,18 @@ with the `u` suffix being able to be used in combination with the other two.
 Additionally you can write integer literals in a different base form by changing the
 prefix of the literal.
 
-```cpp
-auto const decimal = 42;
-auto const octal = 052;
-auto const hex = 0x2a;
-auto const Hex = 0X2A; // capital hex digits
-auto const binary 0b101010;
+```cpp,icon=%cplusplus
+const auto decimal = 42;
+const auto octal = 052;
+const auto hex = 0x2a;
+const auto Hex = 0X2A; // capital hex digits
+const auto binary 0b101010;
 ```
 
 Integers can also be separated using a `'` to make large numbers easier to read.
 
-```cpp
-auto const x = 1'234'567'890;
+```cpp,icon=%cplusplus
+const auto x = 1'234'567'890;
 ```
 
 ### Character Types
@@ -131,17 +127,17 @@ because character types in C++ are represented using numbers, specifically `char
 represents ASCII code points. Character literals are specified with single quotes like
 the example below. 
 
-```cpp
-char const x = 'a';
-auto const y = 'b';
+```cpp,icon=%cplusplus
+const char x = 'a';
+const auto y = 'b';
 ```
 
 ### Boolean Type
 
 C++'s Boolean type is called `bool` and can either hold the value `true` or `false`.
 Booleans are used mostly in conditional and loop statements eg. `if` and `while`.
 
-```cpp
+```cpp,icon=%cplusplus
 bool x = false;
 auto y = true;
 ```
@@ -164,41 +160,42 @@ floating point number.
 With `auto`, floating point values being initialized as a `double` by default and `float`
 and `long double` literals being specified by `f` and `l` literal suffixes.
 
-```cpp
-auto const f = -0.06f;
-auto const d = 47.5768;
-auto const l = -655456.457567l;
+```cpp,icon=%cplusplus
+const auto f = -0.06f;
+const auto d = 47.5768;
+const auto l = -655456.457567l;
 ```
 
 We can also initialize floating points using exponential form:
 
-```cpp
-auto const f = -6e-2f;
-auto const d = 475768e4;
-auto const l = -655456457567le7l;
+```cpp,icon=%cplusplus
+const auto f = -6e-2f;
+const auto d = 475768e4;
+const auto l = -655456457567le7l;
 ```
 
 #### Arithmetic Operations
 
 Integral and floating point types are categorized as *arithmetic* types which mean they
 support the common arithmetic operations like addition, subtraction etc.
-```cpp
+
+```cpp,icon=%cplusplus,fp=main.cxx
 auto main() -> int {
     // addition
-    auto const sum = 4 + 6;
+    const auto sum = 4 + 6;
 
     // subtraction
-    auto const diff = 10 - 5.5;
+    const auto diff = 10 - 5.5;
 
     // multiplication
-    auto const mul = 5 * 3.2;
+    const auto mul = 5 * 3.2;
 
     // division
-    auto const idiv = 10 / 3;
-    auto const fdif = 13.5 / 2.4;
+    const auto idiv = 10 / 3;
+    const auto fdif = 13.5 / 2.4;
 
     // remainder
-    auto const = 23 % 4;
+    const auto = 23 % 4;
 
     return 0;
 }
@@ -223,14 +220,14 @@ restricted to a set of named variants or *enumerators*. These named constants ha
 underlying integral type. Specifying the underlying type is optional ie. omit the
 `: type` in the enum declaration.
 
-```cpp
+```cpp,icon=%cplusplus
 enum class colour : char {
     red,
     green,
     blue
 };
 
-auto const c = colour::red;
+const auto c = colour::red;
 ```
 
 
@@ -242,33 +239,33 @@ declared. Tuples in C++ are not language types but are provided by the standard
 in the `<tuple>` header and is called `std::tuple`. We create a tuple using brace
 initialization (top) or using the helper function `std::make_tuple()`.
 
-```cpp
-auto const t = std::tuple { 5u, 5.34f, -345, "abc", false };
-auto const u = std::make_tuple(5u, 5.f, -345, "abc", false);
+```cpp,icon=%cplusplus
+const auto t = std::tuple { 5u, 5.34f, -345, "abc", false };
+const auto u = std::make_tuple(5u, 5.f, -345, "abc", false);
 ```
 
 Tuples can be accessed using `std::get<I>(t)` with `I` being the index of the value we
 want to access and `t` is the tuple object.
 
-```cpp
-auto const e = std::get<2>(t);  // e := -345
+```cpp,icon=%cplusplus
+const auto e = std::get<2>(t);  // e := -345
 ```
 
 You can also destructure tuples into its constituent values like so.
 
-```cpp
-auto const [v, w, x, y, z] = t;
+```cpp,icon=%cplusplus
+const auto [v, w, x, y, z] = t;
 ```
 
 There is a specialization of *tuples* called `std::pair` which holds just two values. The
 values of a pair can be extracted using the same methods as tuples but they also have
 public members `std::pair::first` and `std::pair::second` which allows you to access the
 data.
 
-```cpp
-auto const p = std::pair {5, 'a'};
-auto const [x, y] = p;
-auto const z = p.second;
+```cpp,icon=%cplusplus
+const auto p = std::pair {5, 'a'};
+const auto [x, y] = p;
+const auto z = p.second;
 ```
 
 ## Special Types
@@ -279,8 +276,8 @@ fundamental to the language.
 The first is the `void` type is an incomplete type that is used to indicate that a
 function does not return a value.
 
-```cpp
-auto foo(auto const i) -> void {
+```cpp,icon=%cplusplus
+auto foo(const auto i) -> void {
    i + 5; 
 }
 ```
@@ -297,9 +294,9 @@ with indices starting at 0. The subscript element access does not perform bounds
 while `array::at()` does, meaning the later will throw and exception if an out of bounds
 index is used while the former will crash the program... sometimes.
 
-```cpp
-auto const a = std::array { 1, 2, 3, 4, 5 };
-auto const e1 = a[0]; // valid
-auto const e2 = a.at(5); // exception std::out_of_range
+```cpp,icon=%cplusplus
+const auto a = std::array { 1, 2, 3, 4, 5 };
+const auto e1 = a[0]; // valid
+const auto e2 = a.at(5); // exception std::out_of_range
 ```
 

src/ch03-common-concepts/vars-mut.md

@@ -1,11 +1,7 @@
 # Variables and Mutability
 
-```admonish warning
-🚧 Page Under Construction! 🏗️
-```
-
 We first saw variables in our mini [guessing game project](/ch02-guessing-game/guessing-game.md#storing-data-with-variables)
-where we used them to store the guess of the user and create our PRNG etc.. Let's exlore
+where we used them to store the guess of the user and create our PRNG etc.. Let's explore
 what happens when we try to modify constant data and when we would want to allow
 mutations.
 
@@ -16,31 +12,37 @@ the `const` keyword which data that does not need to change, cannot change; opti
 remove the `const` keyword when data needs to be mutable.
 ```
 
-Create a new (or use an existing project) with a `main.cxx` and `CMakeLists.txt` etc.
-like we did for our previous programs; or use an existing one, and we'll explore
-mutability. Change the name of the target to `main` in the CMakeLists.txt, as I'll be
-using this as the target name from (near) all examples from now on in the book.
+Create a new project have done before, with a `main.cxx` and `CMakeLists.txt` and add the
+following contents. This will act as out scratchbook project for tinkering with examples.
+I won't always go into super detail about what changes will be made between various
+topics but most examples will have a full example with some being hidden behind snips
+which can be exposed using the 'eye' button in a codeblock.
 
-```haskell
+```haskell,icon=%cmake,fp=CMakeLists.txt
 cmake_minimum_required(VERSION 3.22)
 
 project(main
     VERSION 0.1.0
-    DESCRIPTION "C++ Book Example"
+    DESCRIPTION "C++ Book Examples"
     LANGUAGES CXX)
 
 add_executable(main main.cxx)
-target_compile_features(main PRIVATE cxx_std_20)
+target_compile_features(main PRIVATE cxx_std_17)
+
+if (MSVC)
+    # warning level 4
+    add_compile_options(/W4)
+else()
+    # additional warnings
+    add_compile_options(-Wall -Wextra -Wpedantic)
+endif()
 ```
 
-In your `main.cxx`, write the following program. When we try to compile this we should
-get an error like so.
-
-```cpp
+```cpp,icon=%cplusplus,fp=main.cxx
 #include <iostream>
 
 auto main() -> int {
-    auto const x = 42;
+    const auto x = 42;
 
     std::cout << x << std::endl;
     x = 43;
@@ -52,8 +54,8 @@ auto main() -> int {
 
 When we try to compile this we should get an error like so:
 
-```sh
-$ cmake -S . -B build --preset=<platform>
+```sh,icon=%gnubash,fp=Shell
+$ cmake -S . -B build
 $ cmake --build build
 [ 50%] Building CXX object CMakeFiles/main.dir/main.cxx.o
 /home/user/projects/common/main.cxx: In function ‘int main()’:
@@ -73,10 +75,10 @@ function boundaries where we expect the function to not mutate data passed to it
 though the surrounding scope might. More on this later.
 
 Even though immutable data is easier to reason about, mutating data is where the fun
-parts of computation occur. We can see that by dropping the `const` we can mutate the
+parts of computing occur. We can see that by dropping the `const` we can mutate the
 variable freely.
 
-```cpp
+```cpp,icon=%cplusplus,fp=main.cxx
 #include <iostream>
 
 auto main() -> int {
@@ -90,10 +92,8 @@ auto main() -> int {
 }
 ```
 
-With it compiling to...
-
-```sh
-$ cmake -S . -B build --preset=<platform>
+```sh,icon=%gnubash,fp=Shell
+$ cmake -S . -B build
 $ cmake --build build
 $ ./build/main
 42
@@ -113,7 +113,7 @@ is a `constexpr` and is initialized to some expression; even containing a functi
 and another initialized to a simple number but immediately changed to the same expression
 value.
 
-```cpp
+```cpp,icon=%cplusplus,fp=main.cxx
 #include <iostream>
 
 auto constexpr sum(auto const n) {
@@ -139,7 +139,7 @@ auto main() -> int {
 
 This generates the following assembly (at least for GCC-14):
 
-```asm
+```haskell,icon=,fp=x86_64
 main:
         push    rbp
         mov     rbp, rsp
@@ -203,7 +203,7 @@ auto y = 6;
 ```
 
 `auto` is a keyword that allows the compiler to perform *type deduction*, which means we
-tell the compiler to figure out the type of the variable or function return signature
+allow the compiler to infer the type of a variable or function return signature
 from the context it is given.
 
 ## Storage Duration