fixup! feat: add exercise for pointer concept

Author: vaeng

config.json

@@ -201,10 +201,11 @@
         "slug": "speedywagon",
         "name": "Speedywagon Foundation",
         "uuid": "ed2148a5-674c-4660-a050-b11ab240b876",
-        "concepts": [],
+        "concepts": [
+          "pointers"
+        ],
         "prerequisites": [
           "classes",
-          "pointers",
           "references"
         ]
       }

exercises/concept/speedywagon/.docs/hints.md

@@ -0,0 +1,40 @@
+# Hints
+
+## General
+
+- Pay close attention to pointer syntax.
+  You will be using `*` (dereference operator) and `->` (member access through pointer).
+- Make sure to check for null pointers (`nullptr`) where necessary to avoid accessing invalid memory.
+- You can run the tests even if your code isn't complete; a rough structure is enough to see test results.
+- All functions used by the tests must be declared in the header file.
+- If your program crashes or behaves unexpectedly, it's often due to null pointer dereferencing.
+  Double-check that you handle `nullptr` properly.
+- When using pointer arithmetic, ensure that you stay within the bounds of the sensor array.
+  Going beyond the array's capacity can lead to memory issues.
+
+## 1. Check Sensor Connection (`connection_check`)
+
+- The task is mainly about verifying whether a pointer is null or not.
+- Use the comparison operator `!=` to check if a pointer is valid.
+- If you're unsure whether you're checking the pointer correctly, think about what `nullptr` represents (the absence of a valid memory address).
+
+
+## 2. Count Activity of Sensors (`activity_counter`)
+
+- You need to iterate over the array of sensors.
+  An array in C++ can be treated as a pointer to its first element.
+- Use pointer arithmetic (`sensor_array + i`) to access the sensor at index `i`.
+- The `->` operator is used to access a member of the struct through a pointer.
+
+### Example
+
+```cpp
+int sum = (sensor_array + i)->activity; // Access activity using pointer arithmetic
+```
+
+## 3. Alarm Control (`alarm_control`)
+
+- First, check if the pointer is null before accessing the sensor.
+- Use the `->` operator to access the `activity` member of the `pillar_men_sensor` struct.
+- Think carefully about what should happen if the sensor's activity level is `0`.
+  Should the alarm trigger?

exercises/concept/speedywagon/.docs/instructions.md

@@ -1,159 +1,91 @@
 # Instructions
 
-In this exercise, you will be simulating a windowing based computer system.
-You will create some windows that can be moved and resized.
-The following image is representative of the values you will be working with below.
+Welcome, Engineer!
+You are one of the last veterans of the Speedywagon Foundation, a secret organization that, for decades, has been battling ancient threats like the Pillar Men.
+In the course of this effort, you've spent years maintaining the Foundation's technological systems, built using a mix of cutting-edge tech and aging libraries.
 
-```
-                  <--------------------- screenSize.width --------------------->
-
-       ^          ╔════════════════════════════════════════════════════════════╗
-       |          ║                                                            ║
-       |          ║          position.x,_                                      ║
-       |          ║          position.y  \                                     ║
-       |          ║                       \<----- size.width ----->            ║
-       |          ║                 ^      *──────────────────────┐            ║
-       |          ║                 |      │        title         │            ║
-       |          ║                 |      ├──────────────────────┤            ║
-screenSize.height ║                 |      │                      │            ║
-       |          ║            size.height │                      │            ║
-       |          ║                 |      │       contents       │            ║
-       |          ║                 |      │                      │            ║
-       |          ║                 |      │                      │            ║
-       |          ║                 v      └──────────────────────┘            ║
-       |          ║                                                            ║
-       |          ║                                                            ║
-       v          ╚════════════════════════════════════════════════════════════╝
-```
+However, in recent times, the sensors that track Pillar Men activities are malfunctioning.
+The Foundation's systems are old, and the code interacts with a legacy C++ library that cannot be updated.
+Your task is to implement three core functions that monitor Pillar Men sensor activity using an old-fashioned pointer-based library.
 
-## 1. Define a `size` struct for storing the dimensions of the window
+The Foundation's operations rely on you.
 
