1 // Copyright 2024 The Pigweed Authors
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
4 // use this file except in compliance with the License. You may obtain a copy of
5 // the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12 // License for the specific language governing permissions and limitations under
13 // the License.
14
15 #include "pw_containers/intrusive_forward_list.h"
16
17 #include <cstddef>
18
19 #include "pw_unit_test/framework.h"
20
21 namespace examples {
22
23 // DOCSTAG: [pw_containers-intrusive_forward_list]
24
25 class Square : public pw::IntrusiveForwardList<Square>::Item {
26 public:
Square(size_t side_length)27 Square(size_t side_length) : side_length_(side_length) {}
Area() const28 size_t Area() const { return side_length_ * side_length_; }
29
30 private:
31 size_t side_length_;
32 };
33
34 class SquareList {
35 public:
36 // These elements are not copied into the linked list, the original objects
37 // are just chained together and can be accessed via `list_`.
SquareList()38 SquareList() : list_(squares_.begin(), squares_.end()) {}
39
40 // It is an error for items to go out of scope while still listed, or for a
41 // list to go out of scope while it still has items.
~SquareList()42 ~SquareList() { list_.clear(); }
43
44 // The list can be iterated over normally.
SumAreas() const45 size_t SumAreas() const {
46 size_t sum = 0;
47 for (const auto& square : list_) {
48 sum += square.Area();
49 }
50 return sum;
51 }
52
53 // Like `std::forward_list`, an iterator is invalidated when the item it
54 // refers to is removed. It is *NOT* safe to remove items from a list while
55 // iterating over it in a range-based for loop.
56 //
57 // To remove items while iterating, use an iterator to the previous item. If
58 // only removing items, consider using `remove_if` instead.
RemoveAndSumAreas(size_t area_to_remove)59 size_t RemoveAndSumAreas(size_t area_to_remove) {
60 size_t sum = 0;
61 auto previous = list_.before_begin();
62 auto current = list_.begin();
63 while (current != list_.end()) {
64 if (current->Area() == area_to_remove) {
65 current = list_.erase_after(previous);
66 } else {
67 sum += current->Area();
68 previous = current;
69 ++current;
70 }
71 }
72 return sum;
73 }
74
75 private:
76 std::array<Square, 3> squares_ = {{{1}, {20}, {400}}};
77 pw::IntrusiveForwardList<Square> list_;
78 };
79
80 // DOCSTAG: [pw_containers-intrusive_forward_list]
81
82 } // namespace examples
83
84 namespace {
85
TEST(IntrusiveForwardListExampleTest,EnlistSquares)86 TEST(IntrusiveForwardListExampleTest, EnlistSquares) {
87 examples::SquareList square_list;
88 EXPECT_EQ(square_list.SumAreas(), 160000u + 400u + 1u);
89 EXPECT_EQ(square_list.RemoveAndSumAreas(400), 160000u + 1u);
90 EXPECT_EQ(square_list.SumAreas(), 160000u + 1u);
91 }
92
93 } // namespace
94