sds.hh

Go to the documentation of this file.

#ifndef _DRAMA2_SDS_INC
#define _DRAMA2_SDS_INC
 
/*
 * History:
     07-Jan-2014 - TJF - Original version
     14-Sep-2016 - TJF - Start of history after development.
     14-Sep-2016 - TJF - Add Exists() by index.
     09-Jan-2023 - TJF - std::iterator is depreciated from C++17.  
 
 * The above ID is for Doxygen, this one has the format ACMM is looking for.
 * "@(#) $Id$"
 */
#include "sds.h"
#include "arg.h"
#include <string>
#include <stdio.h>
#include <vector>
#include <memory>
#include <assert.h>
 
/*
 * A bit of a flaw in our include file layout means we need to declare this
 * here.  Its real location is drama.hh, but we don't want to include that
 * in this file.
 */
namespace drama {
    extern  void CheckLockTaken(const std::string func,
                                const std::string &file,
                                const int lineNum) ;
} // namespace drama.
 
 
#include "drama/exception.hh"
#include "drama/sdsarray.hh"
 
#include <tuple>
 
namespace drama { 
    namespace sds {
        using std::begin;
        using std::end;
 
        /*
         * The SdsArgPut() template function is used by the Put() method
         * of sds::Id and is implementing traditional Arg style Put.
         *
         * The idea is that we must instantiate a specific version of this
         * for each primitive SDS type and for strings.
         *
         * The Put() method won't link unless there is a specific version for
         *  the type in question. There are all implemented in parsys.cpp.
         */
        template <typename T> void SdsArgPut(
            SdsIdType id, const std::string &name, 
            T value, StatusType *status); 
 
        template <> void SdsArgPut<bool>(
            SdsIdType id, const std::string &name, 
            bool value, StatusType *status);
        template <> void SdsArgPut<char>(
            SdsIdType id, const std::string &name, 
            char value, StatusType *status);
        template <> void SdsArgPut<short>(
            SdsIdType id, const std::string &name, 
            short value, StatusType *status);
        template <> void SdsArgPut<unsigned short>(
            SdsIdType id, const std::string &name, 
            unsigned short value, StatusType *status);
        template <> void SdsArgPut<INT32>(
            SdsIdType id, const std::string &name, 
            INT32 value, StatusType *status);
        template <> void SdsArgPut<UINT32>(
            SdsIdType id, const std::string &name, 
            UINT32 value, StatusType *status);
        template <> void SdsArgPut<INT64>(
            SdsIdType id, const std::string &name, 
            INT64 value, StatusType *status);
        template <> void SdsArgPut<UINT64>(
            SdsIdType id, const std::string &name, 
            UINT64 value, StatusType *status);
        template <> void SdsArgPut<float>(
            SdsIdType id, const std::string &name, 
            float value, StatusType *status);
        template <> void SdsArgPut<double>(
            SdsIdType id, const std::string &name, 
            double value, StatusType *status);
 
        template <> void SdsArgPut<const char *>(
            SdsIdType id, const std::string &name, 
            const char *value, StatusType *status);
 
        /*
         * The SdsArgGet() template function is used by the Get() method
         * of sds::Id and is implementing traditional Arg style Get.
         *
         * The idea is that we must instantiate a specific version of this
         * for each primitive SDS type.
         *
         * The Get() method won't link unless there is a specific version for
         *  the type in question.
         */
        template <typename T> void SdsArgGet(
            SdsIdType id, const std::string &name, 
            T *value, StatusType *status); 
 
        template <> void SdsArgGet<bool>(
            SdsIdType id, const std::string &name, 
            bool *value, StatusType *status);
        template <> void SdsArgGet<char>(
            SdsIdType id, const std::string &name, 
            char *value, StatusType *status);
        template <> void SdsArgGet<short>(
            SdsIdType id, const std::string &name, 
            short *value, StatusType *status);
        template <> void SdsArgGet<unsigned short>(
            SdsIdType id, const std::string &name, 
            unsigned short *value, StatusType *status);
        template <> void SdsArgGet<INT32>(
            SdsIdType id, const std::string &name, 
            INT32 *value, StatusType *status);
        template <> void SdsArgGet<UINT32>(
            SdsIdType id, const std::string &name, 
            UINT32 *value, StatusType *status);
        template <> void SdsArgGet<INT64>(
            SdsIdType id, const std::string &name, 
            INT64 *value, StatusType *status);
        template <> void SdsArgGet<UINT64>(
            SdsIdType id, const std::string &name, 
            UINT64 *value, StatusType *status);
        template <> void SdsArgGet<float>(
            SdsIdType id, const std::string &name, 
            float *value, StatusType *status);
        template <> void SdsArgGet<double>(
            SdsIdType id, const std::string &name, 
            double *value, StatusType *status);
        template <> void SdsArgGet<std::string>(
            SdsIdType id, const std::string &name, 
            std::string *value, StatusType *status);
 
 
 
 
 
 
        /* 
         * The PutScalar() template function is used by the Put() method
         * of sds::Id (no name version) and is implementing something like
         * the traditional Arg style Put, but directly into the current item.
         *
         * The idea is that we must instantiate a specific version of this
         * for each primitive SDS type and for strings.
         *
         * The Put() method won't link unless there is a specific version for
         *  the type in question. There are all implemented in parsys.cpp.
         */
        template <typename T> void PutScalar(
            SdsIdType id, 
            T value, StatusType *status); 
 
        template <> void PutScalar<bool>(
            SdsIdType id, 
            bool value, StatusType *status);
        template <> void PutScalar<char>(
            SdsIdType id, 
            char value, StatusType *status);
        template <> void PutScalar<short>(
            SdsIdType id, 
            short value, StatusType *status);
        template <> void PutScalar<unsigned short>(
            SdsIdType id, 
            unsigned short value, StatusType *status);
        template <> void PutScalar<INT32>(
            SdsIdType id, 
            INT32 value, StatusType *status);
        template <> void PutScalar<UINT32>(
            SdsIdType id, 
            UINT32 value, StatusType *status);
        template <> void PutScalar<INT64>(
            SdsIdType id, 
            INT64 value, StatusType *status);
        template <> void PutScalar<UINT64>(
            SdsIdType id, 
            UINT64 value, StatusType *status);
        template <> void PutScalar<float>(
            SdsIdType id, 
            float value, StatusType *status);
        template <> void PutScalar<double>(
            SdsIdType id, 
            double value, StatusType *status);
 
        template <> void PutScalar<const char *>(
            SdsIdType id, 
            const char *value, StatusType *status);
 
        template <> void PutScalar<const std::string &>(
            SdsIdType id, 
            const std::string &value, StatusType *status);
 
        /*
         * The GetScalar() template function is used by the Get() method
         * (no name versions) of sds::Id and is implementing something like 
         * the traditional Arg style Get, but from the current item directly, 
         * hence why no name is supplied.
         *
         * The idea is that we must instantiate a specific version of this
         * for each primitive SDS type.
         *
         * The Get() method won't link unless there is a specific version for
         *  the type in question.
         */
        template <typename T> void GetScalar(
            SdsIdType id, 
            T *value, StatusType *status); 
 
