tb_dynamic_structure.hpp

 
#ifndef TurtleBrains_DynamicStructure_hpp
#define TurtleBrains_DynamicStructure_hpp
 
#include <turtle_brains/core/tb_string.hpp>
#include <turtle_brains/core/tb_types.hpp>
#include <turtle_brains/core/tb_file_utilities.hpp>
 
#include <cmath>
#include <vector>
#include <map>
#include <string>
#include <limits>
#include <initializer_list>
 
//
// As of 2025-11-08: TurtleBrains has consistent support for ToString/FromString, ToDynamicStructure/FromDynamicStructure
//   and WriteBinary/ReadBinary across the board. This was surprisingly done without polluting the global namespace.
//   There is a bit of setup every project needs to do to make the magic work. Start by creating the following generic
//   template functions and just let those pass through to TurtleBrains specific ones. Then template specializations for
//   the objects in your game/project will automatically work along side any of the built-in TurtleBrains types.
//
// For example project named "Playground"
//  namespace Playground {
//      template<typename Type> void ToString(const Type& object) { tbCore::ToString(object); }
//      template<typename Type> void FromString(const String& string) { return tbCore::FromString<Type>(string); }
//      template<typename Type> void ToDynamicStructure(const Type& object) { tbCore::ToString(object); }
//      template<typename Type> void FromDynamicStructure(const DynamicStructure& data) {
//          return tbCore::FromDynamicStructure<Type>(data);
//      }
//      template<typename Type> void WriteBinary(const Type& object, tbCore::OutputFile& outputFile) {
//          tbCore::FileUtilities::WriteBinary(object, outputFile);
//      }
//      template<typename Type> void ReadBinary(const Type& object, tbCore::InputFile& inputFile) {
//          tbCore::FileUtilities::ReadBinary(object, inputFile);
//      }
//      template<typename Type> Type ReadBinary(tbCore::InputFile& inputFile) {
//          return tbCore::FileUtilities::ReadBinary<Type>(inputFile);
//      }
//  };
//
// Now you'll see ReadBinary has two versions, ReadBinary(inputFile) shouldn't need any specializations, it should call
//   the ReadBinary(object, inputFile) automatically so you only need to worry about the one matching WriteBinary().
//
// Any area of your project that knows of those templates can now create a specialization for your specific object with
//   a template specialization. Lets say you had a Vehicle object;
//
//  template<> void ToString<Vehicle>(const Vehicle& object) { return object.make + " " + object.model; }
//
//
// NOTE!!!! 2025-11-11: If we are using ice we will actually need the project implementations to call InternalCombustion
//   versions in order to hop through the namespacing. Like using ice::FromDynamicStructure<Type>(data) instead of tbCore.
//   And if we use TrackBuilder it would need to be TrackBuilder::ToString() which then ice::ToString() which then calls
//   TurtleBrains::ToString(). This is the only way through the namespace boundaries...
//
// CRITICAL NOTE: 2025-11-11: ADL (Argument Dependent-Lookup) apparently crosses the namespace borders and will create
//   an ambiguity without the project specificying Rushcremental::FromDynamicStructure(). Interestingly this ONLY applies
//   to DynamicStructure, because DynStruct is in the tbCore namespace and and ADL then brings it up as an option? So
//   if String became an actual tbCore object type (rather than using String = std::string) To/FromString would have the
//   same ambiguity problems...
//
 
namespace TurtleBrains::Core
{
    class DynamicStructure;
 
    namespace FileUtilities
    {
        template<> void WriteBinary<tbCore::DynamicStructure>(const tbCore::DynamicStructure& data, TurtleBrains::Core::OutputFile& outputFile);
 
        template<> void ReadBinary<tbCore::DynamicStructure>(tbCore::DynamicStructure& object, TurtleBrains::Core::InputFile& inputFile);
    };
};
 
