disti_metadata.h

Go to the documentation of this file.

///   \file
///   \brief  The disti metadata.
///
///   \par Copyright Information
///
///   Copyright (c) 2017 by The DiSTI Corporation.<br>
///   11301 Corporate Blvd; Suite 100<br>
///   Orlando, Florida 32817<br>
///   USA<br>
///   <br>
///   All rights reserved.<br>
///
///   This Software contains proprietary trade secrets of DiSTI and may not be
/// reproduced, in whole or part, in any form, or by any means of electronic,
/// mechanical, or otherwise, without the written permission of DiSTI.  Said
/// permission may be derived through the purchase of applicable DiSTI product
/// licenses which detail the distribution rights of this content and any
/// Derivative Works based on this or other copyrighted DiSTI Software.
///
///   NO WARRANTY. THE SOFTWARE IS PROVIDED "AS-IS," WITHOUT WARRANTY OF ANY KIND,
/// AND ANY USE OF THIS SOFTWARE PRODUCT IS AT YOUR OWN RISK. TO THE MAXIMUM EXTENT
/// PERMITTED BY APPLICABLE LAW, DISTI AND ITS SUPPLIERS DISCLAIM ALL WARRANTIES
/// AND CONDITIONS, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
/// IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY AND/OR FITNESS FOR A
/// PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE.
///
///   LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW,
/// IN NO EVENT SHALL DISTI OR ITS SUPPLIERS BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
/// INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION,
/// DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
/// INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE USE OF OR
/// INABILITY TO USE THE SOFTWARE, EVEN IF DISTI HAS BEEN ADVISED OF THE POSSIBILITY
/// OF SUCH DAMAGES.  DISTI'S ENTIRE LIABILITY AND YOUR EXCLUSIVE REMEDY SHALL NOT
/// EXCEED FIVE DOLLARS (US$5.00).
///
///   The aforementioned terms and restrictions are governed by the laws of the
/// State of Florida and the United States of America.
 
#ifndef INCLUDED_DISTI_METADATA_H
#define INCLUDED_DISTI_METADATA_H
 
#if defined( WIN32 )
#    pragma warning( push )
#    pragma warning( disable : 4786 )
#    pragma warning( disable : 4251 ) // This may hide non-exported code.
#endif
 
#include "disti_include.h"
#include "dynamic_array.h"
#include "gls_cpp_lang_support.h"
#include "scoped_ptr.h"
#include "unhide_globals.h"
#include "weak_reference.h"
#include "weak_referenceable_mixin.h"
 
#include <cfloat>
#include <cstdarg>
#include <cstring>
#include <iostream>
#include <list>
#include <map>
#include <sstream>
 
#if defined( LINUX )
#    include <cstdlib>
#    include <typeinfo>
#endif
 
/// Macro to exclude attribute name debug code when not used.
#if GLS_DEBUG_ATTRIBUTE_NAMES
#    define IF_GLS_DEBUG_ATTRIBUTE_NAMES( x ) x
#else
#    define IF_GLS_DEBUG_ATTRIBUTE_NAMES( x )
#endif
 
namespace disti
{
class CallbackMethodCallerBase;
const int MAX_ATTRIBUTE_NAME_LENGTH = 128; ///< Unused, remains for backward compatibility.
 
/** AttributeName class can be treated like a std::string in some instances
  * It creates static storage for any referenced name.
  * This results in only one copy for each name which saves memory
  * Very fast comparison between references to names
  */
class AttributeName
{
public:
    /// Constructor
    /// Explicit because construction of an AttributeName is an
    /// expensive operation.  If possible you should use a static
    /// AttrbuteName object rather than constructing a new
    /// one each time it is needed.
    /// \param name The desired name.
    DISTI_EXPORT explicit AttributeName( const std::string& name );
 
    /// Constructor
    /// See comments on AttributeName(const std::string &name)
    /// \param name The desired name.
    DISTI_EXPORT explicit AttributeName( const char* name );
 
    /// Constructor
    /// \param stringIndex  The index into the string map.
    DISTI_EXPORT explicit AttributeName( long stringIndex );
 
    /// Copy constructor
    /// \param other The object to copy from.
    AttributeName( const AttributeName& other ) DISTI_FUNC_NOEXCEPT
        : _stringIndex( other._stringIndex )
    {
        IF_GLS_DEBUG_ATTRIBUTE_NAMES( _name = *this );
    }
 
    /// Copy assignment operator
    /// \param other The object to copy from.
    /// \return The resulting object (this).
    AttributeName& operator=( const AttributeName& other ) DISTI_FUNC_NOEXCEPT
    {
        _stringIndex = other._stringIndex;
        IF_GLS_DEBUG_ATTRIBUTE_NAMES( _name = *this );
        return *this;
    }
 
    /// \return The index to the string associate with this instance.
    long StringIndex() const { return _stringIndex; }
 
    /// Defines the cast operator to make this look like a std::string for reading
    DISTI_EXPORT operator std::string() const;
 
private:
    long _stringIndex;
 
    // for easier debugging
    IF_GLS_DEBUG_ATTRIBUTE_NAMES( std::string _name; )
 
