.. oe:namespace:: OESystem



.. meta::
   :keywords: OEOwnedPtr, OwnedPtr


.. _OESystem_OEOwnedPtr:

.. oe:class:: OEOwnedPtr

   .. oe:api::

      template<class T>
      class OEOwnedPtr

   .. warning::

      This class has been deprecated. Use ``std::unique_ptr`` instead.
      C++ only class. This class is not visible in any other languages.

   This class is a classic `smart pointer
   <http://en.wikipedia.org/wiki/Smart_pointer>`_ used for
   automatically managing the dynamic memory allocated for the object
   ``T``. Explicitly calling ``delete`` is generally frowned upon
   in modern C++ due to the propensity of explicit ``delete`` leading
   to resource leaks and crashes. Deleting memory should be handled
   more automatically by mechanisms like
   :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` and :ref:`OESharedPtr <OESystem_OESharedPtr>`.

   :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` is designed to mimic the C++11
   `std::unique_ptr
   <http://en.cppreference.com/w/cpp/memory/unique_ptr>`_ in
   functionality with some important differences.

   The first and most obvious difference is that
   :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` will compile and work in non-C++11
   compilers. This provides the convenience and safety of
   `std::unique_ptr
   <http://en.cppreference.com/w/cpp/memory/unique_ptr>`_ without
   having to wait for every *OpenEye* platform to support C++11. That
   means the following will compile on all *OpenEye* supported
   platforms:

   .. code-block:: c++

      struct Foo { };

      struct BarOwnsFoo
      {
        OEOwnedPtr<Foo> _owned;
        Foo *GetFoo() { return _owned; }
      };

   .. note::

      Users are free to use C++11 features with the OpenEye toolkits in
      their own code. OpenEye will be slowly phasing in more support
      for C++11 features over many releases. For example,
      :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` has `move constructors
      <http://en.cppreference.com/w/cpp/language/move_constructor>`_
      to allow for the following idiom to work in C++11 compilers:

      .. code-block:: c++

         OEOwnedPtr<Foo> MakeFoo()
         {
           return OEOwnedPtr<Foo>(new Foo);
         };

   The second key difference between :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>`
   and `std::unique_ptr
   <http://en.cppreference.com/w/cpp/memory/unique_ptr>`_ is whether
   ``const`` is maintained when accessing the object being pointed
   to. By default, in order to maintain compatibility with C, C++
   allows non-const access to const pointers. By extension, this same
   rule applied to C++ smart pointers. This leads to very surprising
   behavior like the following:

   .. code-block:: c++

      struct Foo
      {
        int _x;
        void AlterFoo() { _x = 1; }
      };

      struct BarOwnsFoo
      {
        Foo *_foo;
        void AConstMethod() const { _foo->AlterFoo(); }
      };

   Even though ``AConstMethod`` is ``const``, it isn't actually
   logically const. The internals of the class are changing. This
   behavior may seem benign at first, but it has vast implications in
   a library seeking to be thread-safe. The ``const`` on a method
   implies that the method is thread-safe, especially in C++11. In
   order to enforce thread-safety at runtime,
   :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` maintains the "const'ness" of its
   accessor methods. Therefore, the following is actually a compile
   error:

   .. code-block:: c++

      struct Foo
      {
        int _x;
        void AlterFoo() { _x = 1; }
      };

      struct BarOwnsFoo
      {
        OEOwnedPtr<Foo> _foo;
        void AConstMethod() const { _foo->AlterFoo(); }
      };

   Catching thread-safety problems very early, at compilation, is
   highly desirable for *OpenEye*. Hence the reason to differ from the
   standard smart pointer semantics in this way.

   .. oe:method:: Constructors

      .. oe:api::

         OEOwnedPtr()
         OEOwnedPtr(T* ptr)

      Default constructors the pointer to ``NULL``. Or constructs a
      smart pointer around the pointer ``ptr``.

      .. oe:api::

         OEOwnedPtr(OEOwnedPtr&& rhs)

      Move constructor to safely transfer ownership of the underlying
      pointer from one :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` to another. This
      allows :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` to be usable in container
      objects like ``std::vector`` in C++11 compatible compilers.

   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OEOwnedPtr<T>& operator=(T* rhs)

      Construct a smart pointer around the pointer ``ptr``.

      .. warning::

         :ref:`OEOwnedPtr <OESystem_OEOwnedPtr>` does not have a copy
         constructor or assignment operator for very good
         reason. It does not know how to properly deep copy the
         pointer, or how to properly "share" the pointer among
         multiple users. If this behavior is desired, for example,
         to use a smart pointer inside an ``std::vector`` prior to
         C++11, use :ref:`OESharedPtr <OESystem_OESharedPtr>` instead.

      .. oe:api::

         OEOwnedPtr<T>& operator=(OEOwnedPtr<T>&& rhs)

      Move assignment operator to work around the above warning
      message. This is only available in C++11 compatible compilers.

      Assignment operator.


   .. oe:method:: operator*
      :language: c++

      .. oe:api::

         T& operator*()
         const T& operator*() const

      Dereference the smart pointer and return a reference to the held
      object while maintaining ``const`` correctness. Note,
      dereferencing a ``NULL`` pointer is undefined.

   .. oe:method:: operator->
      :language: c++

      .. oe:api::

         T* operator->()
         const T* operator->() const

      Access the pointer held by this smart pointer while maintaining
      ``const`` correctness.

   .. oe:method:: operator T *
      :language: c++

      .. oe:api::

         operator T *()

      Implicit conversion to a pointer to ``T``.

   .. oe:method:: operator const T *
      :language: c++

      .. oe:api::

         operator const T *() const

      Implicit conversion to a pointer to ``const T``.

   .. oe:method:: Get

      .. oe:api::

         T* Get()
         const T* Get() const

      Access the pointer held by this smart pointer while maintaining
      ``const`` correctness.

   .. oe:method:: Release

      .. oe:api::

         T* Release()

      Returns the pointer owned by this smart pointer. The smart
      pointer will cease to "own" the pointer in question. The smart
      pointer will effectively become a ``NULL`` pointer.

      .. warning::

         The user is expected to ``delete`` the pointer, usually by
         passing to a different smarter pointer class immediately.