namespace TurtleBrains::Core
{
    class DynamicStructure
    {
    public:
        static const DynamicStructure& Nil(void);
        static DynamicStructure EmptyArray(void);
 
        typedef std::vector<DynamicStructure> ArrayContainer;
 
        typedef std::map<String, DynamicStructure> StructureContainer;
 
        DynamicStructure(void);
 
        DynamicStructure(const int& integerValue);
        DynamicStructure(const tbCore::int64& integerValue);
        //can't add tbCore::uint32 because size_t could match it...
        DynamicStructure(const size_t& integerValue);
 
        //maybe someday this would be good to add a template ctor for integer types.
        //template<typename IntegerType> DynamicStructure(const IntegerType
 
        DynamicStructure(const float& floatValue);
 
        DynamicStructure(const bool& booleanValue);
 
        DynamicStructure(const String& stringValue);
 
        DynamicStructure(const char* stringValue);
 
        template<typename Type> DynamicStructure(std::initializer_list<const Type> arguments) :
            mValueType(kNilType),
            mInteger(0)
        {
            for (auto value : arguments)
            {
                PushValue(value);
            }
        }
 
        DynamicStructure(std::initializer_list<std::pair<const String, const DynamicStructure>> arguments);
 
        DynamicStructure(const DynamicStructure& other) noexcept;
 
        DynamicStructure(DynamicStructure&& other) noexcept;
 
        DynamicStructure& operator=(const DynamicStructure& other) noexcept;
 
        DynamicStructure& operator=(DynamicStructure&& other) noexcept;
 
        ~DynamicStructure(void);
 
 
        bool IsNil(void) const;
 
        bool IsArray(void) const;
 
        bool IsStructure(void) const;
 
        bool IsInteger(void) const;
 
        bool IsFloat(void) const;
 
        bool IsBoolean(void) const;
 
        bool IsString(void) const;
 
 
        tbCore::int64 AsInteger(bool implicitConversion = kImplicitConversions) const;
 
        // template<typename Type> typename std::enable_if<std::is_unsigned<Type>::value, Type>::type
        // AsRangedInteger(const String& errorMessage,
        //  const Type minimumValue = MinimumValue<Type>(), const Type maximumValue = MaximumValue<Type>(),
        //  bool implicitConversion = kImplicitConversions) const
        // {
        //  const tbCore::int64 intValue = AsInteger(implicitConversion);
 
        //  tb_error_if(std::is_unsigned<Type>::value && intValue < 0, "%s (Expected _value(%d) to be greater than 0 for unsigned ranges.",
        //      errorMessage.c_str(), intValue);
 
        //  //int32 intValue = -1   :  0x0001FFFF  //131k
 
        //  //uint16  min 0         :  0x00000000
        //  //uint16  max 65        :  0x0000FFFF
 
 
        //  //int64 value  0x00000000-FFFFFFFF
        //  //int64 min    0x00000000-00000000
        //  //int64 max    0x00000000-FFFFFFFF
 
