using System.Collections.Generic;

namespace Chernobyl.Collections.Generic
{
    /// <summary>
    /// An <see cref="IEnumerable{T}"/> type for types that are structured 
    /// like the node in a linked list where the type holds an instance of it's 
    /// own type. For example:
    /// <code>
    /// public class Foobar : ILinkedEnumerable{Foobar}
    /// {
    ///     public Foobar NextFoo { get; set; }
    /// 
    ///     public IEnumerator{T} GetLinkedEnumerator()
    ///     {
    ///         return new LinkedEnumerator{Foobar}(this, LinkedNextItem);
    ///     }
    /// 
    ///     public IEnumerator{IResourceProcessor{TResource}} GetEnumerator()
    ///     {
    ///         return GetLinkedEnumerator();
    ///     }
    /// 
    ///     IEnumerator IEnumerable.GetEnumerator()
    ///     {
    ///         return GetEnumerator();
    ///     }
    ///     
    ///     static bool LinkedNextItem(T current, out T next)
    ///     {
    ///         next = current.NextFoo;
    ///         return next != null;
    ///     }
    /// }
    /// </code>
    /// This type allows client code to use LINQ operations on linked instances.
    /// </summary>
    /// <typeparam name="T">The type that contains an instance of it's 
    /// own type (a class that acts as a node in a linked list).</typeparam>
    public interface ILinkedEnumerable<T> : IEnumerable<T>
    {
        /// <summary>
        /// Returns an enumerator that iterates through a linked set of instances.
        /// </summary>
        /// <returns>The <see cref="IEnumerator{T}"/> that allows iteration over 
        /// a set of linked instance.</returns>
        IEnumerator<T> GetLinkedEnumerator();
    }
}