|
| 1 | +[TOC] |
| 2 | + |
| 3 | +# Work In Progress |
| 4 | + |
| 5 | +# Presentation |
| 6 | + |
| 7 | +The Support Class Library (or SCL, formerly named Standard Class Library as a nod to the STL) is a library built on top of the STL and wants to provide tools and interfaces for common problems and patterns in order to make application development easier. |
| 8 | + |
| 9 | + |
| 10 | + |
| 11 | +# Parts |
| 12 | + |
| 13 | +## Stream |
| 14 | + |
| 15 | +The stream API is a library that allows lazy evaluation of potentially infinite sequences of data in an easy to write and easy to extend fashion. |
| 16 | + |
| 17 | + |
| 18 | + |
| 19 | +### Comparison with pure STL |
| 20 | + |
| 21 | +For instance, a recurrent task is to filter through a collection and execute an action on the filtered elements, let's compare how one would approach this task in both pure STL and using `scl::stream`. |
| 22 | + |
| 23 | +We will assume that the data is initially stored in a `std::vector`. |
| 24 | + |
| 25 | + |
| 26 | + |
| 27 | +#### Pure STL solution |
| 28 | + |
| 29 | +``` |
| 30 | +template <class Predicate, class Action> |
| 31 | +void processActionIf(Predicate predicate, Action action){ |
| 32 | + std::vector<std::shared_ptr<GuiComponent>> components = GUI.getComponents(); |
| 33 | + for(GuiComponent& component : components){ |
| 34 | + if(predicate(component)) |
| 35 | + action(component); |
| 36 | + } |
| 37 | +} |
| 38 | +
|
| 39 | +// OR |
| 40 | +
|
| 41 | +template <class Predicate, class Action> |
| 42 | +void processActionIf(Predicate predicate, Action action){ |
| 43 | + std::vector<std::shared_ptr<GuiComponent>> components = GUI.getComponents(); |
| 44 | + std::vector<std::shared_ptr<GuiComponent>> filtered; |
| 45 | + |
| 46 | + std::copy_if(begin(components), end(components), emplace_back(filtered), predicate); |
| 47 | + std::for_each(begin(filtered), end(filtered), action); |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | + |
| 52 | + |
| 53 | +In this simple use-case, using a for-loop reduces the amount of unnecessary copies that the otherwise functional-ish code would make. But things can get quite messy with a for-loop : conditions in conditions, chains of conditions, etc... . With the stream API, we want to get the best of both world : expressive and as efficient as a single for-loop. |
| 54 | + |
| 55 | + |
| 56 | + |
| 57 | +#### Stream API |
| 58 | + |
| 59 | +``` |
| 60 | +template <class Predicate, class Action> |
| 61 | +void processActionIf(Predicate predicate, Action action){ |
| 62 | + streamFrom(GUI.getComponents()) |
| 63 | + | filter(predicate) |
| 64 | + | forEach(action); |
| 65 | +} |
| 66 | +``` |
| 67 | + |
| 68 | +Here we get a lot of advantages : |
| 69 | + |
| 70 | +* Because it has been developped with knowledge of what we encounter in C++, we do not have the "begin&end iterators" issues : we simply pass a container and use it as the data source |
| 71 | +* We gain in expressiveness : `filter` expresses more intent than `copy_if` (because `copy_if` was not the actual intent, we used it to filter and use the result afterward) |
| 72 | +* We gain in clarity : Loops can get messy, we can mismatch types. Here no type is specified for the components container nor the components themselves (this is true even when there's a lot to process, where loops could get messier) |
| 73 | +* We gain in readability : `streamFrom` is where we begin the sequence processing, `|` indicate the start of a new operation, `;` ends the sequence processing |
| 74 | + |
| 75 | + |
| 76 | + |
| 77 | +### Design |
| 78 | + |
| 79 | +The library is greatly inspired by rangev3, Rust's `iter`, JS functional methods for arrays, the JS library `sequency` and Java 8's Stream API. |
| 80 | + |
| 81 | + |
| 82 | + |
| 83 | +#### Why free functions and operators instead of methods? |
| 84 | + |
| 85 | +In addition to the looks of it, using free functions and operators instead of methods provide one really important selling point : extendability. |
| 86 | + |
| 87 | + |
| 88 | + |
| 89 | +With methods, if you want to add an operation for streams you would have to : |
| 90 | + |
| 91 | +* Create a class that inherits from `scl::stream::Stream` |
| 92 | +* Add your methods |
| 93 | +* Tell the people that want to use your operation to use your class instead of `scl::stream::Stream` |
| 94 | + |
| 95 | +One could argue that with some runtime polymorphism shenanigans provided by the base class we could achieve something similar but it would be painful for the SCL maintainers and probably for the library maintainers. |
| 96 | + |
| 97 | + |
| 98 | + |
| 99 | +Using free functions, to add an operation, all you have to do is : |
| 100 | + |
| 101 | +* Create an appropriate stream iterator class (if needed) |
| 102 | +* Create a toolbox/type tag (if needed) |
| 103 | +* Create the free function |
| 104 | +* Create the `operator|` overload for your toolbox/type tag (if needed) |
| 105 | + |
| 106 | +The pain is where it should be, on the library maintainers' side. Honestly, pain is a bit of an exageration. |
| 107 | + |
| 108 | + |
| 109 | + |
| 110 | +You can have a look at `filter`/`map` to see how an operator is built from the ground up. |
| 111 | + |
| 112 | +You can have a look at `unique` to see how an operator is built on top of another one. |
| 113 | + |
| 114 | + |
| 115 | + |
| 116 | +#### What is the cost? |
| 117 | + |
| 118 | +Let's say you have |
| 119 | + |
| 120 | +``` |
| 121 | +std::vector<SpecialElement> v = streamFrom(container) |
| 122 | +| map(&Element::getSpecialId) |
| 123 | +| unique() |
| 124 | +| filter(startsWith("s", Case::INSENSITIVE)) |
| 125 | +| map(+[](const SpecialId& id){ return SpecialHub::from(id, Checks::NONE); }) |
| 126 | +| pack::toVector(); |
| 127 | +``` |
| 128 | + |
| 129 | + |
| 130 | + |
| 131 | + |
| 132 | + |
| 133 | +This is roughly equivalent to |
| 134 | + |
| 135 | +``` |
| 136 | +std::vector<SpecialElement> v; |
| 137 | +std::set<SpecialId> tagged; |
| 138 | +
|
| 139 | +auto superSpecial = startsWith("s", Case::INSENSITIVE); |
| 140 | +for(auto&& e : container){ |
| 141 | + SpecialId id = e.getSpecialId(); |
| 142 | + if(tagged.count(id)) |
| 143 | + continue; |
| 144 | + else |
| 145 | + tagged.insert(id); |
| 146 | + |
| 147 | + if(!superSpecial(id)) |
| 148 | + continue; |
| 149 | + |
| 150 | + v.emplace_back(SpecialHub::from(id, Checks::NONE)); |
| 151 | +} |
| 152 | +``` |
| 153 | + |
| 154 | + |
| 155 | + |
| 156 | + |
| 157 | + |
| 158 | +"roughly" because we need to take in account the iterators lifetime as well as the space and state they may use. |
| 159 | + |
| 160 | +Because they are all objects, the state is limited to the lifetime of the iterators/streams and cannot be accessed outside unlike `tagged` and `superSpecial`. |
0 commit comments