com.sas.collection
Class Permuter

com.sas.collection.Permuter

public class Permuter

Permutes the items in an ordered collection according to a index reordering. A permutation is an integer array which shows where each item in the new ordering of items should come from, based on the original order. For example, a collection containing the string values

 { "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L" }
 

and permuted with the int array

 { 8, 9, 10, 11, 4, 5, 6, 7, 0, 1, 2, 3 }
 

will result in the collection

 { "I", "J", "K", "L", "E", "F", "G", "H", "A", "B", "C", "D" }
 

A permutation array must satisfy these constraints:

1. its length equals the collection size, determined by invoking collection's the count() method
2. All values must be in the range [0, length-1]
3. All values must be unique.

The permuting operations require an object that implements IndexedSetInterface, i.e. just the methods

• Object count();
• Object get(int);
• void set(int index, Object value)

Constructor Summary

Permuter()
Default constructor.

Permuter(IndexedSetInterface collection)
Construct a Permuter for a collection.

Permuter(IndexedSetInterface collection, int size)
Construct a Permuter for a collection.

Permuter(IndexedSetInterface collection, int[] permutation)
Construct a Permuter for a collection and a permutation.

Permuter(int[] permutation)
Construct a Permuter with a permutation array.

Method Summary

protected void	disableEvents() If the collection implements the EventGateInterface, use it to suppress events during a permute operation.
protected void	enableEvents() If the collection implements the EventGateInterface, use it to allow events after a permute operation.
IndexedSetInterface	getCollection() Return the collection that this Permuter will permute.
int[]	getPermutation() Get the permutation for the collection.
int[]	identityPermutation() Return an identity permutation.
static int[]	identityPermutation(int length) Return an identity permutation.
static void	move(IndexedSetInterface collection, int[] items, int offset) Move the items selected by an array of indices by an offset.
static void	move(IndexedSetInterface collection, int index, int offset) Move an item in a collection by a specified offset.
void	move(int[] items, int offset) Move the items selected by an array of indices by an offset.
void	move(int index, int offset) Move an item in the collection by a specified offset.
int[]	newMovePermutation(int[] items, int offset) Create a permutation which will move by a specified offset the set of items specified by an array of item indeces.
int[]	newMovePermutation(int index, int offset) Create a permutation which will move an item in the collection by a specified offset.
int[]	newReversePermutation(int start, int end) Create a permutation array which reverses the items between start and end
int[]	newRotatePermutation(int start, int end, int n) Create a permutation array which rotates the items between start and end by n items.
void	permute() Permute the collection according to the permutation.
static void	permute(IndexedSetInterface collection, int[] permutation) A static method useful for a one-time permutation of a collection.
void	permute(int[] permutation) Set the permutation, then permutes the collection.
static void	reverse(IndexedSetInterface collection, int start, int end) A static method useful for reversing a (subrange) of items in a collection.
void	reverse(int start, int end) Reverse a (subrange) of the collection.
static void	rotate(IndexedSetInterface collection, int start, int end, int n) A static method useful for rotating a (subrange) of items in a collection.
void	rotate(int start, int end, int n) Rotate a (subrange) of items in a collection.
void	setCollection(IndexedSetInterface collection) Set the collection which this Permuter will permute.
void	setCollection(IndexedSetInterface collection, int size) Set the collection which this Permuter will permute.
void	setPermutation(int[] permutation) Set the permutation array.
static void	swap(IndexedSetInterface collection, int i, int j) Convenience method to swap two items in an ordered collection.
protected void	validateItems(int[] items, int offset, int length) Validate that all items are in the range [0,length-1] may be moved by an offset.
protected void	validatePermutation(int[] permutation) Validate a permutation.

Constructor Detail

Permuter

public Permuter()

Default constructor. Use setCollection(com.sas.util.IndexedSetInterface) and setPermutation(int[]) to initialize the Permuter.

Permuter

public Permuter(IndexedSetInterface collection,
                int[] permutation)