        template <> void GetScalar<bool>(
            SdsIdType id, 
            bool *value, StatusType *status);
        template <> void GetScalar<char>(
            SdsIdType id, 
            char *value, StatusType *status);
        template <> void GetScalar<short>(
            SdsIdType id, 
            short *value, StatusType *status);
        template <> void GetScalar<unsigned short>(
            SdsIdType id, 
            unsigned short *value, StatusType *status);
        template <> void GetScalar<INT32>(
            SdsIdType id, 
            INT32 *value, StatusType *status);
        template <> void GetScalar<UINT32>(
            SdsIdType id, 
            UINT32 *value, StatusType *status);
        template <> void GetScalar<INT64>(
            SdsIdType id, 
            INT64 *value, StatusType *status);
        template <> void GetScalar<UINT64>(
            SdsIdType id, 
            UINT64 *value, StatusType *status);
        template <> void GetScalar<float>(
            SdsIdType id, 
            float *value, StatusType *status);
        template <> void GetScalar<double>(
            SdsIdType id, 
            double *value, StatusType *status);
        template <> void GetScalar<std::string>(
            SdsIdType id, 
            std::string *value, StatusType *status);
 
 
        class PrintObjectPnt {
        public:
            virtual void Print(const std::string &line) = 0;
        };
        class PrintObjectCR {
        public:
            virtual void Print(const std::string &line) const = 0;
        };
 
        class Id {
        private:
            SdsIdType _id;      /* Actual Sds id.  0 (zero) is the null ID */
            struct {
                bool free : 1;/* Set true to cause destructor to free the OD*/
                bool del  : 1;/* If free is true, destructor will do SdsDelete*/
                bool readfree : 1;/* if free , destructor will do SdsReadFree */
            } _flags;
 
            /* 
             * Private routine to clean up, will be called by destructor and 
             * Shallow copy operations.  
             *
             * We defer the work to CleanUpWorker(), but need to indicate to
             * it if SdsFreeIdAndCheck() should be invoked instead of
             * just SdsFreeId().
             *
             * @param from_where  Where have we been invoked form, for message
             *      about SDS ID free failures.
             */
            /* no exceptions allowed as may be called from move or destructor */
            void CleanUp(const std::string &from_where) noexcept {
#if defined(SDS_CHECK_FREE)||defined(SDS_CHECK_FREE_W)            
                bool check_free = true;
#else
                bool check_free = false;
#endif                
                CleanUpWorker(check_free, from_where);
            }
 
            /*
             * Do the actual clean up.
             */
            void CleanUpWorker(bool check, const std::string &from_where) noexcept;
 
                
 
            /* This method is used by the ArrayAccess methods to check the item
               is appropiate for the SdsArrayAccessHelper being used
            */
            template <class ContainerType>
            void CheckArrayType(
                const SdsCodeType code,     /* Expected code */
                const long ndims,           /* Expected number of dims */
                ContainerType * const dims) const { /* Actual dims written here */
 
                SdsCodeType tcode = GetCode();
                /*
                 * Get details on the object.
                 */
                GetDims(dims);
                /*
                 * Check the code and number of dimensions are correct.
                 */
                if (tcode != code)
                {
                    DramaTHROW(SDS__INVTYPE,
                               "SDS type does not match expected array type");
                }
                if (dims->size() == 0)
                {
                    DramaTHROW(SDS__NOTARRAY,
                               "Attempt to access an array in an SDS structure which is not an array");
                }
                if (dims->size() != static_cast<unsigned>(ndims))
                {
                    DramaTHROW_S(SDS__INVDIMS,
                                 "SDS Array structure has % dimensions instead of the expected %",
                                 dims->size(), ndims);
                }
            
            }
            /*
             * A simplified access to  CheckArrayType, for a single 
             *  dimensional array.
             */
            void CheckArrayTypeSingleDim(
                const SdsCodeType code, 
                unsigned long * const nitems) const { /* Actual number of items written here*/
            
                std::vector<unsigned long> dims;
                CheckArrayType(code, 1, &dims);
                *nitems = dims[0];
            
            }
 
            /*
             * This is used to set an ArrayAccessHelper item's data
             * pointer to be the result of SdsPointer() on this item.
             * 
             */
            template <class T> void SetArrayHelperDataAddr(
                T * const data) const {
 
                unsigned char *dataAddr = 0;
                Pointer(&dataAddr);
                data->SetDataToAddr(dataAddr);
            }
                
 
        public:
            /*  Whilst we have SdsCloneId() we can't really use it at this
             *  point since we don't know what to do with the flags.
             */
            Id& operator=(const Id &rhs) = delete;
            /*  Whilst we have SdsCloneId() we can't really use it at this
             *  point since we don't know what to do with the flags (who
             *  gets to control deletion?)
             */
            Id(const Id &source) = delete;
 
            /*
             *  Note, the "copy elision" rule is an allowed optimization
             *  in C++, implemented in gcc.  It means that the following
             *  two methods will not actually be invoked, through they
             *  must exist for the moves to be allowed.  In effect, in cases
             *  where a temp would be constructed and its value moved, 
             *  the optimization allows the target variable to be constructed
             *  instead of the temp.  See
             *
             *  http://en.cppreference.com/w/cpp/language/copy_elision
             *
             */
 
 
            Id& operator=(Id &&rhs) noexcept {
                //fprintf(stderr,"drama::sds::Id move assignment triggered\n");
 
                CleanUp("sds::Id move assignment");
 
                _id = rhs._id;
                _flags = std::move(rhs._flags);
 
                rhs._id = 0;
                return *this;
            }
            Id(Id &&source) noexcept : 
            _id(source._id), _flags(std::move(source._flags))  {
                //fprintf(stderr,"drama::sds::Id move constructor triggered\n");
                source._id = 0;
            }
 
            Id() {
                _id = 0;
                _flags.free     = false;
                _flags.del      = false;
                _flags.readfree = false;
            }
 
        private:
            /* Construct an sds::Id item from an existing C language SDS id.
             *  
             *  This sds::Id constructor that takes an existing SDS id
             *  (C style) and creates an sds::Id class object which refers
             *  to that SDS id.  You must explicitly specify if the item is to be
             *  free-ed and/or deleted when the object's destructor is invoked,
             *  and what you do depends on when what other code may do with
             *  item.  The del and readfree are mutually exclusive, through
             *  this is currently not checked in this implementation.
             *
             * @param item The SdsIdType of the item.  If 0 (the default), the 
             *             sds::Id object constructed does not refer to any SDS 
             *             item.  This is normally only used when we want an 
             *             argument to pass (by pointer) to a function which 
             *             will use move assignment or sds::Id::ShallowCopy()
             *             to set the ID.
             *
             * @param free Set true to invoke DCF(SdsFreeId) on the ID when the 
             *             object  is  destroyed.  The default is false.
             *
             * @param del  Set true to invoke DCF(SdsDelete) on the ID when 
             *             the object is destroyed.  The default is false.
             *
             * @param readfree Set true to invoke DCF(SdsReadFree) on the ID 
             *             when the object is destroyed.  The default is false.
             *
             */
            explicit Id(const SdsIdType item, const bool free=false, 
                        const bool del = false, const bool readfree = false) :
                _id(item) {
                _flags.free = free;
                _flags.del = del; 
                _flags.readfree = readfree;
            }
        public:
            static Id CreateNullItem();
 
            static Id CreateFromSdsIdType(
                const SdsIdType item, const bool free=false, 
                const bool del = false, const bool readfree = false);
 
            static Id CreateFromSdsIdTypeCopy(
                const SdsIdType item);
 
 
            static Id CreateFromSdsId(const SdsId &item);
 
