/** File: FileTable.java */

import java.io.*;

/**
 * This class reads tab-delimited data from files into a Table and 
 * can write data to files. The term Table (upper case 'T') denotes
 * the FileTable data structure. The class also parses tab-delimited 
 * data with or without a header (1 to n-lines of header) from a 
 * file into a Table 
 *    <B>(tRows,tCols,tHdrRows,tPreface,tHeader,tFields,tData)</B>.
 *<P>
 * If there are multiple header lines, it uses the last header line as
 * the tFields[] data.  You can optionally check for duplicate files 
 * and ignore them otherwise it is a parsing error.
 * <P>
 * You can optionally search the input file for a blank line after which
 * the actually header appears. You can also specify a keyword in the 
 * header line to denote where the Table starts. You can remove blank 
 * lines at the end of the file to shorten the table length. It can be 
 * used to create an empty table (not associated with a file).
 *
 * <P>
 * <PRE>
 * <U><B>List of Methods</B></U>
 * FileTable() - Constructor, set some defaults. 
 * FileTable(tableName) - Constructor, set some defaults. 
 * FileTable(tableName, rows, cols) - Constructor, set some defaults.
 * clearTable() - set to empty table. Generally called from Constructor
 * cloneTable() - clone the current Table. Copy data by value.
 * setNbrTableHdrLines() - number of lines of the Table header.
 * setHasTableHeaderFlag() - set Has Table Header Flag.
 * setDuplicateFieldsFlag() - set duplicate fields Flag.
 * setHasEmptyLineBeforeTableFlag() - set look for empty line(s) BEFORE table
 * setRmvTrailingBlankLinesFlag() - remove trailing blank lines in the Table
 * setRmvTrailingEmptyColumnsFlag() - set remove empty trailing columns flag.
 * setStartTableAtColStr() - start Table at string known to be in header.
 * setColNameIndexMapKeys() - set column names keys for ftIdxMap index-map.
 * setUseOnlyLastHeaderLineFlag() - set use only last header line flag
 * readTableRowFromFile() - random access read row r tokens from indexed file.
 * readLineRowFromFile() - random access read row r data from indexed file.
 * checkForBadTable() - verify that it is a well formed table
 * checkForBadTableHeader() - verify that is a well formed tField Table
 * parseTableFromString() - convert tab-delim string to Table structure.
 * readAndParseTableIndexMap() - read tab-delim file to Table Index-Map.
 * readAndParseTableAll() - read & convert tab-delim file to Table & ftIdxMap.
 * readAndParseTable() - read & convert tab-delim file to Table structure.
 * readAndParseTableFields() - read tab-delim file to tFields Table structure.
 * readAndParseTableFieldsAndIndexMap - read tab-delim file tFields & ftIdxMap
 * readAndParseTableData() - read & convert tab-delim file to Table structure.
 * computeFileLineTermSize() - compute a file's line terminator size.
 * cvtTableToTabDelimStr() - convert table to tab delimited string
 * rmvTrailingBlankLinesFromTable() - remove Table trailing blank lines.  
 * deleteTableColumnByName() - delete a column from the Table.
 * deleteTableColumnByColIdx() - delete a column from table by column index
 * lookupFieldIdx() - lookup column index of field if exists.
 * lookupRowFromColumnData() - lookup row index from column data if exists.
 * lookupCol2DataFromCol1DataRow() - lookup col2 data from row w/col1 data match
 * appendRowToTable() - append row of data to table.
 * removeRowFromTable() - remove row of data from table.
 * deleteRowsFromTable() - delete rows from the Table and resize the Table.
 * deleteTrailingEmptyColumnsFromTable() - removes empty trailing columns
 * mapHeaderColNames() - map tField & tHeaders old to new names in map list.
 * setFieldsToTable() - set the Fields list to the Table and set tCols.
 * setHeadersToTable() - set the Headers list to the Table and set tHdrRows.
 * addEmptyColumnToExistingTable() - add empty column to existing Table.
 * addColumnToTable() - add a new column to Table with  specified field name. 
 * replaceColumnData() - replace data in a column in the Table.
 * setColumnDataByValue() - set all data in a column in Table to a value.
 * getColumnData() - lookup the column name and then return all column data.
 * reorderRowsBySortIndex() - reorder the entire table rows by the sortIdx.
 * reorderColumnsInTable() - reorder Table tFields & tData by column index
 * joinTableToCurrentTable() - join another Table ftJoin to current Table.
 * trimTableEnclWhitespace() - trim (clean) enclosing white space in Table.
 * trimArrayEnclWhitespace() - trim (clean) enclosing white space in a 1D array.
 * sortTableRowsByField() - sort table rows by field.
 * limitMaxRows() - keep max nbr rows in front of the Table.
 * limitMaxRowsSortedByField() - sort Table by field, then keep max nbr rows
 * </PRE>
 * 
 * <P> 
 * This code is available at the HTMLtools project on SourceForge at
 * <A HREF="http://htmltools.sourceforge.net/">http://htmltools.sourceforge.net/</A>
 * under the "Common Public License Version 1.0" 
 * <A HREF="http://www.opensource.org/licenses/cpl1.0.php">
 * http://www.opensource.org/licenses/cpl1.0.php</A>.<P></P>
 * <P>
 * It was derived and refactored from the open source
 * MAExplorer (http://maexplorer.sourceforge.net/), and
 * Open2Dprot (http://Open2Dprot.sourceforge.net/) Table modules.
 * <P>
 * $Date: 2009/11/23 11:45:56 $ $Revision: 1.37 $
 * <BR> 
 * Copyright 2008, 2009 by Peter Lemkin 
 * E-Mail: lemkin@users.sourceforge.net 
 * <A HREF="http://lemkingroup.com/">http://lemkingroup.com/</A>
 * <BR>
 */

public class FileTable extends FileIO
{    
     
  /** Global utilities UtilCM instance */
  public UtilCM
    util;
  
  /** Set to true (default) if has table header). */
  public boolean 
    hasTableHeaderRowFlag;
  
  /** Set to true if has table may have duplicate fields. */
  public boolean 
    ignoreDuplicateFieldsFlag;

  /** Set to true to look for empty line(s) BEFORE the table data */
  public boolean
    hasEmptyLineBeforeTableFlag;
  
  /** Set to true if remove trailing blank lines from the table */
  public boolean
    rmvTrailingBlankLinesFlag;
  
  /** Set to true to remove empty trailing columns defined as columns
   * in a Table with a header as null column names.
   */
  public boolean
    rmvTrailingEmptyColumnsFlag;
  
  /** Set to string known to be in header. When parsing the
   * table input string, we look for this value to determine the
   * line where the Table starts.
   */
  public String 
    startTblColStr; 
  
  /** Reduce the number of header lines to 1 even if there are more 
   * than 1 header line. 
   */
  public boolean
    useOnlyLastHeaderLineFlag;
  
  /** size of input buffer */
  public int
    bufSize;      
  
  /** List of unmodified tField names, if not null with size 
   * nUnmodifiedFieldNames. This is the maximum size of tFields[],
   * i.e., tCols and may be setup by other methods in other classes
   * (e.g., see Convert..
  */
  public String 
    unmodifiedFieldNames[]= null;

  /** Size of unmodifiedFieldNames[], the list of unmodified tField[] 
   * names. 
   */
  public int
    nUnmodifiedFieldNames= 0;

  /** Line number of the first row with table data
   * (Table Fields or Data if no Fields) */
  public int
    firstDataRowLineNbr;
  
  /** Char index of input buffer first row with table data
   * (Table Fields or Data if no Fields).
   */  
  public int
    firstDataRowCharIdx; 
  
  /** Number of lines of the Table header "-hdr:{nbr of lines in header}"
   * switches. The number of Table header lines with default of 1. 
   * If > 1 line, then the Table Fields searched for URL mapping are the
   * last one in the header row. All header lines are bolded with TH 
   * rather than TD.  The tokens for the last of these header lines is 
   * also saved in lastTblHdrRow[0:tCols] to be used by the Column to 
   * URL mapping...
   */
  public int
    nbrTableHdrLines= 1;
  
  /** file to read or write I/O */
  public String
    fileName;

  /** number of header rows (default is 1) */
  public int
    tHdrRows;            
  /** number of columns/row in the table. */
  public int
    tCols;         
  /** number of rows. i.e. number row Clone Id's */
  public int
    tRows;     
  
  /** Table name if any */
  public String
    tName;   
  
  /** Table preface if any. This is parsed from the initial text
   * prior to the actual table if it was separated by a
   * blank line or the table defined by a tField keyword.
   */
  public String
    tPreface;   
  
  /** names of table headers of size [0:tHdrRows-1][0:tCols-1].
   * Some of the non-primary (i.e., tField[]) header rows may not have
   * tCols of data (i.e., short rows). These are filled with "".
   */
  public String
    tHeader[][]; 
  
  /** names of table fields. These are the primary table column names. */
  public String
    tFields[];
  
  /** row data cell vectors [0:tRows-1][0:tCols-1] */
  public String
    tData[][];  

  /* ---- Index-maps of the data for random access of the data ---- */
  
  /** Index-map byte pointers of the start of header lines synced 
   * with tHeader rows. 
   */
  public long
    lineStartHeaderBytePtr[];  
  
  /** Index-map byte pointers of the start of header lines synced 
   * with tHeader rows. 
   */
  public long
    lineEndHeaderBytePtr[]; 
  
  /** Index-map byte pointers of the start of data lines synced 
   * with tData rows. 
   */
  public long
    lineStartDataBytePtr[];  
  
  /** Index-map byte pointers of the start of data lines synced 
   * with tData rows. 
   */
  public long 
    lineEndDataBytePtr[];
  
  /** List of column names to be used in the left side of the ftIdxMap
   * Table if it is built. If it is null, do not build the index-map
   * since these column names are the keys used to build the index-map 
   * Table.
   */
  public String 
    colNameIndexMap[]= null;

  /** FileTable index map where save the {colNames, "StartByte", "EndByte")
   * The colNames is a list with arbitrary names that can not be
   * either  "StartByte" or "EndByte".
   */
  public FileTable
    ftIdxMap= null;
  
  /** [HACK] If the table is sorted by sortTableRowsByField for numeric 
   * values with the useAbsValueFlag set true, and both + and - changes
   * were found, it will set the needToSortTableAgainFlag so the calling 
   * program can resort one more time if it wants to keep the data in 
   * numeric order.
   */
  public boolean 
    needToSortTableAgainFlag= false;
  
  /** This is the (sorted) full table data BEFORE the length of the table
   * was limited using limitMaxRowsXXX() methods. It is null unless
   * the Table was limited in number of rows. This is useful
   * if we need to get at the full Table later.
   */
  public String 
    tDataFull[][]= null;

  /**
   * FileTable() - generic Constructor, set some defaults to 0.
   */
  public FileTable()
  { /* FileTable */
    clearTable();                /* set to empty table */
    util= new UtilCM();          /* set up utility package */    
  } /* FileTable */
  
  
  /**
   * FileTable() - generic Constructor, set some defaults.
   * @param tableName String name of table
   * @see UtilCM
   * @see #setDuplicateFieldsFlag
   * @see #setNbrTableHdrLines
   * @see #setRmvTrailingBlankLinesFlag
   * @see #setHasEmptyLineBeforeTableFlag
   */
  public FileTable(String tableName)
  { /* FileTable */
    clearTable();                /* set to empty table */
    util= new UtilCM();          /* set up utility package */
    
    this.tName= tableName;
  } /* FileTable */
  
  
  /**
   * FileTable() - Constructor to make empty table of known size
   * @param tableName String name of table
   * @param rows max rows in table
   * @param cols max columns in table
   * @see UtilCM
   * @see #setDuplicateFieldsFlag
   * @see #setNbrTableHdrLines
   * @see #setRmvTrailingBlankLinesFlag
   * @see #setHasEmptyLineBeforeTableFlag
   */
  public FileTable(String tableName, int rows, int cols)
  { /* FileTable */
    clearTable();                /* set to empty table */
    util= new UtilCM();          /* set up utility package */
    
    this.tName= tableName;
    this.tRows= rows;
    this.tCols= cols;    
  } /* FileTable */
  

  /**
   * clearTable() - set to empty table. Generally called from Constructor
   */
  public void clearTable()
  { /* clearTable */

    fileName= null;
    tName= "none";
    tRows= 0;
    tCols= 0;
    tHdrRows= 0;
        
    tFields= null;
    tHeader= null;
    tData= null;
    tDataFull= null;
    tPreface= null;   

    unmodifiedFieldNames= null;
    nUnmodifiedFieldNames= 0;
    
    errMsgLog= "";
    lastErrMsgLog= "";
    
    startTblColStr= null;
    firstDataRowLineNbr= 0;
    firstDataRowCharIdx= 0;
    
    lineStartHeaderBytePtr= null;
    lineEndHeaderBytePtr= null;
    lineStartDataBytePtr= null;
    lineEndDataBytePtr= null;    
    
    /* Set the rest using set methods */
    setHasTableHeaderFlag(true);
    setDuplicateFieldsFlag(false);
    setNbrTableHdrLines(1);
    setHasEmptyLineBeforeTableFlag(false);
    setRmvTrailingBlankLinesFlag(false);
    setRmvTrailingEmptyColumnsFlag(false);
    setStartTableAtColStr(null);
    useOnlyLastHeaderLineFlag= false;
    
    needToSortTableAgainFlag= false;
  } /* clearTable */  
  
  
  /**
   * cloneTable() - clone the current Table. Copy data by value.
   * @param cloneTableName is new tName of the clone
   * @param return FileTable instance of clone if successful, else null.
   */
  public FileTable cloneTable(String cloneTableName)
  { /* cloneTable */
    FileTable ftC= new FileTable(cloneTableName);

    ftC.setHasTableHeaderFlag(this.hasTableHeaderRowFlag);
    ftC.setDuplicateFieldsFlag(this.ignoreDuplicateFieldsFlag);
    ftC.setNbrTableHdrLines(this.nbrTableHdrLines);
    ftC.setRmvTrailingBlankLinesFlag(this.rmvTrailingBlankLinesFlag);
    ftC.setRmvTrailingEmptyColumnsFlag(this.rmvTrailingEmptyColumnsFlag);
    ftC.setHasEmptyLineBeforeTableFlag(this.hasEmptyLineBeforeTableFlag);
    ftC.setStartTableAtColStr(this.startTblColStr);
    ftC.setUseOnlyLastHeaderLineFlag(this.useOnlyLastHeaderLineFlag);

    ftC.setFieldsToTable(this.tFields);
    ftC.setHeadersToTable(this.tHeader, this.tHdrRows, this.tCols);
    ftC.tRows= this.tRows;
    
    if(this.tData==null)
      ftC.tData= null;
    else
    { /* Copy the data by value */
      ftC.tData= new String[tRows][];
      for(int r=0;r<tRows;r++)
      {
        String rowData[]= new String[tCols];
        for(int c=0;c<tCols;c++)
          rowData[c]= new String(this.tData[r][c]);
        ftC.tData[r]= rowData;
      }
      ftC.tRows= this.tRows;
    } /* Copy the data by value */
       
    return(ftC);
  } /* cloneTable */ 
  
  
  /**
   * setNbrTableHdrLines() - number of lines of the Table header.
   * The number of Table header lines with default of 1. If > 1 line, 
   * then the Table Fields searched for URL mapping are the last one 
   * in the header row.
   * The tokens for the last of these header lines is also saved in 
   * lastTblHdrRow[0:tCols] to be used by the Column to URL mapping.
   * The last header row is also saved in tFields[0:tcols-1].
   * All headers are saved in tHeader[0:tHdrRows-1][0:tCols] where
   * tCols is determined by the last header row.
   * Must have at least 1 line.
   * @param nbrTableHdrLines value
   */
  public void setNbrTableHdrLines(int nbrTableHdrLines)
  { /* setNbrTableHdrLines */ 
    this.nbrTableHdrLines= (nbrTableHdrLines<1)? 1 : nbrTableHdrLines;
    tHdrRows= this.nbrTableHdrLines;
  } /* setNbrTableHdrLines */
  

  /**
   * setHasTableHeaderFlag() - set Has Table Header Flag.
   * @param hasTableHeaderRowFlag value
   */
  public void setHasTableHeaderFlag(boolean hasTableHeaderRowFlag)
  { /* setHasTableHeaderFlag */
    this.hasTableHeaderRowFlag= hasTableHeaderRowFlag;
  } /* setHasTableHeaderFlag */
  

