table_c.h

Go to the documentation of this file.

/**********************************************************//**
 **
 ** @file data/Store/table_c.h
 **
 ** Copyright (C) 2012  Xpace, LLC.  All rights reserved
 **
 ** www.xpace.net
 **
 **************************************************************/

#ifndef XPACE_TABLE_C_H
#define XPACE_TABLE_C_H

#include "base/types.h"
#include "base/c/types_c.h"
#include "base/c/exception_c.h"

#ifdef __cplusplus
# include "base/datetime.h"
# include "data/store/table.h"
  typedef Xpace::Table* Xpace_Table;
  typedef Xpace::Table::Source* Xpace_Table_Source;
#else
  typedef void* Xpace_Table;
  typedef void* Xpace_Table_Source;
#endif

// ================================== CREATE / DESTROY ========

enum Xpace_StoreAccess
{
  SA_readWrite,
  SA_readOnly,
  SA_bulkWrite
};

/// @param config the Table's Configuration
/// @param access how the Table will be opened
XPACE_C_EXPORT(Xpace_Error) Xpace_Table_create
  (Xpace_Char16* config,
   Xpace_StoreAccess access,
   Xpace_Table* result);

XPACE_C_EXPORT(void) Xpace_Table_destroy
  (Xpace_Table);

// ================================== GET INFO ================

XPACE_C_EXPORT(Xpace_Error) Xpace_Table_getConfig
  (const Xpace_Table,
   const Xpace_Char16** result);

/// @retval true if the table is empty
XPACE_C_EXPORT(Xpace_Error) Xpace_Table_isEmpty
  (const Xpace_Table,
   bool* result);

/// @retval the table's name
XPACE_C_EXPORT(Xpace_Error) Xpace_Table_getName
  (const Xpace_Table,
   const Xpace_Char16** result);

/// Get a column's configuration
/// @param col the column number
/// @retval the column's Configuration
XPACE_C_EXPORT(Xpace_Error) Xpace_Table_getColumnConfig
  (const Xpace_Table, 
   uint col,
   const Xpace_Char16** result);

/// @retval the number of rows in the table
XPACE_C_EXPORT(Xpace_Error) Xpace_Table_getRowCount
  (const Xpace_Table,
   uint64* result);

/// @retval the number of columns in the table
XPACE_C_EXPORT(Xpace_Error) Xpace_Table_getColumnCount
  (const Xpace_Table,
   uint* result);

// ================================== GET DATA ================

/// create a read-only cursor into a Table
/// @param row start at this row
/// @retval the Source
XPACE_C_EXPORT(Xpace_Error) Xpace_Table_createSource
  (Xpace_Table tc,
   uint64 row,
   Xpace_Table_Source* result);

/// destroy a Table Source
XPACE_C_EXPORT(void) Xpace_Table_Source_destroy
  (Xpace_Table_Source);

/// @param row move cursor to this row
/// @retval true if successful, false (and don't move) if not
XPACE_C_EXPORT(Xpace_Error) Xpace_Table_Source_moveToRow
  (Xpace_Table_Source,
   uint64 row,
   bool* result);

/// get the (String) contents of a cell from the current row
/// @param column from this column
/// @retval the (String) contents of the cell
XPACE_C_EXPORT(Xpace_Error) Xpace_Table_Source_getCellStr
  (const Xpace_Table_Source,
   uint column,
   const Xpace_Char16** result);

/// get the (integer) contents of a cell from the current row
/// @param column from this column
/// @param ok fillin true if successful
/// @retval the (integer) contents of the cell
XPACE_C_EXPORT(Xpace_Error) Xpace_Table_Source_getCellInt
  (const Xpace_Table_Source,
   uint column,
   bool* ok,
   int64* result);

/// get the (raw) contents of a cell from the current row
///   NB only guarenteed to be valid while the row is current
/// @param column from this column
/// @retval the (raw) contents of the cell
XPACE_C_EXPORT(Xpace_Error) Xpace_Table_Source_getCellBytes
  (const Xpace_Table_Source,
   uint column,
   Xpace_Bytes* result);

// ================================== GET TO SINK =============

/// Sink callbacks for table data

/// Set a column's name and type
/// @param name the name of the column
/// @param type the type of the column
/// @param columnNum a proposed column number
/// @retval added true iff actually added
/// @return the actual column number to continue, -1 to stop
XPACE_C_CALLBACK(int, Xpace_Table_addColumn)
  (const Xpace_Char16* name,
   Xpace_Data_Type type,
   uint columnNum,   
   bool* added,
   void* callerInfo);
   
/// Begin a new row, committing this one (if any)
/// @param docNum the new row number
/// @return -1 to stop, 0 to return this row, >0 to skip rows
XPACE_C_CALLBACK(int64, Xpace_Table_startRow)
  (uint64 row,
   void* callerInfo);

/// Add a 64-bit int to the row
/// @param column 
/// @param value
/// @return true to continue
XPACE_C_CALLBACK(bool, Xpace_Table_setInt64)
  (uint column,
   int64 value,
   void* callerInfo);