    /** Attempts to find the specified name.
      * If found _stringIndex is set to its index
      * otherwise a new one is created and its index is saved */
    void Initialize( const char* name );
};
 
/// Stream out operator.
/// \param outstr The stream to write to.
/// \param name The value to write to the stream.
/// \return The stream in its current state.
DISTI_EXPORT std::ostream& operator<<( std::ostream& outstr, const AttributeName& name );
 
/// Compares this string to the specified AttributeName.
/// This compare is very fast compared to doing string compares, and is
/// one of the primary reasons for creating this class
/// \param attr1 A name to compare.
/// \param attr2 The other name to compare.
/// \return Whether or not the names are the same.
inline bool operator==( const AttributeName& attr1, const AttributeName& attr2 )
{
    return attr1.StringIndex() == attr2.StringIndex();
}
 
/// Compares this string for inequality to the specified AttributeName.
/// This compare is very fast compared to doing string compares, and is
/// one of the primary reasons for creating this class
/// \param attr1 A name to compare.
/// \param attr2 The other name to compare.
/// \return Whether or not the names are not the same.
inline bool operator!=( const AttributeName& attr1, const AttributeName& attr2 )
{
    return !( attr1 == attr2 );
}
 
/// Compare two attribute names in various formats.
/// \param lName A name to compare.
/// \param rName The other name to compare.
/// \return Whether or not the names are the same.
DISTI_EXPORT bool operator==( const AttributeName& lName, const char* rName );
 
/// Compare two attribute names in various formats.
/// \param lName A name to compare.
/// \param rName The other name to compare.
/// \return Whether or not the names are the same.
DISTI_EXPORT bool operator==( const char* lName, const AttributeName& rName );
 
/// Compare two attribute names in various formats.
/// \param lName A name to compare.
/// \param rName The other name to compare.
/// \return Whether or not the names are the same.
DISTI_EXPORT bool operator==( const std::string& lName, const AttributeName& rName );
 
/// Compare two attribute names in various formats.
/// \param lName A name to compare.
/// \param rName The other name to compare.
/// \return Whether or not the names are the same.
DISTI_EXPORT bool operator==( const AttributeName& lName, const std::string& rName );
 
/// Add a string literal suffix operator to allow "MyAttribute"_Attr for creation of attributes.
DISTI_IF_HAS_USER_DEFINED_LITERAL( inline AttributeName operator""_Attr( const char* str, std::size_t ) { return AttributeName( str ); } )
 
class DistiAttributeBase;
 
/** Class used to call a callback method that takes a DistiAttributeBase */
class AttributeObserver
{
public:
    /// Call the callback with the provided display event.
    /// \param attr The attribute associated with this callback.
    virtual void Call( DistiAttributeBase& attr ) = 0;
 
    /// When IsValid is false, then this AttributeObserver can be deleted.
    /// \return Whether or not this observer is attached to a valid attribute.
    virtual bool IsValid() const = 0;
 
    virtual ~AttributeObserver() {}
};
 
class DistiAttributeObserverList;
 
/** \class DistiAttributeBase
  *  This is the base class for all Disti Attributes.
  */
class DistiAttributeBase : public WeakReferenceableMixin
{
private:
    DistiAttributeBase( const DistiAttributeBase& ) DISTI_SPECIAL_MEM_FUN_DELETE;
 
protected:
    /** The name of this attribute */
    AttributeName _name;
    /** The callback which is called when the value of this object changes */
    CallbackMethodCallerBase* _callback;
 
    /** The list of observers to be notified when this property changes. */
    ScopedPtr<DistiAttributeObserverList> _observerList;
 
    /** _localStorage is true if this attributes data should be copied.
      * It would typically be set false if the data is stored externally,
      * and there is no need to copy the data through metadata. 
      * It is also used to determine if storage should be deleted.*/
    bool _localStorage;
 
public:
    /** Constructor
      * \param callback The method to call when the value changes.  A duplicate of the
               CallbackMethodCallerBase is created and stored internally. 
      * \param name The name of the attribute
      * \param localStorage True if this DistiAttribute contains actual storage,
               rather than just a pointer to somebody elses storage*/
    DISTI_EXPORT DistiAttributeBase( CallbackMethodCallerBase* callback, const AttributeName& name, bool localStorage );
 
    /// This will perform the copy using ReadValue() and WriteValue()
    /// It can be overridden by any dervied classes to do a smarter more efficent copy.
    /// \param oldClass The object to copy from.
    /// \return The resulting object (this).
    virtual DISTI_EXPORT DistiAttributeBase& operator=( const DistiAttributeBase& oldClass );
 
    virtual DISTI_EXPORT ~DistiAttributeBase();
 
    /// \return The name of this object.
    DISTI_EXPORT const AttributeName& Name() const;
 
    /// \returns The name of this object.
    DISTI_EXPORT AttributeName& Name();
 
    /// \return True if this object has local storage.
    DISTI_EXPORT bool LocalStorage() const;
 
    /// It is not a word, but it means it is able to be copied.
    /// \note By default, will only copy if it contains local storage
    /// \return True if it makes sense for the data to be copied.
    virtual DISTI_EXPORT bool Copyable() const;
 
    /// This SHOULD be overriden by any derived objects that may not be ready to write at any point.
    /// The reason for this is the data is often written "NAME: VALUE".
    /// If Value is not available, we don't want to write "NAME: " first, so before
    /// writing "NAME: ", OkToWrite() can be called to see if it will have a valid value.
    /// \return True if this object is ready to have its WriteValue() called.
    virtual DISTI_EXPORT bool OkToWrite() const;
 
