llvm/Support/BinaryStream.h

0001 //===- BinaryStream.h - Base interface for a stream of data -----*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008
0009 #ifndef LLVM_SUPPORT_BINARYSTREAM_H
0010 #define LLVM_SUPPORT_BINARYSTREAM_H
0011
0012 #include "llvm/ADT/ArrayRef.h"
0013 #include "llvm/ADT/BitmaskEnum.h"
0014 #include "llvm/Support/BinaryStreamError.h"
0015 #include "llvm/Support/Error.h"
0016 #include <cstdint>
0017
0018 namespace llvm {
0019
0020 enum BinaryStreamFlags {
0021   BSF_None = 0,
0022   BSF_Write = 1,  // Stream supports writing.
0023   BSF_Append = 2, // Writing can occur at offset == length.
0024   LLVM_MARK_AS_BITMASK_ENUM(/* LargestValue = */ BSF_Append)
0025 };
0026
0027 /// An interface for accessing data in a stream-like format, but which
0028 /// discourages copying.  Instead of specifying a buffer in which to copy
0029 /// data on a read, the API returns an ArrayRef to data owned by the stream's
0030 /// implementation.  Since implementations may not necessarily store data in a
0031 /// single contiguous buffer (or even in memory at all), in such cases a it may
0032 /// be necessary for an implementation to cache such a buffer so that it can
0033 /// return it.
0034 class BinaryStream {
0035 public:
0036   virtual ~BinaryStream() = default;
0037
0038   virtual llvm::endianness getEndian() const = 0;
0039
0040   /// Given an offset into the stream and a number of bytes, attempt to
0041   /// read the bytes and set the output ArrayRef to point to data owned by the
0042   /// stream.
0043   virtual Error readBytes(uint64_t Offset, uint64_t Size,
0044                           ArrayRef<uint8_t> &Buffer) = 0;
0045
0046   /// Given an offset into the stream, read as much as possible without
0047   /// copying any data.
0048   virtual Error readLongestContiguousChunk(uint64_t Offset,
0049                                            ArrayRef<uint8_t> &Buffer) = 0;
0050
0051   /// Return the number of bytes of data in this stream.
0052   virtual uint64_t getLength() = 0;
0053
0054   /// Return the properties of this stream.
0055   virtual BinaryStreamFlags getFlags() const { return BSF_None; }
0056
0057 protected:
0058   Error checkOffsetForRead(uint64_t Offset, uint64_t DataSize) {
0059     if (Offset > getLength())
0060       return make_error<BinaryStreamError>(stream_error_code::invalid_offset);
0061     if (getLength() < DataSize + Offset)
0062       return make_error<BinaryStreamError>(stream_error_code::stream_too_short);
0063     return Error::success();
0064   }
0065 };
0066
0067 /// A BinaryStream which can be read from as well as written to.  Note
0068 /// that writing to a BinaryStream always necessitates copying from the input
0069 /// buffer to the stream's backing store.  Streams are assumed to be buffered
0070 /// so that to be portable it is necessary to call commit() on the stream when
0071 /// all data has been written.
0072 class WritableBinaryStream : public BinaryStream {
0073 public:
0074   ~WritableBinaryStream() override = default;
0075
0076   /// Attempt to write the given bytes into the stream at the desired
0077   /// offset. This will always necessitate a copy.  Cannot shrink or grow the
0078   /// stream, only writes into existing allocated space.
0079   virtual Error writeBytes(uint64_t Offset, ArrayRef<uint8_t> Data) = 0;
0080
0081   /// For buffered streams, commits changes to the backing store.
0082   virtual Error commit() = 0;
0083
0084   /// Return the properties of this stream.
0085   BinaryStreamFlags getFlags() const override { return BSF_Write; }
0086
0087 protected:
0088   Error checkOffsetForWrite(uint64_t Offset, uint64_t DataSize) {
0089     if (!(getFlags() & BSF_Append))
0090       return checkOffsetForRead(Offset, DataSize);
0091
0092     if (Offset > getLength())
0093       return make_error<BinaryStreamError>(stream_error_code::invalid_offset);
0094     return Error::success();
0095   }
0096 };
0097
0098 } // end namespace llvm
0099
0100 #endif // LLVM_SUPPORT_BINARYSTREAM_H