| inplace(3) | inplace(3) |
inplace - assign result inplace
#include <cfl/functions/inplace.hpp>
r = map (f, u...); // (1)
(r <<= map) (f, u...); // (2)
(r %= map) (f, u...); // (3)
inplace <assign_ > (r, map, f, u...); // (4)
inplace <placement_new_> (r, map, f, u...); // (5)
Basically, adapt a function to assign its result to an existing value in-place, instead of returning a new value. Normally, a manual optimization when assignment can be moved into a collective operation.
In-place operation is an intrinsic property of some collective operations, such as map, product, scan and unfold. Also compositions thereof (i.e. closures) support inplace operations. When not applicable, normal assignment is used instead.
There are two predefined in-place operators, <<= for regular assignment, and
%= for placement new to “assign” uninitialized storage.
However, in-place operations are not limited to assignment and placement new, but any operation can be done in-place through the template argument to the function form (4) and (5).
In the first expression (1), f returns a new value assigned to r. In the
second expression (2), map assigns the elements of r upon calls to f with
the elements of u, saving a possibly large temporary result array.
The third expression (3) uses placement new instead of assignment, when the
left-hand side is uninitialized storage. Some natural restrictions to r
apply, such as being at least traversable.
Expressions (4) and (5) show the function form of operators <<= and %=.
The operators <<= and %= return a closure-like container holding the
left-hand side r and the function f. When invoked, it returns the
left-hand side r, like normal assignment would have. The function form
returns r without any intermediate container.
inplace is a container function.
Valid for “normal” assignment, i.e. when the left-hand side is returned from the
assignment. An error when substituting r is a failure, so using a stand-alone (r <<= f) as function argument to a higher-order function may result in failure.