|
Purpose |
A collection object is a set of items which can be referred to as a unit. It provides a convenient way to refer to a related group of items as a single object. The items in a collection need only be related by the fact that they exist in the collection. They do not have to share the same data type. You create a collection the same way you create other objects, but using a predefined internal class and a predefined internal interface. LOCAL Collect AS IPowerCollection LET Collect = CLASS "PowerCollection" Once you have created a collection object, you can manipulate it using
the member methods. Each
data item in the set is stored as a variant variable, which may contain
any valid data type (
While the collection object expects to receive your data items as variant variables, you can take advantage of the auto-conversion options in PowerBASIC. If a variant parameter is expected, and you pass a single variable instead, PowerBASIC will automatically convert it with no intervention needed on your part. Very often, it's convenient to create a collection of user defined types (UDT). While a variant may not normally contain a UDT, PowerBASIC offers a special methodology to do so. At programmer direction, a TYPE may be assigned to a variant (as a byte string) by using: [LET] VrntVar = TypeVar AS STRING In the same manner, a UDT argument can be auto-converted to the variant type by appending AS STRING: CollObj.Add(Key$$, UDTVar AS STRING) The data contained in the User-Defined Type variable (UDTVar) is stored in the variant argument as a dynamic string of bytes (vt_bstr). When the collection object retrieves that UDT data, it understands the content and handles it accurately. This special technique offers ease of coding and much improved execution speed. If you like, you can use the same sort of functionality in your own PowerBASIC code. However, you should keep in mind that other programming languages may not understand this technique, so it should be limited to PowerBASIC applications. |
|
A Power Collection creates a set of data items, each of which is associated
with an alpha-numeric
| |
|
Syntax |
The CLASS is "PowerCollection". The INTERFACE is IPowerCollection (a DUAL interface). <ObjectVar>.membername(params) RetVal = <ObjectVar>.membername(params) <ObjectVar>.membername(params) TO ReturnVariable |
|
Remarks |
Items in a PowerCollection may be retrieved by their key using the ITEM method. They may be retrieved sequentially using the NEXT or PREVIOUS method. Each key in a PowerCollection must be unique. Keys in a PowerCollection are case-sensitive. To access the keys in a case-insensitive manner, you must create and retrieve all keys as either upper case or lower case, but not mixed. The Dispatch ID (DispID) for each member method is displayed within angle brackets. Power Collection Methods ADD <3> (PowerKey AS WString, PowerItem AS Variant) The PowerItem variant is added to the end of the PowerCollection. It is associated with the PowerKey string for later retrieval. If the operation was successful, an HResult of S_OK (0) is returned. If it fails because of a duplicate key, an HResult of E_DUPLICATEKEY (&H800A01C9) is returned, and an Object Error (99) is generated. All PowerKeys and PowerItems are removed from the PowerCollection. CONTAINS <5> (PowerKey AS WString) AS Long The PowerCollection is scanned to determine if the specified PowerKey is present. If found, the Index number of this Item (range of 1 - COUNT) is returned. This value will always evaluate as true. If not found, the value false (0) is returned. The number of data items currently contained in the PowerCollection is returned to the caller. ENTRY <7> (Index AS Long, OUT PowerKey as WString, OUT PowerItem as Variant) The PowerCollection entry specified by the Index number is returned to the caller in the two specified OUT parameters. If the index number is less than one, or greater than the item count, the variant returned will be of type empty (VT_EMPTY), and the OBJRESULT will be %S_FALSE (1). The current INDEX for the PowerCOLLECTION is set to one (1), so that subsequent references to the NEXT method will access member items from the beginning. The previous value of the INDEX is returned to the caller. INDEX <8> (Index AS Long) AS Long The current INDEX for the PowerCOLLECTION is set to the specified index number. If the parameter is less than one, or greater than the current count of data items, the INDEX is not changed. The previous value of the INDEX is returned to the caller. IndexVar& = ObjectVar.INDEX(0) The above example retrieves the current index number, without changing it, and assigns it to the variable IndexVar&. ITEM <9> (PowerKey AS WString) AS Variant The PowerItem associated with the specified PowerKey is returned. If the specified key is not found, the variant returned will be of type empty (VT_EMPTY), and the OBJRESULT will be %S_FALSE (1). The current INDEX for the PowerCOLLECTION is set to the last item so that subsequent references to the PREVIOUS method will access member items from the end. The previous value of the INDEX is returned to the caller. The NEXT method allows the PowerCollection data items to be retrieved sequentially. Each time NEXT is referenced, the data item at the position specified by the INDEX is returned to the caller, and the INDEX is incremented. If the operation is successful, the OBJRESULT is set to %S_OK (0). When there are no more data items to retrieve, the OBJRESULT is set to %S_FALSE (1). The PREVIOUS method allows the PowerCollection data items to be retrieved sequentially. Each time PREVIOUS is referenced, the data item at the position specified by the INDEX is returned to the caller, and the INDEX is decremented. If the operation is successful, the OBJRESULT is set to %S_OK (0). When there are no more data items to retrieve, the OBJRESULT is set to %S_FALSE (1). REMOVE <12> (PowerKey AS WString) The specified PowerKey, and the PowerItem associated with it, are removed from the PowerCollection. The index number of each data item past the removed item is decremented by one. If the requested PowerKey is not found, OBJRESULT returns %S_FALSE (1) and no operation is performed. REPLACE <13> (PowerKey AS WString, PowerItem AS Variant) The PowerItem associated with the specified PowerKey is replaced by the new specified PowerItem. If the requested PowerKey is not found, OBJRESULT returns %S_FALSE (1) and no operation is performed. The data items in the PowerCollection are sorted based upon the text in the associated PowerKeys. If the parameter Flags is zero(0), the items are sorted in ascending sequence. If one (1), the items are sorted in descending sequence. |
|
A Linked List Collection is an ordered set of data items, which are accessed by their position in the list rather than by an alphanumeric string key. Each data item is passed and stored as a variant variable. You can retrieve these data items by their position number, or sequentially in ascending or descending sequence. | |
|
Syntax |
The CLASS is "LinkListCollection". The INTERFACE is ILinkListCollection (a DUAL interface). <ObjectVar>.membername(params) RetVal = <ObjectVar>.membername(params) <ObjectVar>.membername(params) TO ReturnVariable |
|
Remarks |
Items in a LinkListCollection may be retrieved by their position number using the ITEM method. They may be retrieved sequentially using the NEXT or PREVIOUS methods. The Dispatch ID (DispID) for each member method is displayed within angle brackets. LinkList Collection Methods ADD <3> (PowerItem AS Variant) The PowerItem variant is added to the end of the LinkListCollection. All PowerItems are removed from the LinkListCollection. The number of data items currently contained in the LinkListCollection is returned to the caller. The current INDEX for the LinkListCOLLECTION is set to one (1), so that subsequent references to the NEXT method will access member items from the beginning. The previous value of the INDEX is returned to the caller. INDEX <6> (Index AS Long) AS Long The current INDEX for the LinkListCOLLECTION is set to the specified index number. If the parameter is less than one, or greater than current count of data items, the INDEX is not changed. The previous value of the INDEX is returned to the caller. IndexVar& = ObjectVar.INDEX(0) The above example retrieves the current index number, without changing it, and assigns it to the variable IndexVar&. INSERT <7> (Index AS Long, PowerItem AS Variant) The PowerItem variant is added to the collection at the position specified by the Index. If the index number is less than one, or greater than the count, the item is added to the end of the list. ITEM <8> (Index AS Long) AS Variant The PowerItem at the position specified by Index is returned. If the specified item is not present, the variant returned will be of type empty (VT_EMPTY), and the OBJRESULT will be %S_FALSE (1). The current INDEX for the LinkListCOLLECTION is set to the last item so that subsequent references to the PREVIOUS method will access member items from the end. The previous value of the INDEX is returned to the caller. The NEXT method allows the LinkListCollection data items to be retrieved sequentially. Each time NEXT is referenced, the data item at the position specified by the INDEX is returned to the caller, and the INDEX is incremented. If the operation is successful, the OBJRESULT is set to %S_OK (0). When there are no more data items to retrieve, the OBJRESULT is set to %S_FALSE (1). The PREVIOUS method allows the LinkListCollection data items to be retrieved sequentially. Each time PREVIOUS is referenced, the data item at the position specified by the INDEX is returned to the caller, and the INDEX is decremented. If the operation is successful, the OBJRESULT is set to %S_OK (0). When there are no more data items to retrieve, the OBJRESULT is set to %S_FALSE (1). The PowerItem at the position specified by Index is removed from the LinkListCollection. The index number of each data item past the removed item is decremented by one. If the requested item is not present, OBJRESULT returns %S_FALSE (1) and no operation is performed. REPLACE <12> (Index AS Long, PowerItem AS Variant) The PowerItem at the position specified by Index is replaced by the new specified PowerItem. If the requested PowerItem is not present, OBJRESULT returns %S_FALSE (1) and no operation is performed. |
|
A Stack Collection is an ordered set of data items, which are accessed on a LIFO (Last-In / First-Out) basis. This collection follows the same algorithm as the machine stack on your Intel CPU. Each data item is passed and stored as a variant variable, using the PUSH and POP methods. | |
|
Syntax |
The CLASS is "StackCollection". The INTERFACE is IStackCollection (a DUAL interface). <ObjectVar>.membername(params) RetVal = <ObjectVar>.membername(params) <ObjectVar>.membername(params) TO ReturnVariable |
|
Remarks |
The Dispatch ID (DispID) for each member method is displayed within angle brackets. Stack Collection Methods All PowerItems are removed from the StackCollection. The number of data items currently contained in the StackCollection is returned to the caller. The PowerItem at the "Stack-Top" (the item most recently added) is retrieved and returned to the caller. When there are no more data items to retrieve, the variant returned will be of type empty (VT_EMPTY), and the OBJRESULT will be %S_FALSE (1). PUSH <4> (PowerItem AS Variant) The specified PowerItem is added to the StackCollection at the "Stack-Top" position. |
|
A Queue Collection is an ordered set of data items, which are accessed on a FIFO (First-In / First-Out) basis. Each data item is passed and stored as a variant variable, using the ENQUEUE and DEQUEUE methods. | |
|
Syntax |
The CLASS is "QueueCollection". The INTERFACE is IQueueCollection (a DUAL interface). <ObjectVar>.membername(params) RetVal = <ObjectVar>.membername(params) <ObjectVar>.membername(params) TO ReturnVariable |
|
Remarks |
The Dispatch ID (DispID) for each member method is displayed within angle brackets. Queue Collection Methods All PowerItems are removed from the QueueCollection. The number of data items currently contained in the QueueCollection is returned to the caller. The PowerItem at the "oldest" position is retrieved and returned to the caller. When there are no more data items to retrieve, the variant returned will be of type empty (VT_EMPTY), and the OBJRESULT will be %S_FALSE (1). ENQUEUE <4> (PowerItem AS Variant) The specified PowerItem is added to the QueueCollection at the "newest" position. |
|
See Also |