UN_Data.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_Data.h ( UN Library, C++)
 *
 * COMMENTS:
 *      
 */

#ifndef __UN_Data_h__
#define __UN_Data_h__

#include "UN_API.h"
#include "UN_CustomData.h"
#include "UN_DataBuffer.h"
#include "UN_DataIndexMap.h"
#include "UN_GenericData.h"
#include "UN_Include.h"

// ============================================================================
/// A generic container of the data buffers.
/// 
/// NOTE: This class is generally not trivially relocatable, because it sets 
/// a pointer to its member (myIndexMap) on another member (myCustomData).

class UN_API UN_Data 
{
public:
    /// Constructors and destructors.
     UN_Data( UN_CustomDataPtr custom_data = UN_CustomDataPtr() );
    ~UN_Data() = default;

    /// Move operators.
                            UN_Data(UN_Data&&);
    UN_Data &               operator=(UN_Data&&);

protected:
    /// This container can have large data, so generally, forbid 
    /// the costly copy operations to the public.
                            UN_Data(const UN_Data&);
    UN_Data &               operator=(const UN_Data &);

public:
    /// @{ Returns the custom data container, if one was provided.
    UN_CustomData *         customData()
                                { return myCustomData.get(); }
    const UN_CustomData *   customData() const
                                { return myCustomData.get(); }
    /// @}

    /// Returns a range for iterating valid IDs
    using IDRange = UN_DataIndexMap::IDRange;
    IDRange                 idRange() const
                                { return myIndexMap.idRange(); }

    /// Returns a range for iterating valid IDs in an ascending order.
    using OrderedIDRange = UN_DataIndexMap::OrderedIDRange;
    OrderedIDRange          orderedIDRange() const
                                { return myIndexMap.orderedIDRange(); }

    /// Returns a list of all the valid IDs in this container
    UN_DataIDList           dataIDs() const
                                { return myIndexMap.ids(); }

    /// Returns a sorted list of all the valid IDs in this container
    UN_DataIDList           sortedDataIDs() const
                                { return myIndexMap.sortedIDs(); }

    /// Returns the number of valid data items in the buffer.
    UN_DataSize             size() const
                                { return myIndexMap.size(); }

    /// Returns the upper limit on the valid indices issued by this container.
    /// Ie, maximum index value plus one.
    UN_DataSize             indexSize() const
                                { return myIndexMap.indexSize(); }

    /// Returns the upper limit on the numerical value of the valid data IDs 
    /// issued by this container. Ie, maximum ID plus one.
    UN_DataSize             idSize() const
                                { return myIndexMap.idSize(); }

protected:
    /// Merges another data container into this one.
    /// 
    /// If @p fuse_id_zero is true, the data for the ID zero is not copied
    /// to a brand new data slot, but is combined with existing slot ID of zero.
    /// Some data containers (subclasses) use ID of zero for a special
    /// entity that is treated differently than the rest. 
    /// Notably, the node data container uses ID of zero for the root node,
    /// and the root node from the src should not become a regular node here.
    /// Instead, src root ID maps to dst root ID and their data is combined.
    UN_DataMergeInfo        mergeData( const UN_Data &src_data,
                                       bool combine_id_zero = false )
                                {
                                    return myIndexMap.merge(
                                            src_data.myIndexMap, 
                                            combine_id_zero );
                                }

    /// Adds a slot for new data in the data buffers of this container,
    /// and returns the data ID by which this slot can be refered to,
    /// and also at which index in a buffer the data slot is expected to be.
    /// A slot usually corresponds to a concrete graph element (eg, a node),
    /// and data buffer slots store some info about it, (eg, a name or a type).
    /// NOTE: The derived classes must insert a corresponding entry in all 
    ///       of their data buffers, at the given index.
    ///       The index can also be found by `dataIndex(ID)`.
    std::pair< UN_DataID, UN_DataIndex >
                            addData()
                                { return myIndexMap.addEntry(); }

    /// Returns an existing data buffer index for the given data ID, 
    /// if already exists in the container, or adds a new slot for the
    /// data and returns the newly created index for it.
    std::pair< UN_DataID, UN_DataIndex >
                            findOrAddData( UN_DataID data_id )
                                { return myIndexMap.findOrAddEntry( data_id ); }

    /// Removes the data slot from this container and frees the slot 
    /// it used to occupy. The slot may be reused in the future for other
    /// data item (but with different data ID).
    /// After calling this method the container will have no knowledge 
    /// of the data by this ID.
    /// Returns true on successs; false if the data was not found.
    bool                    removeData( UN_DataID data_id )
                                { return myIndexMap.removeEntry( data_id ); }

    /// Frees the data slots occupied by all the data.
    /// @param 'reset_next_id' If true, the data ID generator is reset to zero.
    void                    removeAllData( bool reset_next_id )
                                { myIndexMap.removeAllEntries( reset_next_id );}


    /// Returns true if the given ID refers to a valid data slot (entries)
    /// in the data buffers. 
    /// Eg, for node data buffers, if such a node exists and is valid.
    bool                    isValid( UN_DataID data_id ) const
                                { return myIndexMap.isValid( data_id ); }

    /// Returns the data index into the data buffer arrays 
    /// (ie, arrays implemented and owned by the sub-classes).
    /// The data index locates a slot (entries in the data buffers) 
    /// for the graph element (eg, for a node) by the given ID.
    UN_DataIndex            dataIndex( UN_DataID id ) const
                                { return myIndexMap.indexFromID(id); }

    /// Returns the size of the data buffers that use indexing based
    /// on the `dataIndex()` lookup call that maps IDs to indices.
    /// The size is the lagest index ever issued plus one.
    /// Ie, it is the number of data entries a buffer can currently hold.
    UN_DataSize             dataBufferSize() const
                                { return myIndexMap.dataBufferSize(); }

