The Collection Ocx (part 2)

In the previous post I introduced the Collection Ocx object and discussed its implementation. The Collection COM object is nothing more than a COM wrapper to the Hash object. To be more precise, the Collection Ocx maintains a Hash Variant data object. The following two statements both result in the creation of a Hash data structure: Dim col As New Collection Dim hs As Hash Variant The Hash commands (and its many operators []) provide the functionality to the underlying hash table. The hash table is the data structure GFA-BASIC 32 uses in almost any case some kind of collection is to be made. GFA-BASIC 32 uses the hash table at the base of the Ocx collections like Panels, ListImages, ColumnHeaders, etc. But it also uses the hash table intensively at the heart of the compiler. All data types, variables, constants, anythings that has to be collected during compiling is stored in a hash table. This prooves the outstanding performance of the Hash data structure, because the compiler is one of the fastest around. Not all Ocx collections use the hash table though; the ListItems Ocx is a COM wrapper around the ListView control's LVM_GETITEM message. The ListItem object, the element from a ListItems collection, is stored in the lParam member of the LVITEM structure used with LVM_GETITEM and LVM_SETITEM messages (see your SDK/MSDN). This brings me to the heart of my post, all so called Ocx/COM collections use the same interface. They use the same properties and methods to access a collection element. These properties and methods I discussed in the previous post. For most of Ocx collection objects these properties and methods directly translate in Hash commands. As said, some Ocx collections implement the methods (and properties) Add, Item, Remove, Clear, and Count in some other way. For instance, the ToolBar's collection Buttons is rather buggy, because the Buttons collection isn't a wrapper for a Hash table, but for a set of functions that maintain the buttons in another way. The Buttons collections is not build on proven mechanism of the hash table. Because most GFA-BASIC 32 Ocx collections are based on the Hash data structure, accessing an item is very fast. An item is either accessed using the default Item() method or obtained with the iteration command For Each...Next. The argument of the Item method of a collection always takes a Variant, which contains

• a numberic value specifying the index
• or a string specifying the key used to store the item

Collection elements are accessible by their index value, although the lower bound of a collection object’s index is always 1, and can’t be set otherwise in code. In VB, however, the performance is poor if items are to be accessed by index. This is in contrast with GFA-BASIC 32, which has a very fast implementation of accessing a collection object by index, due to its fast performance Hash structure! (And this isn't the only optimization GFA-BASIC 32 features with Collections.) Often the default method .Item() is invoked using a literal string key, rather than a string variable. For instance, look at these statements that access the element by a literal string key: v =c("a") v = c.Item("a") In the case the string literal starts with an alphabetic character (a-z, A-Z) and for the rest contains digits and/or an underscore (_), GFA-BASIC 32 uses a non-OLE compatible function to access the item. Rather than converting the "a" to COM string, GFA-BASIC 32 passes a pointer to the ANSI version of the key-string. This might need some more explanation. Every call to a COM function, whether it is a property or method, that takes a string (either in a Variant or as string parameter) uses a special COM BSTR data type. To facilitate the COM requirement GFA-BASIC will convert each(!) string you assign to a COM property or use in a method call to a BSTR, a wide UNICODE string. GFA-BASIC 32 consequently uses this ANSI to UNICODE conversion, because this is required by the COM rules. GFA-BASIC 32 must perform these conversions when you use the CreateObject() function to obtain an external COM automation object that require COM compatibility, which is the use of UNICODE. Internally, GFA-BASIC 32 objects stores the BSTRs as ANSI strings. Now you might notice the strange fact, that a string passed to an Ocx object is conerted twice, form ANSI to COM-compatible UNICODE, and back from UNICODE to ANSI. This IS EXACTLY what is happening, for instance when you pass a (large) string to aTextBox ocx, the string is first converted to UNICODE and then passed to the underlying EDITTEXT control using SetWindowTextA(). Before the string is passed to the ANSI version the SetWindowText() API it has to reconverted to ANSI. Fortunately, GFA-BASIC uses its own highly optimized Ansi-to-Unicode and Unicode-to-Ansi functions. The !-operator is used to provide an optimization for the literal strings used as keys used in methods to access an item of a GFA-BASIC 32 collection (Collection, ListImages, ListItems, Buttons, etc), the literal strings are passed in ANSI format rather than in UNICODE when you use the ! operator to specify the key. This alternative syntax results in 'v!a' for the example mentioned, and in general: Collection!StringIndex. So v =c!a <=> v =c("a") Next time I discuss the gain in performance.