src/extra166y/ParallelArrayWithBounds.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/publicdomain/zero/1.0/
 */

package extra166y;

import jsr166y.*;
import static extra166y.Ops.*;
import java.util.*;
import java.util.concurrent.atomic.*;
import java.lang.reflect.Array;

/**
 * A prefix view of ParallelArray that causes operations to apply
 * only to elements within a given range.
 * Instances of this class may be constructed only via prefix
 * methods of ParallelArray or its other prefix classes.
 */
public abstract class ParallelArrayWithBounds<T> extends ParallelArrayWithFilter<T> {
    ParallelArrayWithBounds
        (ForkJoinPool ex, int origin, int fence, T[] array) {
        super(ex, origin, fence, array);
    }

    /**
     * Returns an operation prefix that causes a method to operate
     * only on the elements of the array between firstIndex
     * (inclusive) and upperBound (exclusive).  The bound
     * arguments are relative to the current bounds.  For example
     * {@code pa.withBounds(2, 8).withBounds(3, 5)} indexes the
     * 5th (= 2+3) and 6th elements of pa. However, indices
     * returned by methods such as {@code indexOf} are
     * with respect to the underlying ParallelArray.
     * @param firstIndex the lower bound (inclusive)
     * @param upperBound the upper bound (exclusive)
     * @return operation prefix
     */
    public abstract ParallelArrayWithBounds<T> withBounds
        (int firstIndex, int upperBound);

    /**
     * Returns the index of some element equal to given target, or
     * -1 if not present.
     * @param target the element to search for
     * @return the index or -1 if not present
     */
    public abstract int indexOf(T target);

    /**
     * Assuming this array is sorted, returns the index of an
     * element equal to given target, or -1 if not present. If the
     * array is not sorted, the results are undefined.
     * @param target the element to search for
     * @return the index or -1 if not present
     */
    public abstract int binarySearch(T target);

    /**
     * Assuming this array is sorted with respect to the given
     * comparator, returns the index of an element equal to given
     * target, or -1 if not present. If the array is not sorted,
     * the results are undefined.
     * @param target the element to search for
     * @param comparator the comparator
     * @return the index or -1 if not present
     */
    public abstract int binarySearch(T target,
                                     Comparator<? super T> comparator);
    /**
     * Replaces each element with the running cumulation of applying
     * the given reducer.
     * @param reducer the reducer
     * @param base the result for an empty array
     * @return this (to simplify use in expressions)
     */
    public abstract ParallelArrayWithBounds<T> cumulate(Reducer<T> reducer, T base);

    /**
     * Replaces each element with the cumulation of applying the given
     * reducer to all previous values, and returns the total
     * reduction.
     * @param reducer the reducer
     * @param base the result for an empty array
     * @return the total reduction
     */
    public abstract T precumulate(Reducer<T> reducer, T base);

    /**
     * Sorts the elements.
     * Unlike Arrays.sort, this sort does
     * not guarantee that elements with equal keys maintain their
     * relative position in the array.
     * @param cmp the comparator to use
     * @return this (to simplify use in expressions)
     */
    public abstract ParallelArrayWithBounds<T> sort(Comparator<? super T> cmp);

