Tuple.hpp

// Copyright (c) 2004-2023 TIBCO Software Inc.  All rights reserved.

#ifndef STREAMBASE_TUPLE_H
#define STREAMBASE_TUPLE_H

#include "StreamBase.hpp"

#include "Timestamp.hpp"
#include "Schema.hpp"
#include "Field.hpp"
#include "Exceptions.hpp"
#include "Errors.hpp"
#include <NMSTL/platform.hpp>
#include <streambase/impl/Memory.hpp>
#include "TuplePrivate.hpp"
#include "TupleExceptions.hpp"
#include "FieldValue.hpp"

#ifdef WIN32
#pragma  warning( push )
#pragma warning(disable:4127)
#endif

SB_INTERNAL_FWD(TupleUtil);
SB_INTERNAL_FWD(Errors);

SB_NAMESPACE_BEGIN;

class Tuple;
class Function;


template <typename T>
T Tuple_do_get(const Tuple& tuple, const Field &field);
template <typename T>
void Tuple_do_set(Tuple& tuple, const Field &field, T value);

/** 
 * Tuples are value types that can be copied and modified separately thus
 * 
 * t2 = t1;<br>
 * t2.setId(0); // does not modify t1
 *
 * They will only make copies of the underlying data as needed, so
 * they are relatively cheap to pass around by value
 */
class Tuple {
public:
    Tuple();

    /// Copy constructor
    Tuple(const Tuple& t);

    /// Construct a tuple of the specified schema
    Tuple(const Schema& s);

    /// Destructor
    ~Tuple();

    const Tuple& operator=(const Tuple& rhs);

    bool operator==(const Tuple& rhs) const;

    /** verify that the tuple is valid
     *  Throws StreamBaseException on invalid tuple */
    void verify() const;

    /** null all fields in the tuple */
    void clear() {
        if(!getSchema()) { return; }
        for(size_t i = 0; i < getNumFields(); ++i) {
            setNull(i);
        }
    }

    /** @return the schema */
    const Schema &getSchema() const;
    /** set the schema */
    void setSchema(const Schema &);

    /** @return the number of fields in the tuple's schema */
    size_t getNumFields() const {
        const Schema& s = getSchema();
        return s ? s.getNumFields() : 0;
    }
        
    /** @return the serialized size of this tuple */
    size_t getSize() const;

    /** Flags that can be passed to setString().  TRUNCATE: starting in StreamBase 6.3 the
     * string type does not have a declared length and strings are never truncated.
     */
    enum Flags {
        NONE = 0,
        TRUNCATE = 1
    };


    //@{
    /** Return the value of the given field of type T.  T must be one of
     * string, int, double, bool, long, or Timestamp, and correspond to the
     * field's actual type.
     *
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     *
     *  @return the value of the field. */
    template <typename T> T get(const Field &f) const {
        return Tuple_do_get<T>(*this, f);
    }
    template <typename T> T get(size_t i) const {
        return get<T>(getSchema().getField(i));
    }
    template <typename T> T get(const std::string &field_name) const {
        return get<T>(getSchema().getField(field_name));
    }
    //@}
    
    //@{
    /** Set a field to a specific value. Supported values are string,
     *  int, double, bool and Timestamp. field must be a of a matching
     *  DataType.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     */
    template <typename T> void set(const Field &field, T value) {
        return Tuple_do_set<T>(*this, field, value);
    }
    template <typename T> void set(int fieldNum, T value) {
        set(getSchema().getField(fieldNum), value);
    }
    template <typename T> void set(const std::string &field_name, T value) {
        set(getSchema().getField(field_name), value);
    }
    //@}

    //@{
    /** Test the null setting for field f
     *
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     *
     *  @return true if field is null, false otherwise */
    bool isNull(const Field &f) const;
    bool isNull(size_t i) const {
        return isNull(getSchema().getField(i));
    }
    bool isNull(const std::string& n) const {
        return isNull(getSchema().getField(n));
    }
    //@}

    //@{
    /** Set the null setting for field f
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     */
    void setNull(const Field &f);
    void setNull(size_t i) { setNull(getSchema().getField(i)); }
    void setNull(const std::string& n) { setNull(getSchema().getField(n)); }
    //@}


    //@{
    /** Return the value of a Boolean field.
     *
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     *
     *  @return the Boolean value. */
    bool getBool(const Field &f) const;
    bool getBool(size_t i) const {
        return getBool(getSchema().getField(i));
    }
    bool getBool(const std::string& n) const {
        return getBool(getSchema().getField(n)); 
    }
    //@}

