All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Components |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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`

All Libraries | This Library | Package | Class | Use | Tree | Deprecated | Index | Grand Index | Help
|  | Components |
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2009 SAS Institute Inc. All Rights Reserved.