param.h

/* ********************************************************************
    itom software
    URL: http://www.uni-stuttgart.de/ito
    Copyright (C) 2020, Institut für Technische Optik (ITO),
    Universität Stuttgart, Germany
 
    This file is part of itom and its software development toolkit (SDK).
 
    itom is free software; you can redistribute it and/or modify it
    under the terms of the GNU Library General Public Licence as published by
    the Free Software Foundation; either version 2 of the Licence, or (at
    your option) any later version.
 
    In addition, as a special exception, the Institut für Technische
    Optik (ITO) gives you certain additional rights.
    These rights are described in the ITO LGPL Exception version 1.0,
    which can be found in the file LGPL_EXCEPTION.txt in this package.
 
    itom is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library
    General Public Licence for more details.
 
    You should have received a copy of the GNU Library General Public License
    along with itom. If not, see <http://www.gnu.org/licenses/>.
*********************************************************************** */
 
#pragma once
 
/* includes */
 
#include "byteArray.h"
#include "commonGlobal.h"
#include "paramMeta.h"
#include "retVal.h"
#include "typeDefs.h"
 
#include <algorithm>
#include <atomic>
#include <limits>
#include <stdarg.h>
#include <stdexcept>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
 
/* definition and macros */
/* global variables (avoid) */
/* content */
 
namespace ito {
class Param;
template <typename _Tp> struct ItomParamHelper;
 
const uint32 paramFlagMask = 0xFFFF0000; 
const uint32 paramTypeMask = 0x0000FFFF; 
 
struct complex128_
{
    float64 real;
    float64 imag;
};
 
union ParamBaseData {
    int8 i8Val;
 
    int32 i32Val;
 
    float64 f64Val;
 
    complex128_ c128Val;
 
    void* ptrVal;
};
 
//-------------------------------------------------------------------------------------
/* \brief Base class for parameter container.
 
   This base class only holds the name of the parameter, the type of the internal value,
   the value itself and
   some optional flags.
 */
class ITOMCOMMON_EXPORT ParamBase
{
public:
    /* For compatibility reasons with older versions of itom, values in this enumeration
       must only set bits in the range 17-32 of an uint32 value, since they can be
       used together with values of the Type enum below, using bits 1-16.
       Internally, the flags are stored as uint16 object, where these enumeration
       values are shifted by 16bits.
    */
    enum Flag
    {
        /* If this bit is set, this parameter should be automatically
        stored if for instance a plugin is closed and if the plugin
        with the same identifier is opened again, the parameter
        value will be tried to be reconstructed from the stored value. */
        NoAutosave = 0x010000,
 
        /* Flag to define this parameter to be readonly. It cannot for instance not be changed
        from Python. Internally, the setVal method does not check for Readonly.
        This has to be programmed manually. Plugins can also set or unset this flag
        during the runtime. */
        Readonly = 0x020000,
 
        /* Flag to mark this parameter as input value only.
        If a plugin defines this flag without the Out-flag, it pretends
        to only consume the given value, but the consumer will not change the value at any time.
        If the Out-flag is set, too, the consumer (e.g. plugin) will read and write the
        value, such that for instance a given dataObject will have another content after having
        called a method of a plugin. Return parameters of a method must never have the In-flag set.
        */
        In = 0x040000,
 
        /* Flag to mark this parameter, that the consumer will create or change
        the value of this parameter.
        This can be set together with In (or alone). All return parameters of an method in
        an algorithm plugin, must have this flag set. For other mandatory or optional
        input parameter, this flag can only be set together with In and means then,
        that the content of the given parameter will be changed by the called method. */
        Out = 0x080000,
 
        /* Flag to mark a parameter to be temporarily not available.
        Plugins can also set or unset this flag
        during the runtime. */
        NotAvailable = 0x100000,
    };
 
    enum Type
    {
        /* Helper-bit for all types that only contain a pointer to the real value and
        not the value itself. For these types, the caller need to keep the pointed object
        until both caller and called method do not use it any more! */
        Pointer = 0x0001,
 
        Char = 0x0002,
 
        Int = 0x0004,
 
        Double = 0x0008,
 
        Complex = 0x0400,
 
        DObjPtr = 0x0010 | Pointer,
 
        String = 0x0020 | Pointer,
 
        HWRef = 0x0040 | Pointer,
 
        CharArray = Char | Pointer,
 
        IntArray = Int | Pointer,
 
        DoubleArray = Double | Pointer,
 
        ComplexArray = Complex | Pointer,
 
        PointCloudPtr = 0x0080 | Pointer,
 
        PointPtr = 0x0100 | Pointer,
 
        PolygonMeshPtr = 0x0200 | Pointer,
 