            static Id CreateFromSdsId(SdsId *item);
 
 
            template <class ContainerType> 
            static Id CreateByAccess(ContainerType *container) {
 
                /*
                 * Confirm the container is a container of POD types.
                 *   From C++20, std::is_pod<>() is depreciated, we can replace 
                 *     by std::is_standard_layout<>::value 
                 */
                static_assert(
                    std::is_standard_layout<typename ContainerType::value_type>::value,
                    "The value type in the container must be a standard layout type"); 
 
                if (container->empty())
                {
                    DramaTHROW(DRAMA2__EMPTY_CONTAINER, 
                               "Attempt to access data in empty container");
                }
                Id item(0, true, false, false); /* Must free-ed when done */
                StatusType status = STATUS__OK;
                SdsAccess(&(*container)[0],&item._id,&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to access SDS Item");
                
                return item;
            }
            template <class ContainerType> 
            static Id CreateByImport(const ContainerType &container) {
                /*
                 * Confirm the container is a container of POD types.
                 *   From C++20, std::is_pod<>() is depreciated, we can replace 
                 *     by std::is_standard_layout<>::value 
                 */
                static_assert(
                    std::is_standard_layout<typename ContainerType::value_type>::value,
                    "The value type in the container must be a standard layout type"); 
 
 
                if (container.empty())
                {
                    DramaTHROW(DRAMA2__EMPTY_CONTAINER, 
                               "Attempt to access data in empty container");
                }
 
 
                Id item(0, true, true, false); /* Must deleted and free-ed when done */
                StatusType status = STATUS__OK;
                SdsImport(&container[0],&item._id,&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to import SDS Item");
                
                return item;
            }
 
            static Id FromFile(const std::string &filename);
            virtual Id CreateChildItem(
                const std::string &name, 
                const SdsCodeType code,
                const std::string &extra = "") const;
 
            static Id CreateTopLevel(
                const std::string &name, 
                const SdsCodeType code,
                const std::string &extra = "");
 
            template <class ContainerType> 
            Id CreateChildArray(
                const std::string &name, 
                const SdsCodeType code,
                const ContainerType& dims,
                const std::string &extra = "") const {
 
                Id item(0,true, false, false);
                StatusType status = STATUS__OK;
 
                /*
                 * "dims" can be any container that
                 *   1. Has a size method.
                 *   2. Can be used to initialize a std::vector of unsigned long.
                 *   3. And it is validated for a    0 < size <= 7.
                 */
                if ((dims.size() < 1)||(dims.size() > SDS__MAXDIMS))
                {
                    DramaTHROW_S(SDS__MAXDIMS,
                                 "Failed to create new SDS array - % dimensions, minimum supported 1, maximum supported is %",
                                 dims.size(),
                                 SDS_C_MAXARRAYDIMS);
                }
                /*
                 * We need to pass an array of unsigned long to SdsNew for
                 * the dimensions.  The best approach is to create a vector
                 * of unsigned long and initialize it with the contents of
                 * our passed in container.
                 */
                std::vector<unsigned long> myDims(dims);
 
                SdsNew(_id,name.c_str(),extra.size(),extra.data(),code,
                       myDims.size(), myDims.data(),&item._id,&status);
                if (status != STATUS__OK)
                    DramaTHROW_S(status, "Failed to create new SDS array top-level item %",name);
                return item;
            }    
 
            Id CreateChildArray(
                const std::string &name, 
                const SdsCodeType code,
                const unsigned    nElem,
                const std::string &extra = "") const {
 
                Id item(0,true, false, false);
                StatusType status = STATUS__OK;
 
                /*
                 * This is a simplification of the above multi-dimensional
                 * version. 
                 */
                unsigned long dims[1];
                dims[0] = nElem;
                SdsNew(_id,name.c_str(),extra.size(),extra.data(),code,
                       1, dims, &item._id,&status);
                if (status != STATUS__OK)
                    DramaTHROW_S(status, "Failed to create new SDS array top-level item %",name);
                return item;
            }    
            
 
            
            template <class ContainerType> 
            static Id CreateTopLevelArray(
                const std::string & name, 
                const SdsCodeType code,
                const ContainerType& dims,
                const std::string &extra = ""){
 
                Id item(0,true, true, false);
                StatusType status = STATUS__OK;
 
                /*
                 * "dims" can be any container that
                 *   1. Has a size method.
                 *   2. Can be used to initialize a std::vector of unsigned long.
                 *   3. And it is validated for a    0 < size <= 7.
                 */
                if ((dims.size() < 1)||(dims.size() > SDS__MAXDIMS))
                {
                    DramaTHROW_S(SDS__MAXDIMS,
                                 "Failed to create new SDS array - % dimensions, minimum supported 1, maximum supported is %",
                                 dims.size(),
                                 SDS_C_MAXARRAYDIMS);
                }
                /*
                 * We need to pass an array of unsigned long to SdsNew for
                 * the dimensions.  The best approach is to create a vector
                 * of unsigned long and initialize it with the contents of
                 * our passed in container.
                 */
                std::vector<unsigned long> myDims(dims);
 
 
                SdsNew(0,name.c_str(),extra.size(),extra.data(),code,
                       myDims.size(), myDims.data(),&item._id,&status);
                if (status != STATUS__OK)
                    DramaTHROW_S(status, "Failed to create new SDS array top-level item %",name);
 
                return item;
            }    
 
            static Id CreateTopLevelArray(
                const std::string & name, 
                const SdsCodeType code,
                const unsigned    nElem,
                const std::string &extra = ""){
 
                Id item(0,true, true, false);
                StatusType status = STATUS__OK;
 
                /*
                 * This is a simplification of the above multi-dimensional
                 * version. 
                 */
                unsigned long dims[1];
                dims[0] = nElem;
 
 
                SdsNew(0,name.c_str(),extra.size(),extra.data(),code,
                       1, dims,&item._id,&status);
                if (status != STATUS__OK)
                    DramaTHROW_S(status, "Failed to create new SDS array top-level item %",name);
 
                return item;
            }    
 
 
        
            template <class ContainerType>
            Id Cell(const ContainerType& indicies,
                    bool throwOnNotFound=true) const {
                Id item(0, true, false, false);
 
                /*
                 * "dims" can be any container that
                 *   1. Has a size method.
                 *   2. Can be used to initialize a std::vector of unsigned long.
                 *   3. And it is validated for a    0 < size <= 7.
                 */
                if ((indicies.size() < 1)||(indicies.size() > SDS__MAXDIMS))
                {
                    DramaTHROW_S(SDS__INVDIMS,
                                 "Failed to access SDS array cell - % dimensions, minimum supported 1, maximum supported is %",
                                 indicies.size(),
                                 SDS_C_MAXARRAYDIMS);
                }
                /*
                 * We need to pass an array of unsigned long to SdsCell for
                 * the dimensions.  The best approach is to create a vector
                 * of unsigned long and initialize it with the contents of
                 * our passed in container.
                 */
                std::vector<unsigned long> myDims(indicies);
 
 
                StatusType status = STATUS__OK;
                SdsCell(_id, myDims.size(), myDims.data(), &item._id, &status); 
 
                /* Special case of item not found and don't want to throw, return null id */
                if ((status == SDS__INDEXERR)&&(!throwOnNotFound))
                {
                    item._flags.del = false;
                    return item;
                }
 
                if (status != STATUS__OK)
                    DramaTHROW(status, 
                               "Failed to access cell of existing SDS array id");
                return item;
            }
            virtual Id Copy() const;
 
            virtual Id Find(const std::string &name, 
                            bool throwOnNotFound=true) const;
 
            virtual Id Index(const long index, bool throwOnNotFound=true) const;
 
            virtual ~Id() {
                /*Just invoke the private cleanup routine */
                CleanUp("sds::Id destructor");
            }
            /* Modify flags */
            
            virtual void SetFree() { _flags.free = true; }
            virtual void SetDelete() { _flags.del = true; }
            
            virtual void ClearDelete() { _flags.del = false; }
 
            virtual void Outlive() { 
                _flags.free = false; 
                _flags.del = false; 
                _flags.readfree = false; 
            }
        
            /*
             *  General operations, as per similar SDS operations.
             *  Currently only Delete, Get and Put are virtual.
             */
        
            virtual void Delete() {
                StatusType status = STATUS__OK;
                SdsDelete(_id,&status);
                if (status == STATUS__OK)
                {
                    _flags.del = false;
                    if (_flags.free)
                    {
                        SdsFreeId(_id, &status);
                        if (status == STATUS__OK)
                        {
                            _id = 0;
                            _flags.free = false;
                        }
                    }
                }
                else
                    DramaTHROW(status, "Failed to delete SDS item");
            }
            template <class ContainerType>
            void Export(ContainerType *container) const {
                StatusType status = STATUS__OK;
 
                /*
                 * Confirm the container is a container of POD types.
                 *   From C++20, std::is_pod<>() is depreciated, we can replace 
                 *     by std::is_standard_layout<>::value
                 */
                static_assert(
                    std::is_standard_layout<typename ContainerType::value_type>::value,
                    "The value type in the container must be a standard layout type"); 
 
 
                // Must multiple container size() in units by size of each unit.
                SdsExport(_id,
                          (container->size()*sizeof((*container)[0])), 
                          &(*container)[0],&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to export SDS item");
 
            }
            template <class ContainerType>
            void ExportDefined(ContainerType *container) const {
                /*
                 * Confirm the container is a container of POD types.
                 *   From C++20, std::is_pod<>() is depreciated, we can replace 
                 *     by std::is_standard_layout<>::value
                 */
                static_assert(
                    std::is_standard_layout<typename ContainerType::value_type>::value ,
                    "The value type in the container must be a standard layout type"); 
 
                StatusType status = STATUS__OK;
                SdsExportDefined(_id,container->size(),&(*container)[0],&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to export defined SDS item");
            }
            virtual void Extract() {
                StatusType status = STATUS__OK;
                SdsExtract(_id,&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to extract SDS item");
 
                /* 
                 * We need to modify the flags to those appropriate for
                 *   and indepent toplevel item 
                 */
                _flags.free = true;
                _flags.del = true;
                _flags.readfree = false;
            }
            virtual void Flush() {
                StatusType status = STATUS__OK;
 
                //fprintf(stderr,"FLUSH:ID=%d\n", (int)(_id));
 
 
                SdsFlush(_id,&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to flush SDS item");
            }
            template <typename T>
            void Get(const unsigned long length,
                     T * const data,
                     unsigned long *actlen = nullptr,
                     const unsigned long offset=0) const {
 
                /*
                 * Confirm the data type is a POD type.
                 *   From C++20, std::is_pod<>() is depreciated, we can replace 
                 *     by std::is_standard_layout<>::value.
                 */
                static_assert(
                    std::is_standard_layout<T>::value,
                    "The type T must be a standard layout type"); 
 
                unsigned long myactlen;
                if (!actlen) actlen = &myactlen;
                StatusType status = STATUS__OK;
                SdsGet(_id,length,offset,(void *)data,actlen,&status);
                
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to Get data from SDS item");
            }
            virtual std::string GetExtra() const {
 
                unsigned long length = 0;
                StatusType status = STATUS__OK;
                SdsGetExtraLen(_id, &length, &status);
                if ((status == STATUS__OK)&&(length == 0))
                    return "";
                /*
                 * Allocate some space to store the extra data in.
                 */
                std::unique_ptr<char[]> extraData(new char[length+1]);
                
                unsigned long actlen;
                /*
                 * Get the data.
                 */
                SdsGetExtra(_id,length,&extraData[0],&actlen,&status);
                if (status != STATUS__OK)
                    DramaTHROW(status,
                               "Failed to Get extra data from SDS item");
                extraData[length] = 0;  // Ensure null termination.
                return &extraData[0];
            }
            virtual std::string GetName() const {
 
                char tName[SDS_C_NAMELEN];
                StatusType status = STATUS__OK;
                SdsGetName(_id,tName,&status);
 
                if (status != STATUS__OK)
                    DramaTHROW(status, 
                               "Failed to Get Name of SDS item");
                return tName;
               
 
            }
            virtual SdsCodeType GetCode() const {
                SdsCodeType code;
                StatusType status = STATUS__OK;
                SdsGetCode(_id,&code,&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to Get code of SDS item");
 
                return code;
 
            }
            virtual void ValidateCode(SdsCodeType requiredCode) const {
                SdsCodeType actualCode;
                StatusType status = STATUS__OK;
                SdsGetCode(_id,&actualCode,&status);
                if (status != STATUS__OK)
                {
                    DramaTHROW(status, "Failed to Get code of SDS item");
                }
 
                if (actualCode != requiredCode)
                {
                    DramaTHROW_S(DRAMA2__INV_SDS_CODE, 
                                 "SDS Item % has code %, was expected to have code %",
                                 GetName(),
                                 SdsTypeToStr(actualCode,1),
                                 SdsTypeToStr(requiredCode,1));
                }
 
            }
 
            template <class ContainerType> 
            void GetDims(ContainerType *dims) const {
 
                unsigned long tdims[SDS_C_MAXARRAYDIMS];
                long ndims;
                StatusType status = STATUS__OK;
                SdsGetDims(_id,&ndims,tdims,&status);
                if (status != STATUS__OK)
                    DramaTHROW(status,
                               "Failed to Get dimensions of SDS item");
 
                /*
                 * Copy dims to output location.
                 */ 
                dims->clear();
                for (int i = 0; i < (int)(ndims) ; ++i)
                {
                    dims->push_back(tdims[i]);
                }
 
            }
            unsigned GetNumItems() const {
 
                long numItems = 0;
                StatusType status = STATUS__OK;
                SdsNumItems(_id, &numItems, &status);
                if (status != STATUS__OK)
                    DramaTHROW(status,
                               "Failed to Get number of SDS items");
 
                return numItems;
            }
 
 
            virtual void Insert(Id & to_insert) {
                StatusType status = STATUS__OK;
                SdsInsert(_id,to_insert._id,&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to insert SDS item.");
 
 
 
                /* 
                 * If we succeed, the new child should not be deleted when
                 * it's id is destroyed, so clear the flag.  (This is why
                 * we break Tony's normal rule of not using non-const
                 * references.  
                 */
                to_insert._flags.del = false;
            }
            template <class ContainerType> 
            void Insert(Id & to_insert, 
                        const ContainerType& dims) {
 
                StatusType status = STATUS__OK;
                /*
                 * "dims" can be any container that
                 *   1. Has a size method.
                 *   2. Can be used to initialize a std::vector of unsigned long.
                 *   3. And it is validated for a    0 < size <= 7.
                 */
                if ((dims.size() < 1)||(dims.size() > SDS__MAXDIMS))
                {
                    DramaTHROW_S(SDS__MAXDIMS,
                                 "Failed to create new SDS array - % dimensions, minimum supported 1, maximum supported is %",
                                 dims.size(),
                                 SDS_C_MAXARRAYDIMS);
                }
 
                /*
                 * We need to pass an array of unsigned long to SdsNew for
                 * the dimensions.  The best approach is to create a vector
                 * of unsigned long and initialize it with the contents of
                 * our passed in container.
                 */
                std::vector<unsigned long> myDims(dims);
 
 
                SdsInsertCell(_id,myDims.size(),myDims.data(),to_insert._id,&status);
 
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to insert item into array cell");
                /*
                 * If we succeed, the new child should not be deleted when
                 * it's id is destroyed, so clear the flag 
                 */
                to_insert._flags.del = false;
            }
            
            virtual void FillArray(const Id &elem) {
                StatusType status = STATUS__OK;
                SdsFillArray(_id,elem._id,&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to fill structure");
            }
            
            template <typename T>
            void Pointer(T **data, unsigned long * length=0) const {
 
 
                /*
                 * Confirm the data type is a POD type.
                 *   From C++20, std::is_pod<>() is depreciated, we can replace 
                 *     by std::is_standard_layout<>::value 
                 */
                static_assert(
                    std::is_standard_layout<T>::value,
                    "The type T must be a standard layout and type"); 
 
 
                unsigned long mylength;
                StatusType status = STATUS__OK;
 
                if (!length) length = &mylength;
 
                void *tdata;
 
                SdsPointer(_id,&tdata,length,&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to get pointer to data.");
 
                *data = static_cast<T *>(tdata);
 
                /* fprintf(stderr,"Pointer:ID=%d, pointer=%p\n",
                   (int)(_id), (void *)(tdata));
                */
            }
            
            template <typename T>
            void Put(const unsigned long length,
                     const T * const data,
                     const unsigned long offset=0) {
                StatusType status = STATUS__OK;
                /*
                 * Confirm the data type is a POD type.
                 *   From C++20, std::is_pod<>() is depreciated, we can replace 
                 *     by std::is_standard_layout<>::value 
                 */
                static_assert(
                    std::is_standard_layout<T>::value,
                    "The type T must be a standard layout type"); 
 
                const void *tdata = static_cast<const void *>(data);
 
                SdsPut(_id,length,offset,tdata,&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to put data into SDS.");
 
 
            }
 
            virtual void PutExtra(const std::string &extra) {
 
                StatusType status = STATUS__OK;
                SdsPutExtra(_id,extra.size(),extra.data(),&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to put extra data into SDS.");
            }
            virtual void Rename(const std::string &name) {
                StatusType status = STATUS__OK;
                SdsRename(_id,name.c_str(),&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to rename SDS item..");
 
            }
            template <class ContainerType> 
            void Resize(const ContainerType& dims) {
 
 
                StatusType status = STATUS__OK;
                /*
                 * "dims" can be any container that
                 *   1. Has a size method.
                 *   2. Can be used to initialize a std::vector of unsigned long.
                 *   3. And it is validated for a    0 < size <= 7.
                 */
                if ((dims.size() < 1)||(dims.size() > SDS__MAXDIMS))
                {
                    DramaTHROW_S(SDS__MAXDIMS,
                                 "Failed to create new SDS array - % dimensions, minimum supported 1, maximum supported is %",
                                 dims.size(),
                                 SDS_C_MAXARRAYDIMS);
                }
 
                /*
                 * We need to pass an array of unsigned long to SdsResize for
                 * the dimensions.  The best approach is to create a vector
                 * of unsigned long and initialize it with the contents of
                 * our passed in container.
                 */
                std::vector<unsigned long> myDims(dims);
 
                SdsResize(_id,myDims.size(),myDims.data(),&status);
 
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to resize SDS array");
 
            }
            virtual unsigned long Size() const {
                unsigned long bytes;
                StatusType status = STATUS__OK;
                SdsSize(_id,&bytes,&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to return size of SDS structure");
                return bytes;
 
            }
            virtual unsigned long SizeDefined() const {
                unsigned long bytes;
                StatusType status = STATUS__OK;
                SdsSizeDefined(_id,&bytes,&status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to return size of SDS structure");
                return bytes;
 
            }
 
            virtual void List() const {
                StatusType status = STATUS__OK;
                SdsList(_id,&status);
 
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to list SDS structure");
            }
            virtual void List(FILE *to) const {
                StatusType status = STATUS__OK;
                SdsListTo(to, _id,&status);
 
                if (status != STATUS__OK)
                    DramaTHROW(status,"Failed to list SDS structure");
            }
            virtual void List(std::ostream &strm,
                              int lineMaxLen=100) const;
 
            virtual void List(PrintObjectPnt *printer, int lineMaxLen=100) const;
 
 
            virtual void List(const PrintObjectCR 
                              &printer, int lineMaxLen=100) const;
            
            virtual void Write(const std::string &filename) const {
                StatusType status = STATUS__OK;
                SdsWrite(_id,filename.c_str(),&status);
                if (status != STATUS__OK)
                    DramaTHROW_S(status,
                                 "Failed to write SDS structure to file \"%\"",
                                 filename);
 
            }        
            
            virtual bool  IsExternal() const {
                StatusType status = STATUS__OK;
                int external = 0;
                SdsIsExternal(_id, &external, &status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "Failed to determine if SDS is external");
 
                return external;
            }
            /* Return the address of an external item.
             *
             * This method is used to determine the address of the buffer 
             * containing an external item, if this item refers to an external 
             * item. This is the value given the contructor which accessed this 
             * item.
             *
             * @returns The address of the external item data buffer.
             */
#if 0 // SdsGetExternInfo() does not actually exist - not sure what happened
            virtual void *GetExternInfo() const {
                void *data;
                StatusType status = STATUS__OK;
                SdsGetExternInfo(_id, &data, &status);
                if (status != STATUS__OK)
                    DramaTHROW(status, 
                               "Failed to get SDS external structure address");
 
 
                return data;
            }
#endif
 
 
            virtual bool Exists(const std::string &name) const;
            virtual bool Exists(unsigned index) const;
 
            
            explicit operator SdsIdType() const { return _id; }
            
            explicit operator bool() const {
                return (_id != 0); 
            }
        
            virtual SdsIdType COut(const bool outlives, bool * const free = 0,
                                   bool * const del= 0, bool * const readfree = 0) {
                if (free)
                    *free = _flags.free;
                if (del)
                    *del  = _flags.del;
                if (readfree)
                    *readfree = _flags.readfree;
                if (outlives)
                    _flags.free = _flags.del = _flags.readfree = false;
                return (_id);
            }
            virtual void ShallowCopy (const Id & source) {
                if (this != &source)
                {
                    CleanUp("sds::Id::ShallowCopy 1"); /* Run destructor on old id */
                    _id = source._id;
                    _flags.free = _flags.del = _flags.readfree = false;
                }
            }
 
 
            virtual void ShallowCopy (Id * source, const bool outlives) {
                if (this != source)
                {
                    CleanUp("sds::Id::ShallowCopy 2");  /* Run destructor on old id */
                    _id = source->_id;
                    if (outlives)
                    {
                        /* If we will outlive the source, then we copy the source's 
                         * flags and set  the sources flags to false.   
                         */
                        
                        _flags.free = source->_flags.free;
                        _flags.del  = source->_flags.del;
                        _flags.readfree  = source->_flags.readfree;
                        
                        source->_flags.free = source->_flags.del = 
                            source->_flags.readfree = false;
                    }
                    else
                    {
                        _flags.free = _flags.del = _flags.readfree = false;
                    }
                }
            }
 
 
            virtual void ShallowCopy (const SdsIdType source, const bool free=false, 
                                      const bool del = false, const bool readfree = false) {
                CleanUp("sds::Id::ShallowCopy 3");      /* Run destructor on old id */
                _flags.free = free;
                _flags.del = del; 
                _flags.readfree = readfree;
                _id = source;
            }
 
            virtual void ToSdsId(::SdsId *target, const bool outlives= false) {
                if (outlives)
                {
                    /*
                     * If the target outlives the source, then copy the
                     * flags and then clear the close versions.
                     */
                    target->ShallowCopy(_id, _flags.free, 
                                        _flags.del, _flags.readfree);
                    _flags.free     = false;
                    _flags.del      = false;
                    _flags.readfree = false;
                }
                else
                {
                    /*
                     * Otherwise the defaults will do.
                     */
                    target->ShallowCopy(_id);
                }
            }
 
            template <typename T> void ArrayAccess(
                ArrayAccessHelper<T> * const data) const {
                
                unsigned long dims[SDS_C_MAXARRAYDIMS];
                CheckArrayTypeSingleDim(data->Code(), dims);
                data->SetNumElements(dims[0]);
                SetArrayHelperDataAddr(data);
            }
            template <typename T> void ArrayAccess(
                const unsigned long nitems, /* Expected number of elements in array*/
                sds::ArrayAccessHelper<T> * const data) const {
                
                unsigned long dims[SDS_C_MAXARRAYDIMS];
                CheckArrayTypeSingleDim(data->Code(), dims);
                if (dims[0] != nitems)
                {
                    DramaTHROW_S(SDS__INVDIMS,
                                 "ArrayAccess expected % items, found %",
                                 nitems, dims[0]);
                }
                data->SetNumElements(dims[0]);
                SetArrayHelperDataAddr(data);
            }
            template <typename T, class ContainerType> void ArrayAccess(
                ArrayAccessHelper<T> * const data,
                long ndims,
                ContainerType *dims) const {
 
 
                
                if ((ndims < 1)||(ndims > SDS_C_MAXARRAYDIMS))
                {
                    DramaTHROW_S(SDS__INVDIMS,
                                 "Failed to access SDS array. Numbers of dimensions % invalid, must be in range 1 to %",
                                 ndims, SDS_C_MAXARRAYDIMS);
 
                }
                CheckArrayType(data->Code(), ndims, dims);
                
                /*
                 * work out the number of elements
                 */
                unsigned long elements = (*dims)[0];
                for (unsigned long i = 1; i < dims->size() ; ++i)
                {
                    elements *= (long)((*dims)[i]);
                }
                data->SetNumElements(elements);
                /*
                 * Access the data.
                 */
                SetArrayHelperDataAddr(data);
            }
            
            
            template <typename T, class ContainerType> void ArrayAccess(
                ArrayAccessHelper<T> * const data,
                ContainerType *dims ) const {
                
                /*
                 * A bit of a pain, we need to call Dims to get the number
                 * of dimensions.
                 */
                GetDims(dims);
                /*
                 * The use the above version where we know the number of dimensions
                 */
                ArrayAccess(data, dims->size(), dims);
            }
            
 
            /*** ARG style methods ***/
 
            static Id CreateArgStruct(const std::string &name = "ArgStructure");
 
            template <typename ContainerType>
            static Id CreateArgCmdStruct(
                const ContainerType &values,
                const std::string &name="ArgStructure") {
 
 
                Id item(CreateArgStruct(name));
 
                std::string itemName = "Argument";
 
                unsigned argNum = 1;
                for (auto s: values) {
                    
                    std::string thisName = itemName + std::to_string(argNum);
                    
                    item.Put(thisName,s);
                    
                    ++argNum;
                    
                }
                
                return item;
 
            }
            template <typename T>
            static Id CreateArgCmdStruct(
                const std::initializer_list<T> &values,
                const std::string &name="ArgStructure") {
 
                return CreateArgCmdStruct(std::vector<T>(values), name);
            }
            template <typename T>
            static Id CreateArgCmdStructSingle(
                const T value,
                const std::string &name="ArgStructure") {
 
 
                Id item(CreateArgStruct(name));
                item.Put("Argument1",value);
                return item;
            }
 
 
            template <typename ContainerType>
            void AddToArgCmdStruct(
                const ContainerType &values,
                const unsigned firstArg = 1) {
 
                std::string itemName = "Argument";
 
                unsigned argNum = firstArg;
                if (argNum == 0) argNum = 1;
                for (auto s: values) {
                    
                    std::string thisName = itemName + std::to_string(argNum);
                    
                    Put(thisName,s);
                    
                    ++argNum;
                    
                }
            }
 
 
 
            virtual std::string toString(int maxlen = 200) {
                
                /*
                 * Allocate some space to store the string in.
                 */
                //std::unique_ptr<char[]> string(new char[maxlen]);
                char *string = new char[maxlen];
                int length=0;
                StatusType status = STATUS__OK;
                /*
                 * ArgToString() does the job for us.
                 */
                ArgToString((SdsIdType)(*this),maxlen,&length,&string[0],&status);
                if (status != STATUS__OK)
                {
                    delete[] string;
                    DramaTHROW(status, "Failed to convert SDS to string");
                }
 
                std::string result=&string[0];
    
                return result;
            }
            template <typename T>
            void Put (const std::string &name, T value, const std::string &extraData="") {
 
                
                StatusType status = STATUS__OK;
                /* There must be a specialization of SdsArgPut() which
                   supports type T. Note that conversion  of DRAMA status
                   to DRAMA 2 exceptions is done here so it need only be
                   done once.
                */
                SdsArgPut(_id, name, value, &status);
                if (status != STATUS__OK)
                    DramaTHROW_S(status, 
                                 "ArgPut failed of item \"%\" failed",
                                 name);
                if (extraData != "")
                {
                    auto itemId = Find(name);
                    itemId.PutExtra(extraData);
                }
    
            }
 
            void Put (const std::string &name, const std::string &value, 
                      const std::string &extraData="") {
 
                
                StatusType status = STATUS__OK;
                ArgPutString(_id, name.c_str(), value.c_str(), &status);
                if (status != STATUS__OK)
                    DramaTHROW_S(status, 
                                 "ArgPut failed of item \"%\" failed",
                                 name);
                if (extraData != "")
                {
                    auto itemId = Find(name);
                    itemId.PutExtra(extraData);
                }
     
            }
            template <typename T>
            void Get (const std::string &name, T *value) const {
 
                
                StatusType status = STATUS__OK;
                /* There must be a specialization of SdsArgGet() which
                   supports type T.  Note that conversion  of DRAMA status
                   to DRAMA 2 exceptions is done here so it need only be
                   done once.
                */
                SdsArgGet(_id, name, value, &status);
                if (status != STATUS__OK)
                    DramaTHROW_S(status, 
                                 "ArgGet failed of item \"%\" failed",
                                 name);
    
            }
 
 
            template <typename T>
            void Put (T value) {
 
                
                StatusType status = STATUS__OK;
                /* There must be a specialization of PutScalar() which
                   supports type T. Note that conversion  of DRAMA status
                   to DRAMA 2 exceptions is done here so it need only be
                   done once.
                */
                PutScalar(_id, value, &status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "PutScalar failed of item failed");
    
            }
 
            void Put (const std::string &value) {
 
                
                StatusType status = STATUS__OK;
                ArgCvt(value.c_str(),ARG_STRING,ARG_SDS,&_id,0,&status);
 
                if (status != STATUS__OK)
                    DramaTHROW(status, "ArgCvt failed of item failed");
    
            }
            template <typename T>
            void Get (T *value) const {
 
                
                StatusType status = STATUS__OK;
                /* There must be a specialization of GetScalar() which
                   supports type T.  Note that conversion  of DRAMA status
                   to DRAMA 2 exceptions is done here so it need only be
                   done once.
                */
                GetScalar(_id, value, &status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "GetScalar failed of item failed");
    
            }
 
 
            template <class ContainerType> 
            void CheckItem(SdsCodeType code, 
                           const ContainerType& dims) const {
 
 
                StatusType status = STATUS__OK;
                /*
                 * "dims" can be any container that
                 *   1. Has a size method.
                 *   2. Can be used to initialize a std::vector of unsigned long.
                 *   3. And it is validated for a    0 <= size <= 7.  
                 *        (Note - dims.size() is unsigned)
                 */
                if (dims.size() > SDS__MAXDIMS)
                {
                    DramaTHROW_S(SDS__MAXDIMS,
                                 "Failed to check SDS array - % dimensions, minimum supported 0, maximum supported is %",
                                 dims.size(),
                                 SDS_C_MAXARRAYDIMS);
                }
 
                /*
                 * We need to pass an array of unsigned long to ArgCheckItem for
                 * the dimensions.  The best approach is to create a vector
                 * of unsigned long and initialize it with the contents of
                 * our passed in container.
                 */
                std::vector<long> myDims(dims);
 
                ArgCheckItem(_id,code, myDims.size(),myDims.data(),&status);
 
                if (status != STATUS__OK)
                    DramaTHROW(status, "Check of SDS item failed");
 
            }
            virtual int GetInt() const;
            virtual unsigned int GetUInt() const;
            virtual long GetLong() const;
 
            virtual unsigned long GetULong() const;
            virtual double GetDouble() const;
 
            std::string GetString() const;
 
 
 
            /* Enable watching of this SDS id.  
             *
             * Output will go to stderr and any older watch details
             * are lost
             */
            void SetWatch() {
                StatusType status = STATUS__OK;
                SdsSetWatch(_id, nullptr, nullptr, 
                            nullptr, nullptr, nullptr, &status);
                if (status != STATUS__OK)
                    DramaTHROW(status, "SdsSetWatch failed");
            }
 
        }; /* class Id */
 
        class  IdChecker {
        private:
            SdsCheckType _chkData;
            int _line;
            std::string _file;
            std::string _function;
        public:
            IdChecker(int line, const char *file, const char *function) 
                : _line(line), _file(file), _function(function) {
                StatusType ignore = STATUS__OK;
                SdsCheckInit(&_chkData, &ignore);
            }
            virtual ~IdChecker() {
                StatusType status = STATUS__OK;
                SdsCheck(0, &_chkData, &status);
                if (status == SDS__CHK_LEAK)
                    fprintf(stderr,"Warning:sds::IdChecker:Function leaked SDS id's - function %s, file %s, check object at line %d\n", _function.c_str(), _file.c_str(), _line);
                else if (status == SDS__CHK_RELEASED)
                    fprintf(stderr,"Warning:sds::IdChecker:Function released SDS id's - function %s, file %s, check object at line %d\n", _function.c_str(), _file.c_str(), _line);
            }
        };
#define SDS_CHECK_IDS2(function_) drama::sds:IdChecker _sds_id_checker(__LINE__, __FILE__, (function_))
 
 
        typedef std::shared_ptr<Id> IdPtr;
 
 
 
        /*
         * This structure is used to specify a deleter to unique_ptr in
         * the DataPointer class.  It provides a null deleter operation as
         * SDS will handle tidying this up.
         */
        struct _nodel
        {
            void operator()(void *) const { }
        };
 
        template <typename T>
        class DataPointer : public std::unique_ptr<T,_nodel> {
            
        private:
            unsigned long _lengthBytes;  // Length of item in bytes.
            drama::sds::Id _refId;       // SDS Id.
        public:
            DataPointer(const drama::sds::Id &theId) {
                
                /*
                 * Confirm the data type is a POD type.
                 *   From C++20, std::is_pod<>() is depreciated, we can replace 
                 *     by std::is_standard_layout<>::value 
                 */
                static_assert(
                    std::is_standard_layout<T>::value,
                    "The type T must be a standard layout and type"); 
 
                T *dataPnt = 0;
                theId.Pointer(&dataPnt, &_lengthBytes);
 
                if (_lengthBytes != sizeof(T))
                {
                    DramaTHROW_S(DRAMA2__LENGTH_ERR,  
                                 "SDS Pointer error - expected % bytes, got %",
                                 sizeof(T), _lengthBytes);
                    
                }
                
                
                std::unique_ptr<T, _nodel> p(dataPnt, _nodel());
        
                *((std::unique_ptr<T,_nodel>*)(this)) = std::move(p);
                
                _refId.ShallowCopy(theId);
                
            }
            DataPointer(drama::sds::Id *theId, bool outlives) {
                
 
                /*
                 * Confirm the data type is a POD type.
                 *   From C++20, std::is_pod<>() is depreciated, we can replace 
                 *     by std::is_standard_layout<>::value
                 */
                static_assert(
                    std::is_standard_layout<T>::value,
                    "The type T must be a standard layout type"); 
 
                T *dataPnt = 0;
                theId->Pointer(&dataPnt, &_lengthBytes);
 
                if (_lengthBytes != sizeof(T))
                {
                    DramaTHROW_S(DRAMA2__LENGTH_ERR,  
                                 "SDS Pointer error - expected % bytes, got %",
                                 sizeof(T), _lengthBytes);
                    
                }
                
                
                std::unique_ptr<T, _nodel> p(dataPnt, _nodel());
        
                *((std::unique_ptr<T,_nodel>*)(this)) = std::move(p);
                
                _refId.ShallowCopy(theId, outlives);
                
            }
 
 
            ~DataPointer() {
                try 
                {
                    _refId.Flush();
                }
                catch (...)
                {
                }
            }
            unsigned long NumBytes() const {
                return _lengthBytes;
            }
        }; // class DataPointer
        
        template <typename T>
        class DataPointer<T[]> : public std::unique_ptr<T[], _nodel> {
            
        private:
            unsigned long  _numItems;
            unsigned long _lengthBytes;
            drama::sds::Id _refId;
        public:
            typedef T * iterator;
            typedef const T * const_iterator;
            typedef T value_type;
            
            DataPointer(const drama::sds::Id &theId) {
                
 
                /*
                 * Confirm the data type is a POD type.
                 *   From C++20, std::is_pod<>() is depreciated, we can replace 
                 *     by std::is_standard_layout<>::value
                 */
                static_assert(
                    std::is_standard_layout<T>::value,
                    "The type T must be a standard layout type"); 
 
                T *dataPnt = 0;
                theId.Pointer(&dataPnt, &_lengthBytes);
                
                if (_lengthBytes < sizeof(T))
                {
                    DramaTHROW_S(DRAMA2__LENGTH_ERR, 
                                 "SDS Array Pointer error - expected at least % bytes, got %",
                                 sizeof(T), _lengthBytes);
                    
                }
 
 
                _numItems = _lengthBytes/sizeof(dataPnt[0]);
                
                
                std::unique_ptr<T[], _nodel> p(dataPnt, _nodel());
                
                *((std::unique_ptr<T[],_nodel>*)(this)) = std::move(p);
                
                _refId.ShallowCopy(theId);
                
            }
            DataPointer(drama::sds::Id *theId, bool outlives=false) {
                
 
                /*
                 * Confirm the data type is a POD type.
                 *   From C++20, std::is_pod<>() is depreciated, we can replace 
                 *     by std::is_standard_layout<>::value
                 */
                static_assert(
                    std::is_standard_layout<T>::value,
                    "The type T must be a standard layout type"); 
 
                T *dataPnt = 0;
                theId->Pointer(&dataPnt, &_lengthBytes);
                
                if (_lengthBytes < sizeof(T))
                {
                    DramaTHROW_S(DRAMA2__LENGTH_ERR, 
                                 "SDS Array Pointer error - expected at least % bytes, got %",
                                 sizeof(T), _lengthBytes);
                    
                }
 
 
                _numItems = _lengthBytes/sizeof(dataPnt[0]);
                
                
                std::unique_ptr<T[], _nodel> p(dataPnt, _nodel());
                
                *((std::unique_ptr<T[],_nodel>*)(this)) = std::move(p);
                
                _refId.ShallowCopy(theId, outlives);
                
            }
 
            ~DataPointer() {
                try 
                {
                    _refId.Flush();
                }
                catch (...)
                {
                }
            }
            unsigned long size() const {
                return _numItems;
            }
            unsigned long NumBytes() const {
                return _lengthBytes;
            }
            iterator begin() {
                return & (*this)[0];
            }
            iterator end() {
                return (&(*this)[0])+_numItems;
            }
            const_iterator begin() const {
                return & (*this)[0];
            }
            const_iterator end() const {
                return (&(*this)[0])+_numItems;
            }
            const_iterator cbegin() const {
                return & (*this)[0];
            }
            const_iterator cend() const {
                return (&(*this)[0])+_numItems;
            }
            bool empty() const {
                return false;
            }
            
        }; // class DataPointer - Array Partial specialization
 
        /*
         * We need to implement the std::iterator template to ensure we pick
         * up various iterator types etc.  
         *
         * It is unclear if we need to define the third argument to this 
         * template,  if we do, I'm not sure what it should be.
         * 
         * std::iterator was depreciated from C++17, we are supposed
         *  to now provide each of the relevant types explicitly. 
         *  See  https://www.fluentcpp.com/2018/05/08/std-iterator-deprecated/ and
         *       http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0174r2.html#2.1
         */
        class IdIterator /*: public std::iterator<std::forward_iterator_tag, Id> */ {
        public: /* std::iterator equivalents */
            using iterator_category = std::forward_iterator_tag;
            using value_type = Id;
            using difference_type =std::ptrdiff_t;
            using pointer = Id*;
            using reference = Id&;
 
        private:
            /* The item we are iterating through */
            const Id &_top;          
            /* Is the item an array of structures.  If false, presumed to
             * be a structure (validated by constructor)
             */
            bool _isArray = false;
            /* Index to Current component  */
            unsigned long  _curCell = ULONG_MAX;
            /* Index to last component + 1 */
            unsigned long  _endCell = ULONG_MAX;
        public:
            explicit IdIterator(const Id & id, const bool setEnd=false) : 
                _top(id) {
                /*
                 * id must be a structure.
                 */
                if (_top.GetCode() != SDS_STRUCT)
                {
                    DramaTHROW_S(DRAMA2__SDS_ITER_TYPE_ERR,
                                 "Attempt to construct IdIterator on non-structured SDS item (code %)", _top.GetCode());
                    
                }
                /*
                 * Grab the dimensions - can only work with a value of 0 or 1.
                 */
                std::vector<unsigned> dims;
                _top.GetDims(&dims);
                if (dims.size() > 0)
                {
                    /*
                     * Array item.
                     */
                    _isArray = true;
                    /*
                     * Code does not yet handle dimensions greater then 1, as
                     * that requires determining the order we index the
                     * array etc.
                     */
                    if (dims.size() > 1)
                    {
                        DramaTHROW(DRAMA2__SDS_ITER_TYPE_ERR,
                                   "Attempt to construct IdIterator on an array of structures with more then 1 dimension - can't yet do that. ");
                    }
                    /*
                     * Index of arrays starts at 1. dims[0] is one
                     * past the last element.
                     */
                    _endCell = dims[0]+1;
                    _curCell = 1;
                }
                else
                {
                    /*
                     * Indexing of structures starts at 1. GetNumItems() is
                     * the maximum value.
                     */
                    _endCell = id.GetNumItems()+1;
                    _curCell = 1;
                }
                /*
                 * IF we are constructing the end item, set _curCell to _endCell.
                 */
                if (setEnd)
                    _curCell = _endCell;
            }
 
            bool operator!= (const IdIterator& other) const {
                /* First ensure we are referring to the same SDS structure */
                if (&_top != &other._top)
                    return false;
                return _curCell != other._curCell;
            }
 
            Id operator* () const {
                if (_curCell >= _endCell)
                {
                    DramaTHROW(DRAMA2__SDS_ITER_DEREF_ERR,
                               "Attempt to dereference IdIterator past end of structure");
 
 
                }
                if (_isArray) {
                    std::vector<unsigned long> indicies(1);
                    indicies[0] = _curCell;
                    return _top.Cell(indicies);
                } else {
                    return _top.Index(_curCell);
                }
            }
            const IdIterator & operator++ () {
                /*
                 * Only increment if less then _endCell.  This should ensure
                 * we never advance past _endCell, ensuring that the comparison
                 * against end() works correctly 
                 */
                if (_curCell <  _endCell)
                    ++_curCell;
 
                // although not strictly necessary for a range-based for loop
                // following the normal convention of returning a value from
                // operator++ is a good idea.
                return *this;
            }
 
 
        private:
        }; // class IdIterator
 
 
 
        template <typename T>
        class ArrayContainer {
        public:
            typedef T value_type;
            typedef value_type& reference;
            typedef std::size_t size_type;
        private:
            T *_address = nullptr;
            size_type _size = 0;
        public:
            ArrayContainer(T *address, size_type size) : 
                _address(address), _size(size){
                static_assert(
                    std::is_standard_layout<T>::value,
                    "The type T must be a standard layout and type"); 
            }
            bool empty() const {
                return (_size <= 0);
            }
            size_type size() const {
                return _size;
            }
            reference operator[](size_type n) {
                return _address[n];
            }
            ~ArrayContainer() {}
        }; // Class ArrayContainer
 
 
        inline drama::sds::IdIterator begin(const drama::sds::Id &id) {
            return drama::sds::IdIterator(id);
        }
        inline drama::sds::IdIterator end(const drama::sds::Id &id) {
            return drama::sds::IdIterator(id, true);
        }
 
    } // namespace sds
 
} // namespace drama
 
#endif