.. _safeddsgen_defining_a_type:

Defining a data type via IDL
============================

.. _safeddsgen_supported_types:

Supported IDL types
-------------------

Be aware that *Safe DDS Gen* is not case sensitive as it is specified in the
`IDL specification <https://www.omg.org/spec/IDL/4.2/PDF>`_.

.. note::

   Unsupported types will abort the file generation, leaving a static assert to alert the user.

.. _idl_primitive_types:

Primitive types
^^^^^^^^^^^^^^^

The following table shows the basic IDL types supported by *Safe DDS Gen* and how they are mapped to C++11.

.. list-table::
   :header-rows: 1

   * - IDL
     - C++11
   * - char
     - ``char``
   * - octet
     - ``uint8_t``
   * - short
     - ``int16_t``
   * - unsigned short
     - ``uint16_t``
   * - long
     - ``int32_t``
   * - unsigned long
     - ``uint32_t``
   * - long long
     - ``int64_t``
   * - unsigned long long
     - ``uint64_t``
   * - float
     - ``float``
   * - double
     - ``double``
   * - boolean
     - ``bool``
   * - string<N>
     - ``std::string``

Enumerations
^^^^^^^^^^^^

*Safe DDS Gen* supports enumerations.
Enumerations are always mapped to C++11 ``enum class``.

Unions
^^^^^^

*Safe DDS Gen* supports unions.
Unions are always mapped to a C++11 ``struct`` with a discriminator.

Constants
^^^^^^^^^

*Safe DDS Gen* supports constants.
Constants are always mapped to C++11 ``const`` variables.

Typedefs
^^^^^^^^

*Safe DDS Gen* supports type definitions.
Typedefs are always mapped to C++11 ``typedef`` aliases.

Arrays
^^^^^^

*Safe DDS Gen* supports single and multidimensional arrays.
Arrays are always mapped to C++11 ``std::array``.

Sequences
^^^^^^^^^

*Safe DDS Gen* supports bounded sequences.
Sequences are always mapped to C++11 ``std::vector``.

Maps
^^^^

*Safe DDS Gen* supports bounded maps.
Maps are always mapped to C++11 ``std::map``.

Optional
^^^^^^^^

*Safe DDS Gen* supports optional types.
Optional types are always mapped to C++11 ``eprosima::safedds::gen::Optional<T>`` template class.

Structures
^^^^^^^^^^

It is possible to define an IDL structure with a set of members with multiple types, which will be converted into a C struct.

The following IDL structure:

.. code-block:: idl

    struct Structure
    {
        octet octet_value;
        long long_value;
        octet octet_array[5];
    };

Would be converted to:

.. literalinclude:: ../../code/safeddsgen/SafeDDSGenCode.cpp
   :language: c++
   :start-after: // STRUCTURES_DATA_TYPE
   :end-before: //! STRUCTURES_DATA_TYPE

Structures can inherit from other structures, extending their member set.

.. code-block:: idl

    struct ParentStruct
    {
        octet parent_member;
    };

    struct ChildStruct : ParentStruct
    {
        long child_member;
    };

In this case, the resulting C++ code will be:

.. literalinclude:: ../../code/safeddsgen/SafeDDSGenCode.cpp
   :language: c++
   :start-after: // STRUCTURE_INHERITANCE
   :end-before: //! STRUCTURE_INHERITANCE

Including other IDL files
-------------------------

Other IDL files can be included in addition to the current IDL file.
*Safe DDS Gen* uses a C/C++ preprocessor for this purpose, and ``#include`` directive can be used to include an IDL file.

.. literalinclude:: ../../code/safeddsgen/SafeDDSGenCode.cpp
   :language: c++
   :start-after: // INCLUDE_MORE_IDL_FILES
   :end-before: //! INCLUDE_MORE_IDL_FILES

If *Safe DDS Gen* does not find a C/C++ preprocessor in default system paths, the preprocessor path can be specified using parameter ``--preprocessor <path>``.
The parameter ``--no-preprocessor`` can be used to disable the usage of the C/C++ preprocessor.