        StringList = 0x0800 | Pointer
    };
 
 
    //--------------------------------------------------------------------------------------------
    //  CONSTRUCTORS, COPY-CONSTRUCTOR, DESTRUCTOR
    //--------------------------------------------------------------------------------------------
    ParamBase();
 
    // type-less ParamBase with name only
    ParamBase(const ByteArray& name);
 
    // constructor with type and name
    ParamBase(const ByteArray& name, const uint32 typeAndFlags);
 
    // constructor with name and type and char val
    ParamBase(const ByteArray& name, const uint32 typeAndFlags, const char* val);
 
    // constructor with name and type and float64 val
    ParamBase(const ByteArray& name, const uint32 typeAndFlags, const float64 val);
 
    // constructor with name and type and int32 val
    ParamBase(const ByteArray& name, const uint32 typeAndFlags, const int32 val);
 
    // constructor with name and type and complex128 val
    ParamBase(const ByteArray& name, const uint32 typeAndFlags, const complex128 val);
 
    // array constructor with name and type, size and array
    ParamBase(
        const ByteArray& name, const uint32 typeAndFlags, const uint32 size, const char* values);
 
    // array constructor with name and type, size and array
    ParamBase(
        const ByteArray& name, const uint32 typeAndFlags, const uint32 size, const int32* values);
 
    // array constructor with name and type, size and array
    ParamBase(
        const ByteArray& name, const uint32 typeAndFlags, const uint32 size, const float64* values);
 
    // array constructor with name and type, size and array
    ParamBase(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const uint32 size,
        const complex128* values);
 
    // array constructor with name and type, size and string list
    ParamBase(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const uint32 size,
        const ByteArray* values);
 
    virtual ~ParamBase();
 
    ParamBase(const ParamBase& other);
 
    ParamBase(ParamBase&& other) noexcept;
 
    //--------------------------------------------------------------------------------------------
    //  ASSIGNMENT AND OPERATORS
    //--------------------------------------------------------------------------------------------
 
    const ParamBase operator[](const int index) const;
 
    ParamBase& operator=(const ParamBase& rhs);
 
    inline ParamBase& operator=(ParamBase&& other) noexcept
    {
        if (this != &other)
        {
            std::swap(d, other.d);
        }
 
        return *this;
    }
 
    ito::RetVal copyValueFrom(const ito::ParamBase* rhs);
 
    //--------------------------------------------------------------------------------------------
    // COMPARISON OPERATORS (two values are equal if both their type and the content is equal)
    //--------------------------------------------------------------------------------------------
    bool operator==(const ParamBase& rhs) const;
 
    inline bool operator!=(const ParamBase& rhs) const
    {
        return !(*this == rhs);
    }
 
    //--------------------------------------------------------------------------------------------
    //  SET/GET FURTHER PROPERTIES
    //--------------------------------------------------------------------------------------------
 
    bool isNumeric(void) const;
 
    bool isNumericArray(void) const;
 
    bool isValid(void) const;
 
    uint16 getType() const;
 
    uint32 getFlags() const;
 
    void setFlags(const uint32 flags);
 
    const char* getName(void) const;
 
    ito::ByteArray getNameWithIndexSuffix(int index) const;
 
    bool getAutosave() const;
 
    void setAutosave(const bool autosave);
 
    /* The return value of this method depends on the type of parameter:
 
    For scalar parameters, like Char, Int, Double, Complex, 1 is always returned.
 
    For number array parameters (CharArray, IntArray, DoubleArray, ComplexArray, the
    number of values in the array is returned. Even if the array is a nullptr,
    0 is returned. This changed from itom 5.0 on. Before -1 was returned
    if the array is a nullptr (which is equal to a length of 0).
 
    StringList parameter behave like the other scalar parameters.
 
    For String parameters, the length of the string is returned, but
    -1 is returned if the internal string is nullptr.
 
    An invalid parameter will also return -1 always.
    */
    int getLen() const;
 
    template <typename _Tp> inline ito::RetVal setVal(_Tp val)
    {
        return ItomParamHelper<_Tp>::setVal(this, val, 0);
    }
 
    template <typename _Tp> inline ito::RetVal setVal(_Tp val, int len)
    {
        return ItomParamHelper<_Tp>::setVal(this, val, len);
    }
 
    template <typename _Tp> inline _Tp getVal() const
    {
        int len = 0;
        return ItomParamHelper<_Tp>::getVal(this, len);
    }
 
    template <typename _Tp> inline _Tp getVal(int& len) const
    {
        return ItomParamHelper<_Tp>::getVal(this, len);
    }
 
private:
    struct Data
    {
        Data(const ByteArray& name_ = "") : ref(0), flags(0), type(0), len(0), name(name_)
        {
            memset(&data, 0, sizeof(ParamBaseData));
        }
 
        std::atomic_int ref;
 
        ParamBaseData data;
 
        uint32 len;
 
        uint16 flags;
 
        uint16 type;
 
        ByteArray name;
    };
 
 
    mutable Data* d;
 
    void clearData(Data* data);
 
    /*
    \param allocNewArray if false, now new arrays, strings or string list
         memory is allocated and the len is set to 0. This should only be
         set to false, if it is assured that the memory is allocated by
         another part of the code.
    */
    void detach(bool allocNewArray = true);
 
    inline void decRefAndFree(Data* x)
    {
        if (x && (!(x->ref--)))
        {
            clearData(x);
            delete (x);
            x = nullptr;
        }
    }
 
    inline void incRef(Data* x)
    {
        if (x)
        {
            (x->ref)++;
        }
    }
 
    void setDefaultAutosaveFlag();
 
    void checkAndCorrectInOutFlag();
 
    template <typename _Tp> friend struct ItomParamHelper;
};
 
//----------------------------------------------------------------------------------------------------------------------------------
class ITOMCOMMON_EXPORT Param : public ParamBase
{
public:
    //--------------------------------------------------------------------------------------------
    //  CONSTRUCTORS, COPY-CONSTRUCTOR, DESTRUCTOR
    //--------------------------------------------------------------------------------------------
    /*
    This parameter has no documentation string and no meta information.
    The type is 0 (invalid).
    The name is empty.
    */
    Param();
 
    /*
    This parameter has no documentation string and no meta information.
    The type is 0 (invalid).
 
    \param name is the name of the parameter
    */
    Param(const ByteArray& name);
 
    /*
    This parameter has no documentation string and no meta information.
 
    \param name is the name of the parameter
    \type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
    e.g. ito::ParamBase::Char | ito::ParamBase::In for a read-only input parameter
    */
    Param(const ByteArray& name, const uint32 typeAndFlags);
 
