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

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions

# Stream Class Reference

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

Search for all occurrences

## Detailed Description

Class handling a list of generic data.

This class maintains a list of data with efficient operations for manipulating elements on the list. It works in the class hierarchy controlled by adsk::Data::Associations; see the documentation for that class for the bigger picture of how the classes interrelate.

adsk::Data::Stream is responsible for managing an indexed list of data. It's conceptually like an array, optimized for operations expected to be common for this class hierarchy (deleting from the middle, inserting into several different spots in the middle, duplicating entries, filling sections of the array in one operation, etc.)

`#include <adskDataStream.h>`

List of all members.

## Public Member Functions
| ~Stream ()
| Default destructor, disowns the implementation object.
| Stream (const Stream &)
| Copy constructor, shares a reference with the copy if possible.
| Stream (const Structure &dataStructure, const std::string &streamName)
| Usual constructor, initializes the definition of data to store.
Stream & | operator= (const Stream &)
| Assignment operator, shares implementation with the rhs.
bool | operator== (const Stream &) const
| Comparison operator, checks if this Stream is the same as another.
Stream::iterator | begin ()
| Get a Member iterator pointed to the beginning of the Stream.
Stream::iterator | end ()
| Get an iterator to the end of the Stream.
Stream::const_iterator | cbegin () const
| Get a const Member iterator pointed to the beginning of the Stream.
Stream::const_iterator | cend () const
| Get an iterator to the end of the Stream.
bool | setIndexType (const std::string &indexTypeName)
| Define the type of index used by this Stream.
std::string | indexType () const
| Return the type of index used by this Stream.
bool | makeUnique ()
| Make the Stream data unique to this object.
bool | clear ()
| Clear out all data currently in the Stream.
const Structure & | structure () const
| Get the Structure being used by this Stream.
bool | setStructure (const Structure &newStructure)
| Set the structure to be used in this Stream.
const std::string & | name () const
| Get the name of this Stream.
IndexCount | elementCount () const
| Get the number of elements currently in this data Stream.
bool | mergeStream (const Stream &streamEdits)
| Merge a stream of metadata into this stream.
bool | setElementRange (Index firstEl, Index lastEl)
| Create space for a fixed range of elements on the Stream.
bool | useDenseStorage (bool isDataDense)
| Switch the current storage mode to dense or sparse.
bool | setUseDefaults (bool useTheDefaults)
| Switch the current retrieval mode of values which are not explicitly stored.
bool | useDefaults () const
| Ask if the storage is using defaults for unspecified values.
bool | setElement (Index elementIndex, const Handle &newElement)
| Add a new data element to the Stream.
Handle | element (Index elementIndex)
| Get the element at the given index.
bool | hasElement (Index elementIndex) const
| Check to see if the element exists in the Stream.
bool | reindexElement (Index oldIndex, Index newIndex)
| Change the index of a single element.
bool | swapElements (Index oldIndex, Index newIndex)
| Swap two indices in a list.
bool | removeElement (Index elementIndex)
| Remove a single element from this data Stream.
| DeclareObjectCounter (Stream)
| Flag indicating to print as hex.
## Static Public Member Functions
static bool | Debug (const Stream *me, Debug::Print &request)
| Answer a Print request for a Stream object.
static bool | Debug (const Stream *me, Debug::Footprint &request)
| Answer a footprint request for a Stream object. Search for all occurrences

## Constructor & Destructor Documentation

Stream | ( | const Stream & | rhs | ) |

Copy constructor, shares a reference with the copy if possible.

Parameters:

  [in] | rhs | Stream data to be copied

## Member Function Documentation

Stream & operator= | ( | const Stream & | rhs | ) |

Assignment operator, shares implementation with the rhs.

Parameters:

  [in] | rhs | Stream data to be copied

bool operator== | ( | const Stream & | rhs | ) | const

Comparison operator, checks if this Stream is the same as another.

Equivalence means "is it the same object". Having the same content is meaningless at this level so just check to see if the objects are sharing the same Stream implementation object.

Parameters:

  [in] | rhs | Stream data to be compared

Returns:
  true if the two Streams refer to the same data

Stream::iterator begin | ( |  | ) |

Search for all occurrences

Get a Member iterator pointed to the beginning of the Stream.

Returns:
  A Member iterator pointing at the first element of the Stream

Stream::iterator end | ( |  | ) |

Search for all occurrences

