- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Examples

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes

# Structure Class Reference

This reference page is linked to from the following overview topics: Autodesk Maya 2014, Meta Data.

Search for all occurrences

## Detailed 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.

`#include <adskDataStructure.h>`

Inheritance diagram for Structure:
[legend]

List of all members.

## 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.
Structure & | operator= (const Structure &rhs)
| Assignment operator, copy a structure's data over to this one.
bool | operator== (const Structure &rhs) const
| Compare two structures for equality.
bool | operator!= (const Structure &rhs) const
| Compare two structures for inequality.
bool | addMember (Member::eDataType, unsigned int len, const char *name)
| Add a new member to the structure.
size_t | totalSize () const
| Return the amount of memory a packed structure will occupy.
const char * | defaultData () const
| Return a chunk of memory containing default values for the structure.
char * | allocateDefaultChunk () const
| Return an allocated chunk of memory containing default values for the structure.
char * | duplicateChunk (const char *dataPtr) const
| Duplicate a data chunk, including all embedded values.
bool | fillWithDefaultChunk (char *dataPtr) const
| Copy the default structure values into a block of memory.
bool | fillWithDuplicateChunk (char *newData, const char *oldData) const
| Copy the passed in structure values into a block of memory.
bool | destroyChunk (char *dataPtr) const
| Destroy a data chunk, including any members with their own destructors.
bool | chunkIsDefault (const char *dataPtr) const
| Check to see if the data chunk contains all 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.
const char * | name () const
| Get the name of the structure.
void | setName (const char *)
| Set a new name for the structure.
Structure::iterator | begin () const
| Get an iterator pointed to the beginning of the Structure.
Structure::iterator | end () const
| Get an iterator positioned off the end of the Members.
Structure::const_iterator | cbegin () const
| Get a const Member iterator pointed to the beginning of the Structure.
Structure::const_iterator | cend () const
| Get a read-only iterator positioned off the end of the Members.
unsigned int | size () const
| Get the number of Members in the Structure.
bool | empty () const
| Check to see if the Structure has no Members.
unsigned int | memberCount () const
| Get the number of Members in the Structure.
## Static Public Member Functions
static Structure * | create ()
| Structure creator.
static bool | registerStructure (Structure &newStruct)
| Register a new structure in the global list.
static bool | deregisterStructure (Structure &oldStruct)
| Remove a structure from the global list.
static Structure * | structureByName (const char *)
| Lookup a created structure by name.
static void | deleteAllStructures ()
| Remove every structure.
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.
static bool | Debug (const Structure *me, Debug::Footprint &request)
| Answer a footprint request for a Structure object.
## Protected Member Functions Search for all occurrences
| ~Structure ()
| Default destructor, remove the default data if it exists.
## Protected Attributes
char * | fDefault
| Allocated array of structure members. Search for all occurrences
char * | fName
| Memory block containing a default structure value. Search for all occurrences
size_t | fSize
| Name of this structure. Search for all occurrences
unsigned int | fMemberCount
| Total size of all structure members, including padding. Search for all occurrences
bool | fDeleting
| Number of members in fMemberList. Search for all occurrences

## 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]`

Search for all occurrences

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

Returns:
  Pointer to the newly created Structure

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

Search for all occurrences

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.

size_t totalSize | ( |  | ) | const

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

Get the name of the structure.

Returns:
  Pointer to the string containing the structure name

void setName | ( | const char * | name | ) |

Search for all occurrences

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

Structure::iterator begin | ( |  | ) | const

Search for all occurrences

Get an iterator pointed to the beginning of the Structure.

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

Structure::iterator end | ( |  | ) | const

Search for all occurrences

Get an iterator positioned off the end of the Members.

Returns:
  An iterator pointed off the end of the iteration

Structure::const_iterator cbegin | ( |  | ) | const

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

Get the number of Members in the Structure.

Returns:
  Number of Members in the Structure

bool empty | ( |  | ) | const

Search for all occurrences

Check to see if the Structure has no Members.

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

bool registerStructure | ( | Structure & | newStruct | ) | `[static]`

Search for all occurrences

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

Search for all occurrences

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

Search for all occurrences

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

void deleteAllStructures | ( |  | ) | `[static]`

Search for all occurrences

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

Search for all occurrences

Get the number of Members in the Structure.

Returns:
  Number of Members in the Structure

bool Debug | ( | const Structure * | me,
|  | Debug::Print & | request
| ) |  | `[static]`

Search for all occurrences

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

Search for all occurrences

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.

Structure Structure Structure Structure Structure Structure Structure Structure Structure Structure
Structure Structure Structure Structure Structure Structure Structure Structure Structure Structure