TupleList.hpp

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

#ifndef STREAMBASE_TUPLE_LIST_H
#define STREAMBASE_TUPLE_LIST_H

#include "Tuple.hpp"

SB_NAMESPACE_BEGIN;

/** TupleLists are value types that can be copied and modified seperately thus
 * 
 *  tl2 = tl1;
 *  tl2[0].clear(); // 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 TupleList {
public:
    /** Default (null) constructor. */
    TupleList();

    /** Create tuple list from a single tuple. */
    TupleList(const Tuple& tuple);

    /** Create tuple list from a tuplelist. */
    TupleList(const TupleList& list);

    /** Create tuple list with an initial size of <i>size</i> */
    TupleList(const Schema &schema, size_t size = 0);

    ~TupleList();

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

    /** Get the schema. */
    const Schema& getSchema() const;
    /** set the schema for this list 
     *  (also setting the schema for any tuples in the list) */
    void setSchema(const Schema& schema);

    //@{
    /** Get the number of tuples in the list */
    size_t getSize() const;
    size_t size() const { return getSize(); }
    //@}
    
    //@{
    /** Change the size of the list
     *  any new tuples will be entirely null */
    void resize(size_t size) { setSize(size); }
    void setSize(size_t size);
    //@}
    
    /**
     * clear the list
     */
    void clear() { setSize(0); }

    /** Is the list empty? */
    bool empty() const { return size() == 0; }

    /** Get the <i>n</i>th tuple. Fails with a std::out_of_range 
     * exception if out of range. */
    const Tuple& operator[] (size_t index) const;
    /** Get the <i>n</i>th tuple. Fails with a std::out_of_range 
     * exception if out of range. */
    Tuple& operator[] (size_t index);

    /** append a tuple to the list */
    void push_back(const Tuple& r);

    //@{
    /** return the last tuple in the list */
    Tuple& back();
    const Tuple& back() const;
    //@}


    typedef std::vector<Tuple>::iterator iterator;
    typedef std::vector<Tuple>::const_iterator const_iterator;
    
    //@{
    /** STL compatible iterators */
    iterator begin();
    iterator end();
    const_iterator begin() const;
    const_iterator end() const;
    //@}


#ifndef DOXYGEN_INTERNAL_ONLY
    /** @brief copy the list into the buffer of the given size
     *  - if the list does not fit in the buffer, the required size is
     *      returned and the buffer is left in an undefined state
     *  - otherwise the tuples are 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 the tuple (NULL is safe)
     *  @param len the size of the buffer in bytes
     *  @param byteswap whether or not to swap the endiannes of the output bytes
     *  @return the space required/used to serialize the list in bytes
     *  <em>Note: this method is not public API, and is for internal StreamBase use only</em>
     */
    size_t copyIntoBuffer(char* buf, size_t len, bool byteswap) const;
    static TupleList createFromPackedBuffer(size_t* size_used,
            const char* buf, size_t buf_len, bool byteswap, const Schema& s, 
            size_t expect_num_tuples = (size_t)-1);
    static TupleList createRawFromPackedBuffer(size_t* size_used,
            const char* buf, size_t buf_len, bool byteswap, const Schema& s, 
            size_t expect_num_tuples = (size_t)-1);

    const std::string getRawBits() const { return _->rawBits; }
    void setRawBits(const char *bits, const size_t len) { _->rawBits.assign(bits, len); }
#endif

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

private:
    struct TupleListPrivateImpl {
        Schema schema;
        std::vector<Tuple> tuples;
        std::string rawBits; // Holds the serialized tuples; only used for raw dequeues (i.e. .NET Client API)
    
        TupleListPrivateImpl() { }
        TupleListPrivateImpl(const TupleListPrivateImpl& t) :
            schema(t.schema), tuples(t.tuples), rawBits(t.rawBits) { }
    };

    std::shared_ptr<TupleListPrivateImpl> _;
    /// 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;
};

SB_NAMESPACE_END;

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


#endif