Merge branch 'main' of https://github.com/splashkit/the-programmers-field-guide into raspberry_gpio

Author: omckeon

resources/code-examples/part-2/6-deep-dive-memory/linked-list.cpp

@@ -1,5 +1,6 @@
 #include <stdlib.h>
 #include <stdio.h>
+#include <new>
 
 /**
  * A node is a struct that contains a pointer to the next node,
@@ -39,8 +40,8 @@ template <typename T>
 linked_list<T> *new_linked_list() 
 {
     linked_list<T> *list = (linked_list<T> *) malloc(sizeof(linked_list<T>));
-    list->first = NULL;
-    list->last = NULL;
+    list->first = nullptr;
+    list->last = nullptr;
     return list;
 }
 
@@ -54,17 +55,18 @@ template <typename T>
 void delete_linked_list(linked_list<T> *list)
 {
     node<T> *current = list->first;
-    while (current != NULL) 
+    while (current != nullptr) 
     {
         node<T> *next = current->next;
         // Clear data from node
-        current->next = NULL;
+        current->next = nullptr;
+        current->data.~T(); // Call destructor
         free(current);
         current = next;
     }
     // Clear old data from list
-    list->first = NULL;
-    list->last = NULL;
+    list->first = nullptr;
+    list->last = nullptr;
     free(list);
 }
 
@@ -79,9 +81,10 @@ template <typename T>
 void add_node(linked_list<T> *list, T data)
 {
     node<T> *new_node = (node<T> *) malloc(sizeof(node<T>));
+    new(&new_node->data) T; // Placement new to construct the data in the node
     new_node->data = data;
-    new_node->next = NULL;
-    if (list->first == NULL) 
+    new_node->next = nullptr;
+    if (list->first == nullptr) 
     {
         list->first = new_node;
         list->last = new_node;
@@ -103,7 +106,7 @@ void add_node(linked_list<T> *list, T data)
 template <typename T>
 void remove_node(linked_list<T> *list, node<T> *node_to_remove)
 {
-    node<T> *previous = NULL;
+    node<T> *previous = nullptr;
 
     // Removing the first node
     if (list->first == node_to_remove
@@ -118,14 +121,14 @@ void remove_node(linked_list<T> *list, node<T> *node_to_remove)
         node<T> *current = list->first;
 
         // Iterate through the list until we find the node to remove
-        while (current != node_to_remove && current != NULL) 
+        while (current != node_to_remove && current != nullptr) 
         {
             previous = current;
             current = current->next;
         }
 
         // Check if the node to remove was found
-        if (current == NULL) 
+        if (current == nullptr) 
         {
             return;
         }
@@ -141,7 +144,8 @@ void remove_node(linked_list<T> *list, node<T> *node_to_remove)
     }
 
     // Clear data from node
-    node_to_remove->next = NULL;
+    node_to_remove->next = nullptr;
+    node_to_remove->data.~T(); // Call destructor
     free(node_to_remove);
 }
 
@@ -154,7 +158,7 @@ int main()
     add_node(list, 4);
 
     node<int> *current = list->first;
-    while (current != NULL) 
+    while (current != nullptr) 
     {
         printf("%d->", current->data);
         current = current->next;
@@ -164,7 +168,7 @@ int main()
     remove_node(list, list->first->next->next);
 
     current = list->first;
-    while (current != NULL) 
+    while (current != nullptr) 
     {
         printf("%d->", current->data);
         current = current->next;

src/assets/illustrations/andrew_ill.png

@@ -0,0 +1,11 @@
+---
+title: Installing Tools
+---
+
+Learning to program will require you to put into practice the things you are reading. To do this, you need to install a few things.
+
+- **Code Editor** - in which you will write your code.
+- **Compiler** - used to convert your code into machine code.
+- **Libraries** - packages of existing code you can build on top of.
+
+Jump over to the [installation guides](/book/appendix/0-installation/0-overview) to install the tools you need. These guides will step you through installing these tools on your computer. You will get to use these in the next chapter.

src/content/docs/book/part-0-getting-started/2-computer-use/0-panorama/05-installing-tools.md

@@ -2,6 +2,12 @@
 title: Activities
 ---
 
+## Install software development tools
+
+The most important first step in getting ready is to install the compilers, libraries, and code editor we will use throughout the next chapters. Jump over to the [installation guides](/book/appendix/0-installation/0-overview) and follow the steps to install the tools you will need.
+
+## Organise your files
+
 You will build a number of programs and small projects as you progress through the journey in this book. To help yourself, we recommend organising your file system in a way that will make it easy to find these projects from the terminal.
 
 Think about how you will organise your projects, and where on your computer's file system you will store them.

src/content/docs/book/part-0-getting-started/2-computer-use/3-explore/3-explore.md

@@ -2,6 +2,10 @@
 title: Go Exploring
 ---
 
+:::tip
+Use the [installation guides](/book/appendix/0-installation/0-overview) to install the tools you need.
+:::
+
 Here is a fun hello world program to wrap up this section. You can also look through the guide and fine other sample code you can download and run now. This is a great way to explore the ideas you are learning.
 
 The code for this part will be using SplashKit functionality to draw images, play sound effects and draw text with a specific font.

src/content/docs/book/part-0-getting-started/3-building-programs/3-explore.md

@@ -6,3 +6,9 @@ Having explore how we can organise code to help make the code in your programs e
 
 - [AFL game data](/book/part-2-organised-code/2-organising-code/3-explore/3-1-afl-score) - create functions and procedures to calculate AFL scores and game details.
 - [Click game](/book/part-2-organised-code/2-organising-code/3-explore/3-2-targets) - create functions and procedures for a small target hitting game.
+
+:::tip
+
+Remember to focus on organising your code in appropriate functions and procedures, using parameters to share data as needed. Make sure your code isn't just all done in main.
+
+:::

src/content/docs/book/part-2-organised-code/2-organising-code/3-explore/3-0-test-your-knowledge.md

@@ -8,7 +8,7 @@ A game in the Australian Football League consists of two teams aiming to achieve
 
 Build a program that allows the user to enter details of an AFL game, output scores and winners, and provide a menu for the user to update game details and output scores.
 
-An example of this running is shown below.
+An example of this running is shown below:
 
 ```txt
 Welcome to the AFL score calculator!
@@ -80,13 +80,13 @@ Are you sure you want to quit? [Y/n]: y
 Bye!
 ```
 
-:::caution
+:::tip[Hints:]
 
-Make sure you are using this to demonstrate how to build this using functions and procedures. Here are some functions and procedures you may want to consider adding:
+Here are some functions and procedures you may want to consider adding:
 
-- Output details (taking in the two team names and scores)
-- Functions to read and validate data from the user (strings, numbers, boolean)
-- Print menu
+- Functions to [read and validate data from the user](/book/part-2-organised-code/2-organising-code/1-tour/00-2-explore-functions) (strings, numbers, boolean).
+- A procedure to output calculated details of each team (taking in the names and score details of the two teams).
+- A procedure to print the menu (taking in the names of the two teams).
 - A function to calculate a score from a number of goals and behinds.
 - A function to calculate and return the name of the winner, from the two team names and scores.
 

src/content/docs/book/part-2-organised-code/2-organising-code/3-explore/3-1-afl-score.md

@@ -4,7 +4,7 @@ sidebar:
     label: " - Click Game"
 ---
 
-For this activity, create a program that lets the user enters a number of targets to hit. Then, show a window that displays the number of targets left to hit, using a health-bar style graphic (a partially filled bar, based on proportion of initial target remaining). Draw a circle on the screen, and test if the user has clicked the circle. When they do click it, subtract one from the targets to be hit, ending when this is 0.
+For this activity, create a program that lets the user enter a number of targets to hit. Then, show a window that displays the number of targets left to hit, using a health-bar style graphic (a partially filled bar, based on proportion of initial target remaining). Draw a circle on the screen, and test if the user has clicked the circle. When they do click it, subtract one from the targets to be hit, ending when this is 0.
 
 ```txt
 Welcome to target click.
@@ -22,20 +22,20 @@ Click 10 targets to end the game.
 // end when there are no targets left to hit
 ```
 
-:::caution
+:::tip[Hints:]
 
-Make sure you are using this to demonstrate how to build this using functions and procedures. Here are some functions and procedures you may want to consider adding:
+Here are some functions and procedures you may want to consider adding:
 
-- Functions to read and validate data from the user (numbers)
-- A procedure to play the game
+- Functions to [read and validate data from the user](/book/part-2-organised-code/2-organising-code/1-tour/00-2-explore-functions) (numbers)
+- A procedure to play the game *(optional)*
 - A procedure to draw the game, that uses a procedure to draw the target bar
 - A procedure to draw the target bar - using parameters for position and proportion of bar to be filled. This can be drawn with two rectangles - using the proportion to be filled for one dimension of the second rectangle.
-- Function (target hit) to check if the user has clicked, and the mouse is inside the target circle.
+- A function (target hit) to check if the user has clicked, and the mouse is inside the target circle.
 
 :::
 
-:::tip
+:::note[Useful SplashKit functions:]
 
-You can use the [point in circle](https://splashkit.io/api/geometry/#point-in-circle-with-values) function to test if the mouse is in the circle. See [mouse x](https://splashkit.io/api/input/#mouse-x) and [mouse y](https://splashkit.io/api/input/#mouse-y) to get the location of the mouse.
+You can use the [Point In Circle](https://splashkit.io/api/geometry/#point-in-circle-with-values) function to test if the mouse is in the circle. See [Mouse X](https://splashkit.io/api/input/#mouse-x) and [Mouse Y](https://splashkit.io/api/input/#mouse-y) to get the location of the mouse.
 
 :::

src/content/docs/book/part-2-organised-code/2-organising-code/3-explore/3-2-targets.md

@@ -7,3 +7,9 @@ At this point in your journey, you have the tools to build more interesting prog
 - [Entity manager](/book/part-2-organised-code/3-structuring-data/3-explore/3-1-entity) - create a simple data entry system that allows you to see and edit details of a single record.
 - [Explore game states](/book/part-2-organised-code/3-structuring-data/3-explore/3-2-game) - explore creating a game menu and other states.
 - [Potentiometer->Servo Control](/book/part-2-organised-code/3-structuring-data/3-explore/3-3-servo-potentiometer/) - explore creating an application to control a servo state using a potentiometer and map the values.
+
+:::tip
+
+For this you want to show how to create and use structs and enums, while also continuing to show how to organise your code in functions and procedures. You want to see these new data types working in conjuncture with the other programming features you have already mastered.
+
+:::

src/content/docs/book/part-2-organised-code/3-structuring-data/3-explore/3-0-test-knowledge.md

@@ -6,10 +6,10 @@ sidebar:
 
 Create a program that lets the user enter and display details associated with a book. This should include your own struct to manage the book data, with a function to read in the book, and a procedure to output the details of the book. Also show a simple menu, with an associated enumeration. Use the enumeration in a read menu option function.
 
-An example of this running is shown below.
+An example of this running is shown below:
 
 ```txt
-Book entry system.
+Book entry system:
 
 Enter the name of the book: Programmers Guide
 Enter book location: https://programmers.guide
@@ -33,10 +33,10 @@ Menu:
 Option: 3
 ```
 
-:::caution
+:::tip[Hints:]
 
-Make sure you have a struct for your book data. Use this in a function that returns a book, and a procedure that accepts a book as a parameter.
+Make sure you have a [struct](/book/part-2-organised-code/3-structuring-data/2-trailside/03-01-struct) for your book data. Use this in a function that returns a book, and a procedure that accepts a book as a parameter.
 
-Also have an enumeration for the menu options, and a function that returns one of the enum values based on what the user chose (read menu option).
+You should also have an [enumeration](/book/part-2-organised-code/3-structuring-data/2-trailside/03-02-enum) for the menu options, and a function for [reading data from the user](/book/part-2-organised-code/3-structuring-data/1-tour/0-1-explore-enums/#reading-data-from-the-user) that returns one of the enum values based on what the user chose (read menu option).
 
 :::