        //  //int32 to uint32 65xxx :  0xFFFFFFFF
 
 
        //  tb_error_if(static_cast<Type>(intValue) < (minimumValue) || static_cast<Type>(intValue) > (maximumValue),
        //      "%s (Expected: %d <= _value(%d)_ <= %d", errorMessage.c_str(), minimumValue, intValue, maximumValue);
        //  return static_cast<Type>(intValue);
        // }
        template<typename Type> Type AsRangedInteger(const String& errorMessage = "Out of Range",
            const Type minimumValue = std::numeric_limits<Type>::min(), const Type maximumValue = std::numeric_limits<Type>::max(),
            bool implicitConversion = kImplicitConversions) const
        {
            const tbCore::int64 intValue = AsInteger(implicitConversion);
 
            if (std::is_unsigned<Type>::value)
            {   //If type is unsigned, ensure it is not less than 0, then cast to an unsigned to compare vs other unsigned values.
                tb_error_if(intValue < 0, "%s (Expected _value(%d) to be greater than 0 for unsigned ranges.",
                    errorMessage.c_str(), intValue);
                tb_error_if(minimumValue < 0, "tbExternalError: Expected minimumValue of unsigned type to be greater than equal to 0.");
                tb_error_if(maximumValue < 0, "tbExternalError: Expected maximumValue of unsigned type to be greater than equal to 0.");
                tb_error_if(static_cast<uint64>(intValue) < static_cast<uint64>(minimumValue) || static_cast<uint64>(intValue) > static_cast<uint64>(maximumValue),
                    "%s (Expected: %d <= _value(%d)_ <= %d", errorMessage.c_str(), minimumValue, intValue, maximumValue);
            }
            else
            {
                tb_error_if(intValue < static_cast<int64>(minimumValue) ||intValue > static_cast<int64>(maximumValue),
                    "%s (Expected: %d <= _value(%d)_ <= %d", errorMessage.c_str(), minimumValue, intValue, maximumValue);
            }
 
            return static_cast<Type>(intValue);
        }
 
        template<typename Type> Type AsRangedIntegerWithDefault(const Type& defaultValue, const String& errorMessage = "Out of Range",
            const Type minimumValue = std::numeric_limits<Type>::min(), const Type maximumValue = std::numeric_limits<Type>::max(),
            bool implicitConversion = kImplicitConversions) const
        {
            if (true == IsNil() || (false == implicitConversion && false == IsInteger()))
            {
                return defaultValue;
            }
 
            return AsRangedInteger(errorMessage, minimumValue, maximumValue, implicitConversion);
        }
 
        float AsFloat(bool implicitConversion = kImplicitConversions) const;
 
        bool AsBoolean(bool implicitConversion = kImplicitConversions) const;
 
        String AsString(bool implicitConversion = kImplicitConversions) const;
 
        //
        // TODO: TurtleBrains: Planning: Do we want to support this?  If so implement and document.
        //   @note Cannot implicitly convert to a string, will assert if type is not a string.
        //
        //const String& AsStringRef(void) const;
 
        tbCore::int64 AsIntegerWithDefault(const tbCore::int64& defaultValue, bool implicitConversion = kImplicitConversions) const;
 
        float AsFloatWithDefault(const float defaultValue, bool implicitConversion = true) const;
 
        bool AsBooleanWithDefault(const bool defaultValue, bool implicitConversion = true) const;
 
        String AsStringWithDefault(const String& defaultValue, bool implicitConversion = true) const;
 
        void SetValue(const int& integerValue, bool implicitTypeChange = kImplicitTypeChange);
        void SetValue(const tbCore::int64& integerValue, bool implicitTypeChange = kImplicitTypeChange);
 
        void SetValue(const float& floatValue, bool implicitTypeChange = kImplicitTypeChange);
 
        void SetValue(const bool& booleanValue, bool implicitTypeChange = kImplicitTypeChange);
 
        void SetValue(const String& stringValue, bool implicitTypeChange = kImplicitTypeChange);
 
        //-------------------------------------------------------------------------------------------------------//
        //    Input and Output
        //-------------------------------------------------------------------------------------------------------//
    private:
 
        friend void TurtleBrains::Core::FileUtilities::WriteBinary<tbCore::DynamicStructure>(const tbCore::DynamicStructure& data, OutputFile& outputFile);
        friend void TurtleBrains::Core::FileUtilities::ReadBinary<tbCore::DynamicStructure>(tbCore::DynamicStructure& object, InputFile& inputFile);
 
