/mcs/class/Mono.C5/C5/Interfaces.cs

Large files files are truncated, but you can click here to view the full file

/*
 Copyright (c) 2003-2006 Niels Kokholm and Peter Sestoft
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in
 all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
*/

using System;
using SCG = System.Collections.Generic;
namespace C5
{
  /// <summary>
  /// A generic collection, that can be enumerated backwards.
  /// </summary>
  public interface IDirectedEnumerable<T> : SCG.IEnumerable<T>
  {
    /// <summary>
    /// Create a collection containing the same items as this collection, but
    /// whose enumerator will enumerate the items backwards. The new collection
    /// will become invalid if the original is modified. Method typically used as in
    /// <code>foreach (T x in coll.Backwards()) {...}</code>
    /// </summary>
    /// <returns>The backwards collection.</returns>
    IDirectedEnumerable<T> Backwards();


    /// <summary>
    /// <code>Forwards</code> if same, else <code>Backwards</code>
    /// </summary>
    /// <value>The enumeration direction relative to the original collection.</value>
    EnumerationDirection Direction { get;}
  }

  /// <summary>
  /// A generic collection that may be enumerated and can answer
  /// efficiently how many items it contains. Like <code>IEnumerable&lt;T&gt;</code>,
  /// this interface does not prescribe any operations to initialize or update the 
  /// collection. The main usage for this interface is to be the return type of 
  /// query operations on generic collection.
  /// </summary>
  public interface ICollectionValue<T> : SCG.IEnumerable<T>, IShowable
  {
    /// <summary>
    /// A flag bitmap of the events subscribable to by this collection.
    /// </summary>
    /// <value></value>
    EventTypeEnum ListenableEvents { get;}

    /// <summary>
    /// A flag bitmap of the events currently subscribed to by this collection.
    /// </summary>
    /// <value></value>
    EventTypeEnum ActiveEvents { get;}

    /// <summary>
    /// The change event. Will be raised for every change operation on the collection.
    /// </summary>
    event CollectionChangedHandler<T> CollectionChanged;

    /// <summary>
    /// The change event. Will be raised for every clear operation on the collection.
    /// </summary>
    event CollectionClearedHandler<T> CollectionCleared;

    /// <summary>
    /// The item added  event. Will be raised for every individual addition to the collection.
    /// </summary>
    event ItemsAddedHandler<T> ItemsAdded;

    /// <summary>
    /// The item inserted  event. Will be raised for every individual insertion to the collection.
    /// </summary>
    event ItemInsertedHandler<T> ItemInserted;

    /// <summary>
    /// The item removed event. Will be raised for every individual removal from the collection.
    /// </summary>
    event ItemsRemovedHandler<T> ItemsRemoved;

    /// <summary>
    /// The item removed at event. Will be raised for every individual removal at from the collection.
    /// </summary>
    event ItemRemovedAtHandler<T> ItemRemovedAt;

    /// <summary>
    /// 
    /// </summary>
    /// <value>True if this collection is empty.</value>
    bool IsEmpty { get;}

    /// <summary>
    /// </summary>
    /// <value>The number of items in this collection</value>
    int Count { get;}

    /// <summary>
    /// The value is symbolic indicating the type of asymptotic complexity
    /// in terms of the size of this collection (worst-case or amortized as
    /// relevant).
    /// </summary>
    /// <value>A characterization of the speed of the 
    /// <code>Count</code> property in this collection.</value>
    Speed CountSpeed { get;}

    /// <summary>
    /// Copy the items of this collection to a contiguous part of an array.
    /// </summary>
    /// <param name="array">The array to copy to</param>
    /// <param name="index">The index at which to copy the first item</param>
    void CopyTo(T[] array, int index);

    /// <summary>
    /// Create an array with the items of this collection (in the same order as an
    /// enumerator would output them).
    /// </summary>
    /// <returns>The array</returns>
    T[] ToArray();

    /// <summary>
    /// Apply a delegate to all items of this collection.
    /// </summary>
    /// <param name="action">The delegate to apply</param>
    void Apply(Act<T> action);


    /// <summary>
    /// Check if there exists an item  that satisfies a
    /// specific predicate in this collection.
    /// </summary>
    /// <param name="predicate">A  delegate 
    /// (<see cref="T:C5.Fun`2"/> with <code>R == bool</code>) defining the predicate</param>
    /// <returns>True is such an item exists</returns>
    bool Exists(Fun<T, bool> predicate);

    /// <summary>
    /// Check if there exists an item  that satisfies a
    /// specific predicate in this collection and return the first one in enumeration order.
    /// </summary>
    /// <param name="predicate">A delegate 
    /// (<see cref="T:C5.Fun`2"/> with <code>R == bool</code>) defining the predicate</param>
    /// <param name="item"></param>
    /// <returns>True is such an item exists</returns>
    bool Find(Fun<T, bool> predicate, out T item);


    /// <summary>
    /// Check if all items in this collection satisfies a specific predicate.
    /// </summary>
    /// <param name="predicate">A delegate 
    /// (<see cref="T:C5.Fun`2"/> with <code>R == bool</code>) defining the predicate</param>
    /// <returns>True if all items satisfies the predicate</returns>
    bool All(Fun<T, bool> predicate);

    /// <summary>
    /// Choose some item of this collection. 
    /// <para>Implementations must assure that the item 
    /// returned may be efficiently removed.</para>
    /// <para>Implementors may decide to implement this method in a way such that repeated
    /// calls do not necessarily give the same result, i.e. so that the result of the following 
    /// test is undetermined:
    /// <code>coll.Choose() == coll.Choose()</code></para>
    /// </summary>
    /// <exception cref="NoSuchItemException">if collection is empty.</exception>
    /// <returns></returns>
    T Choose();