    //@{
    /** Set the value of a Boolean field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     */
    void setBool(const Field &f, bool v);
    void setBool(size_t i, bool v) {
        setBool(getSchema().getField(i), v);
    }
    void setBool(const std::string& n, bool v) {
        setBool(getSchema().getField(n), v); 
    }
    //@}


    //@{
    /** Return the value of an int field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     *
     *  @return the int value. */
    int getInt(const Field &f) const;
    int getInt(size_t i) const {
        return getInt(getSchema().getField(i));
    }
    int getInt(const std::string& n) const {
        return getInt(getSchema().getField(n)); 
    }
    //@}

    //@{
    /** Set the value of an integer field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     */
    void setInt(const Field &f, int v);
    void setInt(size_t i, int v) {
        setInt(getSchema().getField(i), v);
    }
    void setInt(const std::string& n, int v) {
        setInt(getSchema().getField(n), v); 
    }
    //@}


    //@{
    /** Return the value of a long field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     *
     *  @return the long value. */
    long long getLong(const Field &f) const;
    long long getLong(size_t i) const {
        return getLong(getSchema().getField(i));
    }
    long long getLong(const std::string& n) const {
        return getLong(getSchema().getField(n)); 
    }
    //@}

    //@{
    /** Set the value of a long field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     */
    void setLong(const Field &f, long long v);
    void setLong(size_t i, long long v) {
        setLong(getSchema().getField(i), v);
    }
    void setLong(const std::string& n, long long v) {
        setLong(getSchema().getField(n), v); 
    }
    //@}


    //@{
    /** Return the value of a double field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     *
     *  @return the double value. */
    double getDouble(const Field &f) const;
    double getDouble(size_t i) const {
        return getDouble(getSchema().getField(i));
    }
    double getDouble(const std::string& n) const {
        return getDouble(getSchema().getField(n)); 
    }
    //@}

    //@{
    /** Set the value of a double field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     */
    void setDouble(const Field &f, double v);
    void setDouble(size_t i, double v) {
        setDouble(getSchema().getField(i), v);
    }
    void setDouble(const std::string& n, double v) {
        setDouble(getSchema().getField(n), v); 
    }
    //@}


    //@{
    /** Return the value of a Timestamp field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     *
     *  @return the Timestamp value. */
    Timestamp getTimestamp(const Field &f) const;
    Timestamp getTimestamp(size_t i) const {
        return getTimestamp(getSchema().getField(i));
    }
    Timestamp getTimestamp(const std::string& n) const {
        return getTimestamp(getSchema().getField(n)); 
    }
    //@}

    //@{
    /** Set the value of a Timestamp field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     */
    void setTimestamp(const Field &f, const Timestamp& v);
    void setTimestamp(size_t i, const Timestamp& v) {
        setTimestamp(getSchema().getField(i), v);
    }
    void setTimestamp(const std::string& n, const Timestamp& v) {
        setTimestamp(getSchema().getField(n), v); 
    }
    //@}



    //@{
    /** Return the value of a BLOB field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     *
     *  @return the BLOB value. */
    const std::string& getBlobBuffer(const Field &f) const;
    const std::string& getBlobBuffer(size_t i) const {
        return getBlobBuffer(getSchema().getField(i));
    }
    const std::string& getBlobBuffer(const std::string& n) const {
        return getBlobBuffer(getSchema().getField(n)); 
    }
    //@}

    //@{
    /** Set the value of a BLOB field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     */
    void setBlobBuffer(const Field &f, const std::string& v);
    void setBlobBuffer(size_t i, const std::string& v) {
        setBlobBuffer(getSchema().getField(i), v);
    }
    void setBlobBuffer(const std::string& n, const std::string& v) {
        setBlobBuffer(getSchema().getField(n), v); 
    }
    //@}


    //@{
    /** Return the value of a LIST field.
     * 
     *  The Schema::Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     *
     *  @return the LIST value. */
    const std::vector<FieldValue>& getList(const Schema::Field &f) const;
    const std::vector<FieldValue>& getList(size_t i) const {
        return getList(getSchema().getField(i));
    }
    const std::vector<FieldValue>& getList(const std::string& n) const {
        return getList(getSchema().getField(n)); 
    }
    //@}