    /*
    This parameter has no meta information. They can be added using setMetaInfo.
 
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::String | ito::ParamBase::In for a read-only input parameter
    \param val is the default string (const char*) of this parameter
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(const ByteArray& name, const uint32 typeAndFlags, const char* val, const char* info);
 
    /*
    This parameter will automatically get meta information of type ito::CharMeta with a minimum and
    maximum value.
 
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::Char | ito::ParamBase::In for a read-only input parameter
    \param minVal is the minimum allowed value (added to meta information)
    \param maxVal is the maximum allowed value (added to meta information)
    \param val is the default int8 value
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const char minVal,
        const char maxVal,
        const char val,
        const char* info);
 
    /*
    This parameter will automatically get meta information of type ito::IntMeta with a minimum and
    maximum value.
 
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
    e.g. ito::ParamBase::Int | ito::ParamBase::In for a read-only input parameter
    \param minVal is the minimum allowed value (added to meta information)
    \param maxVal is the maximum allowed value (added to meta information)
    \param val is the default int32 value
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const int32 minVal,
        const int32 maxVal,
        const int32 val,
        const char* info);
 
    /*
    This parameter will automatically get meta information of type ito::DoubleMeta with a minimum
    and maximum value.
 
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
    e.g. ito::ParamBase::Double | ito::ParamBase::In for a read-only input parameter
    \param minVal is the minimum allowed value (added to meta information)
    \param maxVal is the maximum allowed value (added to meta information)
    \param val is the default float64 value
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const float64 minVal,
        const float64 maxVal,
        const float64 val,
        const char* info);
 
    /*
    This parameter has no meta information. They can be added using setMetaInfo.
 
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::CharArray | ito::ParamBase::In for a read-only input parameter
    \param size is the size of the given default values array
    \param values is the default int8 array value
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const unsigned int size,
        const char* values,
        const char* info); // array constructor with name and type, size and array
 
    /*
    This parameter has no meta information. They can be added using setMetaInfo.
 
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::IntArray | ito::ParamBase::In for a read-only input parameter
    \param size is the size of the given default values array
    \param values is the default int32 array value
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const unsigned int size,
        const int32* values,
        const char* info);
 
    /*
    This parameter has no meta information. They can be added using setMetaInfo.
 
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::DoubleArray | ito::ParamBase::In for a read-only input parameter
    \param size is the size of the given default values array
    \param values is the default float64 array value
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const unsigned int size,
        const float64* values,
        const char* info);
 
    /*
    This parameter has no meta information.
 
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::ComplexArray | ito::ParamBase::In for a read-only input parameter
    \param size is the size of the given default values array
    \param values is the default complex array value
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const unsigned int size,
        const complex128* values,
        const char* info);
 
    /*
    This parameter has no meta information.
 
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::ComplexArray | ito::ParamBase::In for a read-only input parameter
    \param size is the size of the given default values array
    \param values is the default ByteArray list
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const unsigned int size,
        const ByteArray* values,
        const char* info);
 
    /*
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::Char | ito::ParamBase::In for a read-only input parameter
    \param val is the default value
    \param meta might be nullptr, if no meta information should be passed to this parameter.
        If a pointer is given, it has to be an object of ito::CharMeta.
        The ownership is taken by this parameter!
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const char val,
        ParamMeta* meta,
        const char* info);
 
    /*
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::Int | ito::ParamBase::In for a read-only input parameter
    \param val is the default value
    \param meta might be nullptr, if no meta information should be passed to this parameter.
        If a pointer is given, it has to be an object of ito::IntMeta.
        The ownership is taken by this parameter!
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const int32 val,
        ParamMeta* meta,
        const char* info);
 
    /*
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::Double | ito::ParamBase::In for a read-only input parameter
    \param val is the default value
    \param meta might be nullptr, if no meta information should be passed to this parameter.
        If a pointer is given, it has to be an object of ito::DoubleMeta.
        The ownership is taken by this parameter!
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const float64 val,
        ParamMeta* meta,
        const char* info);
 
    /*
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
    e.g. ito::ParamBase::Complex | ito::ParamBase::In for a read-only input parameter
    \param val is the default value
    \param meta might be nullptr, if no meta information should be passed to this parameter.
        Currently, there is no meta information class for complex value parameters!
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const complex128 val,
        ParamMeta* meta,
        const char* info);
 
    /*
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::CharArray | ito::ParamBase::In for a read-only input parameter
    \param size is the length of the default array, passed to values
    \param values is the pointer to the default array of values
    \param meta might be nullptr, if no meta information should be passed to this parameter.
        If a pointer is given, it has to be an object of ito::CharArrayMeta.
        The ownership is taken by this parameter!
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const unsigned int size,
        const char* values,
        ParamMeta* meta,
        const char* info);
 
    /*
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::IntArray | ito::ParamBase::In for a read-only input parameter
    \param size is the length of the default array, passed to values
    \param values is the pointer to the default array of values
    \param meta might be nullptr, if no meta information should be passed to this parameter.
        If a pointer is given, it has to be an object of ito::IntArrayMeta, ito::IntervalMeta,
        ito::RangeMeta or ito::RectMeta.
        The ownership is taken by this parameter!
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const unsigned int size,
        const int32* values,
        ParamMeta* meta,
        const char* info);
 
    /*
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::DoubleArray | ito::ParamBase::In for a read-only input parameter
    \param size is the length of the default array, passed to values
    \param values is the pointer to the default array of values
    \param meta might be nullptr, if no meta information should be passed to this parameter.
        If a pointer is given, it has to be an object of ito::DoubleArrayMeta or
    ito::DoubleIntervalMeta. The ownership is taken by this parameter! \param info can be a
    documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const unsigned int size,
        const float64* values,
        ParamMeta* meta,
        const char* info);
 
    /*
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::ComplexArray | ito::ParamBase::In for a read-only input parameter
    \param size is the length of the default array, passed to values
    \param values is the pointer to the default array of values
    \param meta might be nullptr, if no meta information should be passed to this parameter.
        If a pointer is given, the ownership is taken by this parameter!
        Currently, there is no meta information class available for complex array parameters!
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const unsigned int size,
        const complex128* values,
        ParamMeta* meta,
        const char* info);
 
    /*
    \param name is the name of the parameter
    \param type is a flag mask, that might consists of combinations of ito::ParamBase::Type,
        e.g. ito::ParamBase::ComplexArray | ito::ParamBase::In for a read-only input parameter
    \param size is the length of the default array, passed to values
    \param values is the pointer to the default string list values
    \param meta might be nullptr, if no meta information should be passed to this parameter.
        If a pointer is given, the ownership is taken by this parameter!
        Currently, there is no meta information class available for complex array parameters!
    \param info can be a documentation string for this parameter, an empty string or nullptr
    */
    Param(
        const ByteArray& name,
        const uint32 typeAndFlags,
        const unsigned int size,
        const ByteArray* values,
        ParamMeta* meta,
        const char* info);
 
    ~Param();
 
    Param(const Param& copyConstr);
 
    Param(Param&& rvalue);
 
    //--------------------------------------------------------------------------------------------
    //  ASSIGNMENT AND OPERATORS
    //--------------------------------------------------------------------------------------------
 