/// Add a double to the row
/// @param column
/// @param mantissa
/// @param decimals
/// @returns true to continue
XPACE_C_CALLBACK(bool, Xpace_Table_setDecimalFloat)
  (uint column,
   int64 mantissa,
   int decimals,
   void* callerInfo);

/// Add a String8 to the row
/// @param column
/// @param data the String8's contents - NB valid only as long as the row is current
/// @param len the String8's length
/// @returns true to continue
XPACE_C_CALLBACK(bool, Xpace_Table_setString8)
  (uint column,
   const Xpace_Char8* data,
   size_t len,
   void* callerInfo);

/// Add a String16 to the row
/// @param column
/// @param data the String16's contents - NB valid only as long as the row is current
/// @param len the String16's length
/// @return true to continue
XPACE_C_CALLBACK(bool, Xpace_Table_setString16)
  (uint column,
   const Xpace_Char16* data,
   size_t len,
   void* callerInfo);

/// Add raw bytes
/// @param column
/// @param data the bytes - NB valid only as long as the row is current
/// @param len the bytes' length
/// @return true to continue
XPACE_C_CALLBACK(bool, Xpace_Table_setBytes)
  (uint column,
   const byte* data,
   size_t len,
   void* callerInfo);

/// Add DateTime
/// @param column
/// @param value - NB valid only as long as the row is current
/// @return true to continue
XPACE_C_CALLBACK(bool, Xpace_Table_setDateTime)
  (uint column,
   Xpace_DateTime* value,
   void* callerInfo);

/// We're finished with this sink
XPACE_C_CALLBACK(void, Xpace_Table_close)
  (void* callerInfo);

struct Xpace_Table_Sink
{
  Xpace_Table_addColumn       addColumn;
  Xpace_Table_startRow        startRow;
  Xpace_Table_setInt64        setInt64; 
  Xpace_Table_setDecimalFloat setDecimalFloat;
  Xpace_Table_setString8      setString8;
  Xpace_Table_setString16     setString16;
  Xpace_Table_setBytes        setBytes;
  Xpace_Table_setDateTime     setDateTime; 
  Xpace_Table_close           close;
};

#ifdef __cplusplus

// C++ caller for Xpace_Table_Sink - used in several places
namespace Xpace
{
  class table_sink : public Table::Sink 
  {
  public:
    table_sink
      (Xpace_Table_Sink*,
       void* callerInfo);

    virtual uint add 
      (const String& name,
       DerivedDataType type,
       uint columnNum,
       bool* added = 0) override;    

    virtual int64 start
      (uint64 row) override
    {
      return start_row(row, caller_info);
    }

    virtual bool set 
      (uint column,
       int64 value) override
    {
      return set_int64(column, value, caller_info);
    }

    virtual bool set 
      (uint column,
       const Xpace::DecimalFloat& value) override
    {
      return set_decimalFloat(column, value.getMantissa(), value.getDecimals(), caller_info);
    }

    virtual bool set 
      (uint column,
       const Xpace::String8& value) override
    {
      return set_string8(column, value.data, value.length, caller_info);
    }

    virtual bool set 
      (uint column,
        const Xpace::String16& value) override
    {
      return set_string16(column, value.data, value.length, caller_info);
    }

    virtual bool set 
      (uint column,
       const Xpace::BytesRef& value) override
    {
      return set_bytes(column, value.data, value.length, caller_info);
    }

    virtual bool set 
      (uint column,
       const Xpace::DateTime& value) override
    {
      Xpace::Date date(value.getDate());
      Xpace::Time time(value.getTime());

      Xpace_DateTime dt;
      dt.year = date.getYear();
      dt.month = date.getMonth();
      dt.day = date.getDay();
      dt.hour = time.getHour();
      dt.minute = time.getMinute();
      dt.second = time.getSecond();
      dt.millisecond = time.getMillisecond();
      return set_dateTime(column, &dt, caller_info);
     }

    virtual void close
      () override
    {
      do_close(caller_info);
    }

  private:
    const Xpace_Table_addColumn       add_column;
    const Xpace_Table_startRow        start_row;
    const Xpace_Table_setInt64        set_int64;
    const Xpace_Table_setDecimalFloat set_decimalFloat;
    const Xpace_Table_setString8      set_string8;
    const Xpace_Table_setString16     set_string16;
    const Xpace_Table_setBytes        set_bytes;
    const Xpace_Table_setDateTime     set_dateTime;
    const Xpace_Table_close           do_close;

    void *const caller_info;
  };
}

#endif

/// Get Table data through a callback, starting from and updating the current position 
/// @param columns ~0-terminated list of columns to get; if 0, get all columns
/// @param maxRows the maximum number of rows to get
/// @param sink called for each cell
/// #param result fillin true iff each call to sink->set() returned true
XPACE_C_EXPORT(Xpace_Error) Xpace_Table_Cursor_forEach
  (Xpace_Table table,
   uint* columns,             
   uint64 maxRows,
   Xpace_Table_Sink* sink,
   void* callerInfo,
   bool* result);

#endif