    /// \note This is not implmented in the base class and will always return true if not overridden.
    /// \return True if the object's value has changed since calling ResetValueChanged().
    virtual DISTI_EXPORT bool ValueChanged();
 
    /// Saves the current value for later comparison by ValueChanged().
    /// \note This does nothing in the base class.
    virtual DISTI_EXPORT void ResetValueChanged();
 
    /// Here in the base class it uses WriteValue().
    /// If this particular attribute's underlying type is a string, this returns the unencoded value, suitable for users.
    /// If a file encoded value is required, call WriteValue instead.
    /// \return The std::string version of the attribute data.
    virtual DISTI_EXPORT std::string ValueString();
 
    /// Sets the value from a std::string argument.
    /// Here in the base class it uses ReadValue().
    /// If this particular attribute's underlying type is a string, this should not be set to an encoded value.
    /// If needing to set from an encoded value, call ReadValue instead.
    /// \param s The string value to set.
    virtual DISTI_EXPORT void ValueString( const std::string& s );
 
    /// Allows for faster access to integer types than the more generic stream operators.
    /// \note This is only faster if it is overridden.
    /// \return The integer value of this attribute.
    virtual DISTI_EXPORT long ValueInt();
 
    /// Allows for faster access to integer types than the more generic stream operator.
    /// \note This is only faster if it is overridden.
    /// \param val The new integer value to set.
    virtual DISTI_EXPORT void ValueInt( long val );
 
    /// Allows for faster access to floating-point types than the more generic stream operators.
    /// \note This is only faster if it is overridden.
    /// \return The double value of this attribute.
    virtual DISTI_EXPORT double ValueFloat();
 
    /// Allows for faster access to floating-point types than the more generic stream operator.
    /// \note This is only faster if it is overridden.
    /// \param val The new double value to set.
    virtual DISTI_EXPORT void ValueFloat( double val );
 
    /// Calls callback CallType3 if it has been set.
    virtual DISTI_EXPORT void CallCallback();
 
    /// Pure virtual because this is specific to the data type to be contained.
    /// This should be overridden to write the data to the stream.
    /// The value written could be encoded for writing to a file as a single string,
    /// or have its own special encoding specific to its underlying type.
    /// In the case of attribute strings, this will be the GLS file encoded value.
    /// The user is responsible for decoding the value themselves, or using ReadValue
    /// which should perform decoding to maintain symmetry.
    /// \param outstr The stream to write to.
    /// \return The output stream in its current state.
    virtual std::ostream& WriteValue( std::ostream& outstr ) = 0;
 
    /// Pure virtual because this is specific to the data type to be contained.
    /// This should be overridden to read the data from the stream.
    /// The value read could be encoded for being read from a file as a single string,
    /// or have its own special encoding specific to its underlying type.
    /// In the case of attribute strings, this will be the GLS file encoded value.
    /// The user is responsible for encoding the value themselves, or using WriteValue
    /// which should perform encoding to maintain symmetry.
    /// \param instr The stream to read from.
    /// \return The input stream in its current state.
    virtual std::istream& ReadValue( std::istream& instr ) = 0;
 
    /// Compares name and value.
    /// \note This can be overriden to improve speed.
    /// \param r The attribute to compare.
    /// \return Whether or not the attributes have the same name and value.
    virtual DISTI_EXPORT bool operator==( const DistiAttributeBase& r );
 
    /// Allow for generic access to some data types.
    /// This will NOT work for types which: s << val does not work.
    /// In general if the WriteValue is overridden, then it probably will not work.
    /// \param val The new value to set.
    /// \return The updated attribute (this).
    template<class valType>
    DistiAttributeBase& operator<<( const valType& val )
    {
        std::stringstream s;
        // Ensure numeric values make it into the attribute's ReadValue implementation unmodified.
        s.precision( MaxDigits10<long double>::value );
        s << val;
        ReadValue( s );
        return *this;
    }
 
    /// Allows for generic access to some data types.
    /// This will NOT work for types which: s >> val does not work.
    /// In general if the ReadValue is overridden, then it probably will not work.
    /// \param val The value to be returned.
    /// \return This attribute (unmodified, unless there are side effects).
    template<class valType>
    DistiAttributeBase& operator>>( valType& val )
    {
        std::stringstream s;
        WriteValue( s );
        s >> val;
        return *this;
    }
 
    /// Stream out operator.
    /// \note Internally it uses WriteValue().
    /// \param outstr Stream to write path to.
    /// \param attribute The value to write to the stream.
    /// \return The stream in its current state.
    friend DISTI_EXPORT std::ostream& operator<<( std::ostream& outstr, const DistiAttributeBase& attribute );
 
    /// Stream in operator.
    /// \note Internally it uses ReadValue().
    /// \param instr The stream to read from.
    /// \param attribute The returned value read from the stream.
    /// \return The stream in its current state.
    friend DISTI_EXPORT std::istream& operator>>( std::istream& instr, DistiAttributeBase& attribute );
 
    /// Type for unique identifiers
    typedef unsigned int CallbackID;
 
    /** Register a callback that is called when the value of the attribute changes.  If multiple oservers are registered, they will be notified in the order they registered.
      * DistiAttributeBase takes ownership of the observer and will delete it. 
      * \param observer the observer to notify.  It is automatically unregistered and destroyed when it becomes invalid.
      * \return an id that can be used to unregister the observer
      */
    virtual DISTI_EXPORT CallbackID RegisterObserver( AttributeObserver* observer );
 