    /// <summary>
    /// Create an enumerable, enumerating the items of this collection that satisfies 
    /// a certain condition.
    /// </summary>
    /// <param name="filter">The T->bool filter delegate defining the condition</param>
    /// <returns>The filtered enumerable</returns>
    SCG.IEnumerable<T> Filter(Fun<T, bool> filter);
  }



  /// <summary>
  /// A sized generic collection, that can be enumerated backwards.
  /// </summary>
  public interface IDirectedCollectionValue<T> : ICollectionValue<T>, IDirectedEnumerable<T>
  {
    /// <summary>
    /// Create a collection containing the same items as this collection, but
    /// whose enumerator will enumerate the items backwards. The new collection
    /// will become invalid if the original is modified. Method typically used as in
    /// <code>foreach (T x in coll.Backwards()) {...}</code>
    /// </summary>
    /// <returns>The backwards collection.</returns>
    new IDirectedCollectionValue<T> Backwards();

    /// <summary>
    /// Check if there exists an item  that satisfies a
    /// specific predicate in this collection and return the first one in enumeration order.
    /// </summary>
    /// <param name="predicate">A delegate 
    /// (<see cref="T:C5.Fun`2"/> with <code>R == bool</code>) defining the predicate</param>
    /// <param name="item"></param>
    /// <returns>True is such an item exists</returns>
    bool FindLast(Fun<T, bool> predicate, out T item);
  }


  /// <summary>
  /// A generic collection to which one may add items. This is just the intersection
  /// of the main stream generic collection interfaces and the priority queue interface,
  /// <see cref="T:C5.ICollection`1"/> and <see cref="T:C5.IPriorityQueue`1"/>.
  /// </summary>
  public interface IExtensible<T> : ICollectionValue<T>, ICloneable
  {
    /// <summary>
    /// If true any call of an updating operation will throw an
    /// <code>ReadOnlyCollectionException</code>
    /// </summary>
    /// <value>True if this collection is read-only.</value>
    bool IsReadOnly { get;}

    //TODO: wonder where the right position of this is
    /// <summary>
    /// 
    /// </summary>
    /// <value>False if this collection has set semantics, true if bag semantics.</value>
    bool AllowsDuplicates { get;}

    //TODO: wonder where the right position of this is. And the semantics.
    /// <summary>
    /// (Here should be a discussion of the role of equalityComparers. Any ). 
    /// </summary>
    /// <value>The equalityComparer used by this collection to check equality of items. 
    /// Or null (????) if collection does not check equality at all or uses a comparer.</value>
    SCG.IEqualityComparer<T> EqualityComparer { get;}

    //ItemEqualityTypeEnum ItemEqualityType {get ;}

    //TODO: find a good name

    /// <summary>
    /// By convention this is true for any collection with set semantics.
    /// </summary>
    /// <value>True if only one representative of a group of equal items 
    /// is kept in the collection together with the total count.</value>
    bool DuplicatesByCounting { get;}

    /// <summary>
    /// Add an item to this collection if possible. If this collection has set
    /// semantics, the item will be added if not already in the collection. If
    /// bag semantics, the item will always be added.
    /// </summary>
    /// <param name="item">The item to add.</param>
    /// <returns>True if item was added.</returns>
    bool Add(T item);

    /// <summary>
    /// Add the elements from another collection with a more specialized item type 
    /// to this collection. If this
    /// collection has set semantics, only items not already in the collection
    /// will be added.
    /// </summary>
    /// <typeparam name="U">The type of items to add</typeparam>
    /// <param name="items">The items to add</param>
    void AddAll<U>(SCG.IEnumerable<U> items) where U : T;

    //void Clear(); // for priority queue
    //int Count why not?
    /// <summary>
    /// Check the integrity of the internal data structures of this collection.
    /// <i>This is only relevant for developers of the library</i>
    /// </summary>
    /// <returns>True if check was passed.</returns>
    bool Check();
  }

  /// <summary>
  /// The simplest interface of a main stream generic collection
  /// with lookup, insertion and removal operations. 
  /// </summary>
  public interface ICollection<T> : IExtensible<T>, SCG.ICollection<T>
  {
    //This is somewhat similar to the RandomAccess marker itf in java
    /// <summary>
    /// The value is symbolic indicating the type of asymptotic complexity
    /// in terms of the size of this collection (worst-case or amortized as
    /// relevant). 
    /// <para>See <see cref="T:C5.Speed"/> for the set of symbols.</para>
    /// </summary>
    /// <value>A characterization of the speed of lookup operations
    /// (<code>Contains()</code> etc.) of the implementation of this collection.</value>
    Speed ContainsSpeed { get;}

    /// <summary>
    /// </summary>
    /// <value>The number of items in this collection</value>
    new int Count { get; }

    /// <summary>
    /// If true any call of an updating operation will throw an
    /// <code>ReadOnlyCollectionException</code>
    /// </summary>
    /// <value>True if this collection is read-only.</value>
    new bool IsReadOnly { get; }

    /// <summary>
    /// Add an item to this collection if possible. If this collection has set
    /// semantics, the item will be added if not already in the collection. If
    /// bag semantics, the item will always be added.
    /// </summary>
    /// <param name="item">The item to add.</param>
    /// <returns>True if item was added.</returns>
    new bool Add(T item);

    /// <summary>
    /// Copy the items of this collection to a contiguous part of an array.
    /// </summary>
    /// <param name="array">The array to copy to</param>
    /// <param name="index">The index at which to copy the first item</param>
    new void CopyTo(T[] array, int index);

