**************
C++11 bindings
**************

.. role:: cpp(code)
   :language: c++
   :class: highlight
   
.. caution::

   DO NOT use the clause ``using namespace adios2`` in your code.
   This is in general a bad practices that creates potential name conflicts.
   Always use ``adios2::`` explicitly, *e.g.* ``adios2::ADIOS``, ``adios2::IO``.


.. tip::

   Prefer the C++11 bindings to take advantage of added functionality (*e.g.* move semantics, lambdas, etc.). If you must use an older C++ standard (98 or 03) to avoid application binary interface (ABI) incompatibilities use the C bindings.
   

ADIOS2 components classes
-------------------------

ADIOS2 C++ bindings objects are mapped 1-to-1 to the ADIOS components described in the :ref:`Components Overview` section.
Only the ``adios2::ADIOS`` object is "owned" by the developer's program using adios2, all other components are light-weight objects that point internally to a component that lives inside the ``adios2::ADIOS`` "factory" object.
 
.. code-block:: c++
   
   c++11                 
   adios2::ADIOS           
   adios2::IO            
   adios2::Variable<T>   
   adios2::Attribute<T>  
   adios2::Engine
   adios2::Operator

The following section provides a summary of the available functionality for each class.

:ref:`ADIOS` class
------------------

.. doxygenclass:: adios2::ADIOS
   :project: CXX11
   :path: ../../bindings/CXX11/adios2/cxx11/
   :members:
   
   
:ref:`IO` class
---------------

.. doxygenclass:: adios2::IO
   :project: CXX11
   :path: ../../bindings/CXX11/adios2/cxx11/
   :members:
   
:ref:`Variable` ``<T>`` class
-----------------------------

.. doxygenclass:: adios2::Variable
   :project: CXX11
   :path: ../../bindings/CXX11/adios2/cxx11/
   :members:


:ref:`Attribute` ``<T>`` class
------------------------------

.. doxygenclass:: adios2::Attribute
   :project: CXX11
   :path: ../../bindings/CXX11/adios2/cxx11/
   :members:


.. _C++11 Engine class:

:ref:`Engine` class
-------------------

.. doxygenclass:: adios2::Engine
   :project: CXX11
   :path: ../../bindings/CXX11/adios2/cxx11/
   :members:

:ref:`Operator` class
---------------------

.. doxygenclass:: adios2::Operator
   :project: CXX11
   :path: ../../bindings/CXX11/adios2/cxx11/
   :members:


**Debugging**

For debugging, ADIOS2 C++11 class instances and enums can be passed directly to ostreams,
as well as converted to human-readable strings via the ubiquitous ``ToString(object)`` member variable.
You can also directly pass objects to an ``ostream``.

Example:

.. code-block:: c++

    auto myVar = io.DefineVariable<double>("myVar");
    std::cout << myVar << " has shape id " << myVar.ShapeID() << std::endl;

    // will print:
    // Variable<double>(Name: "myVar") has shape id ShapeID::GlobalValue

    if (myVar.ShapeID() != adios2::ShapeID::GlobalArray)
    {
        throw std::invalid_argument("can't handle " +
                                    ToString(myVar.ShapeID()) + " in " +
                                    ToString(myVar));
    }

    // will throw exception like this:
    // C++ exception with description "can't handle ShapeID::GlobalValue
    // in Variable<double>(Name: "myVar")" thrown

**Group API**


.. doxygenclass:: adios2::Group
   :project: CXX11
   :path: ../../bindings/CXX11/adios2/cxx11/
   :members:

The Group API can be used for inquiring other group objects, variables, and attributes
by reading, provided that variable and attribute names were written in a tree-like
way similar that is used in a file system:

.. code-block:: bash

   "group1/group2/group3/variable1"
   "group1/group2/group3/attribute1"

A group object containing the tree structure is obtained by the
``InquireGroup`` function of the ``IO`` object.

.. code-block:: c++

   Group g = io.InquireGroup("group1");

Another group object can be generated by the predecessor group object.

.. code-block:: c++

   Group g1 = g.InquireGroup("group2");

The absolute path can be inquired or set explicitly

.. code-block:: c++

   std::string path =  g.InquirePath();
   g.setPath("group1/group2/group3");

Names of available groups, variables and attributes could be inquired:

.. code-block:: c++

   std::vector<std::string> groups = g.AvailableGroups();
   std::vector<std::string> variables = g.AvailableVariables();
   std::vector<std::string> attributes = g.AvailableVariables();

Finally, variables can be inquired

.. code-block:: c++

   auto var = g.InquireVariable("variable1");

An extra function is provided that returns a type of a variable

.. code-block:: c++

   DataType varType  = g.VariableType("variable1");


**Step selection**

Steps for reading can be selected using a pre-set parameter with as a file name
as a key and a list of selected steps separated by comma as a value.

.. code-block:: c++

   io.SetParameter(filename, "1,3");
