Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
Sequence |
|
| 0.0;0 |
1 | /* | |
2 | * Copyright 2007 Sun Microsystems, Inc. All Rights Reserved. | |
3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | |
4 | * | |
5 | * This code is free software; you can redistribute it and/or modify it | |
6 | * under the terms of the GNU General Public License version 2 only, as | |
7 | * published by the Free Software Foundation. Sun designates this | |
8 | * particular file as subject to the "Classpath" exception as provided | |
9 | * by Sun in the LICENSE file that accompanied this code. | |
10 | * | |
11 | * This code is distributed in the hope that it will be useful, but WITHOUT | |
12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
14 | * version 2 for more details (a copy is included in the LICENSE file that | |
15 | * accompanied this code). | |
16 | * | |
17 | * You should have received a copy of the GNU General Public License version | |
18 | * 2 along with this work; if not, write to the Free Software Foundation, | |
19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. | |
20 | * | |
21 | * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, | |
22 | * CA 95054 USA or visit www.sun.com if you need additional information or | |
23 | * have any questions. | |
24 | */ | |
25 | ||
26 | package com.sun.javafx.runtime.sequence; | |
27 | ||
28 | import java.util.BitSet; | |
29 | import java.util.Iterator; | |
30 | ||
31 | /** | |
32 | * Sequences are immutable, homogeneous, ordered collections. A sequence has an element type, | |
33 | * a length, and a list of elements. New sequences can be derived by calling the factory methods | |
34 | * (insert, delete, subsequence, etc) or can be constructed with the static factories in Sequences. | |
35 | * Sequence types are reified; the sequence references the Class object for the element type. | |
36 | * | |
37 | * Sequences are stored as trees. The "leaf" nodes are array-based sequences; intermediate nodes are "views" | |
38 | * onto underlying sequences, performing transformations such as adding elements, filtering elements, changing the | |
39 | * order of elements, etc. Do not use the constructors for the various Sequence implementation classes to produce | |
40 | * sequences; use the factory methods in the Sequence interface or the static factories in the Sequences class. | |
41 | * | |
42 | * Sequences with elements of type Integer, Boolean, and Double are special; in these cases, when the | |
43 | * get() operation might return a null (because the index is out of range), it will instead return the | |
44 | * default value for that type (zero or false). | |
45 | * | |
46 | * @author Brian Goetz | |
47 | */ | |
48 | public interface Sequence<T> extends Iterable<T> { | |
49 | /** How large is this sequence? */ | |
50 | public int size(); | |
51 | ||
52 | /** Is this sequence empty? */ | |
53 | public boolean isEmpty(); | |
54 | ||
55 | /** What is the element type? */ | |
56 | public Class<T> getElementType(); | |
57 | ||
58 | /** Copy the contents of this sequence to an array, at a specified offset within the destination array */ | |
59 | public void toArray(Object[] array, int destOffset); | |
60 | ||
61 | /** Create a new sequence whose elements are the result of applying a mapping function to the elements | |
62 | * of the original sequence. */ | |
63 | public<V> Sequence<V> map(Class<V> clazz, SequenceMapper<T, V> mapper); | |
64 | ||
65 | /** Extract the element at the specified position. If the position is out of range, the default value for | |
66 | * the element type is returned; either null, zero for Integer or Double sequences, or false for Boolean | |
67 | * sequences. */ | |
68 | public T get(int position); | |
69 | ||
70 | /** Extract a slice of the sequence */ | |
71 | public Sequence<T> getSlice(int startPos, int endPos); | |
72 | ||
73 | /** Delete the element at the specified position. If the position is out of range, the sequence is not modified. */ | |
74 | public Sequence<T> delete(int position); | |
75 | ||
76 | /** Delete the elements matching the specified predicate. */ | |
77 | public Sequence<T> delete(SequencePredicate<? super T> predicate); | |
78 | ||
79 | /** Modify the element at the specified position. If the position is out of range, the sequence is not | |
80 | * modified. */ | |
81 | public Sequence<T> set(int position, T value); | |
82 | ||
83 | /** Modify a slice of the sequence. A slice is defined by a starting position and an ending position, both | |
84 | * inclusive. Extracting element n is equivalent to the slice from n..n. Extracting the whole sequence is | |
85 | * equivalent to the slice from 0..size-1. */ | |
86 | public Sequence<T> replaceSlice(int startPos, int endPos, Sequence<? extends T> newValues); | |
87 | ||
88 | /** Select elements from the sequence matching the specified predicate. */ | |
89 | public Sequence<T> get(SequencePredicate<? super T> predicate); | |
90 | ||
91 | /** Return a subsequence starting at the specified start position, up to but not including the specified | |
92 | * end position. If the end position is less than or equal to the start, an empty sequence is returned. */ | |
93 | public Sequence<T> subsequence(int start, int end); | |
94 | ||
95 | /** Insert the specified value at the end of the sequence */ | |
96 | public Sequence<T> insert(T value); | |
97 | ||
98 | /** Insert the specified values at the end of the sequence */ | |
99 | public Sequence<T> insert(Sequence<? extends T> values); | |
100 | ||
101 | /** Insert the specified value at the beginning of the sequence */ | |
102 | public Sequence<T> insertFirst(T value); | |
103 | ||
104 | /** Insert the specified values at the beginning of the sequence */ | |
105 | public Sequence<T> insertFirst(Sequence<? extends T> values); | |
106 | ||
107 | /** Insert the specified value before the specified position. If the position is negative, it is inserted before | |
108 | * element zero; if it is greater than or equal to the size of the sequence, it is inserted at the end. */ | |
109 | public Sequence<T> insertBefore(T value, int position); | |
110 | ||
111 | /** Insert the specified value before the position(s) matching the specified predicate. */ | |
112 | public Sequence<T> insertBefore(T value, SequencePredicate<? super T> predicate); | |
113 | ||
114 | /** Insert the specified values before the specified position. If the position is negative, they are inserted before | |
115 | * element zero; if it is greater than or equal to the size of the sequence, they are inserted at the end. */ | |
116 | public Sequence<T> insertBefore(Sequence<? extends T> values, int position); | |
117 | ||
118 | /** Insert the specified values before the position(s) matchign the specified predicate. */ | |
119 | public Sequence<T> insertBefore(Sequence<? extends T> values, SequencePredicate<? super T> predicate); | |
120 | ||
121 | /** Insert the specified value after the specified position. If the position is negative, it is inserted before | |
122 | * element zero; if it is greater than or equal to the size of the sequence, it is inserted at the end. */ | |
123 | public Sequence<T> insertAfter(T value, int position); | |
124 | ||
125 | /** Insert the specified value after the position(s) matching the specified predicate. */ | |
126 | public Sequence<T> insertAfter(T value, SequencePredicate<? super T> predicate); | |
127 | ||
128 | /** Insert the specified values after the specified position. If the position is negative, they are inserted before | |
129 | * element zero; if it is greater than or equal to the size of the sequence, they are inserted at the end. */ | |
130 | public Sequence<T> insertAfter(Sequence<? extends T> values, int position); | |
131 | ||
132 | /** Insert the specified values after the position(s) matchign the specified predicate. */ | |
133 | public Sequence<T> insertAfter(Sequence<? extends T> values, SequencePredicate<? super T> predicate); | |
134 | ||
135 | /** Reverse the elements of the sequence */ | |
136 | public Sequence<T> reverse(); | |
137 | ||
138 | /** Many sequences are represented as trees to reduce copying costs; if the current sequence has depth > 0, | |
139 | * copy the elements into a new sequence of depth == 0. | |
140 | */ | |
141 | public Sequence<T> flatten(); | |
142 | ||
143 | /** | |
144 | * Returns the number of levels of sequence objects between this Sequence object and the deepest data. | |
145 | * Leaf classes (e.g., ArraySequence, IntRangeSequence) have a depth of zero; composite classes have a depth | |
146 | * one greater than their deepest leaf. | |
147 | */ | |
148 | public int getDepth(); | |
149 | ||
150 | /** | |
151 | * Return a BitSet indicating which elements of the sequence match the given predicate. AbstractSequence | |
152 | * provides a default implementation in terms of get(i); implementations may want to provide an optimized | |
153 | * version. | |
154 | */ | |
155 | public BitSet getBits(SequencePredicate<? super T> predicate); | |
156 | ||
157 | public Iterator<T> iterator(); | |
158 | } |