    /// <summary>
    /// The unordered collection hashcode is defined as the sum of 
    /// <code>h(hashcode(item))</code> over the items
    /// of the collection, where the function <code>h</code> is a function from 
    /// int to int of the form <code> t -> (a0*t+b0)^(a1*t+b1)^(a2*t+b2)</code>, where 
    /// the ax and bx are the same for all collection classes. 
    /// <para>The current implementation uses fixed values for the ax and bx, 
    /// specified as constants in the code.</para>
    /// </summary>
    /// <returns>The unordered hashcode of this collection.</returns>
    int GetUnsequencedHashCode();


    /// <summary>
    /// Compare the contents of this collection to another one without regards to
    /// the sequence order. The comparison will use this collection's itemequalityComparer
    /// to compare individual items.
    /// </summary>
    /// <param name="otherCollection">The collection to compare to.</param>
    /// <returns>True if this collection and that contains the same items.</returns>
    bool UnsequencedEquals(ICollection<T> otherCollection);


    /// <summary>
    /// Check if this collection contains (an item equivalent to according to the
    /// itemequalityComparer) a particular value.
    /// </summary>
    /// <param name="item">The value to check for.</param>
    /// <returns>True if the items is in this collection.</returns>
    new bool Contains(T item);


    /// <summary>
    /// Count the number of items of the collection equal to a particular value.
    /// Returns 0 if and only if the value is not in the collection.
    /// </summary>
    /// <param name="item">The value to count.</param>
    /// <returns>The number of copies found.</returns>
    int ContainsCount(T item);


    /// <summary>
    /// 
    /// </summary>
    /// <returns></returns>
    ICollectionValue<T> UniqueItems();

    /// <summary>
    /// 
    /// </summary>
    /// <returns></returns>
    ICollectionValue<KeyValuePair<T, int>> ItemMultiplicities();

    /// <summary>
    /// Check whether this collection contains all the values in another collection.
    /// If this collection has bag semantics (<code>AllowsDuplicates==true</code>)
    /// the check is made with respect to multiplicities, else multiplicities
    /// are not taken into account.
    /// </summary>
    /// <param name="items">The </param>
    /// <typeparam name="U"></typeparam>
    /// <returns>True if all values in <code>items</code>is in this collection.</returns>
    bool ContainsAll<U>(SCG.IEnumerable<U> items) where U : T;


    /// <summary>
    /// Check if this collection contains an item equivalent according to the
    /// itemequalityComparer to a particular value. If so, return in the ref argument (a
    /// binary copy of) the actual value found.
    /// </summary>
    /// <param name="item">The value to look for.</param>
    /// <returns>True if the items is in this collection.</returns>
    bool Find(ref T item);


    //This should probably just be bool Add(ref T item); !!!
    /// <summary>
    /// Check if this collection contains an item equivalent according to the
    /// itemequalityComparer to a particular value. If so, return in the ref argument (a
    /// binary copy of) the actual value found. Else, add the item to the collection.
    /// </summary>
    /// <param name="item">The value to look for.</param>
    /// <returns>True if the item was found (hence not added).</returns>
    bool FindOrAdd(ref T item);


    /// <summary>
    /// Check if this collection contains an item equivalent according to the
    /// itemequalityComparer to a particular value. If so, update the item in the collection 
    /// with a (binary copy of) the supplied value. If the collection has bag semantics,
    /// it depends on the value of DuplicatesByCounting if this updates all equivalent copies in
    /// the collection or just one.
    /// </summary>
    /// <param name="item">Value to update.</param>
    /// <returns>True if the item was found and hence updated.</returns>
    bool Update(T item);

    /// <summary>
    /// Check if this collection contains an item equivalent according to the
    /// itemequalityComparer to a particular value. If so, update the item in the collection 
    /// with a (binary copy of) the supplied value. If the collection has bag semantics,
    /// it depends on the value of DuplicatesByCounting if this updates all equivalent copies in
    /// the collection or just one.
    /// </summary>
    /// <param name="item">Value to update.</param>
    /// <param name="olditem">On output the olditem, if found.</param>
    /// <returns>True if the item was found and hence updated.</returns>
    bool Update(T item, out T olditem);


    /// <summary>
    /// Check if this collection contains an item equivalent according to the
    /// itemequalityComparer to a particular value. If so, update the item in the collection 
    /// to with a binary copy of the supplied value; else add the value to the collection. 
    /// </summary>
    /// <param name="item">Value to add or update.</param>
    /// <returns>True if the item was found and updated (hence not added).</returns>
    bool UpdateOrAdd(T item);


    /// <summary>
    /// Check if this collection contains an item equivalent according to the
    /// itemequalityComparer to a particular value. If so, update the item in the collection 
    /// to with a binary copy of the supplied value; else add the value to the collection. 
    /// </summary>
    /// <param name="item">Value to add or update.</param>
    /// <param name="olditem">On output the olditem, if found.</param>
    /// <returns>True if the item was found and updated (hence not added).</returns>
    bool UpdateOrAdd(T item, out T olditem);

    /// <summary>
    /// Remove a particular item from this collection. If the collection has bag
    /// semantics only one copy equivalent to the supplied item is removed. 
    /// </summary>
    /// <param name="item">The value to remove.</param>
    /// <returns>True if the item was found (and removed).</returns>
    new bool Remove(T item);


    /// <summary>
    /// Remove a particular item from this collection if found. If the collection
    /// has bag semantics only one copy equivalent to the supplied item is removed,
    /// which one is implementation dependent. 
    /// If an item was removed, report a binary copy of the actual item removed in 
    /// the argument.
    /// </summary>
    /// <param name="item">The value to remove.</param>
    /// <param name="removeditem">The value removed if any.</param>
    /// <returns>True if the item was found (and removed).</returns>
    bool Remove(T item, out T removeditem);


