Streaming C++ API
TupleList.hpp
1// Copyright (c) 2004-2023 TIBCO Software Inc. All rights reserved.
2
3#ifndef STREAMBASE_TUPLE_LIST_H
4#define STREAMBASE_TUPLE_LIST_H
5
6#include "Tuple.hpp"
7
8SB_NAMESPACE_BEGIN;
9
10/** TupleLists are value types that can be copied and modified seperately thus
11 *
12 * tl2 = tl1;
13 * tl2[0].clear(); // does not modify t1
14 *
15 * They will only make copies of the underlying data as needed, so
16 * they are relatively cheap to pass around by value */
17class TupleList {
18public:
19 /** Default (null) constructor. */
21
22 /** Create tuple list from a single tuple. */
23 TupleList(const Tuple& tuple);
24
25 /** Create tuple list from a tuplelist. */
26 TupleList(const TupleList& list);
27
28 /** Create tuple list with an initial size of <i>size</i> */
29 TupleList(const Schema &schema, size_t size = 0);
30
31 ~TupleList();
32
33 const TupleList& operator=(const TupleList& rhs);
34
35 /** Get the schema. */
36 const Schema& getSchema() const;
37 /** set the schema for this list
38 * (also setting the schema for any tuples in the list) */
39 void setSchema(const Schema& schema);
40
41 //@{
42 /** Get the number of tuples in the list */
43 size_t getSize() const;
44 size_t size() const { return getSize(); }
45 //@}
46
47 //@{
48 /** Change the size of the list
49 * any new tuples will be entirely null */
50 void resize(size_t size) { setSize(size); }
51 void setSize(size_t size);
52 //@}
53
54 /**
55 * clear the list
56 */
57 void clear() { setSize(0); }
58
59 /** Is the list empty? */
60 bool empty() const { return size() == 0; }
61
62 /** Get the <i>n</i>th tuple. Fails with a std::out_of_range
63 * exception if out of range. */
64 const Tuple& operator[] (size_t index) const;
65 /** Get the <i>n</i>th tuple. Fails with a std::out_of_range
66 * exception if out of range. */
67 Tuple& operator[] (size_t index);
68
69 /** append a tuple to the list */
70 void push_back(const Tuple& r);
71
72 //@{
73 /** return the last tuple in the list */
75 const Tuple& back() const;
76 //@}
77
78
79 typedef std::vector<Tuple>::iterator iterator;
80 typedef std::vector<Tuple>::const_iterator const_iterator;
81
82 //@{
83 /** STL compatible iterators */
84 iterator begin();
85 iterator end();
86 const_iterator begin() const;
87 const_iterator end() const;
88 //@}
89
90
91#ifndef DOXYGEN_INTERNAL_ONLY
92 /** @brief copy the list into the buffer of the given size
93 * - if the list does not fit in the buffer, the required size is
94 * returned and the buffer is left in an undefined state
95 * - otherwise the tuples are copied into the buffer in a packed
96 * representation and the amount of the buffer used is returned
97 *
98 * @param buf the buffer into which to copy the tuple (NULL is safe)
99 * @param len the size of the buffer in bytes
100 * @param byteswap whether or not to swap the endiannes of the output bytes
101 * @return the space required/used to serialize the list in bytes
102 * <em>Note: this method is not public API, and is for internal StreamBase use only</em>
103 */
104 size_t copyIntoBuffer(char* buf, size_t len, bool byteswap) const;
105 static TupleList createFromPackedBuffer(size_t* size_used,
106 const char* buf, size_t buf_len, bool byteswap, const Schema& s,
107 size_t expect_num_tuples = (size_t)-1);
108 static TupleList createRawFromPackedBuffer(size_t* size_used,
109 const char* buf, size_t buf_len, bool byteswap, const Schema& s,
110 size_t expect_num_tuples = (size_t)-1);
111
112 const std::string getRawBits() const { return _->rawBits; }
113 void setRawBits(const char *bits, const size_t len) { _->rawBits.assign(bits, len); }
114#endif
115
116 /** Return a human-readable string value representing this list
117 * in its entirety (including all header values, if applicable).
118 * @return the string value. */
119 std::string as_string() const;
120
121private:
122 struct TupleListPrivateImpl {
123 Schema schema;
124 std::vector<Tuple> tuples;
125 std::string rawBits; // Holds the serialized tuples; only used for raw dequeues (i.e. .NET Client API)
126
127 TupleListPrivateImpl() { }
128 TupleListPrivateImpl(const TupleListPrivateImpl& t) :
129 schema(t.schema), tuples(t.tuples), rawBits(t.rawBits) { }
130 };
131
132 std::shared_ptr<TupleListPrivateImpl> _;
133 /// These methods are used to implement copy-on-write
134 /// ensureUnique() should be called as the first line of any non-const method
135 /// ensureAllocated() should be called as the first line of any const method
136 void ensureUnique();
137 void ensureAllocated() const;
138};
139
140SB_NAMESPACE_END;
141
142inline std::ostream& operator << (std::ostream& os, const sb::TupleList& tl) {
143 os << tl.as_string();
144 return os;
145}
146
147
148#endif
A type of tuple, containing zero or more fields (each encapsulated as a Schema::Field object).
Definition: Schema.hpp:62
TupleLists are value types that can be copied and modified seperately thus.
Definition: TupleList.hpp:17
std::string as_string() const
Return a human-readable string value representing this list in its entirety (including all header val...
TupleList(const Schema &schema, size_t size=0)
Create tuple list with an initial size of size
TupleList(const TupleList &list)
Create tuple list from a tuplelist.
void clear()
clear the list
Definition: TupleList.hpp:57
iterator begin()
STL compatible iterators.
void setSchema(const Schema &schema)
set the schema for this list (also setting the schema for any tuples in the list)
void push_back(const Tuple &r)
append a tuple to the list
size_t getSize() const
Get the number of tuples in the list.
const Schema & getSchema() const
Get the schema.
TupleList(const Tuple &tuple)
Create tuple list from a single tuple.
Tuple & back()
return the last tuple in the list
bool empty() const
Is the list empty?
Definition: TupleList.hpp:60
void resize(size_t size)
Change the size of the list any new tuples will be entirely null.
Definition: TupleList.hpp:50
TupleList()
Default (null) constructor.
Tuples are value types that can be copied and modified separately thus.
Definition: Tuple.hpp:47