Coverage Report

Coverage Report - jaggregate.GettableStream

Classes in this File

 /*
  Copyright 2004-2008 Paul R. Holser, Jr.  All rights reserved.
  Licensed under the Academic Free License version 3.0
  */
 
 package jaggregate;
 
 /**
  * Provides protocol for a stream that can read objects from its <dfn>future sequence
  * values</dfn>.
  *
  * @param <E> the type of elements in the stream
  * @param <S> the type of the backing store
  * @author <a href="mailto:pholser@alumni.rice.edu">Paul Holser</a>
  * @version $Id: GettableStream.java,v 1.4 2008/05/08 03:49:37 pholser Exp $
  */
 public interface GettableStream<E, S extends ReadOnlySequence<E>> {
     /**
      * Evaluates the given operation with each of this stream's future sequence values,
      * terminating evaluation when there are no more future sequence values.
      * <p/>
      * Each member of the future sequence values is, in turn, removed from the future
      * sequence values; appended to the past sequence values; and, passed as the
      * argument to an evaluation of {@code operation}.  The number of evaluations is
      * equal to the initial size of the future sequence values.  If initially there are
      * no future sequence values, {@code operation} is not evaluated.  The future
      * sequence values are used as arguments in their sequence order.  The result is
      * undefined if any evaluation of {@code operation} changes the future sequence
      * values.
      *
      * @param <R> a constraint on the return type of the operation
      * @param operation the operation to evaluate
      * @throws NullPointerException if {@code operation} is {@code null}
      */
     <R> void forEachDo( UnaryFunctor<? super E, ? extends R> operation );
 
     /**
      * Answers the next object in this stream.
      * <p/>
      * The first object is removed from the future sequence values and appended to the
      * end of the past sequence values, and returned as the result of the message.
      *
      * @return the next object in this stream
      * @throws java.util.NoSuchElementException if this stream has no future sequence
      * values
      */
     E next();
 
     /**
      * Answers a collection of the next given number of objects in this stream.
      * <p/>
      * A number of objects equal to {@code amount} are removed from the future sequence
      * values and appended, in order, to the end of the past sequence values.
      * A collection whose elements consist of those objects, in the same order,
      * is returned.  If {@code amount == 0}, an empty collection is returned.
      *
      * @param amount the number of objects to enumerate
      * @return a sequence consisting of the enumerated objects
      * @throws IllegalArgumentException if {@code amount < 0} or {@code amount >} the
      * number of objects in this stream's future sequence values
      */
     S next( int amount );
 
     /**
      * Reads the next object from this stream and tells whether the object is
      * {@linkplain Object#equals(Object) equivalent} to the given target.
      * <p/>
      * The first object is removed from the future sequence values and appended to the
      * past sequence values, regardless of the result of the comparison to
      * {@code target}.
      *
      * @param target the object against which to compare the next object from this
      * stream
      * @return {@code true} if the next object is equivalent to {@code target};
      * {@code false} otherwise
      * @throws java.util.NoSuchElementException if there are no future sequence values
      * in this stream
      */
     boolean isNextMatchFor( E target );
 
     /**
      * Answers the next object in this stream without advancing this stream's position.
      * <p/>
      * Answers the first object in the future sequence values without removing it from
      * the future sequence values.  Answers {@code null} if this stream has no future
      * sequence values.  The answer will also be {@code null} if the first future
      * sequence value is {@code null}.
      *
      * @return the next object in this stream
      */
     E peek();
 
     /**
      * Peeks at the next object in this stream and tells whether it is
      * {@linkplain Object#equals(Object) equivalent} to the given target.
      *
      * @param target the object to match against
      * @return {@code true} if the first object in this stream's future sequence values
      * is equivalent to {@code target}, otherwise {@code false}
      */
     boolean isPeekMatchFor( E target );
 
     /**
      * Skips the next given number of objects in this stream's future sequence values.
      * <p/>
      * A number of objects equal to the lesser of {@code amount} and the size of the
      * future sequence values are removed from the future sequence values and appended,
      * in order, to the end of the past sequence values.
      *
      * @param amount the number of objects to skip
      * @throws IllegalArgumentException if {@code amount < 0}
      */
     void skip( int amount );
 
     /**
      * Sets this stream to read the object just after the next occurrence of the given
      * target and answers {@code true}.  If {@code target} is not found before the end
      * of this stream is encountered, answers {@code false}.
      * <p/>
      * Each object in the future sequence values up to and including the first
      * occurrence of an object that is {@linkplain Object#equals(Object) equivalent} to
      * {@code target} is removed from the future sequence values and appended to the
      * past sequence values.  If an object that is equivalent to {@code target} is not
      * found in the future sequence values, all of the objects in the future sequence
      * values are so appended.
      *
      * @param target the object to skip to
      * @return {@code true} if {@code target} could be found, otherwise {@code false}
      */
     boolean skipTo( E target );
 
     /**
      * Answers a collection of all of the objects in this stream up to, but not
      * including, the next occurrence of the given target.  Sets this stream to read the
      * object just after the next occurrence of {@code target}.  If {@code target} is
      * not found and the end of this stream is encountered, a collection of the objects
      * read is returned.
      * <p/>
      * Each object in the future sequence values up to and including the first
      * occurrence of an object that is {@linkplain Object#equals(Object) equivalent}
      * to {@code target} is removed from the future sequence values and appended to the
      * past sequence values.  A collection, containing, in order, all of the transferred
      * objects except the object (if any) that is equivalent to {@code target}
      * is returned.  If the future sequence values is initially empty, an empty
      * collection is returned.
      *
      * @param target the object to seek
      * @return a sequence as specified above
      */
     S upTo( E target );
 }