    /// <summary>
    /// Remove all items equivalent to a given value.
    /// </summary>
    /// <param name="item">The value to remove.</param>
    void RemoveAllCopies(T item);


    /// <summary>
    /// Remove all items in another collection from this one. If this collection
    /// has bag semantics, take multiplicities into account.
    /// </summary>
    /// <typeparam name="U"></typeparam>
    /// <param name="items">The items to remove.</param>
    void RemoveAll<U>(SCG.IEnumerable<U> items) where U : T;

    //void RemoveAll(Fun<T, bool> predicate);

    /// <summary>
    /// Remove all items from this collection.
    /// </summary>
    new void Clear();


    /// <summary>
    /// Remove all items not in some other collection from this one. If this collection
    /// has bag semantics, take multiplicities into account.
    /// </summary>
    /// <typeparam name="U"></typeparam>
    /// <param name="items">The items to retain.</param>
    void RetainAll<U>(SCG.IEnumerable<U> items) where U : T;

    //void RetainAll(Fun<T, bool> predicate);
    //IDictionary<T> UniqueItems()
  }



  /// <summary>
  /// An editable collection maintaining a definite sequence order of the items.
  ///
  /// <i>Implementations of this interface must compute the hash code and 
  /// equality exactly as prescribed in the method definitions in order to
  /// be consistent with other collection classes implementing this interface.</i>
  /// <i>This interface is usually implemented by explicit interface implementation,
  /// not as ordinary virtual methods.</i>
  /// </summary>
  public interface ISequenced<T> : ICollection<T>, IDirectedCollectionValue<T>
  {
    /// <summary>
    /// The hashcode is defined as <code>h(...h(h(h(x1),x2),x3),...,xn)</code> for
    /// <code>h(a,b)=CONSTANT*a+b</code> and the x's the hash codes of the items of 
    /// this collection.
    /// </summary>
    /// <returns>The sequence order hashcode of this collection.</returns>
    int GetSequencedHashCode();


    /// <summary>
    /// Compare this sequenced collection to another one in sequence order.
    /// </summary>
    /// <param name="otherCollection">The sequenced collection to compare to.</param>
    /// <returns>True if this collection and that contains equal (according to
    /// this collection's itemequalityComparer) in the same sequence order.</returns>
    bool SequencedEquals(ISequenced<T> otherCollection);
  }



  /// <summary>
  /// A sequenced collection, where indices of items in the order are maintained
  /// </summary>
  public interface IIndexed<T> : ISequenced<T>
  {
    /// <summary>
    /// </summary>
    /// <exception cref="IndexOutOfRangeException"> if <code>index</code> is negative or
    /// &gt;= the size of the collection.</exception>
    /// <value>The <code>index</code>'th item of this list.</value>
    /// <param name="index">the index to lookup</param>
    T this[int index] { get;}

    /// <summary>
    /// 
    /// </summary>
    /// <value></value>
    Speed IndexingSpeed { get;}

    /// <summary>
    /// </summary>
    /// <exception cref="ArgumentOutOfRangeException"></exception>
    /// <value>The directed collection of items in a specific index interval.</value>
    /// <param name="start">The low index of the interval (inclusive).</param>
    /// <param name="count">The size of the range.</param>
    IDirectedCollectionValue<T> this[int start, int count] { get;}


    /// <summary>
    /// Searches for an item in the list going forwards from the start. 
    /// </summary>
    /// <param name="item">Item to search for.</param>
    /// <returns>Index of item from start. A negative number if item not found, 
    /// namely the one's complement of the index at which the Add operation would put the item.</returns>
    int IndexOf(T item);


    /// <summary>
    /// Searches for an item in the list going backwards from the end.
    /// </summary>
    /// <param name="item">Item to search for.</param>
    /// <returns>Index of of item from the end. A negative number if item not found, 
    /// namely the two-complement of the index at which the Add operation would put the item.</returns>
    int LastIndexOf(T item);

    /// <summary>
    /// Check if there exists an item  that satisfies a
    /// specific predicate in this collection and return the index of the first one.
    /// </summary>
    /// <param name="predicate">A delegate 
    /// (<see cref="T:C5.Fun`2"/> with <code>R == bool</code>) defining the predicate</param>
    /// <returns>the index, if found, a negative value else</returns>
    int FindIndex(Fun<T, bool> predicate);

    /// <summary>
    /// Check if there exists an item  that satisfies a
    /// specific predicate in this collection and return the index of the last one.
    /// </summary>
    /// <param name="predicate">A delegate 
    /// (<see cref="T:C5.Fun`2"/> with <code>R == bool</code>) defining the predicate</param>
    /// <returns>the index, if found, a negative value else</returns>
    int FindLastIndex(Fun<T, bool> predicate);


    /// <summary>
    /// Remove the item at a specific position of the list.
    /// </summary>
    /// <exception cref="IndexOutOfRangeException"> if <code>index</code> is negative or
    /// &gt;= the size of the collection.</exception>
    /// <param name="index">The index of the item to remove.</param>
    /// <returns>The removed item.</returns>
    T RemoveAt(int index);


    /// <summary>
    /// Remove all items in an index interval.
    /// </summary>
    /// <exception cref="ArgumentOutOfRangeException"> if start or count 
    /// is negative or start+count &gt; the size of the collection.</exception>
    /// <param name="start">The index of the first item to remove.</param>
    /// <param name="count">The number of items to remove.</param>
    void RemoveInterval(int start, int count);
  }

