Stream Class Reference
Related help topics: #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:
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
Copy constructor, shares a reference with the copy if possible.
- Parameters
-
[in] rhs Stream data to be copied
Member Function Documentation
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 | ( | ) |
| Stream::iterator end | ( | ) |
| Stream::const_iterator cbegin | ( | ) | const |
| Stream::const_iterator cend | ( | ) | const |
| 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:
| std::string indexType | ( | ) | const |
| 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 | ( | ) |
| const Structure & structure | ( | ) | const |
| 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.
- Returns
- false if any data already existed
| const std::string & name | ( | ) | const |
| IndexCount elementCount | ( | ) | const |
| 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
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])
- 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
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:
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:
| bool hasElement | ( | Index | elementIndex | ) | const |
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
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 | ) |
|
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.
|
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