#include <tb_dynamic_structure.hpp>

Public Types
typedef std::vector< DynamicStructure >	ArrayContainer

typedef std::map< String, DynamicStructure >	StructureContainer

Public Member Functions
	DynamicStructure (void)

	DynamicStructure (const int &integerValue)

	DynamicStructure (const tbCore::int64 &integerValue)

	DynamicStructure (const size_t &integerValue)

	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)

	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 >
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

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

float	AsFloat (bool implicitConversion=kImplicitConversions) const

bool	AsBoolean (bool implicitConversion=kImplicitConversions) const

String	AsString (bool implicitConversion=kImplicitConversions) 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)

template<typename Type >
const DynamicStructure &	operator[] (const Type &nameOrIndex) const

template<typename Type >
DynamicStructure &	operator[] (const Type &nameOrIndex)

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)

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)

	operator tbCore::int64 () const

	operator int () const

	operator float () const

	operator bool () const

	operator String () const

bool	operator== (const DynamicStructure &rightSide) const

bool	operator!= (const DynamicStructure &rightSide) const

Static Public Member Functions
static const DynamicStructure &	Nil (void)

static DynamicStructure	EmptyArray (void)

Static Public Attributes
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

Friends
void	TurtleBrains::Core::FileUtilities::WriteBinary (const tbCore::DynamicStructure &data, OutputFile &outputFile)

void	TurtleBrains::Core::FileUtilities::ReadBinary (tbCore::DynamicStructure &object, InputFile &inputFile)

Detailed Description

Provide a simple interface for creating structures that can be changed dynamically, for file loading, scripting and other exchanges of complex objects or structures in a semi defined manner.

Member Typedef Documentation

◆ ArrayContainer

typedef std::vector<DynamicStructure> TurtleBrains::Core::DynamicStructure::ArrayContainer

TODO: TIM: InternalDoc: This is a TurtleBrains implementation detail, and should be documented as such.

◆ StructureContainer

typedef std::map<String, DynamicStructure> TurtleBrains::Core::DynamicStructure::StructureContainer

TODO: TIM: InternalDoc: This is a TurtleBrains implementation detail, and should be documented as such.

Constructor & Destructor Documentation

◆ DynamicStructure() [1/9]

TurtleBrains::Core::DynamicStructure::DynamicStructure ( void )

Creates an empty "Nil" structure with no values or data contained.

◆ DynamicStructure() [2/9]

TurtleBrains::Core::DynamicStructure::DynamicStructure ( const int & integerValue )

Creates a DynamicStructure object from an integer value that will represent the integer.

Note: implicit conversion is desired in this case so we can do: object.AddMember("gearCount", 5);

◆ DynamicStructure() [3/9]

TurtleBrains::Core::DynamicStructure::DynamicStructure ( const float & floatValue )

Creates a DynamicStructure object from a float value that will represent the float.

Note: implicit conversion is desired in this case so we can do: object.AddMember("gearRatio", 2.13f);

◆ DynamicStructure() [4/9]

TurtleBrains::Core::DynamicStructure::DynamicStructure ( const bool & booleanValue )

Creates a DynamicStructure object from a boolean value that will represent the boolean.

Note: implicit conversion is desired in this case so we can do: object.AddMember("hasReverse", false);

◆ DynamicStructure() [5/9]

TurtleBrains::Core::DynamicStructure::DynamicStructure ( const String & stringValue )

Creates a DynamicStructure object from a string value that will contain and represent the string.

Note: implicit conversion is desired in this case so we can do: object.AddMember("modelName", stringValue);

◆ DynamicStructure() [6/9]

TurtleBrains::Core::DynamicStructure::DynamicStructure ( const char * stringValue )

Creates a DynamicStructure object from a string value that will contain and represent the string.

Note: implicit conversion is desired in this case so we can do: object.AddMember("modelName", "MX5");

◆ DynamicStructure() [7/9]

template<typename Type >

TurtleBrains::Core::DynamicStructure::DynamicStructure ( std::initializer_list< const Type > arguments )

inline

Creates a DynamicStructure array from a list of values so that initialization from within code can look/act very close to the json it resembles:

tbCore::DynamicStructure object = { { "names", { "TimBeaudet", "shakesoda", "tsjost" } }, { "numbers", { 42, 8, 35, 10 } }, };

Parameters

