src/java/org/apache/poi/hssf/usermodel/HSSFRow.java

   1 /* ====================================================================
   2    Licensed to the Apache Software Foundation (ASF) under one or more
   3    contributor license agreements.  See the NOTICE file distributed with
   4    this work for additional information regarding copyright ownership.
   5    The ASF licenses this file to You under the Apache License, Version 2.0
   6    (the "License"); you may not use this file except in compliance with
   7    the License.  You may obtain a copy of the License at
   8
   9        http://www.apache.org/licenses/LICENSE-2.0
  10
  11    Unless required by applicable law or agreed to in writing, software
  12    distributed under the License is distributed on an "AS IS" BASIS,
  13    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14    See the License for the specific language governing permissions and
  15    limitations under the License.
  16 ==================================================================== */
  17
  18 /*
  19  * HSSFRow.java
  20  *
  21  * Created on September 30, 2001, 3:44 PM
  22  */
  23 package org.apache.poi.hssf.usermodel;
  24
  25 import java.util.Iterator;
  26 import java.util.NoSuchElementException;
  27
  28 import org.apache.poi.hssf.model.Sheet;
  29 import org.apache.poi.hssf.model.Workbook;
  30 import org.apache.poi.hssf.record.CellValueRecordInterface;
  31 import org.apache.poi.hssf.record.RowRecord;
  32
  33 /**
  34  * High level representation of a row of a spreadsheet.
  35  *
  36  * Only rows that have cells should be added to a Sheet.
  37  * @version 1.0-pre
  38  * @author  Andrew C. Oliver (acoliver at apache dot org)
  39  * @author Glen Stampoultzis (glens at apache.org)
  40  */
  41
  42 public class HSSFRow
  43         implements Comparable
  44 {
  45
  46     // used for collections
  47     public final static int INITIAL_CAPACITY = 5;
  48     //private short rowNum;
  49     private int rowNum;
  50     private HSSFCell[] cells=new HSSFCell[INITIAL_CAPACITY];
  51 //    private short firstcell = -1;
  52 //    private short lastcell = -1;
  53
  54     /**
  55      * reference to low level representation
  56      */
  57
  58     private RowRecord row;
  59
  60     /**
  61      * reference to containing low level Workbook
  62      */
  63
  64     private Workbook book;
  65
  66     /**
  67      * reference to containing Sheet
  68      */
  69
  70     private Sheet sheet;
  71
  72     protected HSSFRow()
  73     {
  74     }
  75
  76     /**
  77      * Creates new HSSFRow from scratch. Only HSSFSheet should do this.
  78      *
  79      * @param book low-level Workbook object containing the sheet that contains this row
  80      * @param sheet low-level Sheet object that contains this Row
  81      * @param rowNum the row number of this row (0 based)
  82      * @see org.apache.poi.hssf.usermodel.HSSFSheet#createRow(int)
  83      */
  84
  85     //protected HSSFRow(Workbook book, Sheet sheet, short rowNum)
  86     protected HSSFRow(Workbook book, Sheet sheet, int rowNum)
  87     {
  88         this.rowNum = rowNum;
  89         this.book = book;
  90         this.sheet = sheet;
  91         row = new RowRecord();
  92         row.setOptionFlags( (short)0x100 );   // seems necessary for outlining to work.
  93         row.setHeight((short) 0xff);
  94         row.setLastCol((short) -1);
  95         row.setFirstCol((short) -1);
  96
  97         setRowNum(rowNum);
  98     }
  99
 100     /**
 101      * Creates an HSSFRow from a low level RowRecord object.  Only HSSFSheet should do
 102      * this.  HSSFSheet uses this when an existing file is read in.
 103      *
 104      * @param book low-level Workbook object containing the sheet that contains this row
 105      * @param sheet low-level Sheet object that contains this Row
 106      * @param record the low level api object this row should represent
 107      * @see org.apache.poi.hssf.usermodel.HSSFSheet#createRow(int)
 108      */
 109
 110     protected HSSFRow(Workbook book, Sheet sheet, RowRecord record)
 111     {
 112         this.book = book;
 113         this.sheet = sheet;
 114         row = record;
 115
 116         setRowNum(record.getRowNumber());
 117     }
 118
 119     /**
 120      * Use this to create new cells within the row and return it.
 121      * <p>
 122      * The cell that is returned is a CELL_TYPE_BLANK. The type can be changed
 123      * either through calling <code>setCellValue</code> or <code>setCellType</code>.
 124      *
 125      * @param column - the column number this cell represents
 126      *
 127      * @return HSSFCell a high level representation of the created cell.
 128      */
 129
 130     public HSSFCell createCell(short column)
 131     {
 132       return this.createCell(column,HSSFCell.CELL_TYPE_BLANK);
 133     }
 134
 135     /**
 136      * Use this to create new cells within the row and return it.
 137      * <p>
 138      * The cell that is returned is a CELL_TYPE_BLANK. The type can be changed
 139      * either through calling setCellValue or setCellType.
 140      *
 141      * @param column - the column number this cell represents
 142      *
 143      * @return HSSFCell a high level representation of the created cell.
 144      */
 145
 146     public HSSFCell createCell(short column, int type)
 147     {
 148         HSSFCell cell = new HSSFCell(book, sheet, getRowNum(), column, type);
 149
 150         addCell(cell);
 151         sheet.addValueRecord(getRowNum(), cell.getCellValueRecord());
 152         return cell;
 153     }
 154
 155     /**
 156      * remove the HSSFCell from this row.
 157      * @param cell to remove
 158      */
 159     public void removeCell(HSSFCell cell) {
 160         removeCell(cell, true);
 161     }
 162     private void removeCell(HSSFCell cell, boolean alsoRemoveRecords) {
 163         if(alsoRemoveRecords) {
 164                 CellValueRecordInterface cval = cell.getCellValueRecord();
 165                 sheet.removeValueRecord(getRowNum(), cval);
 166         }
 167
 168         short column=cell.getCellNum();
 169         if(cell!=null && column<cells.length)
 170         {
 171           cells[column]=null;
 172         }
 173
 174         if (cell.getCellNum() == row.getLastCol())
 175         {
 176             row.setLastCol(findLastCell(row.getLastCol()));
 177         }
 178         if (cell.getCellNum() == row.getFirstCol())
 179         {
 180             row.setFirstCol(findFirstCell(row.getFirstCol()));
 181         }
 182     }
 183
 184     /**
 185      * create a high level HSSFCell object from an existing low level record.  Should
 186      * only be called from HSSFSheet or HSSFRow itself.
 187      * @param cell low level cell to create the high level representation from
 188      * @return HSSFCell representing the low level record passed in
 189      */
 190
 191     protected HSSFCell createCellFromRecord(CellValueRecordInterface cell)
 192     {
 193         HSSFCell hcell = new HSSFCell(book, sheet, getRowNum(), cell);
 194
 195         addCell(hcell);
 196
 197         // sheet.addValueRecord(getRowNum(),cell.getCellValueRecord());
 198         return hcell;
 199     }
 200
 201     /**
 202      * set the row number of this row.
 203      * @param rowNum  the row number (0-based)
 204      * @throws IndexOutOfBoundsException if the row number is not within the range 0-65535.
 205      */
 206
 207     //public void setRowNum(short rowNum)
 208     public void setRowNum(int rowNum)
 209     {
 210         if ((rowNum < 0) || (rowNum > RowRecord.MAX_ROW_NUMBER))
 211           throw new IndexOutOfBoundsException("Row number must be between 0 and "+RowRecord.MAX_ROW_NUMBER+", was <"+rowNum+">");
 212         this.rowNum = rowNum;
 213         if (row != null)
 214         {
 215             row.setRowNumber(rowNum);   // used only for KEY comparison (HSSFRow)
 216         }
 217     }
 218
 219     /**
 220      * get row number this row represents
 221      * @return the row number (0 based)
 222      */
 223
 224     //public short getRowNum()
 225     public int getRowNum()
 226     {
 227         return rowNum;
 228     }
 229
 230     /**
 231      * Returns the rows outline level. Increased as you
 232      *  put it into more groups (outlines), reduced as
 233      *  you take it out of them.
 234      * TODO - Should this really be public?
 235      */
 236     protected int getOutlineLevel() {
 237         return row.getOutlineLevel();
 238     }
 239
 240     /**
 241      * Moves the supplied cell to a new column, which
 242      *  must not already have a cell there!
 243      * @param cell The cell to move
 244      * @param newColumn The new column number (0 based)
 245      */
 246     public void moveCell(HSSFCell cell, short newColumn) {
 247         // Ensure the destination is free
 248         if(cells.length > newColumn && cells[newColumn] != null) {
 249                 throw new IllegalArgumentException("Asked to move cell to column " + newColumn + " but there's already a cell there");
 250         }
 251
 252         // Check it's one of ours
 253         if(! cells[cell.getCellNum()].equals(cell)) {
 254                 throw new IllegalArgumentException("Asked to move a cell, but it didn't belong to our row");
 255         }
 256
 257         // Move the cell to the new position
 258         // (Don't remove the records though)
 259         removeCell(cell, false);
 260         cell.updateCellNum(newColumn);
 261         addCell(cell);
 262     }
 263
 264     /**
 265      * used internally to add a cell.
 266      */
 267     private void addCell(HSSFCell cell)
 268     {
 269         short column=cell.getCellNum();
 270         if (row.getFirstCol() == -1)
 271         {
 272             row.setFirstCol(column);
 273         }
 274         if (row.getLastCol() == -1)
 275         {
 276             row.setLastCol(column);
 277         }
 278
 279         if(column>=cells.length)
 280         {
 281           HSSFCell[] oldCells=cells;
 282           int newSize=oldCells.length*2;
 283           if(newSize<column+1) newSize=column+1;
 284           cells=new HSSFCell[newSize];
 285           System.arraycopy(oldCells,0,cells,0,oldCells.length);
 286         }
 287         cells[column]=cell;
 288
 289         if (column < row.getFirstCol())
 290         {
 291             row.setFirstCol(column);
 292         }
 293         if (column > row.getLastCol())
 294         {
 295             row.setLastCol(column);
 296         }
 297     }
 298
 299     /**
 300      * get the hssfcell representing a given column (logical cell) 0-based.  If you
 301      * ask for a cell that is not defined....you get a null.
 302      *
 303      * @param cellnum  0 based column number
 304      * @return HSSFCell representing that column or null if undefined.
 305      */
 306
 307     public HSSFCell getCell(short cellnum)
 308     {
 309       if(cellnum<0||cellnum>=cells.length) return null;
 310       return cells[cellnum];
 311     }
 312
 313     /**
 314      * get the number of the first cell contained in this row.
 315      * @return short representing the first logical cell in the row, or -1 if the row does not contain any cells.
 316      */
 317
 318     public short getFirstCellNum()
 319     {
 320         if (getPhysicalNumberOfCells() == 0)
 321             return -1;
 322         else
 323             return row.getFirstCol();
 324     }
 325
 326     /**
 327      * gets the number of the last cell contained in this row <b>PLUS ONE</b>.
 328      * @return short representing the last logical cell in the row <b>PLUS ONE</b>, or -1 if the row does not contain any cells.
 329      */
 330
 331     public short getLastCellNum()
 332     {
 333         if (getPhysicalNumberOfCells() == 0)
 334             return -1;
 335         else
 336             return row.getLastCol();
 337     }
 338
 339
 340     /**
 341      * gets the number of defined cells (NOT number of cells in the actual row!).
 342      * That is to say if only columns 0,4,5 have values then there would be 3.
 343      * @return int representing the number of defined cells in the row.
 344      */
 345
 346     public int getPhysicalNumberOfCells()
 347     {
 348       int count=0;
 349       for(int i=0;i<cells.length;i++)
 350       {
 351         if(cells[i]!=null) count++;
 352       }
 353       return count;
 354     }
 355
 356     /**
 357      * set the row's height or set to ff (-1) for undefined/default-height.  Set the height in "twips" or
 358      * 1/20th of a point.
 359      * @param height  rowheight or 0xff for undefined (use sheet default)
 360      */
 361
 362     public void setHeight(short height)
 363     {
 364
 365         // row.setOptionFlags(
 366         row.setBadFontHeight(true);
 367         row.setHeight(height);
 368     }
 369
 370     /**
 371      * set whether or not to display this row with 0 height
 372      * @param zHeight  height is zero or not.
 373      */
 374     public void setZeroHeight(boolean zHeight) {
 375         row.setZeroHeight(zHeight);
 376     }
 377
 378     /**
 379      * get whether or not to display this row with 0 height
 380      * @return - zHeight height is zero or not.
 381      */
 382     public boolean getZeroHeight() {
 383         return row.getZeroHeight();
 384     }
 385
 386     /**
 387      * set the row's height in points.
 388      * @param height  row height in points
 389      */
 390
 391     public void setHeightInPoints(float height)
 392     {
 393
 394         // row.setOptionFlags(
 395         row.setBadFontHeight(true);
 396         row.setHeight((short) (height * 20));
 397     }
 398
 399     /**
 400      * get the row's height or ff (-1) for undefined/default-height in twips (1/20th of a point)
 401      * @return rowheight or 0xff for undefined (use sheet default)
 402      */
 403
 404     public short getHeight()
 405     {
 406         return row.getHeight();
 407     }
 408
 409     /**
 410      * get the row's height or ff (-1) for undefined/default-height in points (20*getHeight())
 411      * @return rowheight or 0xff for undefined (use sheet default)
 412      */
 413
 414     public float getHeightInPoints()
 415     {
 416         return (row.getHeight() / 20);
 417     }
 418
 419     /**
 420      * get the lowlevel RowRecord represented by this object - should only be called
 421      * by other parts of the high level API
 422      *
 423      * @return RowRecord this row represents
 424      */
 425
 426     protected RowRecord getRowRecord()
 427     {
 428         return row;
 429     }
 430
 431     /**
 432      * used internally to refresh the "last cell" when the last cell is removed.
 433      */
 434
 435     private short findLastCell(short lastcell)
 436     {
 437         short cellnum = (short) (lastcell - 1);
 438         HSSFCell r = getCell(cellnum);
 439
 440         while (r == null && cellnum >= 0)
 441         {
 442             r = getCell(--cellnum);
 443         }
 444         return cellnum;
 445     }
 446
 447     /**
 448      * used internally to refresh the "first cell" when the first cell is removed.
 449      */
 450
 451     private short findFirstCell(short firstcell)
 452     {
 453         short cellnum = (short) (firstcell + 1);
 454         HSSFCell r = getCell(cellnum);
 455
 456         while (r == null && cellnum <= getLastCellNum())
 457         {
 458             r = getCell(++cellnum);
 459         }
 460         if (cellnum > getLastCellNum())
 461             return -1;
 462         return cellnum;
 463     }
 464
 465     /**
 466      * @return cell iterator of the physically defined cells.  Note element 4 may
 467      * actually be row cell depending on how many are defined!
 468      */
 469     public Iterator cellIterator()
 470     {
 471       return new CellIterator();
 472     }
 473     /**
 474      * Alias for {@link CellIterator} to allow
 475      *  foreach loops
 476      */
 477     public Iterator iterator() {
 478        return cellIterator();
 479     }
 480
 481     private class CellIterator implements Iterator
 482     {
 483       int thisId=-1;
 484       int nextId=-1;
 485
 486       public CellIterator()
 487       {
 488         findNext();
 489       }
 490
 491       public boolean hasNext() {
 492         return nextId<cells.length;
 493       }
 494
 495       public Object next() {
 496           if (!hasNext())
 497                   throw new NoSuchElementException("At last element");
 498         HSSFCell cell=cells[nextId];
 499         thisId=nextId;
 500         findNext();
 501         return cell;
 502       }
 503
 504       public void remove() {
 505           if (thisId == -1)
 506                   throw new IllegalStateException("remove() called before next()");
 507         cells[thisId]=null;
 508       }
 509
 510       private void findNext()
 511       {
 512         int i=nextId+1;
 513         for(;i<cells.length;i++)
 514         {
 515           if(cells[i]!=null) break;
 516         }
 517         nextId=i;
 518       }
 519
 520     }
 521
 522     public int compareTo(Object obj)
 523     {
 524         HSSFRow loc = (HSSFRow) obj;
 525
 526         if (this.getRowNum() == loc.getRowNum())
 527         {
 528             return 0;
 529         }
 530         if (this.getRowNum() < loc.getRowNum())
 531         {
 532             return -1;
 533         }
 534         if (this.getRowNum() > loc.getRowNum())
 535         {
 536             return 1;
 537         }
 538         return -1;
 539     }
 540
 541     public boolean equals(Object obj)
 542     {
 543         if (!(obj instanceof HSSFRow))
 544         {
 545             return false;
 546         }
 547         HSSFRow loc = (HSSFRow) obj;
 548
 549         if (this.getRowNum() == loc.getRowNum())
 550         {
 551             return true;
 552         }
 553         return false;
 554     }
 555 }