    /** Unregister an observer
      * \param id the id returned when the observer was registered
      */
    virtual DISTI_EXPORT void UnregisterObserver( CallbackID id );
 
    /** Triggers all observers to have their callbacks called.  Typically called by the class that owns the DistiAttributeBase */
    virtual DISTI_EXPORT void NotifyObservers();
};
 
/** Template for an AttributeCallbackBase that will call a class method whenever the attribute changes. The class must implement WeakReferenceable. 
  * Don't use this directly, use CreateAttributeMethodCallback instead.
  */
template<class T>
class AttributeMethodCallback : public AttributeObserver
{
public:
    typedef void ( T::*Callback )( DistiAttributeBase& attr ); ///< Typedef for the callback function pointer.
 
    /// Construct a new AttributeMethodCallback object to link the callback and the class containing it.
    /// \param object The object containing the callback method.
    /// \param method The method to call back.
    AttributeMethodCallback( T* object, Callback method )
        : _method( method )
        , _object( object )
    {
        GLS_VERIFY( NULL != method );
        GLS_VERIFY( NULL != object );
    }
 
    void Call( DistiAttributeBase& ev ) DISTI_METHOD_OVERRIDE
    {
        if( IsValid() )
        {
            ( _object.Get()->*( _method ) )( ev );
        }
    }
 
    virtual bool IsValid() const DISTI_METHOD_OVERRIDE
    {
        return !_object.IsNull();
    }
 
protected:
    Callback   _method; ///< Method to call back when invoked.
    WeakRef<T> _object; ///< The underlying object containing the callback method.
};
 
/// Create an AttributeMethodCallback that will call a class method whenever the attribute changes.
/// \param obj The object to call the method on.
/// \param method A class method pointer.
/// \return The created AttributeMethodCallback.
template<class Class>
AttributeObserver* CreateAttributeMethodCallback(
    Class* const                                            obj,
    const typename AttributeMethodCallback<Class>::Callback method )
{
    return new AttributeMethodCallback<Class>( obj, method );
}
 
/** Template for an AttributeCallbackBase that will set another object's attribute whenever the attribute changes. The class must implement WeakReferenceable. 
  * Don't use this directly, use CreateAttributeResourceCallback instead.
  */
template<class T>
class AttributeResourceCallback : public AttributeObserver
{
public:
    /// Construct a new AttributeResourceCallback object to link an attribute to an attribute of another object.
    /// \param object The object containing the attribute.
    /// \param attributeName The attribute to set.
    AttributeResourceCallback( T* object, const AttributeName& attributeName )
        : _attributeName( attributeName )
        , _object( object )
    {
        GLS_VERIFY( NULL != object );
    }
 
    void Call( DistiAttributeBase& attr ) DISTI_METHOD_OVERRIDE
    {
        if( IsValid() )
        {
            if( DistiAttributeBase* objAttr = _object.Get()->Attributes().Get( _attributeName ) )
            {
                ( *objAttr ) << attr.ValueString();
            }
        }
    }
 
    virtual bool IsValid() const DISTI_METHOD_OVERRIDE
    {
        return !_object.IsNull();
    }
 
protected:
    AttributeName _attributeName; ///< The attribute to set when invoked.
    WeakRef<T>    _object;        ///< The object containing the attribute.
};
 
/// Create an CreateAttributeResourceCallback that will set another object's attribute whenever the attribute changes.
/// \param obj The object to set the resource on.
/// \param attributeName The name of the property.
/// \return The created CreateAttributeResourceCallback.
template<class Class>
AttributeObserver* CreateAttributeResourceCallback(
    Class* const obj,
    const char*  attributeName )
{
    return new AttributeResourceCallback<Class>( obj, AttributeName( attributeName ) );
}
 
/** Interface for notifying when attributes have changed */
class AttributeChangedNotifier
{
public:
    /** Notify the class that the attribute has changed.  Observers of the attribute will have their callbacks called 
      * \param name the name of the attribute
      */
    virtual DISTI_EXPORT void NotifyAttributeChanged( const AttributeName& name ) = 0;
 
    /** destructor */
    virtual ~AttributeChangedNotifier() {}
};
 
/** helper method to notify if an attribute has changed through a setter method
  * \param object the object to notify
  * \param property the storage for the data that is going to be set
  * \param newValue the new value to set
  * \param name the attribute name
  */
template<class T>
void SetAndNotifyIfChanged( AttributeChangedNotifier* object, T& property, const T& newValue, const AttributeName& name )
{
    if( newValue != property )
    {
        property = newValue;
        object->NotifyAttributeChanged( name );
    }
}
 
/** \class DistiAttribute 
  * A templated class for creating attributes.
  */
class DistiAttribDict;
template<class T>
class DistiAttribute : public DistiAttributeBase
{
protected:
    /** Points to the actual storage */
    T* _attribPtr;
    /** Allows for setting of precision for floating point numbers */
    int _precision;
 
public:
    /** Constructor
      * Keeps a pointer to the specified type
      * \param callback The method to call when the value changes.  A duplicate of the
      *        CallbackMethodCallerBase is created and stored internally. 
      * \param name The name of the attribute
      * \param attribPtr The address of the storage.
      */
    DistiAttribute( CallbackMethodCallerBase* callback, const AttributeName& name, T* attribPtr )
        : DistiAttributeBase( callback, name, false )
        , _attribPtr( attribPtr )
        , _precision( MaxDigits10<T>::value )
    {
    }
 
