1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.numbers.examples.jmh.arrays;
18
19 /**
20 * An interval that contains indices used for partitioning an array into multiple regions.
21 *
22 * <p>The interval provides the following functionality:
23 *
24 * <ul>
25 * <li>Return the supported bounds of the interval {@code [left <= right]}.
26 * <li>Split the interval around two indices {@code k1} and {@code k2}.
27 * </ul>
28 *
29 * <p>Note that the interval provides the supported bounds. If a split invalidates an interval
30 * the bounds are undefined and the interval is marked as {@link #empty()}.
31 *
32 * <p>Implementations may assume indices are positive.
33 *
34 * @since 1.2
35 */
36 interface SplittingInterval {
37 /**
38 * The start (inclusive) of the interval.
39 *
40 * @return start of the interval
41 */
42 int left();
43
44 /**
45 * The end (inclusive) of the interval.
46 *
47 * @return end of the interval
48 */
49 int right();
50
51 /**
52 * Signal this interval is empty. The left and right bounds are undefined. This results
53 * from a split where there is no right side.
54 *
55 * @return {@code true} if empty
56 */
57 boolean empty();
58
59 /**
60 * Split the interval using two splitting indices. Returns the left interval that occurs
61 * before the specified split index {@code ka}, and updates the current interval left bound
62 * to after the specified split index {@code kb}.
63 *
64 * <pre>{@code
65 * l-----------ka-kb----------r
66 * ra <--| |--> lb
67 *
68 * ra < ka
69 * lb > kb
70 * }</pre>
71 *
72 * <p>If {@code ka <= left} the returned left interval is {@code null}.
73 *
74 * <p>If {@code kb >= right} the current interval is invalidated and marked as empty.
75 *
76 * @param ka Split index.
77 * @param kb Split index.
78 * @return the left interval
79 * @see #empty()
80 */
81 SplittingInterval split(int ka, int kb);
82 }