UN_CustomData.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UN_NodeData.h ( UN Library, C++)
 *
 * COMMENTS:
 *      
 */

#ifndef __UN_CustomData_h__
#define __UN_CustomData_h__

#include "UN_API.h"
#include "UN_DataBuffer.h"
#include "UN_DataIndexMap.h"
#include <UT/UT_UniquePtr.h>

class UN_Data;
class UN_DataMergeInfo;
class UN_CustomData;
using UN_CustomDataPtr = UT_UniquePtr<UN_CustomData>;


// ============================================================================
/// Container for custom data in UN. 
/// It is intended to hold vectorized buffers indexed by data index value.
/// However, the UN API functions and methods usually operate on data IDs,
/// so this class provides a mapping from an ID to an INDEX.
class UN_CustomData 
{
public:
    /// Constructor and destructor.
                            UN_CustomData() = default;
    virtual                ~UN_CustomData() = default;

    /// Returns an index map used for mapping IDs to indices.
    /// Used by sub-classes to map an ID to an INDEX.
    const UN_DataIndexMap * indexMap() const
                                { return myIndexMap; }

private:
    /// Returns a clone copy of this custom data object.
    virtual UN_CustomDataPtr    clone() const = 0;

    /// Sets the map from an ID to an INDEX of a slot in custom data buffers.
    // Only UN_Data should need to set the index map.
    friend UN_Data;
    void                    setIndexMap( const UN_DataIndexMap *map )
                                { myIndexMap = map; }

private:
    /// A reference pointer to an index map.
    /// This is a mapping from a data ID to an index of a slot in the 
    /// buffer array of custom data elements .
    const UN_DataIndexMap * myIndexMap = nullptr;
};

// ============================================================================
/// The interface for custom data containters, templetized for convenience 
/// of using spcific IDs (eg, UN_NodeID, UN_PortID, etc), 
/// rather than generic UN_DataID.
/// Note, this would normally be part of UN_CustomData, but templates 
/// can complicate things, like forward declarations, so using a concrete 
/// base class for that.
template <typename ID, typename INDEX>
class UN_CustomDataT : public UN_CustomData
{
public:
    /// Increases the capacity of the data buffer arrays to the given minimum,
    /// unless the capacity is already greater or equal to that minimum,
    /// in which case the capacity remains unchanged.
    /// This is a hint to the custom data, in case it uses data buffer arrays.
    virtual void        setCapacityIfNeeded(UN_DataSize min_capacity) = 0;

    /// Merge the other custom data into this one.
    /// The merge info includes ID remapping as well as buffer spans
    /// that can be copied in bulk. 
    /// The spans don't contain root data, (applicable only to node and subnet 
    /// data) so this method should merge any desired root data separately.
    virtual void        merge( const UN_CustomData &other,
                               const UN_DataMergeInfo &data_merge_info ) = 0;

    /// Adds a new data slot to accommodate a new piece of data
    // for an element (eg, node) of a given ID, which corresponds 
    // to the given index (either can be used).
    virtual void        addData( ID id, INDEX index ) = 0;

    /// Clears the data slot of a given ID and at the corresponding index
    /// as if it was newly created.
    virtual void        clearData( ID id, INDEX index ) = 0;

    /// Frees the data slot occupied by the item given by the id and 
    /// a corresponding index (either can be used), clearing it if necessary.
    virtual void        removeData( ID id, INDEX index ) = 0;

    /// Frees all the the data slots occupied by all the items, clearing
    /// them if necessary. 
    virtual void        removeAllData() = 0;

    /// Returns true if the given ID refers to a valid data entry 
    /// in the data buffers. Ie, such a piece of data exists and is valid.
    bool                isValid( ID id ) const
                            {
                                return indexMap() && indexMap()->isValid( id );
                            }

    /// Returns the data index into the data buffer arrays given its ID.
    INDEX               dataIndex( ID id ) const
                            {
                                return indexMap() 
                                    ? INDEX( indexMap()->indexFromID( id )) 
                                    : INDEX();
                            }

    /// Returns the size of the data buffers that use indexing based
    /// on the `dataIndex()` lookup call that maps IDs to indices.
    /// The size is lagest index issued plus one.
    UN_DataSize         dataBufferSize() const
                            {
                                return indexMap() 
                                    ? indexMap()->dataBufferSize() 
                                    : UN_DataSize(0);
                            }
protected:
    /// Helper method to copy-assign the value to an entry in the data buffer.
    template<typename V, typename B>
    inline void
    setData( B &buffer, ID id, const V &value )
    {
        UN_DataBufferUtils::setData( buffer, dataIndex(id), value );
    }

    /// Helper method to move-assign the value to an entry in the data buffer.
    template<typename V, typename B>
    inline void
    setData( B &buffer, ID id, V &&value )
    {
        UN_DataBufferUtils::setData( buffer, dataIndex(id), 
                std::forward<V>(value));
    }

    /// Helper method to return a const ref to an entry in the data buffer.
    template<typename V, typename B>
    inline const V &
    getDataRef( const B &buffer, ID id, const V &default_value ) const
    {
        return UN_DataBufferUtils::getDataRef( buffer, dataIndex(id), 
                default_value );
    }

    /// Returns a value constructed from an entry in the data buffer.  
    /// This is useful when the type returned here differs from 
    /// the underlying entry type.
    /// In particular, this is needed for UN_BoolDataBuffer whose underlying 
    /// entries are bits (for which we can't return a const reference) 
    /// while here we are returning bool (byte).
    template<typename V, typename B>
    inline V 
    getDataVal( const B &buffer, ID id, const V &default_value ) const
    {
        return UN_DataBufferUtils::getDataVal( buffer, dataIndex(id),
                default_value );
    }

    /// Helper method to return a value moved from an entry in the data buffer.
    template<typename V, typename B>
    inline V 
    stealData( B &buffer, ID id, const V &default_value )
    {
        return UN_DataBufferUtils::stealData( buffer, dataIndex(id),
                default_value );
    }

    /// Helper method to update an entry value in the data buffer.
    /// It updates a data value in-place in the data buffer, 
    /// which for complex data values (eg, dictionaries or arrays) is faster 
    /// than getting and setting the value (although stealing and setting
    /// may be comparable). This is a convenient and useful idiom, that
    /// tries to avoid the buffer data aliasing issues.
    /// Intended usage: 
    ///   updateData(buff, id, [&key, &value](auto &x) { x[key] = value; });
    template<typename OP, typename B>
    inline void
    updateData( B &buffer, ID id, const OP &op  )
    {
        UN_DataBufferUtils::updateData( buffer, dataIndex(id), op );
    }
};

#endif