    /** Constructor
      * Actually creates storage of the specified type
      * \param callback The method to call when the value changes.  A duplicate of the
      *        CallbackMethodCallerBase is created and stored internally. 
      * \param name The name of the attribute
      * \param initialValue The initial value of the internally stored variable.
      */
    DistiAttribute( CallbackMethodCallerBase* callback, const AttributeName& name, const T& initialValue )
        : DistiAttributeBase( callback, name, true /*Because we actually have storage*/ )
        , _attribPtr( new T( initialValue ) )
        , _precision( MaxDigits10<T>::value )
    {
    }
 
    /// \return Whether or not this attribute is copyable (which it is).
    bool Copyable() const DISTI_METHOD_OVERRIDE { return true; }
 
    /// \return The integer value of this attribute.
    long ValueInt() DISTI_METHOD_OVERRIDE
    {
        return DistiAttributeBase::ValueInt();
    }
 
    /// Set the integer value of this attribute.
    /// \param val The integer value to set for this attribute.
    void ValueInt( long val ) DISTI_METHOD_OVERRIDE
    {
        DistiAttributeBase::ValueInt( val );
    }
 
    /// \return The double value of this attribute.
    double ValueFloat() DISTI_METHOD_OVERRIDE
    {
        return DistiAttributeBase::ValueFloat();
    }
 
    /// Set the double value for this attribute.
    /// \param val The double value to set for this attribute.
    void ValueFloat( double val ) DISTI_METHOD_OVERRIDE
    {
        DistiAttributeBase::ValueFloat( val );
    }
 
    /// Assignment operator
    /// \param oldClass The attribute to assign.
    /// \return The resulting attribute (this).
    DistiAttributeBase& operator=( const DistiAttributeBase& oldClass ) DISTI_METHOD_OVERRIDE
    {
        DistiAttribute* ptr;
 
        ptr = dynamic_cast<DistiAttribute*>( const_cast<DistiAttributeBase*>( &oldClass ) );
        if( ptr )
        {
            Value( ptr->Value() );
        }
        else
        {
            return DistiAttributeBase::operator=( oldClass );
        }
        return *this;
    }
 
    /// Write this attribute's string value to the stream.
    /// \param outstr The stream to write to.
    /// \return The stream in its updated state.
    std::ostream& WriteValue( std::ostream& outstr ) DISTI_METHOD_OVERRIDE
    {
        if( _precision > 0 )
            outstr.precision( _precision );
 
        //operator<<(outstr, *_attribPtr);
        outstr << *_attribPtr;
        return outstr;
    };
 
    /// Read from the stream, and store it in this attribute.
    /// \param instr The stream to read from.
    /// \return The stream in its updated state.
    std::istream& ReadValue( std::istream& instr ) DISTI_METHOD_OVERRIDE
    {
        return ReadValueImpl( instr );
    };
 
    /// Allows for type specific access to the data.
    /// \return The underlying value of the attribute in its type.
    virtual T Value()
    {
        return *_attribPtr;
    }
 
    /// Allows for type specific access to the data.
    /// \param val The value to set in the attribute's type.
    virtual void Value( const T& val )
    {
        *_attribPtr = val;
        CallCallback();
    }
 
    /// Performs type specific comparison.
    /// This results in faster comparisons than the base class
    /// \param rArg The attribute to compare.
    /// \return Whether or not the attribute names and values are the same.
    bool operator==( const DistiAttributeBase& rArg ) DISTI_METHOD_OVERRIDE
    {
        DistiAttribute<T>* r = dynamic_cast<DistiAttribute<T>*>( const_cast<DistiAttributeBase*>( &rArg ) );
        if( !r )
            return false;
 
        if( !( _name == r->_name ) )
            return false;
 
        return Value() == r->Value();
    }
 
    /** Destructor 
      * deletes local storage if we created it */
    ~DistiAttribute() DISTI_METHOD_OVERRIDE
    {
        // Only delete it if we created it.
        if( _localStorage )
        {
            delete _attribPtr;
        }
        _attribPtr = NULL;
    }
 
private:
    std::istream& ReadValueImpl( std::istream& instr )
    {
        GLS_ASSERT( _attribPtr );
        instr >> *_attribPtr;
        CallCallback();
 
        return instr;
    }
};
 
/** Optimized ReadValueImpl for floating point types.
  * Visual Studio 2012 (vc110) runtime performs much slower when using
  * std::istream::operator>>( float& val )
  */
template<>
inline std::istream& DistiAttribute<float>::ReadValueImpl( std::istream& instr )
{
    char instrBuf[ 64 ];
    instr >> instrBuf;
    *_attribPtr = static_cast<float>( atof( instrBuf ) );
    CallCallback();
 
    return instr;
}
 
template<>
inline std::istream& DistiAttribute<double>::ReadValueImpl( std::istream& instr )
{
    char instrBuf[ 64 ];
    instr >> instrBuf;
    *_attribPtr = atof( instrBuf );
    CallCallback();
 
    return instr;
}
 
/** The Attribute Dictionary is a container for DistiAttributeBase derived objects */
class DistiAttribDict DISTI_FINAL
{
public:
    /** Allows for easy access to the contained class type */
    typedef DistiAttributeBase* Attr_t;
 
