Collection Template News

This page details the changes in the latest versions of the Collection Templates, giving some background on the one-line summaries in the ReadMe file.

Collection Templates Discontinued

As of 30 October 2005, the entire functionality of the Collection Templates has been added to the Tektosyne library (version 3.0.0 or later) in the form of generic collection classes. The Collection Templates are therefore discontinued. Anyone is welcome to take up their maintenance.

Version 2.0.0

This release drops synchronized wrappers from all class templates. These wrappers were never actually thread-safe since they only synchronize individual method calls, and collection changes that require synchronization typically involve multiple calls. Microsoft likewise dropped support for this ill-conceived feature from .NET 2.0 onward.

• Breaking change in all class templates: The internal architecture was completely overhauled for shorter files, easier maintenance, and some extra speed. All synchronized wrappers were removed, and only a single wrapper is supported as a derived class.
• Breaking change in ArrayList: Due to the above change, the Unique wrapper was replaced by a settable IsUnique property. This is actually an improvement since it eliminates the chance of duplicate items being added to the wrapped collection.
• DictionaryList and SortedList now have read-only wrappers like all other collections, with the exception of Queue and Stack for which read-only access doesn’t make sense.
• Enumerators allow modifications to the enumerated collection, checking only for an unchanged element count when MoveNext is invoked. The internal collection version counters were dropped, further simplifying the class templates.
• Native code routines were smuggled back in for one special case: they are now activated automatically for Int32 elements.

Version 1.6.0

This release comes with significant breaking changes due to new and changed properties. Make sure to check the revised “Performance” and “Known Issues” sections in the ReadMe file for details on these changes!

• Breaking change in all class templates: The Item/KeyCustomSearch properties were dropped because the new release always uses custom search routines. To handle the special case of standard value types that was previously left to native code routines, there are two new properties: ItemOperators and KeyOperators.

  The new design adequately supports another special case that I had previously overlooked, namely standard library types such as System.Drawing.Point that offer equality operators but no strongly-typed Object.Equals overrides, and that are not handled by native code routines. Performance for such types changed from abysmal to excellent with this release.

• Breaking changes in ArrayList, resulting from the above changes: You must now set KeyValueType to true when using a KeyType that is a value type, and you must set ItemCompareTo to true to generate the BinarySearch overload with a single parameter.
• All ICollection.CopyTo methods now accept Object[] arrays. This resolves the issue that template collections could not act as the DataSource of a bound control, as reported by Dejan Dradovic in the CodeSmith forums.
• Setting the Capacity property of a synchronized wrapper around a DictionaryList or SortedList threw an exception because I forgot to override the setter. This is now fixed, and all unit tests pass with synchronized wrappers as well as with basic collections.
• Added BinarySearch overloads that take an IComparer parameter to the ArrayList template. This complements the existing Sort overloads that take an IComparer.
• The key-and-value pair structure defined in IDictionary.cst got explicit To/FromDictionaryEntry methods as alternatives to the implicit conversion operators, overrides for Object.Equals and GetHashCode, and equality operators to go along with the Equals override. These additions also shut up some FxCop warnings.

Version 1.5.1

This release fixes a bug in the CopyTo method of all templates that was reported by Kyle Blaney in the CodeSmith forums.

Normally, the target array index where copying starts must be less than the length of the target array. However, empty collections accept zero-length target arrays with a target index of zero, since no elements are actually being copied anyway.

Version 1.5.0

This release fixes a couple of bugs and adds several significant new features:

• The Queue template (whose Clone method actually works, unlike Microsoft’s). Now all the standard collection classes have a template equivalent!
• The Hashtable template now has a read-only wrapper, just like the ArrayList. This feature was suggested by Dr. Rainer Hessmer who also provided a sample implementation. Thanks!
• The optional DeepCopy and DeepCopyItem properties provide a deep copy method for all collection classes, named Copy so that Clone remains available for shallow copies. Besides, some (non-collection) standard classes already have a Copy method for deep copies.

  Copy automatically performs a shallow copy for value types and strings, and for the keys of dictionary classes. The latter are usually value types or strings anyway, or else mostly use a simple reference comparison that would fail if the keys were duplicated with a deep copy.

  I also adopted a standard whereby Clone always duplicates whatever wrappers (read-only, synchronized, unique) surround the original collection but Copy does not. Microsoft seems to be confused on this issue; it’s undocumented and varies between collection classes.

In other news, the ItemValueType and KeyValueType properties are now part of CodeSmith’s Context group, along with ItemType and KeyType, since they’re not really Options (their previous group).

Version 1.4.1

This release adds two new features to the ArrayList template:

• The Unique wrapper checks at construction, and then at each addition of a new element, that the collection contains no duplicate elements. That’s an essential security feature when you know that a collection shouldn’t contain any duplicates, and now it’s available in a non-dictionary collection.
• The optional KeyType, KeyName, and KeyIndexer properties allow users to define a field or property of the ArrayList’s ItemType as a “key” that can be searched for, just like a dictionary key. While this feature confers none of the extra benefits of a true dictionary key (uniqueness, fast key search), it comes without the extra memory and runtime cost required for a dictionary.

As you may note, the new (optional) ContainsKey method is not virtual, and the existing Contains method has been de-virtualized as well. This is because all of these methods resolved to a single call to another method (IndexOf/IndexOfKey) which is virtual, and properly overriden by all wrapper classes. Virtualizing this extra step gained nothing and merely wasted time.