  /**
   * setDuplicateFieldsFlag() - set duplicate fields Flag.
   * @param ignoreDuplicateFieldsFlag value
   */
  public void setDuplicateFieldsFlag(boolean ignoreDuplicateFieldsFlag)
  { /* setDuplicateFieldsFlag */ 
    this.ignoreDuplicateFieldsFlag= ignoreDuplicateFieldsFlag;
  } /* setDuplicateFieldsFlag */

  
  /**
   * setHasEmptyLineBeforeTableFlag() - set look for empty line(s) 
   * BEFORE table data flag
   * @param hasEmptyLineBeforeTableFlag value
   */
  public void setHasEmptyLineBeforeTableFlag(
                                    boolean hasEmptyLineBeforeTableFlag)
  { /* setHasEmptyLineBeforeTableFlag */ 
    this.hasEmptyLineBeforeTableFlag= hasEmptyLineBeforeTableFlag;
  } /* setHasEmptyLineBeforeTableFlag */
      

  /**
   * setRmvTrailingBlankLinesFlag() - remove trailing blank lines in 
   * the table by shortening the end of the table.
   * @param rmvTrailingBlankLinesFlag value
   */
  public void setRmvTrailingBlankLinesFlag(
                                       boolean rmvTrailingBlankLinesFlag)
  { /* setRmvTrailingBlankLinesFlag*/ 
    this.rmvTrailingBlankLinesFlag= rmvTrailingBlankLinesFlag;
  } /* setRmvTrailingBlankLinesFlag */
  