    typedef std::list<Attr_t>           List_t; ///< Typedef for a list of attribute pointers.
    typedef std::multimap<long, Attr_t> Map_t;  ///< Typedef for a map ot attribute pointers.
 
    typedef List_t::const_iterator const_iterator; ///< Shorthand for List_t::const_iterator.
    typedef List_t::iterator       iterator;       ///< Shorthand for List_t::iterator.
 
    /** Constructor */
    DISTI_EXPORT DistiAttribDict();
 
    /** Destructor */
    DISTI_EXPORT ~DistiAttribDict();
 
#if defined( DISTI_HAS_RVAL_REFS )
    /// Move constructor
    /// \param other The object to move.
    DISTI_EXPORT DistiAttribDict( DistiAttribDict&& other )
    {
        *this = std::move( other );
    }
 
    /// Move Assignment
    /// \param other The object to move.
    /// \return This object, post move.
    DISTI_EXPORT DistiAttribDict& operator=( DistiAttribDict&& other )
    {
        if( this != &other )
        {
            _list = std::move( other._list );
            _map  = std::move( other._map );
        }
        return *this;
    }
#endif
 
    /** Used as needed for version specific parsing
      * Whenever a version is parsed, the results should be stored here.
      * This does add order dependency. 
      *
      * Note: These are not set or used by the DistiAttribDict class
      * they are here to be set and accessed by the derived Attributes.
      * Since they are shared by all instances of DistiAttribDict, they
      * are only valid while the dictionary is parsing a file.
      */
    static DISTI_EXPORT unsigned int _currentFileVersionMajor;
    /** \sa _currentFileVersionMajor */
    static DISTI_EXPORT unsigned int _currentFileVersionMinor;
    /** \sa _currentFileVersionMajor */
    static DISTI_EXPORT unsigned int _currentFileVersionBuild;
 
    /** \deprecated Do not use. Will be removed in a later version. */
    static DISTI_EXPORT double _currentFileVersionPrimary;
    /** \deprecated Do not use. Will be removed in a later version. */
    static DISTI_EXPORT long _currentFileVersionSecondary;
 
    /// Copies the values for all items which have matching names between this object and \a dict.
    /// All other values are ignored.
    /// \param dict The dictionary to copy from.
    /// \return The combined dictionary (this).
    /// \deprecated Use CopyCommonValues() instead.
    DISTI_DEPRECATED( "Renamed to CopyCommonValues() to better represent the action taken by this function." )
    DISTI_EXPORT DistiAttribDict& operator=( const DistiAttribDict& dict )
    {
        CopyCommonValues( dict );
        return *this;
    }
 
    /// Copies the values for all items which have matching names between this object and \a dict.
    /// All other values are ignored.
    /// \param dict The dictionary to copy from.
    DISTI_EXPORT void CopyCommonValues( const DistiAttribDict& dict );
 
    /// Equality operator
    /// Compares length, names and values, order does not matter.
    /// \param other The other dictionary to compare.
    /// \return Whether or not the dictionaries are equivalent.
    DISTI_EXPORT bool operator==( const DistiAttribDict& other );
 
    /// Adds the specified Attribute to the list. The object passed in becomes the responsibility
    /// of this class, and should NOT be deleted by the caller. It will be deleted by this class as needed.
    /// \param attr The attribute to add.
    DISTI_EXPORT void Add( DistiAttributeBase* attr );
 
    /// \return A const iterator to the beginning of the list.
    const_iterator Begin() const { return _list.begin(); }
 
    /// \return A const iterator to the end of the list.
    const_iterator End() const { return _list.end(); }
 
    /// \return A iterator to the beginning of the list.
    iterator Begin() { return _list.begin(); }
 
    /// \return A iterator to the end of the list.
    iterator End() { return _list.end(); }
 
    /// \return The current number of elements in the dictionary.
    int DISTI_EXPORT Count() const;
 
    /// \param name The name of the element(s) to count up.
    /// \return The number of elements with the same name in the dictionary.
    int DISTI_EXPORT Count( const AttributeName& name ) const;
 
    /** Removes all elements in the list, deleting the data as it goes */
    void DISTI_EXPORT Clear();
 
    /// Removes the attribute specified by name from the dictionary and deletes the data.
    /// \param name The name of the attribute to remove.
    /// \note This does actually delete the attribute.
    DISTI_EXPORT void Delete( const AttributeName& name );
 
    /// Reads a stream, expecting each line to be of the form: NAME: SomeStringValue
    /// For each line a new DistiAttribute<std::string> is created, and the remaining line is placed as it's value.
    /// This is intended for special uses and is not considered the 'normal' mode of operation.
    /// \param instr The stream to read from.
    DISTI_EXPORT void ReadStrings( std::istream& instr );
 
    /// Writes all items in the dictionary to the stream in the form: "NAME: VALUE"
    /// If changedDataOnly is true, only items which return ValueChanged() == true will be written.
    /// \param outstr The stream to write to.
    /// \param changedDataOnly Whether or not to only write items where ValueChanged() == true.
    DISTI_EXPORT void Write( std::ostream& outstr, bool changedDataOnly = false );
 
    /// Reads multiple attributes from the stream expecting the form: "NAME: VALUE"
    /// \param instr The stream to read from.
    /// \return True if something was found and set..
    DISTI_EXPORT bool Read( std::istream& instr );
 