Get an iterator to the end of the Stream.

Returns:
  A Stream iterator positioned off the end of the Stream

Stream::const_iterator cbegin | ( |  | ) | const

Search for all occurrences

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

Returns:
  A Member iterator pointing at the first element of the Stream

Stream::const_iterator cend | ( |  | ) | const

Search for all occurrences

Get an iterator to the end of the Stream.

Returns:
  A Stream iterator positioned off the end of the Stream

bool setIndexType | ( | const std::string & | indexTypeName | ) |

Search for all occurrences

Define the type of index used by this Stream.

Only a single IndexType is allowed for any given Stream. This method sets and remembers the allowed type so that it can be verified when values are being set or requested.

If no explicit index type is set the default of "numeric" is used. i.e. adsk::Data::Index values are all numerics and Stream members are accessed the same as an array would be

If the new index type does not support dense storage and the current data is already stored densely then it must be copied over into a mapped implementation first.

Parameters:

  [in] | indexTypeName | Name of the Index type to be used

Returns:
  false if the Index type could not be set, e.g. because the type name was not recognized, or uncopyable data was present

std::string indexType | ( |  | ) | const

Search for all occurrences

Return the type of index used by this Stream.

Returns:
  Name of the IndexType class used by this Stream for indexing its data

bool makeUnique | ( |  | ) |

Search for all occurrences

Make the Stream data unique to this object.

Makes a copy of the data if it's currently being shared, otherwise leaves it as-is. Note that it can still be shared afterwards by some other object, i.e. this is not a persistent state, just an operation to perform before making changes you don't want any other copies of the associations to share.

Returns:
  true if the data was duplicated in order to make it unique

bool clear | ( |  | ) |

Search for all occurrences

Clear out all data currently in the Stream.

Removes and destroys if necessary all current elements in the Stream.

Returns:
  true if the data was successfully cleared

const Structure & structure | ( |  | ) | const

Search for all occurrences

Get the Structure being used by this Stream.

Returns:
  reference to this Stream's structure

bool setStructure | ( | const Structure & | newStructure | ) |

Search for all occurrences

Set the structure to be used in this Stream.

It's an error to redefine the structure if there is any existing data. If that is the case then this method will return 'false' and the structure definition will not be changed.

Parameters:

  [in] | newStructure | Structure definition to use for this Stream

Returns:
  false if any data already existed

const std::string & name | ( |  | ) | const

Search for all occurrences

Get the name of this Stream.

Returns:
  reference to this Stream's name

IndexCount elementCount | ( |  | ) | const

Search for all occurrences

Get the number of elements currently in this data Stream.

Returns:
  count of the number of elements currently in this Stream

bool mergeStream | ( | const Stream & | streamEdits | ) |

Search for all occurrences

Merge a stream of metadata into this stream.

An efficient way of adding and setting new values on a metadata Stream is to create a new Stream and merge its values in to the original. When an index had a value already the value will be changed to the one in the edits, when it did not the value from the edits is added to the current Stream.

Parameters:

  [in] | streamEdits | Stream containing the new values to be merged in

Returns:
  true if the edits in the streamEdits Stream were successful

bool setElementRange | ( | Index | firstEl,
|  | Index | lastEl
| ) |  |

Search for all occurrences

Create space for a fixed range of elements on the Stream.

If there are already elements in the Stream then leave them intact. If there are more than requested then the extras will be removed. e.g. if the Stream had elements [0,5] then after setElementRange(0,4) the 5th element will be removed, but after setElementRange(0,6) the original 5 will be intact and one element with the default value will be added to the end of the Stream.

Subsequent calls to addElement with an index outside of this range will still work, this is just a hint as to where the range might be. Those subsequent calls will expand the element range to included the added index. (e.g. setElementRange(3,8) and addElement(20, DATA) will make the valid range [3,20])

Parameters:

  [in] | firstEl | Index of the first valid element
  [in] | lastEl | Index of the last valid element

Returns:
  true if the Stream now has space for the element range specified

bool useDenseStorage | ( | bool | isDataDense | ) |

Search for all occurrences

Switch the current storage mode to dense or sparse.

In some cases you will know that you wish to set values on most or all of your metadata elements. In those cases it is more efficient to store every single value separately rather than a map of (index, value) pairs. This method lets you provide that information to the class.

This is purely for performance optimization. The answers returned from the data query methods will be the same no matter which storage mode is in use.