        //-------------------------------------------------------------------------------------------------------//
        //  Ignore the mess of private API:
        //-------------------------------------------------------------------------------------------------------//
    private:
        const tbCore::DynamicStructure& LookupByNameOrIndex(tbCore::uint64 index) const;
        tbCore::DynamicStructure& LookupByNameOrIndex(tbCore::uint64 index);
        const tbCore::DynamicStructure& LookupByNameOrIndex(const std::string_view& memberName) const;
        tbCore::DynamicStructure& LookupByNameOrIndex(const std::string_view& memberName);
        const tbCore::DynamicStructure& LookupByNameOrIndex(const String& memberName) const;
        tbCore::DynamicStructure& LookupByNameOrIndex(const String& memberName);
        const tbCore::DynamicStructure& LookupByNameOrIndex(const char* memberName) const;
        tbCore::DynamicStructure& LookupByNameOrIndex(const char* memberName);
 
    public:
        template<typename Type> const DynamicStructure& operator[](const Type& nameOrIndex) const { return LookupByNameOrIndex(nameOrIndex); }
 
        template<typename Type> DynamicStructure& operator[](const Type& nameOrIndex) { return LookupByNameOrIndex(nameOrIndex); }
 
        //-------------------------------------------------------------------------------------------------------//
        //    Used ONLY for Array Values.  Type must be kArrayType or kNilType to PushValue
        //-------------------------------------------------------------------------------------------------------//
 
        DynamicStructure& PushValue(const DynamicStructure& value);
 
        const DynamicStructure& GetValue(const tbCore::uint64& arrayIndex) const;
 
        DynamicStructure& GetValue(const tbCore::uint64& arrayIndex);
 
        size_t ArraySize(void) const;
 
        size_t size(void) const;
 
        ArrayContainer::const_iterator BeginArray(void) const;
 
        ArrayContainer::iterator BeginArray(void);
 
        ArrayContainer::const_iterator begin(void) const;
 
        ArrayContainer::iterator begin(void);
 
        ArrayContainer::const_iterator EndArray(void) const;
 
        ArrayContainer::iterator EndArray(void);
 
        ArrayContainer::const_iterator end(void) const;
 
        ArrayContainer::iterator end(void);
 
        const ArrayContainer& AsArray(void) const;
 
        ArrayContainer& AsArray(void);
 
        //-------------------------------------------------------------------------------------------------------//
        //    Used ONLY for Structure Values.  Type must be kStructureType or kNilType to AddMember
        //-------------------------------------------------------------------------------------------------------//
 
        DynamicStructure& AddMember(const String& memberName, const DynamicStructure& memberValue);
 
        void RemoveMember(const String& memberName);
 
        DynamicStructure& SetMember(const String& memberName, const DynamicStructure& memberValue);
 
        const DynamicStructure& GetMember(const String& memberName) const;
 
        DynamicStructure& GetMember(const String& memberName);
 
        bool HasMember(const String& memberName) const;
 
        size_t StructureSize(void) const;
 
        StructureContainer::const_iterator BeginStructure(void) const;
 
        StructureContainer::iterator BeginStructure(void);
 
        StructureContainer::const_iterator EndStructure(void) const;
 
        StructureContainer::iterator EndStructure(void);
 
        const StructureContainer& AsStructure(void) const;
 
        StructureContainer& AsStructure(void);
 
        //TODO: TIM: Implementation: (Test) Add a way to iterate over all Members in a structure.
 
        //-------------------------------------------------------------------------------------------------------//
        //    Used ONLY for Structure or Array Values.
        //-------------------------------------------------------------------------------------------------------//
 
        //Acceptable Inputs:
        //  "engine.pistons[0].isDamaged"
        //const DynamicStructure& FromPath(const String& path) const;
 
        explicit operator tbCore::int64() const { return AsInteger(true); }
 
        explicit operator int() const { return AsRangedInteger<int>(); }
 
        explicit operator float() const { return AsFloat(true); }
 
        explicit operator bool() const { return AsBoolean(true); }
 
        explicit operator String() const { return AsString(true); }
 
        bool operator==(const DynamicStructure& rightSide) const;
 
        bool operator!=(const DynamicStructure& rightSide) const;
 
    private:
        void SetToNil(void);
 
        tbCore::int64 ConvertToInteger(void) const;
 