    /// Reads multiple attributes from the stream expecting the form: "NAME: VALUE"
    /// missing stream is filled with attributes that were not in the dictionary
    /// \param instr The stream to read from.
    /// \param missingStream The return stream to write attributes that were not found.
    /// \return True if something was found and set.
    DISTI_EXPORT bool ReadAndCaptureMissing( std::istream& instr, std::stringstream* missingStream );
 
    /// \param name The name of the attribute whose value is to be returned.
    /// \return The std::string value of the attribute specified by name, "" if not found.
    /// \note Internally it uses ValueString() from the attribute
    DISTI_EXPORT std::string ValueString( const AttributeName& name ) const;
 
    /// Sets the attribute of named 'name' to the value of 'val'.
    /// \param name The attribute name whose value is to be set.
    /// \param val The string value to set.
    /// \note If name is not found, there is no indication or error given.
    DISTI_EXPORT void ValueString( const AttributeName& name, const std::string& val );
 
    /// \param name The name of the attribute whose value is to be returned.
    /// \return The ValueInt() of the named attribute.
    DISTI_EXPORT long ValueInt( const AttributeName& name ) const;
 
    /// Sets the ValueInt() of the named attribute.
    /// \param name The attribute name whose value is to be set.
    /// \param val The int value to set.
    DISTI_EXPORT void ValueInt( const AttributeName& name, long val );
 
    /// Calls WriteValue() for the attribute specified by name.
    /// \param name The name of the attribute to write out.
    /// \param outstr The stream to write to.
    /// \return The stream that was written to, in its current state.
    DISTI_EXPORT std::ostream& WriteValue( const AttributeName& name, std::ostream& outstr );
 
    /// Calls ReadValue() for the attribute specified by name.
    /// \param name The name of the attribute to read in.
    /// \param instr The stream to read from.
    /// \return The stream that was read from, in its current state.
    DISTI_EXPORT std::istream& ReadValue( const AttributeName& name, std::istream& instr );
 
    /// \param name The name of the attribute to return.
    /// \return The DistiAttributeBase* for the specified name, if not found it returns NULL.
    DISTI_EXPORT DistiAttributeBase* Get( const AttributeName& name ) const;
 
    /// \param name The name of the attribute to compare.
    /// \param val The value to compare the attribute value with.
    /// \return A comparison of val with ValueInt() of the attribute looked up by name, false if not found.
    DISTI_EXPORT bool IsEqual( const AttributeName& name, const long val ) const;
 
    /** Static, data for formating output */
    static DISTI_EXPORT int currentOutputSpacing; // Should be private
 
    /** Static, Increments the current spacing */
    static DISTI_EXPORT void SpacingInc();
 
    /** Static, Decrements the current spacing */
    static DISTI_EXPORT void SpacingDec();
 
    /** Static, Sets the spacing to zero */
    static DISTI_EXPORT void SpacingZero();
 
    /// \note static
    /// \return A string containing the current spacing.
    static DISTI_EXPORT std::string SpacingString();
 
    /// Static method used for parsing a stream.
    /// Used internally and exposed here so others can use it.
    /// \param instr The stream to read from.
    /// \param result The returned string that was parsed.
    /// \return True if parse was successful.
    static DISTI_EXPORT bool ScanToken( std::istream& instr, std::string& result );
 
    /// Removes the attribute specified by name.
    /// \param name The name of the attribute to remove.
    /// \note This does NOT actually delete the attribute, just removes it from the dictionary.
    DISTI_EXPORT void Remove( const AttributeName& name );
 
private:
    List_t _list;
    Map_t  _map;
 
    /** Disable copy construction.
      * \note copy-assignment will also be disabled in the future. 
      * \sa CopyCommonValues(). */
    DistiAttribDict( const DistiAttribDict& ) DISTI_SPECIAL_MEM_FUN_DELETE;
};
 
/// Iterator interface for use in range-for loops etc.
/// \param dict The DistiAttribDict whose iterator is to be returned.
/// \return A const iterator to the beginning of the list.
inline DistiAttribDict::const_iterator begin( const DistiAttribDict& dict ) { return dict.Begin(); }
 
/// Iterator interface for use in range-for loops etc.
/// \param dict The DistiAttribDict whose iterator is to be returned.
/// \return A const iterator to the end of the list.
inline DistiAttribDict::const_iterator end( const DistiAttribDict& dict ) { return dict.End(); }
 
/// Iterator interface for use in range-for loops etc.
/// \param dict The DistiAttribDict whose iterator is to be returned.
/// \return An iterator to the beginning of the list.
inline DistiAttribDict::iterator begin( DistiAttribDict& dict ) { return dict.Begin(); }
 
/// Iterator interface for use in range-for loops etc.
/// \param dict The DistiAttribDict whose iterator is to be returned.
/// \return An iterator to the end of the list.
inline DistiAttribDict::iterator end( DistiAttribDict& dict ) { return dict.End(); }
 
////////////////////////////////////////////////////////////
// Some useful derivations
////////////////////////////////////////////////////////////
 
/** \class DistiAttributeEnumStringPair
    * A string to enumeration mapping
    */
typedef struct
{
    char _string[ 64 ]; ///< String value for enumeration.
    int  _enum;         ///< Integer value for enumeration.
} DistiAttributeEnumStringPair;
 
/** A list of enumeration definitions */
class DistiAttributeEnumDefList : public std::list<DistiAttributeEnumStringPair*>
{
public:
    /// Create a new DistiAttributeEnumDefList object.
    /// \param stringVal The first string value of the list.
    DISTI_EXPORT DistiAttributeEnumDefList( char* stringVal, ... );
 
