132
|
1 /*
|
|
2 File: SeqView.d
|
|
3
|
|
4 Originally written by Doug Lea and released into the public domain.
|
|
5 Thanks for the assistance and support of Sun Microsystems Labs, Agorics
|
|
6 Inc, Loral, and everyone contributing, testing, and using this code.
|
|
7
|
|
8 History:
|
|
9 Date Who What
|
|
10 24Sep95 dl@cs.oswego.edu Create from collections.d working file
|
|
11
|
|
12 */
|
|
13
|
|
14
|
|
15 module tango.util.collection.model.SeqView;
|
|
16
|
|
17 private import tango.util.collection.model.View;
|
|
18
|
|
19
|
|
20 /**
|
|
21 *
|
|
22 *
|
|
23 * Seqs are indexed, sequentially ordered collections.
|
|
24 * Indices are always in the range 0 .. size() -1. All accesses by index
|
|
25 * are checked, raising exceptions if the index falls out of range.
|
|
26 * <P>
|
|
27 * The elements() enumeration for all seqs is guaranteed to be
|
|
28 * traversed (via nextElement) in sequential order.
|
|
29 *
|
|
30 author: Doug Lea
|
|
31 * @version 0.93
|
|
32 *
|
|
33 * <P> For an introduction to this package see <A HREF="index.html"> Overview </A>.
|
|
34 **/
|
|
35
|
|
36 public interface SeqView(T) : View!(T)
|
|
37 {
|
|
38 /**
|
|
39 * Return the element at the indicated index
|
|
40 * @param index
|
|
41 * Returns: the element at the index
|
|
42 * Throws: NoSuchElementException if index is not in range 0..size()-1
|
|
43 **/
|
|
44
|
|
45 public T get(int index);
|
|
46 public alias get opIndex;
|
|
47
|
|
48
|
|
49 /**
|
|
50 * Return the first element, if it exists.
|
|
51 * Behaviorally equivalent to at(0)
|
|
52 * Throws: NoSuchElementException if isEmpty
|
|
53 **/
|
|
54
|
|
55 public T head();
|
|
56
|
|
57
|
|
58 /**
|
|
59 * Return the last element, if it exists.
|
|
60 * Behaviorally equivalent to at(size()-1)
|
|
61 * Throws: NoSuchElementException if isEmpty
|
|
62 **/
|
|
63
|
|
64 public T tail();
|
|
65
|
|
66
|
|
67 /**
|
|
68 * Report the index of leftmost occurrence of an element from a
|
|
69 * given starting point, or -1 if there is no such index.
|
|
70 * @param element the element to look for
|
|
71 * @param startingIndex the index to start looking from. The startingIndex
|
|
72 * need not be a valid index. If less than zero it is treated as 0.
|
|
73 * If greater than or equal to size(), the result will always be -1.
|
|
74 * Returns: index such that
|
|
75 * <PRE>
|
|
76 * let int si = max(0, startingIndex) in
|
|
77 * index == -1 &&
|
|
78 * foreach (int i in si .. size()-1) !at(index).equals(element)
|
|
79 * ||
|
|
80 * at(index).equals(element) &&
|
|
81 * foreach (int i in si .. index-1) !at(index).equals(element)
|
|
82 * </PRE>
|
|
83 **/
|
|
84
|
|
85 public int first(T element, int startingIndex = 0);
|
|
86
|
|
87 /**
|
|
88 * Report the index of righttmost occurrence of an element from a
|
|
89 * given starting point, or -1 if there is no such index.
|
|
90 * @param element the element to look for
|
|
91 * @param startingIndex the index to start looking from. The startingIndex
|
|
92 * need not be a valid index. If less than zero the result
|
|
93 * will always be -1.
|
|
94 * If greater than or equal to size(), it is treated as size()-1.
|
|
95 * Returns: index such that
|
|
96 * <PRE>
|
|
97 * let int si = min(size()-1, startingIndex) in
|
|
98 * index == -1 &&
|
|
99 * foreach (int i in 0 .. si) !at(index).equals(element)
|
|
100 * ||
|
|
101 * at(index).equals(element) &&
|
|
102 * foreach (int i in index+1 .. si) !at(index).equals(element)
|
|
103 * </PRE>
|
|
104 *
|
|
105 **/
|
|
106 public int last(T element, int startingIndex = 0);
|
|
107
|
|
108
|
|
109 /**
|
|
110 * Construct a new SeqView that is a clone of self except
|
|
111 * that it does not contain the elements before index or
|
|
112 * after index+length. If length is less than or equal to zero,
|
|
113 * return an empty SeqView.
|
|
114 * @param index of the element that will be the 0th index in new SeqView
|
|
115 * @param length the number of elements in the new SeqView
|
|
116 * Returns: new seq such that
|
|
117 * <PRE>
|
|
118 * s.size() == max(0, length) &&
|
|
119 * foreach (int i in 0 .. s.size()-1) s.at(i).equals(at(i+index));
|
|
120 * </PRE>
|
|
121 * Throws: NoSuchElementException if index is not in range 0..size()-1
|
|
122 **/
|
|
123 public SeqView subset(int index, int length);
|
|
124
|
|
125 /**
|
|
126 * Construct a new SeqView that is a clone of self except
|
|
127 * that it does not contain the elements before begin or
|
|
128 * after end-1. If length is less than or equal to zero,
|
|
129 * return an empty SeqView.
|
|
130 * @param index of the element that will be the 0th index in new SeqView
|
|
131 * @param index of the last element in the SeqView plus 1
|
|
132 * Returns: new seq such that
|
|
133 * <PRE>
|
|
134 * s.size() == max(0, length) &&
|
|
135 * foreach (int i in 0 .. s.size()-1) s.at(i).equals(at(i+index));
|
|
136 * </PRE>
|
|
137 * Throws: NoSuchElementException if index is not in range 0..size()-1
|
|
138 **/
|
|
139 public SeqView opSlice(int begin, int end);
|
|
140
|
|
141
|
|
142 version (VERBOSE)
|
|
143 {
|
|
144 /**
|
|
145 * Construct a new SeqView that is a clone of self except
|
|
146 * that it adds (inserts) the indicated element at the
|
|
147 * indicated index.
|
|
148 * @param index the index at which the new element will be placed
|
|
149 * @param element The element to insert in the new collection
|
|
150 * Returns: new seq s, such that
|
|
151 * <PRE>
|
|
152 * s.at(index) == element &&
|
|
153 * foreach (int i in 1 .. s.size()-1) s.at(i).equals(at(i-1));
|
|
154 * </PRE>
|
|
155 * Throws: NoSuchElementException if index is not in range 0..size()-1
|
|
156 **/
|
|
157
|
|
158 public SeqView insertingAt(int index, T element);
|
|
159
|
|
160
|
|
161 /**
|
|
162 * Construct a new SeqView that is a clone of self except
|
|
163 * that the indicated element is placed at the indicated index.
|
|
164 * @param index the index at which to replace the element
|
|
165 * @param element The new value of at(index)
|
|
166 * Returns: new seq, s, such that
|
|
167 * <PRE>
|
|
168 * s.at(index) == element &&
|
|
169 * foreach (int i in 0 .. s.size()-1)
|
|
170 * (i != index) --> s.at(i).equals(at(i));
|
|
171 * </PRE>
|
|
172 * Throws: NoSuchElementException if index is not in range 0..size()-1
|
|
173 **/
|
|
174
|
|
175 public SeqView replacingAt(int index, T element);
|
|
176
|
|
177
|
|
178 /**
|
|
179 * Construct a new SeqView that is a clone of self except
|
|
180 * that it does not contain the element at the indeicated index; all
|
|
181 * elements to its right are slided left by one.
|
|
182 *
|
|
183 * @param index the index at which to remove an element
|
|
184 * Returns: new seq such that
|
|
185 * <PRE>
|
|
186 * foreach (int i in 0.. index-1) s.at(i).equals(at(i)); &&
|
|
187 * foreach (int i in index .. s.size()-1) s.at(i).equals(at(i+1));
|
|
188 * </PRE>
|
|
189 * Throws: NoSuchElementException if index is not in range 0..size()-1
|
|
190 **/
|
|
191 public SeqView removingAt(int index);
|
|
192 } // version
|
|
193 }
|
|
194
|