        float ConvertToFloat(void) const;
 
        bool ConvertToBoolean(void) const;
 
        String ConvertToString(void) const;
 
        enum class NotFoundPolicy { OnMissingError, OnMissingNull, OnMissingAdd };
 
        const DynamicStructure& ActuallyGetMember(const String& memberName, const NotFoundPolicy& policy = NotFoundPolicy::OnMissingError) const;
        DynamicStructure& ActuallyGetMember(const String& memberName, const NotFoundPolicy& policy = NotFoundPolicy::OnMissingError);
 
        enum DynamicStructureValueType : tbCore::uint8
        {
            kNilType,       
 
            kIntegerType,   
            kFloatType,     
            kBooleanType,   
            kStringType,    
 
            kArrayType,     
            kStructureType, 
        };
 
        DynamicStructureValueType mValueType;
 
        union
        {   //Unnamed anonymous union so DynamicStrucure contains the contents as its own members, "this->mRawBytes".
            char mRawBytes[8];     //Reserve 64-bits for whatever types follow.
            tbCore::int64 mInteger;
            bool mBoolean;
            float mFloat;
 
            String* mString;
            ArrayContainer* mArray;
            StructureContainer* mStructure;
        };
 
    public:
        static const DynamicStructure kNullValue;    
        static const String kNullAsString; 
        static const String kTrueAsString; 
        static const String kFalseAsString;
        static const unsigned int kInvalidSize;      
        static const bool kImplicitConversions;      
        static const bool kImplicitTypeChange;       
        static const float kFloatElipson;            
    };
 
    namespace Implementation {
        template<class> constexpr bool tbiDependentTrue = true;
    };
 
    String ToJsonString(const tbCore::DynamicStructure& data, bool prettyJson);
 
 
    std::ostream& operator<<(std::ostream& outputStream, const DynamicStructure& data);
 
    //This is actually not _that_ trivial, at least not with how we have implemented the operator<<. So we either
    //changed that format to make this easier, or ignore doing this for now. You can always save ToJsonString and
    //then use tbCore::ParseJson() to get back.
    //std::istream& operator>>(std::istream& inputStream, DynamicStructure& data);
 
    /* Overloads to make the DynamicStructure behave like a built in Integer */
    inline bool operator==(const DynamicStructure& leftSide, const int& rightSide) { return (leftSide.AsInteger() == rightSide) ? true : false; }
    inline bool operator==(const int& leftSide, const DynamicStructure& rightSide) { return (rightSide.AsInteger() == leftSide) ? true : false; }
    inline bool operator!=(const DynamicStructure& leftSide, const int& rightSide) { return (leftSide.AsInteger() != rightSide) ? true : false; }
    inline bool operator!=(const int& leftSide, const DynamicStructure& rightSide) { return (rightSide.AsInteger() != leftSide) ? true : false; }
 
    inline bool operator==(const DynamicStructure& leftSide, const tbCore::int64& rightSide) { return (leftSide.AsInteger() == rightSide) ? true : false; }
    inline bool operator==(const tbCore::int64& leftSide, const DynamicStructure& rightSide) { return (rightSide.AsInteger() == leftSide) ? true : false; }
    inline bool operator!=(const DynamicStructure& leftSide, const tbCore::int64& rightSide) { return (leftSide.AsInteger() != rightSide) ? true : false; }
    inline bool operator!=(const tbCore::int64& leftSide, const DynamicStructure& rightSide) { return (rightSide.AsInteger() != leftSide) ? true : false; }
 
    inline bool operator==(const DynamicStructure& leftSide, const float& rightSide) { return (fabs(leftSide.AsFloat() - rightSide) <= DynamicStructure::kFloatElipson)  ? true : false; }
    inline bool operator==(const float& leftSide, const DynamicStructure& rightSide) { return (fabs(rightSide.AsFloat() - leftSide) <= DynamicStructure::kFloatElipson) ? true : false; }
    inline bool operator!=(const DynamicStructure& leftSide, const float& rightSide) { return (fabs(leftSide.AsFloat() - rightSide) > DynamicStructure::kFloatElipson) ? true : false; }
    inline bool operator!=(const float& leftSide, const DynamicStructure& rightSide) { return (fabs(rightSide.AsFloat() - leftSide) > DynamicStructure::kFloatElipson) ? true : false; }
 
