#include <adskDataStructure.h>

Class Description

Class handling the definition of the structure of a piece of data.

The adsk::Data::Handle class manages the handling of a single piece of structured data. adsk::Data::Structure class is responsible for defining and managing what the structure of that data looks like. It includes the naming of the structure members as well as maintaining the metadata necessary to efficiently store the collection of data values.

Examples:: MetadataSample/createMetadataCmd.cpp, MetadataSample/createMetadataCmd.h, MetadataXML/streamSerializerXML.cpp, MetadataXML/structureSerializerXML.h, and sceneAssembly/adskSceneMetadataCmd.cpp.

Inheritance diagram for Structure:

Public Member Functions
	Structure ()
	Default constructor, initialize to defaults.

	Structure (const char *name)
	Constructor with structure name, initialize to defaults.

	Structure (const Structure &rhs)
	Copy constructor, copy values from an existing structure. More...

Structure &	operator= (const Structure &rhs)
	Assignment operator, copy a structure's data over to this one. More...

bool	operator== (const Structure &rhs) const
	Compare two structures for equality. More...

bool	operator!= (const Structure &rhs) const
	Compare two structures for inequality. More...

bool	addMember (Member::eDataType, unsigned int len, const char *name)
	Add a new member to the structure. More...

size_t	totalSize () const
	Return the amount of memory a packed structure will occupy. More...

const char *	defaultData () const
	Return a chunk of memory containing default values for the structure. More...

char *	allocateDefaultChunk () const
	Return an allocated chunk of memory containing default values for the structure. More...

char *	duplicateChunk (const char *dataPtr) const
	Duplicate a data chunk, including all embedded values. More...

bool	fillWithDefaultChunk (char *dataPtr) const
	Copy the default structure values into a block of memory. More...

bool	fillWithDuplicateChunk (char newData, const char oldData) const
	Copy the passed in structure values into a block of memory. More...

bool	destroyChunk (char *dataPtr) const
	Destroy a data chunk, including any members with their own destructors. More...

bool	chunkIsDefault (const char *dataPtr) const
	Check to see if the data chunk contains all default values. More...

bool	chunkMemberIsDefault (const char dataPtr, const char memberName) const
	Check to see if a single member in the data chunk contains default values. More...

const char *	name () const
	Get the name of the structure. More...

void	setName (const char *)
	Set a new name for the structure. More...

Structure::iterator	begin () const
	Get an iterator pointed to the beginning of the Structure. More...

Structure::iterator	end () const
	Get an iterator positioned off the end of the Members. More...

Structure::const_iterator	cbegin () const
	Get a const Member iterator pointed to the beginning of the Structure. More...

Structure::const_iterator	cend () const
	Get a read-only iterator positioned off the end of the Members. More...

unsigned int	size () const
	Get the number of Members in the Structure. More...

bool	empty () const
	Check to see if the Structure has no Members. More...

unsigned int	memberCount () const
	Get the number of Members in the Structure. More...

Public Member Functions inherited from Checkpointed
Checkpoint	checkpoint () const
	Retrieve the current object checkpoint state. More...

bool	changedSinceCheckpoint (const Checkpoint &check) const
	Determine if the object has been altered since the given checkpoint. More...

	Checkpointed ()
	Default constructor - initialize counter.

virtual	~Checkpointed ()
	Destructor, updates checkpoint count for the class.

	Checkpointed (const Checkpointed &rhs)
	Copy constructor - counter starts where copy left off. More...

Checkpointed &	operator= (const Checkpointed &rhs)
	Assignment operator and copy constructor are just to allow objects with counters embedded or derived to copy properly. More...

Static Public Member Functions
static Structure *	create ()
	Structure creator. More...

static bool	registerStructure (Structure &newStruct)
	Register a new structure in the global list. More...

static bool	deregisterStructure (Structure &oldStruct)
	Remove a structure from the global list. More...

static Structure *	structureByName (const char *)
	Lookup a created structure by name. More...

static void	deleteAllStructures ()
	Remove every structure. More...

static List &	allStructures ()
	Global list of all defined structures.

static bool	Debug (const Structure *me, Debug::Print &request)
	Answer a Print request for a Structure object. More...

static bool	Debug (const Structure *me, Debug::Footprint &request)
	Answer a footprint request for a Structure object. More...

Static Public Member Functions inherited from RefCounted
static bool	Debug (const RefCounted *me, Debug::Print &request)
	Answer a Print request for a RefCounted object. More...

static bool	Debug (const RefCounted *me, Debug::Footprint &request)
	Answer a footprint request for a RefCounted object. More...

Static Public Member Functions inherited from Checkpointed
static Checkpoint	globalCheckpoint ()
	Retrieve the global checkpoint. More...

static Checkpoint	globalChange ()
	Update the global checkpoint and return the new value. More...

static bool	Debug (const Checkpointed *me, Debug::Print &request)
	Answer a Print request for a Checkpointed object. More...

static bool	Debug (const Checkpointed *me, Debug::Footprint &request)
	Answer a footprint request for an Checkpointed object. More...

Protected Member Functions
	~Structure ()
	Default destructor, remove the default data if it exists.