    /// Return the associated integer value with the enumeration string
    /// \param string The string whose enum value is to be returned.
    /// \return The enumeration value, 0 if the string isn't present in the list.
    virtual DISTI_EXPORT int EnumToInt( const std::string& string );
 
    virtual DISTI_EXPORT ~DistiAttributeEnumDefList();
};
 
/** \class DistiAttributeEnum
  * A Disti Attribute which reads and writes enumerations.
  */
template<class containerClass, class setType, class getType>
class DistiAttributeEnum : public DistiAttributeBase
{
public:
    typedef void ( containerClass::*SetMethodType )( setType ); ///< Typedef for the set method function pointer.
    typedef getType ( containerClass::*GetMethodType )();       ///< Typedef for the get method function pointer.
 
    DistiAttributeEnumDefList* _pairList; ///< A list of name value pairs describing the enumeration.
    containerClass*            _object;   ///< Object that contains the attribute.
 
    SetMethodType _setMethod; ///< Set method member function pointer.
    GetMethodType _getMethod; ///< Get method member function pointer.
 
    /// Create a new DistiAttributeEnum object, able to convert string and int enum values between one another.
    /// \param object The object containing the enumeration.
    /// \param setMethod The set method pointer for the property.
    /// \param getMethod The get method pointer for the property.
    /// \param name The name of the attribute to contain the enumeration.
    DistiAttributeEnum( containerClass* object, SetMethodType setMethod, GetMethodType getMethod, const AttributeName& name )
        : DistiAttributeBase( NULL, name, false )
        , _object( object )
        , _setMethod( setMethod )
        , _getMethod( getMethod )
    {
        GLS_ASSERT( setMethod );
        GLS_ASSERT( getMethod );
    }
 
    virtual ~DistiAttributeEnum()
    {
    }
 
    /// \return The integer value via the underlying get method.
    virtual long ValueInt() DISTI_METHOD_OVERRIDE
    {
        return (long)( _object->*_getMethod )();
    }
 
    /// Set the integer value via the underlying set method.
    /// \param val The new integer value to set.
    virtual void ValueInt( long val ) DISTI_METHOD_OVERRIDE
    {
        ( _object->*_setMethod )( (setType)val );
    };
 
    /// Assignment operator.
    /// \param oldClass The attribute to assign to.
    /// \return The resulting attribute (this).
    virtual DistiAttributeBase& operator=( const DistiAttributeBase& oldClass ) DISTI_METHOD_OVERRIDE
    {
        DistiAttributeEnum<containerClass, getType, setType>* ptr = dynamic_cast<DistiAttributeEnum<containerClass, getType, setType>*>( const_cast<DistiAttributeBase*>( &oldClass ) );
        if( ptr )
        {
            ValueInt( ptr->ValueInt() );
        }
        else
        {
            return DistiAttributeBase::operator=( oldClass );
        }
        return *this;
    }
 
    /// Write this attribute's string value to the stream.
    /// \param outstr The stream to write to.
    /// \return The stream in its updated state.
    virtual std::ostream& WriteValue( std::ostream& outstr ) DISTI_METHOD_OVERRIDE
    {
        bool                                foundIt = false;
        getType                             value   = ( _object->*_getMethod )();
        DistiAttributeEnumDefList::iterator item    = _pairList->begin();
        while( item != _pairList->end() && *item )
        {
            if( ( *item )->_enum == value )
            {
                outstr << ( *item )->_string;
                foundIt = true;
                break;
            }
            ++item;
        }
        if( !foundIt )
        {
            //Didn't find it so just write the number
            outstr << value;
        }
        return outstr;
    }
 
    /// Return the associated integer value with the enumeration string.
    /// \param string The string whose enum value is to be returned.
    /// \return The enumeration value, 0 if the string isn't present in the list.
    int EnumToInt( std::string& string )
    {
        int                                 returnVal = 0;
        DistiAttributeEnumDefList::iterator item      = _pairList->begin();
 
        while( item != _pairList->end() && *item )
        {
            if( strcmp( ( *item )->_string, string.c_str() ) == 0 )
            {
                returnVal = ( *item )->_enum;
                break;
            }
            ++item;
        }
        return returnVal;
    }
 
    /// Read from the stream, and store it in this attribute.
    /// \param instr The stream to read from.
    /// \return The stream in its updated state.
    virtual std::istream& ReadValue( std::istream& instr ) DISTI_METHOD_OVERRIDE
    {
        char value[ 64 ];
        instr >> value;
 
        bool                                foundIt = false;
        DistiAttributeEnumDefList::iterator item    = _pairList->begin();
 
        // First look by enumeration
        while( item != _pairList->end() && *item )
        {
            if( strcmp( ( *item )->_string, value ) == 0 )
            {
                ( _object->*_setMethod )( (setType)( *item )->_enum );
 
                foundIt = true;
                break;
            }
            ++item;
        }
 
        // If not found, assume that the numerical value is specified.
        if( !foundIt )
        {
            ( _object->*_setMethod )( (setType)atoi( value ) );
        }
        return instr;
    }
};
 
} // namespace disti
 
#if defined( WIN32 )
#    pragma warning( pop )
#endif
 
#endif