stream.swift

/// A type that provides sequential access to generated elements.
///
/// A stream represents an infinite number of data elements made
/// available over time. The data may be algorithmic or random.
/// The most common way to access is to request one or more
/// elements from the stream.
///
/// This capability enables you to perform shared operations that
/// work on any stream.
///
/// Conforming to the Stream Protocol
/// =================================
///
/// Making your own custom types conform to `Stream` enables access to
/// several useful operations without much effort. Just bake in `next()`
/// and the magic happens for `FIXME`, `FIXME`, and `FIXME`.
///
public protocol Stream {
    
    /// A type representing the stream's elements.
    associatedtype Element where Self.Element == Self.Iterator.Element
    
    /// A type that provides the stream's infinite iteration interface
    /// and encapsulates its iteration state.
    associatedtype Iterator : IteratorProtocol
    
    /// Returns an iterator over the elements of this sequence.
    func makeIterator() -> Self.Iterator

    /// I have removed 'Map' here but there has to be some
    /// kind of additive transformation. It may not belong
    /// to this protocol however.

    /// Fetches elements until a predicate is satisfied.
    /// By default, the satisfying element is considered a
    /// separator and is not included in the return array.
    func fetchUntil(_ predicate: (Self.Element) throws -> Bool, includeSeparator: Bool) rethrows -> [Self.Element]
    
    /// Fetches elements until a predicate is satisfied
    /// with respect to the already fetched elements.
    func fetchUntil(_ predicate: ([Self.Element]) throws -> Bool) rethrows -> [Self.Element]
    
    /// Return the first n elements (defaulting to 1) that
    /// satisfy the filter, discarding all elements that do
    /// not satisfy the supplied predicate. An infinite
    /// stream may not include any or enough satisfying elements
    /// so unless you filter responsibly, you may end up waiting
    /// indefinitely for a non-stopping result.
    func filteredFetch(count: Int, _ isIncluded: (Self.Element) throws -> Bool) rethrows -> Self.Element
    
    /// Return an array of n elements fetched from the stream.
    func fetch(_ n: Int) -> [Self.Element]
    
    /// Possibly some kind of transformative fetch?
    // public func fetch<T>(_ n: Int, _ transform: (Self.Element) -> T = { _ in $0 }) -> [T]
 }