Protected Member Functions inherited from RefCounted
	RefCounted ()
	RefCounted default ctor.

	RefCounted (const RefCounted &)
	RefCounted copy ctor.

virtual	~RefCounted ()
	RefCounted dtor.

Protected Member Functions inherited from Checkpointed
Checkpoint	objectChanged ()
	Call this whenever an object changes, increments the class and object checkpoint counters. More...

Protected Attributes
char *	fDefault
	Allocated array of structure members.

char *	fName
	Memory block containing a default structure value.

size_t	fSize
	Name of this structure.

unsigned int	fMemberCount
	Total size of all structure members, including padding.

bool	fDeleting
	Number of members in fMemberList.

Protected Attributes inherited from Checkpointed
Checkpoint	fCheckpoint
	ID updating when the object changes.

Additional Inherited Members
Static Protected Attributes inherited from Checkpointed
static Checkpoint	sfGlobalCheckpoint = 0
	Global monotonic checkpoint. More...

Constructor & Destructor Documentation

Structure ( const Structure & rhs )

Copy constructor, copy values from an existing structure.

Parameters

[in] rhs Structure to copy

Member Function Documentation

Structure & operator= ( const Structure & rhs )

Assignment operator, copy a structure's data over to this one.

Allocates new copies of the member array and default data. Does not copy reference counts as all underlying references to this Structure and the copied Structure will remain intact and independent.

Parameters

[in] rhs Structure to copy

Returns: reference to the new copy (this)

bool operator== ( const Structure & rhs ) const

Compare two structures for equality.

The structures are deemed equal if they refer to the same object or if every member of the class matches. (Ordering is important as well since it determines storage layout.)

Parameters

[in] rhs Structure to compare against

Returns: true if the structures are the same

bool operator!= ( const Structure & rhs ) const

Compare two structures for inequality.

Not an optimal implementation but is expected to be less common and avoids code duplication.

Parameters

[in] rhs Structure to compare against

Returns: true if the structures are not the same

Structure * create ( )

static

Structure creator.

Used to force allocation of the Structure data into the main heap so that it controls deletion (which it must since the Structure is reference-counted).

NOTE: After creation you *must* either call registerStructure() to make it visible or call ref() to maintain a local copy of it. Otherwise it can be deleted at any point since it is reference counted. This includes any calls to the Structure class itself or iteration on the Structure members.

Returns: Pointer to the newly created Structure

bool addMember	(	Member::eDataType	type,
		unsigned int	length,
		const char *	name
	)

Add a new member to the structure.

The order in which the members are added is not necessarily related to the order in which they appear in the iterator. Like a C structure though the members will be stored in the order received (to avoid the overhead of rearranging existing data chunks) so in order to maximize storage efficiency you should add items in order of size from largest to smallest.

If there is no data which uses the old structure yet you can also call the optimize() method after the last item is added. It's up to the caller to verify that this is the case.

Parameters

[in]	type	Type of data to be added
[in]	length	Number of elements per member
[in]	name	Name of this new piece of data

Returns: true if the member was added, false if not Member name must be non-zero length and unique. Member length must be 1 or higher. Member type cannot be invalid.

Examples:: sceneAssembly/adskSceneMetadataCmd.cpp.

size_t totalSize ( ) const

Return the amount of memory a packed structure will occupy.

This is used in order to allocate enough memory to hold all of the data in a defined structure. Use the individual structure member offsets and sizes (e.g. via the iterator) to find out how the members are laid out in memory.

Returns: the size in bytes of a packed structure

const char * defaultData ( ) const

Return a chunk of memory containing default values for the structure.

The structure data has a very specific layout determined by the structure itself so the most efficient way to define a set of default values for a structure is to provide a memory block filled with those defaults.

Note that the default data does not own anything. If a (char*) pointing to a string appears it is assumed that string is managed elsewhere and will not be deleted while the default data exists.

The memory block is owned by the structure and cannot be modified directly. Use the block and totalSize() result to copy it if desired.

Returns: a pointer to the default structure block, NULL if it has no members

char * allocateDefaultChunk ( ) const

Return an allocated chunk of memory containing default values for the structure.

The difference between this method and defaultData() is that this one transfers ownership of the memory to the caller whereas defaultData() offers only const access to a pre-allocated piece of memory.

The caller should use delete [] to release the memory once they are done using it.

Returns: a pointer to the allocated block, NULL if it has no members

char * duplicateChunk ( const char * dataPtr ) const

Duplicate a data chunk, including all embedded values.

Mostly this routine just does a bit copy from the old data chunk to the new one, under the assumption that the sizes are the same and the new one has no data requiring cleanup.

The second step is to do a deep copy on any member types requiring it for uniqueness, e.g. strings.

Parameters

[in] dataPtr a pointer to a block of data to be duplicated

Returns: An allocated duplicate of the passed-in data

bool fillWithDefaultChunk ( char * dataPtr ) const

Copy the default structure values into a block of memory.

The memory pointer passed in should be big enough to hold the structure values, i.e. totalSize() bytes

