• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 class CordByteSink;
60 class MemBlock;
61 
62 namespace google {
63 namespace protobuf {
64 namespace strings {
65 
66 // An abstract interface for an object that consumes a sequence of bytes. This
67 // interface offers 3 different ways to append data, and a Flush() function.
68 //
69 // Example:
70 //
71 //   string my_data;
72 //   ...
73 //   ByteSink* sink = ...
74 //   sink->Append(my_data.data(), my_data.size());
75 //   sink->Flush();
76 //
77 class LIBPROTOBUF_EXPORT ByteSink {
78  public:
ByteSink()79   ByteSink() {}
~ByteSink()80   virtual ~ByteSink() {}
81 
82   // Appends the "n" bytes starting at "bytes".
83   virtual void Append(const char* bytes, size_t n) = 0;
84 
85   // Flushes internal buffers. The default implemenation does nothing. ByteSink
86   // subclasses may use internal buffers that require calling Flush() at the end
87   // of the stream.
88   virtual void Flush();
89 
90  private:
91   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ByteSink);
92 };
93 
94 // An abstract interface for an object that produces a fixed-size sequence of
95 // bytes.
96 //
97 // Example:
98 //
99 //   ByteSource* source = ...
100 //   while (source->Available() > 0) {
101 //     StringPiece data = source->Peek();
102 //     ... do something with "data" ...
103 //     source->Skip(data.length());
104 //   }
105 //
106 class LIBPROTOBUF_EXPORT ByteSource {
107  public:
ByteSource()108   ByteSource() {}
~ByteSource()109   virtual ~ByteSource() {}
110 
111   // Returns the number of bytes left to read from the source. Available()
112   // should decrease by N each time Skip(N) is called. Available() may not
113   // increase. Available() returning 0 indicates that the ByteSource is
114   // exhausted.
115   //
116   // Note: Size() may have been a more appropriate name as it's more
117   //       indicative of the fixed-size nature of a ByteSource.
118   virtual size_t Available() const = 0;
119 
120   // Returns a StringPiece of the next contiguous region of the source. Does not
121   // reposition the source. The returned region is empty iff Available() == 0.
122   //
123   // The returned region is valid until the next call to Skip() or until this
124   // object is destroyed, whichever occurs first.
125   //
126   // The length of the returned StringPiece will be <= Available().
127   virtual StringPiece Peek() = 0;
128 
129   // Skips the next n bytes. Invalidates any StringPiece returned by a previous
130   // call to Peek().
131   //
132   // REQUIRES: Available() >= n
133   virtual void Skip(size_t n) = 0;
134 
135   // Writes the next n bytes in this ByteSource to the given ByteSink, and
136   // advances this ByteSource past the copied bytes. The default implementation
137   // of this method just copies the bytes normally, but subclasses might
138   // override CopyTo to optimize certain cases.
139   //
140   // REQUIRES: Available() >= n
141   virtual void CopyTo(ByteSink* sink, size_t n);
142 
143  private:
144   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ByteSource);
145 };
146 
147 //
148 // Some commonly used implementations of ByteSink
149 //
150 
151 // Implementation of ByteSink that writes to an unsized byte array. No
152 // bounds-checking is performed--it is the caller's responsibility to ensure
153 // that the destination array is large enough.
154 //
155 // Example:
156 //
157 //   char buf[10];
158 //   UncheckedArrayByteSink sink(buf);
159 //   sink.Append("hi", 2);    // OK
160 //   sink.Append(data, 100);  // WOOPS! Overflows buf[10].
161 //
162 class LIBPROTOBUF_EXPORT UncheckedArrayByteSink : public ByteSink {
163  public:
UncheckedArrayByteSink(char * dest)164   explicit UncheckedArrayByteSink(char* dest) : dest_(dest) {}
165   virtual void Append(const char* data, size_t n);
166 
167   // Returns the current output pointer so that a caller can see how many bytes
168   // were produced.
169   //
170   // Note: this method is not part of the ByteSink interface.
CurrentDestination()171   char* CurrentDestination() const { return dest_; }
172 
173  private:
174   char* dest_;
175   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(UncheckedArrayByteSink);
176 };
177 
178 // Implementation of ByteSink that writes to a sized byte array. This sink will
179 // not write more than "capacity" bytes to outbuf. Once "capacity" bytes are
180 // appended, subsequent bytes will be ignored and Overflowed() will return true.
181 // Overflowed() does not cause a runtime error (i.e., it does not CHECK fail).
182 //
183 // Example:
184 //
185 //   char buf[10];
186 //   CheckedArrayByteSink sink(buf, 10);
187 //   sink.Append("hi", 2);    // OK
188 //   sink.Append(data, 100);  // Will only write 8 more bytes
189 //
190 class LIBPROTOBUF_EXPORT CheckedArrayByteSink : public ByteSink {
191  public:
192   CheckedArrayByteSink(char* outbuf, size_t capacity);
193   virtual void Append(const char* bytes, size_t n);
194 
195   // Returns the number of bytes actually written to the sink.
NumberOfBytesWritten()196   size_t NumberOfBytesWritten() const { return size_; }
197 
198   // Returns true if any bytes were discarded, i.e., if there was an
199   // attempt to write more than 'capacity' bytes.
Overflowed()200   bool Overflowed() const { return overflowed_; }
201 
202  private:
203   char* outbuf_;
204   const size_t capacity_;
205   size_t size_;
206   bool overflowed_;
207   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(CheckedArrayByteSink);
208 };
209 
210 // Implementation of ByteSink that allocates an internal buffer (a char array)
211 // and expands it as needed to accomodate appended data (similar to a string),
212 // and allows the caller to take ownership of the internal buffer via the
213 // GetBuffer() method. The buffer returned from GetBuffer() must be deleted by
214 // the caller with delete[]. GetBuffer() also sets the internal buffer to be
215 // empty, and subsequent appends to the sink will create a new buffer. The
216 // destructor will free the internal buffer if GetBuffer() was not called.
217 //
218 // Example:
219 //
220 //   GrowingArrayByteSink sink(10);
221 //   sink.Append("hi", 2);
222 //   sink.Append(data, n);
223 //   const char* buf = sink.GetBuffer();  // Ownership transferred
224 //   delete[] buf;
225 //
226 class LIBPROTOBUF_EXPORT GrowingArrayByteSink : public strings::ByteSink {
227  public:
228   explicit GrowingArrayByteSink(size_t estimated_size);
229   virtual ~GrowingArrayByteSink();
230   virtual void Append(const char* bytes, size_t n);
231 
232   // Returns the allocated buffer, and sets nbytes to its size. The caller takes
233   // ownership of the buffer and must delete it with delete[].
234   char* GetBuffer(size_t* nbytes);
235 
236  private:
237   void Expand(size_t amount);
238   void ShrinkToFit();
239 
240   size_t capacity_;
241   char* buf_;
242   size_t size_;
243   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(GrowingArrayByteSink);
244 };
245 
246 // Implementation of ByteSink that appends to the given string.
247 // Existing contents of "dest" are not modified; new data is appended.
248 //
249 // Example:
250 //
251 //   string dest = "Hello ";
252 //   StringByteSink sink(&dest);
253 //   sink.Append("World", 5);
254 //   assert(dest == "Hello World");
255 //
256 class LIBPROTOBUF_EXPORT StringByteSink : public ByteSink {
257  public:
StringByteSink(string * dest)258   explicit StringByteSink(string* dest) : dest_(dest) {}
259   virtual void Append(const char* data, size_t n);
260 
261  private:
262   string* dest_;
263   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(StringByteSink);
264 };
265 
266 // Implementation of ByteSink that discards all data.
267 //
268 // Example:
269 //
270 //   NullByteSink sink;
271 //   sink.Append(data, data.size());  // All data ignored.
272 //
273 class LIBPROTOBUF_EXPORT NullByteSink : public ByteSink {
274  public:
NullByteSink()275   NullByteSink() {}
Append(const char * data,size_t n)276   virtual void Append(const char *data, size_t n) {}
277 
278  private:
279   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(NullByteSink);
280 };
281 
282 //
283 // Some commonly used implementations of ByteSource
284 //
285 
286 // Implementation of ByteSource that reads from a StringPiece.
287 //
288 // Example:
289 //
290 //   string data = "Hello";
291 //   ArrayByteSource source(data);
292 //   assert(source.Available() == 5);
293 //   assert(source.Peek() == "Hello");
294 //
295 class LIBPROTOBUF_EXPORT ArrayByteSource : public ByteSource {
296  public:
ArrayByteSource(StringPiece s)297   explicit ArrayByteSource(StringPiece s) : input_(s) {}
298 
299   virtual size_t Available() const;
300   virtual StringPiece Peek();
301   virtual void Skip(size_t n);
302 
303  private:
304   StringPiece   input_;
305   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ArrayByteSource);
306 };
307 
308 // Implementation of ByteSource that wraps another ByteSource, limiting the
309 // number of bytes returned.
310 //
311 // The caller maintains ownership of the underlying source, and may not use the
312 // underlying source while using the LimitByteSource object.  The underlying
313 // source's pointer is advanced by n bytes every time this LimitByteSource
314 // object is advanced by n.
315 //
316 // Example:
317 //
318 //   string data = "Hello World";
319 //   ArrayByteSource abs(data);
320 //   assert(abs.Available() == data.size());
321 //
322 //   LimitByteSource limit(abs, 5);
323 //   assert(limit.Available() == 5);
324 //   assert(limit.Peek() == "Hello");
325 //
326 class LIBPROTOBUF_EXPORT LimitByteSource : public ByteSource {
327  public:
328   // Returns at most "limit" bytes from "source".
329   LimitByteSource(ByteSource* source, size_t limit);
330 
331   virtual size_t Available() const;
332   virtual StringPiece Peek();
333   virtual void Skip(size_t n);
334 
335   // We override CopyTo so that we can forward to the underlying source, in
336   // case it has an efficient implementation of CopyTo.
337   virtual void CopyTo(ByteSink* sink, size_t n);
338 
339  private:
340   ByteSource* source_;
341   size_t limit_;
342 };
343 
344 }  // namespace strings
345 }  // namespace protobuf
346 }  // namespace google
347 
348 #endif  // GOOGLE_PROTOBUF_STUBS_BYTESTREAM_H_
349