Construct a Permuter for a collection and a permutation.

Parameters:

collection - the collection to permute

permutation - the purmutation array

Permuter

public Permuter(int[] permutation)

Construct a Permuter with a permutation array. Use setCollection(com.sas.util.IndexedSetInterface) to specifiy the collection to permute.

Parameters:

permutation - the purmutation array

Permuter

public Permuter(IndexedSetInterface collection)

Construct a Permuter for a collection. Use setPermutation(int[]) to specifiy the permutation array.

Parameters:

collection - the collection to permute

Permuter

public Permuter(IndexedSetInterface collection,
                int size)

Construct a Permuter for a collection.

Parameters:

collection - the collection to permute

size - the collection size, used instead of collection.count().

Method Detail

getCollection

public IndexedSetInterface getCollection()

Return the collection that this Permuter will permute.

Returns:

the ordered collection that this Permuter will permute.

setCollection

public void setCollection(IndexedSetInterface collection)

Set the collection which this Permuter will permute.

Parameters:

collection - a ordered collection

setCollection

public void setCollection(IndexedSetInterface collection,
                          int size)

Set the collection which this Permuter will permute.

Parameters:

collection - a ordered collection

size - the collection size, used instead of collection.count().

getPermutation

public int[] getPermutation()

Get the permutation for the collection.

Returns:

the int[] permutation.

setPermutation

public void setPermutation(int[] permutation)

Set the permutation array.

Parameters:

an - array of permutation indices. A permutation array must satisfy the constraints defined in validatePermutation(int[]):

disableEvents

protected void disableEvents()

If the collection implements the EventGateInterface, use it to suppress events during a permute operation.

enableEvents

protected void enableEvents()

If the collection implements the EventGateInterface, use it to allow events after a permute operation.

validatePermutation

protected void validatePermutation(int[] permutation)

Validate a permutation. A permutation array must satisfy these constraints:

1. its length equals the collection.count()
2. all values must be in the range [0, length-1]
3. all values must be unique.

Parameters:

permutation - an array of indices to validate

permute

public void permute()

Permute the collection according to the permutation. This reorders the items in collection. If the collection implements the EventGateInterface, use it to suppress events during the permutation operation. so that an event is not fired for every item that is moved.

permute

public void permute(int[] permutation)

Set the permutation, then permutes the collection.

permute

public static void permute(IndexedSetInterface collection,
                           int[] permutation)

A static method useful for a one-time permutation of a collection.

Parameters:

collection - the collection to permite

permutation - the permutation array

reverse

public static void reverse(IndexedSetInterface collection,
                           int start,
                           int end)

A static method useful for reversing a (subrange) of items in a collection. To reverse the entire collection, use

 reverse(collection, 0, collection.count());
 

Parameters:

collection - the collection to reverse

start - the index of the first item in the range of items to reverse

end - one past the index of the last item in the range of items to reverse.

reverse

public void reverse(int start,
                    int end)

Reverse a (subrange) of the collection. This does a setPermutation(int[]). To reverse the entire collection, use

 reverse(0, collection.count());
 

Parameters:

start - the index of the first item in the range of items to reverse

end - one past the index of the last item in the range of items to reverse.

newReversePermutation

public int[] newReversePermutation(int start,
                                   int end)

Create a permutation array which reverses the items between start and end

Parameters:

start - the index of the first item in the range of items to reverse

end - one past the index of the last item in the range of items to reverse.

Returns:

a new int array for the permutation.

swap

public static void swap(IndexedSetInterface collection,
                        int i,
                        int j)

Convenience method to swap two items in an ordered collection. This method handles the special case of swapping items in an AssociationListInterface; it swaps the key and item values at i and j

Parameters:

collection - the collection in which to swap items

i - index of one item to swap

j - index of the other item to swap

rotate

public static void rotate(IndexedSetInterface collection,
                          int start,
                          int end,
                          int n)

A static method useful for rotating a (subrange) of items in a collection. To rotate the entire collection, use

 rotate(collection, 0, collection.count(), n);
 