The memory pointer passed in should not have any data in need of destruction (e.g. don't call this method twice, it may leave dangling data pointers for things like strings)

Parameters

[out] dataPtr a pointer to a block of data to be filled with defaults

Returns: true if the default data was copied to the dataPtr

bool fillWithDuplicateChunk	(	char *	newData,
		const char *	oldData
	)		const

Copy the passed in structure values into a block of memory.

Presumes that the allocated size of newData and oldData are the same.

Since some data requires construction this method copies the oldData onto the new data and then walks each structure member, manually constructing any member requiring construction using the oldData values for a copy constructor or equivalent.

Parameters

[out]	newData	a pointer to a block of data to be filled with values
[in]	oldData	a pointer to a block of data to be duplicated

Returns: true if the data was duplicated into the newData location

bool destroyChunk ( char * dataPtr ) const

Destroy a data chunk, including any members with their own destructors.

A data chunk stores all of the data values from one instance of a structure.

Parameters

[in] dataPtr a pointer to a block of data to be destroyed

Returns: True if the destruction succeeded

bool chunkIsDefault ( const char * dataPtr ) const

Check to see if the data chunk contains all default values.

Parameters

[in] dataPtr a pointer to a block of data corresponding to this Handle

Returns: True if the block of data contained default values

bool chunkMemberIsDefault	(	const char *	dataPtr,
		const char *	memberName
	)		const

Check to see if a single member in the data chunk contains default values.

Parameters

[in]	dataPtr	a pointer to a block of data corresponding to this Handle
[in]	memberName	The name of the member to check. If NULL check all of them

Returns: True if the block of data contained default values

const char * name ( ) const

Get the name of the structure.

Returns: Pointer to the string containing the structure name

Examples:: MetadataXML/streamSerializerXML.cpp.

void setName ( const char * name )

Set a new name for the structure.

The name string is copied internally so the caller is still responsible for deleting the original.

Parameters

[in] name New name to be set

Examples:: sceneAssembly/adskSceneMetadataCmd.cpp.

Structure::iterator begin ( ) const

Get an iterator pointed to the beginning of the Structure.

Returns: An iterator pointing at the first Member of the Structure

Examples:: MetadataXML/streamSerializerXML.cpp.

Structure::iterator end ( ) const

Get an iterator positioned off the end of the Members.

Returns: An iterator pointed off the end of the iteration

Examples:: MetadataXML/streamSerializerXML.cpp.

Structure::const_iterator cbegin ( ) const

Get a const Member iterator pointed to the beginning of the Structure.

Returns: A read-only iterator pointing at the first element of the Structure

Structure::const_iterator cend ( ) const

Get a read-only iterator positioned off the end of the Members.

Returns: A read-only iterator pointed off the end of the iteration

unsigned int size ( ) const

Get the number of Members in the Structure.

Returns: Number of Members in the Structure

bool empty ( ) const

Check to see if the Structure has no Members.

Returns: true if the Structure has no Members, else false

bool registerStructure ( Structure & newStruct )

static

Register a new structure in the global list.

All structures are maintained in a global list. The registration and deregistration happens when the structures become visible. External undo capabilities may allow structures to exist without becoming visible so verify that the newStruct doesn't already exist on the registration list before adding it.

Parameters

[in] newStruct New structure to be added to the list

Returns: false if the structure was already registered, otherwise true

bool deregisterStructure ( Structure & oldStruct )

static

Remove a structure from the global list.

External undo handling may create a situation where structures exist but are not registered. Check the presence of the oldStruct in the registration list first to confirm that the calling code has properly matched register/deregister calls.

Parameters

[in] oldStruct Structure to be removed from the list

Returns: true if the structure was found and deregistered

Structure * structureByName ( const char * name )

static

Lookup a created structure by name.

Parameters

[in] name Name of structure to find

Returns: Structure with the given name, NULL if there is none

Examples:: MetadataSample/createMetadataCmd.cpp, and MetadataXML/streamSerializerXML.cpp.

void deleteAllStructures ( )

static

Remove every structure.

This is possible without using this method but it's a bit messy to ensure you don't delete structures out from under yourself so it's packaged up nicely here.

unsigned int memberCount ( ) const

Get the number of Members in the Structure.

Returns: Number of Members in the Structure

bool Debug	(	const Structure *	me,
		Debug::Print &	request
	)

static

Answer a Print request for a Structure object.

Use the request object to dump all information on the "me" Structure, or all static Structure information if "me" is NULL.

Parameters

[in]	me	Pointer to object to debug, NULL means class static
[out]	request	Print request object

Returns: True if the request was successfully processed.

bool Debug	(	const Structure *	me,
		Debug::Footprint &	request
	)

static

Answer a footprint request for a Structure object.

Populate the Footprint request with the information on all data stored within this class if "me" is NULL, otherwise the information stored in the Structure object pointed at by "me".

Parameters

[in]	me	Pointer to object to footprint, NULL means class static
[out]	request	Footprint object to populate

Returns: True if the request was successfully processed. The Footprint object will have all information added to it.

The documentation for this class was generated from the following files:

adskDataStructure.h
adskDataStructure.cpp

Structure Class Reference

Class Description

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Constructor & Destructor Documentation

Member Function Documentation