com.sas.table
Interface SortableTableInterface

public interface SortableTableInterface

Allow sorting a table by reordering their rows. The sort methods defined below may be used to sort a table in-place. You may sort by comparing one or multiple column values in table rows, or by comparing the entire row. As a side effect of sorting a table, the permutation generated by reordering the rows can be saved in order to permute other tables. This class also provides methods to remove duplicate rows from a sorted table. As with sorting, you provide a comparator to determine if a row is a duplicate; you can compare cells from one column, multiple columns, or the entire row.

Examples

For example, if you wish to sort a table by column 2, which contains String values, you may use

  table.sort(2, StringComparator.defaultInstance, 1, table.getRowCount(), null);
 

The next example sorts a table using a custom row based comparator. This custom comparator extracts a (fictional) ShippingRecord object from two columns, and compares them by computing a value: subtract the second ShippingRecord's date from the date of the first ShippingRecord. The sort method is used to sort the table by comparing the shipping duration computed from columns 3 and 4. The row permutation from the sort is then applied to reorder a second table (of the same number of rows) with the same row reordering.

 public class ShippingDurationTableComparator implements java.util.Comparator
 {
   private int shipColumn, receiptColumn;
   public ShippingDurationTableComparator(int shipColumn, int receiptColumn) {
     this.shipColumn = shipColumn;
     this.receiptColumn = receiptColumn;
   }
   private long duration(Object row) {
     ShippingRecord ship    = (ShippingRecord) SimpleTable.getCell(row, shipColumn);
     ShippingRecord receipt = (ShippingRecord) SimpleTable.getCell(row, receiptColumn;
     return receipt.getDate().getTime() - ship.getDate().getTime();
   }
   public int compare(Object a, Object b) {
     long durationA = duration(a);
     long durationB = duration(b);
     if (durationA < durationB)
       return LESS_THAN;
     else if (durationA > durationB)
       return GREATER_THAN;
     else
       return EQUALS;
   }
 }

 int permutation[] = com.sas.collection.Permuter.identityPermutation(table.getRowCount());
 table.sort(new ShippingDurationTableComparator(3, 4), 1, -1, permutation);
 table2.permute(permutation);
 

Note that this method extracts the desired cell from the row using SimpleTable.getCell(Object row, int columnIndex). This static method should be used for row based comparators (for either sorting or removing duplicates). It isolates the comparator from row representation details, such as a row being stored as a Object[] array or as a List (such as a Vector or ArrayList).

startRowIndex and endRowIndex

In tables, rows and columns are indexed with 1-based indexing. That is, the first data row of a table is row 1 and the first column is column 1. Several methods in this interface allow you to specify a range of rows over which the method applies (such as sorting a range of rows or removing duplicates in a range of rows.) These methods specify the row range with two parameters, startRowIndex and endRowIndex. The endRowIndex is always one past the last row you want to operate on. If you wish to sort the first ten rows of a table, use table.sort(comparator, 1, 11, null); To perform an operation on all rows of a table, you should pass startRowIndex == 1 and endRowIndex == table.getRowCount()+1

As a convenience, if an endRowIndex number is negative, the methods adjust the end row relative to the end of the table. endRowIndex == -1 is equivalent to table.getRowCount()+1 and may be used to operate on all rows including the last row; endRowIndex == -2 will operate on all but the last row, and so on. If you wish to sort the all but the last ten rows of a table, use table.sort(comparator, 1, -11, null);

Since:

2.0

See Also:

Sort, Permuter, StringComparator, GenericComparator

Method Summary

void	deleteRows(boolean[] delete) Delete rows as indicated in an array of flags.
java.util.Comparator	getColumnComparator(int columnIndex) Return the comparator associated with this column.
boolean	isRowsDeletable() Returns the value of the rowsDeletable property. rowsDeletable indicates whether or not rows can be deleted.
void	permute(int[] permutation) Permute a table according to a permutation array.
void	removeDuplicates(java.util.Comparator comparator, int startRowIndex, int endRowIndex, boolean keepFirst, boolean[] removed) Remove duplicates from a sorted table, based on comparing the row contents.
void	removeDuplicates(int[] columnIndices, java.util.Comparator[] comparators, int startRowIndex, int endRowIndex, boolean keepFirst, boolean[] removed) Remove duplicates from a sorted table, based on comparing cell contents from multiple columns.
void	removeDuplicates(int columnIndex, java.util.Comparator comparator, int startRowIndex, int endRowIndex, boolean keepFirst, boolean[] removed) Remove duplicates from a sorted table, based on comparing cell contents from a single column.
void	reverseColumnComparator(int columnIndex) Reverse the sense of the comparator for column columnIndex.
void	setColumnComparator(int columnIndex, java.util.Comparator comparator)
void	sort(java.util.Comparator comparator, int startRowIndex, int endRowIndex, int[] permutation) Sort the table in place, based on comparing row contents using the comparator.
void	sort(int[] columnIndices, java.util.Comparator[] comparators, int startRowIndex, int endRowIndex, int[] permutation) Sort the table in place, based on comparing elements from multiple columns listed in columnIndices, using the corresponding	void	sort(int columnIndex, java.util.Comparator comparator, int startRowIndex, int endRowIndex, int[] permutation) Sort the table in place, based on comparing elements from the column columnIndex, using the comparator.

Method Detail

sort

void sort(java.util.Comparator comparator,
          int startRowIndex,
          int endRowIndex,
          int[] permutation)
          throws com.sas.table.TableException

Sort the table in place, based on comparing row contents using the comparator.

Parameters:

comparator - the Comparator to use to compare table rows. Row values are passed to the comparator an Object[] array or a List. Use SimpleTable.getCell(Object row, int columnIndex) to extract a cell from this row for use in the comparator. If comparator is null, a Comparator is made from combining all column comparators.

startRowIndex - the index of the first row of the range of rows to sort.

endRowIndex - one greater than then index of the last row of the range of rows to sort, or -1 to include all rows through the end of the table. See also startRowIndex and endRowIndex above.

permutation - the permutation under which the table was sorted. This may be null; otherwise it must be initialized with the consecutive integers from 0 to table.getRowCount() - 1 (the permutation is 0 based). If non-null, the sort method will return the sort permutation in this int[] array. See Permuter.identityPermutation(int)

Throws:

com.sas.table.TableException - if the table operation cannot be performed

sort

void sort(int columnIndex,
          java.util.Comparator comparator,
          int startRowIndex,
          int endRowIndex,
          int[] permutation)
          throws com.sas.table.TableException

Sort the table in place, based on comparing elements from the column columnIndex, using the comparator. This method is equivalent to sort(new int[] {columnIndex}, new Comparator[] {comparator}, startRowIndex, endRowIndex, permutation)

Parameters:

columnIndex - the column index to use for sorting. Table column indices are 1-based.

comparator - the comparator to use to compare table cells When sorting by a column, only table cell values table.getCell(a, columnIndex) and table.getCell(b, columnIndex) are passed to the comparator. If this value is null, use the comparator assigned to this row with setColumnComparator(int, Comparator)

startRowIndex - the index of the first row of the range of rows to sort.

endRowIndex - one greater than then index of the last row of the range of rows to sort, or -1 to include all rows through the end of the table. See also startRowIndex and endRowIndex above.

permutation - the permutation under which the table was sorted. This may be null; otherwise it must be initialized with the consecutive integers from 0 to table.getRowCount() - 1 (the permutation is 0 based). If non-null, the sort method will return the sort permutation in this int[] array. See Permuter.identityPermutation(int)

Throws:

com.sas.table.TableException - if the table operation cannot be performed

sort

void sort(int[] columnIndices,
          java.util.Comparator[] comparators,
          int startRowIndex,
          int endRowIndex,
          int[] permutation)
          throws com.sas.table.TableException

Sort the table in place, based on comparing elements from multiple columns listed in columnIndices, using the corresponding Comparator from the array, comparators. Column columnIndices[0] is treated as a primary sort key, Column columnIndices[1] is treated as a secondary sort key, etc. Thus, comparators[i+1] is ony invoked if comparators[i] returned EQUALS. For example, to compare rows a and b, this method performs an operation similar to

 Object rowA = table.getRow[a];
 Object rowB = table.getRow[b];
 for (int col = 0; col < columnIndices.length; col++) {
    Object cellA = rowA[columnIndices[col]];
    Object cellA = rowA[columnIndices[col]];
    int result = comparators[columnIndices[col]].compare(cellA, cellB);
    if (result != EQUALS)
       return result;
 }
 return EQUALS;
 

Parameters:

columnIndices - an array of column indices to use for sorting. Table column indices are 1-based.

comparators - the comparators to use to compare table cells comparators.length must not be less than columnIndices.length. If any comparators[col] is null, for a column col use getColumnComparator(col)

startRowIndex - the index of the first row of the range of rows to sort.

endRowIndex - one greater than then index of the last row of the range of rows to sort, or -1 to include all rows through the end of the table. See also startRowIndex and endRowIndex above.

permutation - the permutation under which the table was sorted. This may be null; otherwise it must be initialized with the consecutive integers from 0 to table.getRowCount() - 1 (the permutation is 0 based). If non-null, the sort method will return the sort permutation in this int[] array See Permuter.identityPermutation(int)

Throws:

com.sas.table.TableException - if the table operation cannot be performed

permute

void permute(int[] permutation)
             throws com.sas.table.TableException

Permute a table according to a permutation array. This is similar to purmuting an ordered collection according to a permutaion, see Permuter.permute(com.sas.util.IndexedSetInterface,int[])

Parameters:

permutation - An array indicating how to permute the rows. For example, with a table of five rows, the permutation { 3, 1, 0, 4, 2 } will reorder the table as { row4, row2, row1, row5, row3 }. The permutation must contain exactly table.getRowCount() items ranging from 0 to table.getRowCount()-1 with no duplicate values. Note that permutations are 0 based while row numbers are one based.

Throws:

com.sas.table.TableException - if the table operation cannot be performed

removeDuplicates

void removeDuplicates(java.util.Comparator comparator,
                      int startRowIndex,
                      int endRowIndex,
                      boolean keepFirst,
                      boolean[] removed)
                      throws com.sas.table.TableException

Remove duplicates from a sorted table, based on comparing the row contents. This method assumes the table has already been sorted. Iterate across rows of the table starting at row startRowIndex and ending before row endRowIndex, and compare rows i and i+1 using the comparator, passing the row contents as a Object[] array. If the comparator returns 0, the rows are considered equal and the duplicate row is removed. If keepFirst is true, then remove row i+1, else remove row i.

Parameters:

comparator - a Comparator which compares entire rows. The values passed to this method are Object[] arrays or List objects. Use SimpleTable.getCell(Object row, int columnIndex) to extract a cell from this row for use in the comparator. If comparator is null, a Comparator is made from combining all column comparators.

startRowIndex - the index of the first row of the range of rows to search for duplicates.

endRowIndex - one greater than then index of the last row of the range of rows to search for duplicates, or -1 to include all rows through the end of the table. See also startRowIndex and endRowIndex above.

keepFirst - if true, then when comparing rows i and i+1, row i+1 is removed when equal. If false, row i is removed when equal.

removed - Flags indicating which items were removed. If row i was removed, then removed[i-1] is set to true, else false. This parameter may be null if you do not need to record the removed rows. Otherwise, it must contain table.getRowCount() elements. This array is zero based, whereas row numbers are one based. This method does not change elements of removed outside of the range of rows specified by endRowIndex and endRowIndex.

Throws:

com.sas.table.TableException - if the table operation cannot be performed

removeDuplicates

void removeDuplicates(int columnIndex,
                      java.util.Comparator comparator,
                      int startRowIndex,
                      int endRowIndex,
                      boolean keepFirst,
                      boolean[] removed)
                      throws com.sas.table.TableException

Remove duplicates from a sorted table, based on comparing cell contents from a single column. This method assumes the table has already been sorted. Iterate across rows of the table starting at row startRowIndex and ending before row endRowIndex, and compare cells [i][columnIndex] and [i+1][columnIndex] using the comparator. If the comparator returns 0, the rows are considered equal and the duplicate row is removed. If keepFirst is true, then remove row i+1, else remove row i.

Parameters:

comparator - a Comparator which compares table cells. If null, use getColumnComparator(columnIndex).

startRowIndex - the index of the first row of the range of rows to search for duplicates.

endRowIndex - one greater than then index of the last row of the range of rows to search for duplicates, or -1 to include all rows through the end of the table. See also startRowIndex and endRowIndex above.

keepFirst - if true, then when comparing rows i and i+1, row i+1 is removed when equal. If false, row i is removed when equal.

removed - Flags indicating which items were removed. See the same parameter in removeDuplicates(Comparator,int,int,boolean,boolean[])

Throws:

com.sas.table.TableException - if the table operation cannot be performed

removeDuplicates

void removeDuplicates(int[] columnIndices,
                      java.util.Comparator[] comparators,
                      int startRowIndex,
                      int endRowIndex,
                      boolean keepFirst,
                      boolean[] removed)
                      throws com.sas.table.TableException

Remove duplicates from a sorted table, based on comparing cell contents from multiple columns. This method assumes the table has already been sorted. Iterate across rows of the table starting at row startRowIndex and ending before row endRowIndex, and compare rows as described in sort(int[],Comparator[],int,int,int[]). If the comparator returns 0, the rows are considered equal and the duplicate row is removed. If keepFirst is true, then remove row i+1, else remove row i.

Parameters:

comparator - a Comparator which compares table cells.

startRowIndex - the index of the first row of the range of rows to search for duplicates. Normally, this is 1

endRowIndex - one greater than then index of the last row of the range of rows to search for duplicates, or -1 to include all rows through the end of the table, See also startRowIndex and endRowIndex above.

keepFirst - if true, then when comparing rows i and i+1, row i+1 is removed when equal. If false, row i is removed when equal.

removed - Flags indicating which items were removed. See the same parameter in removeDuplicates(Comparator,int,int,boolean,boolean[])

Throws:

com.sas.table.TableException - if the table operation cannot be performed

deleteRows

void deleteRows(boolean[] delete)
                throws com.sas.table.TableException

Delete rows as indicated in an array of flags.

Parameters:

delete - If delete[i] is set to true, remove row i+1. The delete array must contain table.getRowCount() elements. This array is zero based, whereas row numbers are one based. The delete array may be obtained from one of the removeDuplicates methods listed in this interface. For example, if you wish to keep two or more tables in sync and you remove duplicate rows from table A, you can have the removeDuplicates method record the deleted rows and then use this mthod to remove the same rows from tables B and C.

Throws:

com.sas.table.TableException - if the table operation cannot be performed

getColumnComparator

java.util.Comparator getColumnComparator(int columnIndex)
                                         throws com.sas.table.TableException

Return the comparator associated with this column.

Throws:

com.sas.table.TableException - if the table operation cannot be performed

setColumnComparator

void setColumnComparator(int columnIndex,
                         java.util.Comparator comparator)
                         throws com.sas.table.TableException

Throws:

com.sas.table.TableException

reverseColumnComparator

void reverseColumnComparator(int columnIndex)
                             throws com.sas.table.TableException

Reverse the sense of the comparator for column columnIndex. This method is useful for toggling the sort order for a column. You must still invoke the correct sort method to sort the table. If the comparator assigned to a column is already a ReverseComparator, replace it with the root comparator, ReverseComparator.getComparator(), else, replace the comparator with new ReverseComparator(getColumnComparator(columnIndex))

Parameters:

columnIndex - the column index whose comparison function you wish to reverse.

Throws:

com.sas.table.TableException - if the table operation cannot be performed

isRowsDeletable

boolean isRowsDeletable()
                        throws com.sas.table.TableException

Returns the value of the rowsDeletable property. rowsDeletable indicates whether or not rows can be deleted. Performing a removeDuplicates operation requires that this method return true.

Returns:

true if rows can be deleted, false otherwise.

Throws:

com.sas.table.TableException