  //TODO: decide if this should extend ICollection
  /// <summary>
  /// The interface describing the operations of a LIFO stack data structure.
  /// </summary>
  /// <typeparam name="T">The item type</typeparam>
  public interface IStack<T> : IDirectedCollectionValue<T>
  {
    /// <summary>
    /// 
    /// </summary>
    /// <value></value>
    bool AllowsDuplicates { get;}
    /// <summary>
    /// Get the <code>index</code>'th element of the stack.  The bottom of the stack has index 0.
    /// </summary>
    /// <param name="index"></param>
    /// <returns></returns>
    T this[int index] { get;}
    /// <summary>
    /// Push an item to the top of the stack.
    /// </summary>
    /// <param name="item">The item</param>
    void Push(T item);
    /// <summary>
    /// Pop the item at the top of the stack from the stack.
    /// </summary>
    /// <returns>The popped item.</returns>
    T Pop();
  }

  /// <summary>
  /// The interface describing the operations of a FIFO queue data structure.
  /// </summary>
  /// <typeparam name="T">The item type</typeparam>
  public interface IQueue<T> : IDirectedCollectionValue<T>
  {
    /// <summary>
    /// 
    /// </summary>
    /// <value></value>
    bool AllowsDuplicates { get;}
    /// <summary>
    /// Get the <code>index</code>'th element of the queue.  The front of the queue has index 0.
    /// </summary>
    /// <param name="index"></param>
    /// <returns></returns>
    T this[int index] { get;}
    /// <summary>
    /// Enqueue an item at the back of the queue. 
    /// </summary>
    /// <param name="item">The item</param>
    void Enqueue(T item);
    /// <summary>
    /// Dequeue an item from the front of the queue.
    /// </summary>
    /// <returns>The item</returns>
    T Dequeue();
  }


  /// <summary>
  /// This is an indexed collection, where the item order is chosen by 
  /// the user at insertion time.
  ///
  /// NBNBNB: we need a description of the view functionality here!
  /// </summary>
  public interface IList<T> : IIndexed<T>, IDisposable, SCG.IList<T>, System.Collections.IList
  {
    /// <summary>
    /// </summary>
    /// <exception cref="NoSuchItemException"> if this list is empty.</exception>
    /// <value>The first item in this list.</value>
    T First { get;}

    /// <summary>
    /// </summary>
    /// <exception cref="NoSuchItemException"> if this list is empty.</exception>
    /// <value>The last item in this list.</value>
    T Last { get;}

    /// <summary>
    /// Since <code>Add(T item)</code> always add at the end of the list,
    /// this describes if list has FIFO or LIFO semantics.
    /// </summary>
    /// <value>True if the <code>Remove()</code> operation removes from the
    /// start of the list, false if it removes from the end.</value>
    bool FIFO { get; set;}

    /// <summary>
    /// 
    /// </summary>
    bool IsFixedSize { get; }

    /// <summary>
    /// On this list, this indexer is read/write.
    /// </summary>
    /// <exception cref="IndexOutOfRangeException"> if index is negative or
    /// &gt;= the size of the collection.</exception>
    /// <value>The index'th item of this list.</value>
    /// <param name="index">The index of the item to fetch or store.</param>
    new T this[int index] { get; set;}

    #region Ambiguous calls when extending SCG.IList<T>

    #region SCG.ICollection<T>
    /// <summary>
    /// 
    /// </summary>
    new int Count { get; }

    /// <summary>
    /// 
    /// </summary>
    new bool IsReadOnly { get; }

    /// <summary>
    /// 
    /// </summary>
    /// <param name="item"></param>
    /// <returns></returns>
    new bool Add(T item);

    /// <summary>
    /// 
    /// </summary>
    new void Clear();

    /// <summary>
    /// 
    /// </summary>
    /// <param name="item"></param>
    /// <returns></returns>
    new bool Contains(T item);

    /// <summary>
    /// 
    /// </summary>
    /// <param name="array"></param>
    /// <param name="index"></param>
    new void CopyTo(T[] array, int index);

    /// <summary>
    /// 
    /// </summary>
    /// <param name="item"></param>
    /// <returns></returns>
    new bool Remove(T item);

    #endregion

    #region SCG.IList<T> proper

    /// <summary>
    /// Searches for an item in the list going forwards from the start. 
    /// </summary>
    /// <param name="item">Item to search for.</param>
    /// <returns>Index of item from start. A negative number if item not found, 
    /// namely the one's complement of the index at which the Add operation would put the item.</returns>
    new int IndexOf(T item);

    /// <summary>
    /// Remove the item at a specific position of the list.
    /// </summary>
    /// <exception cref="IndexOutOfRangeException"> if <code>index</code> is negative or
    /// &gt;= the size of the collection.</exception>
    /// <param name="index">The index of the item to remove.</param>
    /// <returns>The removed item.</returns>
    new T RemoveAt(int index);

    #endregion

    #endregion

    /*/// <summary>
    /// Insert an item at a specific index location in this list. 
    /// </summary>
    /// <exception cref="IndexOutOfRangeException"> if <code>index</code> is negative or
    /// &gt; the size of the collection.</exception>
    /// <exception cref="DuplicateNotAllowedException"> if the list has
    /// <code>AllowsDuplicates==false</code> and the item is 
    /// already in the list.</exception>
    /// <param name="index">The index at which to insert.</param>
    /// <param name="item">The item to insert.</param>
    void Insert(int index, T item);*/

