vtkTable.h

/*=========================================================================

  Program:   Visualization Toolkit
  Module:    vtkTable.h

  Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
  All rights reserved.
  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.

     This software is distributed WITHOUT ANY WARRANTY; without even
     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
     PURPOSE.  See the above copyright notice for more information.

=========================================================================*/
/*-------------------------------------------------------------------------
  Copyright 2008 Sandia Corporation.
  Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
  the U.S. Government retains certain rights in this software.
-------------------------------------------------------------------------*/
// .NAME vtkTable - A table, which contains similar-typed columns of data
//
// .SECTION Description
// vtkTable is a basic data structure for storing columns of data.
// Internally, columns are stored in a vtkDataSetAttributes structure called
// RowData. However, using the vtkTable API additionally ensures that every column
// has the same number of entries, and provides row access (using vtkVariantArray)
// and single entry access (using vtkVariant).
//
// The field data inherited from vtkDataObject may be used to store metadata
// related to the table.
//
// .SECTION Caveats
// You should use the vtkTable API to change the table data. Performing
// operations on the object returned by GetRowData() may
// yield unexpected results. vtkTable does allow the user to set the field
// data using SetRowData(); the number of rows in the table is determined
// by the number of tuples in the first array (it is assumed that all arrays
// are the same length).
//
// Each column added with AddColumn <b>must</b> have its name set to a unique,
// non-empty string in order for GetValue() to function properly.
//
// .SECTION Thanks
// Thanks to Patricia Crossno, Ken Moreland, Andrew Wilson and Brian Wylie from
// Sandia National Laboratories for their help in developing this class API.

#ifndef __vtkTable_h
#define __vtkTable_h

#include "vtkDataObject.h"

class vtkAbstractArray;
class vtkDataSetAttributes;
class vtkVariant;
class vtkVariantArray;

class VTK_FILTERING_EXPORT vtkTable : public vtkDataObject
{
public:
  static vtkTable* New();
  vtkTypeMacro(vtkTable, vtkDataObject);
  void PrintSelf(ostream &os, vtkIndent indent);

  // Description:
  // Dump table contents.  If rowLimit is -1 then the full table
  // is printed out (Default).  If rowLimit is 0 then only the
  // header row will be displayed.  Otherwise, if rowLimit > 0
  // then Dump will print the first rowLimit rows of data.
  void Dump( unsigned int colWidth = 16, int rowLimit = -1 );

  // Description:
  // Return what type of dataset this is.
  int GetDataObjectType() {return VTK_TABLE;}

  // Description:
  // Return the actual size of the data in kilobytes. This number
  // is valid only after the pipeline has updated. The memory size
  // returned is guaranteed to be greater than or equal to the
  // memory required to represent the data (e.g., extra space in
  // arrays, etc. are not included in the return value).
  virtual unsigned long GetActualMemorySize();

  // Description:
  // Get/Set the main data (columns) of the table.
  vtkGetObjectMacro(RowData, vtkDataSetAttributes);
  virtual void SetRowData(vtkDataSetAttributes* data);

  //
  // Row functions
  //

  // Description:
  // Get the number of rows in the table.
  vtkIdType GetNumberOfRows();

  // Description:
  // Set the number of rows in the table. Note that memory allocation might be performed
  // as a result of this, but no memory will be released. 
  void SetNumberOfRows(const vtkIdType );

  // Description:
  // Get a row of the table as a vtkVariantArray which has one entry for each column.
  // NOTE: This version of the method is NOT thread safe.
  vtkVariantArray* GetRow(vtkIdType row);

  // Description:
  // Get a row of the table as a vtkVariantArray which has one entry for each column.
  void GetRow(vtkIdType row, vtkVariantArray *values);

  // Description:
  // Set a row of the table with a vtkVariantArray which has one entry for each column.
  void SetRow(vtkIdType row, vtkVariantArray *values);

  // Description:
  // Insert a blank row at the end of the table.
  vtkIdType InsertNextBlankRow(double default_num_val=0.0);

  // Description:
  // Insert a row specified by a vtkVariantArray.  The number of entries in the array
  // should match the number of columns in the table.
  vtkIdType InsertNextRow(vtkVariantArray* arr);

  // Description:
  // Delete a row from the table.  Rows below the deleted row are shifted up.
  void RemoveRow(vtkIdType row);

  //
  // Column functions
  //

  // Description:
  // Get the number of columns in the table.
  vtkIdType GetNumberOfColumns();

  // Get the name of a column of the table.
  const char* GetColumnName(vtkIdType col);

  // Description:
  // Get a column of the table by its name.
  vtkAbstractArray* GetColumnByName(const char* name);

  // Description:
  // Get a column of the table by its column index.
  vtkAbstractArray* GetColumn(vtkIdType col);

  // Description:
  // Add a column to the table.
  void AddColumn(vtkAbstractArray* arr);

  // Description:
  // Remove a column from the table by its name.
  void RemoveColumnByName(const char* name);

  // Description:
  // Remove a column from the table by its column index.
  void RemoveColumn(vtkIdType col);

  //
  // Table single entry functions
  //

  // Description:
  // Retrieve a value in the table by row and column index as a variant.
  // Note that this calls GetValueByName internally so that each column
  // array must have its name set (and that name should be unique within
  // the table).
  vtkVariant GetValue(vtkIdType row, vtkIdType col);

  // Description:
  // Retrieve a value in the table by row index and column name as a variant.
  vtkVariant GetValueByName(vtkIdType row, const char* col);

  // Description:
  // Set a value in the table by row and column index as a variant.
  void SetValue(vtkIdType row, vtkIdType col, vtkVariant value);

  // Description:
  // Set a value in the table by row index and column name as a variant.
  void SetValueByName(vtkIdType row, const char* col, vtkVariant value);
  
  // Description:
  // Initialize to an empty table.
  virtual void Initialize();

  // Description:
  // Retrieve the table from vtkInformation.
  static vtkTable* GetData(vtkInformation* info);
  static vtkTable* GetData(vtkInformationVector* v, int i=0);

  // Description:
  // Shallow/deep copy the data from src into this object.
  virtual void ShallowCopy(vtkDataObject* src);
  virtual void DeepCopy(vtkDataObject* src);

  // Description:
  // Returns the attributes of the data object as a vtkFieldData.
  // This returns non-null values in all the same cases as GetAttributes,
  // in addition to the case of FIELD, which will return the field data
  // for any vtkDataObject subclass.
  virtual vtkFieldData* GetAttributesAsFieldData(int type);

  // Description:
  // Get the number of elements for a specific attribute type (ROW, etc.).
  virtual vtkIdType GetNumberOfElements(int type);

protected:
  vtkTable();
  ~vtkTable();

  // Description:
  // Holds the column data of the table.
  vtkDataSetAttributes* RowData;

  // Description:
  // Holds row information returned by GetRow().
  vtkVariantArray* RowArray;

private:
  vtkTable(const vtkTable&); // Not implemented
  void operator=(const vtkTable&); // Not implemented
};

#endif