    const Param operator[](const int index) const;
 
    Param& operator=(const Param& rhs);
 
    Param& operator=(Param&& rvalue) noexcept;
 
    ito::RetVal copyValueFrom(const ParamBase* rhs);
 
private:
    struct MetaShared
    {
        MetaShared(ParamMeta* m) : meta(m), ref(0)
        {
        }
 
        ParamMeta* meta;
        std::atomic_int ref;
    };
 
    MetaShared* m_pMetaShared;
 
    ByteArray m_info;
 
    /* call this method, if the internal meta object
    is likely to be changed. If so, a deep copy of the
    internal meta object will be done (if it is currently shared),
    such that other Param objects are not affected by the possible meta
    change. */
    void detachMeta();
 
    inline void incRefMeta(MetaShared* ms) const
    {
        if (ms)
        {
            ms->ref++;
        }
    }
 
    inline void decRefMeta(MetaShared* ms) const
    {
        if (ms && !(ms->ref--))
        {
            delete ms->meta;
            delete ms;
            ms = nullptr;
        }
    }
 
public:
    //--------------------------------------------------------------------------------------------
    //  SET/GET FURTHER PROPERTIES
    //--------------------------------------------------------------------------------------------
    inline const char* getInfo() const
    {
        return m_info.data();
    }
 
    inline void setInfo(const char* info)
    {
        m_info = info;
    }
 
    inline void setInfo(const ByteArray& info)
    {
        m_info = info;
    }
 
    inline const ParamMeta* getMeta() const
    {
        return m_pMetaShared ? m_pMetaShared->meta : nullptr;
    }
 
    inline const ParamMeta* getConstMeta() const
    {
        return m_pMetaShared ? m_pMetaShared->meta : nullptr;
    }
 
    inline ParamMeta* getMeta(void)
    {
        if (m_pMetaShared && m_pMetaShared->ref > 0)
        {
            // decouple the internal meta object, since it
            // could be changed by the caller of this method.
            detachMeta();
        }
 
        return m_pMetaShared ? m_pMetaShared->meta : nullptr;
    }
 
    /*
    Example: intParam.getMetaT<ito::IntMeta>();
 
    Usually, it is more explicit to call getConstMetaT instead of this method.
    */
    template <typename _Tp> inline const _Tp* getMetaT(void) const
    {
        if (m_pMetaShared)
        {
            return static_cast<const _Tp*>(m_pMetaShared->meta);
        }
 
        return nullptr;
    }
 
    /*
    Example: intParam.getMetaT<ito::IntMeta>();
    */
    template <typename _Tp> inline const _Tp* getConstMetaT(void) const
    {
        if (m_pMetaShared)
        {
            return static_cast<const _Tp*>(m_pMetaShared->meta);
        }
 
        return nullptr;
    }
 
    /*
    Example: intParam.getMetaT<ito::IntMeta>();
    */
    template <typename _Tp> inline _Tp* getMetaT(void)
    {
        if (m_pMetaShared)
        {
            if (m_pMetaShared->ref > 0)
            {
                // decouple the internal meta object, since it
                // could be changed by the caller of this method.
                detachMeta();
            }
 
            return static_cast<_Tp*>(m_pMetaShared->meta);
        }
 
        return nullptr;
    }
 
 
    void setMeta(ParamMeta* meta, bool takeOwnership = false);
 
    /* The returned value is only valid, if a meta has been set and if it
    contains a minimum value. Else -Inf is returned. */
    float64 getMin() const;
 