    /// <summary>
    /// Insert an item at the end of a compatible view, used as a pointer.
    /// <para>The <code>pointer</code> must be a view on the same list as
    /// <code>this</code> and the endpoitn of <code>pointer</code> must be
    /// a valid insertion point of <code>this</code></para>
    /// </summary>
    /// <exception cref="IncompatibleViewException">If <code>pointer</code> 
    /// is not a view on the same list as <code>this</code></exception>
    /// <exception cref="IndexOutOfRangeException"><b>??????</b> if the endpoint of 
    ///  <code>pointer</code> is not inside <code>this</code></exception>
    /// <exception cref="DuplicateNotAllowedException"> if the list has
    /// <code>AllowsDuplicates==false</code> and the item is 
    /// already in the list.</exception>
    /// <param name="pointer"></param>
    /// <param name="item"></param>
    void Insert(IList<T> pointer, T item);

    /// <summary>
    /// Insert an item at the front of this list.
    /// <exception cref="DuplicateNotAllowedException"/> if the list has
    /// <code>AllowsDuplicates==false</code> and the item is 
    /// already in the list.
    /// </summary>
    /// <param name="item">The item to insert.</param>
    void InsertFirst(T item);

    /// <summary>
    /// Insert an item at the back of this list.
    /// <exception cref="DuplicateNotAllowedException"/> if the list has
    /// <code>AllowsDuplicates==false</code> and the item is 
    /// already in the list.
    /// </summary>
    /// <param name="item">The item to insert.</param>
    void InsertLast(T item);

    /// <summary>
    /// Insert into this list all items from an enumerable collection starting 
    /// at a particular index.
    /// </summary>
    /// <exception cref="IndexOutOfRangeException"> if <code>index</code> is negative or
    /// &gt; the size of the collection.</exception>
    /// <exception cref="DuplicateNotAllowedException"> if the list has 
    /// <code>AllowsDuplicates==false</code> and one of the items to insert is
    /// already in the list.</exception>
    /// <param name="index">Index to start inserting at</param>
    /// <param name="items">Items to insert</param>
    /// <typeparam name="U"></typeparam>
    void InsertAll<U>(int index, SCG.IEnumerable<U> items) where U : T;

    /// <summary>
    /// Create a new list consisting of the items of this list satisfying a 
    /// certain predicate.
    /// </summary>
    /// <param name="filter">The filter delegate defining the predicate.</param>
    /// <returns>The new list.</returns>
    IList<T> FindAll(Fun<T, bool> filter);

    /// <summary>
    /// Create a new list consisting of the results of mapping all items of this
    /// list. The new list will use the default equalityComparer for the item type V.
    /// </summary>
    /// <typeparam name="V">The type of items of the new list</typeparam>
    /// <param name="mapper">The delegate defining the map.</param>
    /// <returns>The new list.</returns>
    IList<V> Map<V>(Fun<T, V> mapper);

    /// <summary>
    /// Create a new list consisting of the results of mapping all items of this
    /// list. The new list will use a specified equalityComparer for the item type.
    /// </summary>
    /// <typeparam name="V">The type of items of the new list</typeparam>
    /// <param name="mapper">The delegate defining the map.</param>
    /// <param name="equalityComparer">The equalityComparer to use for the new list</param>
    /// <returns>The new list.</returns>
    IList<V> Map<V>(Fun<T, V> mapper, SCG.IEqualityComparer<V> equalityComparer);

    /// <summary>
    /// Remove one item from the list: from the front if <code>FIFO</code>
    /// is true, else from the back.
    /// <exception cref="NoSuchItemException"/> if this list is empty.
    /// </summary>
    /// <returns>The removed item.</returns>
    T Remove();

    /// <summary>
    /// Remove one item from the front of the list.
    /// <exception cref="NoSuchItemException"/> if this list is empty.
    /// </summary>
    /// <returns>The removed item.</returns>
    T RemoveFirst();

    /// <summary>
    /// Remove one item from the back of the list.
    /// <exception cref="NoSuchItemException"/> if this list is empty.
    /// </summary>
    /// <returns>The removed item.</returns>
    T RemoveLast();

    /// <summary>
    /// Create a list view on this list. 
    /// <exception cref="ArgumentOutOfRangeException"/> if the view would not fit into
    /// this list.
    /// </summary>
    /// <param name="start">The index in this list of the start of the view.</param>
    /// <param name="count">The size of the view.</param>
    /// <returns>The new list view.</returns>
    IList<T> View(int start, int count);

    /// <summary>
    /// Create a list view on this list containing the (first) occurrence of a particular item. 
    /// <exception cref="NoSuchItemException"/> if the item is not in this list.
    /// </summary>
    /// <param name="item">The item to find.</param>
    /// <returns>The new list view.</returns>
    IList<T> ViewOf(T item);

    /// <summary>
    /// Create a list view on this list containing the last occurrence of a particular item. 
    /// <exception cref="NoSuchItemException"/> if the item is not in this list.
    /// </summary>
    /// <param name="item">The item to find.</param>
    /// <returns>The new list view.</returns>
    IList<T> LastViewOf(T item);

    /// <summary>
    /// Null if this list is not a view.
    /// </summary>
    /// <value>Underlying list for view.</value>
    IList<T> Underlying { get;}

    /// <summary>
    /// </summary>
    /// <value>Offset for this list view or 0 for an underlying list.</value>
    int Offset { get;}

    /// <summary>
    /// 
    /// </summary>
    /// <value></value>
    bool IsValid { get;}

    /// <summary>
    /// Slide this list view along the underlying list.
    /// </summary>
    /// <exception cref="NotAViewException"> if this list is not a view.</exception>
    /// <exception cref="ArgumentOutOfRangeException"> if the operation
    /// would bring either end of the view outside the underlying list.</exception>
    /// <param name="offset">The signed amount to slide: positive to slide
    /// towards the end.</param>
    IList<T> Slide(int offset);