arguments The initializer list to initialize the array from.

◆ DynamicStructure() [8/9]

TurtleBrains::Core::DynamicStructure::DynamicStructure ( std::initializer_list< std::pair< const String, const DynamicStructure >> arguments )

Creates a DynamicStructure object from key-value pairs so that initialization from within code can look/act very close to the json it resembles:

tbCore::DynamicStructure object = { { "name", "TimBeaudet" }, { "fortyTwo", 42 }, { "pi", 3.14159f }, { "valid", true, } };

Parameters

arguments The initializer list to initialize the object from.

◆ DynamicStructure() [9/9]

TurtleBrains::Core::DynamicStructure::DynamicStructure ( const DynamicStructure & other )

noexcept

Creates a DynamicStruction object from an existing object. Because the objects can be quite large and complex, this could potentially use a fair bit of memory or copy overhead.

◆ ~DynamicStructure()

TurtleBrains::Core::DynamicStructure::~DynamicStructure ( void )

Cleans up after the DynamicStructure which for simple objects does not require any cleanup but for strings, arrays or structure objects can involve deleting any memory allocated during the lifespan of the structure, and any child structure as well.

Member Function Documentation

◆ AddMember()

DynamicStructure& TurtleBrains::Core::DynamicStructure::AddMember	(	const String &	memberName,
		const DynamicStructure &	memberValue
	)

Attempts to add a member with name and value to an object with type Structure or Nil. Any other types will cause an error condition to be triggered. If the type is Nil, the type will become Structure and the first member will be added. If a value already exists for the member an error condition will be triggered. A reference to the added value object will then be returned.

Parameters

memberName	The name of the member to be able to retrieve the value later. If a value with the memberName has already been added to the Structure an error condition will be triggered.
memberValue	The value of the member which will be retrieved by it's name.

◆ ArraySize()

size_t TurtleBrains::Core::DynamicStructure::ArraySize ( void ) const

Returns the number of values contained within an array type structure. If the type is NOT an array-type then 0 will be returned so a loop could be used on an Array type without checking that the array object was valid.

Note: To count the number of values in a structure, use StructureSize().

◆ AsArray() [1/2]

ArrayContainer& TurtleBrains::Core::DynamicStructure::AsArray ( void )

Returns the underlying structure type for the array object. This should only be used to iterate over the items in an array object.

