public class GroupIterator
extends java.lang.Object
A GroupIterator allows a curve to choose the points from a control-path that the curve uses to define itself. The subset of points to use is defined by a control-string. The control-string is evaluated to produce a series of integer groups that are iterated over.
A common way to create a GroupIterator that uses all the points of a control-path is:
GroupIterator gi = new GroupIterator("0:n-1", cp.getNumPoints());
The "0:n-1" is the control-string and cp is a control-path. Once created, the groups that are iterated over cannot be changed. Thus, if the number of points in the control-path changes, then a new group iterator is required.
Some blended curves do not evaluate over the first and last points. A technique to get the curve to connect to the endpoints is to create duplicate endpoints. But instead of doing that, a control-string such as "0,0:n-1,n-1" will do the same thing.
The syntax of the control-string is fairly basic. A control-string consists of one or more groups separated by a comma and possibly additional whitespace. Each group consists of either 1 or 2 expressions. If there are two expressions, then a colon ':' separates them. The expressions are parsed using the ExpressionTree.parse(String) method. Each expression can contain at most one variable and the value of that variable is set to the value specified in the GroupIterator constructor. An exception is thrown if there are multiple variables in a single expression. The result of evaluating the expressions is rounded.
Suppose the control-string is: "1:4,8:n/2,7:3,5"
Suppose n = 21, then the internal group array is {1, 4, 8, 11, 7, 3, 5, 5}
Notice that the length of the group array is twice the number groups.
The group size is (|1 - 4| + 1) + (|8 - 11| + 1) + (|7 - 3| + 1) + (|5 - 5| + 1) = 14.
GroupIterator gi = new GroupIterator("1:4,8:n/2,7:3,5", 21);
while (gi.hasNext())
System.out.print(gi.next() + ", ");
Output: 1, 2, 3, 4, 8, 9, 10, 11, 7, 6, 5, 4, 3, 5
index_i: 0, 0, 0, 0, 2, 2, 2, 2, 4, 4, 4, 4, 4, 6
count_j: 0, 1, 2, 3, 0, 1, 2, 3, 0, 1, 2, 3, 4, 0
Notice that the number of numbers outputted is 14, which is the group size. At this point, calling next() will result in an exception. However, GroupIterator objects are reusable and can be reset by calling the reset() method or by calling set(0, 0).
The variables index_i and count_j represent the current state of the group-iterator. The index_i is an index location in the internal group-array that keeps track of the current group. Since each group always has a start index and a finish index, index_i refers to the first index and increments by 2.
The count_j variable increments by one until group[index_i] ± count_j == group[index_i + 1]. At this point, count_j is reset to 0 and index_i is incremented by 2.
ExpressionTree,
Curve,
ControlPath| Modifier and Type | Field and Description |
|---|---|
protected java.lang.String |
controlString |
protected int |
count_j |
protected int[] |
group |
protected int |
index_i |
| Constructor and Description |
|---|
GroupIterator(int[] group)
Constructs a group-iterator by copying the specified group array into a new internal array.
|
GroupIterator(java.lang.String controlString,
int n)
Constructs a group-iterator by parsing the control-string string according to the class description.
|
| Modifier and Type | Method and Description |
|---|---|
void |
copyGroupArray(int[] arr)
Copies the internal group-array into the specified array.
|
int |
count_j()
count_j is the increment that keeps track of the position in the current group.
|
java.lang.String |
getControlString()
Returns the control-string used in the constuctor.
|
int |
getGroupLength()
Returns the length of the internal group-array.
|
int |
getGroupSize()
Returns the total number of times next() can be called before hasNext() returns false starting from state 0, 0.
|
int |
getGroupValue(int index)
Returns the value at the specified index in the internal group-array.
|
boolean |
hasNext()
Returns true if the iterator is not finished.
|
int |
index_i()
index_i is the index location into the internal group array of the current group.
|
boolean |
isInRange(int min,
int max)
Returns true if all values returned by next() are >= min and < max, false otherwise.
|
int |
next()
Returns the current index and advances the state to the next index.
|
static int[] |
parseControlString(java.lang.String controlString,
int n)
Parses the specified control-string according to the class description and returns a group-array.
|
void |
reset()
Resets the state of the iterator back to the initial state.
|
void |
set(int index_i,
int count_j)
Sets the current state of the iterator.
|
private static Expression |
setVariables(java.lang.String s,
VarMap vm,
int n,
int j,
int i) |
protected java.lang.String controlString
protected int[] group
protected int index_i
protected int count_j
public GroupIterator(java.lang.String controlString,
int n)
java.lang.IllegalArgumentException - If the control-string is null.ControlStringParseException - If the control-string is invalid.public GroupIterator(int[] group)
java.lang.IllegalArgumentException - If the specified array is null, the array length is 0 or the array length is odd.public static int[] parseControlString(java.lang.String controlString,
int n)
private static Expression setVariables(java.lang.String s, VarMap vm, int n, int j, int i)
public java.lang.String getControlString()
public int getGroupLength()
public int getGroupValue(int index)
java.lang.IllegalArgumentException - If index < 0 or index >= group.length.getGroupLength()public int getGroupSize()
public void copyGroupArray(int[] arr)
java.lang.IllegalArgumentException - If the specified array is null or is shorter than the group-length.getGroupLength()public boolean hasNext()
public int next()
public void set(int index_i,
int count_j)
java.lang.IllegalArgumentException - If index_i < 0, count_j < 0 or index_i is an odd number.public int index_i()
public int count_j()
public void reset()
public boolean isInRange(int min,
int max)