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