    //@{
    /** Set the value of a LIST field.
     * 
     *  The Schema::Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     */
    void setList(const Schema::Field &f, const std::vector<FieldValue>& v);
    void setList(size_t i, const std::vector<FieldValue>& v) {
        setList(getSchema().getField(i), v);
    }
    void setList(const std::string& n, const std::vector<FieldValue>& v) {
        setList(getSchema().getField(n), v); 
    }
    //@}

    //@{
    /** Return the value of a string field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     *
     *  @return the string value. */
    const std::string& getString(const Field &f) const;
    const std::string& getString(size_t i) const {
        return getString(getSchema().getField(i));
    }
    const std::string& getString(const std::string& n) const {
        return getString(getSchema().getField(n)); 
    }
    //@}


    //@{
    /** Set the value of a string field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     */
    void setString(const Field &field,
                           const std::string &value, Flags flags = NONE);
    void setString(size_t field,
            const char* data, size_t len, Flags flags = NONE) {
        setString(field, std::string(data, len), flags);
    }
    void setString(const std::string& field,
            const char* data, size_t len, Flags flags = NONE) {
        setString(field, std::string(data, len), flags);
    }
    void setString(const Field& field,
            const char* data, size_t len, Flags flags = NONE) {
        setString(field, std::string(data, len), flags);
    }
    void setString(size_t field_index,
                           const std::string &value, Flags flags = NONE) {
        setString(getSchema().getField(field_index), value, flags);
    }
    void setString(const std::string& field_name,
                           const std::string& value, Flags flags = NONE) {
        setString(getSchema().getField(field_name), value, flags);
    }
    //@}


    //@{
    /** Return the value of a nested tuple field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     *
     *  @return the nested tuple value. */
    const Tuple& getTuple(const Field &f) const;
    const Tuple& getTuple(size_t i) const {
        return getTuple(getSchema().getField(i));
    }
    const Tuple& getTuple(const std::string& n) const {
        return getTuple(getSchema().getField(n)); 
    }
    //@}

    //@{
    /** Return the value of a function field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     *
     *  @return the function value. 
     */
    const Function& getFunction(const Field& f) const;
    const Function& getFunction(size_t i) const {
        return getFunction(getSchema().getField(i));
    }
    const Function& getFunction(const std::string& n) const {
        return getFunction(getSchema().getField(n)); 
    }
    //@}

  private:
    Tuple& getTupleMutable(const Field &f);

  public:

    //@{
    /** Set the value of a nested tuple field.
     * 
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     */
    void setTuple(const Field &f, const Tuple& v);
    void setTuple(size_t i, const Tuple& v) {
        setTuple(getSchema().getField(i), v);
    }
    void setTuple(const std::string& n, const Tuple& v) {
        setTuple(getSchema().getField(n), v); 
    }
    //@}

    //@{
    /**
     * Set the value of a function field
     *
     *  The Field objects used to set and get Tuple field values must be
     *  obtained via the Tuple's Schema object.  A Schema.Field object that has
     *  been created by the user or retrieved from a different Schema may not work.
     */
    void setFunction(const Field& f, const Function& v);
    void setFunction(size_t i, const Function& v) {
        setFunction(getSchema().getField(i), v);
    }
    void setFunction(const std::string& n, const Function& v) {
        setFunction(getSchema().getField(n), v); 
    }
    //@}
    
    /// Takes a field with a path and returns the field at the target of that path
    FieldValue& getFieldValue(const Field& f);
    /// Takes a field with a path and returns the field at the target of that path
    const FieldValue& getFieldValue(const Schema::Field& f) const;

    /// Takes the index of a field in this tuple's schema, returns the corresponding 
    /// field value.
    FieldValue& getFieldValue(size_t field_num);
    /// Takes the index of a field in this tuple's schema, returns the corresponding 
    /// field value.
    const FieldValue& getFieldValue(size_t field_num) const;

    /// Takes the name of a field in this tuple's schema, returns the corresponding 
    /// field value.
    FieldValue& getFieldValue(const std::string& field_name);
    /// Takes the name of a field in this tuple's schema, returns the corresponding 
    /// field value.
    const FieldValue& getFieldValue(const std::string& field_name) const;
    
    /// Takes a field with a path and sets the value of the field at the target of 
    /// that path to that of the provided FieldValue.
    void setFieldValue(const Field& f, const FieldValue& fv);
    /// Takes the index of a field in this tuple's schema and sets the corresponding
    /// field value.
    void setFieldValue(size_t field_num, const FieldValue& fv);
    /// Takes the name of a field in this tuple's schema and sets the corresponding 
    /// field value.
    void setFieldValue(const std::string& field_name, const FieldValue& fv);