Parameters:

collection - the collection to rotate

start - the index of the first item in the range of items to rotate

end - one past the index of the last item in the range of items to rotate

n - the distance you want to rotate items.

See Also:

rotate(int, int, int)

rotate

public void rotate(int start,
                   int end,
                   int n)

Rotate a (subrange) of items in a collection. To rotate the entire collection, use

 rotate(0, collection.count(), n);
 

Parameters:

collection - the collection to rotate

start - the index of the first item in the range of items to rotate.

end - one past the index of the last item in the range of items to rotate.

n - the distance you want to rotate items. If n > 0, items are rotated right to left n places; if n < 0, items are rotated left to right n places. For example, the collection

 { "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L" }
 

rotated by 2 yields

 { "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "A", "B" }
 

newRotatePermutation

public int[] newRotatePermutation(int start,
                                  int end,
                                  int n)

Create a permutation array which rotates the items between start and end by n items.

Parameters:

start - the index of the first item in the range of items to rotate.

end - one past the index of the last item in the range of items to rotate.

n - the distance you want to rotate items. If n > 0, items are rotated right to left n places; if n < 0, items are rotated left to right n places.

Returns:

a new int array for the permutation.

move

public static void move(IndexedSetInterface collection,
                        int index,
                        int offset)

Move an item in a collection by a specified offset.

Parameters:

collection - the collection to permute.

index - the index of the item you want to move.

offset - the distance you want to move the item. Move the item to position index + offset.

See Also:

move(int, int)

move

public void move(int index,
                 int offset)

Move an item in the collection by a specified offset.

Parameters:

index - the index of the item you want to move.

offset - the distance you want to move the item. Negative numbers move the items closer to the beginning; positive numbers move the items towards the end. Move the item to position index + offset. All other items between index and index+offset are shifted. This therefore has the same effect as rotating the affected items left or right 1 item, depending on the sign of the offset.

newMovePermutation

public int[] newMovePermutation(int index,
                                int offset)

Create a permutation which will move an item in the collection by a specified offset.

Parameters:

index - the index of the item you want to move.

offset - the distance you want to move the item. Negative numbers move the items closer to the beginning; positive numbers move the items towards the end.

Returns:

a new permutation array.

move

public static void move(IndexedSetInterface collection,
                        int[] items,
                        int offset)

Move the items selected by an array of indices by an offset.

Parameters:

collection - the collection to permute.

items - an array of item indices. Each element must be a valid index within the collection.

offset - how much to move the items. negative numbers move the items closer to the beginning; positive numbers move the items towards the end.

See Also:

move(int[], int)

move

public void move(int[] items,
                 int offset)

Move the items selected by an array of indices by an offset.

Parameters:

collection - the collection to permute.

items - an array of item indices. Each element must be a valid index within the collection. The items must be in ascending order and each index must be unique.

offset - how much to move the items. negative numbers move the items closer to the beginning; positive numbers move the items towards the end.

newMovePermutation

public int[] newMovePermutation(int[] items,
                                int offset)

Create a permutation which will move by a specified offset the set of items specified by an array of item indeces.

Parameters:

items - an array of indices identifying the items item you want to move. The array need not be contiguous, but the items must be in ascending order and each index must be unique.

offset - the distance you want to move the items. negative numbers move the items closer to the beginning; positive numbers move the items towards the end.

Returns:

a new permutation array.

validateItems

protected void validateItems(int[] items,
                             int offset,
                             int length)

Validate that all items are in the range [0,length-1] may be moved by an offset.

Parameters:

items - an array of permutation indices

offset - how much to move the items.

length - the permutation length.

identityPermutation

public int[] identityPermutation()

Return an identity permutation.

Returns:

an int array with values {0, 1, 2, ..., collection.count()-1}

identityPermutation

public static int[] identityPermutation(int length)

Return an identity permutation.

Parameters:

length - the size of the permutation array

Returns:

an int array with values {0, 1, 2, ..., length-1}