BinaryStreamRef.h revision 341825 
1//===- BinaryStreamRef.h - A copyable reference to a stream -----*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9
10#ifndef LLVM_SUPPORT_BINARYSTREAMREF_H
11#define LLVM_SUPPORT_BINARYSTREAMREF_H
12
13#include "llvm/ADT/ArrayRef.h"
14#include "llvm/ADT/Optional.h"
15#include "llvm/Support/BinaryStream.h"
16#include "llvm/Support/BinaryStreamError.h"
17#include "llvm/Support/Error.h"
18#include <algorithm>
19#include <cstdint>
20#include <memory>
21
22namespace llvm {
23
24/// Common stuff for mutable and immutable StreamRefs.
25template <class RefType, class StreamType> class BinaryStreamRefBase {
26protected:
27  BinaryStreamRefBase() = default;
28  explicit BinaryStreamRefBase(StreamType &BorrowedImpl)
29      : BorrowedImpl(&BorrowedImpl), ViewOffset(0) {
30    if (!(BorrowedImpl.getFlags() & BSF_Append))
31      Length = BorrowedImpl.getLength();
32  }
33
34  BinaryStreamRefBase(std::shared_ptr<StreamType> SharedImpl, uint32_t Offset,
35                      Optional<uint32_t> Length)
36      : SharedImpl(SharedImpl), BorrowedImpl(SharedImpl.get()),
37        ViewOffset(Offset), Length(Length) {}
38  BinaryStreamRefBase(StreamType &BorrowedImpl, uint32_t Offset,
39                      Optional<uint32_t> Length)
40      : BorrowedImpl(&BorrowedImpl), ViewOffset(Offset), Length(Length) {}
41  BinaryStreamRefBase(const BinaryStreamRefBase &Other) = default;
42  BinaryStreamRefBase &operator=(const BinaryStreamRefBase &Other) = default;
43
44  BinaryStreamRefBase &operator=(BinaryStreamRefBase &&Other) = default;
45  BinaryStreamRefBase(BinaryStreamRefBase &&Other) = default;
46
47public:
48  llvm::support::endianness getEndian() const {
49    return BorrowedImpl->getEndian();
50  }
51
52  uint32_t getLength() const {
53    if (Length.hasValue())
54      return *Length;
55
56    return BorrowedImpl ? (BorrowedImpl->getLength() - ViewOffset) : 0;
57  }
58
59  /// Return a new BinaryStreamRef with the first \p N elements removed.  If
60  /// this BinaryStreamRef is length-tracking, then the resulting one will be
61  /// too.
62  RefType drop_front(uint32_t N) const {
63    if (!BorrowedImpl)
64      return RefType();
65
66    N = std::min(N, getLength());
67    RefType Result(static_cast<const RefType &>(*this));
68    if (N == 0)
69      return Result;
70
71    Result.ViewOffset += N;
72    if (Result.Length.hasValue())
73      *Result.Length -= N;
74    return Result;
75  }
76
77  /// Return a new BinaryStreamRef with the last \p N elements removed.  If
78  /// this BinaryStreamRef is length-tracking and \p N is greater than 0, then
79  /// this BinaryStreamRef will no longer length-track.
80  RefType drop_back(uint32_t N) const {
81    if (!BorrowedImpl)
82      return RefType();
83
84    RefType Result(static_cast<const RefType &>(*this));
85    N = std::min(N, getLength());
86
87    if (N == 0)
88      return Result;
89
90    // Since we're dropping non-zero bytes from the end, stop length-tracking
91    // by setting the length of the resulting StreamRef to an explicit value.
92    if (!Result.Length.hasValue())
93      Result.Length = getLength();
94
95    *Result.Length -= N;
96    return Result;
97  }
98
99  /// Return a new BinaryStreamRef with only the first \p N elements remaining.
100  RefType keep_front(uint32_t N) const {
101    assert(N <= getLength());
102    return drop_back(getLength() - N);
103  }
104
105  /// Return a new BinaryStreamRef with only the last \p N elements remaining.
106  RefType keep_back(uint32_t N) const {
107    assert(N <= getLength());
108    return drop_front(getLength() - N);
109  }
110
111  /// Return a new BinaryStreamRef with the first and last \p N elements
112  /// removed.
113  RefType drop_symmetric(uint32_t N) const {
114    return drop_front(N).drop_back(N);
115  }
116
117  /// Return a new BinaryStreamRef with the first \p Offset elements removed,
118  /// and retaining exactly \p Len elements.
119  RefType slice(uint32_t Offset, uint32_t Len) const {
120    return drop_front(Offset).keep_front(Len);
121  }
122
123  bool valid() const { return BorrowedImpl != nullptr; }
124
125  bool operator==(const RefType &Other) const {
126    if (BorrowedImpl != Other.BorrowedImpl)
127      return false;
128    if (ViewOffset != Other.ViewOffset)
129      return false;
130    if (Length != Other.Length)
131      return false;
132    return true;
133  }
134
135protected:
136  Error checkOffsetForRead(uint32_t Offset, uint32_t DataSize) const {
137    if (Offset > getLength())
138      return make_error<BinaryStreamError>(stream_error_code::invalid_offset);
139    if (getLength() < DataSize + Offset)
140      return make_error<BinaryStreamError>(stream_error_code::stream_too_short);
141    return Error::success();
142  }
143
144  std::shared_ptr<StreamType> SharedImpl;
145  StreamType *BorrowedImpl = nullptr;
146  uint32_t ViewOffset = 0;
147  Optional<uint32_t> Length;
148};
149
150/// BinaryStreamRef is to BinaryStream what ArrayRef is to an Array.  It
151/// provides copy-semantics and read only access to a "window" of the underlying
152/// BinaryStream. Note that BinaryStreamRef is *not* a BinaryStream.  That is to
153/// say, it does not inherit and override the methods of BinaryStream.  In
154/// general, you should not pass around pointers or references to BinaryStreams
155/// and use inheritance to achieve polymorphism.  Instead, you should pass
156/// around BinaryStreamRefs by value and achieve polymorphism that way.
157class BinaryStreamRef
158    : public BinaryStreamRefBase<BinaryStreamRef, BinaryStream> {
159  friend BinaryStreamRefBase<BinaryStreamRef, BinaryStream>;
160  friend class WritableBinaryStreamRef;
161  BinaryStreamRef(std::shared_ptr<BinaryStream> Impl, uint32_t ViewOffset,
162                  Optional<uint32_t> Length)
163      : BinaryStreamRefBase(Impl, ViewOffset, Length) {}
164
165public:
166  BinaryStreamRef() = default;
167  BinaryStreamRef(BinaryStream &Stream);
168  BinaryStreamRef(BinaryStream &Stream, uint32_t Offset,
169                  Optional<uint32_t> Length);
170  explicit BinaryStreamRef(ArrayRef<uint8_t> Data,
171                           llvm::support::endianness Endian);
172  explicit BinaryStreamRef(StringRef Data, llvm::support::endianness Endian);
173
174  BinaryStreamRef(const BinaryStreamRef &Other) = default;
175  BinaryStreamRef &operator=(const BinaryStreamRef &Other) = default;
176  BinaryStreamRef(BinaryStreamRef &&Other) = default;
177  BinaryStreamRef &operator=(BinaryStreamRef &&Other) = default;
178
179  // Use BinaryStreamRef.slice() instead.
180  BinaryStreamRef(BinaryStreamRef &S, uint32_t Offset,
181                  uint32_t Length) = delete;
182
183  /// Given an Offset into this StreamRef and a Size, return a reference to a
184  /// buffer owned by the stream.
185  ///
186  /// \returns a success error code if the entire range of data is within the
187  /// bounds of this BinaryStreamRef's view and the implementation could read
188  /// the data, and an appropriate error code otherwise.
189  Error readBytes(uint32_t Offset, uint32_t Size,
190                  ArrayRef<uint8_t> &Buffer) const;
191
192  /// Given an Offset into this BinaryStreamRef, return a reference to the
193  /// largest buffer the stream could support without necessitating a copy.
194  ///
195  /// \returns a success error code if implementation could read the data,
196  /// and an appropriate error code otherwise.
197  Error readLongestContiguousChunk(uint32_t Offset,
198                                   ArrayRef<uint8_t> &Buffer) const;
199};
200
201struct BinarySubstreamRef {
202  uint32_t Offset;            // Offset in the parent stream
203  BinaryStreamRef StreamData; // Stream Data
204
205  BinarySubstreamRef slice(uint32_t Off, uint32_t Size) const {
206    BinaryStreamRef SubSub = StreamData.slice(Off, Size);
207    return {Off + Offset, SubSub};
208  }
209  BinarySubstreamRef drop_front(uint32_t N) const {
210    return slice(N, size() - N);
211  }
212  BinarySubstreamRef keep_front(uint32_t N) const { return slice(0, N); }
213
214  std::pair<BinarySubstreamRef, BinarySubstreamRef>
215  split(uint32_t Offset) const {
216    return std::make_pair(keep_front(Offset), drop_front(Offset));
217  }
218
219  uint32_t size() const { return StreamData.getLength(); }
220  bool empty() const { return size() == 0; }
221};
222
223class WritableBinaryStreamRef
224    : public BinaryStreamRefBase<WritableBinaryStreamRef,
225                                 WritableBinaryStream> {
226  friend BinaryStreamRefBase<WritableBinaryStreamRef, WritableBinaryStream>;
227  WritableBinaryStreamRef(std::shared_ptr<WritableBinaryStream> Impl,
228                          uint32_t ViewOffset, Optional<uint32_t> Length)
229      : BinaryStreamRefBase(Impl, ViewOffset, Length) {}
230
231  Error checkOffsetForWrite(uint32_t Offset, uint32_t DataSize) const {
232    if (!(BorrowedImpl->getFlags() & BSF_Append))
233      return checkOffsetForRead(Offset, DataSize);
234
235    if (Offset > getLength())
236      return make_error<BinaryStreamError>(stream_error_code::invalid_offset);
237    return Error::success();
238  }
239
240public:
241  WritableBinaryStreamRef() = default;
242  WritableBinaryStreamRef(WritableBinaryStream &Stream);
243  WritableBinaryStreamRef(WritableBinaryStream &Stream, uint32_t Offset,
244                          Optional<uint32_t> Length);
245  explicit WritableBinaryStreamRef(MutableArrayRef<uint8_t> Data,
246                                   llvm::support::endianness Endian);
247  WritableBinaryStreamRef(const WritableBinaryStreamRef &Other) = default;
248  WritableBinaryStreamRef &
249  operator=(const WritableBinaryStreamRef &Other) = default;
250
251  WritableBinaryStreamRef(WritableBinaryStreamRef &&Other) = default;
252  WritableBinaryStreamRef &operator=(WritableBinaryStreamRef &&Other) = default;
253
254  // Use WritableBinaryStreamRef.slice() instead.
255  WritableBinaryStreamRef(WritableBinaryStreamRef &S, uint32_t Offset,
256                          uint32_t Length) = delete;
257
258  /// Given an Offset into this WritableBinaryStreamRef and some input data,
259  /// writes the data to the underlying stream.
260  ///
261  /// \returns a success error code if the data could fit within the underlying
262  /// stream at the specified location and the implementation could write the
263  /// data, and an appropriate error code otherwise.
264  Error writeBytes(uint32_t Offset, ArrayRef<uint8_t> Data) const;
265
266  /// Conver this WritableBinaryStreamRef to a read-only BinaryStreamRef.
267  operator BinaryStreamRef() const;
268
269  /// For buffered streams, commits changes to the backing store.
270  Error commit();
271};
272
273} // end namespace llvm
274
275#endif // LLVM_SUPPORT_BINARYSTREAMREF_H
276