C# Class WizardWrx.ListHelpers

Compare two objects of a kind. See Remarks.

This method encapsulates the CompareTo method of a class T, returning a member of the CompareResult enumeration in place of the arbitrary zero or positive or negative integer specified in the IComparable interface. This syntactic sugar enables its return value to be processed by a switch block, rather than a nested IF block. Whether or not I wrote it into the this, calling CompareTo on a null pReference object would elicit a NullReference exception. Having the application throw the exception permits it to supply a more informative message than the one that the CLR would have generated. For a two-argument function, the generic message is ambiguous.

Merge two sorted lists, returning a new sorted list containg the new or updated items from a second list. Please see Remarks.

The goal of this routine is to merge two lists, the first of which is treated as a master list, into which new and updated items from from the second list are merged. Merging is based on comparing items from both lists based on the values returned by their respective CompareTo methods. Values that return zero (equality) are merged by replacing the value from the first list, represented by the first argument (paMasterList) with that from the second list, represented by the second argument (paNewItems). This algorithm imposes four requirements on its inputs. 1) Both input arrays must be composed of objects of the same type. 2) That type must implement the IComparable interface. 3) That type must have a default constructor. 4) Both input arrays must be sorted. In return, it makes the following four guarantees. 1) Every item in array paNewItems will become part of the new list. 2) Every item in array paMasterList that has no matching value in array paNewItems will become part of the new list. 3) Every item in array paNewItems that matches an item in array paMasterList replaces that matching item. 4) Every item in array paNewItems that doesn't match any item in paMasterList is added to the list. On input, both lists must be sorted, which is the first reason that the objects in the arrays must implement IComparable. The second reason is that this routine must compare the two lists in order to merge them correctly. The comparison happens in CompareTwoOfAKind, a companion routine that also takes generics meeting the first of the two specified constraints.