-Define a `struct` named `size`.
-It should have two member variables `width` and `height` that store the window's current dimensions.
-The constructor function should accept initial values for these fields.
-The width is provided as the first parameter, the height as the second one.
-The default width and height should be `80` and `60`, respectively.
+## 0. The Sensor Environment (`pillar_men_sensor`)
 
-Additionally, define a member function `void resize(int newWidth, int newHeight)` that takes a new width and height as parameters and changes the fields to reflect the new size.
+As sensor readings can be huge, we supply a mockup _struct_ that is used in the actual library.
+The code has already been implemented in the header file for you.
 
 ```cpp
-size aSize{1080, 764};
-aSize.width;
-// => 1080
-aSize.height;
-// => 764
-
-aSize.resize(1920, 1080);
-aSize.width;
-// => 1920
-aSize.height;
-// => 1080
+struct pillar_men_sensor {
+    int activity{};
+    std::string location{};
+    std::vector<int> data{};
+};
 ```
 
-## 2. Define a `position` struct to store a window position
-
-Define a struct (or class) named `position` with two member variables, `x` and `y` that store the current horizontal and vertical position, respectively, of the window's upper left corner.
-The constructor function should accept initial values for these fields.
-The value for `x` is provided as the first parameter, the value for `y` as the second one.
-The default value should be `0` for both variables.
-
-The position (0, 0) is the upper left corner of the screen with `x` values getting larger as you move right and `y` values getting larger as you move down.
+## 1. Check Sensor Connection (`connection_check`)
 
-Also define a method `void move(int newX, int newY)` that takes new x and y parameters and changes the properties to reflect the new position.
-
-```cpp
-position point{};
-point.x;
-// => 0
-point.y;
-// => 0
-
-point.move(100, 200);
-point.x;
-// => 100
-point.y;
-// => 200
-```
+Your first task is to ensure that the Pillar Men sensor is connected properly.
+We can't have false alarms triggered by disconnected sensors.
+You will write a function `connection_check`, which tests if the sensor's pointer is valid by checking for `nullptr`.
 
-## 3. Define a `programWindow` class
+### Task
 
-Define a `programWindow` class or struct with __pointers__ to the following member variables:
+- Define a function that accepts a pointer a a `pillar_men_sensor` _struct_.
+- The function should return `true` if the sensor pointer is not null, and `false` otherwise.
 
-- `screenSize`: holds a pointer of type `size` with `width` 800 and `height` 600
-- `windowSize` : holds a pointer of type `size`, the initial value is the default value of the `size` instance
-- `windowPosition` : holds a pointer of type `position`, the initial value is the default value of the `position` instance
-
-When the window is opened (initialized), it always has the default `windowSize` and `windowPosition` in the beginning.
-Its constructor should not take any input parameters.
+### Example
 
 ```cpp
-programWindow aProgramWindow{};
-programWindow.screenSize->width;
-// => 800
-
-// Similar for the other fields.
+pillar_men_sensor* sensor{nullptr};
+bool isConnected = connection_check(sensor);
+// isConnected => false
 ```
 
-## 4. Add a method to resize the window
+## 2. Count Activity of Sensors (`activity_counter`)
+
+Pillar Men are lurking in the shadows, and we need to know if sensors have detected any activity.
+You will write the `activity_counter` function, which takes in an array of sensors and a capacity indicating the number of sensors in the array.
 
-The `programWindow` class should include a function `resize`.
-It should accept a __pointer__ of type `size` as input and attempts to resize the window to the specified size.
+### Task
 
-However, the new size cannot exceed certain bounds.
+- Define a function that accepts a pointer to the first element of an array and the arrays capacity.
+- Use pointer arithmetic to loop through the sensor array and accumulate the activity readings.
+- Return the accumulated activity.
 