This method switches the current storage type. It provides no guarantee that this storage type will continue to be used in the future.

Parameters:

  [in] | isDataDense | Should every element be explicitly stored rather than only the ones with values assigned?

Returns:
  true if the new storage mode was successfully set

bool setUseDefaults | ( | bool | useTheDefaults | ) |

Search for all occurrences

Switch the current retrieval mode of values which are not explicitly stored.

(Possibilities are return fail and return default.)

When values which are not explicitly stored are requested then that could either mean that they don't exist at all, or that they have the default value and are just not stored for performance reasons.

This method sets the interpretation for this missing data. The interpretation also depends on the storage mode. So when a value for the requested index is not found in storage:

Returns failure when setUseDefaults is false if:

- value is outside of the setElementRange range, if defined and
- index does not exist in the sparse map, if it exists

Returns failure when setUseDefaults is true if:

- value is outside of the setElementRange range, if defined

Parameters:

  [in] | useTheDefaults | If true then if an index is in range but has no explicit value return the default value instead. If false this returns failure.

Returns:
  true if the new missing value mode was successfully set

bool useDefaults | ( |  | ) | const

Search for all occurrences

Ask if the storage is using defaults for unspecified values.

See documentation for Stream::setUseDefaults for deteails on what it means to use defaults for unspecified values.

Returns:
  true if defaults are being used for unspecified values

bool setElement | ( | Index | elementIndex,
|  | const Handle & | newElement
| ) |  |

Search for all occurrences

Add a new data element to the Stream.

The indexes are not necessarily sequential so only the given index is guaranteed to be added regardless of what other index values already have data. The values of the other indexes, if added, will depend on structure information. See the documentation for adsk::Data::Structure for details.

If an element already exists at that particular index the old data will be replaced by the new data so be sure to check element(index) first if that's not the desired behavior.

The handle has to have the same data structure as the Stream, otherwise nothing is added and false is returned.

Parameters:

  [in] | elementIndex | Index of the element to be added
  [in] | newElement | Handle to the element to be added at the new index

Returns:
  true if the element was added

Handle element | ( | Index | elementIndex | ) |

Search for all occurrences

Get the element at the given index.

In the current implementation some elements may be NULL so be sure to check the return value before dereferencing it. The return value is a direct reference to the Stream's copy of the data so modifying it effects the values immediately. There is no need to call setElement when the modifications are complete.

Parameters:

  [in] | elementIndex | Index of the element to retrieve

Returns:
  data handle for the given index

bool hasElement | ( | Index | elementIndex | ) | const

Search for all occurrences

Check to see if the element exists in the Stream.

Parameters:

  [in] | elementIndex | Index of the element to find

Returns:
  true if the element is a member of the Stream

bool reindexElement | ( | Index | oldIndex,
|  | Index | newIndex
| ) |  |

Search for all occurrences

Change the index of a single element.

If the newIndex already had a value it will be overwritten. The oldIndex value is copied to the newIndex location. In sparse mode the oldIndex value is removed; in dense mode it is overwritten with default values.

Parameters:

  [in] | oldIndex | Index of the element to be altered
  [in] | newIndex | New index for the element

Returns:
  true if the element exists and was renumbered

bool swapElements | ( | Index | firstIndex,
|  | Index | secondIndex
| ) |  |

Search for all occurrences

Swap two indices in a list.

This does a one-for-one swap of the elements at two different indices in the Stream. It preserves both sets of values, just swapping their indices. (i.e. the return values from calling element(firstIndex) and element(secondIndex) are reversed)

Parameters:

  [in] | firstIndex | One index to swap
  [in] | secondIndex | The other index to swap

Returns:
  true if the element exists and was renumbered

bool removeElement | ( | Index | elementIndex | ) |

Search for all occurrences

Remove a single element from this data Stream.

Parameters:

  [in] | elementIndex | Index of the data to be removed

Returns:
  true if the element exists and was removed, or if it didn't exist

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

Search for all occurrences

Answer a Print request for a Stream object.

Use the request object to dump all information on the "me" Stream, or all static Stream 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 Stream * | me,
|  | Debug::Footprint & | request
| ) |  | `[static]`

Search for all occurrences

Answer a footprint request for a Stream 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 Stream 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.

Stream Stream Stream Stream Stream Stream Stream Stream Stream Stream
Stream Stream Stream Stream Stream Stream Stream Stream Stream Stream