    /* The returned value is only valid, if a meta has been set and if it
    contains a maximum value. Else +Inf is returned. */
    float64 getMax() const;
};
 
//-------------------------------------------------------------------------------------
/* template helper class (with template specializations) for getting or setting
   the value of the parameter. These classes must be defined in the header file.
   This class is a friend of ito::ParamBase.
 */
template <typename _Tp> struct ItomParamHelper
{
    static ito::RetVal setVal(ito::ParamBase* param, const _Tp val, int len = 0)
    {
        static_assert(std::is_pointer<_Tp>::value, "unsupported template type.");
 
        switch (param->d->type)
        {
        case ito::ParamBase::HWRef:
        case ito::ParamBase::DObjPtr:
        case ito::ParamBase::PointCloudPtr:
        case ito::ParamBase::PointPtr:
        case ito::ParamBase::PolygonMeshPtr: {
            param->detach();
            param->d->data.ptrVal = (void*)(reinterpret_cast<const void*>(val));
            return ito::retOk;
        }
 
        case ito::ParamBase::String:{
            param->detach(false);
            auto cVal_ = param->d->data.ptrVal;
 
            if (val)
            {
                int str_len = static_cast<int>(strlen((const char*)val));
 
                if (((ito::uint32)str_len != param->d->len) || (param->d->data.ptrVal == nullptr))
                {
                    param->d->data.ptrVal = new char[str_len + 1];
                }
                else
                {
                    cVal_ = nullptr;
                }
 
                std::copy_n((const char*)val, str_len + 1, (char*)param->d->data.ptrVal);
                param->d->len = str_len;
            }
            else
            {
                param->d->data.ptrVal = 0;
                param->d->len = 0;
            }
 
            if (cVal_)
            {
                delete[](char*) cVal_;
            }
        }
            return ito::retOk;
        case ito::ParamBase::CharArray:{
            param->detach(false);
            auto cVal_ = param->d->data.ptrVal;
 
            if ((val) && (len > 0))
            {
                if ((ito::uint32)len != param->d->len)
                {
                    param->d->data.ptrVal = new char[len];
                    param->d->len = len;
                }
                else
                {
                    cVal_ = nullptr;
                }
 
                std::copy_n((const char*)val, len, (char*)param->d->data.ptrVal);
            }
            else
            {
                param->d->data.ptrVal = nullptr;
                param->d->len = 0;
            }
 
            if (cVal_)
            {
                delete[](char*) cVal_;
            }
        }
             return ito::retOk;
        case ito::ParamBase::IntArray:{
            param->detach(false);
            auto cVal_ = param->d->data.ptrVal;
 
            if ((val) && (len > 0))
            {
                if ((ito::uint32)len != param->d->len)
                {
                    param->d->data.ptrVal = new int32[len];
                    param->d->len = len;
                }
                else
                {
                    cVal_ = nullptr;
                }
 
                std::copy_n((const int32*)val, len, (int32*)param->d->data.ptrVal);
            }
            else
            {
                param->d->data.ptrVal = nullptr;
                param->d->len = 0;
            }
 
            if (cVal_)
            {
                delete[](int32*) cVal_;
            }
        }
            return ito::retOk;
        case ito::ParamBase::DoubleArray:{
            param->detach(false);
            auto cVal_ = param->d->data.ptrVal;
 
            if ((val) && (len > 0))
            {
                if ((ito::uint32)len != param->d->len)
                {
                    param->d->data.ptrVal = new float64[len];
                    param->d->len = len;
                }
                else
                {
                    cVal_ = nullptr;
                }
 
                std::copy_n((const float64*)val, len, (float64*)param->d->data.ptrVal);
            }
            else
            {
                param->d->data.ptrVal = nullptr;
                param->d->len = 0;
            }
 
            if (cVal_)
            {
                delete[](float64*) cVal_;
            }
        }
            return ito::retOk;
        case ito::ParamBase::ComplexArray:{
            param->detach(false);
            auto cVal_ = param->d->data.ptrVal;
 
            if ((val) && (len > 0))
            {
                if ((ito::uint32)len != param->d->len)
                {
                    param->d->data.ptrVal = new complex128[len];
                    param->d->len = len;
                }
                else
                {
                    cVal_ = nullptr;
                }
 
                std::copy_n((const complex128*)val, len, (complex128*)param->d->data.ptrVal);
            }
            else
            {
                param->d->data.ptrVal = nullptr;
                param->d->len = 0;
            }
 
            if (cVal_)
            {
                delete[](complex128*) cVal_;
            }
        }
            return ito::retOk;
        case ito::ParamBase::StringList:{
            param->detach(false);
            auto cVal_ = param->d->data.ptrVal;
 
            if ((val) && (len > 0))
            {
                ito::ByteArray* dest = new ito::ByteArray[len];
                param->d->data.ptrVal = dest;
 
                for (int i = 0; i < len; ++i)
                {
                    dest[i] = ((const ito::ByteArray*)(val))[i]; // operator=
                }
 
                param->d->len = len;
            }
            else
            {
                param->d->data.ptrVal = nullptr;
                param->d->len = 0;
            }
 
            if (cVal_)
            {
                delete[](ito::ByteArray*) cVal_;
            }
        }
            return ito::retOk;
        default:
            return ito::RetVal(
                ito::retError,
                0,
                "_Tp parameter of setVal<_Tp> does not match the type of the parameter");
        }
    }
 
    static _Tp getVal(const ito::ParamBase* param, int& len)
    {
        static_assert(std::is_pointer<_Tp>::value, "unsupported template type.");
 
        if (std::is_pointer<_Tp>::value)
        {
            if (std::is_same<_Tp, ito::ByteArray*>::value ||
                std::is_same<_Tp, void*>::value ||
                std::is_same<_Tp, char*>::value ||
                std::is_same<_Tp, ito::int8*>::value ||
                std::is_same<_Tp, ito::int16*>::value ||
                std::is_same<_Tp, ito::int32*>::value ||
                std::is_same<_Tp, ito::float32*>::value ||
                std::is_same<_Tp, ito::float64*>::value ||
                std::is_same<_Tp, ito::complex64*>::value ||
                std::is_same<_Tp, ito::complex128*>::value)
            {
                const_cast<ito::ParamBase*>(param)->detach();
            }
        }
 
        switch (param->d->type)
        {
        case ito::ParamBase::String:
            if (param->d->data.ptrVal)
            {
                len = static_cast<int>(strlen((const char*)param->d->data.ptrVal));
                return reinterpret_cast<_Tp>((char*)param->d->data.ptrVal);
            }
            else
            {
                len = 0;
                return nullptr;
            }
 
        case ito::ParamBase::CharArray:
        case ito::ParamBase::IntArray:
        case ito::ParamBase::DoubleArray:
        case ito::ParamBase::ComplexArray:
        case ito::ParamBase::StringList:
            if (param->d->data.ptrVal)
            {
                len = param->d->len;
                return reinterpret_cast<_Tp>((char*)param->d->data.ptrVal);
            }
            else
            {
                len = 0;
                return nullptr;
            }
 
        case ito::ParamBase::HWRef:
        case ito::ParamBase::DObjPtr:
        case ito::ParamBase::PointCloudPtr:
        case ito::ParamBase::PointPtr:
        case ito::ParamBase::PolygonMeshPtr:
            return reinterpret_cast<_Tp>((char*)param->d->data.ptrVal);
 
        default:
            throw std::logic_error("Param::getVal<_Tp>: Non-matching type!");
        }
    }
};
 
template <> struct ItomParamHelper<float64>
{
    static ito::RetVal setVal(ito::ParamBase* param, float64 val, int /*len = 0*/)
    {
        param->detach();
 
        switch (param->d->type)
        {
        case ito::ParamBase::Char:
            param->d->data.i8Val = static_cast<int8>(val);
            return ito::retOk;
        case ito::ParamBase::Int:
            param->d->data.i32Val = static_cast<int32>(val);
            return ito::retOk;
        case ito::ParamBase::Double:
            param->d->data.f64Val = val;
            return ito::retOk;
        case ito::ParamBase::Complex:
            param->d->data.c128Val.real = val;
            param->d->data.c128Val.imag = 0.0;
            return ito::retOk;
        default:
            return ito::RetVal(
                ito::retError,
                0,
                "float64 value passed to setVal<float64> does not match the type of the parameter");
        }
    }
 
    static float64 getVal(const ito::ParamBase* param, int& /*len*/)
    {
        switch (param->d->type)
        {
        case ito::ParamBase::Char:
            return static_cast<float64>(param->d->data.i8Val);
        case ito::ParamBase::Int:
            return static_cast<float64>(param->d->data.i32Val);
        case ito::ParamBase::Double:
            return param->d->data.f64Val;
        case ito::ParamBase::Complex:
            return param->d->data.c128Val.real;
        default:
            throw std::logic_error("Param::getVal<float64>: Non-matching type!");
        }
    }
};
 
template <> struct ItomParamHelper<int32>
{
    static ito::RetVal setVal(ito::ParamBase* param, int32 val, int /*len = 0*/)
    {
        param->detach();
 
        switch (param->d->type)
        {
        case ito::ParamBase::Char:
            param->d->data.i8Val = static_cast<int8>(val);
            return ito::retOk;
        case ito::ParamBase::Int:
            param->d->data.i32Val = val;
            return ito::retOk;
        case ito::ParamBase::Double:
            param->d->data.f64Val = static_cast<float64>(val);
            return ito::retOk;
        case ito::ParamBase::Complex:
            param->d->data.c128Val.real = static_cast<float64>(val);
            param->d->data.c128Val.imag = 0.0;
            return ito::retOk;
        default:
            return ito::RetVal(
                ito::retError,
                0,
                "int32 value passed to setVal<int32> does not match the type of the parameter");
        }
    }
 
    static int32 getVal(const ito::ParamBase* param, int& /*len*/)
    {
        switch (param->d->type)
        {
        case ito::ParamBase::Char:
            return param->d->data.i8Val;
        case ito::ParamBase::Int:
            return param->d->data.i32Val;
        case ito::ParamBase::Double:
            return static_cast<int32>(param->d->data.f64Val);
        case ito::ParamBase::Complex:
            return static_cast<int32>(param->d->data.c128Val.real);
        case 0:
            throw std::invalid_argument("Param::getVal<int32>: non existent parameter");
 
        default:
            throw std::logic_error("Param::getVal<int32>: Non-matching type!");
        }
    }
};
 
template <> struct ItomParamHelper<int8>
{
    static ito::RetVal setVal(ito::ParamBase* param, int8 val, int /*len = 0*/)
    {
        param->detach();
 
        switch (param->d->type)
        {
        case ito::ParamBase::Char:
            param->d->data.i8Val = static_cast<int8>(val);
            return ito::retOk;
        case ito::ParamBase::Int:
            param->d->data.i32Val = static_cast<int32>(val);
            return ito::retOk;
        case ito::ParamBase::Double:
            param->d->data.f64Val = static_cast<float64>(val);
            return ito::retOk;
        case ito::ParamBase::Complex:
            param->d->data.c128Val.real = static_cast<float64>(val);
            param->d->data.c128Val.imag = 0.0;
            return ito::retOk;
        default:
            return ito::RetVal(
                ito::retError,
                0,
                "char value passed to setVal<int8> does not match the type of the parameter");
        }
    }
 
    static int8 getVal(const ito::ParamBase* param, int& /*len*/)
    {
        switch (param->d->type)
        {
        case ito::ParamBase::Int:
            return static_cast<int8>(param->d->data.i8Val);
        case ito::ParamBase::Char:
            return static_cast<int8>(param->d->data.i32Val);
        case ito::ParamBase::Double:
            return static_cast<int8>(param->d->data.f64Val);
        case ito::ParamBase::Complex:
            return static_cast<int8>(param->d->data.c128Val.real);
        case 0:
            throw std::invalid_argument("Param::getVal<int8>: non existent parameter");
 
        default:
            throw std::logic_error("Param::getVal<int8>: Non-matching type!");
        }
    }
};
 
template <> struct ItomParamHelper<char>
{
    static ito::RetVal setVal(ito::ParamBase* param, char val, int /*len = 0*/)
    {
        param->detach();
 
        switch (param->d->type)
        {
        case ito::ParamBase::Char:
            param->d->data.i8Val = static_cast<int8>(val);
            return ito::retOk;
        case ito::ParamBase::Int:
            param->d->data.i32Val = static_cast<int32>(val);
            return ito::retOk;
        case ito::ParamBase::Double:
            param->d->data.f64Val = static_cast<float64>(val);
            return ito::retOk;
        case ito::ParamBase::Complex:
            param->d->data.c128Val.real = static_cast<float64>(val);
            param->d->data.c128Val.imag = 0.0;
            return ito::retOk;
        default:
            return ito::RetVal(
                ito::retError,
                0,
                "char value passed to setVal<char> does not match the type of the parameter");
        }
    }
 
    static char getVal(const ito::ParamBase* param, int& /*len*/)
    {
        switch (param->d->type)
        {
        case ito::ParamBase::Int:
            return static_cast<char>(param->d->data.i8Val);
        case ito::ParamBase::Char:
            return static_cast<char>(param->d->data.i32Val);
        case ito::ParamBase::Double:
            return static_cast<char>(param->d->data.f64Val);
        case ito::ParamBase::Complex:
            return static_cast<char>(param->d->data.c128Val.real);
        case 0:
            throw std::invalid_argument("Param::getVal<char>: non existent parameter");
 
        default:
            throw std::logic_error("Param::getVal<char>: Non-matching type!");
        }
    }
};
 
template <> struct ItomParamHelper<complex128>
{
    static ito::RetVal setVal(ito::ParamBase* param, const complex128 val, int /*len = 0*/)
    {
        param->detach();
 
        switch (param->d->type)
        {
        case ito::ParamBase::Complex:
            param->d->data.c128Val.real = val.real();
            param->d->data.c128Val.imag = val.imag();
            return ito::retOk;
        default:
            return ito::RetVal(
                ito::retError,
                0,
                "complex128 value passed to setVal<complex128> does not match the type of the "
                "parameter");
        }
    }
 
    static complex128 getVal(const ito::ParamBase* param, int& /*len*/)
    {
        switch (param->d->type)
        {
        case ito::ParamBase::Char:
            return complex128(param->d->data.i8Val, 0.0);
        case ito::ParamBase::Int:
            return complex128(param->d->data.i32Val, 0.0);
        case ito::ParamBase::Double:
            return complex128(param->d->data.f64Val, 0.0);
        case ito::ParamBase::Complex:
            return complex128(param->d->data.c128Val.real, param->d->data.c128Val.imag);
        default:
            throw std::logic_error("Param::getVal<complex128>: Non-matching type!");
        }
    }
};
 
} // end namespace ito