for (const DynamicStructure& object : myArrayObject.AsArray() { ... }

Note: This is experimental, and may actually get removed in future versions of the API, but as long as it was used only for iteration, there is always BeginArray() / EndArray() to solve that requirement.

◆ AsArray() [2/2]

const ArrayContainer& TurtleBrains::Core::DynamicStructure::AsArray ( void ) const

Returns the underlying structure type for the array object. This should only be used to iterate over the items in an array object.

for (const DynamicStructure& object : myArrayObject.AsArray() { ... }

Note: This is experimental, and may actually get removed in future versions of the API, but as long as it was used only for iteration, there is always BeginArray() / EndArray() to solve that requirement.

◆ AsBoolean()

bool TurtleBrains::Core::DynamicStructure::AsBoolean ( bool implicitConversion = kImplicitConversions ) const

Gets the value of the object as a bool using implicit conversions if allowed, otherwise an error condition will be triggered if the Type is not a bool and implicitConversion is false.

Parameters

implicitConversion Set to true to allow other basic types (Integer, Float, String, Nil) to convert to an integer value automatically. If false, no conversion will be attempted and an error condition will be triggered.

◆ AsBooleanWithDefault()

bool TurtleBrains::Core::DynamicStructure::AsBooleanWithDefault	(	const bool	defaultValue,
		bool	implicitConversion = `true`
	)		const

First checks to make sure the type of the object is a boolean, then returns the value as a boolean without any conversions*. If the type is not a boolean the defaultValue will be returned.

Parameters

defaultValue	The boolean value to return if the type is not specifically a boolean, even if the type could be implicitly converted.
implicitConversion	Set to true to allow other basic types (Bool, Integer, Float) to convert to an integer value automatically, although a Nil value will return default. If false, no conversion will be attempted and the defaultValue will be returned.

Note: Current implementation does not allow any implicit conversions, but in the future this may change and it may become the default behavior of the WithDefault functions.

◆ AsFloat()

float TurtleBrains::Core::DynamicStructure::AsFloat ( bool implicitConversion = kImplicitConversions ) const

Gets the value of the object as a float using implicit conversions if allowed, otherwise an error condition will be triggered if the Type is not a float and implicitConversion is false.

Parameters

implicitConversion Set to true to allow other basic types (Bool, Integer, String, Nil) to convert to an integer value automatically. If false, no conversion will be attempted and an error condition will be triggered.

◆ AsFloatWithDefault()

float TurtleBrains::Core::DynamicStructure::AsFloatWithDefault	(	const float	defaultValue,
		bool	implicitConversion = `true`
	)		const

First checks to make sure the type of the object is a float, then returns the value as a float without any conversions*. If the type is not a float the defaultValue will be returned.

Parameters

defaultValue	The float value to return if the type is not specifically a float, even if the type could be implicitly converted.
implicitConversion	Set to true to allow other basic types (Bool, Integer, Float) to convert to an integer value automatically, although a Nil value will return default. If false, no conversion will be attempted and the defaultValue will be returned.

Note: Current implementation does not allow any implicit conversions, but in the future this may change and it may become the default behavior of the WithDefault functions.

◆ AsInteger()

tbCore::int64 TurtleBrains::Core::DynamicStructure::AsInteger ( bool implicitConversion = kImplicitConversions ) const

Gets the value of the object as an integer using implicit conversions if allowed, otherwise an error condition will be triggered if the Type is not an integer and implicitConversion is false.

Parameters

implicitConversion Set to true to allow other basic types (Bool, Float, String, Nil) to convert to an integer value automatically. If false, no conversion will be attempted and an error condition will be triggered.

◆ AsIntegerWithDefault()

tbCore::int64 TurtleBrains::Core::DynamicStructure::AsIntegerWithDefault	(	const tbCore::int64 &	defaultValue,
		bool	implicitConversion = `kImplicitConversions`
	)		const

First checks to make sure the type of the object is an integer, then returns the value as an integer without any conversions*. If the type is not an integer the defaultValue will be returned.

Parameters

defaultValue	The integer value to return if the type is not specifically an integer, even if the type could be implicitly converted.
implicitConversion	Set to true to allow other basic types (Bool, Integer, Float) to convert to an integer value automatically, although a Nil value will return default. If false, no conversion will be attempted and the defaultValue will be returned.

◆ AsRangedInteger()

template<typename Type >

Type TurtleBrains::Core::DynamicStructure::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

inline

First grabs the integer value by calling AsInteger, (using implicit conversion if allowed) then checks the range with minimum and maximum value parameters that default to min/max of the type, throwing the errorMessage if it fails to match range.

Parameters

errorMessage	The message to display if the values range is less than min or greater than max. An additional string will be added to the end showing the expected range.
minimumValue	This is the inclusive minimum value of the range. Passes when value is >= minimum. This will default to the minimum value supported by the Type as given by std::numeric_limits.
maximumValue	This is the inclusive maximum value of the range. Passes when value is <= maximum. This will default to the maximum value supported by the Type as given by std::numeric_limits.
implicitConversion	Set to true to allow other basic types (Bool, Float, String, Nil) to convert to an integer value automatically. If false, no conversion will be attempted and an error condition will be triggered.

Note: This will throw an error with errorMessage if the value is not within the range. minimum <= value <= maximum

◆ AsRangedIntegerWithDefault()

template<typename Type >

Type TurtleBrains::Core::DynamicStructure::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

inline

Grabs the integer value if possible, or returns the default. Then checks the range with minimum and maximum value parameters that default to min/max of the type, throwing the errorMessage if the value of the integer falls out of the given range.

Parameters

defaultValue	The integer value to return if the type is not specifically an integer, even if the type could be implicitly converted.
errorMessage	The message to display if the values range is less than min or greater than max. An additional string will be added to the end showing the expected range.
minimumValue	This is the inclusive minimum value of the range. Passes when value is >= minimum. This will default to the minimum value supported by the Type as given by std::numeric_limits.
maximumValue	This is the inclusive maximum value of the range. Passes when value is <= maximum. This will default to the maximum value supported by the Type as given by std::numeric_limits.
implicitConversion	Set to true to allow other basic types (Bool, Integer, String, Nil) to convert to an integer value automatically. If false, no conversion will be attempted and an error condition will be triggered.

Note: This will throw an error with errorMessage if the value is not within the range. minimum <= value <= maximum; As of 2025-11-09 this function swapped order of defaultValue and errorMessage. There was a SECOND version of AsRangedIntegerWithDefault(errorMessage, defaultValue) that had previously existed and was removed. It was acting SLIGHTLY differently in how it approached grabbing the value then erroring if out of range. If necessary check this commit or before it to find old version; b68bc4e08c4f3326bd041e5f0385cd524d7069d2

◆ AsString()

String TurtleBrains::Core::DynamicStructure::AsString ( bool implicitConversion = kImplicitConversions ) const

Gets the value of the object as a string using implicit conversions if allowed, otherwise an error condition will be triggered if the Type is not a string and implicitConversion is false.

Parameters

implicitConversion Set to true to allow other basic types (Bool, Integer, Float, Nil) to convert to an integer value automatically. If false, no conversion will be attempted and an error condition will be triggered.

◆ AsStringWithDefault()

String TurtleBrains::Core::DynamicStructure::AsStringWithDefault	(	const String &	defaultValue,
		bool	implicitConversion = `true`
	)		const

First checks to make sure the type of the object is a string, then returns the value as a string without any conversions*. If the type is not a string the defaultValue will be returned.

Parameters

defaultValue	The string value to return if the type is not specifically a string, even if the type could be implicitly converted.
implicitConversion	Set to true to allow other basic types (Bool, Integer, Float) to convert to an integer value automatically, although a Nil value will return default. If false, no conversion will be attempted and the defaultValue will be returned.

Note: Current implementation does not allow any implicit conversions, but in the future this may change and it may become the default behavior of the WithDefault functions.

◆ AsStructure() [1/2]

StructureContainer& TurtleBrains::Core::DynamicStructure::AsStructure ( void )

Returns the underlying structure type for the structure object. This should only be used to iterate over the items in a structure object, for saving or exporting etc.

for (const DynamicStructure& keyValue : myStructureObject.AsStructure() { const String& keyName = keyValue.first; const tbCore::DynamicStructure& value = keyValue.second; ... }

Note: This is experimental, and may actually get removed in future versions of the API, but as long as it was used only for iteration, there is always BeginArray() / EndArray() to solve that requirement.; If the object is NOT a structure, the reference to an empty structure container is returned.

◆ AsStructure() [2/2]

const StructureContainer& TurtleBrains::Core::DynamicStructure::AsStructure ( void ) const

Returns the underlying structure type for the structure object. This should only be used to iterate over the items in a structure object, for saving or exporting etc.

for (const DynamicStructure& keyValue : myStructureObject.AsStructure() { const String& keyName = keyValue.first; const tbCore::DynamicStructure& value = keyValue.second; ... }

Note: This is experimental, and may actually get removed in future versions of the API, but as long as it was used only for iteration, there is always BeginArray() / EndArray() to solve that requirement.; If the object is NOT a structure, the reference to an empty structure container is returned.

◆ begin() [1/2]

ArrayContainer::iterator TurtleBrains::Core::DynamicStructure::begin ( void )

Returns an array iterator at the start of the container. To be used to iterate over each member in the array.

Note: This will trigger an error condition if the dynamic structure is not an Array.

◆ begin() [2/2]

ArrayContainer::const_iterator TurtleBrains::Core::DynamicStructure::begin ( void ) const

Returns an array iterator at the start of the container. To be used to iterate over each member in the array.

Note: This will trigger an error condition if the dynamic structure is not an Array.

◆ BeginArray() [1/2]

ArrayContainer::iterator TurtleBrains::Core::DynamicStructure::BeginArray ( void )

Returns an array iterator at the start of the container. To be used to iterate over each member in the array.

Note: This will trigger an error condition if the dynamic structure is not an Array.

◆ BeginArray() [2/2]

ArrayContainer::const_iterator TurtleBrains::Core::DynamicStructure::BeginArray ( void ) const

Returns an array iterator at the start of the container. To be used to iterate over each member in the array.

Note: This will trigger an error condition if the dynamic structure is not an Array.

◆ BeginStructure() [1/2]

StructureContainer::iterator TurtleBrains::Core::DynamicStructure::BeginStructure ( void )

Returns a structure iterator at the start of the container for a Structure value. To be used to iterate over each member in the structure, typically for saving/exporting the dynamic structure.

◆ BeginStructure() [2/2]

StructureContainer::const_iterator TurtleBrains::Core::DynamicStructure::BeginStructure ( void ) const

Returns a structure iterator at the start of the container for a Structure value. To be used to iterate over each member in the structure, typically for saving/exporting the dynamic structure.

◆ end() [1/2]

ArrayContainer::iterator TurtleBrains::Core::DynamicStructure::end ( void )

Returns an array iterator at the end of the container. To be used to iterate over each member in the array.

Note: This will trigger an error condition if the dynamic structure is not an Array.

◆ end() [2/2]

ArrayContainer::const_iterator TurtleBrains::Core::DynamicStructure::end ( void ) const

Returns an array iterator at the end of the container. To be used to iterate over each member in the array.

Note: This will trigger an error condition if the dynamic structure is not an Array.

◆ EndArray() [1/2]

ArrayContainer::iterator TurtleBrains::Core::DynamicStructure::EndArray ( void )

Returns an array iterator at the end of the container. To be used to iterate over each member in the array.

Note: This will trigger an error condition if the dynamic structure is not an Array.

◆ EndArray() [2/2]

ArrayContainer::const_iterator TurtleBrains::Core::DynamicStructure::EndArray ( void ) const

Returns an array iterator at the end of the container. To be used to iterate over each member in the array.

Note: This will trigger an error condition if the dynamic structure is not an Array.

◆ EndStructure() [1/2]

StructureContainer::iterator TurtleBrains::Core::DynamicStructure::EndStructure ( void )

Returns a structure iterator representing the end of the container for a Structure value. To be used to iterate over each member in the structure.

◆ EndStructure() [2/2]

StructureContainer::const_iterator TurtleBrains::Core::DynamicStructure::EndStructure ( void ) const

Returns a structure iterator representing the end of the container for a Structure value. To be used to iterate over each member in the structure.

◆ GetMember() [1/2]

DynamicStructure& TurtleBrains::Core::DynamicStructure::GetMember ( const String & memberName )

Attempts to retrieve a DynamicStructure object for the memberName given, if this object is of type Nil then a Nil object will be returned,* but if this object is a Structure the member will be searched for and returned if found otherwise if not found a Nil object will be returned.*

Parameters

memberName The name of the member as it was added during AddMember.

@history 2025-11-15: Before today GetMember() would return a const Nil object when the DynamicStructure was not a StructureType or if it did not contain the member. The non-const version of this did so by adding a member, setting it to Nil and returning that as the reference. GetMember() would only previously trigger an error condition if the DynamicStructure was not Nil and not a StructureType.

Going forward GetMember() will default to triggering an error condition if the memberName requested could not be found for any reason, whether the DynamicStructure is Nil, not a StructureType or simply does not contain the requested memberName. This is akin to std::map::at().

If GetMember() is throwing an error condition where it didn't prior to v0.4.4 then you may want to use the operator[] to get the member. This will return Null if a member is not found, and if your DynamicStructure is a non-const that returned reference is to a member that was just added. Similar to std::map::operator[] except the const version doesn't crash; which maybe it should to prevent the change from const/non-const in the code suddenly adding members.

◆ GetMember() [2/2]

const DynamicStructure& TurtleBrains::Core::DynamicStructure::GetMember ( const String & memberName ) const

Attempts to retrieve a DynamicStructure object for the memberName given, if this object is of type Nil then a Nil object will be returned,* but if this object is a Structure the member will be searched for and returned if found otherwise if not found a Nil object will be returned.*

Parameters

memberName The name of the member as it was added during AddMember.

@history 2025-11-15: Before today GetMember() would return a const Nil object when the DynamicStructure was not a StructureType or if it did not contain the member. The non-const version of this did so by adding a member, setting it to Nil and returning that as the reference. GetMember() would only previously trigger an error condition if the DynamicStructure was not Nil and not a StructureType.

Going forward GetMember() will default to triggering an error condition if the memberName requested could not be found for any reason, whether the DynamicStructure is Nil, not a StructureType or simply does not contain the requested memberName. This is akin to std::map::at().

If GetMember() is throwing an error condition where it didn't prior to v0.4.4 then you may want to use the operator[] to get the member. This will return Null if a member is not found, and if your DynamicStructure is a non-const that returned reference is to a member that was just added. Similar to std::map::operator[] except the const version doesn't crash; which maybe it should to prevent the change from const/non-const in the code suddenly adding members.

◆ GetValue() [1/2]

DynamicStructure& TurtleBrains::Core::DynamicStructure::GetValue ( const tbCore::uint64 & arrayIndex )

Returns a reference to the value in the array at the specified index. If this object is not an Array type an error condition will be triggered.

Parameters

arrayIndex is the index of the desired element. Must be within the range: 0 <= arrayIndex <= size() or an error condition will be triggered for going out of range.

Note: This can only be called on DynamicStructures with the Array type, any other type, including Nil will cause an error condition to be triggered.

◆ GetValue() [2/2]

const DynamicStructure& TurtleBrains::Core::DynamicStructure::GetValue ( const tbCore::uint64 & arrayIndex ) const

Returns a const reference to the value in the array at the specified index. If this object is not an Array type an error condition will be triggered.

Parameters

arrayIndex is the index of the desired element. Must be within the range: 0 <= arrayIndex <= size() or an error condition will be triggered for going out of range.

Note: This can only be called on DynamicStructures with the Array type, any other type, including Nil will cause an error condition to be triggered.

◆ HasMember()

bool TurtleBrains::Core::DynamicStructure::HasMember ( const String & memberName ) const

Checks if a DynamicStructure object has an entry, Nil or otherwise, for a given memberName. This will not add a Nil object if it does exist, like GetMember() would.

Parameters

memberName The name of the member as it was added during AddMember.

◆ IsArray()

bool TurtleBrains::Core::DynamicStructure::IsArray ( void ) const

Checks to see if the object is holding an array returning true if it is, otherwise false.

◆ IsBoolean()

bool TurtleBrains::Core::DynamicStructure::IsBoolean ( void ) const

Checks to see if the object is holding an boolean type returning true if it is.

◆ IsFloat()

bool TurtleBrains::Core::DynamicStructure::IsFloat ( void ) const

Checks to see if the object is holding an float type returning true if it is.

◆ IsInteger()

bool TurtleBrains::Core::DynamicStructure::IsInteger ( void ) const

Checks to see if the object is holding an integer type returning true if it is.

◆ IsNil()

bool TurtleBrains::Core::DynamicStructure::IsNil ( void ) const

Checks to see if the dynamic structure is a Nil object, representing no data, empty/clean, and returns the result, true if the object is Nil otherwise false.

Note: This may be renamed to IsNull().

◆ IsString()

bool TurtleBrains::Core::DynamicStructure::IsString ( void ) const

Checks to see if the object is holding an string type returning true if it is.

◆ IsStructure()

bool TurtleBrains::Core::DynamicStructure::IsStructure ( void ) const

Checks to see if the object is a structure type which could hold multiple other objects within returning true if it is a structure type, otherwise false.

◆ operator bool()

TurtleBrains::Core::DynamicStructure::operator bool ( ) const

inlineexplicit

This operator will cast a DynamicStructure object into a bool with implicit conversion allowed.

◆ operator float()

TurtleBrains::Core::DynamicStructure::operator float ( ) const

inlineexplicit

This operator will cast a DynamicStructure object into a float with implicit conversion allowed.

◆ operator String()

TurtleBrains::Core::DynamicStructure::operator String ( ) const

inlineexplicit

This operator will cast a DynamicStructure object into a string with implicit conversion allowed.

◆ operator tbCore::int64()

TurtleBrains::Core::DynamicStructure::operator tbCore::int64 ( ) const

inlineexplicit

This operator will cast a DynamicStructure object into an integer with implicit conversion allowed.

◆ operator!=()

bool TurtleBrains::Core::DynamicStructure::operator!= ( const DynamicStructure & rightSide ) const

Checks two DynamicStructures for non-equality. This can only check the basic types (Nil, Integer, Float, Boolean and String) for equality with another of the same type. Checking for inequality with an Array or Structure type will result in an error condition being triggered.

Note: Checking for inequality of an Array or Structure type will trigger an error condition.

◆ operator=()

DynamicStructure& TurtleBrains::Core::DynamicStructure::operator= ( const DynamicStructure & other )

noexcept

Cleans up the current object then assigns itself to an existing object. Because the objects can be quite large and complex, this could potentially use a fair bit of memory or copy overhead.

◆ operator==()

bool TurtleBrains::Core::DynamicStructure::operator== ( const DynamicStructure & rightSide ) const

Checks two DynamicStructures for equality. This can only check the basic types (Nil, Integer, Float, Boolean and String) for equality with another of the same type. Checking for equality with an Array or Structure type will result in an error condition being triggered.

Note: Checking for equality of an Array or Structure type will trigger an error condition.

◆ operator[]() [1/2]

template<typename Type >

DynamicStructure& TurtleBrains::Core::DynamicStructure::operator[] ( const Type & nameOrIndex )

inline

◆ operator[]() [2/2]

template<typename Type >

const DynamicStructure& TurtleBrains::Core::DynamicStructure::operator[] ( const Type & nameOrIndex ) const

inline

@history 2025-11-15: For a StructureType objects operator[] will add the member when it does not already contain it, unless the DynamicStructure object is const. That will return null or potentially just trigger an error. Today it returns null, but there is reason to believe it may trigger errors to match operator[] of a std::map a little more closely.

◆ PushValue()

DynamicStructure& TurtleBrains::Core::DynamicStructure::PushValue ( const DynamicStructure & value )

Attempts to push the value onto the back of a standard vector if this object is either a Nil type or an Array type. If the type is not Nil or an Array an error condition will be triggered.

Parameters

value The value to push into the array of values, it can be of any type.

Note: This can only be called on DynamicStructures with the Nil type or Array type, any other type will cause an error condition to be triggered.

◆ RemoveMember()

void TurtleBrains::Core::DynamicStructure::RemoveMember ( const String & memberName )

Attempts to remove a member from a Structure typed DynamicStructure. An error condition will be triggered if the object is not a Structure or Nil. If the member does not exist, or this is a Nil object, nothing will happen.

Parameters

memberName The name of the member to delete from the Structure.

◆ SetMember()

DynamicStructure& TurtleBrains::Core::DynamicStructure::SetMember	(	const String &	memberName,
		const DynamicStructure &	memberValue
	)

Sets the value of an existing structure member, or adds the member if it did not exists, to an object with type Structure or Nil. Any other types will cause an error condition to be triggered. If the type is Nil, the object/type will become a Structure and the member will be added. If a value already exists for the member, it will be set to the new value. A reference to the object will then be returned.

Parameters

memberName	The name of the member to be able to retrieve the value later. If a value with the memberName has already been added to the Structure an error condition will be triggered.
memberValue	The value of the member which will be retrieved by it's name.

◆ SetValue() [1/4]

void TurtleBrains::Core::DynamicStructure::SetValue	(	const bool &	booleanValue,
		bool	implicitTypeChange = `kImplicitTypeChange`
	)

Attempts to change the value of the object to the value specified, if the object Type is a boolean, Nil or implicityTypeChange is allowed this will succeed, otherwise an error condition will be triggered. The object type will become a float type during this process.

Parameters

booleanValue	The value for the object to hold as a boolean type.
implicitTypeChange	Set to true the value and type will always be set properly, however if false, and the object is not already a boolean or Nil type this will cause an error condition to trigger.

◆ SetValue() [2/4]

void TurtleBrains::Core::DynamicStructure::SetValue	(	const float &	floatValue,
		bool	implicitTypeChange = `kImplicitTypeChange`
	)

Attempts to change the value of the object to the value specified, if the object Type is a float, Nil or implicityTypeChange is allowed this will succeed, otherwise an error condition will be triggered. The object type will become a float type during this process.

Parameters

floatValue	The value for the object to hold as a float type.
implicitTypeChange	Set to true the value and type will always be set properly, however if false, and the object is not already a float or Nil type this will cause an error condition to trigger.

◆ SetValue() [3/4]

void TurtleBrains::Core::DynamicStructure::SetValue	(	const int &	integerValue,
		bool	implicitTypeChange = `kImplicitTypeChange`
	)

Attempts to change the value of the object to the value specified, if the object Type is an integer, Nil or implicityTypeChange is allowed this will succeed, otherwise an error condition will be triggered. The object type will become an integer type during this process.

Parameters

integerValue	The value for the object to hold as an integer type.
implicitTypeChange	Set to true the value and type will always be set properly, however if false, and the object is not already an integer or Nil type this will cause an error condition to trigger.

◆ SetValue() [4/4]

void TurtleBrains::Core::DynamicStructure::SetValue	(	const String &	stringValue,
		bool	implicitTypeChange = `kImplicitTypeChange`
	)

Attempts to change the value of the object to the value specified, if the object Type is a string, Nil or implicityTypeChange is allowed this will succeed, otherwise an error condition will be triggered. The object type will become a string type during this process.

Parameters

stringValue	The value for the object to hold as a string type.
implicitTypeChange	Set to true the value and type will always be set properly, however if false, and the object is not already a string or Nil type this will cause an error condition to trigger.

◆ size()

size_t TurtleBrains::Core::DynamicStructure::size ( void ) const

Returns the number of values contained with an array type structure or the number of values within an object like structure. Returns 0 for any other type.

◆ StructureSize()

size_t TurtleBrains::Core::DynamicStructure::StructureSize ( void ) const

Returns the number of values contained within an structure type structure. If the type is NOT an structure-type then 0 will be returned without triggering an error condition.

Member Data Documentation

◆ kFalseAsString

const String TurtleBrains::Core::DynamicStructure::kFalseAsString

static

The value returned when a false boolean is converted to a string.

◆ kFloatElipson

const float TurtleBrains::Core::DynamicStructure::kFloatElipson

static

Consider two floating point values equal if the difference is less than epsilon.

◆ kImplicitConversions

const bool TurtleBrains::Core::DynamicStructure::kImplicitConversions

static

Changes the behavior of the DynamicStructure's AsType functions.

◆ kImplicitTypeChange

const bool TurtleBrains::Core::DynamicStructure::kImplicitTypeChange

static

Allows the DynamicStructure to change type on the fly.

◆ kInvalidSize

const unsigned int TurtleBrains::Core::DynamicStructure::kInvalidSize

static

The value returned when size() is called with an invalid type, likely to be 0.

◆ kNullAsString

const String TurtleBrains::Core::DynamicStructure::kNullAsString

static

The value returned when a null structure is converted to a string.

◆ kNullValue

const DynamicStructure TurtleBrains::Core::DynamicStructure::kNullValue

static

The value returned to represent a const-reference to null.

◆ kTrueAsString

const String TurtleBrains::Core::DynamicStructure::kTrueAsString

static

The value returned when a true boolean is converted to a string.

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ ArrayContainer

◆ StructureContainer

Constructor & Destructor Documentation

◆ DynamicStructure() [1/9]

◆ DynamicStructure() [2/9]

◆ DynamicStructure() [3/9]

◆ DynamicStructure() [4/9]

◆ DynamicStructure() [5/9]

◆ DynamicStructure() [6/9]

◆ DynamicStructure() [7/9]

◆ DynamicStructure() [8/9]

◆ DynamicStructure() [9/9]

◆ ~DynamicStructure()

Member Function Documentation

◆ AddMember()

◆ ArraySize()

◆ AsArray() [1/2]

◆ AsArray() [2/2]

◆ AsBoolean()

◆ AsBooleanWithDefault()

◆ AsFloat()

◆ AsFloatWithDefault()

◆ AsInteger()

◆ AsIntegerWithDefault()

◆ AsRangedInteger()

◆ AsRangedIntegerWithDefault()

◆ AsString()

◆ AsStringWithDefault()

◆ AsStructure() [1/2]

◆ AsStructure() [2/2]

◆ begin() [1/2]

◆ begin() [2/2]

◆ BeginArray() [1/2]

◆ BeginArray() [2/2]

◆ BeginStructure() [1/2]

◆ BeginStructure() [2/2]

◆ end() [1/2]

◆ end() [2/2]

◆ EndArray() [1/2]

◆ EndArray() [2/2]

◆ EndStructure() [1/2]

◆ EndStructure() [2/2]

◆ GetMember() [1/2]

◆ GetMember() [2/2]

◆ GetValue() [1/2]

◆ GetValue() [2/2]

◆ HasMember()

◆ IsArray()

◆ IsBoolean()

◆ IsFloat()

◆ IsInteger()

◆ IsNil()

◆ IsString()

◆ IsStructure()

◆ operator bool()

◆ operator float()

◆ operator String()

◆ operator tbCore::int64()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ PushValue()

◆ RemoveMember()

◆ SetMember()

◆ SetValue() [1/4]

◆ SetValue() [2/4]

◆ SetValue() [3/4]

◆ SetValue() [4/4]

◆ size()

◆ StructureSize()

Member Data Documentation