  /** 
   * setRmvTrailingEmptyColumnsFlag() - set remove empty trailing columns 
   * flag. Empty columns are defined as columns in a Table with a 
   * header as null column names. If the flag is set, after the table is 
   * created, we define tFields for the first empty cell. We then 
   * rebuild tFields, tHeader and tData to the new size and set tCols 
   * to the new size.
   * @param rmvTrailingEmptyColumnsFlag value
   */
  public void setRmvTrailingEmptyColumnsFlag(
                                      boolean rmvTrailingEmptyColumnsFlag)
  { /* setRmvTrailingEmptyColumnsFlag */ 
    this.rmvTrailingEmptyColumnsFlag= rmvTrailingEmptyColumnsFlag;
  } /* setRmvTrailingEmptyColumnsFlag */

  
  /** 
   * setStartTableAtColStr() - start Table at string known to be in header.
   * @param startTblColStr - value that is known to be in the header 
   */
  public void setStartTableAtColStr(String startTblColStr)
  { /* setStartTableAtColStr */ 
    this.startTblColStr= startTblColStr;
  } /* setStartTableAtColStr */
  
  
  /** 
   * setColNameIndexMapKeys() - set column names keys for ftIdxMap index-map.
   * If it is null, do not build the index-map since these column names 
   * are the keys used to build the index-map Table.
   * @param colNameIndexMap - list of column names keys for ftIdxMap index-map.
   */
  public void setColNameIndexMapKeys(String colNameIndexMap[])
  { /* setColNameIndexMapKeys */ 
    this.colNameIndexMap= colNameIndexMap;
  } /* setColNameIndexMapKeys */
  
  
  /** 
   * setUseOnlyLastHeaderLineFlag() - set reduce number of header lines to 1
   * even if there are more than 1 header lines. If the tHeader list exists,
   * it shrinks it to 1 row and copies the previous last tHeader to to the
   * new list. 
   * @param useOnlyLastHeaderLineFlag - value to set the flag.
   */
  public void setUseOnlyLastHeaderLineFlag(boolean useOnlyLastHeaderLineFlag)
  { /* setUseOnlyLastHeaderLineFlag */ 
    this.useOnlyLastHeaderLineFlag= useOnlyLastHeaderLineFlag;
    
    if(useOnlyLastHeaderLineFlag &&
      (tHeader!=null && tHdrRows>1 && tCols>0 && tFields!=null))
    { /* Reduce the number of headers to 1 in the list */
      String newTheader[][]= new String[1][];
      newTheader[0]= tHeader[tHdrRows-1];
      
      tHeader= newTheader;   /* Set so only the last row of the header list */
      tHdrRows= 1;
    } /* Reduce the number of headersto 1 in the list */
  } /* setUseOnlyLastHeaderLineFlag */
  
  
  /**
   * readTableRowFromFile() - random access read row r token list from 
   * indexed file.  This assumes that there is a ftIdxMap FileTable created 
   * by MakeIndexFile for the file or.
   * @param fileName file name
   * @param r is the row to retrieve
   * @param ftIdxMap is the FileTable index previously created by 
   *          MakeIndexFile for the file.
   * @param nullFillStr is the string to replace all null strings
   *          if not null.
   * @return string row of file if successful, else null if any errors.
   * @see FileIO#readRandomAccessLine
   */
  public String[] readTableLineRowFromFile(String fileName, int r, 
                                           FileTable ftIdxMap,
                                           String nullFillStr)
  { /* readTableLineRowFromFile */
    String lineData= readLineRowFromFile(fileName, r, ftIdxMap);
    if(lineData==null)
      return(null);
    String tokenList[]= UtilCM.cvs2ArrayNullFill(lineData, "\t", 
                                                 nullFillStr);
    return(tokenList);
  } /* readTableLineRowFromFile */
  
       
  /**
   * readLineRowFromFile() - random access read row r data from indexed file.
   * This assumes that there is a ftIdxMap FileTable created by 
   * parseTableFromString(), readAndParseTableIndexMap(), readAndParseTable().
   * or MakeIndexFile for the file.
   * @param fileName file name
   * @param r is the row to retrieve
   * @param ftIdxMap is the FileTable index previously created by 
   *          MakeIndexFile for the file.
   * @return string row of file if successful, else null if any errors.
   * @see FileIO#readRandomAccessLine
   */
  public String readLineRowFromFile(String fileName, int r, 
                                    FileTable ftIdxMap)
  { /* readLineRowFromFile */
    if(ftIdxMap==null || !ftIdxMap.fileName.equals(fileName))
      return(null);
    if(r>=tRows)
      return(null);
    
    /* Get the start and end byte pointers on the disk */
    int
      idxStartByte= ftIdxMap.lookupFieldIdx("StartByte"),
      idxEndByte= ftIdxMap.lookupFieldIdx("EndByte");
    if(idxStartByte==-1 || idxEndByte==-1)
      return(null);
    String
      mapRowData[]= ftIdxMap.tData[r],
      strStartByte= mapRowData[idxStartByte],
      strEndByte= mapRowData[idxEndByte];
    long 
      startBytePtr= UtilCM.cvs2l(strStartByte,-1),
      endBytePtr= UtilCM.cvs2l(strEndByte,-1);
    if(startBytePtr==-1 || endBytePtr==-1)
      return(null);
    
    /* Now read the data. Just read from startBytePtr until
     * end-of-line.
     */
    String rawData= readRandomAccessLine(fileName,startBytePtr);
    int expectedLth= (int)(endBytePtr-startBytePtr+1);
    if(rawData.length()!=expectedLth)
    {
      UtilCM.logMsg("I/O error file '"+fileName+
                    "' read.length="+rawData.length()+
                    " NEQ (endBytePtr-startBytePtr+1)="+expectedLth+
                    " startBytePtr="+startBytePtr+
                    " endBytePtr="+endBytePtr+
                    " for row="+r+"\n");
      return(null);
    }
    
    return(rawData);
  } /* readLineRowFromFile */ 
         
  
  /**
   * checkForBadTable() - verify that it is a well formed Table
   * with all field names present and with no null, "" or duplicate 
   * entries, and tRows EQ tData.length.
   * @return true if successful, also stuff error message into
   *         "errMsgLog" to be displayed later.
   */
  public boolean checkForBadTable()
  { /* checkForBadTable */
    
    if(tData!=null && tData.length!=tRows)
     {
       errMsgLog += "FT-CFBT bad Table["+tName+
                    "] data row size tData.length="+
                    tData.length+" tRows="+tRows+"\n";
       lastErrMsgLog= errMsgLog;
       return(false);
     }
    
    /* Check the header */
    if(!checkForBadTableHeader())
      return(false);
        
    return(true);
  } /* checkForBadTable */
  
  
  /**
   * checkForBadTableHeader() - verify that is a well formed tField Table
   * with all field names present and with no null, "" or duplicate 
   * entries.
   * @return true if successful, also stuff error message into
   *         "errMsgLog" to be displayed later.
   */
  public boolean checkForBadTableHeader()
  { /* checkForBadTableHeader */
    if(hasTableHeaderRowFlag && tCols<=0)
    {
      errMsgLog += "FT-CFBTH bad Table tCols="+tCols+"\n";
      return(false);
    }
    
    if(hasTableHeaderRowFlag && 
       (tFields==null || tFields.length!=tCols))
    {
      errMsgLog += "FT-CFBTH bad Table["+tName+"] tFields.length="+
                   tFields.length+" NEQ tCols="+tCols+"\n";
      lastErrMsgLog= errMsgLog;
      return(false);
    }
    
    /* Look for errors: null, "" or duplicate Field name entries */
    if(hasTableHeaderRowFlag)
    { /* has table - check it */
      for(int c=0;c<tCols;c++)
      { /* check fields */
        if(tFields[c]==null) //|| tFields[c].equals(""))
        {
          errMsgLog += "FT-CFBTH bad Table["+tName+
                       "] has empty tFields["+c+"]\n";
          lastErrMsgLog= errMsgLog;
          return(false);
        }
        
        if(tHeader==null && tHdrRows>=1)
        {
          errMsgLog += "FT-CFBTH bad Table["+tName+
                       "] no tHeader data.\n";
          lastErrMsgLog= errMsgLog;
          return(false);
        }
        
        if(tHeader!=null && !tFields[c].equals(tHeader[tHdrRows-1][c]))
        {
          errMsgLog += "FT-CFBTH bad Table["+tName+"] tFields["+c+
                       "] NEQ last tHeader["+(tHdrRows-1)+"]["+c+
                       "].\n";
          lastErrMsgLog= errMsgLog;
          return(false);
        }
        
        if(!ignoreDuplicateFieldsFlag)
          for(int c2= 0; c2 < tCols; c2++)
            if(c != c2 && tFields[c].equals(tFields[c2]))
            {
              errMsgLog += "FT-CFBT bad Table["+tName+
                           "] dupl. fields: #" + c + 
                           " and #" + c2 + " [" + tFields[c] + 
                           "] with value='"+tFields[c]+"'\n";
              lastErrMsgLog= errMsgLog;
              return (false);
            }
        } /* check fields */
    } /* has table - check it */
    
    return(true);
  } /* checkForBadTableHeader */
  
  
  /**
   * parseTableFromString() - convert tab-delim string to Table structure.
   * Set up the table data structures in this instance of FileTable:
   *  (tHeader,tPreface,tRows,tCols,tFields[],tData[][],tCols,tRows,tHdrNbr).
   * <P> 
   * If the table is not at the front of the file, one option is to
   * find the start of the table by searching for a this.startTblColStr 
   * string if you know a unique string in the header row. This is used 
   * if startTblColStr is not blank (set by setStartTableAtColStr()). 
   * If it matches, we then search backwards to the front of the string 
   * for a '\n' which is the  end of the previous row.
   * <P>
   * An alternate method for finding the start of the file, if the
   * this.hasEmptyLineBeforeTableFlag is set, is to look for the first 
   * non-empty empty row after seeing an empty row that it is then 
   * assumed to be the Table data (Fields + data or data) follows. 
   * This can be problematic if there are multiple blank lines.
   *<P> 
   * When the front of the table is found, then it sets
   * this.firstDataRowLineNbr to that line number.
   * If there is no empty row found, then it assumes there is no extra
   * data before the table and it sets this.firstDataRowLineNbr to 0.
   * If there is text before the Table, then it is put into this.tPreface.
   * <P>
   * @param tblStr is String to parse and convert to Table
   * @return true if successful, else errMsgLog has reason failed.
   * @see #rmvTrailingBlankLinesFromTable
   * @see #deleteTrailingEmptyColumnsFromTable
   * @see #checkForBadTable
   */
  public boolean parseTableFromString(String tblStr)
  { /* parseTableFromString */
    if(tblStr==null)
      return(false);
    
    /* [1] Setup parser variables */
    int
      tDataSize= 0,
      nbrRowsIncr= 100,
      lineTermSize= 0,
      countLines= 0,            /* local line counter */
      countMoreHdrLines= 0;     /* used to save hdr lines before parse
                                 * after found blank line */
    long
      startByte= 0, /* buffer ptr at start of a line */
      endByte= 0;   /* buffer ptr at end of a line */
    
    /* [1.1] Find terminator as either \r, \n or \r\n  */
    String  
      lineSep= this.getLineSeparatorFromString(tblStr);
    
    /* Set to the first line of tData when found */
    firstDataRowLineNbr= -1;
    
    /* [2] Read and parse the tab-delimited data file into the Table
     * and get the tPreface as all data before the Header.
     */
    /* Read file and parse data into Table */
      /* [2.1] Get the file line separator and it's size. 
       * It is either \r, \n or \r\n - or null if an error */
      if(lineSep==null)
      { /* Handle errors */
        errMsgLog += "MIF-RAPF no \r, \n or \r\n terminator in " +
        	         	"input string.\n";
        lastErrMsgLog= errMsgLog;
        return (false);
      }      
      lineTermSize= lineSep.length();
           
      /* [2.2] Init parse variables */
      String 
        lookbackHdrs[]= new String[nbrTableHdrLines],
        tokens[]= null,           /* list of tokens in the inputLine */
        inputLine = null;         /* lines read from buffered reader */
      long
        lookbackStartBytePtr[]= new long[nbrTableHdrLines+1],
        lookbackEndBytePtr[]= new long[nbrTableHdrLines+1];
      
      boolean    
        foundDataRowFlag= false,
        foundHdrRowFlag= false;  /* We saw header row in file, else error */

      tHdrRows= nbrTableHdrLines;
      tRows= 0;                   /* count first row */
      tCols= 0;                   /* there is at least 1 Row if fields*/
    
      /* [3] Read lines from the input file */
      int
        fromIndex= 0,
        idx= 0;
      while(fromIndex!=-1 && idx!=-1)
      { /* process lines */
        idx= tblStr.indexOf(lineSep, fromIndex);
        if(idx==-1)
          inputLine= tblStr;
        else
        {
          inputLine= tblStr.substring(fromIndex,idx);
          fromIndex= idx+lineTermSize;  /* advance the line pointer */ 
        }
        countLines++;
                       
        /* [3.1] Parse the Header and save header lines, backwards,
         * for parsing into the tHeader and tFields.
         */
        if(!foundHdrRowFlag)
        { /* save until parsed header */
          /* [3.1.1] Save Preface with stuff falling out of lookback */
          String prefaceLine= lookbackHdrs[tHdrRows-1];
          if(prefaceLine!=null)
          { /* only push non-null lines to the tPreface */
            if(tPreface==null)
              tPreface= prefaceLine +"\n";
            else
              tPreface += prefaceLine +"\n";
          }
          
          /* [3.1.2] Push data back into the look back list */
          for(int lb=(tHdrRows-2); lb>=0; lb--)
          { /* lb is backwards index */
            lookbackHdrs[lb+1]= lookbackHdrs[lb]; 
            lookbackStartBytePtr[lb+1]= lookbackStartBytePtr[lb]; 
            lookbackEndBytePtr[lb+1]= lookbackEndBytePtr[lb];
          }

          /* [3.2] Compute the line byte pointers with terminator */
          startByte= endByte+1;
          endByte += inputLine.length() + lineTermSize; 
          
          /* [3.3] Save current line at end of look back stack. */
          lookbackHdrs[0]= inputLine;
          lookbackStartBytePtr[0]= startByte;
          lookbackEndBytePtr[0]= endByte;
               
          /* [3.4] Read the rest of the header lines. */
          if(countMoreHdrLines>0)
          { /* save more header lines until ready to parse */
            if(--countMoreHdrLines<=0)
              foundHdrRowFlag= true;
            else
              continue;  /* keep saving lines */
          }
          
          /* [3.5] Look for the header starting with specific 
           * string in the tFields (last row of the tHeader.
           */
          if(startTblColStr!=null)
          { /* look for string known in header for start of Table */
            int idxKeyword= inputLine.indexOf(startTblColStr);
            if(idxKeyword!=-1)
            { /* Found the header tFields row */
              foundHdrRowFlag= true;
            }
          }
        
          /* [3.6] Alternately, look for empty line after which the table 
           * will start. This can be problematic if there are multiple 
           * blank lines.
           */
          else if(hasEmptyLineBeforeTableFlag)
          {  /* scan through the preface */          
            if(inputLine.length()==0)
            { /* found empty line - assume before header */
              countMoreHdrLines= nbrTableHdrLines;
              continue;
            } /* found empty line - assume before header */
          } 
          else if(countLines>=tHdrRows)
          { /* captured header line since no empty lines before Table */
            foundHdrRowFlag= true;
          }

          /* [3.7] Continue scanning for the header */
          if(!foundHdrRowFlag && !foundDataRowFlag)
            continue;            /* keep scanning */

          /* [4] Found the header - save it in tFields and tHeader */
          else if(foundHdrRowFlag && !foundDataRowFlag)
          { /* Process the header rows */
            if(countLines==1)
              tPreface= null;        /* there is no preface */
            
            /* [4.1] Save the tFields[] */
            inputLine= lookbackHdrs[0]; 
            tFields= UtilCM.cvs2Array(inputLine, "\t");
            tCols= tFields.length;
            
            /* [4.2] Now save the header rows */
            tHeader= new String[tHdrRows][];
            lineStartHeaderBytePtr= new long[tHdrRows];
            lineEndHeaderBytePtr= new long[tHdrRows];
            for(int h=0;h<tHdrRows;h++)
            { /* process header line h in reverse order in look-back list */              
              inputLine= lookbackHdrs[(tHdrRows-1)-h];
              tokens= UtilCM.cvs2ArrayNullFill(inputLine, "\t","");
              
              /* Extend header rows that are less than tCols to tCols long
               * and set the new entries to "".
               */
              tokens= UtilCM.rightSizeArray(tokens, tCols,"");
              tHeader[h]= tokens; 
              
              /* Save Index-map byte pointers of start/end of header rows. */
              lineStartHeaderBytePtr[h]= lookbackStartBytePtr[(tHdrRows-1)-h]; 
              lineEndHeaderBytePtr[h]= lookbackEndBytePtr[(tHdrRows-1)-h];                
            } /* process header line h */ 
            
            /* Now we advance to the Data rows */
            foundDataRowFlag= true;
            continue;
          } /* Process the header rows */
        } /* save until parsed header */
         
        /* [5] Process data rows and capture the start/end byte pointers */
        else if(foundHdrRowFlag && foundDataRowFlag)
        { /* process the next data row */          
          /* Post process the state */
          if(firstDataRowLineNbr==-1)
            firstDataRowLineNbr= countLines;
          
          /* [5.1] Test if all out of data by seeing empty line. */
          if(inputLine.length()==0)
          { /* Done - empty rows at the end of the table */
            continue;               /* ignore empty lines */
          }
          tokens= UtilCM.cvs2Array(inputLine, "\t");
          
          if(UtilCM.isEmptyArray(tokens))
            continue;  /* ignore empty token list of "\t\t\t\t\t" form */
          
          if(tokens.length<tCols)
          { /* if row data size is < header size, then extend the row */
            errMsgLog += "Short data row["+tRows+"] with "+tokens.length+
                       " columns - extending it to "+tCols+
                       " and continuing...\n";
            lastErrMsgLog= errMsgLog;
            /* Extend header rows that are less than tCols to tCols long
             * and set the new entries to "".
             */
            tokens= UtilCM.rightSizeArray(tokens, tCols,"");
            //continue;
          }
          
          /* [5.2] If not enough room in the data arrays, then row the
           * arrays by nbrRowsIncr.
           */
          if(tData==null)
          { /* allocate arrays */
            tDataSize= nbrRowsIncr;
            tData= new String[tDataSize][];
            lineStartDataBytePtr= new long[tDataSize];
            lineEndDataBytePtr= new long[tDataSize];
          }
          else if(tRows>= tDataSize)
          { /* grow the arrays by nbrRowsIncr */
            tDataSize += nbrRowsIncr;
            String tDataNew[][]= new String[tDataSize][];
            long lineStartDataBytePtrNew[]= new long[tDataSize];
            long lineEndDataBytePtrNew[]= new long[tDataSize];
            for(int r=0;r<tRows;r++)
            { /* copy data */
              tDataNew[r]= tData[r];
              lineStartDataBytePtrNew[r]= lineStartDataBytePtr[r]; 
              lineEndDataBytePtrNew[r]= lineEndDataBytePtr[r]; 
            }
            tData= tDataNew;
            lineStartDataBytePtr= lineStartDataBytePtrNew; 
            lineEndDataBytePtr= lineEndDataBytePtrNew; 
          } /* grow the arrays by nbrRowsIncr */
          
          /* [5.3] Copy the data for this line to Table tData. */
          tData[tRows]= tokens;
          lineStartDataBytePtr[tRows]= startByte; 
          lineEndDataBytePtr[tRows]= endByte; 
          
          tRows++;
        } /* process the next data row */          
      } /* process lines */

      /* [6] Make the tData[] the actual number of rows */
      if(tRows < tDataSize)
      { /* shrink the arrays size to the exact size */
        String tDataNew[][]= new String[tRows][];
        long lineStartDataBytePtrNew[]= new long[tRows];
        long lineEndDataBytePtrNew[]= new long[tRows];
        for(int r=0;r<tRows;r++)
        { /* copy data */
          tDataNew[r]= tData[r];
          lineStartDataBytePtrNew[r]= lineStartDataBytePtr[r]; 
          lineEndDataBytePtrNew[r]= lineEndDataBytePtr[r]; 
        }
        tData= tDataNew;
        lineStartDataBytePtr= lineStartDataBytePtrNew; 
        lineEndDataBytePtr= lineEndDataBytePtrNew; 
      } /* shrink the arrays size to the exact size */ 
    
    if(rmvTrailingEmptyColumnsFlag)
      deleteTrailingEmptyColumnsFromTable();    
    
    if(!checkForBadTable())
      return(false);                /* valid data tFields data */        
              
    return(true);
  } /* parseTableFromString */

  
 /**
   * readAndParseTableIndexMap() - read tab-delim file to Table Index-Map.
   * Set up the table data structures in this instance of FileTable:<BR>
   *  (tHeader,tPreface,tRows,tCols,tFields[],tCols,tRows,tHdrNbr).<BR>  
   * This does NOT save the tData rows. 
   * <P>
   * It also sets the the Index-Map byte pointers 
   * lineStartHeaderBytePtr[], lineEndHeaderBytePtr[] for the tHeader and
   * lineStartDataBytePtr[], and lineEndDataBytePtr[] for the tData.
   * <P> 
   * If the table is not at the front of the file, one option is to
   * find the start of the table by searching for a this.startTblColStr 
   * string if you know a unique string in the header row. This is used 
   * if startTblColStr is not blank (set by setStartTableAtColStr()). 
   * If it matches, we then search backwards to the front of the string 
   * for a '\n' which is the  end of the previous row.
   * <P>
   * An alternate method for finding the start of the file, if the
   * this.hasEmptyLineBeforeTableFlag is set, is to look for the first 
   * non-empty empty row after seeing an empty row that it is then 
   * assumed to be the Table data (Fields + data or data) follows. 
   * This can be problematic if there are multiple blank lines.
   *<P> 
   * When the front of the table is found, then it sets
   * this.firstDataRowLineNbr to that line number.
   * If there is no empty row found, then it assumes there is no extra
   * data before the table and it sets this.firstDataRowLineNbr to 0.
   * If there is text before the Table, then it is put into this.tPreface.
   * <P>
   * @param inputFile is file to read and convert to table
   * @return true if successful, else errMsgLog has reason failed.
   * @see #readAndParseTableData
   */
  public boolean readAndParseTableIndexMap(String inputFile)
  { /* readAndParseTableIndexMap */
    return(readAndParseTableData(inputFile, false, false, true));
  }  /* readAndParseTableIndexMap */
  
  
  /**
   * readAndParseTableAll() - read & convert tab-delim file to Table 
   * structure. Set up the table data structures in this instance of 
   * FileTable:<BR>
   *  (tHeader,tPreface,tRows,tCols,tFields[],tData[][],tCols,tRows,tHdrNbr).
   * <P> 
   * If the table is not at the front of the file, one option is to
   * find the start of the table by searching for a this.startTblColStr 
   * string if you know a unique string in the header row. This is used 
   * if startTblColStr is not blank (set by setStartTableAtColStr()). 
   * If it matches, we then search backwards to the front of the string 
   * for a '\n' which is the  end of the previous row.
   * <P>
   * An alternate method for finding the start of the file, if the
   * this.hasEmptyLineBeforeTableFlag is set, is to look for the first 
   * non-empty empty row after seeing an empty row that it is then 
   * assumed to be the Table data (Fields + data or data) follows. 
   * This can be problematic if there are multiple blank lines.
   *<P> 
   * When the front of the table is found, then it sets
   * this.firstDataRowLineNbr to that line number.
   * If there is no empty row found, then it assumes there is no extra
   * data before the table and it sets this.firstDataRowLineNbr to 0.
   * If there is text before the Table, then it is put into this.tPreface. 
   * <P>
   * It also sets the the Index-Map byte pointers 
   * lineStartHeaderBytePtr[], lineEndHeaderBytePtr[] for the tHeader and
   * lineStartDataBytePtr[], and lineEndDataBytePtr[] for the tData.
   * It creates the ftIdxMap index-Map Table as one of the elements 
   * of this Table.
   * <P>
   * @param inputFile is file to read and convert to table
   * @return true if successful, else errMsgLog has reason failed.
   * @see #readAndParseTableData
   */
  public boolean readAndParseTableAll(String inputFile)
  { /* readAndParseTableAll */
    return(readAndParseTableData(inputFile, false, true, true));
  }  /* readAndParseTableAll */
  
  
  /**
   * readAndParseTable() - read & convert tab-delim file to Table 
   * structure. Set up the table data structures in this instance of 
   * FileTable:<BR>
   *  (tHeader,tPreface,tRows,tCols,tFields[],tData[][],tCols,tRows,tHdrNbr).
   * <P> 
   * If the table is not at the front of the file, one option is to
   * find the start of the table by searching for a this.startTblColStr 
   * string if you know a unique string in the header row. This is used 
   * if startTblColStr is not blank (set by setStartTableAtColStr()). 
   * If it matches, we then search backwards to the front of the string 
   * for a '\n' which is the  end of the previous row.
   * <P>
   * An alternate method for finding the start of the file, if the
   * this.hasEmptyLineBeforeTableFlag is set, is to look for the first 
   * non-empty empty row after seeing an empty row that it is then 
   * assumed to be the Table data (Fields + data or data) follows. 
   * This can be problematic if there are multiple blank lines.
   *<P> 
   * When the front of the table is found, then it sets
   * this.firstDataRowLineNbr to that line number.
   * If there is no empty row found, then it assumes there is no extra
   * data before the table and it sets this.firstDataRowLineNbr to 0.
   * If there is text before the Table, then it is put into this.tPreface. 
   * <P>
   * It also sets the the Index-Map byte pointers 
   * lineStartHeaderBytePtr[], lineEndHeaderBytePtr[] for the tHeader and
   * lineStartDataBytePtr[], and lineEndDataBytePtr[] for the tData.
   * It does not create the ftIdxMap index-Map Table.
   * <P>
   * @param inputFile is file to read and convert to table
   * @return true if successful, else errMsgLog has reason failed.
   * @see #readAndParseTableData
   */
  public boolean readAndParseTable(String inputFile)
  { /* readAndParseTable */
    return(readAndParseTableData(inputFile, false, true, false));
  }  /* readAndParseTable */
   
  
  /**
   * readAndParseTableFields() - read tab-delim file to tFields Table 
   * structure. Set up the table data structures in this instance of 
   * FileTable:
   *  (tHeader,tPreface,tRows,tCols,tFields[],tCols,tRows,tHdrNbr).<BR>  
   * This does NOT save the tData rows. 
   * <P> 
   * If the table is not at the front of the file, one option is to
   * find the start of the table by searching for a this.startTblColStr 
   * string if you know a unique string in the header row. This is used 
   * if startTblColStr is not blank (set by setStartTableAtColStr()). 
   * If it matches, we then search backwards to the front of the string 
   * for a '\n' which is the  end of the previous row.
   * <P>
   * An alternate method for finding the start of the file, if the
   * this.hasEmptyLineBeforeTableFlag is set, is to look for the first 
   * non-empty empty row after seeing an empty row that it is then 
   * assumed to be the Table data (Fields + data or data) follows. 
   * This can be problematic if there are multiple blank lines.
   *<P> 
   * When the front of the table is found, then it sets
   * this.firstDataRowLineNbr to that line number.
   * If there is no empty row found, then it assumes there is no extra
   * data before the table and it sets this.firstDataRowLineNbr to 0.
   * If there is text before the Table, then it is put into this.tPreface.
   * <P>
   * It also sets the the  Index-Map byte pointers 
   * lineStartHeaderBytePtr[], lineEndHeaderBytePtr[] for the tHeader.
   * It does not read the tData rows, but instead closes the file and returns.
   * So the index map is incomplete.
   * <P>
   * @param inputFile is file to read and convert to table
   * @return true if successful, else errMsgLog has reason failed.
   * @see #readAndParseTableData
   */
  public boolean readAndParseTableFields(String inputFile)
  { /* readAndParseTableFields */
    return(readAndParseTableData(inputFile, true, false, false));
  }  /* readAndParseTableFields */
  
  
  /**
   * readAndParseTableFieldsAndIndexMap - read tab-delim file to tFields
   * and ftIdxMap Table. Set up the table data structures in this instance 
   * of FileTable:
   *  (tHeader,tPreface,tRows,tCols,tFields[],tCols,tRows,tHdrNbr).<BR>  
   * This does NOT save the tData rows. 
   * <P> 
   * If the table is not at the front of the file, one option is to
   * find the start of the table by searching for a this.startTblColStr 
   * string if you know a unique string in the header row. This is used 
   * if startTblColStr is not blank (set by setStartTableAtColStr()). 
   * If it matches, we then search backwards to the front of the string 
   * for a '\n' which is the  end of the previous row.
   * <P>
   * An alternate method for finding the start of the file, if the
   * this.hasEmptyLineBeforeTableFlag is set, is to look for the first 
   * non-empty empty row after seeing an empty row that it is then 
   * assumed to be the Table data (Fields + data or data) follows. 
   * This can be problematic if there are multiple blank lines.
   *<P> 
   * When the front of the table is found, then it sets
   * this.firstDataRowLineNbr to that line number.
   * If there is no empty row found, then it assumes there is no extra
   * data before the table and it sets this.firstDataRowLineNbr to 0.
   * If there is text before the Table, then it is put into this.tPreface.
   * <P>
   * It also sets the the Index-Map byte pointers 
   * lineStartHeaderBytePtr[], lineEndHeaderBytePtr[] for the tHeader.
   * It creates the ftIdxMap index-Map Table as one of the elements 
   * of this Table.
   * It does not read the tData rows, but instead closes the file and 
   * returns.
   * <P>
   * @param inputFile is file to read and convert to table
   * @return true if successful, else errMsgLog has reason failed.
   * @see #readAndParseTableData
   */
  public boolean readAndParseTableFieldsAndIndexMap(String inputFile)
  { /* readAndParseTableFieldsAndIndexMap */
    return(readAndParseTableData(inputFile, true, false, true));
  }  /* readAndParseTableFieldsAndIndexMap */
  
       
  /**
   * readAndParseTableData() - read & convert tab-delim file to Table 
   * structure. Set up the table data structures in this instance of 
   * FileTable:
   *  (tHeader,tPreface,tRows,tCols,tFields[],tData[][],tCols,tRows,tHdrNbr).
   * <P> 
   * If the table is not at the front of the file, one option is to
   * find the start of the table by searching for a this.startTblColStr 
   * string if you know a unique string in the header row. This is used 
   * if startTblColStr is not blank (set by setStartTableAtColStr()). 
   * If it matches, we then search backwards to the front of the string 
   * for a '\n' which is the  end of the previous row.
   * <P>
   * An alternate method for finding the start of the file, if the
   * this.hasEmptyLineBeforeTableFlag is set, is to look for the first 
   * non-empty empty row after seeing an empty row that it is then 
   * assumed to be the Table data (Fields + data or data) follows. 
   * This can be problematic if there are multiple blank lines.
   *<P> 
   * When the front of the table is found, then it sets
   * this.firstDataRowLineNbr to that line number.
   * If there is no empty row found, then it assumes there is no extra
   * data before the table and it sets this.firstDataRowLineNbr to 0.
   * If there is text before the Table, then it is put into this.tPreface.
   * <P>
   * It also sets the the Index-Map byte pointers 
   * lineStartHeaderBytePtr[], lineEndHeaderBytePtr[] for the tHeader and
   * lineStartDataBytePtr[], and lineEndDataBytePtr[] for the tData if
   * making an Index-Map ftIdxMap.
   * If makeIndexMapFlag is set it creates the ftIdxMap index-Map Table
   * as one of the elements of this Table.
   * <P>
   * @param inputFile is file to read and convert to table
   * @param onlyReadHeaderFlag only read the tPreface, tFields and tHeader
   *             and then stop reading the file unless making an index map.
   * @param saveTblRowDataFlag to save the tData rows, else just compute 
   *              the Index-Map for the data rows.
   * @param makeIndexMapFlag make an index map of Table in this.ftIdxMap
   * @return true if successful, else errMsgLog has reason failed.
   * @see #rmvTrailingBlankLinesFromTable
   * @see #deleteTrailingEmptyColumnsFromTable
   * @see #checkForBadTable
   */
  public boolean readAndParseTableData(String inputFile,
                                       boolean onlyReadHeaderFlag,
                                       boolean saveTblRowDataFlag,
                                       boolean makeIndexMapFlag)
  { /* readAndParseTableData */
    if(inputFile==null)
      return(false);

    /* [1] Setup parser variables */
    int
      DBUG_NBR_LINES= -1; /* (5) [TODO] remove this DEBUG code when working fully. */
    int
      tDataSize= 0,
      nbrRowsIncr= 100,
      lineTermSize= -1,         /* will compute it */
      countLines= 0,            /* local line counter */
      countMoreHdrLines= 0;     /* used to save hdr lines before parse
                                 * after found blank line */
    long
      startByte= 0,  /* buffer ptr at start of a line */
      endByte= 0;    /* buffer ptr at end of a line.  */
    int
      nColNameIndexMap= 0, /* this.colNameIndexMap.length if used */
      ftIMcols= 0,         /* Nbr of ftIdxMap field indexes if index-map used */ 
      idxColNames[]= null; /* ftIdxMap field indexes if index-map used */

    /* Fix file separators if need to do it. */
    inputFile= mapPathFileSeparators(inputFile);
    
    /* [1.1] Find terminator as either \r, \n or \r\n  */
    String  
      fileLineSep= this.getLineSeparatorFromFile(inputFile);
    
    /* Set to the first line of tData when found */
    firstDataRowLineNbr= -1;
    
    /* If making Index-Map, setup the empty ftIdxMap Table */
    if(!makeIndexMapFlag)
      ftIdxMap= null;        /* There is no map Table until read data rows */
    else
    { /* setup the empty ftIdxMap Table */
      ftIdxMap= new FileTable("File-Index-Map");
      ftIdxMap.setHasTableHeaderFlag(true);
      ftIdxMap.setDuplicateFieldsFlag(false);
      ftIdxMap.setNbrTableHdrLines(1);
      ftIdxMap.setRmvTrailingBlankLinesFlag(false);
      ftIdxMap.setHasEmptyLineBeforeTableFlag(false);
    } /* setup the empty ftIdxMap Table */
            
    /* [2] Read and parse the tab-delimited data file into the Table
     * and get the tPreface as all data before the Header.
     */
    try
    { /* Read file and parse data into Table */
      RandomAccessFile rafL= new RandomAccessFile(inputFile, "r");

      /* [2.1] Get the file line separator and it's size. 
       * It is either \r, \n or \r\n - or null if an error */
      if(fileLineSep==null)
      { /* Handle errors */
        errMsgLog += "MIF-RAPF no \r, \n or \r\n terminator in '" + 
                     inputFile + "'\n";
        lastErrMsgLog= errMsgLog;
        return (false);
      }
           
      /* [2.2] Init parse variables */
      String 
        lookbackHdrs[]= new String[nbrTableHdrLines],
        tokens[]= null,           /* list of tokens in the inputLine */
        inputLine = null;         /* lines read from buffered reader */
      long
        lookbackStartBytePtr[]= new long[nbrTableHdrLines+1],
        lookbackEndBytePtr[]= new long[nbrTableHdrLines+1];
      
      boolean  
        beforeFirstDataLineFlag= true, /* set false on 1st data row */
        foundDataRowFlag= false,  /* set at end of the header */
        foundHdrRowFlag= false;   /* saw header row in file, else error */

      tHdrRows= nbrTableHdrLines;
      tRows= 0;                   /* count first row */
      tCols= 0;                   /* there is at least 1 Row if fields*/
    
      /* [3] Read lines from the input file using the RandomAccessFile
       * readLine() fct that stops at and ignores line terminators "\n",
       * "\r", or "\r\n".
       */
            
      /* Compute the extra line terminate length we will add to each startByte
       * after 1st so aligned correctly.
       * Note that the lineTermSize of the file may be different from
       * that of the operating system (for various reasons such as being
       * edited by an editor that changes "\n" or "\r", to "\r\n"). 
       * Therefore, we need to compute it for the current file.
       */
      lineTermSize= computeFileLineTermSize(rafL, 0L); 
      if(lineTermSize==-1)
      {
        UtilCM.logMsg("Problem computing file line terminator size for "+
                      "file '"+inputFile+"- aborting.\n");
        return(false);
      }
              
      endByte= -lineTermSize; /* set for first line computations */
      long curFilePtr= rafL.getFilePointer();  /* Should be 0L */
      
      while((inputLine= rafL.readLine()) != null)
      { /* process lines */
        countLines++;        /* first row is defined as line 1, not 0 */
        
        /* [3.1] Compute the line byte pointers with terminator.
         * Note: startByte starts and old endByte + lineTermSize + 1.
         */
        int
          //offset= ((countLines==1)? 0 : lineTermSize+1), /* no offset first line */
          lineLth= inputLine.length();      /* does not include terminator */
        long prevFilePtr= curFilePtr;       /* Save it */
        curFilePtr= rafL.getFilePointer();  /* After the read */
        startByte= prevFilePtr;             /* starts after prev line terminator */
        endByte= curFilePtr-lineTermSize;   /* does not include term.r */
        
        /* [3.1.1] DEBUG TEST if Index-Map byte seek pointers are correct.
         * [TODO] remove this DEBUG code when working fully.
         */        
        if(false && countLines<DBUG_NBR_LINES &&
           UtilCM.testDebugValue("IndexMapSeeks", inputFile))
        { /* ***DEBUG*** TEST if seek pointers are correct */          
          long nextReadPtr= rafL.getFilePointer();  /* save while use same file */
          rafL.seek(startByte);
          String sRowData= rafL.readLine();
          rafL.seek(nextReadPtr);
          
          String
            sInputLineToks[]= UtilCM.cvs2Array(inputLine, "\t"),
            sRowDataToks[]= UtilCM.cvs2Array(sRowData, "\t");
          int
            lth_sInputLineToks= sInputLineToks.length,
            lth_sRowDataToks= sRowDataToks.length;              
           
          UtilCM.logMsg("\n====================================\nRAPT.3.1.1 ");

          if(ftIdxMap!=null)
            UtilCM.logMsg("ftIdxMap.tRows="+ftIdxMap.tRows);
          else
            UtilCM.logMsg("this.tRows="+this.tRows);
          UtilCM.logMsg(" of '"+inputFile + 
                        "\n  seek startByte="+startByte+
                        " endByte="+endByte+
                        " nextReadPtr="+nextReadPtr+
                        " prevFilePtr="+prevFilePtr+
                        " curFilePtr="+curFilePtr+
                        " countLines="+countLines+
                        " lineTermSize="+lineTermSize+"\n");
          UtilCM.logMsg("  |inputLine|="+inputLine.length()+
                        " (#toks="+lth_sInputLineToks+")"+
                        "='"+inputLine+"'\n");
          UtilCM.logMsg("\n  |sRowData| ="+sRowData.length()+
                        " (#toks="+lth_sRowDataToks+")"+
                        "='"+sRowData+"'\n");
          UtilCM.logMsg("\n");
        } /* ***DEBUG*** TEST if seek pointers are correct */
        
        /* [3.2] Parse the Header and save header lines, backwards,
         * for parsing into the tHeader and tFields.
         */
        if(!foundHdrRowFlag)
        { /* save until parsed header */
          /* [3.2.1] Save Preface with stuff falling out of lookback */
          String prefaceLine= lookbackHdrs[tHdrRows-1];
          if(prefaceLine!=null)
          { /* only push non-null lines to the tPreface */
            if(tPreface==null)
              tPreface= prefaceLine +"\n";
            else
              tPreface += prefaceLine +"\n";
          }
          
          /* [3.2.2] Push data back into the look back list */
          for(int lb=(tHdrRows-2); lb>=0; lb--)
          { /* lb is backwards index */
            lookbackHdrs[lb+1]= lookbackHdrs[lb]; 
            lookbackStartBytePtr[lb+1]= lookbackStartBytePtr[lb]; 
            lookbackEndBytePtr[lb+1]= lookbackEndBytePtr[lb];
          }
          
          /* [3.3] Save current line at end of look back stack. */
          lookbackHdrs[0]= inputLine;
          lookbackStartBytePtr[0]= startByte;
          lookbackEndBytePtr[0]= endByte;
               
          /* [3.4] Read the rest of the header lines. */
          if(countMoreHdrLines>0)
          { /* save more header lines until ready to parse */
            if(--countMoreHdrLines<=0)
              foundHdrRowFlag= true;
            else
              continue;  /* keep saving lines */
          }
          
          /* [3.5] Look for the header starting with specific 
           * string in the tFields (last row of the tHeader.
           */
          if(startTblColStr!=null)
          { /* look for string known in header for start of Table */
            int idxKeyword= inputLine.indexOf(startTblColStr);
            if(idxKeyword!=-1)
            { /* Found the header tFields row */
              foundHdrRowFlag= true;
            }
          }
        
          /* [3.6] Alternately, look for empty line after which the table 
           * will start. This can be problematic if there are multiple 
           * blank lines.
           */
          else if(hasEmptyLineBeforeTableFlag)
          {  /* scan through the preface */          
            if(inputLine.length()==0)
            { /* found empty line - assume before header */
              countMoreHdrLines= nbrTableHdrLines;
              continue;
            } /* found empty line - assume before header */
          } 
          else if(countLines>=tHdrRows)
          { /* captured header line since no empty lines before Table */
            foundHdrRowFlag= true;
          }

          /* [3.7] Continue scanning for the header */
          if(!foundHdrRowFlag && !foundDataRowFlag)
            continue;            /* keep scanning for header or data */

          /* [4] Found the header - save it in tFields and tHeader */
          else if(foundHdrRowFlag && !foundDataRowFlag)
          { /* Process the header rows */
            if(countLines==1)
              tPreface= null;        /* there is no preface */
            
            /* [4.1] Save the tFields[] */
            inputLine= lookbackHdrs[0]; 
            tFields= UtilCM.cvs2Array(inputLine, "\t");
            tCols= tFields.length;
            
            /* [4.2] Now save the header rows */
            tHeader= new String[tHdrRows][];
            lineStartHeaderBytePtr= new long[tHdrRows];
            lineEndHeaderBytePtr= new long[tHdrRows];
            for(int h=0;h<tHdrRows;h++)
            { /* process header line h in reverse order in look-back list */              
              inputLine= lookbackHdrs[(tHdrRows-1)-h];
              tokens= UtilCM.cvs2ArrayNullFill(inputLine, "\t","");
              
              /* Extend header rows that are less than tCols to tCols long
               * and set the new entries to "".
               */
              tokens= UtilCM.rightSizeArray(tokens, tCols,"");
              tHeader[h]= tokens; 
              
              /* Save Index-map byte pointers of start/end of header rows. */
              lineStartHeaderBytePtr[h]= lookbackStartBytePtr[(tHdrRows-1)-h]; 
              lineEndHeaderBytePtr[h]= lookbackEndBytePtr[(tHdrRows-1)-h];                
            } /* process header line h in reverse order in look-back list */ 
            
            /* [4.3] Now we advance to the Data rows */
            foundDataRowFlag= true;
            
            /* [4.4] Process data rows and capture the start/end byte pointers.
             * If we are creating the full index, then we will read the
             * data lines, but not parse or save them - so we need to continue
             * and just save the start/end byte pointers.
             */
            if(onlyReadHeaderFlag)
            { /* Done reading header - ignore data part unless make index-map */
              firstDataRowLineNbr= countLines+1;  /* Capture start of data row */
              if(makeIndexMapFlag)
              { /* clear it so can continue and not come back here */
                onlyReadHeaderFlag= false;
                continue;         /* go build index map for data lines */
              }
              else
                break;
            } /* Done reading header - ignore data part unless make index-map */  
            
            /* [4.5] Continue scanning to get data or index-map pointers */
            continue;
          } /* Process the header rows */
        } /* save until parsed header */     
                      
        /* [5] Process data rows and capture the start/end byte pointers */
        if(foundHdrRowFlag && foundDataRowFlag)
        { /* process the next data row */          
          /* Post process the state */
          if(firstDataRowLineNbr==-1)
          { /* Special first data row processing */
            firstDataRowLineNbr= countLines;          
          } /* Special first data row processing */
            
          if(beforeFirstDataLineFlag)
          { /* init for processing 1st data row line */            
            beforeFirstDataLineFlag= false;
            
            if(ftIdxMap!=null && colNameIndexMap!=null)
            { /* Create the FileTable ftIdxMap index map */
              /* Create the FileTable index map where save the 
               * {colNames-list, "StartByte", "EndByte") data.
               */
              nColNameIndexMap= this.colNameIndexMap.length;
              ftIMcols= nColNameIndexMap+2; /* room for "StartByte","EndByte" */
              idxColNames= new int[nColNameIndexMap];
              int
                k= 0;
              String ftIMfields[]= new String[ftIMcols];
              for(int m=0;m<nColNameIndexMap;m++)
              { /* add tFields[c] if in colNameIndexMap[m] */
                boolean foundIt= false;
                String colToMap= this.colNameIndexMap[m];
                for(int c=0;c<tCols;c++)
                { /* Map columns to map to the tField columns available */
                  String field= tFields[c];
                  if(field.equals(colToMap))
                  {
                    idxColNames[m]= c;   /* so can lookup values later */
                    ftIMfields[m]= field;
                    foundIt= true;
                    k++;
                  }
                } /* Map columns to map to the tField columns available */
                if(!foundIt)
                {
                  errMsgLog += "FT-RAPT Missing -makeIndex column '"+colToMap+
                               "' in Table file '" + inputFile + "'\n";
                  lastErrMsgLog= errMsgLog;
                  return (false);
                }
              } /* add tFields[c] if in colNameIndexMap[m] */
              /* Now add the byte pointer column names. */
              ftIMfields[k++]= "StartByte";
              ftIMfields[k++]= "EndByte";
              
              /* Fill in the index-map Table */             

              /* Setup the Table fields and headers */
              ftIdxMap.setFieldsToTable(ftIMfields);
              String ftIMheaders[][]= new String[1][];
              ftIMheaders[0]= ftIMfields;
              ftIdxMap.setHeadersToTable(ftIMheaders,1,ftIMcols);
              ftIdxMap.setUseOnlyLastHeaderLineFlag(true);
            } /* Create the FileTable ftIdxMap index map */
          } /* init for processing 1st data row line */        
          
          /* [5.1] Test if all out of data by seeing empty line. */
          if(inputLine.length()==0)
          { /* Done - empty rows at the end of the table */
            continue;               /* ignore empty lines */
          }
          
          /* [5.2] Now parse data rows if saving the data or
           * making an index-map
           */
          if(saveTblRowDataFlag || ftIdxMap!=null)
          { /* only parse data rows if saving the data */
            tokens= UtilCM.cvs2Array(inputLine, "\t");
            if(UtilCM.isEmptyArray(tokens))
              continue;  /* ignore empty token list of "\t\t\t\t\t" form */
          
            if(tokens.length<tCols)
            { /* if row data size is < header size, then extend the row */
              errMsgLog += "Short data row["+tRows+"] with "+tokens.length+
                           " columns - extending it to "+tCols+
                           " and continuing...\n";
              lastErrMsgLog= errMsgLog;
              
              /* Extend header rows that are less than tCols to tCols long
               * and set the new entries to "".
               */
              tokens= UtilCM.rightSizeArray(tokens, tCols,"");
              
              /* Remove enclosing white space */
              for(int c=0;c<tokens.length;c++)
                tokens[c]= UtilCM.rmvEnclosingWhitespace(tokens[c]);
            }
          } /* only parse data rows if saving the data */
          
          /* [5.3] If not enough room in the data arrays and index map
           * tables, then grow the arrays by nbrRowsIncr. Only if 
           * saveTblRowDataFlag and/or makeIndexMapFlag.
           */
          if(saveTblRowDataFlag || ftIdxMap!=null)
          { /* alloc the tData array */
            if(tRows==0)
            { /* allocate arrays */
              tDataSize= nbrRowsIncr;
              if(saveTblRowDataFlag)
                tData= new String[tDataSize][];
              if(ftIdxMap!=null)
                ftIdxMap.tData= new String[tDataSize][];
              lineStartDataBytePtr= new long[tDataSize];
              lineEndDataBytePtr= new long[tDataSize];
            }
            else if(tRows >= tDataSize)
            { /* grow the arrays by nbrRowsIncr */
              tDataSize += nbrRowsIncr;              
              if(saveTblRowDataFlag)
              { /* expand this Table data */
                String tDataNew[][]= new String[tDataSize][];
                for(int r= 0; r < tRows; r++)
                  tDataNew[r]= tData[r];
                tData= tDataNew;
              }              
              if(ftIdxMap!=null)
              { /* expand ftIdxMap Table data */
                String tDataNew[][]= new String[tDataSize][];
                for(int r= 0; r < tRows; r++)
                  tDataNew[r]= ftIdxMap.tData[r];
                ftIdxMap.tData= tDataNew;
              }
              long lineStartDataBytePtrNew[]= new long[tDataSize];
              long lineEndDataBytePtrNew[]= new long[tDataSize];
              for(int r= 0; r < tRows; r++)
              { /* copy data */
                lineStartDataBytePtrNew[r]= lineStartDataBytePtr[r];
                lineEndDataBytePtrNew[r]= lineEndDataBytePtr[r];
              }                            
              lineStartDataBytePtr= lineStartDataBytePtrNew;
              lineEndDataBytePtr= lineEndDataBytePtrNew;
            } /* grow the arrays by nbrRowsIncr */
          } /* alloc the tData array */
          
          /* [5.3.1] Copy the data row for this line to Table tData
           * only if saving the data. But copy the index map data.
           */
          if(saveTblRowDataFlag)
            tData[tRows]= tokens;
          if(saveTblRowDataFlag || ftIdxMap!=null)
          { /* Save the Index-Map byte pointers */
            lineStartDataBytePtr[tRows]= startByte; 
            lineEndDataBytePtr[tRows]= endByte; 
          }
          
          /* [5.3.1.1] DEBUG TEST if Index-Map byte seek pointers are correct.
           * [TODO] remove this DEBUG code when working fully.
           */ 
          if(false && countLines<DBUG_NBR_LINES &&
             UtilCM.testDebugValue("IndexMapSeeks", inputFile) &&
             (saveTblRowDataFlag || ftIdxMap!=null))
          { /* ***DEBUG*** TEST if seek pointers are correct */
            long nextReadPtr= rafL.getFilePointer();  /* save while use same file */
            rafL.seek(startByte);
            String sRowData= rafL.readLine();
            rafL.seek(nextReadPtr);
            
            String
              sInputLineToks[]= UtilCM.cvs2Array(inputLine, "\t"),
              sRowDataToks[]= UtilCM.cvs2Array(sRowData, "\t");
            int
            lth_sInputLineToks= sInputLineToks.length,
            lth_sRowDataToks= sRowDataToks.length;              
             
            UtilCM.logMsg("\n---------------------------------------\nRAPT.5.3.1.1 ");
            if(ftIdxMap!=null)
              UtilCM.logMsg("ftIdxMap.tRows="+ftIdxMap.tRows);
            else
              UtilCM.logMsg("this.tRows="+this.tRows);
            UtilCM.logMsg("\n  seek startByte="+startByte+
                          " endByte="+endByte+
                          " nextReadPtr="+nextReadPtr+
                          " prevFilePtr="+prevFilePtr+
                          " curFilePtr="+curFilePtr+
                          " countLines="+countLines+
                          " lineTermSize="+lineTermSize+"\n");
            UtilCM.logMsg("  |inputLine|="+inputLine.length()+
                          " (#toks="+lth_sInputLineToks+")"+
                          "='"+inputLine+"'\n");
            UtilCM.logMsg("\n  |sRowData| ="+sRowData.length()+
                          " (#toks="+lth_sRowDataToks+")"+
                          "='"+sRowData+"'\n");
            if(this.errMsgLog.length()>0)
              UtilCM.logMsg("   errMsgLog="+this.errMsgLog+"\n");
          } /* ***DEBUG*** TEST if seek pointers are correct */
          
          /* [5.3.2] Build the ftIdxMap data Table row by row */
          if(ftIdxMap!=null)
          { /* add ftIdxMap row */
            String imDataRow[]= new String[ftIMcols];
            /* copy the colNameIndexMap[] key values */
            int
              c,
              k= 0;
            for(int m=0;m<nColNameIndexMap;m++)
            {
              c= idxColNames[k];
              imDataRow[k++]= new String(tokens[c]);
            }
            imDataRow[k++]= (""+startByte); 
            imDataRow[k++]= (""+endByte);  
            ftIdxMap.tData[tRows]= imDataRow;
            ftIdxMap.tRows++;
          }  /* add ftIdxMap row */
                    
          tRows++;
        } /* process the next data row */
          
      } /* process lines */

      /* [6] Make the tData[] the actual number of rows only if
       * saving the data.
       */
      if(!onlyReadHeaderFlag &&  saveTblRowDataFlag && 
         (tRows < tDataSize))
      { /* shrink the data array size to the exact size */
        String tDataNew[][]= new String[tRows][];
        for(int r=0;r<tRows;r++)
          tDataNew[r]= tData[r]; 
        tData= tDataNew;
      } /* shrink the data array size to the exact size */ 
      
      /* [6.1] Make the Index-Map buffers the actual number of rows
       * only if making the index.
       */
      if(ftIdxMap!=null && (tRows < tDataSize))
      { /* shrink the index-map arrays size to the exact size */        
        String tDataNew[][]= new String[tRows][];
        for(int r= 0; r < tRows; r++)
          tDataNew[r]= ftIdxMap.tData[r];
        ftIdxMap.tData= tDataNew;
        long lineStartDataBytePtrNew[]= new long[tRows];
        long lineEndDataBytePtrNew[]= new long[tRows];
        for(int r=0;r<tRows;r++)
        { /* copy data */
          lineStartDataBytePtrNew[r]= lineStartDataBytePtr[r]; 
          lineEndDataBytePtrNew[r]= lineEndDataBytePtr[r]; 
        }
        lineStartDataBytePtr= lineStartDataBytePtrNew; 
        lineEndDataBytePtr= lineEndDataBytePtrNew;                
      } /* shrink the index-map arrays size to the exact size */

      /* [7] Close input file - we were successful */
      rafL.close();
    } /* Read file and parse data into Table */

    catch (IOException e)
    {
      errMsgLog += "FT-RAPT read Table from file '" + inputFile + "'\n"+
                   "Exception e='"+e.toString()+"'\n";
      lastErrMsgLog= errMsgLog;
      return (false);
    }         
    
    if(!onlyReadHeaderFlag && rmvTrailingEmptyColumnsFlag)
      deleteTrailingEmptyColumnsFromTable();    
    
    /* [TODO] may want to do a partial check */
    if(!onlyReadHeaderFlag && saveTblRowDataFlag && !checkForBadTable())
      return(false);                /* valid data tFields data */        
              
    return(true);
  } /* readAndParseTableData */
  

