 |  |
23.3. 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.
23.3.1. Win32::OLE::Enum Methods
The following methods are defined in Win32::OLE::Enum.
| new |
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.
| All |
$Enum->All( )
Returns a list of all objects in the collection. Note that to use All again, you need to first call Reset.
| Clone |
$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.
| Next |
$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.
| Reset |
$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.
| Skip |
$Enum->Skip([count])
Skips the next count number of items of the enumeration (again, count must be positive and defaults to 1). Skip returns false if there are not at least countitems left.
|  | |
| 23.2. Automation Methods and Properties |  | 23.4. Win32::OLE::Variant |
Copyright © 2002 O'Reilly & Associates. All rights reserved.