1// Protocol Buffers - Google's data interchange format
2// Copyright 2008 Google Inc. All rights reserved.
3// https://developers.google.com/protocol-buffers/
4//
5// Redistribution and use in source and binary forms, with or without
6// modification, are permitted provided that the following conditions are
7// met:
8//
9// * Redistributions of source code must retain the above copyright
10// notice, this list of conditions and the following disclaimer.
11// * Redistributions in binary form must reproduce the above
12// copyright notice, this list of conditions and the following disclaimer
13// in the documentation and/or other materials provided with the
14// distribution.
15// * Neither the name of Google Inc. nor the names of its
16// contributors may be used to endorse or promote products derived from
17// this software without specific prior written permission.
18//
19// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31// This file declares the ByteSink and ByteSource abstract interfaces. These
32// interfaces represent objects that consume (ByteSink) or produce (ByteSource)
33// a sequence of bytes. Using these abstract interfaces in your APIs can help
34// make your code work with a variety of input and output types.
35//
36// This file also declares the following commonly used implementations of these
37// interfaces.
38//
39// ByteSink:
40// UncheckedArrayByteSink Writes to an array, without bounds checking
41// CheckedArrayByteSink Writes to an array, with bounds checking
42// GrowingArrayByteSink Allocates and writes to a growable buffer
43// StringByteSink Writes to an STL string
44// NullByteSink Consumes a never-ending stream of bytes
45//
46// ByteSource:
47// ArrayByteSource Reads from an array or string/StringPiece
48// LimitedByteSource Limits the number of bytes read from an
49
50#ifndef GOOGLE_PROTOBUF_STUBS_BYTESTREAM_H_
51#define GOOGLE_PROTOBUF_STUBS_BYTESTREAM_H_
52
53#include <stddef.h>
54#include <string>
55
56#include <google/protobuf/stubs/common.h>
57#include <google/protobuf/stubs/stringpiece.h>
58
59#include <google/protobuf/port_def.inc>
60
61class CordByteSink;
62
63namespace google {
64namespace protobuf {
65namespace strings {
66
67// An abstract interface for an object that consumes a sequence of bytes. This
68// interface offers a way to append data as well as a Flush() function.
69//
70// Example:
71//
72// string my_data;
73// ...
74// ByteSink* sink = ...
75// sink->Append(my_data.data(), my_data.size());
76// sink->Flush();
77//
78class PROTOBUF_EXPORT ByteSink {
79 public:
80 ByteSink() {}
81 virtual ~ByteSink() {}
82
83 // Appends the "n" bytes starting at "bytes".
84 virtual void Append(const char* bytes, size_t n) = 0;
85
86 // Flushes internal buffers. The default implementation does nothing. ByteSink
87 // subclasses may use internal buffers that require calling Flush() at the end
88 // of the stream.
89 virtual void Flush();
90
91 private:
92 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ByteSink);
93};
94
95// An abstract interface for an object that produces a fixed-size sequence of
96// bytes.
97//
98// Example:
99//
100// ByteSource* source = ...
101// while (source->Available() > 0) {
102// StringPiece data = source->Peek();
103// ... do something with "data" ...
104// source->Skip(data.length());
105// }
106//
107class PROTOBUF_EXPORT ByteSource {
108 public:
109 ByteSource() {}
110 virtual ~ByteSource() {}
111
112 // Returns the number of bytes left to read from the source. Available()
113 // should decrease by N each time Skip(N) is called. Available() may not
114 // increase. Available() returning 0 indicates that the ByteSource is
115 // exhausted.
116 //
117 // Note: Size() may have been a more appropriate name as it's more
118 // indicative of the fixed-size nature of a ByteSource.
119 virtual size_t Available() const = 0;
120
121 // Returns a StringPiece of the next contiguous region of the source. Does not
122 // reposition the source. The returned region is empty iff Available() == 0.
123 //
124 // The returned region is valid until the next call to Skip() or until this
125 // object is destroyed, whichever occurs first.
126 //
127 // The length of the returned StringPiece will be <= Available().
128 virtual StringPiece Peek() = 0;
129
130 // Skips the next n bytes. Invalidates any StringPiece returned by a previous
131 // call to Peek().
132 //
133 // REQUIRES: Available() >= n
134 virtual void Skip(size_t n) = 0;
135
136 // Writes the next n bytes in this ByteSource to the given ByteSink, and
137 // advances this ByteSource past the copied bytes. The default implementation
138 // of this method just copies the bytes normally, but subclasses might
139 // override CopyTo to optimize certain cases.
140 //
141 // REQUIRES: Available() >= n
142 virtual void CopyTo(ByteSink* sink, size_t n);
143
144 private:
145 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ByteSource);
146};
147
148//
149// Some commonly used implementations of ByteSink
150//
151
152// Implementation of ByteSink that writes to an unsized byte array. No
153// bounds-checking is performed--it is the caller's responsibility to ensure
154// that the destination array is large enough.
155//
156// Example:
157//
158// char buf[10];
159// UncheckedArrayByteSink sink(buf);
160// sink.Append("hi", 2); // OK
161// sink.Append(data, 100); // WOOPS! Overflows buf[10].
162//
163class PROTOBUF_EXPORT UncheckedArrayByteSink : public ByteSink {
164 public:
165 explicit UncheckedArrayByteSink(char* dest) : dest_(dest) {}
166 virtual void Append(const char* data, size_t n) override;
167
168 // Returns the current output pointer so that a caller can see how many bytes
169 // were produced.
170 //
171 // Note: this method is not part of the ByteSink interface.
172 char* CurrentDestination() const { return dest_; }
173
174 private:
175 char* dest_;
176 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(UncheckedArrayByteSink);
177};
178
179// Implementation of ByteSink that writes to a sized byte array. This sink will
180// not write more than "capacity" bytes to outbuf. Once "capacity" bytes are
181// appended, subsequent bytes will be ignored and Overflowed() will return true.
182// Overflowed() does not cause a runtime error (i.e., it does not CHECK fail).
183//
184// Example:
185//
186// char buf[10];
187// CheckedArrayByteSink sink(buf, 10);
188// sink.Append("hi", 2); // OK
189// sink.Append(data, 100); // Will only write 8 more bytes
190//
191class PROTOBUF_EXPORT CheckedArrayByteSink : public ByteSink {
192 public:
193 CheckedArrayByteSink(char* outbuf, size_t capacity);
194 virtual void Append(const char* bytes, size_t n) override;
195
196 // Returns the number of bytes actually written to the sink.
197 size_t NumberOfBytesWritten() const { return size_; }
198
199 // Returns true if any bytes were discarded, i.e., if there was an
200 // attempt to write more than 'capacity' bytes.
201 bool Overflowed() const { return overflowed_; }
202
203 private:
204 char* outbuf_;
205 const size_t capacity_;
206 size_t size_;
207 bool overflowed_;
208 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(CheckedArrayByteSink);
209};
210
211// Implementation of ByteSink that allocates an internal buffer (a char array)
212// and expands it as needed to accommodate appended data (similar to a string),
213// and allows the caller to take ownership of the internal buffer via the
214// GetBuffer() method. The buffer returned from GetBuffer() must be deleted by
215// the caller with delete[]. GetBuffer() also sets the internal buffer to be
216// empty, and subsequent appends to the sink will create a new buffer. The
217// destructor will free the internal buffer if GetBuffer() was not called.
218//
219// Example:
220//
221// GrowingArrayByteSink sink(10);
222// sink.Append("hi", 2);
223// sink.Append(data, n);
224// const char* buf = sink.GetBuffer(); // Ownership transferred
225// delete[] buf;
226//
227class PROTOBUF_EXPORT GrowingArrayByteSink : public strings::ByteSink {
228 public:
229 explicit GrowingArrayByteSink(size_t estimated_size);
230 virtual ~GrowingArrayByteSink();
231 virtual void Append(const char* bytes, size_t n) override;
232
233 // Returns the allocated buffer, and sets nbytes to its size. The caller takes
234 // ownership of the buffer and must delete it with delete[].
235 char* GetBuffer(size_t* nbytes);
236
237 private:
238 void Expand(size_t amount);
239 void ShrinkToFit();
240
241 size_t capacity_;
242 char* buf_;
243 size_t size_;
244 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(GrowingArrayByteSink);
245};
246
247// Implementation of ByteSink that appends to the given string.
248// Existing contents of "dest" are not modified; new data is appended.
249//
250// Example:
251//
252// string dest = "Hello ";
253// StringByteSink sink(&dest);
254// sink.Append("World", 5);
255// assert(dest == "Hello World");
256//
257class PROTOBUF_EXPORT StringByteSink : public ByteSink {
258 public:
259 explicit StringByteSink(std::string* dest) : dest_(dest) {}
260 virtual void Append(const char* data, size_t n) override;
261
262 private:
263 std::string* dest_;
264 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(StringByteSink);
265};
266
267// Implementation of ByteSink that discards all data.
268//
269// Example:
270//
271// NullByteSink sink;
272// sink.Append(data, data.size()); // All data ignored.
273//
274class PROTOBUF_EXPORT NullByteSink : public ByteSink {
275 public:
276 NullByteSink() {}
277 void Append(const char* /*data*/, size_t /*n*/) override {}
278
279 private:
280 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(NullByteSink);
281};
282
283//
284// Some commonly used implementations of ByteSource
285//
286
287// Implementation of ByteSource that reads from a StringPiece.
288//
289// Example:
290//
291// string data = "Hello";
292// ArrayByteSource source(data);
293// assert(source.Available() == 5);
294// assert(source.Peek() == "Hello");
295//
296class PROTOBUF_EXPORT ArrayByteSource : public ByteSource {
297 public:
298 explicit ArrayByteSource(StringPiece s) : input_(s) {}
299
300 virtual size_t Available() const override;
301 virtual StringPiece Peek() override;
302 virtual void Skip(size_t n) override;
303
304 private:
305 StringPiece input_;
306 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ArrayByteSource);
307};
308
309// Implementation of ByteSource that wraps another ByteSource, limiting the
310// number of bytes returned.
311//
312// The caller maintains ownership of the underlying source, and may not use the
313// underlying source while using the LimitByteSource object. The underlying
314// source's pointer is advanced by n bytes every time this LimitByteSource
315// object is advanced by n.
316//
317// Example:
318//
319// string data = "Hello World";
320// ArrayByteSource abs(data);
321// assert(abs.Available() == data.size());
322//
323// LimitByteSource limit(abs, 5);
324// assert(limit.Available() == 5);
325// assert(limit.Peek() == "Hello");
326//
327class PROTOBUF_EXPORT LimitByteSource : public ByteSource {
328 public:
329 // Returns at most "limit" bytes from "source".
330 LimitByteSource(ByteSource* source, size_t limit);
331
332 virtual size_t Available() const override;
333 virtual StringPiece Peek() override;
334 virtual void Skip(size_t n) override;
335
336 // We override CopyTo so that we can forward to the underlying source, in
337 // case it has an efficient implementation of CopyTo.
338 virtual void CopyTo(ByteSink* sink, size_t n) override;
339
340 private:
341 ByteSource* source_;
342 size_t limit_;
343};
344
345} // namespace strings
346} // namespace protobuf
347} // namespace google
348
349#include <google/protobuf/port_undef.inc>
350
351#endif // GOOGLE_PROTOBUF_STUBS_BYTESTREAM_H_
352