clean-up: ItemWrapper now stands on its own

...initially, this header was a collection of small helpers made on occasion;
one of them, the `ItemWrapper` used in transforming pipelines came
into widespread use and was much augmented and improved over the years.

many other tiny helpers could be replaced by standard library facilities...

src/lib/item-wrapper.hpp

@@ -1,8 +1,8 @@
 /*
-  WRAPPER.hpp  -  some smart wrapping and reference managing helper templates
+  ITEM-WRAPPER.hpp  -  hold anything for unified handling
 
    Copyright (C)
-     2009,            Hermann Vosseler <Ichthyostega@web.de>
+     2009,2023        Hermann Vosseler <Ichthyostega@web.de>
 
   **Lumiera** is free software; you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by the
@@ -11,32 +11,34 @@
 
 */
 
-/** @file wrapper.hpp
- ** Library implementation: smart-pointer variations, wrappers and managing holders.
- ** This is (intended to become) a loose collection of the various small helper templates
- ** for wrapping, containing, placing or handling a somewhat \em problematic other object.
- ** Mostly these are implemented to suit a specific need and then factored out later on.
- ** - ReturnRef is similar to std::reference_wrapper, but with a function-like usage.
- ** - ItemWrapper is a similar concept, but used more like a smart-ptr. Notably,
- **   a value-object is stored inline, into an embedded buffer.
- **   Furthermore, ItemWrapper can be used to level differences between values,
- **   references and pointers, as it can be instantiated with any of them, offering
- **   (almost) uniform handling in all cases (useful for building templates)
- ** - FunctionResult is the combination of ItemWrapper with a functor object
- **   to cache the function result value. It was split off into a separate
- **   header \ref wrapper-function-result.hpp to reduce include impact
- ** @remark most of this helper collection became obsolete with the evolution of the
- **   standard library — with the exception of ItermWrapper, which turned out to be
- **   very effective and is now pervasively used as part of transforming functor
- **   pipelines, to cache the result of the transforming function invocation.
+/** @file item-wrapper.hpp
+ ** Adapter to store and hold an element of arbitrary type in local storage.
+ ** Notably, the difference between values and references can be levelled,
+ ** while default construction or copy abilities are passed through.
+ ** Such an _inline container_ can be relevant for generic programming,
+ ** especially to capture the result of an arbitrary function.
+ ** This container can be created empty (which requires to store an additional
+ ** state flag); the stored payload can be accessed through the dereferentiation
+ ** operator (similar to a smart-ptr or to std::optional). The interface was
+ ** shaped by its primary use case, which is to bind transforming functors
+ ** into a processing pipeline, or for caching the result of a computation.
+ ** Another use case is to circumvent the finiteness of references, to
+ ** re-bind them to another target, or to replace an immutable object.
+ ** @note the essential trait is that for each usage we have static,
+ **       compile-time knowledge of the precise type with all its adornments,
+ **       while we can not assume _anything_ about this type when writing the
+ **       code, to allow for maximum flexibility of potential usages. Contrast
+ **       this to the pattern of _type erasure_, where we discard specific
+ **       knowledge after construction; for _such_ cases, opaque-holder.hpp
+ **       might be a better fit.
  ** @see lib::TransformIter
  ** @see lib::explore
  **
  */
 
 
-#ifndef LIB_WRAPPER_H
-#define LIB_WRAPPER_H
+#ifndef LIB_ITEM_WRAPPER_H
+#define LIB_ITEM_WRAPPER_H
 
 #include "lib/error.hpp"
 #include "lib/nocopy.hpp"