-- The minimum allowed height or width is 1.
-  Requested heights or widths less than 1 will be clipped to 1.
-- The maximum height and width depend on the current position of the window, the edges of the window cannot move past the edges of the screen.
-  Values larger than these bounds will be clipped to the largest size they can take.
-  E.g. if the window's position is at `x` = 400, `y` = 300 and a resize to `height` = 400, `width` = 300 is requested, then the window would be resized to `height` = 300, `width` = 300 as the screen is not large enough in the `y` direction to fully accommodate the request.
+### Example
 
 ```cpp
-programWindow aProgramWindow{};
-
-size newSize{600, 400};
-aProgramWindow.resize(&newSize);
-aProgramWindow.size->width;
-// => 600
-aProgramWindow.size->height;
-// => 400
+pillar_men_sensor sensor_array[3] = {{0}, {101}, {22}};
+int totalActivity = activity_counter(sensor_array, 3);
+// totalActivity => 123
 ```
 
-## 5. Add a method to move the window
+## 3. Alarm Control (`alarm_control`)
 
-Besides the resize functionality, the `programWindow` class should also include a function `move`.
-It should accept a parameter as a __pointer__ of type `position` as input.
-The `move` function is similar to `resize` however, this function adjusts the _position_ of the window to the requested value, rather than the size.
+Not every sensor should trigger an alarm unless there’s real danger.
+The `alarm_control` function ensures that a sensor only triggers an alarm if its activity level is greater than 0.
+This function should also check for null sensors to prevent system crashes.
 
-As with `resize` the new position cannot exceed certain limits.
+### Task
 
-- The smallest position is 0 for both `x` and `y`.
-- The maximum position in either direction depends on the current size of the window.
-  The edges cannot move past the edges of the screen.
-  Values larger than these bounds will be clipped to the largest size they can take.
-  E.g. if the window's size is at `x` = 250, `y` = 100 and a move to `x` = 600, `y` = 200 is requested, then the window would be moved to `x` = 550, `y` = 200 as the screen is not large enough in the `x` direction to fully accommodate the request.
+- Define a function that accepts the pointer to a `pillar_men_sensor`.
+- The function should first check for a `nullptr` sensor. If the sensor is `nullptr`, return `false`.
+- If the sensor is valid and its activity is greater than 0, return `true`; otherwise, return `false`.
+
+### Example
 
 ```cpp
-programWindow aProgramWindow{};
-
-position newPosition{50, 100};
-aProgramWindow.move(&newPosition);
-aProgramWindow.position->x;
-// => 50
-aProgramWindow.position->y;
-// => 100
+pillar_men_sensor db{9008, "songokunoie", {7, 7, 7}};
+bool alarm = alarm_control(&db);
+// alarm => true
 ```
 
-## 6. Change a program window
-
-Implement a `changeWindow` function that accepts a __pointer__ to a `programWindow` object as input and changes the window to the specified size and position.
+## Wrapping Up
 
-The window should get a width of 400, a height of 300 and be positioned at x = 100, y = 150.
+You’ve been entrusted with an essential task for the Speedywagon Foundation.
+By testing for valid sensor connections, counting activity, and implementing alarm controls, you’ve ensured that the Foundation's battle against the Pillar Men can continue uninterrupted.
 
-```cpp
-programWindow aProgramWindow{};
-changeWindow(&programWindow);
-aProgramWindow.size->width;
-// => 400
+As a modern C++ engineer, you’d prefer using smart pointers, but alas, legacy code demands respect for the old ways.
+The fate of humanity may rest on these pointers, so proceed carefully, and may the Hamon energy guide you.
 
-// Similar for the other fields.
-```

exercises/concept/speedywagon/.docs/introduction.md