1		/*
2		Copyright 2004-2008 Paul R. Holser, Jr. All rights reserved.
3		Licensed under the Academic Free License version 3.0
4		*/
5
6		package jaggregate;
7
8		/**
9		* Provides protocol for a stream that can read objects from its <dfn>future sequence
10		* values</dfn>.
11		*
12		* @param <E> the type of elements in the stream
13		* @param <S> the type of the backing store
14		* @author <a href="mailto:pholser@alumni.rice.edu">Paul Holser</a>
15		* @version $Id: GettableStream.java,v 1.4 2008/05/08 03:49:37 pholser Exp $
16		*/
17		public interface GettableStream<E, S extends ReadOnlySequence<E>> {
18		/**
19		* Evaluates the given operation with each of this stream's future sequence values,
20		* terminating evaluation when there are no more future sequence values.
21		* <p/>
22		* Each member of the future sequence values is, in turn, removed from the future
23		* sequence values; appended to the past sequence values; and, passed as the
24		* argument to an evaluation of {@code operation}. The number of evaluations is
25		* equal to the initial size of the future sequence values. If initially there are
26		* no future sequence values, {@code operation} is not evaluated. The future
27		* sequence values are used as arguments in their sequence order. The result is
28		* undefined if any evaluation of {@code operation} changes the future sequence
29		* values.
30		*
31		* @param <R> a constraint on the return type of the operation
32		* @param operation the operation to evaluate
33		* @throws NullPointerException if {@code operation} is {@code null}
34		*/
35		<R> void forEachDo( UnaryFunctor<? super E, ? extends R> operation );
36
37		/**
38		* Answers the next object in this stream.
39		* <p/>
40		* The first object is removed from the future sequence values and appended to the
41		* end of the past sequence values, and returned as the result of the message.
42		*
43		* @return the next object in this stream
44		* @throws java.util.NoSuchElementException if this stream has no future sequence
45		* values
46		*/
47		E next();
48
49		/**
50		* Answers a collection of the next given number of objects in this stream.
51		* <p/>
52		* A number of objects equal to {@code amount} are removed from the future sequence
53		* values and appended, in order, to the end of the past sequence values.
54		* A collection whose elements consist of those objects, in the same order,
55		* is returned. If {@code amount == 0}, an empty collection is returned.
56		*
57		* @param amount the number of objects to enumerate
58		* @return a sequence consisting of the enumerated objects
59		* @throws IllegalArgumentException if {@code amount < 0} or {@code amount >} the
60		* number of objects in this stream's future sequence values
61		*/
62		S next( int amount );
63
64		/**
65		* Reads the next object from this stream and tells whether the object is
66		* {@linkplain Object#equals(Object) equivalent} to the given target.
67		* <p/>
68		* The first object is removed from the future sequence values and appended to the
69		* past sequence values, regardless of the result of the comparison to
70		* {@code target}.
71		*
72		* @param target the object against which to compare the next object from this
73		* stream
74		* @return {@code true} if the next object is equivalent to {@code target};
75		* {@code false} otherwise
76		* @throws java.util.NoSuchElementException if there are no future sequence values
77		* in this stream
78		*/
79		boolean isNextMatchFor( E target );
80
81		/**
82		* Answers the next object in this stream without advancing this stream's position.
83		* <p/>
84		* Answers the first object in the future sequence values without removing it from
85		* the future sequence values. Answers {@code null} if this stream has no future
86		* sequence values. The answer will also be {@code null} if the first future
87		* sequence value is {@code null}.
88		*
89		* @return the next object in this stream
90		*/
91		E peek();
92
93		/**
94		* Peeks at the next object in this stream and tells whether it is
95		* {@linkplain Object#equals(Object) equivalent} to the given target.
96		*
97		* @param target the object to match against
98		* @return {@code true} if the first object in this stream's future sequence values
99		* is equivalent to {@code target}, otherwise {@code false}
100		*/
101		boolean isPeekMatchFor( E target );
102
103		/**
104		* Skips the next given number of objects in this stream's future sequence values.
105		* <p/>
106		* A number of objects equal to the lesser of {@code amount} and the size of the
107		* future sequence values are removed from the future sequence values and appended,
108		* in order, to the end of the past sequence values.
109		*
110		* @param amount the number of objects to skip
111		* @throws IllegalArgumentException if {@code amount < 0}
112		*/
113		void skip( int amount );
114
115		/**
116		* Sets this stream to read the object just after the next occurrence of the given
117		* target and answers {@code true}. If {@code target} is not found before the end
118		* of this stream is encountered, answers {@code false}.
119		* <p/>
120		* Each object in the future sequence values up to and including the first
121		* occurrence of an object that is {@linkplain Object#equals(Object) equivalent} to
122		* {@code target} is removed from the future sequence values and appended to the
123		* past sequence values. If an object that is equivalent to {@code target} is not
124		* found in the future sequence values, all of the objects in the future sequence
125		* values are so appended.
126		*
127		* @param target the object to skip to
128		* @return {@code true} if {@code target} could be found, otherwise {@code false}
129		*/
130		boolean skipTo( E target );
131
132		/**
133		* Answers a collection of all of the objects in this stream up to, but not
134		* including, the next occurrence of the given target. Sets this stream to read the
135		* object just after the next occurrence of {@code target}. If {@code target} is
136		* not found and the end of this stream is encountered, a collection of the objects
137		* read is returned.
138		* <p/>
139		* Each object in the future sequence values up to and including the first
140		* occurrence of an object that is {@linkplain Object#equals(Object) equivalent}
141		* to {@code target} is removed from the future sequence values and appended to the
142		* past sequence values. A collection, containing, in order, all of the transferred
143		* objects except the object (if any) that is equivalent to {@code target}
144		* is returned. If the future sequence values is initially empty, an empty
145		* collection is returned.
146		*
147		* @param target the object to seek
148		* @return a sequence as specified above
149		*/
150		S upTo( E target );
151		}