    /// Returns the number of free slots in the data buffer.
    /// Ie, the buffer consists of data entry slots that are either occupied 
    /// or free, and this menthod returns the free slots count.
    UN_DataSize             freeDataBufferSize() const
                                { return myIndexMap.freeDataBufferSize(); }

    /// Returns the number of valid data entries in the data buffer.
    /// Ie, the buffer consists of data entry slots that are either occupied 
    /// or free, and this menthod returns the occupied slots count.
    UN_DataSize             usedDataBufferSize() const
                                { return myIndexMap.usedDataBufferSize(); }

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, UN_DataID 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, UN_DataID 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, UN_DataID id, const V &default_value ) const
    {
        return UN_DataBufferUtils::getDataRef( buffer, dataIndex(id),
                default_value );
    }
    
    /// Helper method to return 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, UN_DataID 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, UN_DataID 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, UN_DataID id, const OP &op  )
    {
        UN_DataBufferUtils::updateData( buffer, dataIndex(id), op );
    }

public:
    /// Adds a new named generic data buffer with a caller-specified default
    /// value. If a buffer with the same name already exists and the type
    /// matches, its existing ID is returned. If the name exists but the
    /// type conflicts, an invalid ID is returned.
    template<typename D>
    UN_GenericBufferID
    addGenericBuffer( const UT_StringRef &name,
                      UN_GenericBufferType type,
                      const D &default_value )
    {
        return myGenericData.addBuffer( name, type, default_value,
                                        dataBufferSize() );
    }

    /// Returns the type of the generic buffer identified by the given ID.
    UN_GenericBufferType
    genericBufferType( UN_GenericBufferID id ) const
    {
        return myGenericData.bufferType( id );
    }

    /// Returns the ID of the generic buffer with the given name, or an
    /// invalid ID if no such buffer exists.
    UN_GenericBufferID
    findGenericBuffer( const UT_StringRef &name ) const
    {
        return myGenericData.findBuffer( name );
    }

    /// Returns the name of the generic buffer identified by the given ID.
    const UT_StringHolder &
    genericBufferName( UN_GenericBufferID id ) const
    {
        return myGenericData.bufferName( id );
    }

protected:
    /// Sets the data value in a generic buffer for a given data ID.
    template<typename T>
    inline void
    setGenericData( UN_GenericBufferID buf_id, UN_DataID id,
                    const T &value )
    {
        myGenericData.setData( buf_id, dataIndex(id), value );
    }

    /// Sets the data value in a generic buffer via move.
    template<typename T>
    inline void
    setGenericData( UN_GenericBufferID buf_id, UN_DataID id, T &&value )
    {
        myGenericData.setData( buf_id, dataIndex(id),
                               std::forward<T>(value) );
    }

    /// Returns a const ref to the data value in a generic buffer.
    template<typename T>
    inline const T &
    genericDataRef( UN_GenericBufferID buf_id, UN_DataID id ) const
    {
        return myGenericData.getDataRef<T>( buf_id, dataIndex(id) );
    }

    /// Returns a copy of a data value from a generic buffer.
    /// Useful when cannot call genericDataRef() for types that cannot return
    /// by reference (eg, bool with bit-packed UN_DataBuffer<bool>).
    template<typename T>
    inline T
    genericDataVal( UN_GenericBufferID buf_id, UN_DataID id ) const
    {
        return myGenericData.getDataVal<T>( buf_id, dataIndex(id) );
    }

    /// Moves the data value out of a generic buffer.
    template<typename T>
    inline T
    stealGenericData( UN_GenericBufferID buf_id, UN_DataID id )
    {
        return myGenericData.stealData<T>( buf_id, dataIndex(id) );
    }

    /// Updates the data value in a generic buffer in-place via a callable.
    template<typename T, typename OP>
    inline void
    updateGenericData( UN_GenericBufferID buf_id, UN_DataID id,
                       const OP &op )
    {
        myGenericData.updateData<T>( buf_id, dataIndex(id), op );
    }



    /// Adds a data slot at the given index to all generic buffers.
    void                    addGenericData( UN_DataIndex index )
                                { myGenericData.addData( index ); }

    /// Clears the generic data at the given index to defaults.
    void                    clearGenericData( UN_DataIndex index )
                                { myGenericData.clearData( index ); }

    /// Removes all data from all generic buffers.
    void                    removeAllGenericData()
                                { myGenericData.removeAllData(); }

    /// Grows all generic buffers to the given minimum capacity.
    void                    setGenericDataCapacityIfNeeded(
                                UN_DataSize min_capacity )
                                { myGenericData.setCapacityIfNeeded(
                                    min_capacity ); }

    /// Merges generic data from another UN_Data container.
    void                    mergeGenericData( const UN_Data &src,
                                const UN_DataMergeInfo &merge_info )
                                { myGenericData.mergeData(
                                    src.myGenericData, merge_info ); }

    /// Returns true if all generic buffers have the expected size.
    bool                    isGenericDataSizeConsistent(
                                UN_DataSize expected_size ) const
                                { return myGenericData.isDataSizeConsistent(
                                    expected_size ); }

private:
    /// A mapping from a data ID to the index into the data buffer arrays.
    /// An index locates the slot (entries in the data buffers)
    /// for the graph element (eg, for a node) the given by the data ID.
    UN_DataIndexMap         myIndexMap;

    /// Cointainer for custom data buffers.
    UN_CustomDataPtr        myCustomData;

    /// Container for dynamically added generic data buffers.
    UN_GenericData          myGenericData;
};

#endif