Win32::OLE::Enum

The Win32::OLE::Enum module provides special support for collections. Collections are special automation data types that contain an array of objects or data. A collection supports enumeration; you can iterate through each item through a standard interface.

Collection objects should always provide a Count property (the number of items in the collection) and an Item method. The Item method is used to access a particular collection item using a subscript, which may be an integer or a string, depending on the server. Collection objects may also optionally contain an Add and a Remove method.

Collection objects also support a standard COM interface (IEnumVARIANT) that allows you to enumerate each item in a collection. It defines methods that let you advance the iteration to the next item, skip a given item, restart the enumeration, and create a new copy of the iterator. While all servers are supposed to provide this interface, some servers don't implement all of the methods (often Reset and Clone are not implemented).

Win32::OLE::Enum defines these methods for enumerating collections. The collection object should provide the Count and Item methods, which are often all you need to use on collections. For example:

$cnt = $coll->Count( ); if( $cnt) {
 $obj = $coll->Item(0); $obj->do_something( );
}

Count will tell you the number of items in the collection, and Item will return the desired item as a Win32::OLE object.

For the enumeration methods, you need to create an enumeration object for the collection object:

$coll = $obj->some_coll( ); $enum = Win32::OLE::Enum->new($coll);

Now you can use the enumeration methods on the object.

Win32::OLE::Enum Methods

The following methods are defined in Win32::OLE::Enum.

Win32::OLE::Enum->new($obj) 

Creates a new Win32::OLE::Enum object. Provides it with a collection object or an existing Enum object, in which case it calls Clone.

$Enum->All( ) 

Returns a list of all objects in the collection. Note that to use All again, you need to first call Reset.

$Enum->Clone( ) 

Returns a copy of the current iterator. This method is supposed to maintain the same iteration position, if possible, but may be unimplemented.

$Enum->Next([count]) 

Returns the next item in the collection. You can optionally provide Next with a count (which must be greater than zero), in which case it returns a list of the next count items. Note that if you provide a scalar context in conjunction with a count, you'll get only the last item in the list of returned items. Next returns undef if it is currently on the last item in the collection.

$Enum->Reset( ) 

Restarts the enumeration with the first item in the collection. Reset returns true if it succeeds, false if it fails. Note that this method may be unimplemented.

$Enum->Skip([count]) 

Skips the next count number of items of the enumeration (again, count must be positive and defaults to ). Skip returns false if there are not at least countitems left.