  /**
   * computeFileLineTermSize() - compute a file's line terminator size.
   * Note that the lineTermSize of the file may be different from
   * that of the operating system (for various reasons such as being
   * edited by an editor that changes "\n" or "\r", to "\r\n"). 
   * Therefore, we need to compute it for the current file.
   * The method assumes that the line terminators are the same for 
   * all lines. 
   * @param rafL is the opened RandomAccessFile
   * @param setSeekPtr leave the file at this seek pointer if != -1.
   * @return lineTermSize (should be either 1 or 2), -1 if error
   */
  public int computeFileLineTermSize(RandomAccessFile rafL, long setSeekPtr)
  { /* computeFileLineTermSize */
    int lineTermSize= -1;
    try
    { /* Read 1st line and compute seek ptr */
      long beforeReadSeekPtr= rafL.getFilePointer();
      String inputLine= rafL.readLine();
      long afterReadSeekPtr= rafL.getFilePointer();
      int diffSeekPtrs= (int)(afterReadSeekPtr - beforeReadSeekPtr);
      lineTermSize= diffSeekPtrs - inputLine.length();
      if(setSeekPtr>=0L)
        rafL.seek(setSeekPtr);  /* Rewind the file to the beginning */
    }
    catch (IOException e)
    {
      lineTermSize= -1;
    }
    
    return(lineTermSize);
  } /* computeFileLineTermSize */
    
  
  /**
   * cvtTableToTabDelimStr() - convert Table to tab delimited string.
   * This converts out multi-line tHeader data if they exist and then 
   * the tData.
   * @param addHdrFlag - add the header (i.e., tFields) to front
   * @return converted string, else null
   */
  public String cvtTableToTabDelimStr(boolean addHdrFlag)
  { /* cvtTableToTabDelimStr */
    
    /* [1] validate Table data */
    if(tCols==0 || tRows==0 || addHdrFlag && tFields==null)
      return(null);                /* bad data */

    String 
      cell,
      rowData[],
      sRowData,
      sHdr= "",
      sTbl= "";
    
    /* [2] Add the header if requested */
    if(addHdrFlag)
    { /* add the header */
      int nHdrs= (tHeader==null) ? 1 : tHdrRows;
      for(int h=0;h<nHdrs;h++)
      { /* process header h */
        sHdr= "";
        for(int c= 0; c < tCols; c++)
        { /* process col c */
          cell= (tHeader==null) ? tFields[c] : tHeader[h][c];
          sHdr += cell;
          sHdr += (c != (tCols - 1)) ? "\t" : "\n";
        } /* process col c */
        sTbl += sHdr;
      } /* process header h */
    } /* add the header */
    
    /* Add the data rows */
    for(int r=0;r<tRows;r++)
    { /* Process row r */
      rowData= tData[r];
      sRowData= "";
      for(int c=0;c<tCols;c++)
      { /* process col c */
        cell= rowData[c];
        sRowData += cell;
        sRowData += (c!=(tCols-1)) ? "\t" : "\n";
      } /* process col c */
      sTbl += sRowData;
    } /* Process row r */
    
    return(sTbl);
  } /* cvtTableToTabDelimStr */
    
  
  /**
   * writeTableToTabDelimFile() - convert Table to tab delimited file.
   * This writes out multi-line tHeader data if they exist and then 
   * the tData.
   * @param fileName - to write the Table
   * @param addHdrFlag - add the header (i.e., tFields) to front
   * @return true if succeed, else put error message in errMsgLog.
   */
  public boolean writeTableToTabDelimFile(String fileName, 
                                          boolean addHdrFlag)
  { /* writeTableToTabDelimFile */
    
    /* [1] validate Table data */
    if(fileName==null || tCols==0 || tRows==0 ||
       addHdrFlag && tFields==null)
      return(false);                /* bad data */

    String 
      cell,
      rowData[],
      sRowData,
      sHdr= "";
    
    try
    { /* Write out the file */
      FileWriter fw= new FileWriter(fileName);
      BufferedWriter bw= new BufferedWriter(fw);

      /* [2] Add the header if requested */
      if(addHdrFlag)
      { /* add the header */
        int nHdrs= (tHeader==null) ? 1 : tHdrRows;
        for(int h=0;h<nHdrs;h++)
        { /* write out header h */
          sHdr= "";
          for(int c= 0; c < tCols; c++)
          { /* process col c */
            cell= (tHeader==null) ? tFields[c] : tHeader[h][c];
            sHdr += cell;
            sHdr += (c != (tCols - 1)) ? "\t" : "\n";
          } /* process col c */
          bw.write(sHdr);
        } /* write out header h */
      } /* add the header */

      /* Add the data rows */
      for(int r= 0; r < tRows; r++)
      { /* Process row r */
        rowData= tData[r];
        sRowData= "";
        for(int c= 0; c < tCols; c++)
        { /* process col c */
          cell= rowData[c];
          sRowData += cell;
          sRowData += (c != (tCols - 1)) ? "\t" : "\n";
        } /* process col c */
        bw.write(sRowData);
      } /* Process row r */
      
      bw.close();
    } /* Write out the file */
    
    catch(IOException e)
    {
      errMsgLog +="FT-WTTTDF write Table for file '"+fileName+"'\n";
      lastErrMsgLog= errMsgLog;
      return(false);
    }
    
    return(true);
  } /* writeTableToTabDelimFile */
  
  
  /**
   * rmvTrailingBlankLinesFromTable() - remove Table trailing blank lines
   * by shortening the table from the bottom of
   * the table. Shorten the tData[rows] and tRows.
   * @return true if shortened the table.
   */
   public boolean rmvTrailingBlankLinesFromTable()
   { /* rmvTrailingBlankLinesFromTable */
     int 
       r,
       c,
       lastNonblankRow= -1;
     String
       sCell,
       tRowsData[];
     
     for(r=(tRows-1);r>=0;r--)
     { /* look backwards for 1st non-blank row */
       tRowsData= tData[r];
       if(tRowsData==null)
       { /* no row data */
         continue;
       }
       for(c=0;c<tCols;c++)
       { /* If find any non-blank cell, then row is not blank */
         sCell= tRowsData[c];
         if(sCell!=null && sCell.length()>0)
         {
           lastNonblankRow= r;
           break;
         }
       } /* If find any non-blank cell, then row is not blank */
       if(lastNonblankRow!=-1)
         break;
     } /* look backwards for 1st non-blank row */
     
     if(lastNonblankRow<=0)
       return(false);       /* no blank rows - just return */
     
     if((lastNonblankRow+1)==tRows)
       return(false);       /* same size - just return */
     
     /* Shorten the table by copying tData[0:lastNonBlankRow] to new 
      * String array and then set tData to the new array.
      */
     String tDataNew[][]= new String[lastNonblankRow+1][];
     for(r=0;r<=lastNonblankRow;r++)
       tDataNew[r]= tData[r];
     tData= tDataNew;
     tRows= lastNonblankRow+1;
     
     return(true);
   } /* rmvTrailingBlankLinesFromTable */
  
  
  /**
   * deleteTableColumnByName() - delete a column from the table.
   * Remove the column from the tFields[] and sData[][] and
   * decrement tCols if succeed. It will also delete the tData column
   * if tData exists (i.e., is not null).
   * @param columnName of column to be deleted if found.
   * @return true if succeed, else if fail the errMsgLog string
   *         is set with the reason it failed.
   * @see #deleteTableColumnByColIdx
   */
  public boolean deleteTableColumnByName(String columnName)
  { /* deleteTableColumnByName */
    /* [1] find the column index to delete */
    int 
      c,
      cIdx= -1;
    
    for(c=0;c<tCols;c++)
      if(tFields[c].equals(columnName))
      {
        cIdx= c;
        break;
      }
    if(cIdx==-1 || (tCols-1)<=0)
    { /* could not find the column */
      errMsgLog += "FT-DTCBN can't find column '"+columnName+"'\n";
      lastErrMsgLog= errMsgLog;
      return(false);           
    }
    
    boolean flag= deleteTableColumnByColIdx(cIdx);
    return(flag);
  } /* deleteTableColumnByName */

    
  /**
   * deleteTableColumnByColIdx() - delete a column from table by column index
   * where (column 1 has index 0).
   * Remove the column from the tFields[], tHeader[] and tData[][] and
   * decrement tCols if succeed. It will also delete the tData column
   * if tData exists (i.e., is not null).
   * @param cIdx is index of column to be deleted.
   * @return true if succeed, else if fail the errMsgLog string
   *         is set with the reason it failed.
   */
  public boolean deleteTableColumnByColIdx(int cIdx)
  { /* deleteTableColumnByColIdx */
    /* [1] find the column index to delete */
    int 
      r,
      c,
      c2;
    
    if(cIdx==-1 || (tCols-1)<=0)
    { /* could not find the column */
      errMsgLog += "FT-DTCBCI bad column index "+cIdx+"'\n";
      lastErrMsgLog= errMsgLog;
      return(false);           
    }
    
    /* [2] Replace tFields array less the cIdx name */
    String 
      tFields2[]= new String[tCols-1],
      tHeader2[][]= new String[tHdrRows][];
    for(int h=0;h<tHdrRows;h++)
      tHeader2[h]= new String[tCols-1];
    
    for(c2= 0,c=0;c<tCols;c++)
      if(c!=cIdx)
      { /* copy all but column to be deleted */
        tFields2[c2]= tFields[c];
        for(int h=0;h<tHdrRows;h++)
          tHeader2[h][c2]= new String(tHeader[h][c]);
        c2++;
      }
    tFields= tFields2;            /* replace it */
    
    /* Copy it to the last tHeader row */
    tHeader= tHeader2;
    
    /* [3] Edit the tData column tData if it exists (i.e., is not
     * null). Replace tData array data less the cIdx cells 
     */
    if(tData != null)
    { /* delete the column from tData */
      String rowData[];
      for(r= 0; r < tRows; r++)
      { /* Process row r */
        String rowData2[]= new String[tCols - 1];
        rowData= tData[r];
        if(rowData == null)
          break;             /* No more data */
        for(c2= 0, c= 0; c < tCols; c++)
          if(c != cIdx)
            rowData2[c2++]= rowData[c];
        tData[r]= rowData2;  /* replace it */
      } /* Process row r */
    } /* delete the column from tData */
    
    /* [4] Decrement the number of columns */
    --tCols;
    
    return(true);
  } /* deleteTableColumnByColIdx */
   
  
  /**
   * lookupFieldIdx() - lookup column index of field if exists.
   * @param fieldName to lookup
   * @return index if found, else if it does not exist return -1
   */
  public int lookupFieldIdx(String fieldName)
  { /* lookupFieldIdx */
    if(fieldName==null)
      return(-1);
    
    int idx= -1;          /* failure default */
    for(int i=0; i<tCols; i++)
      if(fieldName.equalsIgnoreCase(tFields[i]))
      {
        idx= i;
        break;
      }
    
    return(idx);
  } /* lookupFieldIdx */

  
  /**
   * lookupRowFromColumnData() - lookup row index from column data if exists.
   * @param colName  of column to lookup
   * @param colValue in column to lookup in a matching row
   * @return row index if found, else if it does not exist return -1
   */
  public int lookupRowFromColumnData(String colName, String colValue)
  { /* lookupRowFromColumnData */
    int idxCol= lookupFieldIdx(colName);
    if(idxCol==-1)
      return(-1);
    
    int idxRow= -1;          /* failure default */
    for(int r=0; r<tRows; r++)
      if(colValue.equalsIgnoreCase(tData[r][idxCol]))
      {
        idxRow= r;
        break;
      }
    
    return(idxRow);
  } /* lookupRowFromColumnData */

     
  /**
   * lookupCol2DataFromCol1DataRow() - lookup col2 data from row with col1 
   * data match.
   * @param col1Name  of column 1 to lookup matching row
   * @param col1Value in column 1 to lookup matching row
   * @param col2Name is column of data to return for matching row.
   * @return col2 value of matching row if found, else if it does not exist 
   *         then null
   */
  public String lookupRowDataFromColumnData(String col1Name, 
                                            String col1Value,
                                            String col2Name)
  { /* lookupRowFromColumnData */
    int idxCol1= lookupFieldIdx(col1Name);
    if(idxCol1==-1)
      return(null);
    
    String col2Value= null;          /* failure default */
    for(int r=0; r<tRows; r++)
      if(col1Value.equalsIgnoreCase(tData[r][idxCol1]))
      {
        int idxCol2= lookupFieldIdx(col2Name);
        if(idxCol2!=-1)
          col2Value= tData[r][idxCol2];
        break;
      }
    
    return(col2Value);
  } /* lookupRowFromColumnData */
  
  
  /**
   * appendRowToTable() - append row of data to and grow the Table.
   * Note: this works with an empty table where tRows==0
   * and tData is null.
   * @param rowData is row of data to append
   * @return true if added row
   */
  public boolean appendRowToTable(String rowData[])
  { /* appendRowToTable */
    if(rowData==null || rowData.length!=tCols)
      return(false);
    
    int 
      new_tRows= tRows+1;
    String 
      newRow[]= new String[tCols],
      new_tData[][]= new String[new_tRows][tCols];
    
    /* Copy by VALUE not REFERENCE */
    for(int c= 0;c<tCols;c++)
      newRow[c]= new String(rowData[c]);  
    
    if(tData!=null)
      for(int r=0;r<tRows;r++)
        new_tData[r]= tData[r];
    
    new_tData[tRows]= newRow;    /* Add copy to the end */
    tData= new_tData;            /* Replace the tData array */
    tRows++;
    
    return(true);
  } /* appendRowToTable */ 
  
  
  /**
   * removeRowFromTable() - remove row of data from table.
   * Note: this works with an empty table where tRows==0
   * and tData is null.
   * @param rowToDelete (count from row 0)
   * @return true if row was deleted
   */
  public boolean removeRowFromTable(int rowToDelete)
  { /* removeRowFromTable */
    if(tData==null || tData.length<=rowToDelete || rowToDelete<=tRows)
      return(false);
    
    int 
      rr= 0,
      new_tRows= tRows-1;
    String 
      newRow[]= new String[tCols],
      new_tData[][]= new String[new_tRows][tCols];
    for(int r=0;r<tRows;r++)
      if(r!=rowToDelete)
        new_tData[rr++]= tData[r];
    new_tData[tRows]= newRow;    /* Add copy to the end */
    tData= new_tData;
    tRows--;
    
    return(true);
  } /* removeRowFromTable */
  
  
  /**
   * deleteRowsFromTable() - delete rows from the table and resize the table.
   * This creates a new tData with all missing rows AND NULL rows removed.
   * @param rowsToDelete if not null
   * @return true if succeed
   */
  public boolean deleteRowsFromTable(int rowsToDelete[])
  { /* deleteRowsFromTable */     
    if(tData==null || rowsToDelete==null)
      return(false);
    
    int n= rowsToDelete.length;
    for(int i=0;i<n; i++)
    { /* check for bogus indices */
      if(rowsToDelete[i] >= tData.length ||
         rowsToDelete[i] >= tRows ||
         rowsToDelete[i] < 0)
      {
        errMsgLog += "DRYROT bad Table["+tName+"] row index ("+ 
                     rowsToDelete[i]+ 
                     ") is outside of row range [0:"+tRows+"]\n";
        lastErrMsgLog= errMsgLog;
        return(false);
      }
    }
    
    for(int i=0;i<n; i++)
    { /* clear rows to be deleted */
      tData[rowsToDelete[i]]= null;
    }
    
    int newRows= 0;
    for(int i=0;i<tRows; i++)
    { /* clear rows to be deleted */
      if(tData[i]!=null)
        newRows++;
    }
    
    String tDataNew[][]= new String[newRows][];
    int r= 0;
    for(int i=0;i<tRows;i++)
    { /* copy non-null rows */
      if(tData[i]!=null)
        tDataNew[r++]= tData[i];
    }
    
    /* Replace instance variables */
    tRows= newRows;
    tData= tDataNew;
    
    return(true);
  } /* deleteRowsFromTable */  

  
  /** 
   * deleteTrailingEmptyColumnsFromTable() - removes empty trailing columns
   * from defined as columns in a Table with a header as null 
   * column names. If the flag is set, after the table is created, 
   * we tFields for the first empty cell. We then rebuild tFields,
   * tHeader and tData to the new size and set tCols to the new size.
   * @return true if removed any columns from the table.
   * [TODO]
   */
  public boolean deleteTrailingEmptyColumnsFromTable()
  { /* deleteTrailingEmptyColumnsFromTable */
    if(tFields==null || tCols==0)
      return(false);
    
    int emptyColIdx= -1;
    for(int c=0;c<tCols;c++)
      if(tFields[c]==null || tFields[c].equals(""))
      { /* found blank header cell */
        emptyColIdx= c;
        break;
      }
    if(emptyColIdx==-1)
      return(false);             /* no change */
    
    
    return(true);
  } /* deleteTrailingEmptyColumnsFromTable */
  
  
  /**
   * mapHeaderColNames() - map tField & tHeaders old to new names in map list.
   * @param oldHdrMapNames is list of current (old) header column names.
   * @param newHdrMapNames is list of new header column names.
   * @param nHdrMapNames is number of header column names to map.
   * @return true if successful, null if no names matched
   */
  public boolean mapHeaderColNames(String oldHdrMapNames[], 
                                String newHdrMapNames[], 
                                int nHdrMapNames)
  { /* mapHeaderColNames */
    if(oldHdrMapNames==null || newHdrMapNames==null || nHdrMapNames<=0 ||
       tFields==null || tCols<= 0)
      return(false);
    
    /* Look for a match */
    for(int m=0;m<nHdrMapNames;m++)
    { /* map m'th map entry if match */
      String 
        oldName= oldHdrMapNames[m],
        newName= newHdrMapNames[m]; 
      for(int c=0;c<tCols;c++)
        if(tFields[c]==null || tFields[c].equals(oldName))
      { /* found match - replace the strings */
        tFields[c]= new String(newName);
        if(tHdrRows>0 && tHeader!=null && tHeader[tHdrRows-1]!=null)
          tHeader[tHdrRows-1][c]= new String(newName);
        break;
      }
    } /* map m'th map entry if match */
    
    return(true);
  } /* mapHeaderColNames */
  
  
  /**
   * setFieldsToTable() - set the Fields list to the Table and set tCols.
   * @param fieldNames is the list of field column names.
   * @return true if added fieldNames to Table
   */
  public boolean setFieldsToTable(String fieldNames[])
  { /* setFieldsToTable */
    if(fieldNames==null)
      return(false);
    tCols= fieldNames.length;
    tFields= new String[tCols];
    for(int c=0;c<tCols;c++)
      tFields[c]= new String(fieldNames[c]);
    return(true);
  } /* setFieldsToTable */
  
  
  /**
   * setHeadersToTable() - set the Headers list to the Table and set tHdrRows.
   * @param hdrNames is the lists of tHeaders column names.
   * @param nHeaders is the number of columns in the header that should
   *                match the tFields if it exists.
   * @param nCols this is the number of columns in the tHeader rows, 
   *                and should be the same as in tFields[].
   * @return true if added fieldNames to Table
   */
  public boolean setHeadersToTable(String hdrNames[][], int nHeaders, 
                                   int nCols)
  { /* setHeadersToTable */
    if(hdrNames==null || nHeaders<=0)
      return(false);

    String new_tHeader[][]= new String[nHeaders][];
    for(int h=0;h<nHeaders;h++)
    {
      String rowData[]= hdrNames[h];
      if(rowData.length!=nCols)
        return(false);            /* bad header data */
      new_tHeader[h]= new String[nCols];
      for(int c=0;c<nCols;c++)
        new_tHeader[h][c]= new String(hdrNames[h][c]);     
    }

    tHdrRows= nHeaders;
    tHeader= new_tHeader;
    
    return(true);
  } /* setHeadersToTable */
  
  
  /**
   * addEmptyColumnToExistingTable() - add empty column to existing Table.
   * Create an empty column of data of size this.tRows with values "".
   * Do NOT add Header extension as well set it to nulls if header
   * exists in the Table.
   * @param newFieldName the new field name. If the field name already
   *        exists, then do not add the field.
   * @param colData is optional data for the new field. The size of the
   *        array must be [0:tRows-1]. If adding the data to an existing
   *        column, just replace the data.
   * @return true if added column to table or column already existed,
   *         false if any problems
   * @see #replaceColumnData
   */
  public boolean addEmptyColumnToExistingTable(String newFieldName)
  { /* addEmptyColumnToExistingTable */
    String colData[]= new String[this.tRows];
    for(int r=0;r<tRows;r++)
      colData[r]= new String("");
    return(addColumnToTable(newFieldName, null, colData));
  } /* addEmptyColumnToExistingTable */
  
  
  /**
   * addColumnToTable() - add a new column to the Table with the specified
   * field name. If there is column data specified, then add it to the table
   * otherwise set null entries the entries to "".
   * Do NOT add Header extension as well set it to nulls if header
   * exists in the Table.
   * @param newFieldName the new field name. If the field name already
   *        exists, then do not add the field.
   * @param colData is optional data for the new field. The size of the
   *        array must be [0:tRows-1]. If adding the data to an existing
   *        column, just replace the data.
   * @return true if added column to table or column already existed,
   *         false if any problems
   * @see #replaceColumnData
   */
  public boolean addColumnToTable(String newFieldName, String colData[])
  { /* addColumnToTable */
    return(addColumnToTable(newFieldName, null, colData));
  } /* addColumnToTable */

  
  /**
   * addColumnToTable() - add a new column to the Table with the specified
   * field name. If there is column data specified, then add it to the table
   * otherwise set null entries the entries to "".
   * Add Header as well if the current Table has a header, else ignore it.
   * If there is no newHdrCols data, copy "" for those cells.
   * @param newFieldName the new field name. If the field name already
   *        exists, then do not add the field.
   * @param newHdrCols[] is the new header column data [0:tHdrRows] if not
   *        null. If it is null, then fill in the extended header entries
   *        with "".  
   * @param colData is optional data for the new field. The size of the
   *        array must be [0:tRows-1]. If adding the data to an existing
   *        column, just replace the data. 
   * @return true if added column to table or column already existed,
   *         false if any problems
   * @see #replaceColumnData
   */
  public boolean addColumnToTable(String newFieldName, String newHdrCols[],
                                  String colData[])
  { /* addColumnToTable */
    return(addColumnToTable(newFieldName, newHdrCols, colData, true));
  } /* addColumnToTable */
    
  
  /**
   * addColumnToTable() - add a new column to the Table with the specified
   * field name. If there is column data specified, then add it to the table
   * otherwise set null entries the entries to "".
   * Add Header as well if the current Table has a header, else ignore it.
   * If there is no newHdrCols data, copy "" for those cells.
   * @param newFieldName the new field name. If the field name already
   *        exists, then do not add the field.
   * @param newHdrCols[] is the new header column data [0:tHdrRows] if not
   *         null. If it is null, then fill in the extended header entries
   *         with "".  
   * @param colData is optional data for the new field. The size of the
   *        array must be [0:tRows-1]. If adding the data to an existing
   *        column, just replace the data. 
   * @param hasColDataFlag - has column data and fill the row data
   *        if any with "" data.
   * @return true if added column to table or column already existed,
   *         false if any problems
   * @see #replaceColumnData
   */
  public boolean addColumnToTable(String newFieldName, String newHdrCols[],
                                  String colData[], boolean hasColDataFlag)
    { /* addColumnToTable */
    if(newFieldName==null)
      return(false);
    if(hasColDataFlag && (colData==null || (tRows>0 && colData.length!=tRows)))
      return(false);
    if((newHdrCols!=null && tHeader!=null) && newHdrCols.length!=tHdrRows)
      return(false);

    /* [1] See if column exists */
    int 
      colIdx= lookupFieldIdx(newFieldName);  
    
    /* [2] If the first column does not exist and there is no data in Table 
     * then make a new tData[][] and set tRows to 1.
     */
    if(colIdx==-1 && tCols==0)
    { /* create new one column Table */ 
      tCols= 1;
      colIdx= 0;
      tFields= new String[1];
      tFields[0]= newFieldName;
      if(tHdrRows>0)
      { /* Make 1 column header row */
        tHeader= new String[tHdrRows][];
        for(int h=0;h<tHdrRows;h++)
        {
          tHeader[h]= new String[1];
          if(newHdrCols!=null)
            tHeader[h][0]= newHdrCols[h];
          else
            tHeader[h][0]= (h==tHdrRows-1) ? newFieldName : "";
        }
      } /* Make 1 column header row */
      
      /* If there is column data, then make empty row */
      if(hasColDataFlag && colData!=null)
      { /* make empty row of one column */
        tRows= colData.length;
        tData= new String[tRows][];
        for(int r=0;r<tRows;r++)
          tData[r]= new String[tCols];
      }
    } /* create new one column Table */

    /* [3] Else if column does not exist and hasColDataFlag add new 
     * Column at the right end of the table and copy the data by VALUE 
     * from the existing columns.
     */
    else if(colIdx==-1)
    { /* Add new Column at the right end of the table */  
      String newFields[]= new String[tCols+1];
      for(int c=0;c<tCols;c++)
        newFields[c]= tFields[c];
      tFields= newFields;
      tFields[tCols]= newFieldName;
      
      /* We add the new newHdrCols data only if current Table has header */ 
      String newHeaders[][]= null;
      if(tHdrRows>0)
      { /* If header exists, extend it */
        newHeaders= new String[tHdrRows][];
        for(int h=0;h<tHdrRows;h++)
        { /* copy new header row */
          newHeaders[h]= new String[tCols+1];
          for(int c=0;c<tCols;c++)
            newHeaders[h][c]= tHeader[h][c];
          String cell= (newHdrCols==null) ? "" : newHdrCols[h];
          if(newHdrCols!=null)
            cell= newHdrCols[h];
          else
            cell= (h==tHdrRows-1) ? tFields[tCols] : "";
          newHeaders[h][tCols]= cell;
        } /* copy new header row */
        tHeader= newHeaders;
      } /* If header exists, extend it */
    
      /* Add column to table data */  
      int
        new_tCols= tCols+1;
      String 
        rowData[],
        newRowData[];

      /* Always add column data to table data, even it no column data
       * so there is a placeholder column.
       */
      String
        new_tData[][]= new String[tRows][new_tCols];
      if(tRows>0 && tData==null)
      { 
        tData= new String[tRows][];          /* sync it */
        for(int r=0;r<tRows;r++)
          tData[r]= new String[tCols+1]; 
      }
      
      for(int r=0;r<tRows;r++)
      { /* expand each row if needed */
        rowData= tData[r];
        if(rowData!=null)
        { /* copy row data since not null */
          newRowData= new String[new_tCols];
          new_tData[r]= newRowData;
          /* Copy old data by VALUE not REFERENCE */
          for(int c= 0;c<tCols;c++)
            newRowData[c]= new String(rowData[c]);
          
          /* Always add placeholder cell at the end in case !hasColDataFlag */
          newRowData[tCols]= new String(""); 
        }
      } /* expand each row if needed */
      
      /* Adjust data array, index and # cols */
      tData= new_tData;
      
      /* Adjust index and # cols */
      colIdx= tCols;
      tCols++;      
    } /* Add new Column at the right end of the table */

    /* [3] Then add data if need be to colIdx if colData exists. */
    boolean flag= true;
    if(hasColDataFlag && colData!=null)
      flag= replaceColumnData(colIdx, colData, false);
    
    return(flag);
  } /* addColumnToTable */ 
  
  
  /**
   * replaceColumnData() - replace Table data in a column by reference.
   * Set null entries to "".
   * @param fieldName is the field name for the column.
   * @param colData is column data for the new field. The size of the
   *        array must be [0:tRows-1]. If adding the data to an existing
   *        column, just replace the data.
   * @return true if replaced data in column
   * @see #lookupFieldIdx
   * @see #replaceColumnData
   */
  public boolean replaceColumnData(String fieldName, String colData[])
  { /* replaceColumnData */
    int colIdx= lookupFieldIdx(fieldName);    
    return(replaceColumnData(colIdx, colData, false));
  } /* replaceColumnData */ 
  
  
  /**
   * replaceColumnData() - replace Table data in a column by value.
   * Set null entries to "".
   * @param fieldName is the field name for the column.
   * @param colData is column data for the new field. The size of the
   *        array must be [0:tRows-1]. If adding the data to an existing
   *        column, just replace the data.
   * @return true if replaced data in column
   * @see #lookupFieldIdx
   * @see #replaceColumnData
   */
  public boolean replaceColumnDataByValue(String fieldName, String colData[])
  { /* replaceColumnData */
    int colIdx= lookupFieldIdx(fieldName);    
    return(replaceColumnData(colIdx, colData, true));
  } /* replaceColumnData */ 
  
  
  /**
   * replaceColumnData() - replace data in a column in the Table.
   * Set null entries to "".
   * @param colIdx is the field index for the column.
   * @param colData is column data for the new field. The size of the
   *        array must be [0:tRows-1]. If adding the data to an existing
   *        column, just replace the data.
   * @param replaceByValueFlag - to replace by value else by reference.
   * @return true if replaced data in column, false if problem
   */
  public boolean replaceColumnData(int colIdx, String colData[],
                                   boolean replaceByValueFlag)
  { /* replaceColumnData */
    if(colIdx==-1 || colData==null || colData.length!=tRows)
      return(false);
    
    String 
      value,
      rowData[];
    for(int r=0;r<tRows;r++)
    { /* process row r */
      rowData= tData[r];      
      value= colData[r];
      if(rowData==null && value!=null)
      { /* Make row since have non-null value */
        rowData= new String[tCols];
        tData[r]= rowData;
      }
      if(value==null)
        value= "";
      else if(replaceByValueFlag)
        value= new String(value);  /* replace by value */
      rowData[colIdx]= value; 
    } /* process row r */
    
    return(true);
  } /* replaceColumnData */ 
  
   
  /**
   * setColumnDataByValue() - set all data in a column in Table to a value.
   * Set null entries to "".
   * @param fieldName is the field name for the column.
   * @param colValue is column data for the new field. 
   * @return true if replaced data in column
   * @see #lookupFieldIdx
   * @see #replaceColumnData
   */
  public boolean setColumnDataByValue(String fieldName, String colValue)
  { /* setColumnDataByValue */
    int colIdx= lookupFieldIdx(fieldName); 
    return(setColumnDataByValue(colIdx, colValue));
  } /* setColumnDataByValue */ 
  
  
  /**
   * setColumnDataByValue() - set all data in a column in Table to a value.
   * Set null entries to "".
   * @param colIdx is the field index for the column.
   * @param colValue is column data for the new field. 
   * @return true if replaced data in column
   */
  public boolean setColumnDataByValue(int colIdx, String colValue)
  { /* setColumnDataByValue */    
    String colData[]= new String[tCols];
    for(int c=0;c<tCols;c++)
      colData[c]= colValue;
    
    return(replaceColumnData(colIdx, colData, false));
  } /* setColumnDataByValue */
    
  
  /**
   * getColumnData() - lookup the column name and then return all
   * data in the column from tData[][c] if the column exists. 
   * If there are null rows at the end of the table, do not 
   * return those data so the length of the table is the actual
   * number of items. This assumes that all null rows are at the
   * end of the table.
   * @param columnName the field name.
   * @return the array of column data, else null 
   */
  public String[] getColumnData(String colName)
  { /* getColumnData */
    if(colName==null)
      return(null); 
    int 
      nNonNullRows= 0,
      colIdx= lookupFieldIdx(colName);
    if(colIdx==-1)
      return(null);
    
    String 
      rowData[],
      colData[]= new String[tRows];    
    for(int r=0;r<tRows;r++)
    { /* expand each row if needed */
      rowData= tData[r];
      if(rowData==null)
        break;                   /* end of table */
      colData[nNonNullRows++]= rowData[colIdx];
    } /* expand each row if needed */
    
    if(tRows>nNonNullRows)
    { /* Shrink the array by removing empty cells at the end */
      String newColData[]= new String[nNonNullRows];
      for(int r=0;r<nNonNullRows;r++)
        newColData[r]= colData[r];
      colData= newColData;
    }
          
    return(colData);
  } /* getColumnData */ 
  
  
  /**
   * reorderRowsBySortIndex() - reorder the entire table rows by the sortIdx.
   * I.e. if sortIdx[0]=4, sortIdx[1]= 7, etc., then tRow[0] gets move
   * to tRow[4], tRow[1] gets moved to tRow[7] etc.
   * @param sortIdx is array of new row 'toRow' indexes 
   * @param return true if successful.
   */
  public boolean reorderRowsBySortIndex(int sortIdx[])
  { /* reorderRowsBySortIndex */
    if(sortIdx==null || sortIdx.length>tRows)
      return(false);
    int
      siLth= sortIdx.length,
      rFrom;
    String 
      rowData[]= null,
      tData2[][]= new String[siLth][];
    
    for(int rTo=0;rTo<siLth;rTo++)
    {
      rFrom= sortIdx[rTo];
      rowData= tData[rFrom];
      tData2[rTo]= rowData;
    }
    
    tData= tData2;
    tRows= siLth;                 /* may shorten it */
    
    return(true);
  } /* reorderRowsBySortIndex */
  
  
  /**
   * reorderColumnsInTable() - reorder Table tFields and tData by column
   * index of the Table based on the list of column header names 
   * reordColName[0:nReorderColName-1] to be reordered by a corresponding
   * list of new column numbers in reordColNbr[]. 
   * <P>
   * Multiple new columns must be different. All reorderColName[]
   * names must be in tFields or it is an error.
   * Those columns not specified are moved toward the right. 
   * This is done after the list of dropped columns has been 
   * processed. It will also reorder the tData column
   * if tData exists (i.e., is not null).
   * <P>
   * if reorderRemainingColumnsAlphabeticlyFlag is set, then sort the 
   * remaining columns not specified, but that are used, alphabetically.
   * <P>
   * @param reordColName - list of column names to be reordered
   * @param reordColNbr - corresponding list of new column numbers
   *                      starting at 1 (used specified, but we
   *                      map to n-1).
   * @param nReorderColName - number of mappings
   * @param reorderRemainingColsFlag to sort the remaining
   *                      columns not specified, but that are used,
   *                      alphabetically.
   * @return true if succeed else if fail the errMsgLog string
   *         is set with the reason it failed.
   */
  public boolean reorderColumnsInTable(String reordColName[],
                                       int reordColNbr[],
                                       int nReorderColName,
                                       boolean reorderRemainingColsFlag)
  { /* reorderColumnsInTable */
    String
      roColName,
      copyReorderColName[]= new String[nReorderColName];
    int
      roColIdx,
      copyReorderColNbr[]= new int[nReorderColName],
      c;
    boolean flag;
    
    /* [1] Make sure have tFields */
    if(tFields==null)
    { /* No tFields in the Table */
      errMsgLog += "FT-RCIT there is no Table (no tFields) header" +
                  " - ignoring reorder.\n";
      lastErrMsgLog= errMsgLog;
      return(false);      
    }
    
    if(tFields.length!=tCols)
    { /* No tFields in the Table */
      errMsgLog += "FT-RCIT DRYROT |tFields|="+tFields.length+
                 " .NEQ tCols="+tCols + " - ignoring reorder.\n";
      lastErrMsgLog= errMsgLog;
      return(false);      
    }

    if(nReorderColName==0 || reordColName==null)
    { /* No tFields in the Table */
      errMsgLog += "FT-RCIT there is no Reorder columns list" +
                  " - ignoring reorder.\n";
      lastErrMsgLog= errMsgLog;
      return(false);      
    }

    /* work off of local copy */
    for(int i=0;i<nReorderColName;i++)
    {
      copyReorderColName[i]= reordColName[i];
      copyReorderColNbr[i]=  reordColNbr[i];
    }
    
    /* [1.1] Make sure all reorder column names exist in tFields.
     * If not, then remove it from the reorder list and adjust
     * the higher reorder numbers if necessary.
     */    
    for(int n=0;n<nReorderColName;n++)
    { /* make sure roColName is in tFields */
      roColName= copyReorderColName[n];
      if(roColName==null)
      { /* No tFields in the Table */
        errMsgLog += "FT-RCIT DRYROT null reorderColName[" +n+
                     "] - ignoring it and continuing.\n";
        lastErrMsgLog= errMsgLog;
        continue;      
      }
      
      flag= false;
      for(c= 0;c<tCols;c++)
        if(roColName.equals(tFields[c]))
        {
          flag= true;
          break;
        }
      if(!flag)
      { /* can't find reorder column name in tFields */
        errMsgLog += "FT-RCIT can't find reorder " +
                     "column '"+ roColName+
                     "' in tFields Table header\n -" +
                     " ignoring it and continuing.\n";
        lastErrMsgLog= errMsgLog;
        
        /* [NOTE] We MUST renumber some elements in the list,
         * otherwise it will currently introduce 'holes' in the list.
         * Solve this problem by decrementing reorderColNbr[n1+1] 
         * IFF it is > reorderColNbr[n] to keep it legal.
         */
        int
          missingColToNbr= copyReorderColNbr[n],
          newToNbr= -1;
        
        for(int n1=n;n1<(nReorderColName-1);n1++)
        { /* remove it from the reorder list */
          copyReorderColName[n1]= copyReorderColName[n1+1];
          newToNbr= copyReorderColNbr[n1+1];
          if(newToNbr>missingColToNbr)
            newToNbr--;      /* decrement it to keep it legal */
          copyReorderColNbr[n1]= newToNbr;
        } /* remove it from the reorder list */
        nReorderColName--;       /* shorten the list */
        n--;                     /* Backup the search by 1 */
        copyReorderColName[nReorderColName]= null;
        copyReorderColNbr[nReorderColName]= -1;
      }
    } /* make sure roColName is in tFields */    

    /* [2] Make sure all reorder new col indexes are different. */
    for(int n=0;n<nReorderColName;n++)
    { /* make sure reorderColNbr[] are unique */
      roColIdx= copyReorderColNbr[n];
      flag= false;
      for(int n2= n+1; n2<nReorderColName;n2++)
        if(roColIdx==copyReorderColNbr[n2])
        { /* duplicate reorder column numbers - impossible */
          errMsgLog += "FT-RCIT dup. reorder column numbers " +
                       "["+roColIdx+"] for '"+copyReorderColName[n]+
                       "' and '"+copyReorderColName[n2]+"'.\n";
          lastErrMsgLog= errMsgLog;
          return(false);            
        }
    } /* make sure reorderColNbr[] are unique */
    
    /* [2.1] Make sure all reorder new col names are different so
     * there are no duplicates. 
     */
    for(int n=0;n<nReorderColName;n++)
    { /* make sure reorderColNbr[] are unique */
      roColName= copyReorderColName[n];
      flag= false;
      for(int n2= n+1; n2<nReorderColName;n2++)
        if(roColName.equals(copyReorderColName[n2]))
        { /* duplicate reorder column numbers - impossible */
          errMsgLog += "FT-RCIT dup. reorder column " +
                       "names ["+roColName+"] for '"+copyReorderColNbr[n]+
                       "' and '"+copyReorderColNbr[n2]+"'.\n";
          lastErrMsgLog= errMsgLog;
          return(false);            
        }
    } /* make sure reorderColNbr[] are unique */
            
    /* [3] Setup the old and new index maps. */
    int
      oldToNewMap[]= new int[tCols];  /* old to new index, index by c */
    boolean
      isMapped[]= new boolean[tCols]; /* list of unmapped fields */
    for(c= 0;c<tCols;c++)  
    { /* set mapping field to -1 (i.e., not-mapped) */
      oldToNewMap[c]= -1;  
      isMapped[c]= false;
    }
    
    /* [3.1] Create partial map for what will be reordered */
    int
      nReorderMapped= 0;
    for(int n=0;n<nReorderColName;n++)
    { /* Create partial map for what will be reordered */
      roColName= copyReorderColName[n];
      roColIdx= copyReorderColNbr[n]-1;  /* Note we work in [0:tCols-1]
                                          * space not [1:tCols] space */
      flag= false;
      for(c= 0;c<tCols;c++)
        if(roColName.equals(tFields[c]))
        {
          oldToNewMap[roColIdx]= c;
          isMapped[c]= true;
          nReorderMapped++;
          flag= true;
          break;
        }
    } /* Create partial map for what will be reordered */   
    
    /* [3.2] Make sequential list of any unmapped fields. */
    int
      nUnmapped= 0,
      unmappedFields[]= new int[tCols];
    if(!reorderRemainingColsFlag)
    { /* build map of unmapped fields - do not sort */
      nUnmapped= 0;
      for(c= 0; c < tCols; c++)
        if(!isMapped[c])
        {
          unmappedFields[nUnmapped++]= c;
        }
    } /* build map of unmapped fields - do not sort */
    else
    { /* build map of unmapped fields - DO ALPHABETIC SORT */
      /* Note: only sort is if all unmodified fields are in 
       * the reordered list. Check for order independent exact contents
       * match  to make sure all unmodified fields are in reordered list.
       */
      boolean 
        doSortFlag= UtilCM.isListInAnotherList(unmodifiedFieldNames, 
                                               nUnmodifiedFieldNames,
                                               reordColName, 
                                               nReorderColName); 
      /* Make rFields[] list in any case */
      String rFields[]= new String[tCols];
      nUnmapped= 0;
      for(c= 0; c < tCols; c++)
        if(!isMapped[c])
          rFields[nUnmapped++]= tFields[c];
      
      /* Only sort if clean data to sort  - ignore sort for
       * missed data.  
       */
      int sortIdx[]= null;
      if(doSortFlag)
        sortIdx= Sort.bubbleSortIndex(rFields,nUnmapped,true);
      
      if(sortIdx!=null)
      { /* Use sorted remaining fields */
        String rName;
        int
          rIdx,
          tfIdx,
          nSorted= nUnmapped;
        nUnmapped= 0;
        for(c= 0; c < nSorted; c++)
          if(!isMapped[c])
          {
            rIdx= sortIdx[c];
            rName= rFields[rIdx];
            tfIdx= lookupFieldIdx(rName);
            unmappedFields[nUnmapped++]= tfIdx;
          }
      } /* Use sorted remaining fields */
      else
      { /* sort failed - build map of unmapped fields - do not sort */
        nUnmapped= 0;
        for(c= 0; c < tCols; c++)
          if(!isMapped[c])
          {
            unmappedFields[nUnmapped++]= c;
          }
      } /* sort failed - build map of unmapped fields - do not sort */
    } /* build map of unmapped fields - DO ALPHABETIC SORT */      
    
    /* [3.3] Assign unmapped fields to unused slots in the map
     * from left to right.
     */
    nUnmapped= 0;
    for(c= 0;c<tCols;c++)
      if(oldToNewMap[c]==-1)
      {
        oldToNewMap[c]= unmappedFields[nUnmapped++];
      }
                    
    /* [4] Reorder the columns in the tFields */
    String
      sTmpFields[]= new String[tCols],
      sTmpHeader[][]= new String[tHdrRows][tCols];
    int 
      fromIdx;
    for(c=0;c<tCols;c++)
    { /* build reordered tFields & tHeaders lists */
      fromIdx= oldToNewMap[c];
      sTmpFields[c]= new String(tFields[fromIdx]);   /* copy cells */
      if(tHdrRows>0)
        for(int h=0;h<tHdrRows;h++)
          sTmpHeader[h][c]= new String(tHeader[h][fromIdx]);
    } /* build reordered tFields list */
    
    for(c=0;c<tCols;c++)
    { /* Copy reordered tFields & tHeaders lists back */
      tFields[c]= sTmpFields[c];
      if(tHdrRows>0)
        for(int h=0;h<tHdrRows;h++)
         tHeader[h][c]= sTmpHeader[h][c];
    } /* Copy reordered tFields & tHeaders lists back */
    
    /* [5] Reorder the columns in all of the tData rows if 
     * tData exists (i.e.,  is not null). 
     */
    if(tData != null)
    { /* delete the column from tData */
      String tDataRow[]= new String[tCols];
      for(int r= 0; r < tRows; r++)
      { /* Reorder tData row r */
        String sTmpRow[]= new String[tCols];
        tDataRow= tData[r];
        if(tDataRow == null)
          break; /* ignore empty rows */

        for(c= 0; c < tCols; c++)
        { /* build reordered tData[r] row list */
          fromIdx= oldToNewMap[c];
          sTmpRow[c]= tDataRow[fromIdx]; /* copy individual cells */
        }
        /* Copy local reordered tData[r] row list back to tData[r] */
        tData[r]= sTmpRow;
      } /* Reorder tData row r */
    } /* delete the column from tData */
        
    return(true);
  } /* reorderColumnsInTable */
  
    
  /**
   * joinTableToCurrentTable() - join another Table ftJoin to current Table.
   * @param ftJoin is the Table file to join to current Table
   * @return true if succeed.
   */
   public boolean joinTables(FileTable ftJoin)
   { /* joinTableToCurrentTable */         
     /* [1] Make sure two tables have the same number of rows */
     if(ftJoin.tRows!=this.tRows)
     {
       this.errMsgLog += "Problem joining tables - joinTable has "+
                         ftJoin.tRows+ " rows, currentTable has "+
                         this.tRows+" rows.\n";
       lastErrMsgLog= errMsgLog;
       return(false);
     }    
     if(ftJoin.tHdrRows!=this.tHdrRows)
     {
       this.errMsgLog += "Problem joining tables - joinTable has "+
                         ftJoin.tHdrRows+ " HdrRows, currentTable has "+
                         this.tRows+" HdrRows.\n";
       lastErrMsgLog= errMsgLog;
       return(false);
     }    
     
     /* [2] If fields in ftJoin are not in ft, then add the columns to ft.
      * This avoids duplicates. If reordering columns is used later, it
      * will take care of the order.
      */
     for(int j=0;j<ftJoin.tCols;j++)
     { /* test if join ftJoin.tFields[j] */
       String 
         fieldJ= ftJoin.tFields[j];
       if(this.lookupFieldIdx(fieldJ)!=-1)
         continue;                   /* column exists, ignore it */
       
       String colData[]= new String[ftJoin.tRows];
       for(int r=0;r<ftJoin.tRows;r++)
       { /* build column list */
         colData[r]= ftJoin.tData[r][j];
       } /* add fieldJ to ft */

       /* Setup the hdrColJ data if it exists */
       String hdrColJ[]= null;
       if(ftJoin.tHdrRows>0)
       {
         hdrColJ= new String[ftJoin.tHdrRows];
         for(int h=0;h<ftJoin.tHdrRows;h++)
           hdrColJ[h]= ftJoin.tHeader[h][j];
       }  
       
       /* Add the new column */
       if(!this.addColumnToTable(fieldJ, hdrColJ, colData))
       {
         this.errMsgLog += "Problem joining tables - addColumnToTable error'\n";
         lastErrMsgLog= errMsgLog;
         return(false);
       }  
     } /* test if join ftJoin.tFields[j] */
     
      return(true);
   } /* joinTableToCurrentTable */ 
   
   
   /**
    * trimTableEnclWhitespace() - trim (clean) enclosing white space in Table.
    * Either the header or data areas can be cleaned.
    * It goes cell by cell to try to remove white space. If a cell is
    * cleaned, it replaces the cell string, otherwise the cell string is not 
    * replaced.
    * @param cleanHeaderFlag to clean the tFields and tHeader
    * @param cleanDataFlag to clean the tData
    */
    public void trimTableEnclWhitespace(boolean cleanHeaderFlag, 
                                       boolean cleanDataFlag)
    { /* trimTableEnclWhitespace */   
      if(cleanHeaderFlag && tFields!=null)
      { /* clean the header */
        for(int c=0;c<tCols;c++)
        {
          tFields[c]= tFields[c].trim();
          if(tHeader!=null)
            for(int h=0;h<tHdrRows;h++)
              tHeader[h][c]= tHeader[h][c].trim();
        }
      } /* clean the header */
      
      if(cleanDataFlag &&tData!=null)
      { /* Clean tData[][] */
        for(int r=0;r<tRows;r++)
          for(int c=0;c<tCols;c++)
          {
            tData[r][c]= tData[r][c].trim();
          }        
      } /* Clean tData[][] */
    } /* trimTableEnclWhitespace */
        
    
   /**
    * sortTableRowsByField() - sort table rows by field.
    * It can sort the data either numerically or by string depending
    * on whether the first cell has a number in it.
    * Get the column data and then do a bubble sort of that data. 
    * Use the sort index to then sort the rows of the Table.
    * It looks up the field column index and then sorts by column.
    * @param sortField is the field to sort by and to use in the thresholding
    * @param useNumericSortFlag sort data numerically else by string
    * @param sortTblAscendingFlag to sort the table in ascending order
    * @param useAbsValueFlag to ignore the sign of the data in the search.
    *        If the table is sorted by numeric value, and both + and - changes
    *        were found, it will set the this.needToSortTableAgainFlag
    *        so the calling program can resort one more time if it wants.
    *        to keep the data in numeric order.
    * @return true if succeed, false if fail with error message in errMsgLog.
    *         Also set this.needToSortTableAgainFlag if need to report later.
    */
    public boolean sortTableRowsByField(String sortField,
                                        boolean sortTblAscendingFlag,
                                        boolean useAbsValueFlag)
    { /* sortTableRowsByField */
      if(tData==null || sortField==null)
        return(false);
       
      int idxSortField= this.lookupFieldIdx(sortField);
      if(idxSortField==-1)
        return(false);
       
      boolean ok= sortTableRowsByField(idxSortField, sortField,
                           sortTblAscendingFlag,useAbsValueFlag);
      return(ok);
    } /* sortTableRowsByField */
    
    
    /**
     * sortTableRowsByField() - sort table rows by idxSortField field index.
     * It can sort the data either numerically or by string depending
     * on whether the first cell has a number in it.
     * Get the column data and then do a bubble sort of that data. 
     * Use the sort index to then sort the rows of the Table.
     * @param idxSortField is the field index to sort by.
     * @param sortField is the name of sort field to sort by for msgs
     * @param useNumericSortFlag sort data numerically else by string
     * @param sortTblAscendingFlag to sort the table in ascending order
     * @param useAbsValueFlag to ignore the sign of the data in the search.
     *        If the table is sorted by numeric value, and both + and - changes
     *        were found, it will set the this.needToSortTableAgainFlag
     *        so the calling program can resort one more time if it wants.
     *        to keep the data in numeric order.
     * @return true if succeed, false if fail with error message in errMsgLog.
     *         Also set this.needToSortTableAgainFlag if need to report later.
     */
     public boolean sortTableRowsByField(int idxSortField, String sortField,
                                         boolean sortTblAscendingFlag,
                                         boolean useAbsValueFlag)
     { /* sortTableRowsByField */
       if(tData==null || idxSortField==-1 || sortField==null)
         return(false);        
       
       if(idxSortField==-1)
         return(false);
        
       String
         colData[]= this.getColumnData(sortField); 
       boolean
         sawPositiveValueFlag= false,
         sawNegativeValueFlag= false; 
       this.needToSortTableAgainFlag= false;  /* Set global flag in case
                                               * need to resort */
       
       if(colData == null)
       { /* no data to sort */
         errMsgLog= "Problem sorting Table by column. \n  Can't "+
                     "find any of the sort-by '"+sortField+"' columns.";
         return(false);
       }
       else
       { /* sort by column data */
        /* If all colData is a number, then convert the String[]
         * data to float[] and sort on that.
         */
        int 
          sortIdx[]= null, 
          nRows= colData.length;
        double 
          dValue,
          doubleData[]= new double[nRows];
        for(int r= 0; r < nRows; r++)
          if(UtilCM.isNumber(colData[r]))
          {
            dValue= UtilCM.cvs2d(colData[r]);
            if(dValue>0)
              sawPositiveValueFlag= true;
            else if(dValue>0)
              sawNegativeValueFlag= true;
            doubleData[r]= (useAbsValueFlag) ? Math.abs(dValue) : dValue;
          }
          else
           { /* found a non-number, so sort by string */
             doubleData= null;
             break;
           }        
         if(doubleData != null)
           sortIdx= Sort.bubbleSortIndex(doubleData, nRows,
                                         sortTblAscendingFlag);
         else 
           sortIdx= Sort.bubbleSortIndex(colData, nRows, 
                                         sortTblAscendingFlag);
         if(sortIdx == null)
         {
           errMsgLog= "Problem sorting table by column '" + 
                      sortField + "' - ignoring sort, continuing.\n";
           return (true);
         }

         /* Reorder the entire table rows by the sortIdx. */
         if(!this.reorderRowsBySortIndex(sortIdx))
         {
           errMsgLog= "Problem reordering table by column '" + 
                      sortField + "'.\n";
           return (false);
         }
         errMsgLog= "Finished sorting table by column '" + 
                    sortField + "'.\n";
         
         /* Set global resort flag if need a resort */
         boolean resortFlag= (useAbsValueFlag && sawPositiveValueFlag &&
                              sawNegativeValueFlag );
         this.needToSortTableAgainFlag= resortFlag;
       } /* sort by column data */
       
       return(true);
     } /* sortTableRowsByField */
    
    
   /**
    * limitMaxRows() - keep max nbr rows in front of the Table.
    * @param maxRowsToKeep is the maximum number of rows to keep.
    * @param useAbsValueFlag to ignore the sign of the data in the search.
    *        If the table is sorted by numeric value, and both + and - changes
    *        were found, it will set the this.needToSortTableAgainFlag
    *        so the calling program can resort one more time if it wants.
    * @return true if succeed or there is no change, false if fail with 
    *         error message in errMsgLog
    */
   public boolean limitMaxRows(int maxRowsToKeep, boolean useAbsValueFlag)
   { /* limitMaxRows */
     return(limitMaxRowsSortedByField(null,false, maxRowsToKeep, false,
                                      useAbsValueFlag)); 
   } /* limitMaxRows */
            
       
   /**
    * limitMaxRowsSortedByField() - sort Table by field, then keep max nbr rows. 
    * Save the full table data in this.tDataFull BEFORE shortening the 
    * length of the this.tData. The this.tDataFull is null unless
    * the Table was limited in number of rows. This is useful
    * if we need to get at the full Table later.
    * @param sortField is the field to sort by and to use in the thresholding
    * @param sortTblAscendingFlag 
    * @param maxRowsToKeep is the maximum number of rows to keep.
    * @param useAbsValueFlag to ignore the sign of the data in the search.
    *        If the table is sorted by numeric value, and both + and - changes
    *        were found, it will set the this.needToSortTableAgainFlag
    *        so the calling program can resort one more time if it wants.
    * @return true if succeed or there is no change, false if fail with 
    *         error message in errMsgLog
    */
    public boolean limitMaxRowsSortedByField(String sortField,
                                            boolean sortTblAscendingFlag,
                                            int maxRowsToKeep, 
                                            boolean doSortFirstFlag,
                                            boolean useAbsValueFlag)
    { /* limitMaxRowsSortedByField */
      this.tDataFull= null;        /* clear it just in case */
      
      if(tData==null || maxRowsToKeep<=0)
      {
        errMsgLog= "Can't limit Table rows by field since Table has no data.\n";
        return(false);
      }
       
      if(tData!=null && tRows<=maxRowsToKeep)
        return(true);
       
      /* [1] Sort Table before limit the rows we keep */ 
      this.needToSortTableAgainFlag= false;       /* clear the resort flag */
      if(doSortFirstFlag)
      { /* Sort Table before limit the rows we keep */
        int idxSortField= this.lookupFieldIdx(sortField);
        if(idxSortField==-1)
        {
          errMsgLog= "Can't limit Table rows by field since sortField '"+
                     sortField+"' not found.\n";
          return(false);
        }
      
        /* [1.1] Get the column data and then do a bubble sort of that data
         * by magnitude. Use the sort index to then sort the rows of 
         * the Table.
         */ 
        useAbsValueFlag= true;
        if(!this.sortTableRowsByField(sortField, sortTblAscendingFlag,
                                      useAbsValueFlag))
          return(false);  /* Note it sets the errMsgLog */
      } /* Sort Table before limit the rows we keep */
        
      /* [2] Now remove any rows >= row maxRowsToKeep */
      if(this.tRows>maxRowsToKeep)
      { /* realloc table with smaller tData */
        /* Save the full table data BEFORE the length of the table
         * was limited using limitMaxRowsXXX() methods. It is null unless
         * the Table was limited in number of rows. This is useful
         * if we need to get at the full Table later.
         */
        tDataFull= tData;;

        String new_tData[][]= new String[maxRowsToKeep][];
        for(int r=0;r<maxRowsToKeep;r++)
          new_tData[r]= tData[r];
          
        /* replace in Table */
        tRows= maxRowsToKeep;
        tData= new_tData;
      } /* realloc table with smaller tData */
      
      /* [3] If there were both + and - data, we may need to resort 
       * one more time to do a true numeric sort. Check the
       * this.needToSortTableAgainFlag possibly set by
       * sortTableRowsByField().
       */
      if(this.needToSortTableAgainFlag)
      { /* Need to resort - ONE MORE TIME! */
        this.needToSortTableAgainFlag= false; /* clear the resort flag */
        useAbsValueFlag= false;
        if(!this.sortTableRowsByField(sortField, sortTblAscendingFlag,
                                      useAbsValueFlag))
          return(false);           /* Note it sets the errMsgLog */
      } /* Need to resort - ONE MORE TIME! */
      
      return(true);
    } /* limitMaxRowsSortedByField */
       
  
} /* end of class FileTable */