EQ2EMu/EQ2/source/depends/boost_1_72_0/libs/gil/doc/design/technicalities.rst

Technicalities
==============

.. contents::
   :local:
   :depth: 2

Creating a reference proxy
--------------------------

Sometimes it is necessary to create a proxy class that represents a
reference to a given object. Examples of these are GIL's reference to
a planar pixel (``planar_pixel_reference``) and GIL's sub-byte channel
references. Writing a reference proxy class can be tricky. One problem
is that the proxy reference is constructed as a temporary object and
returned by value upon dereferencing the iterator:

.. code-block:: cpp

  struct rgb_planar_pixel_iterator
  {
   typedef my_reference_proxy<T> reference;
   reference operator*() const { return reference(red,green,blue); }
  };

The problem arises when an iterator is dereferenced directly into a
function that takes a mutable pixel:

.. code-block:: cpp

  template <typename Pixel>    // Models MutablePixelConcept
  void invert_pixel(Pixel& p);

  rgb_planar_pixel_iterator myIt;
  invert_pixel(*myIt);        // compile error!

C++ does not allow for matching a temporary object against a non-constant
reference. The solution is to:

* Use const qualifier on all members of the reference proxy object:

.. code-block:: cpp

    template <typename T>
    struct my_reference_proxy
    {
      const my_reference_proxy& operator=(const my_reference_proxy& p) const;
      const my_reference_proxy* operator->() const { return this; }
      ...
    };

* Use different classes to denote mutable and constant reference
  (maybe based on the constness of the template parameter)

* Define the reference type of your iterator with const qualifier:

.. code-block:: cpp

    struct iterator_traits<rgb_planar_pixel_iterator>
    {
      typedef const my_reference_proxy<T> reference;
    };

A second important issue is providing an overload for ``swap`` for
your reference class. The default ``std::swap`` will not work
correctly. You must use a real value type as the temporary. A further
complication is that in some implementations of the STL the ``swap``
function is incorrectly called qualified, as ``std::swap``. The only
way for these STL algorithms to use your overload is if you define it
in the ``std`` namespace:

.. code-block:: cpp

  namespace std
  {
   template <typename T>
   void swap(my_reference_proxy<T>& x, my_reference_proxy<T>& y)
   {
      my_value<T> tmp=x;
      x=y;
      y=tmp;
   }
  }

Lastly, remember that constructors and copy-constructors of proxy
references are always shallow and assignment operators are deep.

We are grateful to Dave Abrahams, Sean Parent and Alex Stepanov for
suggesting the above solution.