Mercurial > projects > ldc

comparison tango/tango/util/collection/model/SeqView.d @ 132:1700239cab2e trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[svn r136] MAJOR UNSTABLE UPDATE!!! Initial commit after moving to Tango instead of Phobos. Lots of bugfixes... This build is not suitable for most things.
author lindquist
date Fri, 11 Jan 2008 17:57:40 +0100
parents
children
comparison
equal deleted inserted replaced
131:5825d48b27d1 132:1700239cab2e
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) --&gt; 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