    /// <summary>
    /// Slide this list view along the underlying list, changing its size.
    /// 
    /// </summary>
    /// <exception cref="NotAViewException"> if this list is not a view.</exception>
    /// <exception cref="ArgumentOutOfRangeException"> if the operation
    /// would bring either end of the view outside the underlying list.</exception>
    /// <param name="offset">The signed amount to slide: positive to slide
    /// towards the end.</param>
    /// <param name="size">The new size of the view.</param>
    IList<T> Slide(int offset, int size);

    /// <summary>
    /// 
    /// </summary>
    /// <param name="offset"></param>
    /// <returns></returns>
    bool TrySlide(int offset);

    /// <summary>
    /// 
    /// </summary>
    /// <param name="offset"></param>
    /// <param name="size"></param>
    /// <returns></returns>
    bool TrySlide(int offset, int size);

    /// <summary>
    /// 
    /// <para>Returns null if <code>otherView</code> is strictly to the left of this view</para>
    /// </summary>
    /// <param name="otherView"></param>
    /// <exception cref="IncompatibleViewException">If otherView does not have the same underlying list as this</exception>
    /// <exception cref="ArgumentOutOfRangeException">If <code>otherView</code> is strictly to the left of this view</exception>
    /// <returns></returns>
    IList<T> Span(IList<T> otherView);

    /// <summary>
    /// Reverse the list so the items are in the opposite sequence order.
    /// </summary>
    void Reverse();

    /// <summary>
    /// Check if this list is sorted according to the default sorting order
    /// for the item type T, as defined by the <see cref="T:C5.Comparer`1"/> class 
    /// </summary>
    /// <exception cref="NotComparableException">if T is not comparable</exception>
    /// <returns>True if the list is sorted, else false.</returns>
    bool IsSorted();

    /// <summary>
    /// Check if this list is sorted according to a specific sorting order.
    /// </summary>
    /// <param name="comparer">The comparer defining the sorting order.</param>
    /// <returns>True if the list is sorted, else false.</returns>
    bool IsSorted(SCG.IComparer<T> comparer);

    /// <summary>
    /// Sort the items of the list according to the default sorting order
    /// for the item type T, as defined by the <see cref="T:C5.Comparer`1"/> class 
    /// </summary>
    /// <exception cref="NotComparableException">if T is not comparable</exception>
    void Sort();

    /// <summary>
    /// Sort the items of the list according to a specified sorting order.
    /// <para>The sorting does not perform duplicate elimination or identify items
    /// according to the comparer or itemequalityComparer. I.e. the list as an 
    /// unsequenced collection with binary equality, will not change.
    /// </para>
    /// </summary>
    /// <param name="comparer">The comparer defining the sorting order.</param>
    void Sort(SCG.IComparer<T> comparer);


    /// <summary>
    /// Randomly shuffle the items of this list. 
    /// </summary>
    void Shuffle();


    /// <summary>
    /// Shuffle the items of this list according to a specific random source.
    /// </summary>
    /// <param name="rnd">The random source.</param>
    void Shuffle(Random rnd);
  }


  /// <summary>
  /// The base type of a priority queue handle
  /// </summary>
  /// <typeparam name="T"></typeparam>
  public interface IPriorityQueueHandle<T>
  {
    //TODO: make abstract and prepare for double dispatch:
    //public virtual bool Delete(IPriorityQueue<T> q) { throw new InvalidFooException();}
    //bool Replace(T item);
  }


  /// <summary>
  /// A generic collection of items prioritized by a comparison (order) relation.
  /// Supports adding items and reporting or removing extremal elements. 
  /// <para>
  /// 
  /// </para>
  /// When adding an item, the user may choose to have a handle allocated for this item in the queue. 
  /// The resulting handle may be used for deleting the item even if not extremal, and for replacing the item.
  /// A priority queue typically only holds numeric priorities associated with some objects
  /// maintained separately in other collection objects.
  /// </summary>
  public interface IPriorityQueue<T> : IExtensible<T>
  {
    /// <summary>
    /// Find the current least item of this priority queue.
    /// </summary>
    /// <returns>The least item.</returns>
    T FindMin();


    /// <summary>
    /// Remove the least item from this  priority queue.
    /// </summary>
    /// <returns>The removed item.</returns>
    T DeleteMin();


    /// <summary>
    /// Find the current largest item of this priority queue.
    /// </summary>
    /// <returns>The largest item.</returns>
    T FindMax();


    /// <summary>
    /// Remove the largest item from this priority queue.
    /// </summary>
    /// <returns>The removed item.</returns>
    T DeleteMax();

    /// <summary>
    /// The comparer object supplied at creation time for this collection
    /// </summary>
    /// <value>The comparer</value>
    SCG.IComparer<T> Comparer { get;}
    /// <summary>
    /// Get or set the item corresponding to a handle. Throws exceptions on 
    /// invalid handles.
    /// </summary>
    /// <param name="handle"></param>
    /// <returns></returns>
    T this[IPriorityQueueHandle<T> handle] { get; set;}

    /// <summary>
    /// Check if the entry corresponding to a handle is in the priority queue.
    /// </summary>
    /// <param name="handle"></param>
    /// <param name="item"></param>
    /// <returns></returns>
    bool Find(IPriorityQueueHandle<T> handle, out T item);

    /// <summary>
    /// Add an item to the priority queue, receiving a 
    /// handle for the item in the queue, 
    /// or reusing an existing unused handle.
    /// </summary>
    /// <param name="handle">On output: a handle for the added item. 
    /// On input: null for allocating a new handle, or a currently unused handle for reuse. 
    /// A handle for reuse must be compatible with this priority queue, 
    /// by being created by a priority queue of the same runtime type, but not 
    /// necessarily the same priority queue object.</param>
    /// <param name="item"></param>
    /// <returns></returns>
    bool Add(ref IPriorityQueueHandle<T> handle, T item);