@@ -0,0 +1,99 @@
+# Introduction
+
+Like many other languages, C++ has _pointers_.
+You already know _references_ and _pointers_ are similar, but think of them as a level closer to the inner workings of your computer.
+_Pointers_ are variables that hold object addresses.
+They are used to directly interact with objects, enabling dynamic memory allocation and efficient data manipulation in C++.
+
+If you're new to _pointers_, they can feel a little mysterious but once you get used to them, they're quite straight-forward.
+
+They're a crucial part of C++, so take some time to really understand them.
+The bare-bone version in this concept is also called _dumb pointer_ or _raw pointer_.
+With modern C++ there are also _smart pointers_, the basic type is not smart at all and you have to handle all the work manually.
+
+Before digging into the details, it's worth understanding the use of _pointers_.
+_Pointers_ are a way to share an object's address with other parts of our program, which is useful for two major reasons:
+1. Like _references_, pointers avoid copies and help to reduce the resource-footprint of your program.
+2. Unlike _references_, pointers can be reassigned to different objects.
+3. Pointers can also point to a null value, to indicate, that they currently do not point to any object.
+
+## General Syntax
+
+A pointer declaration in C++ involves specifying the data type to which the the pointer is pointing, followed by an asterisk (`*`) and the pointer's name.
+When pointers are declared, they are not automatically initialized.
+Without explicit assignment, a pointer typically holds an indeterminate value, often referred to as a "garbage address."
+While certain compilers might initialize pointers to `nullptr`, this behavior is not guaranteed across all compilers, so it's essential not to rely on it.
+It's best practice to explicitly initialize raw pointers and verify their non-null status before utilization to avoid potential issues.
+
+```cpp
+int* ptr{nullptr}; // Declares a pointer and makes sure it is not invalid
+```
+
+To assign the address of a variable to a pointer, you use the address-of operator (`&`).
+Dereferencing a pointer is done using the _indirection operator_ (`*`) operator.
+
+```cpp
+std::string opponent{"Solomon Lane"};
+// 'ethan' points to the address of the string opponent
+std::string* ethan{&opponent}; 
+// Instead of ethan's, the opponent's name address is given to the passPort
+std::string passportName{*ethan};
+```
+
+Attention: dereferencing has to be done explicitly, while _references_ just worked like an alias.
+
+## Pointer Arithmetic
+
+_Pointer arithmetic_ allows you to perform arithmetic operations on pointers, which is particularly useful when working with arrays.
+Adding an integer to a pointer makes it point to a different element.
+
+```cpp
+// Stargate addresses
+int gateAddresses[] = {462, 753, 218, 611, 977};
+// 'ptr' points to the first element of 'gateAddresses'
+int* ptr{gateAddresses}; 
+// Accesses the third Stargate address through pointer arithmetic
+int dialedAddress{*(ptr + 2)}; 
+// Chevron encoded! Dialing Stargate address:
+openStarGate(dialedAddress);
+```
+
+~~~~exercism/caution
+Pointer arithmetic in C++ can easily lead to __undefined behavior__ if not handled carefully.
+Undefined behavior can manifest in unexpected program outcomes, crashes, or even security vulnerabilities.
+One infamous example of the consequences of undefined behavior occurred in the [explosion of the Ariane 5 rocket][ariane-flight-v88] in 1996, where a software exception caused by the conversion of a 64-bit floating-point number to a 16-bit signed integer led to a catastrophic failure.
+~~~~
+
+## Accessing member variables
+
+In C++, the `->` operator is used to access members of an object through a pointer to that object.
+It is a shorthand which simplifies accessing members of objects pointed to by pointers.
+For instance, if `ptr` is a pointer to an object with a member variable `x`, instead of using `(*ptr).x`, you can directly use `ptr->x`.
+This operator enhances code readability and reduces verbosity when working with pointers to objects.
+
+Here's a brief example, with a _struct_ `Superhero` that has a member variable `superpower`.
+The main function creates a pointer `dianaPrince` to a `Superhero` object (representing Wonder Woman).
+The `->` operator is used to access the member variable `superpower`, showcasing Wonder Woman's iconic "Lasso of Truth."
+
+```cpp
+struct Superhero {
+    std::string superpower;
+};
+
+Superhero* dianaPrince = new Superhero;
+dianaPrince->superpower = "Lasso of Truth";
+// Using the -> operator to access member variable superpower:
+std::cout << "Wonder Woman, possesses the mighty " << dianaPrince->superpower;
+// Memory cleanup:
+delete dianaPrince; 
+```
+
+## Pointers vs. references
+
+Pointers and references both enable indirect access to objects, but they differ in their capabilities and safety considerations.
+Pointers offer the flexibility of changing their target object and can be assigned null.
+However, this flexibility introduces risks, such as dereferencing null pointers or creating dangling pointers.
+References, on the other hand, cannot be null and are bound to valid objects upon creation, avoiding these risks.
+Given their safer nature, references should be preferred over pointers unless the additional functionalities provided by pointers are necessary.
+
+[ariane-flight-v88]: https://en.wikipedia.org/wiki/Ariane_flight_V88