    /**
     * Sorts the elements, assuming all elements are
     * Comparable. Unlike Arrays.sort, this sort does not
     * guarantee that elements with equal keys maintain their relative
     * position in the array.
     * @return this (to simplify use in expressions)
     * @throws ClassCastException if any element is not Comparable
     */
    public abstract ParallelArrayWithBounds<T> sort();
}
Revision:	1.7
Committed:	Sun Jan 18 20:17:32 2015 UTC (9 years, 3 months ago) by jsr166
Branch:	MAIN
Changes since 1.6:	+1 -0 lines
Log Message:	exactly one blank line before and after package statements
#	User	Rev	Content
1	dl	1.1	/*
2			* Written by Doug Lea with assistance from members of JCP JSR-166
3			* Expert Group and released to the public domain, as explained at
4	jsr166	1.2	* http://creativecommons.org/publicdomain/zero/1.0/
5	dl	1.1	*/
6
7			package extra166y;
8	jsr166	1.7
9	dl	1.1	import jsr166y.*;
10			import static extra166y.Ops.*;
11			import java.util.*;
12			import java.util.concurrent.atomic.*;
13			import java.lang.reflect.Array;
14
15			/**
16			* A prefix view of ParallelArray that causes operations to apply
17			* only to elements within a given range.
18			* Instances of this class may be constructed only via prefix
19			* methods of ParallelArray or its other prefix classes.
20			*/
21			public abstract class ParallelArrayWithBounds<T> extends ParallelArrayWithFilter<T> {
22			ParallelArrayWithBounds
23			(ForkJoinPool ex, int origin, int fence, T[] array) {
24			super(ex, origin, fence, array);
25			}
26
27			/**
28			* Returns an operation prefix that causes a method to operate
29			* only on the elements of the array between firstIndex
30			* (inclusive) and upperBound (exclusive). The bound
31			* arguments are relative to the current bounds. For example
32	jsr166	1.6	* {@code pa.withBounds(2, 8).withBounds(3, 5)} indexes the
33	dl	1.1	* 5th (= 2+3) and 6th elements of pa. However, indices
34	jsr166	1.6	* returned by methods such as {@code indexOf} are
35	dl	1.1	* with respect to the underlying ParallelArray.
36			* @param firstIndex the lower bound (inclusive)
37			* @param upperBound the upper bound (exclusive)
38			* @return operation prefix
39			*/
40			public abstract ParallelArrayWithBounds<T> withBounds
41			(int firstIndex, int upperBound);
42
43			/**
44			* Returns the index of some element equal to given target, or
45	jsr166	1.5	* -1 if not present.
46	dl	1.1	* @param target the element to search for
47			* @return the index or -1 if not present
48			*/
49			public abstract int indexOf(T target);
50
51			/**
52			* Assuming this array is sorted, returns the index of an
53			* element equal to given target, or -1 if not present. If the
54			* array is not sorted, the results are undefined.
55			* @param target the element to search for
56			* @return the index or -1 if not present
57			*/
58			public abstract int binarySearch(T target);
59
60			/**
61			* Assuming this array is sorted with respect to the given
62			* comparator, returns the index of an element equal to given
63			* target, or -1 if not present. If the array is not sorted,
64			* the results are undefined.
65			* @param target the element to search for
66			* @param comparator the comparator
67			* @return the index or -1 if not present
68			*/
69			public abstract int binarySearch(T target,
70			Comparator<? super T> comparator);
71			/**
72			* Replaces each element with the running cumulation of applying
73			* the given reducer.
74			* @param reducer the reducer
75			* @param base the result for an empty array
76			* @return this (to simplify use in expressions)
77			*/
78			public abstract ParallelArrayWithBounds<T> cumulate(Reducer<T> reducer, T base);
79
80			/**
81			* Replaces each element with the cumulation of applying the given
82			* reducer to all previous values, and returns the total
83			* reduction.
84			* @param reducer the reducer
85			* @param base the result for an empty array
86			* @return the total reduction
87			*/
88			public abstract T precumulate(Reducer<T> reducer, T base);
89
90			/**
91			* Sorts the elements.
92			* Unlike Arrays.sort, this sort does
93			* not guarantee that elements with equal keys maintain their
94			* relative position in the array.
95			* @param cmp the comparator to use
96			* @return this (to simplify use in expressions)
97			*/
98			public abstract ParallelArrayWithBounds<T> sort(Comparator<? super T> cmp);
99
100			/**
101			* Sorts the elements, assuming all elements are
102			* Comparable. Unlike Arrays.sort, this sort does not
103			* guarantee that elements with equal keys maintain their relative
104			* position in the array.
105			* @return this (to simplify use in expressions)
106	jsr166	1.4	* @throws ClassCastException if any element is not Comparable
107	dl	1.1	*/
108			public abstract ParallelArrayWithBounds<T> sort();
109			}