#include <adskDataStream.h>

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

Examples:: MetadataSample/createMetadataCmd.cpp, MetadataSample/importMetadataCmd.cpp, MetadataSample/tweakMetadataNode.cpp, MetadataXML/channelSerializerXML.cpp, MetadataXML/streamSerializerXML.cpp, MetadataXML/streamSerializerXML.h, and sceneAssembly/adskSceneMetadataCmd.cpp.

Public Member Functions
	~Stream ()
	Default destructor, disowns the implementation object.

	Stream (const Stream &)
	Copy constructor, shares a reference with the copy if possible. More...

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

bool	operator== (const Stream &) const
	Comparison operator, checks if this Stream is the same as another. More...

Stream::iterator	begin ()
	Get a Member iterator pointed to the beginning of the Stream. More...

Stream::iterator	end ()
	Get an iterator to the end of the Stream. More...

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

Stream::const_iterator	cend () const
	Get an iterator to the end of the Stream. More...

bool	setIndexType (const std::string &indexTypeName)
	Define the type of index used by this Stream. More...

std::string	indexType () const
	Return the type of index used by this Stream. More...

bool	makeUnique ()
	Make the Stream data unique to this object. More...

bool	clear ()
	Clear out all data currently in the Stream. More...

const Structure &	structure () const
	Get the Structure being used by this Stream. More...

bool	setStructure (const Structure &newStructure)
	Set the structure to be used in this Stream. More...

const std::string &	name () const
	Get the name of this Stream. More...

IndexCount	elementCount () const
	Get the number of elements currently in this data Stream. More...

bool	mergeStream (const Stream &streamEdits)
	Merge a stream of metadata into this stream. More...

bool	setElementRange (Index firstEl, Index lastEl)
	Create space for a fixed range of elements on the Stream. More...

bool	useDenseStorage (bool isDataDense)
	Switch the current storage mode to dense or sparse. More...

bool	setUseDefaults (bool useTheDefaults)
	Switch the current retrieval mode of values which are not explicitly stored. More...

bool	useDefaults () const
	Ask if the storage is using defaults for unspecified values. More...

bool	setElement (Index elementIndex, const Handle &newElement)
	Add a new data element to the Stream. More...

Handle	element (Index elementIndex)
	Get the element at the given index. More...

bool	hasElement (Index elementIndex) const
	Check to see if the element exists in the Stream. More...

bool	reindexElement (Index oldIndex, Index newIndex)
	Change the index of a single element. More...

bool	swapElements (Index oldIndex, Index newIndex)
	Swap two indices in a list. More...

bool	removeElement (Index elementIndex)
	Remove a single element from this data Stream. More...

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

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

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

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

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

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

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

Examples:: MetadataXML/streamSerializerXML.cpp.

Stream::const_iterator cend ( ) const

Get an iterator to the end of the Stream.

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

Examples:: MetadataXML/streamSerializerXML.cpp.

bool setIndexType ( const std::string & indexTypeName )

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

Examples:: MetadataXML/streamSerializerXML.cpp.

std::string indexType ( ) const

Return the type of index used by this Stream.

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

Examples:: MetadataXML/streamSerializerXML.cpp.

bool makeUnique ( )

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

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

Get the Structure being used by this Stream.

Returns: reference to this Stream's structure

Examples:: MetadataXML/streamSerializerXML.cpp.

bool setStructure ( const Structure & newStructure )

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

Get the name of this Stream.

Returns: reference to this Stream's name

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

IndexCount elementCount ( ) const

Get the number of elements currently in this data Stream.

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

Examples:: MetadataSample/tweakMetadataNode.cpp, and sceneAssembly/adskSceneMetadataCmd.cpp.

bool mergeStream ( const Stream & streamEdits )

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
	)

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 )

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 )

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

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
	)

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

Examples:: MetadataXML/streamSerializerXML.cpp, and sceneAssembly/adskSceneMetadataCmd.cpp.

Handle element ( Index elementIndex )

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

Examples:: MetadataSample/tweakMetadataNode.cpp, and sceneAssembly/adskSceneMetadataCmd.cpp.

bool hasElement ( Index elementIndex ) const

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
	)

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
	)

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 )

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

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

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.

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

adskDataStream.h
adskDataStream.cpp

Stream Class Reference

Class Description

Public Member Functions

Static Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation