XSICollection.Unique

Description

Returns or sets a Boolean value indicating whether or not this collection is unique. A collection is unique if it contains only one copy of an object (ie., no duplicates). However, you can have several different objects in a unique collection.

Note: XSICollection is non-unique by default: you have to explicitly set the Unique flag to True in order to get a unique collection. Once a collection is unique, all duplicates are removed and you cannot add any more duplicates.

Examples

1. VBScript Example

Dim oColl             ' object pointer for collection
' Create a non-unique collection as an ActiveX object
Set oColl = CreateObject("XSI.Collection")
' Add a bunch of duplicates
oColl.Add ActiveSceneRoot
oColl.Add ActiveSceneRoot
oColl.Add ActiveSceneRoot
oColl.Add ActiveSceneRoot
oColl.Add ActiveSceneRoot
' How many members are in this collection?
countMembers oColl
' Explicitly set
oColl.Unique = True
' Now how many members are in this collection?
countMembers oColl
'--------------------------------------------------
function countMembers( in_coll )
        ' How many members are in this collection
        LogMessage "This collection contains " & in_coll.Count & " members."
end function
'--------------------------------------------------
' Output of above script:
'INFO : "This collection contains 5 members."
'INFO : "This collection contains 1 members."

2. JScript Example

/*
        This example demonstrates how you can remove all instances
        of an object using either the Unique property or using the
        RemoveItems method iteratively
*/
NewScene( null, false );
// Add multiple instances of the Scene_Root to two collections
var oQuints1 = new ActiveXObject( "XSI.Collection" );
var oQuints2 = new ActiveXObject( "XSI.Collection" );
for ( i=0; i<5; i++)
{
        oQuints1.Add( ActiveSceneRoot );
        oQuints2.Add( ActiveSceneRoot );
}
LogMessage( "-------------------------------" );
LogMessage( "oQuints1 before removing: " + oQuints1.GetAsText() );
LogMessage( "oQuints2 before removing: " + oQuints2.GetAsText() );
// Reduce the first collection to one scene root using the Unique property
oQuints1.Unique = true;
LogMessage( "-------------------------------" );
LogMessage( "oQuints2 after Unique: " + oQuints2.GetAsText() );
// Now create an XSICollection with a single scene root so we can remove
// a single instance of the root one at a time
var oRemoveMe = new ActiveXObject( "XSI.Collection" );
oRemoveMe.Add( ActiveProject.ActiveScene.Root );
// One a time, remove all instances of the root
LogMessage( "-------------------------------" );
while ( oQuints2.RemoveItems( oRemoveMe ).Count != 0 )
{
        LogMessage( "Another one bites the dust (" + oQuints2.Count + " items now remain in the collection)." );
}
LogMessage( "-------------------------------" );
LogMessage( "oQuints2 after RemoveItems: " + oQuints2.GetAsText() );
//--------------------------------------------------
// Output of above script:
//INFO : "-------------------------------"
//INFO : "oQuints1 before removing: Scene_Root,Scene_Root,Scene_Root,Scene_Root,Scene_Root"
//INFO : "oQuints2 before removing: Scene_Root,Scene_Root,Scene_Root,Scene_Root,Scene_Root"
//INFO : "-------------------------------"
//INFO : "oQuints2 after Unique: Scene_Root,Scene_Root,Scene_Root,Scene_Root,Scene_Root"
//INFO : "-------------------------------"
//INFO : "Another one bites the dust (4 items now remain in the collection)."
//INFO : "Another one bites the dust (3 items now remain in the collection)."
//INFO : "Another one bites the dust (2 items now remain in the collection)."
//INFO : "Another one bites the dust (1 items now remain in the collection)."
//INFO : "Another one bites the dust (0 items now remain in the collection)."
//INFO : "-------------------------------"
//INFO : "oQuints2 after RemoveItems: "

See Also

XSICollection.RemoveItems