@@ -55,32 +57,6 @@ namespace wrapper {
   
   
   
-  /**
-   * Reference wrapper implemented as constant function,
-   * returning the (fixed) reference on invocation
-   */
-  template<typename T>
-  class ReturnRef
-    {
-      T& ref_;
-      
-    public:
-      ReturnRef(T& target) : ref_(target) { }
-      T& operator() ()  const { return ref_;}
-    };
-  
-  template<typename T>
-  ReturnRef<T>
-  refFunction (T& target)
-  {
-    return ReturnRef<T> (target);
-  }
-  
-  
-  
-  
-  
-  
   /**
    * Universal value/ref wrapper accessible similar to a pointer.
    * A copyable, assignable value object to hold a given value within
@@ -387,4 +363,4 @@ namespace wrapper {
   
   
 }} // namespace lib::wrap
-#endif /*LIB_WRAPPER_H*/
+#endif /*LIB_ITEM_WRAPPER_H*/

src/lib/iter-explorer.hpp

@@ -103,7 +103,7 @@
 #include "lib/meta/duck-detector.hpp"
 #include "lib/meta/function.hpp"
 #include "lib/meta/trait.hpp"
-#include "lib/wrapper.hpp"
+#include "lib/item-wrapper.hpp"
 #include "lib/iter-adapter.hpp"
 #include "lib/iter-source.hpp"   /////////////TICKET #493 : only using the IterSource base feature / interface here. Should really split the iter-source.hpp
 #include "lib/iter-stack.hpp"

src/lib/itertools.hpp

@@ -69,10 +69,10 @@
 
 
 #include "lib/iter-adapter.hpp"
+#include "lib/item-wrapper.hpp"
 #include "lib/meta/value-type-binding.hpp"
 #include "lib/meta/function.hpp"
 #include "lib/meta/trait.hpp"
-#include "lib/wrapper.hpp"
 #include "lib/util.hpp"
 
 #include <functional>

src/lib/result.hpp

@@ -38,7 +38,7 @@
 #define LIB_RESULT_H
 
 #include "lib/error.hpp"
-#include "lib/wrapper.hpp"
+#include "lib/item-wrapper.hpp"
 #include "lib/meta/util.hpp"
 #include "lib/null-value.hpp"
 

src/lib/wrapper-function-result.hpp

@@ -23,7 +23,7 @@
 #ifndef LIB_WRAPPER_FUNCTION_RESULT_H
 #define LIB_WRAPPER_FUNCTION_RESULT_H
 
-#include "lib/wrapper.hpp"
+#include "lib/item-wrapper.hpp"
 #include "lib/meta/function.hpp"
 #include "lib/meta/function-closure.hpp"
 #include "lib/meta/util.hpp"

src/steam/control/memento-tie.hpp

@@ -34,8 +34,7 @@
 #include "lib/meta/maybe-compare.hpp"
 #include "lib/meta/function-closure.hpp"
 #include "steam/control/command-signature.hpp"
-//#include "lib/replaceable-item.hpp"
-#include "lib/wrapper.hpp"
+#include "lib/item-wrapper.hpp"
 #include "lib/format-obj.hpp"
 #include "lib/util.hpp"
 

tests/library/item-wrapper-test.cpp

@@ -23,7 +23,7 @@
 #include "lib/random.hpp"
 #include "lib/util.hpp"
 
-#include "lib/wrapper.hpp"
+#include "lib/item-wrapper.hpp"
 #include "lib/wrapper-function-result.hpp"
 
 #include <functional>

tests/vault/gear/activity-detector.hpp

@@ -73,7 +73,7 @@
 #include "lib/meta/variadic-rebind.hpp"
 #include "lib/meta/typeseq-util.hpp"
 #include "lib/meta/function.hpp"
-#include "lib/wrapper.hpp"
+#include "lib/item-wrapper.hpp"
 #include "lib/format-util.hpp"
 #include "lib/random.hpp"
 #include "lib/util.hpp"

wiki/thinkPad.ichthyo.mm

@@ -163620,7 +163620,20 @@ Since then others have made contributions, see the log for the history.</font></
 </node>
 <node CREATED="1748622765812" ID="ID_1447472606" MODIFIED="1748622792373" TEXT="Header aufr&#xe4;umen">
 <node CREATED="1748622795210" ID="ID_971344498" MODIFIED="1748622815722" TEXT="wrapper.hpp &#x27fc; item-wrapper.hpp"/>
-<node CREATED="1748622837148" ID="ID_1686776944" MODIFIED="1748622856501" TEXT="ReturnRef &#xfc;berfl&#xfc;ssig machen"/>
+<node COLOR="#5b280f" CREATED="1748622837148" ID="ID_1686776944" MODIFIED="1748642624085" TEXT="ReturnRef: bereits obsolet">
+<richcontent TYPE="NOTE"><html>
+  <head>
+    
+  </head>
+  <body>
+    <p>
+      ...hat bereits keinerlei Verwendungen mehr (hab es wohl schrittweise durch std::ref() ersetzt ... ohne eigens darauf zu achten)
+    </p>
+  </body>
+</html>
+</richcontent>
+<icon BUILTIN="button_cancel"/>
+</node>
 <node CREATED="1748622823574" ID="ID_518076065" MODIFIED="1748622828698" TEXT="Kommentar glattziehen"/>
 </node>
 </node>