Skip to content

Commit

Permalink
fix: improve docs to align with tests (#925)
Browse files Browse the repository at this point in the history
* fix: improve docs to align with tests

* tests: fix closing bracket.
  • Loading branch information
vaeng authored Nov 20, 2024
1 parent 0063583 commit acc3255
Show file tree
Hide file tree
Showing 4 changed files with 34 additions and 54 deletions.
21 changes: 12 additions & 9 deletions concepts/pointers/about.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,10 @@ With modern C++ there are also _smart pointers_, the basic type is not smart at

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.
1. Unlike _references_, pointers can be reassigned to different objects.
1. Pointers can also point to a null value, to indicate, that they currently do not point to any object.

## General Syntax

Expand Down Expand Up @@ -48,10 +49,10 @@ _Pointer arithmetic_ allows you to perform arithmetic operations on pointers, wh
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};
// Stargate Coordinate Code
int gateCode[] = {462, 753, 218, 611, 977};
// 'ptr' points to the first element of 'gateCode'
int* ptr{&gateCode[0]};
// Accesses the third Stargate address through pointer arithmetic
int dialedAddress{*(ptr + 2)};
// Chevron encoded! Dialing Stargate address:
Expand Down Expand Up @@ -80,10 +81,13 @@ struct Superhero {
std::string superpower;
};
Superhero* dianaPrince = new Superhero;
Superhero wonder_woman{};
Superhero* dianaPrince = &wonder_woman;
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;
```
Expand Down Expand Up @@ -127,6 +131,5 @@ It is your responsibility to detect these cases and ensure those pointers are su
In older code, you might encounter two alternatives to `nullptr`.
Firstly, the literal `0` is specifically interpreted as a null value for pointers, though it's the only scenario where an integral literal can be assigned to a pointer.
Secondly, the `preprocessor macro` `NULL`, inherited from C and defined in the `<cstddef>` header, is another representation of a null pointer, though its usage is less common in modern C++ code.
~~~~

[ariane-flight-v88]: https://en.wikipedia.org/wiki/Ariane_flight_V88
~~~~
19 changes: 9 additions & 10 deletions concepts/pointers/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,10 @@ With modern C++ there are also _smart pointers_, the basic type is not smart at

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.
1. Unlike _references_, pointers can be reassigned to different objects.
1. Pointers can also point to a null value, to indicate, that they currently do not point to any object.

## General Syntax

Expand Down Expand Up @@ -48,10 +49,10 @@ _Pointer arithmetic_ allows you to perform arithmetic operations on pointers, wh
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};
// Stargate Coordinate Code
int gateCode[] = {462, 753, 218, 611, 977};
// 'ptr' points to the first element of 'gateCode'
int* ptr{&gateCode[0]};
// Accesses the third Stargate address through pointer arithmetic
int dialedAddress{*(ptr + 2)};
// Chevron encoded! Dialing Stargate address:
Expand Down Expand Up @@ -79,8 +80,8 @@ The `->` operator is used to access the member variable `superpower`, showcasing
struct Superhero {
std::string superpower;
};
Superhero* dianaPrince = new Superhero;
Superhero wonder_woman{};
Superhero* dianaPrince = &wonder_woman;
dianaPrince->superpower = "Lasso of Truth";
// Using the -> operator to access member variable superpower:
std::cout << "Wonder Woman, possesses the mighty " << dianaPrince->superpower;
Expand All @@ -95,5 +96,3 @@ Pointers offer the flexibility of changing their target object and can be assign
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
29 changes: 4 additions & 25 deletions exercises/concept/speedywagon/.docs/instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ However, in recent times, the sensors that track Pillar Men activities are malfu
The Foundation's systems are old, and the code interacts with a legacy C++ library that cannot be updated.
Your task is to implement four core functions that monitor Pillar Men sensor activity using an old-fashioned pointer-based library.

The Foundation's operations rely on you.

## 0. The Sensor Environment (`pillar_men_sensor`)
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.

~~~~exercism/note
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.
Expand All @@ -22,20 +22,17 @@ struct pillar_men_sensor {
std::vector<int> data{};
};
```
~~~~

## 1. Check Sensor Connection (`connection_check`)

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`.

### Task
- 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.

### Example
```cpp
pillar_men_sensor* sensor{nullptr};
bool isConnected = connection_check(sensor);
Expand All @@ -47,14 +44,10 @@ bool isConnected = connection_check(sensor);
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.
### Task

- 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.
### Example

```cpp
pillar_men_sensor sensor_array[3] = {{0}, {101}, {22}};
int totalActivity = activity_counter(sensor_array, 3);
Expand All @@ -67,14 +60,10 @@ 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.

### Task
- 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
pillar_men_sensor db{9008, "songokunoie", {7, 7, 7}};
bool alarm = alarm_control(&db);
Expand All @@ -87,19 +76,9 @@ In this task, you will implement the `uv_alarm` function to determine whether an
The `uv_alarm` function should use the provided `uv_light_heuristic` function, which operates on a vector of data and returns a value based on certain thresholds.
This is a mockup version of the complex code that will run during production, please don't change the interface.
### Task

Define the `uv_alarm` function in the `speedywagon` namespace. It should:
- Take a pointer to a `pillar_men_sensor` _struct_ as its parameter.
- Return `false` if the sensor pointer is null.
- Call the `uv_light_heuristic` function, passing the address of the sensor's `data` array.
- Return `true` if the value returned by `uv_light_heuristic` is greater than the `sensor->activity` level, otherwise return `false`.

## Wrapping Up

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.

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.
19 changes: 9 additions & 10 deletions exercises/concept/speedywagon/.docs/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,10 @@ With modern C++ there are also _smart pointers_, the basic type is not smart at

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.
1. Unlike _references_, pointers can be reassigned to different objects.
1. Pointers can also point to a null value, to indicate, that they currently do not point to any object.

## General Syntax

Expand Down Expand Up @@ -48,10 +49,10 @@ _Pointer arithmetic_ allows you to perform arithmetic operations on pointers, wh
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};
// Stargate Coordinate Code
int gateCode[] = {462, 753, 218, 611, 977};
// 'ptr' points to the first element of 'gateCode'
int* ptr{&gateCode[0]};
// Accesses the third Stargate address through pointer arithmetic
int dialedAddress{*(ptr + 2)};
// Chevron encoded! Dialing Stargate address:
Expand Down Expand Up @@ -79,8 +80,8 @@ The `->` operator is used to access the member variable `superpower`, showcasing
struct Superhero {
std::string superpower;
};
Superhero* dianaPrince = new Superhero;
Superhero wonder_woman{};
Superhero* dianaPrince = &wonder_woman;
dianaPrince->superpower = "Lasso of Truth";
// Using the -> operator to access member variable superpower:
std::cout << "Wonder Woman, possesses the mighty " << dianaPrince->superpower;
Expand All @@ -95,5 +96,3 @@ Pointers offer the flexibility of changing their target object and can be assign
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

0 comments on commit acc3255

Please sign in to comment.