    /// <summary>
    /// Delete an item with a handle from a priority queue
    /// </summary>
    /// <param name="handle">The handle for the item. The handle will be invalidated, but reusable.</param>
    /// <returns>The deleted item</returns>
    T Delete(IPriorityQueueHandle<T> handle);

    /// <summary>
    /// Replace an item with a handle in a priority queue with a new item. 
    /// Typically used for changing the priority of some queued object.
    /// </summary>
    /// <param name="handle">The handle for the old item</param>
    /// <param name="item">The new item</param>
    /// <returns>The old item</returns>
    T Replace(IPriorityQueueHandle<T> handle, T item);

    /// <summary>
    /// Find the current least item of this priority queue.
    /// </summary>
    /// <param name="handle">On return: the handle of the item.</param>
    /// <returns>The least item.</returns>
    T FindMin(out IPriorityQueueHandle<T> handle);

    /// <summary>
    /// Find the current largest item of this priority queue.
    /// </summary>
    /// <param name="handle">On return: the handle of the item.</param>
    /// <returns>The largest item.</returns>

    T FindMax(out IPriorityQueueHandle<T> handle);

    /// <summary>
    /// Remove the least item from this  priority queue.
    /// </summary>
    /// <param name="handle">On return: the handle of the removed item.</param>
    /// <returns>The removed item.</returns>

    T DeleteMin(out IPriorityQueueHandle<T> handle);

    /// <summary>
    /// Remove the largest item from this  priority queue.
    /// </summary>
    /// <param name="handle">On return: the handle of the removed item.</param>
    /// <returns>The removed item.</returns>
    T DeleteMax(out IPriorityQueueHandle<T> handle);
  }



  /// <summary>
  /// A sorted collection, i.e. a collection where items are maintained and can be searched for in sorted order.
  /// Thus the sequence order is given as a sorting order.
  /// 
  /// <para>The sorting order is defined by a comparer, an object of type IComparer&lt;T&gt; 
  /// (<see cref="T:C5.IComparer`1"/>). Implementors of this interface will normally let the user 
  /// define the comparer as an argument to a constructor. 
  /// Usually there will also be constructors without a comparer argument, in which case the 
  /// comparer should be the defalt comparer for the item type, <see cref="P:C5.Comparer`1.Default"/>.</para>
  /// 
  /// <para>The comparer of the sorted collection is available as the <code>Comparer</code> property 
  /// (<see cref="P:C5.ISorted`1.Comparer"/>).</para>
  /// 
  /// <para>The methods are grouped according to
  /// <list>
  /// <item>Extrema: report or report and delete an extremal item. This is reminiscent of simplified priority queues.</item>
  /// <item>Nearest neighbor: report predecessor or successor in the collection of an item. Cut belongs to this group.</item>
  /// <item>Range: report a view of a range of elements or remove all elements in a range.</item>
  /// <item>AddSorted: add a collection of items known to be sorted in the same order (should be faster) (to be removed?)</item>
  /// </list>
  /// </para>
  /// 
  /// <para>Since this interface extends ISequenced&lt;T&gt;, sorted collections will also have an 
  /// item equalityComparer (<see cref="P:C5.IExtensible`1.EqualityComparer"/>). This equalityComparer will not be used in connection with 
  /// the inner workings of the sorted collection, but will be used if the sorted collection is used as 
  /// an item in a collection of unsequenced or sequenced collections, 
  /// (<see cref="T:C5.ICollection`1"/> and <see cref="T:C5.ISequenced`1"/>)</para>
  /// 
  /// <para>Note that code may check if two sorted collections has the same sorting order 
  /// by checking if the Comparer properties are equal. This is done a few places in this library
  /// for optimization purposes.</para>
  /// </summary>
  public interface ISorted<T> : ISequenced<T>
  {
    /// <summary>
    /// Find the current least item of this sorted collection.
    /// </summary>
    /// <exception cref="NoSuchItemException"> if the collection is empty.</exception>
    /// <returns>The least item.</returns>
    T FindMin();


    /// <summary>
    /// Remove the least item from this sorted collection.
    /// </summary>
    /// <exception cref="NoSuchItemException"> if the collection is empty.</exception>
    /// <returns>The removed item.</returns>
    T DeleteMin();


    /// <summary>
    /// Find the current largest item of this sorted collection.
    /// </summary>
    /// <exception cref="NoSuchItemException"> if the collection is empty.</exception>
    /// <returns>The largest item.</returns>
    T FindMax();


    /// <summary>
    /// Remove the largest item from this sorted collection.
    /// </summary>
    /// <exception cref="NoSuchItemException"> if the collection is empty.</exception>
    /// <returns>The removed item.</returns>
    T DeleteMax();

    /// <summary>
    /// The comparer object supplied at creation time for this sorted collection.
    /// </summary>
    /// <value>The comparer</value>
    SCG.IComparer<T> Comparer { get; }

    /// <summary>
    /// Find the strict predecessor of item in the sorted collection,
    /// that is, the greatest item in the collection smaller than the item.
    /// </summary>
    /// <param name="item">The item to find the predecessor for.</param>
    /// <param name="res">The predecessor, if any; otherwise the default value for T.</param>
    /// <returns>True if item has a predecessor; otherwise false.</returns>
    bool TryPredecessor(T item, out T res);


    /// <summary>
    /// Find the strict successor of item in the sorted collection,
    /// that is, the least item in the collection greater than the supplied value.
    /// </summary>
    /// <param name="item">The item to find the successor for.</param>
    /// <param name="res">The successor, if any; otherwise the default value for T.</param>
    /// <returns>True …

Large files files are truncated, but you can click here to view the full file