    inline bool operator==(const DynamicStructure& leftSide, const bool& rightSide) { return (leftSide.AsBoolean() == rightSide) ? true : false; }
    inline bool operator==(const bool& leftSide, const DynamicStructure& rightSide) { return (rightSide.AsBoolean() == leftSide) ? true : false; }
    inline bool operator!=(const DynamicStructure& leftSide, const bool& rightSide) { return (leftSide.AsBoolean() != rightSide) ? true : false; }
    inline bool operator!=(const bool& leftSide, const DynamicStructure& rightSide) { return (rightSide.AsBoolean() != leftSide) ? true : false; }
 
    inline bool operator==(const DynamicStructure& leftSide, const String& rightSide) { return (leftSide.AsString() == rightSide) ? true : false; }
    inline bool operator==(const String& leftSide, const DynamicStructure& rightSide) { return (rightSide.AsString() == leftSide) ? true : false; }
    inline bool operator!=(const DynamicStructure& leftSide, const String& rightSide) { return (leftSide.AsString() != rightSide) ? true : false; }
    inline bool operator!=(const String& leftSide, const DynamicStructure& rightSide) { return (rightSide.AsString() != leftSide) ? true : false; }
 
 
};  /* namespace TurtleBrains::Core */
 
namespace tbCore = TurtleBrains::Core;
 
namespace TurtleBrains
{
    using DynamicStructure = TurtleBrains::Core::DynamicStructure;
 
    template<typename Type> DynamicStructure ToDynamicStructure(const Type& object)
    {   // 2025-11-11: This is to fix something with clang v14.0.0 and static_assert failing even if the function is not
        //   called... This error should only happen if this very function would be used; it means the Type given does
        //   not have a template specialization. The dependentTrue is a workaround before CWG2518/P2593R1
        tb_static_error_if(true == Core::Implementation::tbiDependentTrue<Type>, "Missing a ToDynamicStructure() overload?");
        return Type();
    }
 
    template<typename Type> Type FromDynamicStructure(const DynamicStructure& data)
    {   // 2025-11-11: This is to fix something with clang v14.0.0 and static_assert failing even if the function is not
        //   called... This error should only happen if this very function would be used; it means the Type given does
        //   not have a template specialization. The dependentTrue is a workaround before CWG2518/P2593R1
        tb_static_error_if(true == Core::Implementation::tbiDependentTrue<Type>, "Missing a FromDynamicStructure() overload?");
        return Type();
    }
 
    template<> inline DynamicStructure ToDynamicStructure<int>(const int& value) { return tbCore::DynamicStructure(value); }
    template<> inline DynamicStructure ToDynamicStructure<bool>(const bool& value) { return tbCore::DynamicStructure(value); }
    template<> inline DynamicStructure ToDynamicStructure<float>(const float& value) { return tbCore::DynamicStructure(value); }
    template<> inline DynamicStructure ToDynamicStructure<String>(const String& value) { return tbCore::DynamicStructure(value); }
 
    template<> inline int FromDynamicStructure<int>(const DynamicStructure& data) { return data.AsRangedInteger<int>(); }
    template<> inline bool FromDynamicStructure<bool>(const DynamicStructure& data) { return data.AsBoolean(); }
    template<> inline float FromDynamicStructure<float>(const DynamicStructure& data) { return data.AsFloat(); }
    template<> inline String FromDynamicStructure<String>(const DynamicStructure& data) { return data.AsString(); }
};
 
#endif /* TurtleBrains_DynamicStructure_hpp */