    /** @return true if tuple has a header, false otherwise */
    bool hasHeader() const { return getSchema().hasHeader(); }


    /** @return The id for this tuple */
    unsigned int getId() const;
    /** set the id */
    void setId(unsigned int tid);

    /** Return a human-readable string value representing this tuple
     *  in its entirety (including all header values, if applicable).
     *  @return the string value. */
    std::string as_string() const;

    /** Return a human-readable string value representing this tuple.
     *  It compares to as_string by allowing a user-specified delimiter
     *  between fields, making the header timestamp stand out, and
     *  omitting the TupleId header field.
     *  null_string is written out for any null field.
     *  @return the string value */
    std::string as_string_external(char delimiter = ',',
            const std::string& null_string = getNullString()) const;

    /** Return a string value representing this tuple, separated by
     *  the given delimiter.
     *
     *  @param delimiter the string to put between fields
     *  @param null_string the string used to represent null values
     *  @param include_names whether to preface each field with "<name>="
     *  @param quote_all_strings whether to put quotes around all strings, 
     *              regardless of need
     *
     *  @return the result string
     */
    std::string toDelimitedString(const std::string &delimiter,
            const std::string& null_string = getNullString(),
            bool include_names = false, bool quote_all_strings = false) const;

#ifndef DOXYGEN_INTERNAL_ONLY
    /** Generates a CSV string with a column for each field in the tuple.
     *  null_string is written out for any null field. */
    void writeCSVString(std::ostream& out, char delim, char quote,
                        const std::string& null_string = getNullString()) const;
#endif

    /** Return the default string used to represent null, i.e., null. */
    static const std::string& getNullString() {
        static std::string NULL_STRING = "null";
        return NULL_STRING;
    }

#ifndef DOXYGEN_INTERNAL_ONLY
    /** @brief copy the tuple into the buffer of the given size
     *  - if the tuple does not fit in the buffer, the required size is
     *      returned and the buffer is left in an undefined state
     *  - otherwise the tuple is copied into the buffer in a packed representation
     *      and the amount of the buffer used is returned
     *
     *  @param buf the buffer into which to copy data (NULL is a safe value to pass)
     *  @param len the size of the buffer in bytes
     *  @param byteswap whether to swap the bytes coming from the buffer
     *  @return the space required/used to serialize the tuple in bytes
     *  <em>Note: this method is not public API, and is for internal StreamBase use only</em>
     */
    size_t copyIntoBuffer(void* buf, size_t len, bool byteswap) const;

    /** Set the contents of this tuple from a buffer containing a packed
     *  representation of a tuple
     * 
     *  @param buf the buffer into which to copy data (NULL is a safe value to pass)
     *  @param buf_len the size of the buffer in bytes
     *  @param byteswap whether to swap the bytes coming from the buffer
     *  @param s the Schema to use
     *  @return the size in bytes used from the buffer
     */
    size_t setFromPackedBuffer(
            const void* buf, size_t buf_len, bool byteswap, const Schema& s);

    static Tuple createFromPackedBuffer(size_t* size_used,
            const void* buf, size_t buf_len, bool byteswap, const Schema& s);
#endif
    
private:
    std::shared_ptr<TuplePrivateImpl> _;
    /// These methods are used to implement copy-on-write
    /// ensureUnique() should be called as the first line of any non-const method
    /// ensureAllocated() should be called as the first line of any const method
    void ensureUnique();
    void ensureAllocated() const;

    Tuple& resolveField(const Field& f);
    const Tuple& resolveField(const Field& f) const;

};

#define DO_ACCESSOR(type, getter) \
template <> inline type Tuple_do_get<type>(const Tuple& t, const Field& f) { return t.get ## getter(f); } \
template <> inline void Tuple_do_set<type>(Tuple& t, const Field& f, type v) { return t.set ## getter(f, v); }

DO_ACCESSOR(bool, Bool)
DO_ACCESSOR(int, Int)
DO_ACCESSOR(long long, Long)
DO_ACCESSOR(double, Double)
DO_ACCESSOR(std::string, String)
DO_ACCESSOR(Timestamp, Timestamp)

#undef DO_ACCESSOR


#ifdef WIN32
#pragma  warning( pop )
#endif

SB_NAMESPACE_END;

inline std::ostream& operator << (std::ostream& os, const sb::Tuple& tuple) {
    os << tuple.as_string();
    return os;
}


#endif // TUPLE_H