StreamBase C++ API  10.6.4.2
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 
8 SB_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 */
17 class TupleList {
18 public:
19  /** Default (null) constructor. */
20  TupleList();
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 */
74  Tuple& back();
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 
121 private:
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 
140 SB_NAMESPACE_END;
141 
142 inline std::ostream& operator << (std::ostream& os, const sb::TupleList& tl) {
143  os << tl.as_string();
144  return os;
145 }
146 
147 
148 #endif